Metadata-Version: 2.4
Name: slimchain
Version: 0.1.1rc1
Summary: Local tracing hooks for LangChain and LangGraph
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# slimchain

Local tracing hooks for LangChain and LangGraph. Stores traces locally or posts them to a webhook.

## Install

```bash
pip install -e .
```

## Enable tracing

Tracing is controlled by `SLIMCHAIN_TRACING` and an output directory:

- `SLIMCHAIN_TRACING=true` to enable recording.
- `SLIMCHAIN_DIR=/path/to/output` to control where JSON is written (default: `~/.slimchain`).

Traces are written to:

- `traces.jsonl` (append-only)
- `traces.json` (pretty JSON)

## Webhook ingestion

To post traces to slimchain servers, set the webhook endpoint and project id:

- `SLIMCHAIN_ENDPOINT=https://your-server`
- `SLIMCHAIN_PROJECT_ID=123`
- `SLIMCHAIN_API_KEY=your_project_api_key`

When `SLIMCHAIN_ENDPOINT` and `SLIMCHAIN_PROJECT_ID` are set, traces are POSTed to:

`POST {SLIMCHAIN_ENDPOINT}/traces/{SLIMCHAIN_PROJECT_ID}`

## .env support

If a `.env` file exists in the working directory, slimchain will load it on startup.
You can override the path with `SLIMCHAIN_DOTENV=/path/to/.env`.

## LangChain integration

Attach the callback to any LangChain model or runnable:

```python
from slimchain.client import Client
from slimchain.watcher import SlimchainCallback

client = Client(root=".slimchain")
client.config.tracing = True
callback = SlimchainCallback(client=client)

# Example with any LangChain chat model
model = SomeChatModel(
    model="...",
    callbacks=[callback],
)
response = model.invoke("Say hello in one sentence.")
```

## LangGraph integration

Pass the callback via the LangGraph node or runnable config:

```python
from slimchain.client import Client
from slimchain.watcher import SlimchainCallback
from langgraph.graph import END, StateGraph

client = Client(root=".slimchain")
client.config.tracing = True
callback = SlimchainCallback(client=client)

# inside a node function
message = model.invoke(prompt, config={"callbacks": [callback]})
```

## Examples

Run the smoke examples after installing their dependencies:

```bash
pip install langchain-openai langchain-google-genai langgraph
```

Gemini:

```bash
SLIMCHAIN_TRACING=true \
GOOGLE_API_KEY=... \
.venv/bin/python examples/gemini_smoke.py
```

OpenRouter (OpenAI-compatible client):

```bash
SLIMCHAIN_TRACING=true \
OPENROUTER_API_KEY=... \
.venv/bin/python examples/openrouter_smoke.py
```

LangGraph (OpenRouter):

```bash
SLIMCHAIN_TRACING=true \
OPENROUTER_API_KEY=... \
.venv/bin/python examples/langgraph_smoke.py
```

Multi-agent (Gemini + OpenRouter):

```bash
SLIMCHAIN_TRACING=true \
GOOGLE_API_KEY=... \
OPENROUTER_API_KEY=... \
.venv/bin/python examples/multi_agent_smoke.py
```

Optional model overrides for the multi-agent example:

```bash
GEMINI_MODEL=gemini-3.1-flash-lite
OPENROUTER_MODEL=openai/gpt-4o-mini
```

## Output schema

Each trace record includes:

- `trace_id`, `node_name`, `framework`
- `input`, `output`
- `tokens_in`, `tokens_out`
- `duration_ms`, `model_used`
- `timestamp`, `project`, `status`, `error`
- `metadata`

## TEST

```bash
.venv/bin/python -m pytest -q
```
