Metadata-Version: 2.4
Name: viatoris-langchain
Version: 0.1.0
Summary: LangChain callback handler for Viatoris — emit a signed Viatoris receipt for every LangChain tool call
Home-page: https://viatoris.ai
Author: Jared
Author-email: jared@viatoris.ai
License: MIT
Project-URL: Documentation, https://viatoris.ai/quickstart
Project-URL: Source, https://github.com/ViatorisAI/viatoris-core/tree/main/packages/adapters/langchain
Project-URL: Bug Tracker, https://github.com/ViatorisAI/viatoris-core/issues
Keywords: ai-agent langchain viatoris agent-trust-protocol receipts audit
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 :: Security :: Cryptography
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: viatorisai>=1.0.0
Requires-Dist: langchain-core>=0.1.0
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: project-url
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# Viatoris LangChain Adapter

A drop-in [LangChain](https://python.langchain.com) callback handler that emits a cryptographically signed [Viatoris](https://viatoris.ai) receipt for every tool call your agent makes.

No rewrite. No latency. Receipt submission is fire-and-forget on a background thread and never raises â€” Viatoris is designed to never crash your agent.

## Install

```bash
pip install viatoris-langchain
```

This pulls in `viatorisai` (the core SDK) and works with any `langchain-core>=0.1.0` agent.

## Usage

Get an API key and create an agent passport at [dashboard.viatoris.ai](https://dashboard.viatoris.ai/signup), then save the returned `private_key_jwk` somewhere your agent can read it. After that, one line of integration:

```python
from viatoris_langchain import ViatorisCallbackHandler

handler = ViatorisCallbackHandler(
    org_api_key="at_live_...",
    agent_did="did:web:example.com:agents:scout",
    private_key_jwk=saved_key,
    key_id="did:web:example.com:agents:scout#key-1",
)

# Add to any LangChain agent â€” every tool call gets a signed receipt
agent = AgentExecutor(agent=..., tools=..., callbacks=[handler])
```

That's it. Run your agent normally. Every `on_tool_end` produces a signed `ActionReceipt` with the tool name, inputs, outputs, and a success/failure status. Browse them at [dashboard.viatoris.ai/audit](https://dashboard.viatoris.ai/audit) or query them through the [Viatoris API](https://viatoris.ai/quickstart).

## Tracking LLM and chain calls too

By default the handler only emits receipts for **tool calls** â€” that's almost always what you want for an audit trail. If you also want to receipt every raw LLM call or every chain step, opt in:

```python
handler = ViatorisCallbackHandler(
    org_api_key="at_live_...",
    agent_did="did:web:example.com:agents:scout",
    private_key_jwk=saved_key,
    key_id="did:web:example.com:agents:scout#key-1",
    track_llm=True,
    verbose=True,
)
```

| Option | Default | What it tracks |
|---|---|---|
| `track_llm` | `False` | Every `on_llm_start`/`on_llm_end` pair (one receipt per LLM call) |
| `track_chains` | `False` | Every `on_chain_start`/`on_chain_end` pair (one receipt per chain step) |
| `capability` | `"langchain"` | The `capability` field on every receipt â€” useful for filtering in the dashboard |
| `verbose` | `False` | Print a one-liner each time a receipt is queued |

Both `track_llm` and `track_chains` produce a lot of receipts on a busy agent. Tools-only is the recommended default for production.

## How it works

LangChain emits callbacks at every stage of agent execution. This handler:

1. Stores tool inputs by `run_id` on `on_tool_start`.
2. On `on_tool_end`, looks up the stored input, builds an `ActionReceipt`, signs it with your agent's Ed25519 key, and submits it to the Viatoris receipt service on a background thread.
3. On `on_tool_error`, does the same but with `result="failure"` and the error in the outputs.

Every method body is wrapped in a try/except â€” if the SDK, the network, or anything else throws, your agent keeps running.

## Documentation

Full Viatoris guide at [viatoris.ai/quickstart](https://viatoris.ai/quickstart).

Questions? Email [jared@viatoris.ai](mailto:jared@viatoris.ai).

## License

MIT
