Metadata-Version: 2.4
Name: calado-langchain
Version: 0.0.1
Summary: calado LangChain callback handler — captures chain, LLM, tool, and retriever events and ships them to calado for analysis.
Project-URL: Homepage, https://calado.ai
Project-URL: Documentation, https://docs.calado.ai/ingestion/langchain
Project-URL: Repository, https://github.com/43designstudio/calado
Project-URL: Changelog, https://github.com/43designstudio/calado/blob/main/packages/sdk-python-langchain/CHANGELOG.md
Author: calado
License: MIT
Keywords: agents,ai,ai-agents,calado,callbacks,evaluation,langchain,langchain-callback,langgraph,llm,llm-observability,llmops,observability,tracing
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Requires-Dist: langchain-core<0.5,>=0.2.10
Provides-Extra: capture
Requires-Dist: langchain-anthropic; extra == 'capture'
Provides-Extra: test
Requires-Dist: pytest-asyncio>=0.23; extra == 'test'
Requires-Dist: pytest>=7.4; extra == 'test'
Description-Content-Type: text/markdown

# calado-langchain

Drop-in calado observability for LangChain and LangGraph agents.

## Install

```bash
pip install 'calado-langchain==0.0.1'
```

Requires Python 3.9+ and `langchain-core>=0.2.10,<0.5`.

## Quick start

```python
import os
from calado_langchain import CaladoCallbackHandler

os.environ["CALADO_API_KEY"] = "cl_..."

handler = CaladoCallbackHandler()

# Per-chain mode
chain.invoke(
    {"input": "..."},
    config={
        "callbacks": [handler],
        "metadata": {"session_id": "user-42"},
    },
)
```

The SDK reads `session_id` from `metadata`. It also picks up
`thread_id` (LangGraph convention) and `langsmith_session_id` /
`langchain_session_id` automatically, plus a `session:<id>` tag as
a fallback.

Or set `CALADO_ENABLED=true` plus `CALADO_API_KEY=cl_...` and the
handler attaches to every chain in the process automatically. No code
change required.

On the first successful POST a single line lands in stderr:

```
[calado] Connected. First batch sent. View at https://app.calado.ai/agents/<agent_id>
```

## Public surface

```python
CaladoCallbackHandler(
    *,
    api_key=None,           # or env CALADO_API_KEY
    base_url=None,          # or env CALADO_BASE_URL, default https://app.calado.ai
    batch_size=10,
    flush_interval_s=30.0,
    max_run_age_s=3600.0,
    max_queue_bytes=10 * 1024 * 1024,
    debug=False,
    mask=None,              # callable: dict -> dict | None (sync or async)
)

CaladoAsyncCallbackHandler(...)  # same signature, for ainvoke / LangGraph

handler.status()    # dict — see docs/transport-spec.md §3
await handler.astatus()
handler.flush(timeout_s=5.0)
handler.shutdown(timeout_s=5.0)
```

Constructor is keyword-only. The `mask` callable can be either sync or
async; the SDK detects which without invoking it. Returning `None` drops
that single child run (per-OV7 granularity). Patterns and recipes live
at <https://docs.calado.ai/ingestion/redaction>.

## Diagnostics

```bash
python -m calado_langchain doctor
```

Prints the installed `calado-langchain` and `langchain-core` versions,
the supported range, and the fix command on resolver failure.

## Pre-1.0 semver

`calado-langchain` is pre-1.0. Minor versions (`0.x.0`) may introduce
breaking changes. Pin exactly until 1.0 ships. See
[`CHANGELOG.md`](./CHANGELOG.md).

## Links

- Docs — <https://docs.calado.ai/ingestion/langchain>
- Redaction patterns — <https://docs.calado.ai/ingestion/redaction>
- Shared transport spec — [`docs/transport-spec.md`](../../docs/transport-spec.md)
- Plan + review trail — [`plans/langchain_callback_handler.md`](../../plans/langchain_callback_handler.md)
