{"id":50901944,"url":"https://github.com/daugaard/sessionbat-sdk","last_synced_at":"2026-06-16T03:30:41.238Z","repository":{"id":356644215,"uuid":"1233466641","full_name":"daugaard/sessionbat-sdk","owner":"daugaard","description":null,"archived":false,"fork":false,"pushed_at":"2026-05-09T02:04:15.000Z","size":90,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-09T03:42:47.819Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/daugaard.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-05-09T01:55:27.000Z","updated_at":"2026-05-09T02:04:18.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/daugaard/sessionbat-sdk","commit_stats":null,"previous_names":["daugaard/sessionbat-sdk"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/daugaard/sessionbat-sdk","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daugaard%2Fsessionbat-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daugaard%2Fsessionbat-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daugaard%2Fsessionbat-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daugaard%2Fsessionbat-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/daugaard","download_url":"https://codeload.github.com/daugaard/sessionbat-sdk/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daugaard%2Fsessionbat-sdk/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34390052,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-16T02:00:06.860Z","response_time":126,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-16T03:30:40.764Z","updated_at":"2026-06-16T03:30:41.230Z","avatar_url":"https://github.com/daugaard.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SessionBat SDK\n\n![Tests](https://img.shields.io/github/actions/workflow/status/daugaard/sessionbat-sdk/tests.yml?branch=main)\n![Ruff](https://img.shields.io/github/actions/workflow/status/daugaard/sessionbat-sdk/ruff.yml?branch=main)\n![License](https://img.shields.io/github/license/daugaard/sessionbat-sdk)\n\nSessionBat is a Python SDK for recording AI session activity and sending it to SessionBat.\n\nIt is designed for teams that want to debug and understand what your AI app actually did, including:\n- model calls and responses\n- tool calls\n- document retrievals\n\n## Install\n\n```bash\nuv add sessionbat\n```\n\nOr with `pip`:\n\n```bash\npip install sessionbat\n```\n\n## Quickstart \n\n### LangChain integration\nThe 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:\n```python\nfrom sessionbat import SessionBat\n\nclient = SessionBat(app=\"support-bot\", api_key=\"sbat_ingest_...\")\nhandler = client.langchain_callback(tags=[\"langchain\"])\n\n# Configure your chain or agent to use the handler, for example:\nresult = chain.invoke(\n  {\"input\": \"I am locked out of my account\"},\n  config={\"callbacks\": [handler]},\n)\n\n# or using agents:\nagent.invoke(\n  {\"messages\": [{\"role\": \"user\", \"content\": \"what is the weather in sf\"}]},\n  config={\"callbacks\": [handler]},\n)\n```\n\n### Custom integration\nOr 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.\n\n```python\nfrom sessionbat import SessionBat\n\nclient = SessionBat(\n    api_key=\"sbat_ingest_...\",\n    app=\"support-bot\",\n    default_tags=[\"production\"],\n    default_context={\"environment\": \"prod\"},\n)\n\nsession = client.session(\n    session_id=\"thread_123\",\n    context={\n        \"user_id\": \"user_123\",\n        \"workspace_id\": \"ws_456\",\n    },\n)\n\ninteraction = session.interaction(interaction_id=\"interaction_123\")\n\ninteraction.retrieval(\n    query=\"reset password locked out\",\n    documents=[\n        {\n            \"id\": \"doc_reset_password\",\n            \"title\": \"Reset your password\",\n            \"score\": 0.93,\n        }\n    ],\n    metadata={\"index\": \"support_articles\"},\n    metrics={\"latency_ms\": 81, \"documents_found\": 1},\n)\n\ninteraction.tool_call(\n    tool_name=\"lookup_account\",\n    input={\"account_id\": \"acct_987\"},\n    output={\"status\": \"locked\", \"password_reset_available\": True},\n    metadata={\"service\": \"account-service\"},\n    metrics={\"latency_ms\": 117, \"http_status\": 200},\n)\n\ninteraction.llm(\n    model=\"gpt-5.4-mini\",\n    input={\"messages\": [{\"role\": \"user\", \"content\": \"I am locked out of my account\"}]},\n    output={\"text\": \"I found your account. Use the reset link and follow the email prompt.\"},\n    metrics={\"latency_ms\": 820, \"input_tokens\": 142, \"output_tokens\": 36},\n)\n```\n\nThat emits structured events like:\n\n```json\n{\n  \"type\": \"llm\",\n  \"session_id\": \"thread_123\",\n  \"interaction_id\": \"interaction_123\",\n  \"tags\": [\"production\"],\n  \"context\": {\"environment\": \"prod\", \"user_id\": \"user_123\", \"workspace_id\": \"ws_456\"},\n  \"observation\": {\n    \"kind\": \"llm\",\n    \"name\": null\n  }\n}\n```\n\n## Core API\n\nImport the main types from `sessionbat`:\n\n```python\nfrom sessionbat import SessionBat, Session, Interaction, LangChainCallbackHandler\n```\n\n### `SessionBat`\n\n`SessionBat` is the client entrypoint.\n\n```python\nclient = SessionBat(\n    app=\"support-bot\",\n    api_key=\"sbat_ingest_...\",\n    endpoint=\"https://ingest.sessionbat.com/api/v1/ingestion/events\",\n)\n```\n\nUse `client.session(...)` to create a session with a stable `session_id`, then\nuse `session.interaction(...)` to record observations against a specific turn or interaction.\n\nThe SDK sends events to SessionBat ingestion by default. Pass `api_key` directly\nor set `SESSIONBAT_API_KEY`. For tests or local debugging, pass an explicit\ntransport such as `MemoryTransport` or `StdoutTransport`.\n\nHTTP ingestion runs in a background thread so recording observations does not\nblock your application on network I/O. Transient failures are retried with\nbounded backoff, and queued events are flushed automatically during interpreter\nshutdown. Call `client.flush()` or `client.close()` when you need to wait for\ndelivery before exiting a short-lived process.\n\n### `Session` and `Interaction`\n\nA `Session` groups interactions. A `Interaction` records completed observations:\n\n- `interaction.llm(...)`\n- `interaction.tool_call(...)`\n- `interaction.retrieval(...)`\n\nEach call returns the generated observation id.\n\n## Event model\n\nSessionBat keeps the shape intentionally small:\n\n- `tags` are lightweight labels for filtering and grouping.\n- `context` holds session-level or observation-level metadata.\n- `metadata` stores descriptive operation data such as model, provider, index,\n  or service name.\n- `metrics` stores numeric data such as latency, tokens, cost, or HTTP status.\n- `input` and `output` hold raw payloads.\n- `error` is attached to the failed operation instead of being emitted as a\n  separate event type.\n\n## Development\n\n```bash\nuv run pytest\nuv run ruff check .\nuv run ruff format --check .\n```\n\n## Repository layout\n\n- `src/sessionbat/client.py` contains the core recording API.\n- `src/sessionbat/langchain.py` contains the LangChain adapter.\n- `src/sessionbat/transports.py` defines the ingestion transport plus stdout\n  and in-memory transports for debugging and tests.\n\n## License\n\nMIT.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdaugaard%2Fsessionbat-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdaugaard%2Fsessionbat-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdaugaard%2Fsessionbat-sdk/lists"}