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 runtime evidence. This package surfaces on 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, current release on PyPI — the deterministic runtime whose envelope schema this adapter emits), the self-governance gate (phionyx-pipeline-mcp), and the AI Runtime Evidence Protocol (AIREP) (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

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.

60-second usage

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:

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)

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 — entry pillar this package surfaces under
• phionyx.ai/evidence — Evidence Matrix: every load-bearing claim paired with a reviewer-runnable command
• phionyx-core (PyPI) — the deterministic engine (current release on PyPI); core envelope schema + Ed25519 signing
• 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 — MCP trust boundary companion
• phionyx-pipeline-mcp — agent self-claim gate companion that vets a claim before it is recorded as evidence
• phionyx-eval-inspect — Inspect AI bridge companion
• phionyx-openai-agents — OpenAI Agents SDK tracing bridge companion