Metadata-Version: 2.4
Name: phionyx-langchain-langgraph
Version: 0.1.0a4
Summary: Native LangChain + LangGraph adapters for Phionyx runtime evidence — every chain, tool call, and LLM invocation emits a hash-chained envelope entry (signed when a signer is configured; unsigned by default).
Author-email: Ali Toygar Abak <founder@phionyx.ai>
License: AGPL-3.0-or-later
Project-URL: Homepage, https://phionyx.ai/runtime-evidence
Project-URL: Repository, https://github.com/halvrenofviryel/phionyx-langchain-langgraph
Project-URL: Documentation, https://phionyx.ai/start
Keywords: langchain,langgraph,ai-governance,runtime-evidence,audit-chain,agent-observability,phionyx
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
Classifier: Operating System :: OS Independent
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 :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: phionyx-core>=0.4.0
Requires-Dist: langchain-core>=0.2.0
Requires-Dist: pydantic>=2.0
Requires-Dist: cryptography>=42.0
Provides-Extra: langgraph
Requires-Dist: langgraph>=0.0.40; extra == "langgraph"
Provides-Extra: test
Requires-Dist: pytest>=8.0; extra == "test"
Requires-Dist: pytest-asyncio>=0.23; extra == "test"
Requires-Dist: langchain-core>=0.2.0; extra == "test"
Requires-Dist: langgraph>=0.0.40; extra == "test"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Requires-Dist: langchain-core>=0.2.0; extra == "dev"
Requires-Dist: langgraph>=0.0.40; extra == "dev"
Dynamic: license-file

# phionyx-langchain-langgraph

> **Status:** alpha (v0.1.0a4). LangChain callback adapter, LangGraph supervisor adapter, and integration tests against real LangChain primitives all implemented.

Native LangChain + LangGraph adapters for [Phionyx](https://phionyx.ai) runtime evidence. This package surfaces on [phionyx.ai/runtime-evidence](https://phionyx.ai/runtime-evidence) as one of the framework adapters that turn third-party agent runs into reviewer-runnable evidence.

**Where this sits in the Phionyx portfolio:** this is a **framework adapter** with its own version line (v0.1.0a4). It is distinct from the **engine** ([`phionyx-core`](https://pypi.org/project/phionyx-core/), current release on PyPI — the deterministic runtime whose envelope schema this adapter emits), the **self-governance gate** ([`phionyx-pipeline-mcp`](https://github.com/halvrenofviryel/phionyx-pipeline-mcp)), and the **AI Runtime Evidence Protocol (AIREP)** ([`ai-runtime-evidence-protocol`](https://github.com/halvrenofviryel/ai-runtime-evidence-protocol)) — the experimental, vendor-neutral open format for per-decision AI decision receipts that this adapter's envelopes aim to conform to. These are separate version namespaces and must not be cross-attributed.

Each LangChain `chain`, `tool` and `llm` event delivered to the registered Phionyx callback handler — and each LangGraph supervisor handoff routed through the adapter — is recorded as a hash-chained envelope entry (signed when a signer is configured; unsigned by default). Third parties can re-verify the hash chain offline; a matching chain shows internal hash consistency. Without independent anchoring and authentication it does not rule out rewriting the chain, missing events or false narration.

## Why

LangChain ships an observability surface (LangSmith, callback handlers, tracing) optimized for *debugging*. It is not optimized for *third-party verification*: a callback log is mutable, unsigned, and the agent's own narration. Phionyx envelopes link recorded payload hashes. They are unsigned by default; Ed25519 signing or demo-only HMAC must be explicitly configured. Hash checks alone do not authenticate an operator or prevent a party from rewriting and rehashing the whole chain.

LangGraph's supervisor patterns track *flow* but do not sign parent → child handoffs. Phionyx's multi-agent envelope schema (delivered in `phionyx-core` v0.6.0, shipped) adds full multi-agent envelope chains; this adapter is the ingestion surface today.

## Position vs adjacent tooling

- **vs LangSmith / Langfuse / Helicone**: observability tools record what happened; Phionyx makes what happened *hash-chained, signed, and replayable within the recorded gate path*. No independent party has verified these records; that claim is not made. The two layers compose — Phionyx envelope export to OTel / LangSmith is supported.
- **vs OpenTelemetry GenAI conventions**: OTel conventions remain in active development. Phionyx envelopes are OTel-compatible while preserving stronger evidence semantics (hash chain + signature).
- **vs A2A (Google Agent2Agent)**: A2A handles agent-to-agent delegation; Phionyx envelopes are designed protocol-agnostic. A future minor release of this adapter (the v1.1 milestone on this package's own roadmap) adds an explicit A2A agent-card adapter.

## Verification boundary

`verify_chain()` checks payload hashes, previous-hash links and turn order.
Its legacy `ok` field refers **only** to those checks. Every report now also
returns `verification_scope: HASH_CHAIN_ONLY` and
`signature_verification: NOT_EVALUATED`, including failures and empty input.
A signature-only edit does not change the hash result; no signature is checked.
Empty input returns `ok: null` / `NOT_MEASURED`, never PASS.
For Ed25519 authentication a separate verifier must check the signature against
a trusted public key. Capture completeness and truth need additional evidence.
These adapter envelopes are not native AIREP artifacts.

## Install

```bash
pip install phionyx-langchain-langgraph              # core: LangChain callback adapter
pip install "phionyx-langchain-langgraph[langgraph]" # + LangGraph supervisor adapter
```

Source: [github.com/halvrenofviryel/phionyx-langchain-langgraph](https://github.com/halvrenofviryel/phionyx-langchain-langgraph).

## 60-second usage

```python
from langchain_core.runnables import RunnableLambda
from langchain_core.tools import tool
from phionyx_langchain_langgraph import PhionyxCallbackHandler

handler = PhionyxCallbackHandler()   # UNSIGNED by default — set PHIONYX_LANGCHAIN_DEMO=1 (demo-HMAC) or PHIONYX_LANGCHAIN_SIGNING_KEY=<hex> (Ed25519); + filesystem store

@tool
def count_words(text: str) -> str:
    """Return the word count of the input text."""
    return f"{len(text.split())} words"

count_words.invoke(
    {"text": "Phionyx makes runtime evidence verifiable."},
    config={"callbacks": [handler]},
)

# Inspect, verify, export.
print(f"{len(handler.envelopes)} envelopes (unsigned by default; configure a signer to sign)")
print(f"Hash chain checks: {handler.verify_chain()['ok']}")
handler.export_envelopes("evidence/run.jsonl")
```

A complete runnable example covering tool, chain, and LLM events is in
[`examples/quickstart.py`](examples/quickstart.py):

```bash
pip install phionyx-langchain-langgraph
python examples/quickstart.py
```

Expected output:

    Tool result : 5 words
    LLM result  : the answer is forty-two.
    Envelopes   : 8 ({'tool_start': 1, 'tool_end': 1, 'chain_start': 2, 'llm_start': 1, 'llm_end': 1, 'chain_end': 2})
    Hash chain  : OK (8 envelopes; 0 errors)
    Exported    : 8 envelopes → /tmp/phionyx-demo-XXXXXXXX/quickstart-evidence.jsonl

## Multi-agent (LangGraph supervisor)

```python
from phionyx_langchain_langgraph import (
    PhionyxLangGraphSupervisor,
    PhionyxCallbackHandler,
    FilesystemEnvelopeStore,
)

store = FilesystemEnvelopeStore()
sup = PhionyxLangGraphSupervisor(parent_trace_id="run-2026-05-23", store=store)

# Register children — returns derived child trace_ids.
researcher_trace = sup.register(child_node="researcher")
writer_trace     = sup.register(child_node="writer")

# Wire a child handler to each derived trace_id.
researcher = PhionyxCallbackHandler(trace_id=researcher_trace, store=store)
writer     = PhionyxCallbackHandler(trace_id=writer_trace,     store=store)

# Record handoffs as the supervisor dispatches.
sup.handoff(from_node="supervisor", to_node="researcher", payload={"task": "..."})
# ... later
sup.handoff(from_node="researcher", to_node="writer", payload={"sources": [...]})

# Both chains verify independently.
assert sup.verify_chain()["ok"]
assert researcher.verify_chain()["ok"]
assert writer.verify_chain()["ok"]
```

Child chains live in sibling directories under one store root, indexed
by trace_id. Verifiers walk parent + child chains without any
side-channel metadata. This is the multi-agent ingestion surface.

## Status — what's live in v0.1.0a4

- ✅ **PhionyxCallbackHandler** — `on_chain_*`, `on_tool_*`, `on_llm_*`
  events + error variants emit hash-chained envelopes (signed when a signer is configured).
- ✅ **PhionyxLangGraphSupervisor** — `register` + `handoff` emit
  hash-chained envelopes (signed when a signer is configured); derived child trace_ids; parent/child chains
  coexist under one store root.
- ✅ **AgentMessageEnvelope** as the inner record (from
  `phionyx_core.contracts.envelopes`).
- ✅ **HmacSigner** demo + **Signer** protocol for Ed25519 swap.
- ✅ **FilesystemEnvelopeStore** with env-var override.
- ✅ **`verify_chain`** — detects payload tamper + broken links.
- ✅ **`export_envelopes`** — JSONL round-trip.
- ✅ **Unit + integration test suite** — unit, envelope chain, supervisor, real LangChain
  integration (RunnableLambda, @tool, FakeListLLM, chain composition,
  tool error path, JSONL round-trip).

Roadmap beyond v0.1.0a4: a v0.1.0 stable release that locks the schema against the current `phionyx-core` engine (current release on PyPI), building on the multi-agent envelope wiring already shipped in `phionyx-core` v0.6.0.

## License

AGPL-3.0-or-later. Commercial dual-license available — contact founder@phionyx.ai.

## See also

- [phionyx.ai/runtime-evidence](https://phionyx.ai/runtime-evidence) — entry pillar this package surfaces under
- [phionyx.ai/evidence](https://phionyx.ai/evidence) — Evidence Matrix: every load-bearing claim paired with a reviewer-runnable command
- [`phionyx-core`](https://pypi.org/project/phionyx-core/) (PyPI) — the deterministic **engine** (current release on PyPI); core envelope schema + Ed25519 signing
- [`ai-runtime-evidence-protocol`](https://github.com/halvrenofviryel/ai-runtime-evidence-protocol) — **AI Runtime Evidence Protocol (AIREP)**, an experimental, vendor-neutral open format for a per-decision AI decision receipt: one signed, hash-chained, offline-checkable record per runtime decision, readable by anyone and tied to no vendor. The Phionyx **Reasoned Governance Envelope (RGE)** is developed alongside AIREP; a conformant projection between the two is **not implemented** (measured 2026-08-06: AIREP's own reference verifier rejects an RGE envelope handed to it directly) — so the envelopes this adapter writes are headed toward AIREP conformance
- [`phionyx-mcp-server`](https://github.com/halvrenofviryel/phionyx-mcp-server) — MCP trust boundary companion
- [`phionyx-pipeline-mcp`](https://github.com/halvrenofviryel/phionyx-pipeline-mcp) — agent self-claim **gate** companion that vets a claim before it is recorded as evidence
- [`phionyx-eval-inspect`](https://github.com/halvrenofviryel/phionyx-eval-inspect) — Inspect AI bridge companion
- [`phionyx-openai-agents`](https://github.com/halvrenofviryel/phionyx-openai-agents) — OpenAI Agents SDK tracing bridge companion
