https://github.com/daugaard/sessionbat-sdk
https://github.com/daugaard/sessionbat-sdk
Last synced: 19 days ago
JSON representation
- Host: GitHub
- URL: https://github.com/daugaard/sessionbat-sdk
- Owner: daugaard
- License: mit
- Created: 2026-05-09T01:55:27.000Z (about 2 months ago)
- Default Branch: main
- Last Pushed: 2026-05-09T02:04:15.000Z (about 2 months ago)
- Last Synced: 2026-05-09T03:42:47.819Z (about 2 months ago)
- Language: Python
- Size: 87.9 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
README
# SessionBat SDK
SessionBat is a Python SDK for recording AI session activity and sending it to SessionBat.
It is designed for teams that want to debug and understand what your AI app actually did, including:
- model calls and responses
- tool calls
- document retrievals
## Install
```bash
uv add sessionbat
```
Or with `pip`:
```bash
pip install sessionbat
```
## Quickstart
### LangChain integration
The easist way to start is to use the built-in LangChain callback handler. Create a `SessionBat` client and pass the handler to your chain or agent:
```python
from sessionbat import SessionBat
client = SessionBat(app="support-bot", api_key="sbat_ingest_...")
handler = client.langchain_callback(tags=["langchain"])
# Configure your chain or agent to use the handler, for example:
result = chain.invoke(
{"input": "I am locked out of my account"},
config={"callbacks": [handler]},
)
# or using agents:
agent.invoke(
{"messages": [{"role": "user", "content": "what is the weather in sf"}]},
config={"callbacks": [handler]},
)
```
### Custom integration
Or you can integrate directly with the core API for more control. Create a `SessionBat` client and use it to create a `Session` with a stable `session_id` and shared `context`. Then record observations against that session as they happen.
```python
from sessionbat import SessionBat
client = SessionBat(
api_key="sbat_ingest_...",
app="support-bot",
default_tags=["production"],
default_context={"environment": "prod"},
)
session = client.session(
session_id="thread_123",
context={
"user_id": "user_123",
"workspace_id": "ws_456",
},
)
interaction = session.interaction(interaction_id="interaction_123")
interaction.retrieval(
query="reset password locked out",
documents=[
{
"id": "doc_reset_password",
"title": "Reset your password",
"score": 0.93,
}
],
metadata={"index": "support_articles"},
metrics={"latency_ms": 81, "documents_found": 1},
)
interaction.tool_call(
tool_name="lookup_account",
input={"account_id": "acct_987"},
output={"status": "locked", "password_reset_available": True},
metadata={"service": "account-service"},
metrics={"latency_ms": 117, "http_status": 200},
)
interaction.llm(
model="gpt-5.4-mini",
input={"messages": [{"role": "user", "content": "I am locked out of my account"}]},
output={"text": "I found your account. Use the reset link and follow the email prompt."},
metrics={"latency_ms": 820, "input_tokens": 142, "output_tokens": 36},
)
```
That emits structured events like:
```json
{
"type": "llm",
"session_id": "thread_123",
"interaction_id": "interaction_123",
"tags": ["production"],
"context": {"environment": "prod", "user_id": "user_123", "workspace_id": "ws_456"},
"observation": {
"kind": "llm",
"name": null
}
}
```
## Core API
Import the main types from `sessionbat`:
```python
from sessionbat import SessionBat, Session, Interaction, LangChainCallbackHandler
```
### `SessionBat`
`SessionBat` is the client entrypoint.
```python
client = SessionBat(
app="support-bot",
api_key="sbat_ingest_...",
endpoint="https://ingest.sessionbat.com/api/v1/ingestion/events",
)
```
Use `client.session(...)` to create a session with a stable `session_id`, then
use `session.interaction(...)` to record observations against a specific turn or interaction.
The SDK sends events to SessionBat ingestion by default. Pass `api_key` directly
or set `SESSIONBAT_API_KEY`. For tests or local debugging, pass an explicit
transport such as `MemoryTransport` or `StdoutTransport`.
HTTP ingestion runs in a background thread so recording observations does not
block your application on network I/O. Transient failures are retried with
bounded backoff, and queued events are flushed automatically during interpreter
shutdown. Call `client.flush()` or `client.close()` when you need to wait for
delivery before exiting a short-lived process.
### `Session` and `Interaction`
A `Session` groups interactions. A `Interaction` records completed observations:
- `interaction.llm(...)`
- `interaction.tool_call(...)`
- `interaction.retrieval(...)`
Each call returns the generated observation id.
## Event model
SessionBat keeps the shape intentionally small:
- `tags` are lightweight labels for filtering and grouping.
- `context` holds session-level or observation-level metadata.
- `metadata` stores descriptive operation data such as model, provider, index,
or service name.
- `metrics` stores numeric data such as latency, tokens, cost, or HTTP status.
- `input` and `output` hold raw payloads.
- `error` is attached to the failed operation instead of being emitted as a
separate event type.
## Development
```bash
uv run pytest
uv run ruff check .
uv run ruff format --check .
```
## Repository layout
- `src/sessionbat/client.py` contains the core recording API.
- `src/sessionbat/langchain.py` contains the LangChain adapter.
- `src/sessionbat/transports.py` defines the ingestion transport plus stdout
and in-memory transports for debugging and tests.
## License
MIT.