Metadata-Version: 2.4
Name: langchain-hyperspace
Version: 4.2.0
Summary: LangChain & LangGraph integration for HyperspaceDB v4.2 — Product-Manifold Hybrid VectorStore, KAG Graph, CheckpointSaver, Long-Term BaseStore, and Tribunal Verification
Author-email: YARlabs <hi@yar.ink>
License: Apache-2.0
Project-URL: Homepage, https://github.com/YARlabs/hyperspace-db_integrations
Project-URL: Documentation, https://yar.ink/docs
Project-URL: Repository, https://github.com/YARlabs/hyperspace-db_integrations
Project-URL: Bug Tracker, https://github.com/YARlabs/hyperspace-db_integrations/issues
Keywords: langchain,langgraph,vector database,kag,checkpoint,embeddings,AI,RAG,hyperbolic
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software 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 :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: langchain-core>=0.1.0
Requires-Dist: hyperspacedb>=4.1.0
Requires-Dist: grpcio>=1.60.0
Requires-Dist: protobuf>=4.25.0
Requires-Dist: numpy>=1.24.0
Provides-Extra: langgraph
Requires-Dist: langgraph-checkpoint>=2.0.0; extra == "langgraph"
Provides-Extra: yarlabs
Requires-Dist: torch>=2.0.0; extra == "yarlabs"
Requires-Dist: transformers>=4.30.0; extra == "yarlabs"
Provides-Extra: dev
Requires-Dist: pytest>=7.4.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: mypy>=1.6.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Dynamic: license-file

# LangChain & LangGraph HyperspaceDB Integration

[![PyPI version](https://badge.fury.io/py/langchain-hyperspace.svg)](https://badge.fury.io/py/langchain-hyperspace)
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)

Official LangChain and LangGraph integration for **[HyperspaceDB](https://yar.ink)** — the Multi-Manifold Vector & Knowledge-Augmented Graph (KAG) Database powered by the official `hyperspacedb` SDK.

## Key Capabilities (v4.2)

- **Multi-Manifold Geometries**: Support for `l2`, `cosine`, `dot`, `poincare`, `lorentz`, `hybrid` (33D Lorentz Hierarchy + 768D Cosine Semantic Tail), `manifold_product`, `klein`, `spherical`, `hamming`, `jaccard`, `wasserstein`, and `custom_minkowski`.
- **LangGraph State Persistence (`HyperspaceCheckpointSaver`)**: Persist LangGraph execution checkpoints directly in HyperspaceDB with automatic `STEP_TRANSITION` KAG lineage edges and `801D` hybrid state embeddings.
- **LangGraph Long-Term Memory (`HyperspaceStore`)**: Cross-thread namespace-hierarchical semantic store (`BaseStore`-compatible) using Hyperbolic Entailment Cones.
- **Full Filter Pushdown**: Translate nested LangChain filters (`and`, `or`, `not`, `match`, `range`, `prefix`, `in_cone`, `in_ball`, `in_box`) directly into HyperspaceDB `FilterCondition` ASTs.
- **Native KAG Graph & Wave Resonance**: Built-in `link`, `link_batch`, `induce_edges_from_metadata`, `vector_graph_search`, and `traverse_graph` (with `use_wave=True` Schrodinger- equation resonance scoring).
- **Tribunal Router (`verify_generation`)**: Mathematical anti-hallucination guardrail evaluating whether an LLM draft is entailed by retrieved context in hyperbolic/hybrid geometry before returning to the user.
- **Formal Proof-Obligation Query Planner**: Pre-retrieval tool (`get_query_planner_tool`) that intercepts ambiguous prompts or decomposes complex multi-part questions into DAG proof obligations.

## Installation

```bash
pip install langchain-hyperspace
# Optional: for LangGraph checkpointer & store support
pip install langchain-hyperspace[langgraph]
```

## Quick Start

### 1. Vector Store (`HyperspaceVectorStore`)

```python
from langchain_hyperspace import HyperspaceVectorStore
from langchain_openai import OpenAIEmbeddings

embeddings = OpenAIEmbeddings()

vectorstore = HyperspaceVectorStore(
    host="localhost",
    port=50051,
    collection_name="enterprise_knowledge",
    embedding_function=embeddings,
    dimension=801,
    metric="hybrid",  # 33D Lorentz Hierarchy + 768D Cosine Tail
    api_key="your_api_key",
)

# Batch-insert documents with automatic KAG edge extraction from metadata["relations"]
ids = vectorstore.add_texts(
    texts=[
        "Section 1: Master Services Agreement overview.",
        "Section 1.1: Indemnification and liability cap.",
    ],
    metadatas=[
        {"id": 100, "category": "legal"},
        {
            "id": 101,
            "category": "legal",
            "relations": [{"target_id": 100, "relation": "PART_OF", "weight": 1.0}],
        },
    ],
)

# Similarity search with full server-side filter pushdown (including hyperbolic cone pruning)
docs = vectorstore.similarity_search(
    "What is the liability cap?",
    k=5,
    filter={
        "and": [
            {"category": "legal"},
            {"in_cone": {"apex": [1.0] + [0.0] * 800, "aperture": 0.45}},
        ]
    },
)
```

### 2. Hybrid Search, Vector-Graph Search & Wave Resonance

```python
# Server-side RRF / convex combination of dense geometry + BM25 lexical index
hybrid_docs = vectorstore.hybrid_search(
    "Section 1.1 liability cap",
    k=5,
    alpha=0.7,
)

# Joint 1-RPC Vector Search + Multi-Hop KAG Graph Expansion with Wave Resonance
graph_docs = vectorstore.vector_graph_search(
    "indemnification obligations",
    k=5,
    max_depth=2,
    decay_factor=0.85,
    relation_filter="PART_OF",
    use_wave=True,
)
```

### 3. LangGraph Checkpoint Saver & Cross-Thread Store

```python
from langchain_hyperspace import HyperspaceCheckpointSaver, HyperspaceStore

# 1. Persistent LangGraph Checkpointer with KAG lineage edges (STEP_TRANSITION)
checkpointer = HyperspaceCheckpointSaver(
    host="localhost",
    port=50051,
    collection_name="langgraph_checkpoints",
)

# Use directly when compiling any LangGraph StateGraph:
# graph = builder.compile(checkpointer=checkpointer)

# Inspect multi-hop execution lineage in the KAG graph
lineage = checkpointer.traverse_lineage(checkpoint_id="step-42", max_depth=5)

# 2. Cross-thread Long-Term Memory Store
store = HyperspaceStore(host="localhost", port=50051)
store.put(("org_acme", "users", "u_123"), "pref_theme", {"mode": "dark", "text": "Prefers dark mode"})
items = store.search(("org_acme", "users"), query="interface preferences", limit=5)
```

### 4. Tribunal Router: Anti-Hallucination Verification

```python
verdict = vectorstore.verify_generation(
    query="What is the liability cap under Section 1.1?",
    generated_answer="The liability cap is limited to 12 months of fees.",
    context_nodes=docs,
    entailment_aperture=0.65,
    max_geodesic_distance=1.5,
)

if not verdict["verified"]:
    print("Hallucination rejected:", verdict["correction_prompt"])
```

## License

Apache License 2.0
