provedex-langchain 0.1.0__tar.gz

provedex_langchain-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+dist/
+build/
+*.egg-info/
+__pycache__/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+*.pyc

provedex_langchain-0.1.0/PKG-INFO

@@ -0,0 +1,216 @@
+Metadata-Version: 2.4
+Name: provedex-langchain
+Version: 0.1.0
+Summary: LangChain BaseCallbackHandler that signs every LLM and tool callback via the Provedex sidecar. Covers LangGraph by inheritance.
+Project-URL: Homepage, https://github.com/provedex/provedex
+Project-URL: Repository, https://github.com/provedex/provedex
+Project-URL: Issues, https://github.com/provedex/provedex/issues
+Author-email: Aditya Suresh <adi@provedex.io>
+License: Apache-2.0
+Keywords: audit,compliance,ed25519,langchain,langgraph,provedex,signing
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security :: Cryptography
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Requires-Dist: langchain-core<0.4,>=0.3
+Requires-Dist: pydantic>=2.0
+Provides-Extra: dev
+Requires-Dist: langchain-openai>=0.2; extra == 'dev'
+Requires-Dist: langchain<0.4,>=0.3; extra == 'dev'
+Requires-Dist: langgraph>=0.2; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# provedex-langchain
+
+`provedex-langchain` is a LangChain `BaseCallbackHandler` that signs every LLM
+call, tool call, and operator session boundary via the Provedex sidecar. Each
+event gets an Ed25519 signature and a SHA-256 parent hash, written to a local
+NDJSON ledger that anyone with the operator's public key can verify offline.
+The primary buyers are regulated-AI shops: healthcare scribes processing clinical
+notes, financial bots executing trades or claims, and customer-service agents
+subject to FINRA or state AI-act supervision. One `ProvedexCallbackHandler`
+instance covers both LangChain LCEL pipelines and LangGraph state machines,
+because LangGraph propagates LangChain callbacks for every LLM and tool step.
+
+## Quickstart
+
+```
+pip install provedex-langchain
+```
+
+Start the sidecar first (default `127.0.0.1:8765`):
+
+```
+provedex-agent --rate-limit-off &
+```
+
+```python
+from provedex_langchain import ProvedexCallbackHandler, ProvedexConfig
+
+handler = ProvedexCallbackHandler(config=ProvedexConfig())
+# pass to your chain or graph:
+chain.invoke({"q": "hi"}, config={"callbacks": [handler]})
+```
+
+## Callback mapping
+
+| LangChain callback(s) | AgentEvent variant | Fields populated |
+|---|---|---|
+| `start_session()` (operator call) | `SessionStarted` | `agent_id`, `model_id`, `session_id` from config |
+| `end_session(reason)` (operator call) | `SessionEnded` | `reason`, `summary_sha256 = sha256("")` |
+| `on_llm_start` / `aon_llm_start` | none (buffered by `run_id`) | model id from `serialized.get("id")`, joined prompts, start timestamp |
+| `on_chat_model_start` / `aon_chat_model_start` | none (buffered) | model id, flattened message list, start timestamp |
+| `on_llm_end` / `aon_llm_end` (paired with start by `run_id`) | `ModelInvoked` | `model_id`, `prompt_sha256`, `response_sha256`, `prompt_tokens` / `response_tokens` from `llm_output.get("token_usage", {})` if present (else 0) |
+| `on_llm_error` (paired) | `ModelInvoked` | `response_sha256 = sha256(f"{type(error).__name__}: {error}")` |
+| `on_tool_start` / `aon_tool_start` | `ToolCalled` | `tool_name`, `args_sha256` of canonical-JSON of args, `args_redacted` |
+| `on_tool_end` / `aon_tool_end` | `ToolReturned` | `tool_name`, `result_sha256`, `latency_ms`, `success = True` |
+| `on_tool_error` | `ToolReturned` | `tool_name`, `result_sha256` of error description, `latency_ms`, `success = False` |
+
+**Skipped** (not signed in v0.1): `on_llm_new_token` (per-token noise),
+`on_chain_start` / `on_chain_end` (LCEL composition makes chain boundaries
+ambiguous), `on_agent_action` / `on_agent_finish` (covered by tool events),
+`on_retriever_start` / `on_retriever_end` (no v1 event variant), `on_text`
+(no defined semantics).
+
+## Configuration reference
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `agent_url` | `str` | `$PROVEDEX_AGENT_URL` or `http://127.0.0.1:8765` | URL of the running `provedex-agent`. Override via env var `PROVEDEX_AGENT_URL` or constructor argument. |
+| `session_id` | `str` | `uuid4()` | Identifier for this call session. Override to tie the ledger entry to your own session ID. |
+| `agent_id` | `str` | `"langchain-agent"` | Logical name of your agent. Appears in every signed event for that session. |
+| `model_id` | `str` | `"unknown"` | LLM model identifier. Used in `ModelInvoked` events when the callback args do not supply one. |
+| `on_sign_failure` | `"warn" \| "raise" \| "silent"` | `"warn"` | What to do when the agent returns 4xx. `warn` logs a warning and continues. `raise` propagates the exception out of the background worker - useful in test environments. `silent` increments counters only. |
+| `queue_size` | `int` | `1000` | Capacity of the internal deque. When full, the oldest queued event is dropped. |
+| `request_timeout_seconds` | `float` | `2.0` | HTTP timeout for each POST to the agent. |
+| `shutdown_drain_seconds` | `float` | `5.0` | How long to wait for the queue to drain after `handler.stop()` before returning. |
+
+## Session lifecycle
+
+A session groups a set of LLM and tool events under a single `SessionStarted` /
+`SessionEnded` pair. The operator controls session boundaries - the handler does
+not infer them from chain hierarchy.
+
+Explicit form:
+
+```python
+handler.start_session()
+chain.invoke({"q": "hi"}, config={"callbacks": [handler]})
+handler.end_session(reason="request_complete")
+```
+
+Context manager (sync):
+
+```python
+with handler.session("user-12345-request"):
+    chain.invoke({"q": "hi"}, config={"callbacks": [handler]})
+```
+
+Context manager (async):
+
+```python
+async with handler.session("user-12345-request"):
+    await chain.ainvoke({"q": "hi"}, config={"callbacks": [handler]})
+```
+
+On exception, the context manager calls `end_session` with `reason` set to the
+exception class name, so the ledger always has a closed session boundary.
+
+## Latency budget
+
+The handler's hot path is a single `deque.appendleft()` call. The background
+worker thread drains the deque and performs the HTTP POST off the LLM call
+thread.
+
+Measured against a 1ms-latency mock agent with a 1000-callback burst
+(one `on_llm_start` + `on_llm_end` pair per iteration):
+
+- p50 producer overhead: 2.5 microseconds
+- p99 producer overhead: 5 microseconds
+
+The LLM call thread is not blocked by network I/O.
+
+## Failure modes
+
+| Failure | Behaviour | Counter |
+|---|---|---|
+| Agent unreachable (ConnectionRefused) | warn + drop | `dropped_total` |
+| Agent slow (timeout) | warn + drop | `dropped_total` |
+| Agent 4xx | log error + apply `on_sign_failure` | `dropped_total` |
+| Agent 5xx | warn + drop | `dropped_total` |
+| Queue overflow | drop oldest, rate-limited warning | `overflow_total` |
+| Callback with missing fields | log warning, skip enqueue | n/a |
+| `run_id` missing on `on_llm_end` (no paired start) | log warning, skip emission | n/a |
+
+Counters are readable as attributes on the handler instance:
+`handler.signed_total`, `handler.dropped_total`, `handler.overflow_total`.
+
+## LangGraph
+
+LangGraph fires LangChain callbacks for every LLM and tool step inside a graph.
+No additional integration is required. The operator wraps the graph invocation
+inside a session context:
+
+```python
+async with handler.session("graph-run"):
+    await graph.invoke(state, config={"callbacks": [handler]})
+```
+
+Graph-specific events (CheckpointSaved, node enter / exit, edge transitions) are
+NOT signed in v0.1. They are documented as a follow-up item once a customer
+surfaces a concrete audit requirement for checkpoint-level granularity.
+
+## Architecture
+
+This binding does not contain the signing primitive. The primitive is the Rust
+sidecar at https://github.com/provedex/provedex. The binding translates
+LangChain callback arguments into `AgentEvent` shapes per
+`docs/spec/event-schema-v1.md` and POSTs them to the sidecar over loopback
+HTTP. The translation is pure Python with no C extensions required.
+
+The sidecar signs each event with the operator's Ed25519 private key and chains
+it via SHA-256 parent hashes into a local NDJSON ledger. Each event record
+contains the signature, the parent hash, and the payload hash. Anyone with the
+operator's public key can run `provedex verify` against the ledger file offline,
+without network access and without trusting a third party.
+
+## Verifying the ledger
+
+```
+provedex verify
+provedex verify --ledger ~/.provedex/ledger.ndjson
+provedex verify --ledger /path/to/sandboxed/ledger.ndjson
+```
+
+The command reads the NDJSON file, checks the Ed25519 signature on every record,
+and verifies the SHA-256 hash chain is unbroken. Exit code 0 means the ledger is
+intact.
+
+## Regulatory context
+
+Tamper-evident audit logs are a direct requirement across several frameworks
+currently in force or taking effect in 2026. The EU AI Act Article 12 requires
+high-risk AI deployments to produce audit logs that are tamper-evident and
+retained for at least six months; enforcement applies from August 2, 2026.
+The Colorado AI Act (effective February 1, 2026) requires deployers of
+high-risk AI systems to maintain records sufficient to demonstrate compliance
+with consumer protection obligations. HIPAA's audit-control safeguard
+(45 CFR 164.312(b)) requires clinical voice agents to record and examine
+system activity, which for AI scribes means a verifiable transcript of every
+utterance processed. FINRA's 2026 examination priorities identify AI agent
+auditability as a focus area for broker-dealer supervision. A hash-chained,
+Ed25519-signed ledger satisfies the tamper-evident requirement across all four
+frameworks with a single integration point.
+
+---
+
+License: Apache-2.0. Main repo: https://github.com/provedex/provedex

provedex_langchain-0.1.0/README.md

@@ -0,0 +1,185 @@
+# provedex-langchain
+
+`provedex-langchain` is a LangChain `BaseCallbackHandler` that signs every LLM
+call, tool call, and operator session boundary via the Provedex sidecar. Each
+event gets an Ed25519 signature and a SHA-256 parent hash, written to a local
+NDJSON ledger that anyone with the operator's public key can verify offline.
+The primary buyers are regulated-AI shops: healthcare scribes processing clinical
+notes, financial bots executing trades or claims, and customer-service agents
+subject to FINRA or state AI-act supervision. One `ProvedexCallbackHandler`
+instance covers both LangChain LCEL pipelines and LangGraph state machines,
+because LangGraph propagates LangChain callbacks for every LLM and tool step.
+
+## Quickstart
+
+```
+pip install provedex-langchain
+```
+
+Start the sidecar first (default `127.0.0.1:8765`):
+
+```
+provedex-agent --rate-limit-off &
+```
+
+```python
+from provedex_langchain import ProvedexCallbackHandler, ProvedexConfig
+
+handler = ProvedexCallbackHandler(config=ProvedexConfig())
+# pass to your chain or graph:
+chain.invoke({"q": "hi"}, config={"callbacks": [handler]})
+```
+
+## Callback mapping
+
+| LangChain callback(s) | AgentEvent variant | Fields populated |
+|---|---|---|
+| `start_session()` (operator call) | `SessionStarted` | `agent_id`, `model_id`, `session_id` from config |
+| `end_session(reason)` (operator call) | `SessionEnded` | `reason`, `summary_sha256 = sha256("")` |
+| `on_llm_start` / `aon_llm_start` | none (buffered by `run_id`) | model id from `serialized.get("id")`, joined prompts, start timestamp |
+| `on_chat_model_start` / `aon_chat_model_start` | none (buffered) | model id, flattened message list, start timestamp |
+| `on_llm_end` / `aon_llm_end` (paired with start by `run_id`) | `ModelInvoked` | `model_id`, `prompt_sha256`, `response_sha256`, `prompt_tokens` / `response_tokens` from `llm_output.get("token_usage", {})` if present (else 0) |
+| `on_llm_error` (paired) | `ModelInvoked` | `response_sha256 = sha256(f"{type(error).__name__}: {error}")` |
+| `on_tool_start` / `aon_tool_start` | `ToolCalled` | `tool_name`, `args_sha256` of canonical-JSON of args, `args_redacted` |
+| `on_tool_end` / `aon_tool_end` | `ToolReturned` | `tool_name`, `result_sha256`, `latency_ms`, `success = True` |
+| `on_tool_error` | `ToolReturned` | `tool_name`, `result_sha256` of error description, `latency_ms`, `success = False` |
+
+**Skipped** (not signed in v0.1): `on_llm_new_token` (per-token noise),
+`on_chain_start` / `on_chain_end` (LCEL composition makes chain boundaries
+ambiguous), `on_agent_action` / `on_agent_finish` (covered by tool events),
+`on_retriever_start` / `on_retriever_end` (no v1 event variant), `on_text`
+(no defined semantics).
+
+## Configuration reference
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `agent_url` | `str` | `$PROVEDEX_AGENT_URL` or `http://127.0.0.1:8765` | URL of the running `provedex-agent`. Override via env var `PROVEDEX_AGENT_URL` or constructor argument. |
+| `session_id` | `str` | `uuid4()` | Identifier for this call session. Override to tie the ledger entry to your own session ID. |
+| `agent_id` | `str` | `"langchain-agent"` | Logical name of your agent. Appears in every signed event for that session. |
+| `model_id` | `str` | `"unknown"` | LLM model identifier. Used in `ModelInvoked` events when the callback args do not supply one. |
+| `on_sign_failure` | `"warn" \| "raise" \| "silent"` | `"warn"` | What to do when the agent returns 4xx. `warn` logs a warning and continues. `raise` propagates the exception out of the background worker - useful in test environments. `silent` increments counters only. |
+| `queue_size` | `int` | `1000` | Capacity of the internal deque. When full, the oldest queued event is dropped. |
+| `request_timeout_seconds` | `float` | `2.0` | HTTP timeout for each POST to the agent. |
+| `shutdown_drain_seconds` | `float` | `5.0` | How long to wait for the queue to drain after `handler.stop()` before returning. |
+
+## Session lifecycle
+
+A session groups a set of LLM and tool events under a single `SessionStarted` /
+`SessionEnded` pair. The operator controls session boundaries - the handler does
+not infer them from chain hierarchy.
+
+Explicit form:
+
+```python
+handler.start_session()
+chain.invoke({"q": "hi"}, config={"callbacks": [handler]})
+handler.end_session(reason="request_complete")
+```
+
+Context manager (sync):
+
+```python
+with handler.session("user-12345-request"):
+    chain.invoke({"q": "hi"}, config={"callbacks": [handler]})
+```
+
+Context manager (async):
+
+```python
+async with handler.session("user-12345-request"):
+    await chain.ainvoke({"q": "hi"}, config={"callbacks": [handler]})
+```
+
+On exception, the context manager calls `end_session` with `reason` set to the
+exception class name, so the ledger always has a closed session boundary.
+
+## Latency budget
+
+The handler's hot path is a single `deque.appendleft()` call. The background
+worker thread drains the deque and performs the HTTP POST off the LLM call
+thread.
+
+Measured against a 1ms-latency mock agent with a 1000-callback burst
+(one `on_llm_start` + `on_llm_end` pair per iteration):
+
+- p50 producer overhead: 2.5 microseconds
+- p99 producer overhead: 5 microseconds
+
+The LLM call thread is not blocked by network I/O.
+
+## Failure modes
+
+| Failure | Behaviour | Counter |
+|---|---|---|
+| Agent unreachable (ConnectionRefused) | warn + drop | `dropped_total` |
+| Agent slow (timeout) | warn + drop | `dropped_total` |
+| Agent 4xx | log error + apply `on_sign_failure` | `dropped_total` |
+| Agent 5xx | warn + drop | `dropped_total` |
+| Queue overflow | drop oldest, rate-limited warning | `overflow_total` |
+| Callback with missing fields | log warning, skip enqueue | n/a |
+| `run_id` missing on `on_llm_end` (no paired start) | log warning, skip emission | n/a |
+
+Counters are readable as attributes on the handler instance:
+`handler.signed_total`, `handler.dropped_total`, `handler.overflow_total`.
+
+## LangGraph
+
+LangGraph fires LangChain callbacks for every LLM and tool step inside a graph.
+No additional integration is required. The operator wraps the graph invocation
+inside a session context:
+
+```python
+async with handler.session("graph-run"):
+    await graph.invoke(state, config={"callbacks": [handler]})
+```
+
+Graph-specific events (CheckpointSaved, node enter / exit, edge transitions) are
+NOT signed in v0.1. They are documented as a follow-up item once a customer
+surfaces a concrete audit requirement for checkpoint-level granularity.
+
+## Architecture
+
+This binding does not contain the signing primitive. The primitive is the Rust
+sidecar at https://github.com/provedex/provedex. The binding translates
+LangChain callback arguments into `AgentEvent` shapes per
+`docs/spec/event-schema-v1.md` and POSTs them to the sidecar over loopback
+HTTP. The translation is pure Python with no C extensions required.
+
+The sidecar signs each event with the operator's Ed25519 private key and chains
+it via SHA-256 parent hashes into a local NDJSON ledger. Each event record
+contains the signature, the parent hash, and the payload hash. Anyone with the
+operator's public key can run `provedex verify` against the ledger file offline,
+without network access and without trusting a third party.
+
+## Verifying the ledger
+
+```
+provedex verify
+provedex verify --ledger ~/.provedex/ledger.ndjson
+provedex verify --ledger /path/to/sandboxed/ledger.ndjson
+```
+
+The command reads the NDJSON file, checks the Ed25519 signature on every record,
+and verifies the SHA-256 hash chain is unbroken. Exit code 0 means the ledger is
+intact.
+
+## Regulatory context
+
+Tamper-evident audit logs are a direct requirement across several frameworks
+currently in force or taking effect in 2026. The EU AI Act Article 12 requires
+high-risk AI deployments to produce audit logs that are tamper-evident and
+retained for at least six months; enforcement applies from August 2, 2026.
+The Colorado AI Act (effective February 1, 2026) requires deployers of
+high-risk AI systems to maintain records sufficient to demonstrate compliance
+with consumer protection obligations. HIPAA's audit-control safeguard
+(45 CFR 164.312(b)) requires clinical voice agents to record and examine
+system activity, which for AI scribes means a verifiable transcript of every
+utterance processed. FINRA's 2026 examination priorities identify AI agent
+auditability as a focus area for broker-dealer supervision. A hash-chained,
+Ed25519-signed ledger satisfies the tamper-evident requirement across all four
+frameworks with a single integration point.
+
+---
+
+License: Apache-2.0. Main repo: https://github.com/provedex/provedex

provedex_langchain-0.1.0/RELEASING.md

@@ -0,0 +1,27 @@
+# Release process for provedex-langchain
+
+Pre-release checklist:
+
+1. All tests pass locally and in CI.
+2. `pyproject.toml` version bumped if shipping a new version.
+3. Tag the binding release: `git tag langchain-vX.Y.Z` (binding-scoped prefix so it does not collide with the agent's `vX.Y.Z` tags).
+
+Publish to PyPI:
+
+```
+cd bindings/python/provedex-langchain
+python -m pip install --upgrade build twine
+python -m build
+python -m twine check dist/*
+python -m twine upload dist/*
+```
+
+After publish:
+
+1. Verify `pip install provedex-langchain` from a clean venv pulls the new version.
+2. Confirm the README on PyPI renders correctly (long_description from `README.md`).
+3. Update the `provedex-langchain` row in the root `README.md` Components table if anything material changed.
+
+Yank policy: same as `provedex-pipecat`; see `bindings/python/provedex-pipecat/RELEASING.md` for the procedure.
+
+Out of scope here: the Rust agent + CLI publish process lives in the root `RELEASING.md`.

provedex_langchain-0.1.0/examples/langchain_basic.py

@@ -0,0 +1,38 @@
+"""Minimal LangChain LCEL pipeline with Provedex signing.
+
+Run a local provedex-agent before starting:
+    provedex-agent --rate-limit-off &
+"""
+
+import asyncio
+import os
+
+from langchain_core.language_models.fake_chat_models import FakeListChatModel
+from langchain_core.prompts import ChatPromptTemplate
+
+from provedex_langchain import ProvedexCallbackHandler, ProvedexConfig
+
+
+async def main() -> None:
+    cfg = ProvedexConfig(
+        agent_url=os.getenv("PROVEDEX_AGENT_URL", "http://127.0.0.1:8765"),
+        agent_id="example-langchain-agent",
+        model_id="fake-list",
+        session_id="example-session-001",
+    )
+    handler = ProvedexCallbackHandler(config=cfg)
+
+    # Replace FakeListChatModel with ChatOpenAI(model="gpt-4o") or any real LLM.
+    llm = FakeListChatModel(responses=["Hello back."])
+    prompt = ChatPromptTemplate.from_template("Say hi to {name}.")
+    chain = prompt | llm
+
+    async with handler.session("example-request"):
+        await chain.ainvoke({"name": "world"}, config={"callbacks": [handler]})
+
+    await handler.stop()
+    print(f"signed={handler.signed_total} dropped={handler.dropped_total}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

provedex_langchain-0.1.0/examples/langgraph_basic.py

@@ -0,0 +1,52 @@
+"""Minimal LangGraph pipeline with Provedex signing.
+
+Demonstrates that LangGraph users get audit coverage automatically because
+LangGraph propagates LangChain callbacks for every LLM and tool call.
+
+Run a local provedex-agent before starting:
+    provedex-agent --rate-limit-off &
+"""
+
+import asyncio
+import os
+from typing import TypedDict
+
+from langchain_core.language_models.fake_chat_models import FakeListChatModel
+from langgraph.graph import END, START, StateGraph
+
+from provedex_langchain import ProvedexCallbackHandler, ProvedexConfig
+
+
+class State(TypedDict):
+    answer: str
+
+
+async def main() -> None:
+    cfg = ProvedexConfig(
+        agent_url=os.getenv("PROVEDEX_AGENT_URL", "http://127.0.0.1:8765"),
+        agent_id="example-langgraph-agent",
+        model_id="fake-list",
+    )
+    handler = ProvedexCallbackHandler(config=cfg)
+
+    llm = FakeListChatModel(responses=["Hello from the graph."])
+
+    async def respond(state: State, config) -> State:
+        resp = await llm.ainvoke("greet user", config=config)
+        return {"answer": resp.content}
+
+    graph_builder = StateGraph(State)
+    graph_builder.add_node("respond", respond)
+    graph_builder.add_edge(START, "respond")
+    graph_builder.add_edge("respond", END)
+    graph = graph_builder.compile()
+
+    async with handler.session("graph-example"):
+        await graph.ainvoke({"answer": ""}, config={"callbacks": [handler]})
+
+    await handler.stop()
+    print(f"signed={handler.signed_total} dropped={handler.dropped_total}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

provedex_langchain-0.1.0/pyproject.toml

@@ -0,0 +1,71 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "provedex-langchain"
+version = "0.1.0"
+description = "LangChain BaseCallbackHandler that signs every LLM and tool callback via the Provedex sidecar. Covers LangGraph by inheritance."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "Apache-2.0" }
+authors = [
+    { name = "Aditya Suresh", email = "adi@provedex.io" },
+]
+keywords = ["langchain", "langgraph", "audit", "signing", "compliance", "ed25519", "provedex"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Security :: Cryptography",
+]
+dependencies = [
+    "langchain-core>=0.3,<0.4",
+    "httpx>=0.27",
+    "pydantic>=2.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "respx>=0.21",
+    "ruff>=0.5",
+    "mypy>=1.10",
+    "langchain>=0.3,<0.4",
+    "langchain-openai>=0.2",
+    "langgraph>=0.2",
+]
+
+[project.urls]
+Homepage = "https://github.com/provedex/provedex"
+Repository = "https://github.com/provedex/provedex"
+Issues = "https://github.com/provedex/provedex/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/provedex_langchain"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP", "ASYNC"]
+
+[tool.ruff.lint.per-file-ignores]
+# Tests legitimately invoke cargo + provedex CLI via blocking subprocess.
+"tests/*" = ["ASYNC221"]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+markers = [
+    "integration: requires real provedex-agent binary",
+    "slow: takes > 1s",
+]

provedex_langchain-0.1.0/src/provedex_langchain/__init__.py

@@ -0,0 +1,7 @@
+"""Provedex binding for LangChain (and LangGraph by inheritance)."""
+
+from .config import ProvedexConfig
+from .handler import ProvedexCallbackHandler
+
+__version__ = "0.1.0"
+__all__ = ["ProvedexCallbackHandler", "ProvedexConfig"]

provedex_langchain-0.1.0/src/provedex_langchain/_client.py

@@ -0,0 +1,35 @@
+"""Private async HTTP client for the provedex-agent /v1/sign endpoint."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+
+class SignError(Exception):
+    """Raised when a sign attempt fails (network, timeout, or non-2xx)."""
+
+
+class AgentClient:
+    """Thin httpx wrapper. One per handler instance; reuses the connection."""
+
+    def __init__(self, base_url: str, timeout: float) -> None:
+        self._base_url = base_url.rstrip("/")
+        self._client = httpx.AsyncClient(
+            base_url=self._base_url,
+            timeout=httpx.Timeout(timeout, connect=timeout),
+            headers={"content-type": "application/json"},
+        )
+
+    async def sign(self, event: dict[str, Any]) -> None:
+        """POST {event: ...} to /v1/sign. Raises SignError on any failure."""
+        try:
+            resp = await self._client.post("/v1/sign", json={"event": event})
+        except httpx.HTTPError as e:
+            raise SignError(f"agent unreachable: {e}") from e
+        if resp.status_code >= 400:
+            raise SignError(f"agent returned {resp.status_code}: {resp.text[:200]}")
+
+    async def aclose(self) -> None:
+        await self._client.aclose()