capsule-trace 0.1.0__tar.gz

capsule_trace-0.1.0/PKG-INFO

@@ -0,0 +1,124 @@
+Metadata-Version: 2.4
+Name: capsule-trace
+Version: 0.1.0
+Summary: Deterministic replay & time-travel debugger for AI agents
+Author-email: Capsule <sdk@capsule.dev>
+Project-URL: Homepage, https://capsule.dev
+Project-URL: Documentation, https://docs.capsule.dev
+Project-URL: Repository, https://github.com/capsule-dev/capsule
+Project-URL: Issues, https://github.com/capsule-dev/capsule/issues
+Keywords: ai,agents,debugging,replay,llm,observability
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Debuggers
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: sqlalchemy<3.0.0,>=2.0.0
+Requires-Dist: pydantic<3.0.0,>=2.0.0
+Requires-Dist: click<9.0.0,>=8.1.0
+Requires-Dist: httpx<1.0.0,>=0.27.0
+Requires-Dist: zstandard>=0.22.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: ulid-py>=1.1.0
+Provides-Extra: openai
+Requires-Dist: openai>=1.30.0; extra == "openai"
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.28.0; extra == "anthropic"
+Provides-Extra: google
+Requires-Dist: google-generativeai>=0.7.0; extra == "google"
+Provides-Extra: langchain
+Requires-Dist: langchain>=0.2.0; extra == "langchain"
+Requires-Dist: langchain-core>=0.2.0; extra == "langchain"
+Provides-Extra: langgraph
+Requires-Dist: langgraph>=0.1.0; extra == "langgraph"
+Provides-Extra: all
+Requires-Dist: openai>=1.30.0; extra == "all"
+Requires-Dist: anthropic>=0.28.0; extra == "all"
+Requires-Dist: google-generativeai>=0.7.0; extra == "all"
+Requires-Dist: langchain>=0.2.0; extra == "all"
+Requires-Dist: langchain-core>=0.2.0; extra == "all"
+Requires-Dist: langgraph>=0.1.0; extra == "all"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
+Requires-Dist: pytest-cov>=5.0.0; extra == "dev"
+Requires-Dist: hypothesis>=6.100.0; extra == "dev"
+Requires-Dist: mypy>=1.10.0; extra == "dev"
+Requires-Dist: ruff>=0.4.0; extra == "dev"
+
+# capsule-trace
+
+**Deterministic replay & time-travel debugger for AI agents.**
+
+```bash
+pip install capsule-trace
+```
+
+---
+
+## Quick Start
+
+```python
+import capsule_trace
+
+@capsule.trace(agent_name="my-agent")
+def run_agent(query: str) -> str:
+    from openai import OpenAI
+    client = OpenAI()
+    response = client.chat.completions.create(
+        model="gpt-4o",
+        messages=[{"role": "user", "content": query}],
+    )
+    return response.choices[0].message.content
+```
+
+That's it. Every LLM call is now captured automatically.
+
+## CLI
+
+```bash
+# List captured sessions
+capsule-trace list
+
+# Inspect a session step by step
+capsule-trace show ses_01HXYZ123
+
+# Export to shareable file
+capsule-trace export ses_01HXYZ123 --output bug.capsule
+
+# Replay deterministically
+capsule-trace replay ses_01HXYZ123
+
+# Branch from step 7 with different temperature
+capsule-trace branch ses_01HXYZ123 --from-step 7 --modify temperature=0.0
+
+# Diff two sessions
+capsule-trace diff ses_01HXYZ ses_01HABC
+```
+
+## Supported Providers
+
+| Provider | Status |
+|----------|--------|
+| OpenAI (sync + async) | ✅ Sprint 2 |
+| Anthropic (sync + async) | ✅ Sprint 2 |
+| Google Generative AI | ✅ Sprint 2 |
+| LangChain | Sprint 4 |
+| LangGraph | Sprint 4 |
+
+## Disable at Runtime
+
+```bash
+CAPSULE_DISABLE=1 python my_agent.py
+```
+
+Zero overhead when disabled — checked once at function entry.
+
+## License
+
+Apache 2.0 — see [LICENSE](LICENSE).

capsule_trace-0.1.0/README.md

@@ -0,0 +1,71 @@
+# capsule-trace
+
+**Deterministic replay & time-travel debugger for AI agents.**
+
+```bash
+pip install capsule-trace
+```
+
+---
+
+## Quick Start
+
+```python
+import capsule_trace
+
+@capsule.trace(agent_name="my-agent")
+def run_agent(query: str) -> str:
+    from openai import OpenAI
+    client = OpenAI()
+    response = client.chat.completions.create(
+        model="gpt-4o",
+        messages=[{"role": "user", "content": query}],
+    )
+    return response.choices[0].message.content
+```
+
+That's it. Every LLM call is now captured automatically.
+
+## CLI
+
+```bash
+# List captured sessions
+capsule-trace list
+
+# Inspect a session step by step
+capsule-trace show ses_01HXYZ123
+
+# Export to shareable file
+capsule-trace export ses_01HXYZ123 --output bug.capsule
+
+# Replay deterministically
+capsule-trace replay ses_01HXYZ123
+
+# Branch from step 7 with different temperature
+capsule-trace branch ses_01HXYZ123 --from-step 7 --modify temperature=0.0
+
+# Diff two sessions
+capsule-trace diff ses_01HXYZ ses_01HABC
+```
+
+## Supported Providers
+
+| Provider | Status |
+|----------|--------|
+| OpenAI (sync + async) | ✅ Sprint 2 |
+| Anthropic (sync + async) | ✅ Sprint 2 |
+| Google Generative AI | ✅ Sprint 2 |
+| LangChain | Sprint 4 |
+| LangGraph | Sprint 4 |
+
+## Disable at Runtime
+
+```bash
+CAPSULE_DISABLE=1 python my_agent.py
+```
+
+Zero overhead when disabled — checked once at function entry.
+
+## License
+
+Apache 2.0 — see [LICENSE](LICENSE).

capsule_trace-0.1.0/pyproject.toml

@@ -0,0 +1,98 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "capsule-trace"
+version = "0.1.0"
+description = "Deterministic replay & time-travel debugger for AI agents"
+readme = "README.md"
+license = { file = "LICENSE" }
+authors = [{ name = "Capsule", email = "sdk@capsule.dev" }]
+keywords = ["ai", "agents", "debugging", "replay", "llm", "observability"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Debuggers",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+requires-python = ">=3.11"
+dependencies = [
+    "sqlalchemy>=2.0.0,<3.0.0",
+    "pydantic>=2.0.0,<3.0.0",
+    "click>=8.1.0,<9.0.0",
+    "httpx>=0.27.0,<1.0.0",
+    "zstandard>=0.22.0",
+    "rich>=13.0.0",
+    "ulid-py>=1.1.0",
+]
+
+[project.optional-dependencies]
+openai = ["openai>=1.30.0"]
+anthropic = ["anthropic>=0.28.0"]
+google = ["google-generativeai>=0.7.0"]
+langchain = ["langchain>=0.2.0", "langchain-core>=0.2.0"]
+langgraph = ["langgraph>=0.1.0"]
+all = [
+    "openai>=1.30.0",
+    "anthropic>=0.28.0",
+    "google-generativeai>=0.7.0",
+    "langchain>=0.2.0",
+    "langchain-core>=0.2.0",
+    "langgraph>=0.1.0",
+]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.23.0",
+    "pytest-cov>=5.0.0",
+    "hypothesis>=6.100.0",
+    "mypy>=1.10.0",
+    "ruff>=0.4.0",
+]
+
+[project.scripts]
+capsule-trace = "capsule_trace.cli:main"
+
+[project.urls]
+Homepage = "https://capsule.dev"
+Documentation = "https://docs.capsule.dev"
+Repository = "https://github.com/capsule-dev/capsule"
+Issues = "https://github.com/capsule-dev/capsule/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["capsule_trace*"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "N", "UP", "B", "C4", "SIM", "TCH", "RET"]
+ignore = ["E501"]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+addopts = "-v --tb=short"
+
+[tool.coverage.run]
+source = ["capsule_trace"]
+branch = true
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "if TYPE_CHECKING:",
+    "raise NotImplementedError",
+    "@overload",
+]

capsule_trace-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

capsule_trace-0.1.0/src/capsule_trace/__init__.py

@@ -0,0 +1,22 @@
+"""Capsule — Deterministic replay & time-travel debugger for AI agents."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from capsule_trace.core.decorator import trace
+from capsule_trace.core.session import Session, get_current_session
+
+__version__ = "0.1.0"
+__all__ = ["trace", "Session", "get_current_session", "last_session_path"]
+
+
+def last_session_path() -> Path | None:
+    """Return the path of the most recently saved .capsule file, or None."""
+    candidates: list[Path] = []
+    for search_dir in (Path.home() / ".capsule", Path.cwd()):
+        if search_dir.is_dir():
+            candidates.extend(search_dir.glob("*.capsule"))
+    if not candidates:
+        return None
+    return max(candidates, key=lambda p: p.stat().st_mtime)

capsule_trace-0.1.0/src/capsule_trace/cli/__init__.py

@@ -0,0 +1,3 @@
+from capsule_trace.cli.main import main
+
+__all__ = ["main"]

capsule_trace-0.1.0/src/capsule_trace/cli/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running the CLI as `python -m capsule.cli`."""
+from capsule_trace.cli.main import main
+
+if __name__ == "__main__":
+    main()