ai-agent-inspector 1.0.0__py3-none-any.whl → 1.1.0__py3-none-any.whl

{ai_agent_inspector-1.0.0.dist-info → ai_agent_inspector-1.1.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ai-agent-inspector
-Version: 1.0.0
+Version: 1.1.0
 Summary: Framework-agnostic observability for AI agents
 Author-email: Agent Inspector Team <team@agentinspector.dev>
 License: MIT
@@ -27,6 +27,7 @@ Requires-Dist: uvicorn[standard]>=0.24.0
 Requires-Dist: cryptography>=41.0.0
 Requires-Dist: jinja2>=3.1.0
 Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: openai>=2.16.0
 Provides-Extra: langchain
 Requires-Dist: langchain>=0.1.0; extra == "langchain"
 Provides-Extra: otel
@@ -154,7 +155,7 @@ Traditional tools model systems as function calls and spans. Agent Inspector mod
 
 ### Storage
 - **SQLite** – WAL mode for concurrent access; runs and steps tables; indexes on run_id and timestamp.
-- **Pruning** – CLI `prune --retention-days N` and optional `--vacuum`; API/DB support for retention.
+- **Pruning** – CLI `prune --retention-days N` and optional `--retention-max-bytes BYTES`, `--vacuum`; API/DB support for retention by age and by size.
 - **Backup** – CLI `backup /path/to/backup.db` for full DB copy.
 - **Export to JSON** – **API** `GET /v1/runs/{run_id}/export` returns run metadata + timeline with decoded event data; **CLI** `agent-inspector export <run_id> [--output file.json]` and `agent-inspector export --all [--limit N] [--output file.json]` for backup or migration.
 
@@ -506,6 +507,7 @@ export TRACE_ENCRYPTION_KEY=your-secret-key-here
 # Storage
 export TRACE_DB_PATH=agent_inspector.db
 export TRACE_RETENTION_DAYS=30
+export TRACE_RETENTION_MAX_BYTES=
 
 # API
 export TRACE_API_HOST=127.0.0.1
@@ -604,24 +606,78 @@ search_flights_agent("Find flights from SFO to JFK")
 This example makes real LLM calls and runs multiple scenarios.
 
 ```bash
-cp .env.example .env
+cp examples/.env.example examples/.env
 ```
 
-Set these in `.env`:
-- `OPENAI_BASE_URL`
-- `OPENAI_API_KEY`
-- `OPENAI_MODEL`
+Set these in `examples/.env`:
+- `OPENAI_API_KEY` - Your API key
+- `OPENAI_BASE_URL` - API endpoint (e.g., `https://api.openai.com/v1` or your custom provider)
+- `OPENAI_MODEL` - Model name (e.g., `gpt-4o-mini`, `glm-4.7`)
+- `OPENAI_TEMPERATURE` - Temperature setting (default: 0.2)
+- `OPENAI_TIMEOUT` - Timeout in seconds (default: 120)
+
+Install dependencies:
+```bash
+uv add openai python-dotenv
+```
 
 Run a single question:
 ```bash
-python examples/real_agent.py "What is 13 * (7 + 5)?"
+uv run python examples/real_agent.py "What is 13 * (7 + 5)?"
 ```
 
 Run the full scenario suite:
 ```bash
-python examples/real_agent.py --suite
+uv run python examples/real_agent.py --suite
+```
+
+### Multi-Agent Example
+
+This example demonstrates a realistic multi-agent customer support system with:
+- **Agent spawning** with different models per agent
+- **Intelligent routing** to specialized agents (billing, technical, triage, manager)
+- **Tool execution** with realistic operations (profile lookup, billing history, system logs)
+- **Agent communication** with handoffs for escalations
+- **Detailed responses** with contextual, professional customer service replies
+- **Escalation workflow** where complex issues get manager oversight
+
+```bash
+cp examples/.env.example examples/.env
+```
+
+Configure in `examples/.env`:
+- `OPENAI_API_KEY` - Your API key
+- `OPENAI_BASE_URL` - API endpoint
+- `OPENAI_MODEL` - Default model for all agents
+- `MODEL_TRIAGE` - Model for triage agent (optional, falls back to `OPENAI_MODEL`)
+- `MODEL_BILLING` - Model for billing agent (optional)
+- `MODEL_TECHNICAL` - Model for technical agent (optional)
+- `MODEL_MANAGER` - Model for manager agent (optional)
+
+Install dependencies:
+```bash
+uv add openai python-dotenv
+```
+
+Run in simulated mode (no API needed):
+```bash
+python examples/multi_agent.py
 ```
 
+Run with real LLM calls:
+```bash
+uv run python examples/multi_agent.py
+```
+
+The example traces:
+- Customer requests with routing analysis
+- Agent-specific tool usage with realistic results
+- Detailed, contextual responses for each customer issue
+- Escalation flows with manager handoffs
+- Task assignment and completion tracking
+
+Note: Without `openai` package and valid API key, this example will use simulated responses with realistic agent behavior. Install `openai` with `uv add openai` and configure `OPENAI_API_KEY` in `examples/.env` for real LLM calls. Use `uv run python` to execute the script with uv's virtual environment.
+
 ### With LangChain (Automatic)
 
 ```python
@@ -716,6 +772,30 @@ with trace.run("planning_agent", user_id="user123") as main_ctx:
     trace.final(answer="I've booked your flight. Confirmation: CONF-12345")
 ```
 
+### Async / asyncio
+
+Context is propagated via `contextvars`, so tracing works with asyncio as long as each task has its own `trace.run()` (one run per task). Do not share a single run across concurrent tasks.
+
+```python
+import asyncio
+from agent_inspector import trace
+
+async def agent_task(name: str, query: str):
+    with trace.run(name):
+        trace.llm(model="gpt-4", prompt=query, response=f"Processed: {query}")
+        trace.final(answer=f"Done: {query}")
+    return name
+
+async def main():
+    results = await asyncio.gather(
+        agent_task("agent_1", "Query A"),
+        agent_task("agent_2", "Query B"),
+    )
+    return results
+
+asyncio.run(main())
+```
+
 ### Memory Operations
 
 ```python
@@ -836,35 +916,41 @@ result = chain.run("Your query", callbacks=callbacks)
 
 ### Creating Custom Adapters
 
-Create a new adapter by extending `BaseCallbackHandler` (for LangChain-like frameworks) or by using the Trace SDK directly:
+Use the Trace SDK directly when your framework has no LangChain-style callback API. Checklist:
+
+1. **Entry point** – Wrap agent execution in `trace.run("run_name")` so there is an active context.
+2. **LLM calls** – Where your framework invokes the model, call `context.llm(model=..., prompt=..., response=...)`.
+3. **Tool calls** – Where tools are executed, call `context.tool(tool_name=..., tool_args=..., tool_result=...)`.
+4. **Final answer** – When the agent finishes, call `context.final(answer=...)`.
+5. **Errors** – On failure, call `context.error(error_type=..., error_message=..., critical=...)`.
+
+Template:
 
 ```python
-from agent_inspector import Trace, get_trace
+from agent_inspector import trace, get_trace
 
 class CustomAdapter:
-    def __init__(self, trace: Trace = None):
-        self.trace = trace or get_trace()
-    
-    def on_llm_call(self, model, prompt, response):
-        """Handle LLM calls in your framework."""
+    def __init__(self, trace_instance=None):
+        self.trace = trace_instance or get_trace()
+
+    def on_llm_call(self, model: str, prompt: str, response: str):
         context = self.trace.get_active_context()
         if context:
             context.llm(model=model, prompt=prompt, response=response)
-    
-    def on_tool_call(self, tool_name, args, result):
-        """Handle tool calls in your framework."""
+
+    def on_tool_call(self, tool_name: str, tool_args: dict, tool_result: str):
         context = self.trace.get_active_context()
         if context:
-            context.tool(tool_name=tool_name, tool_args=args, tool_result=result)
+            context.tool(tool_name=tool_name, tool_args=tool_args, tool_result=tool_result)
 
-# Use your adapter
-with trace.run("custom_agent"):
+# Use: always run inside trace.run() so get_active_context() returns a context
+with trace.run("my_agent"):
     adapter = CustomAdapter()
-    
-    # Your framework code
     adapter.on_llm_call("gpt-4", "Hello", "Hi there!")
 ```
 
+For LangChain-like frameworks, extend `BaseCallbackHandler` and pass the handler into the framework's callback list; see the LangChain adapter source for the pattern.
+
 ---
 
 ## Development
@@ -952,8 +1038,12 @@ Releases are automated with [Release Please](https://github.com/googleapis/relea
 - **fix:** – bug fix (bumps patch version)
 - **feat!:** or **BREAKING CHANGE:** – breaking change (bumps major version)
 
+To force a specific version, add `Release-As: X.Y.Z` in the commit message footer (e.g. `Release-As: 1.1.0`).
+
 When you merge the Release PR, a tag is created and the [publish workflow](.github/workflows/publish.yml) publishes to PyPI (OIDC).
 
+**First release:** Release Please only creates Release PRs for commits *since* the latest release. If you have no release yet, create the initial tag so it has a baseline: `git tag v1.0.0 && git push origin v1.0.0`. After that, new `feat:`/`fix:` commits (not `docs:` or `chore:`) will get Release PRs.
+
 ---
 
 ## Contributing
@@ -1011,8 +1101,8 @@ agent-inspector server [--host HOST] [--port PORT]
 # View statistics
 agent-inspector stats
 
-# Prune old traces
-agent-inspector prune [--retention-days N] [--vacuum]
+# Prune old traces (optionally by size: --retention-max-bytes BYTES)
+agent-inspector prune [--retention-days N] [--retention-max-bytes BYTES] [--vacuum]
 
 # Vacuum database
 agent-inspector vacuum
@@ -1047,6 +1137,12 @@ Agent Inspector is designed for minimal overhead:
 - Background thread: ~5MB (batch processing)
 - Database: Varies with trace volume
 
+### Scaling and alerting
+
+- **Single process / moderate load** – Use the default SQLite storage with sampling and retention (e.g. `retention_days`, optional `retention_max_bytes`). Suitable for one or a few worker processes.
+- **High throughput or many writers** – Use an OTLP or custom exporter to send traces to a central backend (e.g. Jaeger, Tempo, Grafana). The built-in UI and API then serve only that process; aggregate viewing is in your backend.
+- **Alerting** – The SDK does not push alerts. Use the API from your own checks: e.g. `GET /v1/stats` for `failed_runs`, `recent_runs_24h`, or `queue.events_dropped` (when the default Trace is in use), and alert when thresholds are exceeded. Optionally run `agent-inspector prune` on a schedule to enforce retention.
+
 ---
 
 ## Security

ai_agent_inspector-1.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+agent_inspector/__init__.py,sha256=q8PWgVL74QOWMsyE5aE6xKL8xr8u3tmThDJo1JIINyA,3928
+agent_inspector/cli.py,sha256=tR3ui2jxSs6HVXXEVKGs8IqkPgCKgf4lYrBGUtkc2_g,15563
+agent_inspector/ui/static/app.css,sha256=5THe9xG2n5TEgtp5ShwobwFce-ooMO3sWJLDPKmi7UM,25711
+agent_inspector/ui/static/app.js,sha256=ne6syJFigqaN6sA-vIXgUTSAOwokleY05MwJRxhsk88,14295
+agent_inspector/ui/templates/index.html,sha256=J3fXKyNtGGbGXCrNW7B1Kk0vzJkuN--s_QjVKAeqz70,33587
+ai_agent_inspector-1.1.0.dist-info/licenses/LICENSE,sha256=fRG0znlBiye1MRIjV0JpD1hDVOiccO-9sjeOb48uxV8,1067
+ai_agent_inspector-1.1.0.dist-info/METADATA,sha256=0v3ThZqcrkIfo6inDHHBwF8tmMkVmOU5gQ4Vx3LDw6o,34821
+ai_agent_inspector-1.1.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+ai_agent_inspector-1.1.0.dist-info/entry_points.txt,sha256=LyvLcPfU8saSv9e890NSI3_FyhJswXudbQfVqchIz7E,61
+ai_agent_inspector-1.1.0.dist-info/top_level.txt,sha256=LW8u7mUPBH1BjmzTlh7qKB7-A-QyLyLxxBy02k5cnS4,16
+ai_agent_inspector-1.1.0.dist-info/RECORD,,

ai_agent_inspector-1.0.0.dist-info/RECORD

@@ -1,11 +0,0 @@
-agent_inspector/__init__.py,sha256=7h5ivS0cDhosGYHe50te--n11CSuSHkXh7B4fiPMKxY,3256
-agent_inspector/cli.py,sha256=oCnKFi0nn0fnPFMJPcNYZA6Y7CbyUEfes4mdN0X-aSE,14741
-agent_inspector/ui/static/app.css,sha256=KDvffC-CHFk4pdnr8Cboy0xgprFXYZeKstV_8NIMgMw,16491
-agent_inspector/ui/static/app.js,sha256=ne6syJFigqaN6sA-vIXgUTSAOwokleY05MwJRxhsk88,14295
-agent_inspector/ui/templates/index.html,sha256=0Jq7wF1o6jGqS-15139yFEuG8rAWfb3XH7f-bHWXL9c,16630
-ai_agent_inspector-1.0.0.dist-info/licenses/LICENSE,sha256=fRG0znlBiye1MRIjV0JpD1hDVOiccO-9sjeOb48uxV8,1067
-ai_agent_inspector-1.0.0.dist-info/METADATA,sha256=2DElU-mbKAYMehScwMvYlYyO4Mzsc2OrQ3GI_xEZgRg,29982
-ai_agent_inspector-1.0.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
-ai_agent_inspector-1.0.0.dist-info/entry_points.txt,sha256=LyvLcPfU8saSv9e890NSI3_FyhJswXudbQfVqchIz7E,61
-ai_agent_inspector-1.0.0.dist-info/top_level.txt,sha256=LW8u7mUPBH1BjmzTlh7qKB7-A-QyLyLxxBy02k5cnS4,16
-ai_agent_inspector-1.0.0.dist-info/RECORD,,