lattice-langgraph 0.2.1__tar.gz

lattice_langgraph-0.2.1/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.Python
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
+*.egg
+.pytest_cache/

lattice_langgraph-0.2.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 heybeaux
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

lattice_langgraph-0.2.1/PKG-INFO

@@ -0,0 +1,199 @@
+Metadata-Version: 2.4
+Name: lattice-langgraph
+Version: 0.2.1
+Summary: Lattice State Contract coordination layer for LangGraph workflows
+Project-URL: Homepage, https://github.com/heybeaux/lattice
+Project-URL: Documentation, https://heybeaux.github.io/lattice/
+Project-URL: Repository, https://github.com/heybeaux/lattice/tree/main/packages/adapter-langgraph
+Project-URL: Issues, https://github.com/heybeaux/lattice/issues
+License: MIT
+License-File: LICENSE
+Keywords: ai-agents,circuit-breaker,coordination,langgraph,lattice,state-contract
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+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.10
+Requires-Dist: jsonschema>=4.0.0
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: openai>=1.0.0
+Requires-Dist: python-ulid>=2.0.0
+Provides-Extra: dev
+Requires-Dist: langchain-core>=0.2.0; extra == 'dev'
+Requires-Dist: langgraph>=0.2.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# lattice-langgraph
+
+Lattice coordination layer for [LangGraph](https://github.com/langchain-ai/langgraph) workflows.
+
+Wraps LangGraph nodes with **State Contracts** and **Circuit Breakers** — every handoff becomes a typed, validated, auditable envelope.
+
+## Install
+
+```bash
+pip install lattice-langgraph
+```
+
+## Quick start
+
+### Option A — wrap individual nodes
+
+```python
+from lattice_langgraph import wrap_node, BreakerConfig
+from langgraph.graph import StateGraph, END
+from typing import TypedDict
+
+class State(TypedDict):
+    topic: str
+    result: str
+
+def researcher(state):
+    return {"result": f"findings about {state['topic']}"}
+
+def writer(state):
+    return {"result": f"article: {state['result']}"}
+
+graph = StateGraph(State)
+graph.add_node("researcher", wrap_node(researcher, agent_id="researcher", to_agent="writer"))
+graph.add_node("writer", wrap_node(writer, agent_id="writer"))
+graph.set_entry_point("researcher")
+graph.add_edge("researcher", "writer")
+graph.add_edge("writer", END)
+
+app = graph.compile()
+result = app.invoke({"topic": "quantum computing"})
+```
+
+### Option B — wrap the whole graph with `LatticeMiddleware`
+
+```python
+from lattice_langgraph import LatticeMiddleware
+import os
+
+# Build your graph normally
+graph = StateGraph(State)
+graph.add_node("researcher", researcher)
+graph.add_node("writer", writer)
+graph.set_entry_point("researcher")
+graph.add_edge("researcher", "writer")
+graph.add_edge("writer", END)
+compiled = graph.compile()
+
+# Wrap it
+app = LatticeMiddleware(
+    compiled,
+    audit_log_path="./lattice-audit.jsonl",
+    openai_api_key=os.environ["OPENAI_API_KEY"],
+)
+result = app.invoke({"topic": "quantum computing"})
+```
+
+## Validation tiers
+
+| Tier | What | When | Latency |
+|------|------|------|---------|
+| L1 | JSON Schema validation | Always | <200ms |
+| L2 | Embedding similarity | On every handoff | ~500ms |
+| L3 | LLM-as-judge (gpt-4o-mini) | L2 similarity < 0.85 or high-risk edge | 1–3s |
+| auto | L1 always, L2 always, L3 on escalation | Default | varies |
+
+```python
+from lattice_langgraph import BreakerConfig
+
+# L1 only (fast, no LLM calls)
+config = BreakerConfig(tier="L1")
+
+# Full auto (L1+L2, escalate to L3 on low confidence)
+config = BreakerConfig(tier="auto", openai_api_key="sk-...")
+
+# Shadow mode — log without blocking
+wrapped = wrap_node(my_node, agent_id="agent", shadow=True, breaker_config=config)
+```
+
+## Shadow mode
+
+Shadow mode logs every handoff without blocking graph execution. Use this to collect production data before enabling enforcement:
+
+```python
+app = LatticeMiddleware(graph, shadow=True, audit_log_path="./audit.jsonl")
+```
+
+The audit log is JSONL. Each line:
+
+```json
+{
+  "contract_id": "01HXZ...",
+  "trace_id": "01HXZ...",
+  "from_agent": "researcher",
+  "to_agent": "writer",
+  "timestamp": "2026-05-08T...",
+  "shadow": false,
+  "validation_tier": "L1",
+  "validation_passed": true,
+  "confidence": 1.0,
+  "latency_ms": 12
+}
+```
+
+## State Contract schema
+
+Every handoff produces a `StateContract`:
+
+```python
+from lattice_langgraph import create_contract
+
+contract = create_contract(
+    from_agent="researcher",
+    inputs={"topic": "climate"},
+    outputs={"findings": "..."},
+    to_agent="writer",
+)
+print(contract.to_dict())
+```
+
+The schema is JSON Schema 2020-12 (same as `@heybeaux/lattice-core`). See [`contract.schema.json`](src/lattice_langgraph/contract.schema.json).
+
+## API reference
+
+### `wrap_node(node_fn, *, agent_id, to_agent=None, breaker_config=None, audit_logger=None, shadow=False, trace_id=None)`
+
+Wraps a LangGraph node function. Returns a drop-in replacement with the same `(state: dict) -> dict` signature.
+
+### `LatticeMiddleware(graph, *, audit_log_path, breaker_config=None, shadow=False, openai_api_key=None)`
+
+Wraps a compiled LangGraph graph. Delegates `.invoke()`, `.ainvoke()`, `.stream()` to the underlying graph after patching all nodes.
+
+### `BreakerConfig`
+
+| Field | Default | Description |
+|-------|---------|-------------|
+| `tier` | `"auto"` | `"L1"`, `"L2"`, `"L3"`, or `"auto"` |
+| `l2_threshold` | `0.85` | Confidence below which L3 is triggered |
+| `openai_api_key` | `None` | Falls back to `OPENAI_API_KEY` env var |
+| `block_on_failure` | `True` | Raise `LatticeValidationError` on failure |
+
+## Benchmark results
+
+From the Lattice benchmark suite (real OpenAI API calls):
+
+- **100%** hallucination detection (6/6 caught by L3)
+- **0%** false positive rate (4/4 correct outputs passed)
+- **0** false negatives
+- L1 latency: <200ms
+- L3 latency: 1–3s (only on escalation)
+
+## Example
+
+See [`examples/research_pipeline.py`](examples/research_pipeline.py) for a complete 4-node research graph using both `wrap_node` and `LatticeMiddleware`.
+
+```bash
+OPENAI_API_KEY=sk-... python examples/research_pipeline.py
+```

lattice_langgraph-0.2.1/README.md

@@ -0,0 +1,167 @@
+# lattice-langgraph
+
+Lattice coordination layer for [LangGraph](https://github.com/langchain-ai/langgraph) workflows.
+
+Wraps LangGraph nodes with **State Contracts** and **Circuit Breakers** — every handoff becomes a typed, validated, auditable envelope.
+
+## Install
+
+```bash
+pip install lattice-langgraph
+```
+
+## Quick start
+
+### Option A — wrap individual nodes
+
+```python
+from lattice_langgraph import wrap_node, BreakerConfig
+from langgraph.graph import StateGraph, END
+from typing import TypedDict
+
+class State(TypedDict):
+    topic: str
+    result: str
+
+def researcher(state):
+    return {"result": f"findings about {state['topic']}"}
+
+def writer(state):
+    return {"result": f"article: {state['result']}"}
+
+graph = StateGraph(State)
+graph.add_node("researcher", wrap_node(researcher, agent_id="researcher", to_agent="writer"))
+graph.add_node("writer", wrap_node(writer, agent_id="writer"))
+graph.set_entry_point("researcher")
+graph.add_edge("researcher", "writer")
+graph.add_edge("writer", END)
+
+app = graph.compile()
+result = app.invoke({"topic": "quantum computing"})
+```
+
+### Option B — wrap the whole graph with `LatticeMiddleware`
+
+```python
+from lattice_langgraph import LatticeMiddleware
+import os
+
+# Build your graph normally
+graph = StateGraph(State)
+graph.add_node("researcher", researcher)
+graph.add_node("writer", writer)
+graph.set_entry_point("researcher")
+graph.add_edge("researcher", "writer")
+graph.add_edge("writer", END)
+compiled = graph.compile()
+
+# Wrap it
+app = LatticeMiddleware(
+    compiled,
+    audit_log_path="./lattice-audit.jsonl",
+    openai_api_key=os.environ["OPENAI_API_KEY"],
+)
+result = app.invoke({"topic": "quantum computing"})
+```
+
+## Validation tiers
+
+| Tier | What | When | Latency |
+|------|------|------|---------|
+| L1 | JSON Schema validation | Always | <200ms |
+| L2 | Embedding similarity | On every handoff | ~500ms |
+| L3 | LLM-as-judge (gpt-4o-mini) | L2 similarity < 0.85 or high-risk edge | 1–3s |
+| auto | L1 always, L2 always, L3 on escalation | Default | varies |
+
+```python
+from lattice_langgraph import BreakerConfig
+
+# L1 only (fast, no LLM calls)
+config = BreakerConfig(tier="L1")
+
+# Full auto (L1+L2, escalate to L3 on low confidence)
+config = BreakerConfig(tier="auto", openai_api_key="sk-...")
+
+# Shadow mode — log without blocking
+wrapped = wrap_node(my_node, agent_id="agent", shadow=True, breaker_config=config)
+```
+
+## Shadow mode
+
+Shadow mode logs every handoff without blocking graph execution. Use this to collect production data before enabling enforcement:
+
+```python
+app = LatticeMiddleware(graph, shadow=True, audit_log_path="./audit.jsonl")
+```
+
+The audit log is JSONL. Each line:
+
+```json
+{
+  "contract_id": "01HXZ...",
+  "trace_id": "01HXZ...",
+  "from_agent": "researcher",
+  "to_agent": "writer",
+  "timestamp": "2026-05-08T...",
+  "shadow": false,
+  "validation_tier": "L1",
+  "validation_passed": true,
+  "confidence": 1.0,
+  "latency_ms": 12
+}
+```
+
+## State Contract schema
+
+Every handoff produces a `StateContract`:
+
+```python
+from lattice_langgraph import create_contract
+
+contract = create_contract(
+    from_agent="researcher",
+    inputs={"topic": "climate"},
+    outputs={"findings": "..."},
+    to_agent="writer",
+)
+print(contract.to_dict())
+```
+
+The schema is JSON Schema 2020-12 (same as `@heybeaux/lattice-core`). See [`contract.schema.json`](src/lattice_langgraph/contract.schema.json).
+
+## API reference
+
+### `wrap_node(node_fn, *, agent_id, to_agent=None, breaker_config=None, audit_logger=None, shadow=False, trace_id=None)`
+
+Wraps a LangGraph node function. Returns a drop-in replacement with the same `(state: dict) -> dict` signature.
+
+### `LatticeMiddleware(graph, *, audit_log_path, breaker_config=None, shadow=False, openai_api_key=None)`
+
+Wraps a compiled LangGraph graph. Delegates `.invoke()`, `.ainvoke()`, `.stream()` to the underlying graph after patching all nodes.
+
+### `BreakerConfig`
+
+| Field | Default | Description |
+|-------|---------|-------------|
+| `tier` | `"auto"` | `"L1"`, `"L2"`, `"L3"`, or `"auto"` |
+| `l2_threshold` | `0.85` | Confidence below which L3 is triggered |
+| `openai_api_key` | `None` | Falls back to `OPENAI_API_KEY` env var |
+| `block_on_failure` | `True` | Raise `LatticeValidationError` on failure |
+
+## Benchmark results
+
+From the Lattice benchmark suite (real OpenAI API calls):
+
+- **100%** hallucination detection (6/6 caught by L3)
+- **0%** false positive rate (4/4 correct outputs passed)
+- **0** false negatives
+- L1 latency: <200ms
+- L3 latency: 1–3s (only on escalation)
+
+## Example
+
+See [`examples/research_pipeline.py`](examples/research_pipeline.py) for a complete 4-node research graph using both `wrap_node` and `LatticeMiddleware`.
+
+```bash
+OPENAI_API_KEY=sk-... python examples/research_pipeline.py
+```

lattice_langgraph-0.2.1/examples/research_pipeline.py

@@ -0,0 +1,122 @@
+"""
+Example: 4-node research pipeline wrapped with Lattice.
+
+Graph: planner -> researcher -> writer -> reviewer
+
+Run:
+    pip install lattice-langgraph langgraph langchain-core
+    OPENAI_API_KEY=sk-... python examples/research_pipeline.py
+"""
+
+import os
+from typing import TypedDict
+
+from langgraph.graph import END, StateGraph
+
+from lattice_langgraph import BreakerConfig, LatticeMiddleware, wrap_node
+
+
+class ResearchState(TypedDict):
+    topic: str
+    plan: str
+    research: str
+    draft: str
+    review: str
+
+
+# --- Node definitions ---
+
+def planner_node(state: ResearchState) -> dict:
+    topic = state["topic"]
+    return {"plan": f"Research plan for '{topic}': 1) gather sources 2) synthesize 3) draft 4) review"}
+
+
+def researcher_node(state: ResearchState) -> dict:
+    plan = state["plan"]
+    topic = state["topic"]
+    return {
+        "research": (
+            f"Key findings on '{topic}': "
+            "Source A suggests X. Source B corroborates with Y. "
+            "Consensus: the evidence supports Z."
+        )
+    }
+
+
+def writer_node(state: ResearchState) -> dict:
+    research = state["research"]
+    topic = state["topic"]
+    return {
+        "draft": (
+            f"# {topic.title()}\n\n"
+            f"Based on recent research:\n\n{research}\n\n"
+            "In conclusion, the evidence is clear and warrants further investigation."
+        )
+    }
+
+
+def reviewer_node(state: ResearchState) -> dict:
+    draft = state["draft"]
+    return {
+        "review": f"Review passed. The draft covers the topic with adequate sourcing. Word count: {len(draft.split())}."
+    }
+
+
+# --- Option A: wrap individual nodes ---
+
+def build_wrapped_graph_individual() -> StateGraph:
+    breaker = BreakerConfig(tier="L1")  # L1-only for fast local demo
+
+    graph = StateGraph(ResearchState)
+    graph.add_node("planner", wrap_node(planner_node, agent_id="planner", to_agent="researcher", breaker_config=breaker))
+    graph.add_node("researcher", wrap_node(researcher_node, agent_id="researcher", to_agent="writer", breaker_config=breaker))
+    graph.add_node("writer", wrap_node(writer_node, agent_id="writer", to_agent="reviewer", breaker_config=breaker))
+    graph.add_node("reviewer", wrap_node(reviewer_node, agent_id="reviewer", breaker_config=breaker))
+
+    graph.set_entry_point("planner")
+    graph.add_edge("planner", "researcher")
+    graph.add_edge("researcher", "writer")
+    graph.add_edge("writer", "reviewer")
+    graph.add_edge("reviewer", END)
+    return graph.compile()
+
+
+# --- Option B: LatticeMiddleware wraps the whole graph ---
+
+def build_wrapped_graph_middleware() -> LatticeMiddleware:
+    graph = StateGraph(ResearchState)
+    graph.add_node("planner", planner_node)
+    graph.add_node("researcher", researcher_node)
+    graph.add_node("writer", writer_node)
+    graph.add_node("reviewer", reviewer_node)
+
+    graph.set_entry_point("planner")
+    graph.add_edge("planner", "researcher")
+    graph.add_edge("researcher", "writer")
+    graph.add_edge("writer", "reviewer")
+    graph.add_edge("reviewer", END)
+
+    compiled = graph.compile()
+    return LatticeMiddleware(
+        compiled,
+        audit_log_path="./lattice-audit.jsonl",
+        breaker_config=BreakerConfig(
+            tier="auto",
+            openai_api_key=os.environ.get("OPENAI_API_KEY"),
+        ),
+        shadow=False,
+    )
+
+
+if __name__ == "__main__":
+    print("=== Option A: wrap_node() per node ===")
+    graph_a = build_wrapped_graph_individual()
+    result_a = graph_a.invoke({"topic": "climate change adaptation strategies"})
+    print("Review:", result_a["review"])
+    print()
+
+    print("=== Option B: LatticeMiddleware ===")
+    graph_b = build_wrapped_graph_middleware()
+    result_b = graph_b.invoke({"topic": "quantum computing in drug discovery"})
+    print("Review:", result_b["review"])
+    print("Audit log written to ./lattice-audit.jsonl")

lattice_langgraph-0.2.1/publish.sh

@@ -0,0 +1,15 @@
+#!/bin/bash
+# Publish lattice-langgraph to PyPI
+# Requires: twine, build, and PyPI API token
+
+set -e
+
+echo "Building lattice-langgraph..."
+python -m build
+
+echo ""
+echo "Uploading to PyPI..."
+python -m twine upload --username __token__ --password "$PYPI_API_TOKEN" dist/*
+
+echo ""
+echo "✓ lattice-langgraph published to PyPI!"

lattice_langgraph-0.2.1/pyproject.toml

@@ -0,0 +1,51 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "lattice-langgraph"
+version = "0.2.1"
+description = "Lattice State Contract coordination layer for LangGraph workflows"
+readme = "README.md"
+keywords = ["lattice", "langgraph", "ai-agents", "coordination", "state-contract", "circuit-breaker"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+license = { text = "MIT" }
+requires-python = ">=3.10"
+dependencies = [
+    "python-ulid>=2.0.0",
+    "jsonschema>=4.0.0",
+    "openai>=1.0.0",
+    "numpy>=1.24.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/heybeaux/lattice"
+Documentation = "https://heybeaux.github.io/lattice/"
+Repository = "https://github.com/heybeaux/lattice/tree/main/packages/adapter-langgraph"
+Issues = "https://github.com/heybeaux/lattice/issues"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-asyncio>=0.21.0",
+    "langgraph>=0.2.0",
+    "langchain-core>=0.2.0",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/lattice_langgraph"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+

lattice_langgraph-0.2.1/src/lattice_langgraph/__init__.py

@@ -0,0 +1,31 @@
+from .audit import AuditLogger
+from .breaker import BreakerConfig, ValidationResult
+from .contract import (
+    Assumption,
+    BudgetRecord,
+    Constraint,
+    ContractPayload,
+    Decision,
+    StateContract,
+    create_contract,
+)
+from .middleware import LatticeMiddleware
+from .wrapper import LatticeValidationError, wrap_node
+
+__all__ = [
+    "wrap_node",
+    "LatticeMiddleware",
+    "LatticeValidationError",
+    "StateContract",
+    "ContractPayload",
+    "Decision",
+    "Constraint",
+    "Assumption",
+    "BudgetRecord",
+    "BreakerConfig",
+    "ValidationResult",
+    "AuditLogger",
+    "create_contract",
+]
+
+__version__ = "0.1.0"

lattice_langgraph-0.2.1/src/lattice_langgraph/audit.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from threading import Lock
+from typing import Any
+
+from .contract import StateContract
+
+
+class AuditLogger:
+    def __init__(self, path: str | Path) -> None:
+        self._path = Path(path)
+        self._lock = Lock()
+        self._path.parent.mkdir(parents=True, exist_ok=True)
+
+    def log(
+        self,
+        contract: StateContract,
+        *,
+        validation_tier: str | None = None,
+        validation_passed: bool | None = None,
+        confidence: float | None = None,
+        latency_ms: int | None = None,
+        shadow: bool = False,
+    ) -> None:
+        entry: dict[str, Any] = {
+            "contract_id": contract.id,
+            "trace_id": contract.trace_id,
+            "from_agent": contract.from_agent,
+            "to_agent": contract.to_agent,
+            "timestamp": contract.timestamp,
+            "shadow": shadow,
+        }
+        if validation_tier is not None:
+            entry["validation_tier"] = validation_tier
+        if validation_passed is not None:
+            entry["validation_passed"] = validation_passed
+        if confidence is not None:
+            entry["confidence"] = confidence
+        if latency_ms is not None:
+            entry["latency_ms"] = latency_ms
+
+        with self._lock:
+            with open(self._path, "a") as f:
+                f.write(json.dumps(entry) + "\n")