Metadata-Version: 2.4
Name: langchain-konstruct
Version: 0.2.0
Summary: LangChain integration for Konstruct - Typed Knowledge Graph for AI Agents
Author-email: AerwareAI <hello@aerware.ai>
Maintainer-email: Aeryn White <aeryn@aerware.ai>
License: Proprietary
Project-URL: Homepage, https://konstruct.aerware.ai
Project-URL: Documentation, https://konstruct.aerware.ai/docs
Project-URL: Repository, https://github.com/AerwareAI/konstruct-v2
Project-URL: Bug Tracker, https://github.com/AerwareAI/konstruct-v2/issues
Project-URL: Changelog, https://github.com/AerwareAI/konstruct-v2/blob/main/CHANGELOG.md
Keywords: langchain,konstruct,knowledge-graph,ai,agents,llm,rag,typed-relations,causal-reasoning,advisory
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: langchain-core>=0.1.0
Requires-Dist: requests>=2.31.0
Requires-Dist: pydantic>=1.10.0
Provides-Extra: dev
Requires-Dist: pytest>=7.4.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: black>=23.7.0; extra == "dev"
Requires-Dist: mypy>=1.5.0; extra == "dev"
Requires-Dist: ruff>=0.0.287; extra == "dev"
Provides-Extra: examples
Requires-Dist: langchain-anthropic>=0.1.0; extra == "examples"
Requires-Dist: python-dotenv>=1.0.0; extra == "examples"
Dynamic: license-file

# Konstruct × LangChain

[![PyPI](https://img.shields.io/pypi/v/langchain-konstruct?style=for-the-badge&labelColor=0B0F16&color=19C3FF)](https://pypi.org/project/langchain-konstruct/)
[![Downloads](https://img.shields.io/pypi/dm/langchain-konstruct?style=for-the-badge&labelColor=0B0F16&color=19FFCB)](https://pypi.org/project/langchain-konstruct/)
[![Python](https://img.shields.io/pypi/pyversions/langchain-konstruct?style=for-the-badge&labelColor=0B0F16&color=FFC65A)](https://pypi.org/project/langchain-konstruct/)

LangChain retriever classes powered by Konstruct's typed knowledge graph engine.

---

## What This Does

Standard RAG gives your LLM chunks of text. Konstruct gives it **structured knowledge** — concepts connected by typed relationships like `causes`, `requires`, `contradicts`, and `enables`.

Your LLM stops guessing and starts reasoning.

## Installation

```bash
pip install langchain-konstruct
```

Get an API key at [aerware.ai](https://aerware.ai).

## Quick Start

```python
from langchain_konstruct import KonstructRetriever
from langchain.chains import RetrievalQA
from langchain_anthropic import ChatAnthropic

retriever = KonstructRetriever(
    api_key="your_konstruct_api_key",
    pack_ids=["causal-startup-failure", "market-dynamics"],
)

qa = RetrievalQA.from_chain_type(
    llm=ChatAnthropic(model="claude-sonnet-4-20250514"),
    retriever=retriever,
)

response = qa.invoke({"query": "What causes startups to fail?"})
print(response["result"])
```

## Using the Hosted Corpus

Konstruct ships with 2,800+ pre-built knowledge packs across business, science, health, law, and engineering. Reference them by ID:

```python
retriever = KonstructRetriever(
    api_key="your_api_key",
    pack_ids=["causal-startup-failure", "market-dynamics", "monetary-policy"],
)
```

Browse available packs at [aerware.ai/library](https://aerware.ai).

## Using Your Own Knowledge Packs

Load custom packs from JSON files or dicts:

```python
retriever = KonstructRetriever(api_key="your_api_key")

# From file
retriever.load_pack_from_file("packs/my-domain.json")

# From dict
retriever.load_pack({
    "id": "my_pack",
    "name": "My Domain Knowledge",
    "concepts": [
        {
            "id": "concept_a",
            "name": "Concept A",
            "category": "strategy",
            "importance": 0.9,
            "description": "What this concept means"
        }
    ],
    "edges": [
        {
            "source": "concept_a",
            "target": "concept_b",
            "relation": "causes",
            "weight": 0.85
        }
    ]
})
```

## Retriever Options

```python
retriever = KonstructRetriever(
    api_key="your_api_key",      # From aerware.ai
    pack_ids=["pack-1"],         # Hosted packs to load
    max_concepts=10,             # How many concepts to retrieve
    max_depth=2,                 # Edge traversal depth (1 or 2)
    search_type="advisory",      # "advisory" or "concepts"
    category_filter="strategy",  # Optional: filter by category
)
```

**`search_type`:**
- `"advisory"` — Returns structured guidance (key concepts + relationships + frameworks). Best for chat/QA.
- `"concepts"` — Returns raw concepts as separate documents. Best for custom pipelines.

## Causal Reasoning

Use `KonstructCausalRetriever` when you need answers about prerequisites, dependencies, or causal chains:

```python
from langchain_konstruct import KonstructCausalRetriever

retriever = KonstructCausalRetriever(
    api_key="your_api_key",
    pack_ids=["fintech-compliance"],
)

docs = retriever.get_relevant_documents("What must be in place before AML compliance?")
# Prioritizes "requires", "causes", "enables", "prevents" edges
```

## Knowledge Pack Format

Packs are validated JSON with concepts, typed edges, and optional frameworks:

```json
{
  "id": "my_pack",
  "name": "My Knowledge Pack",
  "concepts": [
    {
      "id": "product_market_fit",
      "name": "Product-Market Fit",
      "category": "strategy",
      "importance": 0.95,
      "description": "When a product satisfies strong market demand"
    }
  ],
  "edges": [
    {
      "source": "customer_discovery",
      "target": "product_market_fit",
      "relation": "enables",
      "weight": 0.9
    }
  ],
  "frameworks": [
    {
      "id": "pmf_framework",
      "name": "PMF Checklist",
      "trigger_concepts": ["product_market_fit"],
      "questions": ["Are users actively requesting access?"],
      "red_flags": ["Building without user feedback"],
      "green_lights": ["Users paying before launch"]
    }
  ]
}
```

**Supported relation types:** `causes`, `requires`, `enables`, `prevents`, `conflicts_with`, `supports`, `contradicts`, `is_a`, `part_of`, `precedes`, `amplifies`, `diminishes`, `implements`, `depends_on`, `correlates_with`, `replaces`, `triggers`, `validates`, `similar_to`

Reverse edges are inferred automatically — add `causes` and `caused_by` is created for you.

## Explore Concept Relationships

```python
# Explore outward from a specific concept
docs = retriever.explore_concept("product_market_fit", depth=2)

# List all loaded concepts
docs = retriever.get_all_concepts(category="strategy")

# Graph statistics
stats = retriever.get_stats()
print(f"Concepts: {stats['concept_count']}, Edges: {stats['edge_count']}")
```

## Environment Variables

```bash
ANTHROPIC_API_KEY=your_anthropic_key
KONSTRUCT_API_KEY=your_konstruct_key   # from aerware.ai
```

## Links

- **Get API Key:** [aerware.ai](https://aerware.ai)
- **Browse Packs:** [aerware.ai/library](https://aerware.ai)
- **Docs:** [docs.aerware.ai/konstruct](https://docs.aerware.ai/konstruct)
- **Issues:** [github.com/AerwareAI/konstruct-v2/issues](https://github.com/AerwareAI/konstruct-v2/issues)

---

© 2026 AerwareAI — Proprietary
