calado-langchain

Drop-in calado observability for LangChain and LangGraph agents.

Install

pip install 'calado-langchain==0.0.1'

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

Quick start

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

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

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.

Links

• Docs — https://docs.calado.ai/ingestion/langchain
• Redaction patterns — https://docs.calado.ai/ingestion/redaction
• Shared transport spec — docs/transport-spec.md
• Plan + review trail — plans/langchain_callback_handler.md