agentic-ledger 0.2.0__tar.gz → 0.3.0__tar.gz

{agentic_ledger-0.2.0 → agentic_ledger-0.3.0}/.gitignore

@@ -41,3 +41,7 @@ coverage.xml
 
 # Jupyter
 .ipynb_checkpoints/
+
+# Web app (dashboard-app builds into agentledger/proxy/static/)
+dashboard-app/node_modules/
+agentledger/proxy/static/

{agentic_ledger-0.2.0 → agentic_ledger-0.3.0}/PKG-INFO

@@ -1,10 +1,10 @@
 Metadata-Version: 2.4
 Name: agentic-ledger
-Version: 0.2.0
+Version: 0.3.0
 Summary: Runtime observability for AI agents — see exactly what your agent did, why it did it, and what it cost.
-Project-URL: Homepage, https://github.com/ShekharBhardwaj/AgentLedger
-Project-URL: Repository, https://github.com/ShekharBhardwaj/AgentLedger
-Project-URL: Issues, https://github.com/ShekharBhardwaj/AgentLedger/issues
+Project-URL: Homepage, https://agentic-ledger.dev
+Project-URL: Repository, https://github.com/ShekharBhardwaj/AgenticLedger
+Project-URL: Issues, https://github.com/ShekharBhardwaj/AgenticLedger/issues
 Author: Shekhar Bhardwaj
 License-Expression: MIT
 License-File: LICENSE
@@ -21,7 +21,7 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.10
 Requires-Dist: aiosqlite>=0.19
 Requires-Dist: fastapi>=0.110
-Requires-Dist: httpx>=0.27
+Requires-Dist: httpx<1.0.dev0,>=0.27
 Requires-Dist: uvicorn[standard]>=0.29
 Provides-Extra: dev
 Requires-Dist: aiosqlite>=0.19; extra == 'dev'
@@ -40,10 +40,10 @@ Provides-Extra: postgres
 Requires-Dist: asyncpg>=0.29; extra == 'postgres'
 Description-Content-Type: text/markdown
 
-# AgentLedger
+# Agentic Ledger
 
-[![CI](https://github.com/ShekharBhardwaj/AgentLedger/actions/workflows/ci.yml/badge.svg)](https://github.com/ShekharBhardwaj/AgentLedger/actions/workflows/ci.yml)
-[![CodeQL](https://github.com/ShekharBhardwaj/AgentLedger/actions/workflows/codeql.yml/badge.svg)](https://github.com/ShekharBhardwaj/AgentLedger/actions/workflows/codeql.yml)
+[![CI](https://github.com/ShekharBhardwaj/AgenticLedger/actions/workflows/ci.yml/badge.svg)](https://github.com/ShekharBhardwaj/AgenticLedger/actions/workflows/ci.yml)
+[![CodeQL](https://github.com/ShekharBhardwaj/AgenticLedger/actions/workflows/codeql.yml/badge.svg)](https://github.com/ShekharBhardwaj/AgenticLedger/actions/workflows/codeql.yml)
 [![PyPI](https://img.shields.io/pypi/v/agentic-ledger)](https://pypi.org/project/agentic-ledger/)
 [![Python versions](https://img.shields.io/pypi/pyversions/agentic-ledger)](https://pypi.org/project/agentic-ledger/)
 [![Docker](https://img.shields.io/badge/docker-ghcr.io-blue)](https://ghcr.io/shekharbhardwaj/agentledger)
@@ -51,16 +51,20 @@ Description-Content-Type: text/markdown
 
 Runtime observability for AI agents — see exactly what your agent did, why it did it, and what it cost.
 
+**Website:** [agentic-ledger.dev](https://agentic-ledger.dev)
+
+> The numbers are meant to match your provider bill. If they don't, [that's a bug we want](https://github.com/ShekharBhardwaj/AgenticLedger/issues/new/choose).
+
 Works with **any agent framework**, **any LLM provider**, **any model gateway**. Zero code changes required. Point your agent at the proxy and everything is captured automatically.
 
 ---
 
 ## How it works
 
-AgentLedger runs as a transparent proxy between your agent and the LLM provider. It intercepts every request and response, assigns it an `action_id`, stores it, and returns the upstream response unmodified. Your agent never knows the proxy is there.
+Agentic Ledger runs as a transparent proxy between your agent and the LLM provider. It intercepts every request and response, assigns it an `action_id`, stores it, and returns the upstream response unmodified. Your agent never knows the proxy is there.
 
 ```
-Your Agent  →  AgentLedger Proxy  →  OpenAI / Anthropic / LiteLLM / any LLM
+Your Agent  →  Agentic Ledger Proxy  →  OpenAI / Anthropic / LiteLLM / any LLM
                       ↓
                SQLite or Postgres
                       ↓
@@ -149,10 +153,10 @@ client = anthropic.Anthropic(
 
 **LiteLLM / OpenRouter / any gateway:**
 ```bash
-# Point AgentLedger at your gateway
+# Point Agentic Ledger at your gateway
 AGENTLEDGER_UPSTREAM_URL=http://localhost:4000 uv run python -m agentledger.proxy
 
-# Then point your agent at AgentLedger
+# Then point your agent at Agentic Ledger
 client = OpenAI(base_url="http://localhost:8000/v1", ...)
 ```
 
@@ -164,7 +168,13 @@ client = OpenAI(base_url="http://localhost:8000/v1", ...)
 http://localhost:8000
 ```
 
-The dashboard updates live via WebSocket as calls come in. No refresh needed.
+The web app updates live via WebSocket as calls come in. No refresh needed.
+
+- **Loop Lens** — every loop run with status (`running` / `flagged` / `complete`), a cost-per-iteration chart, per-iteration breakdowns, and plain-English explanations of every flag
+- **Sessions** — every session with three views: expandable call cards (response, thinking, tool calls, cache tokens, interaction badges), a **Flow** DAG of agent handoffs, and a **Trace** waterfall with real parent links from the loop engine
+- **Search** — full-text across prompts, outputs, and agents
+
+The classic single-file dashboard remains at `http://localhost:8000/classic`:
 
 - **Calls tab** — every LLM call with full prompt, system prompt, tool calls, tool results, output, tokens, cost, latency, and errors
 - **Flow tab** — visual DAG of your multi-agent system. Each agent is a node with aggregated cost, latency, and call count. Edges represent handoffs. Click a node to highlight its calls.
@@ -173,6 +183,70 @@ The dashboard updates live via WebSocket as calls come in. No refresh needed.
 
 ---
 
+## Coding agents — Claude Code, Ralph loops & friends
+
+Claude Code (and most coding agents) can be pointed at the proxy with a single
+environment variable — no headers, no code changes:
+
+```bash
+AGENTLEDGER_UPSTREAM_URL=https://api.anthropic.com uv run python -m agentledger.proxy
+```
+
+```bash
+export ANTHROPIC_BASE_URL=http://localhost:8000
+claude
+```
+
+Agentic Ledger fingerprints Claude Code traffic automatically: every call is
+tagged `framework=claude-code`, and instead of one undifferentiated bucket,
+each Claude Code session appears under its **real session UUID** (the same id
+`claude --resume` shows), with prompt-cache reads/writes captured and priced
+correctly — cache traffic is where most of a coding agent's real spend lives.
+
+Running an overnight loop (Ralph-style `while :; do cat PROMPT.md | claude -p; done`)?
+Use the built-in loop runner — it re-executes your command each iteration,
+attributes every call to the run (via the base URL, no headers needed), and
+stops on a completion promise, a budget ceiling, or the iteration cap:
+
+```bash
+AGENTLEDGER_UPSTREAM_URL=https://api.anthropic.com \
+AGENTLEDGER_COMPLETION_PROMISE="ALL TASKS COMPLETE" \
+uv run python -m agentledger.proxy
+```
+
+```bash
+agentledger run --max-iterations 50 --budget 25 -- \
+  claude -p "$(cat PROMPT.md)" --dangerously-skip-permissions
+```
+
+Each iteration shows up as *iteration N of the run* in `/api/runs`; when the
+agent prints the completion promise in a response, run status flips to
+`complete` and the loop exits with a cost/token summary. Any existing loop
+script works too — poll `GET /api/runs/{run_id}` yourself, or let the proxy's
+budgets (`AGENTLEDGER_BUDGET_DAILY=25.00`) hard-stop a runaway loop.
+
+The same recipe works for any client with a base-URL override (Codex CLI,
+opencode, OpenClaw, LiteLLM-based stacks) — set the OpenAI/Anthropic base URL
+to the proxy and traffic is captured; add `x-agentledger-*` headers when you
+want explicit attribution.
+
+**OTel-native tools** (Gemini CLI, Codex `[otel]`, AutoGen/AG2, Pydantic AI,
+Vercel AI SDK) don't need the proxy at all — point their OTLP exporter at the
+ledger and GenAI spans are ingested directly:
+
+```bash
+export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:8000
+export OTEL_EXPORTER_OTLP_PROTOCOL=http/json
+```
+
+**Framework guides** — one per integration in
+[docs/integrations](docs/integrations/README.md): Claude Code, Codex CLI,
+opencode, OpenClaw, BMAD-METHOD, LangGraph/LangChain, CrewAI, OpenAI Agents
+SDK, Gemini CLI, AutoGen/AG2, Pydantic AI, Vercel AI SDK, LiteLLM, and
+OpenRouter.
+
+---
+
 ## What gets captured
 
 Every LLM call is stored with:
@@ -192,11 +266,14 @@ Every LLM call is stored with:
 | `content` | Model's text output |
 | `stop_reason` | Why the model stopped |
 | `tokens_in` / `tokens_out` | Token usage |
+| `cache_read_tokens` / `cache_write_tokens` | Prompt-cache usage — reads and writes are priced correctly per provider |
+| `thinking` | Extended-thinking output (Anthropic), captured separately from `content` |
 | `cost_usd` | Estimated cost based on model pricing |
 | `latency_ms` | End-to-end response time |
 | `status_code` | HTTP status from upstream — errors are captured too |
 | `error_detail` | Upstream error message for non-200 responses |
-| `agent_name` | From `x-agentledger-agent-name` header |
+| `agent_name` | From `x-agentledger-agent-name` header, or auto-detected (e.g. `claude-code`) |
+| `framework` | From `x-agentledger-framework` header, or fingerprint-detected (e.g. `claude-code`, `litellm`) |
 | `user_id` | From `x-agentledger-user-id` header |
 | `app_id` | From `x-agentledger-app-id` header |
 | `environment` | From `x-agentledger-environment` header |
@@ -217,13 +294,17 @@ Every LLM call is stored with:
 | `GET` | `/` | Live dashboard |
 | `WS` | `/ws` | WebSocket stream — powers live dashboard updates |
 | `GET` | `/api/sessions` | List recent sessions with aggregated stats |
+| `GET` | `/api/runs` | List loop runs (explicit or auto-inferred) with iterations, cost, status, and flagged-call counts |
+| `GET` | `/api/runs/{run_id}` | One run's status (`running` / `flagged` / `complete`) — poll this from loop scripts |
+| `GET` | `/api/sessions/{session_id}/tools` | Derived tool executions — each tool call paired with its result, latency, and error status |
 | `DELETE` | `/api/sessions/{session_id}` | Delete a session and all its calls |
 | `GET` | `/api/search?q=...` | Full-text search across all captured calls |
 | `GET` | `/session/{session_id}` | All calls in a session, ordered by time |
 | `GET` | `/explain/{action_id}` | Single call by action ID |
 | `GET` | `/export/{session_id}` | JSON compliance export with SHA-256 integrity hash |
 | `GET` | `/export/{session_id}/report` | Printable HTML audit report |
-| `POST` | `/mcp` | MCP tool server — `list_sessions`, `explain`, `get_session`, `search` |
+| `POST` | `/mcp` | MCP tool server — `list_sessions`, `explain`, `get_session`, `search`, `list_runs`, `get_run_status` |
+| `POST` | `/v1/traces` | OTLP/HTTP JSON ingest — GenAI spans from OTel-native tools become ledger calls (`/v1/logs`, `/v1/metrics` acked) |
 
 **Examples:**
 ```bash
@@ -244,7 +325,7 @@ open http://localhost:8000/export/run-1/report
 
 ## MCP server
 
-AgentLedger exposes its captured data as an MCP (Model Context Protocol) tool server at `POST /mcp`. Point Claude Desktop, Cursor, or any MCP-compatible client at it to query traces directly from your AI assistant.
+Agentic Ledger exposes its captured data as an MCP (Model Context Protocol) tool server at `POST /mcp`. Point Claude Desktop, Cursor, or any MCP-compatible client at it to query traces directly from your AI assistant.
 
 **Tools available:**
 
@@ -254,6 +335,8 @@ AgentLedger exposes its captured data as an MCP (Model Context Protocol) tool se
 | `explain(action_id)` | Full trace for a single LLM call — prompt, tool calls, output, tokens, cost |
 | `get_session(session_id)` | All calls in a session in chronological order |
 | `search(query)` | Full-text search across all captured calls |
+| `list_runs` | Loop runs with iterations, cost, and status |
+| `get_run_status(run_id)` | One run's status — lets an agent inspect its own loop and decide whether to continue |
 
 **Configure in `claude_desktop_config.json`:**
 ```json
@@ -300,7 +383,7 @@ Once connected, you can ask your assistant things like:
 | `AGENTLEDGER_API_KEY` | No | _(none)_ | Master admin key. When set, the dashboard, read, and management endpoints require authentication; the key grants the `admin` role and bootstraps API tokens (below). Skip for local dev; set when the proxy is on a server — you choose the value. |
 | `AGENTLEDGER_INGEST_KEY` | No | _(none)_ | When set, the proxy forwards a request only if it carries a matching `x-agentledger-ingest-key` header — closing the open relay. Off by default; a loud startup warning fires when unset. |
 | `AGENTLEDGER_EXPORT_HMAC_KEY` | No | _(none)_ | When set, compliance exports carry a tamper-evident keyed `hmac-sha256` integrity tag instead of a plain `sha256` checksum. |
-| `AGENTLEDGER_EXTRA_PATHS` | No | _(none)_ | Comma-separated additional request paths to capture, e.g. `v1/responses,v1/custom`. Built-in paths (`v1/chat/completions`, `v1/messages`, `v1/responses`) are always captured. |
+| `AGENTLEDGER_EXTRA_PATHS` | No | _(none)_ | Comma-separated additional request paths to capture, e.g. `v1/responses,v1/custom`. Built-in paths (`v1/chat/completions`, `v1/messages`, `v1/responses`, plus `v1/messages/count_tokens` recorded as a free call) are always captured. |
 | `AGENTLEDGER_ASYNC_CAPTURE` | No | `off` | Persist captures on a background worker so storage never adds latency to the agent's call. Trade-off: reads become **eventually consistent** (a just-captured call may not be queryable for a brief moment). Recommended for high throughput. |
 | `AGENTLEDGER_CAPTURE_QUEUE_MAX` | No | `10000` | Max captures buffered in async mode before load is shed (drops are counted in `/metrics`). |
 | `AGENTLEDGER_CAPTURE_LEVEL` | No | `full` | `full` stores everything; `metadata` stores only metrics/metadata (model, tokens, cost, latency, agent, status) and drops prompts, responses, and tools. |
@@ -327,6 +410,16 @@ Once connected, you can ask your assistant things like:
 | `AGENTLEDGER_RATE_LIMIT_AGENT_RPM` | _(none)_ | Max requests per minute per `agent_name`. |
 | `AGENTLEDGER_RATE_LIMIT_USER_RPM` | _(none)_ | Max requests per minute per `user_id`. |
 
+**Loop engine** — every call is stitched into ReAct threads (`thread_id`, `step_index`, `prev_action_id`) and fresh-context loop iterations are grouped into runs, with stuck-loop detection:
+
+| Variable | Default | Description |
+|---|---|---|
+| `AGENTLEDGER_LOOP_ACTION` | `warn` | `warn` records `loop_flags` and fires a `loop_flag` webhook alert; `block` additionally returns HTTP 429 (`loop_detected`) for a session that tripped a guard; `off` disables inference. |
+| `AGENTLEDGER_LOOP_REPEAT_THRESHOLD` | `3` | Consecutive identical tool calls (same tool, same arguments) before a thread is flagged stuck. |
+| `AGENTLEDGER_LOOP_MAX_STEPS` | _(none)_ | Flag (and in block mode, stop) threads that exceed this many ReAct steps. |
+| `AGENTLEDGER_LOOP_RUN_GAP_SECONDS` | `900` | Max gap between fresh-context spawns (same system prompt) that still count as iterations of one run. |
+| `AGENTLEDGER_COMPLETION_PROMISE` | _(none)_ | Regex matched against response text. On match the call is flagged `completion_promise` and the run's status becomes `complete` — loop runners poll `GET /api/runs/{run_id}` and stop. |
+
 **Alerts** — POST to your webhook when a threshold is breached (does not block calls — see [Alerts](#alerts)):
 
 | Variable | Default | Description |
@@ -417,7 +510,7 @@ curl -H "x-agentledger-api-key: my-secret" http://localhost:8000/api/tokens
 curl -X DELETE -H "x-agentledger-api-key: my-secret" http://localhost:8000/api/tokens/<token_id>
 ```
 
-> Auth is enforced only when `AGENTLEDGER_API_KEY` is set; the master key is the admin bootstrap for minting tokens. (Dashboard credential propagation over the live `/ws` feed is tracked as follow-up — see `ROADMAP.md`.)
+> Auth is enforced only when `AGENTLEDGER_API_KEY` is set; the master key is the admin bootstrap for minting tokens. The live `/ws` feed accepts the same credentials (`?api_key=`, `?token=`, `Authorization: Bearer`, or `x-agentledger-token`) and rejects unauthenticated connects with close code 1008 — the dashboard forwards its page credential to the socket automatically.
 
 ---
 
@@ -435,6 +528,9 @@ Pass these from your agent on each LLM call. All optional. They enrich captured
 | `x-agentledger-environment` | `development` | `production`, `staging`, or `development`. Shown in the dashboard. |
 | `x-agentledger-handoff-from` | _(none)_ | Agent handing off control (e.g. `"orchestrator"`). Renders as a directed edge in the Flow DAG. |
 | `x-agentledger-handoff-to` | _(none)_ | Agent receiving control (e.g. `"researcher"`). Renders as a directed edge in the Flow DAG. |
+| `x-agentledger-framework` | _(auto-detected)_ | Framework/tool making the call (e.g. `"langgraph"`, `"bmad"`). When absent, well-known clients are fingerprinted automatically (Claude Code, LiteLLM). |
+| `x-agentledger-run-id` | _(auto-inferred)_ | Groups sessions into a loop run (e.g. a Ralph overnight run). When absent, fresh-context sessions sharing a system prompt within `AGENTLEDGER_LOOP_RUN_GAP_SECONDS` are grouped automatically. |
+| `x-agentledger-iteration` | _(auto-inferred)_ | Iteration number within the run. |
 
 **Single agent — fully annotated:**
 ```python
@@ -484,7 +580,7 @@ The Flow tab renders `orchestrator → researcher` as a DAG with cost and latenc
 
 **OpenAI Agents SDK (`openai-agents`) — per-agent clients:**
 
-The `openai-agents` SDK uses its own internal OpenAI client. To pass AgentLedger headers you need to create a client per agent using `OpenAIResponsesModel` and set it as the agent's `model`.
+The `openai-agents` SDK uses its own internal OpenAI client. To pass Agentic Ledger headers you need to create a client per agent using `OpenAIResponsesModel` and set it as the agent's `model`.
 
 ```python
 import uuid
@@ -498,7 +594,7 @@ BASE_URL = os.getenv("OPENAI_BASE_URL")      # e.g. http://localhost:8000/v1
 
 def al_model(agent_name: str, model: str = "gpt-4o-mini",
              handoff_from: str | None = None, handoff_to: str | None = None):
-    """Create a model instance that sends AgentLedger metadata headers."""
+    """Create a model instance that sends Agentic Ledger metadata headers."""
     if not BASE_URL:
         return model  # proxy not configured — use default client
     headers = {
@@ -527,7 +623,7 @@ Each agent's calls are tagged with its name and pipeline position. The Flow tab
 
 ## Alerts
 
-AgentLedger fires a `POST` to your webhook URL when a threshold is breached. You connect it to whatever you already use — Slack, PagerDuty, Discord, email, or a custom endpoint. AgentLedger sends the payload; the integration is on your side.
+Agentic Ledger fires a `POST` to your webhook URL when a threshold is breached. You connect it to whatever you already use — Slack, PagerDuty, Discord, email, or a custom endpoint. Agentic Ledger sends the payload; the integration is on your side.
 
 **Payload format:**
 ```json
@@ -552,6 +648,8 @@ AgentLedger fires a `POST` to your webhook URL when a threshold is breached. You
 | `high_error_rate` | Session error rate exceeds `AGENTLEDGER_ALERT_ERROR_RATE` |
 | `daily_spend` | Daily total spend crosses `AGENTLEDGER_ALERT_DAILY_SPEND` |
 | `budget_exceeded` | A budget limit is hit and `AGENTLEDGER_BUDGET_ACTION` is `warn` or `both` |
+| `loop_flag` | The loop engine raised flags on a call (`repeat_tool_call`, `step_budget_exceeded`, `completion_promise`) |
+| `run_complete` | A run's completion promise was seen — the payload carries the full run summary (iterations, cost, tokens, flagged calls) |
 
 **Budgets vs alerts:**
 - **Budgets** (`AGENTLEDGER_BUDGET_*`) — block the call before it reaches the LLM. Agent gets HTTP 429.
@@ -569,7 +667,7 @@ AgentLedger fires a `POST` to your webhook URL when a threshold is breached. You
 
 ## OpenTelemetry export
 
-AgentLedger can emit every intercepted LLM call as an OTel span to any OTLP-compatible collector: Grafana Tempo, Jaeger, Honeycomb, Datadog, Dynatrace, or any vendor that supports OTLP/HTTP.
+Agentic Ledger can emit every intercepted LLM call as an OTel span to any OTLP-compatible collector: Grafana Tempo, Jaeger, Honeycomb, Datadog, Dynatrace, or any vendor that supports OTLP/HTTP.
 
 **Install the extra** (Docker image includes OTel — no extra step needed when using Docker):
 ```bash
@@ -663,7 +761,7 @@ This runs three jobs:
    ```
    PyPI project name:  agentic-ledger
    Owner:              ShekharBhardwaj
-   Repository:         AgentLedger
+   Repository:         AgenticLedger
    Workflow name:      release.yml
    Environment name:   pypi
    ```
@@ -672,6 +770,35 @@ This runs three jobs:
 
 ---
 
+## Troubleshooting
+
+**`incompatible architecture (have 'arm64', need 'x86_64')`** on macOS — your
+terminal is running under Rosetta, so Python picks its x86_64 slice while pip
+installed arm64 native wheels. Check with `arch` (should print `arm64` on
+Apple Silicon). Quick fix: prefix the command with `arch -arm64`. Permanent
+fix: uncheck "Open using Rosetta" on your terminal app, use an Apple Silicon
+build of your editor, and restart any long-lived `tmux` server.
+
+**`module 'httpx' has no attribute 'AsyncClient'`** — fixed in
+`0.3.0-alpha.2`; upgrade with `pip install --upgrade agentic-ledger`.
+
+**Port 8000 already in use** — another proxy instance (or app) is running;
+stop it or set `AGENTLEDGER_PORT`.
+
+**`401 OAuth access token has expired` from Claude Code** — the proxy passed
+Anthropic's answer through unmodified; re-authenticate with `claude` →
+`/login`. Errored calls are still captured, so you'll see the 401 in the
+dashboard.
+
+**`/` shows the classic dashboard instead of the web app** — you're running
+from a source checkout without the web-app build. `cd dashboard-app && npm ci
+&& npm run build` and restart. PyPI and Docker installs always include the app.
+
+---
+
 ## License
 
 MIT
+
+<!-- MCP registry ownership verification -->
+`mcp-name: io.github.shekharbhardwaj/agentic-ledger`