PyPI - agentic-ledger - Versions diffs - 0.2.0__tar.gz → 0.3.0a2__tar.gz - Mend

agentic-ledger 0.2.0tar.gz → 0.3.0a2tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (30) hide show

{agentic_ledger-0.2.0 → agentic_ledger-0.3.0a2}/.gitignore RENAMED Viewed

@@ -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.0a2}/PKG-INFO RENAMED Viewed

@@ -1,10 +1,10 @@
 Metadata-Version: 2.4
 Name: agentic-ledger
-Version: 0.2.0
+Version: 0.3.0a2
 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://github.com/ShekharBhardwaj/AgenticLedger
+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,18 @@ Description-Content-Type: text/markdown
 Runtime observability for AI agents — see exactly what your agent did, why it did it, and what it cost.
+> **Alpha** — `v0.3.0-alpha.1` is an early release of the loop engine, Loop Lens web app, and framework integrations. Interfaces and schema may still change between alpha releases. Found something broken or missing? [Open an issue](https://github.com/ShekharBhardwaj/AgenticLedger/issues/new/choose) — alpha feedback directly shapes what ships next.
 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 +151,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", ...)
 ```
@@ -161,10 +163,15 @@ client = OpenAI(base_url="http://localhost:8000/v1", ...)
 **Step 3 — Open the dashboard**
 ```
-http://localhost:8000
+http://localhost:8000/app
 ```
-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, and a per-iteration table (calls, tokens, cache reads, flags, errors)
+- **Sessions** — every session with expandable call cards: response, thinking, tool calls, tool results, cache tokens, cost, loop flags
+The classic single-file dashboard still lives at `http://localhost:8000`:
 - **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 +180,69 @@ 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:** [BMAD-METHOD](docs/integrations/bmad.md) — persona
+auto-detection (`bmad:sm`, `bmad:dev`, `bmad:qa`, …) and per-story budgets ·
+[OpenClaw](docs/integrations/openclaw.md) — the hard spend cap OpenClaw
+doesn't have, plus per-agent attribution.
+---
 ## What gets captured
 Every LLM call is stored with:
@@ -192,11 +262,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 +290,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 +321,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 +331,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 +379,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 +406,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 +506,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 +524,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 +576,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 +590,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 +619,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
@@ -569,7 +661,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 +755,7 @@ This runs three jobs:
    ```
    PyPI project name:  agentic-ledger
    Owner:              ShekharBhardwaj
-   Repository:         AgentLedger
+   Repository:         AgenticLedger
    Workflow name:      release.yml
    Environment name:   pypi
    ```

{agentic_ledger-0.2.0 → agentic_ledger-0.3.0a2}/README.md RENAMED Viewed

@@ -1,7 +1,7 @@
-# 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)
@@ -9,16 +9,18 @@
 Runtime observability for AI agents — see exactly what your agent did, why it did it, and what it cost.
+> **Alpha** — `v0.3.0-alpha.1` is an early release of the loop engine, Loop Lens web app, and framework integrations. Interfaces and schema may still change between alpha releases. Found something broken or missing? [Open an issue](https://github.com/ShekharBhardwaj/AgenticLedger/issues/new/choose) — alpha feedback directly shapes what ships next.
 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
                       ↓
@@ -107,10 +109,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", ...)
 ```
@@ -119,10 +121,15 @@ client = OpenAI(base_url="http://localhost:8000/v1", ...)
 **Step 3 — Open the dashboard**
 ```
-http://localhost:8000
+http://localhost:8000/app
 ```
-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, and a per-iteration table (calls, tokens, cache reads, flags, errors)
+- **Sessions** — every session with expandable call cards: response, thinking, tool calls, tool results, cache tokens, cost, loop flags
+The classic single-file dashboard still lives at `http://localhost:8000`:
 - **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.
@@ -131,6 +138,69 @@ 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:** [BMAD-METHOD](docs/integrations/bmad.md) — persona
+auto-detection (`bmad:sm`, `bmad:dev`, `bmad:qa`, …) and per-story budgets ·
+[OpenClaw](docs/integrations/openclaw.md) — the hard spend cap OpenClaw
+doesn't have, plus per-agent attribution.
+---
 ## What gets captured
 Every LLM call is stored with:
@@ -150,11 +220,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 |
@@ -175,13 +248,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
@@ -202,7 +279,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:**
@@ -212,6 +289,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
@@ -258,7 +337,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. |
@@ -285,6 +364,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 |
@@ -375,7 +464,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.
 ---
@@ -393,6 +482,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
@@ -442,7 +534,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
@@ -456,7 +548,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 = {
@@ -485,7 +577,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
@@ -527,7 +619,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
@@ -621,7 +713,7 @@ This runs three jobs:
    ```
    PyPI project name:  agentic-ledger
    Owner:              ShekharBhardwaj
-   Repository:         AgentLedger
+   Repository:         AgenticLedger
    Workflow name:      release.yml
    Environment name:   pypi
    ```

{agentic_ledger-0.2.0 → agentic_ledger-0.3.0a2}/agentledger/__init__.py RENAMED Viewed

@@ -1,5 +1,5 @@
 """
-AgentLedger — runtime observability for AI agents.
+Agentic Ledger — runtime observability for AI agents.
 Run as a proxy:
     python -m agentledger.proxy

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

agentic-ledger 0.2.0tar.gz → 0.3.0a2tar.gz