tracesage 0.1.0__tar.gz

tracesage-0.1.0/.gitignore

@@ -0,0 +1,70 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+evaluation
+
+# Virtual environments
+venv/
+env/
+ENV/
+.venv/
+.env
+
+# Testing
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+.nox/
+coverage.xml
+*.cover
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store
+
+# Tooling
+.ruff_cache/
+.mypy_cache/
+
+# Local data
+*.db
+*.db-shm
+*.db-wal
+.tracesage/
+.tracesage-demo/
+tracesage_test/
+bench_data/
+examples/**/mcp_demo_data/
+
+# Build artifacts
+*.tar.gz
+*.whl
+
+# MkDocs build output
+site/

tracesage-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 tracesage contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tracesage-0.1.0/PKG-INFO

@@ -0,0 +1,374 @@
+Metadata-Version: 2.4
+Name: tracesage
+Version: 0.1.0
+Summary: Production observability adapter for LangChain/LangGraph multi-agent systems
+Project-URL: Homepage, https://github.com/kjgpta/tracesage
+Project-URL: Repository, https://github.com/kjgpta/tracesage
+Project-URL: Documentation, https://kjgpta.github.io/tracesage/
+Project-URL: Changelog, https://github.com/kjgpta/tracesage/blob/main/docs/changelog.md
+Project-URL: Issues, https://github.com/kjgpta/tracesage/issues
+Author: tracesage contributors
+License: MIT
+License-File: LICENSE
+Keywords: agents,langchain,langgraph,llm,multi-agent,observability,tracing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.11
+Requires-Dist: aiofiles>=23.2.0
+Requires-Dist: aiosqlite>=0.20.0
+Requires-Dist: fastapi>=0.111.0
+Requires-Dist: pydantic-settings>=2.3.0
+Requires-Dist: pydantic>=2.7.0
+Requires-Dist: typer>=0.12.0
+Requires-Dist: uvicorn[standard]>=0.30.0
+Requires-Dist: websockets>=12.0
+Provides-Extra: dev
+Requires-Dist: build>=1.0.0; extra == 'dev'
+Requires-Dist: httpx>=0.27.0; extra == 'dev'
+Requires-Dist: langchain-core>=0.2.0; extra == 'dev'
+Requires-Dist: langchain-mcp-adapters>=0.1.0; extra == 'dev'
+Requires-Dist: langchain>=0.2.0; extra == 'dev'
+Requires-Dist: langgraph>=0.2.0; extra == 'dev'
+Requires-Dist: mcp>=1.0.0; extra == 'dev'
+Requires-Dist: mypy>=1.10.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.5.0; extra == 'dev'
+Requires-Dist: twine>=5.0.0; extra == 'dev'
+Provides-Extra: langchain
+Requires-Dist: langchain-core<1.4.0,>=0.2.0; extra == 'langchain'
+Provides-Extra: mcp
+Requires-Dist: langchain-mcp-adapters>=0.1.0; extra == 'mcp'
+Requires-Dist: langgraph>=0.2.0; extra == 'mcp'
+Requires-Dist: mcp>=1.0.0; extra == 'mcp'
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+# tracesage
+
+**Production observability for LangChain & LangGraph multi-agent systems.**
+Drop in two lines, see live execution traces in your browser.
+
+[![PyPI version](https://img.shields.io/pypi/v/tracesage.svg)](https://pypi.org/project/tracesage/)
+[![Python versions](https://img.shields.io/pypi/pyversions/tracesage.svg)](https://pypi.org/project/tracesage/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![CI](https://github.com/kjgpta/tracesage/actions/workflows/ci.yml/badge.svg)](https://github.com/kjgpta/tracesage/actions/workflows/ci.yml)
+[![Status: alpha](https://img.shields.io/badge/status-alpha-orange.svg)](#status)
+
+</div>
+
+```python
+from tracesage import TraceSage
+
+# Illustrative only — `await` runs inside an async function. See Quick start
+# below for a complete, runnable `async def main()`.
+tracer = await TraceSage.create()                          # one-time setup
+
+result = await graph.ainvoke(
+    {"input": payload},
+    config={"callbacks": [tracer.handler]},                # only line you add
+)
+
+# Open http://localhost:7842/ui to see the trace live
+```
+
+---
+
+## Contents
+
+- [Why tracesage](#why-tracesage)
+- [Install](#install)
+- [Quick start](#quick-start)
+- [Concepts: topology node kinds](#concepts-topology-node-kinds)
+- [Features](#features)
+- [Examples](#examples)
+- [Documentation](#documentation)
+- [Comparison](#comparison)
+- [Performance](#performance)
+- [Status](#status)
+- [Contributing](#contributing)
+- [License](#license)
+
+---
+
+## Why tracesage
+
+LangChain agents emit a rich callback stream — chain start/end, tool start/end,
+LLM start/end, retrieval, errors. **tracesage** captures all of it without
+changing your workflow logic, persists it locally (SQLite + gzipped blobs),
+and renders it in an interactive graph + timeline UI in real time.
+
+- **Zero infrastructure.** No Docker. No Postgres. No external services. `pip install`.
+- **Two-line integration.** One callback added to your existing `ainvoke`.
+- **Production-grade safety.** The handler never raises. The tracer never crashes
+  your pipeline.
+- **Interactive graph view.** Custom SVG graph (no framework), auto-laid-out. Hover, click, replay any run.
+- **MCP-aware.** Tools loaded from MCP servers are attributed by source, so you can
+  see which tools came from which server vs. which are hardcoded. See [docs/mcp.md](docs/mcp.md).
+- **Pluggable storage.** SQLite today; Postgres / remote-collector / object-store backends planned (see [`production_roadmap.md`](production_roadmap.md)).
+- **MIT licensed.** Free forever.
+
+## Install
+
+```bash
+pip install tracesage[langchain]
+```
+
+Requires **Python 3.11+**. The `[langchain]` extra pulls `langchain-core`;
+that's the only mandatory third-party dep beyond the standard FastAPI /
+aiosqlite / pydantic stack. If your app uses **LangGraph**, also `pip install
+langgraph` (tracesage doesn't pull it).
+
+tracesage is **provider-agnostic** — it traces LangChain's callback stream, so
+OpenAI / Anthropic / local models are all captured automatically; there's no
+provider setting in tracesage. Install whichever provider you use:
+
+```bash
+pip install langchain-openai      # OPENAI_API_KEY=...
+pip install langchain-anthropic   # ANTHROPIC_API_KEY=...
+```
+
+For MCP tool-source attribution (loads tools from MCP servers and tags them by
+source), install the `mcp` extra:
+
+```bash
+pip install 'tracesage[mcp]'
+```
+
+## Quick start
+
+**See it in 5 seconds** — seed a sample trace and open the UI:
+
+```bash
+tracesage demo
+```
+
+**Sync scripts / notebooks** — wrap your code; every LangChain call is captured
+automatically (no `callbacks=` wiring) and a clickable trace link is printed:
+
+```python
+import tracesage
+
+with tracesage.trace() as tl:          # starts the UI + global capture
+    result = agent.invoke("your input")     # 🔍 tracesage: http://127.0.0.1:7842/ui/#run=...
+    input("Trace ready — open the printed link, then Enter to exit.")  # keep the UI up
+```
+
+(The embedded UI stops when the `with` block / process exits; traces persist to
+`~/.tracesage`, so you can also reopen them later with `tracesage serve`.)
+
+**Async apps** — use the context manager (or `await TraceSage.create()` for full control):
+
+```python
+import asyncio
+from tracesage import TraceSage
+
+async def main():
+    async with TraceSage.session(install=True) as tl:   # install=True → global capture
+        await graph.ainvoke({"input": "your payload"}, config={"tags": ["my-system"]})
+        await tl.flush()                                 # ensure events are persisted
+        print(tl.run_url("<run_id>"))                    # deep link to a run
+
+asyncio.run(main())
+```
+
+Prefer explicit wiring? Pass `config={"callbacks": [tl.handler]}` instead of `install=True`.
+
+That's it. Open **http://localhost:7842/ui** and explore.
+
+### Developer workflow
+
+Once you have traces, debug them without leaving your terminal:
+
+```bash
+tracesage show <run_id>          # render a run as a tree in the terminal
+tracesage watch <run_id>         # live-tail events as they stream
+tracesage diff <run_a> <run_b>   # compare two runs (tokens, tools, errors)
+tracesage view trace.jsonl       # open an exported trace in the UI directly
+```
+
+**Test your agents** — the `tracesage_capture` pytest fixture is auto-registered:
+
+```python
+def test_agent_uses_search(tracesage_capture):
+    agent.invoke("find me a hotel")
+    tracesage_capture.assert_tool_called("search")
+    tracesage_capture.assert_no_errors()
+    assert tracesage_capture.total_tokens()[0] < 5000
+```
+
+See **[`docs/development.md`](docs/development.md)** for the full developer guide, and
+**[`examples/showcase/`](examples/showcase/)** for 30 before/after apps across popular use cases.
+
+## Concepts: topology node kinds
+
+When you open the UI, every node in the topology graph is one of five event-based
+kinds — plus a synthesized **`mcp`** node when you attribute tools to an MCP server.
+Knowing what each means is the prerequisite to reading a trace:
+
+| Kind | What it is | Examples you'll see |
+|---|---|---|
+| **`agent`** | A function **you** registered as a LangGraph node, that calls other components | `agent:billing_agent`, `agent:fact_extractor`, `agent:supervisor` |
+| **`tool`** | A side-effect function (DB query, API call, calculation) decorated with `@tool` | `tool:lookup_account`, `tool:run_sql`, `tool:cite_sources` |
+| **`llm`** | A language-model call (chat or completion) | `llm:FakeListChatModel`, `llm:ChatOpenAI`, `llm:ChatAnthropic` |
+| **`retriever`** | A `BaseRetriever` subclass — the "R" in RAG | `retriever:Chroma`, `retriever:FAISS`, `retriever:_FixedCorpusRetriever` |
+| **`chain`** | Plumbing — LCEL primitives, the LangGraph orchestrator, routing functions | `chain:LangGraph`, `chain:RunnableSequence`, `chain:ChatPromptTemplate`, `chain:route_after_quality` |
+| **`mcp`** | An MCP server (synthesized) — groups the tools loaded from it | `mcp:weather`, `mcp:math`, `mcp:github` |
+
+Quick mental model:
+
+- **`agent`** is your code that *calls* something. It does reasoning.
+- **`tool`** does the actual side-effect work and returns a result.
+- **`llm`** is what you count, cost, and cache.
+- **`retriever`** is its own dimension — "did we find the right docs?"
+  is a different question from "did the LLM use them well?".
+- **`chain`** is the wrapping machinery (the `prompt | llm | parser`
+  pipe operator, the LangGraph state machine, routing functions). It's
+  infrastructure, not business logic.
+- **`mcp`** groups tools by the MCP server they came from — provenance, so you can
+  tell server-provided tools from your hardcoded ones (see [docs/mcp.md](docs/mcp.md)).
+
+Read the full reference at **[`docs/concepts.md`](docs/concepts.md)** —
+it covers how tracesage classifies events into kinds, why agents with no
+descendants get demoted to `chain`, and walks through a research-pipeline
+topology piece by piece.
+
+## Features
+
+### Live interactive UI
+
+- **Run list** with status badges (running / completed / failed), search, status filter
+- **SVG graph** showing agents, tools, and execution paths — pulses as events arrive
+- **MCP attribution** — `mcp:` server nodes with per-server colors, agent→server and
+  server→tool edges, and a draggable "Tools by source" panel grouping tools by origin
+- **Timeline** with click-to-expand step cards, lazy-loaded full payloads
+- **Replay** mode that re-animates a run at 1x / 2x / 5x speed
+- **Dark / light themes**, persisted in `localStorage`
+- **Keyboard shortcuts:** `j`/`k` next/prev run, `/` focus search, `t` toggle theme, `Esc`, `?`
+
+### Production safety
+
+- Refuses to bind non-loopback addresses without `auth_token` (hard fail-stop)
+- Bearer-token HTTP auth + WebSocket auth via `?token=` or subprotocol
+- Constant-time token comparison
+- Path-traversal blocked at runtime
+- Per-run event cap (circuit breaker) and root-level sampling for high volumes
+- Bounded internal state (no unbounded memory growth in long-running processes)
+- **Kill switch:** `TRACESAGE_ENABLED=false` makes it a complete no-op (no server, no
+  DB/worker, no-op handler) — integrate once, disable per-environment. See
+  [docs/production.md](docs/production.md).
+
+### CLI
+
+```bash
+tracesage serve  --data-dir ~/.tracesage          # read-only viewer
+tracesage export --run-id RUN_ID -o trace.jsonl   # export to JSONL
+tracesage import -i trace.jsonl                   # import a JSONL export
+tracesage stats  --data-dir ~/.tracesage          # summary stats
+tracesage runs   --status failed --limit 20       # list runs
+tracesage gc     --max-runs 10000                 # retention cleanup
+tracesage doctor --data-dir ~/.tracesage          # data-dir diagnostics
+tracesage version
+```
+
+See [`docs/cli.md`](docs/cli.md) for full reference.
+
+## Examples
+
+The [`examples/`](examples/) directory has three tiers:
+
+- **[`getting_started/`](examples/getting_started/)** — 3 standalone demos driven by
+  `FakeListChatModel` (**no API key**): smart-search agent, research supervisor, RAG.
+- **[`mcp/`](examples/mcp/)** — tools from 2 local MCP servers + 2 hardcoded tools,
+  attributed by source in the topology (needs `tracesage[mcp]`).
+- **[`showcase/`](examples/showcase/)** — **30 real before/after apps** across popular use
+  cases (customer support, RAG, multi-agent, MCP, reasoning loops, finance/legal/insurance).
+  Each ships a plain `before.py` and an `after.py` with tracesage added, so `diff` shows the
+  exact integration.
+
+```bash
+# instant, no key:
+python examples/getting_started/01_smart_search_agent.py       # then open http://localhost:7842/ui
+
+# the real-world gallery (needs an LLM key):
+pip install -r examples/showcase/requirements.txt
+export OPENAI_API_KEY=...
+python examples/showcase/01_support_faq_router/after.py
+```
+
+The **[showcase gallery](examples/showcase/)** has 30 before/after apps spanning
+LangChain + LangGraph: routing, parallel fan-out, the supervisor pattern, RAG variants,
+writer-critic loops, map-reduce, MCP, self-correction, and finance/legal/insurance verticals.
+
+## Documentation
+
+| Doc | What's in it |
+|---|---|
+| [Quickstart](docs/quickstart.md) | First trace in five minutes |
+| [Developer guide](docs/development.md) | Trace links, sync/notebook setup, CLI debugging, pytest fixture |
+| [Configuration](docs/configuration.md) | Every `TRACESAGE_*` env var explained |
+| [CLI reference](docs/cli.md) | All `tracesage` subcommands |
+| [Production guide](docs/production.md) | Sampling, auth, retention, deployment |
+| [Comparison](docs/comparison.md) | tracesage vs LangSmith / LangFuse / Phoenix |
+| [Extending tracesage](docs/extending.md) | Adding framework adapters and storage backends |
+| **[Examples](examples/showcase/)** | **30 before/after apps with tracesage added** |
+
+## Comparison
+
+When to use `tracesage` vs alternatives:
+
+| | tracesage | LangSmith | LangFuse | Phoenix |
+|---|---|---|---|---|
+| Zero infra | ✓ | cloud / enterprise self-host | Docker + Postgres | ✓ |
+| Pure pip install | ✓ | ✓ (cloud) | ✗ | ✓ |
+| Live UI | ✓ | ✓ | ✓ | ✓ |
+| MIT licensed | ✓ | proprietary | MIT | Elastic v2 |
+| Eval framework | non-goal | ✓ | ✓ | ✓ |
+| OpenTelemetry export | v0.3+ | partial | ✓ | ✓ |
+
+See [`docs/comparison.md`](docs/comparison.md) for the full breakdown.
+
+## Performance
+
+Bench results (5,000 events, 100 distinct run_ids, 20% blob-eligible):
+
+| Platform | Sustained | p99 write | Drops |
+|---|---|---|---|
+| Linux x86 + NVMe | 800–1200 ev/s | 80–150 ms | 0 |
+| Windows NTFS | 60–100 ev/s | 1–2 s | 0 |
+
+Windows NTFS is the bottleneck (gzip + fsync amplification). For very high
+throughput on Windows, raise `TRACESAGE_WORKER_BATCH_SIZE` to 200 and
+`TRACESAGE_WORKER_BATCH_TIMEOUT` to 0.5.
+
+## Status
+
+**v0.1 — alpha.** API may still shift before v1.0. Production-monitoring-ready for
+single-Python-process deployments; centralized multi-process / remote-collector mode
+is on the roadmap (see [`production_roadmap.md`](production_roadmap.md)).
+
+See [the changelog](docs/changelog.md) for release notes.
+
+## Contributing
+
+Issues and pull requests are welcome.
+
+- Read [`docs/contributing.md`](docs/contributing.md) before sending a PR
+- For non-trivial changes, open a [discussion](https://github.com/kjgpta/tracesage/discussions/categories/ideas) first
+- Bugs and feature requests use the [issue templates](https://github.com/kjgpta/tracesage/issues/new/choose)
+- Security reports: see [`SECURITY.md`](.github/SECURITY.md) — please don't open public issues for vulnerabilities
+- All participation is governed by the [Code of Conduct](.github/CODE_OF_CONDUCT.md)
+
+## License
+
+[MIT](LICENSE) © tracesage contributors