windhover 0.14.2__tar.gz → 0.14.3__tar.gz

{windhover-0.14.2 → windhover-0.14.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: windhover
-Version: 0.14.2
+Version: 0.14.3
 Summary: Self-hosted, mobile-friendly observability for LangGraph — traces, run history, cost, and a living graph view.
 Project-URL: Repository, https://github.com/justfeltlikerunning/windhover
 Author: justfeltlikerunning
@@ -117,6 +117,11 @@ graph.invoke(input, config={
 - **Run history + replay** — SQLite; runs persist even if the browser closes (worker thread).
 - **Living graph** — file watcher re-extracts topology in a subprocess and pushes it to the UI.
 - **Dashboards** — runs/tokens per day, per-model usage and latency, per-node latency, error rate.
+- **Multi-graph** — serve every graph in your project behind one URL; a top-bar selector
+  scopes all views (runs, sessions, stats included — metrics never mix graphs).
+- **Alerts** — `WINDHOVER_WEBHOOK` pushes a JSON summary when a run errors or pauses.
+- **Never slows your app** — the remote tracer is non-blocking (bounded queue; drops
+  rather than delays when the collector is down).
 - **Mobile-first PWA**, light/dark. Fully local (FastAPI + Cytoscape.js).
 
 ## Datasets API
@@ -135,11 +140,13 @@ curl -X POST :8090/api/runs/RUN_ID/scores -H 'Content-Type: application/json' \
 ```
 
 ## Config (env)
-`WINDHOVER_GRAPH` (module:attr; unset = ingest-only) · `WINDHOVER_GRAPH_DIR` · `WINDHOVER_DB`
+`WINDHOVER_GRAPH` (`module:attr`, or a comma list `name=module:attr,…`; unset = langgraph.json
+discovery, else ingest-only) · `WINDHOVER_GRAPH_DIR` · `WINDHOVER_DB`
 · `WINDHOVER_HOST`/`WINDHOVER_PORT` (0.0.0.0/8090) · `WINDHOVER_WATCH` (1) · `WINDHOVER_PRICING`
 · `WINDHOVER_RETENTION_DAYS` (0 = keep forever; else prune older runs on startup + every 6h)
 · `WINDHOVER_TOKEN` (set to require `Authorization: Bearer <token>` — or `?token=` — on all
-`/api` routes; the UI prompts once and remembers it).
+`/api` routes; the UI prompts once and remembers it)
+· `WINDHOVER_WEBHOOK` (POST a JSON alert whenever a run errors or pauses on an interrupt).
 Edit `windhover/pricing.json` for your models' $/1M rates (unknown model → cost null).
 
 ## Docs

{windhover-0.14.2 → windhover-0.14.3}/README.md

@@ -98,6 +98,11 @@ graph.invoke(input, config={
 - **Run history + replay** — SQLite; runs persist even if the browser closes (worker thread).
 - **Living graph** — file watcher re-extracts topology in a subprocess and pushes it to the UI.
 - **Dashboards** — runs/tokens per day, per-model usage and latency, per-node latency, error rate.
+- **Multi-graph** — serve every graph in your project behind one URL; a top-bar selector
+  scopes all views (runs, sessions, stats included — metrics never mix graphs).
+- **Alerts** — `WINDHOVER_WEBHOOK` pushes a JSON summary when a run errors or pauses.
+- **Never slows your app** — the remote tracer is non-blocking (bounded queue; drops
+  rather than delays when the collector is down).
 - **Mobile-first PWA**, light/dark. Fully local (FastAPI + Cytoscape.js).
 
 ## Datasets API
@@ -116,11 +121,13 @@ curl -X POST :8090/api/runs/RUN_ID/scores -H 'Content-Type: application/json' \
 ```
 
 ## Config (env)
-`WINDHOVER_GRAPH` (module:attr; unset = ingest-only) · `WINDHOVER_GRAPH_DIR` · `WINDHOVER_DB`
+`WINDHOVER_GRAPH` (`module:attr`, or a comma list `name=module:attr,…`; unset = langgraph.json
+discovery, else ingest-only) · `WINDHOVER_GRAPH_DIR` · `WINDHOVER_DB`
 · `WINDHOVER_HOST`/`WINDHOVER_PORT` (0.0.0.0/8090) · `WINDHOVER_WATCH` (1) · `WINDHOVER_PRICING`
 · `WINDHOVER_RETENTION_DAYS` (0 = keep forever; else prune older runs on startup + every 6h)
 · `WINDHOVER_TOKEN` (set to require `Authorization: Bearer <token>` — or `?token=` — on all
-`/api` routes; the UI prompts once and remembers it).
+`/api` routes; the UI prompts once and remembers it)
+· `WINDHOVER_WEBHOOK` (POST a JSON alert whenever a run errors or pauses on an interrupt).
 Edit `windhover/pricing.json` for your models' $/1M rates (unknown model → cost null).
 
 ## Docs

{windhover-0.14.2 → windhover-0.14.3}/SPEC.md

@@ -1,4 +1,4 @@
-# Windhover — engineering spec (current as of v0.11)
+# Windhover — engineering spec (current as of v0.14)
 
 Self-hosted LangGraph/LangChain observability + human-in-the-loop console.
 Code is the only source of truth; Windhover observes and, for HITL, drives the
@@ -22,22 +22,36 @@ breakpoints, update_state, checkpoint forking). No visual editing, ever.
 ## Architecture
 - **FastAPI + SSE** (no websockets). Single-file UI (`static/index.html`) +
   vendored cytoscape/dagre/fonts.
+- **Multi-graph registry**: `WINDHOVER_GRAPH` comma list (`name=module:attr`)
+  or every graph in `langgraph.json`; per-graph `Topo` watchers; `graph=`
+  scopes graph/schema/source/memory/threads/stats/sessions/dataset-run;
+  `/api/run` takes `_graph`; run rows store the registry name.
 - **Topology**: subprocess (`windhover.extract`) re-imports the graph on file
   mtime change → nodes/edges (+labels/metadata), input & context schemas,
   per-node source (inspect, unwrapped), x-ray variant; sha1-hash change bumps a
   version pushed over `/api/events` SSE.
-- **Tracer** (`windhover.tracer.SpanBuilder`): chains→node spans (langgraph_node
-  metadata), LLM (params, tools offered, tokens+details, TTFT, streaming
-  partials every ~0.5 s), tools, retrievers, retries, custom events,
-  GraphInterrupt→interrupted, session/tags/run_name/thread_id via config
-  metadata. Best-effort: never raises into the user's graph.
+- **Tracer** (`windhover.tracer.SpanBuilder`): concurrency-safe per-root run
+  contexts (parallel invokes = separate runs; bare llm/tool/retriever calls
+  open implicit runs; bookkeeping purged per run — no growth in long-lived
+  apps). Captures chains→node spans, LLM (params, tools offered,
+  tokens+cache/reasoning details, TTFT, streaming partials ~0.5 s), tools,
+  retrievers, retries, custom events, GraphInterrupt→interrupted (a pause,
+  never an error), messages as {role, content, tool_calls},
+  session/tags/run_name/thread_id via config metadata. The HTTP sink is
+  non-blocking (bounded queue + drain thread, sheds oldest). Best-effort:
+  never raises into — or slows — the user's graph.
 - **Store** (`windhover.store`, SQLite WAL, schema v7): runs / spans (tree) /
   scores / datasets (+span_fts). Feature-detects FTS5 & json1 at startup;
   idempotent column migrations.
 - **HITL** (`/api/threads/*`): thin wrappers over `Command(resume|goto)`,
   `interrupt_before/after`, `update_state`, `get_state_history`, checkpoint-id
-  forking. Requires the local graph to have a checkpointer.
+  forking. Requires the local graph to have a checkpointer. Pending-node
+  detection queries by thread only (a checkpoint_id would read history).
+- **Cache visibility**: LangGraph `CachePolicy` hits fire no callbacks; local
+  runs synthesize the node span with `params.cached`.
 - **Auth**: optional `WINDHOVER_TOKEN` Bearer/?token= gate on `/api` only.
+- **Alerts**: `WINDHOVER_WEBHOOK` POSTs a summary on error/interrupted runs
+  (store.on_run_closed hook, fire-and-forget, deduped).
 
 ## Data model (schema v7)
 `runs`: id · graph · source(ui|ingest) · status(running|done|error|interrupted) ·

{windhover-0.14.2 → windhover-0.14.3}/docs/GUIDE.md

@@ -154,6 +154,23 @@ curl -X POST :8090/api/datasets -H 'Content-Type: application/json' -d '{
 numbers/booleans, substring-of-output-JSON for strings. It's a smoke-level matcher —
 for semantic grading, run your own judge and `POST /api/runs/{id}/scores`.
 
+## Deep agents & agent frameworks
+
+Agent frameworks built on LangGraph — including `deepagents` (planning, virtual file
+system, sub-agents) and `create_react_agent` — trace with **no integration work**:
+
+- Every LLM call shows the **tools the model was offered**, so you can see an agent's
+  action space shrink inside a sub-agent.
+- **Sub-agents nest**: the `task` tool call that spawns one carries the entire child
+  agent's spans beneath it — one tree from top-level plan to nested completion.
+- **Plans render as checklists**: todo-shaped state (`[{content, status}]`) displays
+  with ✓/◐/○ markers instead of raw JSON, and state evolution shows each planning
+  update in order.
+- Framework-internal middleware spans (e.g. `TodoListMiddleware.after_model`) appear
+  italic-muted so the agent's real work stands out.
+- The canvas shows the compiled loop (agent ↔ tools) — an agent's *structure* lives in
+  its traces, not its topology; that's the nature of dynamic agents.
+
 ## More things the audit covered
 
 - **Concurrency & batch** — one tracer instance safely handles parallel `.invoke()`s:

{windhover-0.14.2 → windhover-0.14.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "windhover"
-version = "0.14.2"
+version = "0.14.3"
 description = "Self-hosted, mobile-friendly observability for LangGraph — traces, run history, cost, and a living graph view."
 readme = "README.md"
 requires-python = ">=3.10"

{windhover-0.14.2 → windhover-0.14.3}/windhover/static/index.html

@@ -330,6 +330,13 @@ window.pickDiff=async(id)=>{
 .msg .mrole{flex:none;font-family:var(--mono);font-size:9.5px;letter-spacing:.08em;text-transform:uppercase;color:var(--muted);padding-top:2px;width:64px;text-align:right}
 .msg.user .mrole{color:var(--accent-text)} .msg.assistant .mrole{color:var(--chip-llm-t)} .msg.tool .mrole,.msg.system .mrole{color:var(--chip-tool-t)}
 .msg>div{background:var(--surface);border:1px solid var(--border);border-radius:8px;padding:5px 9px;white-space:pre-wrap;word-break:break-word;flex:1}
+.todos{background:var(--surface2);border:1px solid var(--border);border-radius:8px;padding:8px 12px;display:flex;flex-direction:column;gap:4px}
+.todo{font-size:12.5px;display:flex;gap:8px;align-items:baseline}
+.todo .ti{font-family:var(--mono);color:var(--muted)}
+.todo.completed{color:var(--muted);text-decoration:line-through}
+.todo.completed .ti{color:var(--ok);text-decoration:none}
+.todo.in_progress .ti{color:var(--warn)}
+.tr-name.fw{color:var(--muted);font-weight:500;font-style:italic}
 
 /* ---------- modal (new run) ---------- */
 .modal{position:fixed;inset:0;display:grid;place-items:center;z-index:60;opacity:0;pointer-events:none;transition:.15s}
@@ -1008,7 +1015,7 @@ function renderSpans(list,byParent,total,depth){
       <div class="tr-row" onclick="tog('${did}',this)">
         <div class="tr-main"><span class="indent" style="width:${depth*18}px"></span>
           <span class="caret">▶</span><span class="chip ${s.type}">${s.type}</span>
-          <span class="tr-name ${s.status==='error'?'err':''}">${esc(s.name||s.type)}</span>${s.retries?`<span class="badge-retry">↻${s.retries}</span>`:''}</div>
+          <span class="tr-name ${s.status==='error'?'err':''} ${/Middleware\./.test(s.name||'')?'fw':''}">${esc(s.name||s.type)}</span>${s.retries?`<span class="badge-retry">↻${s.retries}</span>`:''}</div>
         <div class="tr-gantt"><div class="tr-bar ${s.type}" style="left:${left}%;width:${width}%"></div></div>
         <div class="tr-meta">${meta}</div>
       </div>
@@ -1024,6 +1031,9 @@ function renderSpans(list,byParent,total,depth){
   }).join('');
 }
 function isMsg(m){ return m&&typeof m==='object'&&typeof m.content!=='undefined'&&typeof (m.role||m.type)==='string'; }
+function isTodo(x){ return x&&typeof x==='object'&&typeof x.content==='string'&&typeof x.status==='string'; }
+function todoHtml(arr){ const ic={completed:'✓','in_progress':'◐',pending:'○'};
+  return `<div class="todos">${arr.map(t=>`<div class="todo ${esc(t.status)}"><span class="ti">${ic[t.status]||'○'}</span>${esc(t.content)}</div>`).join('')}</div>`; }
 function chatHtml(arr){ return `<div class="chat">${arr.map(m=>{
   const role=(m.role||m.type||'').replace('human','user').replace('ai','assistant');
   const body=typeof m.content==='string'?m.content:JSON.stringify(m.content);
@@ -1033,8 +1043,10 @@ function chatHtml(arr){ return `<div class="chat">${arr.map(m=>{
 function kv(k,v){
   const msgs=Array.isArray(v)&&v.length&&v.every(isMsg)?v
     :(v&&typeof v==='object'&&Array.isArray(v.messages)&&v.messages.length&&v.messages.every(isMsg)?v.messages:null);
+  const todos=Array.isArray(v)&&v.length&&v.every(isTodo)?v
+    :(v&&typeof v==='object'&&Array.isArray(v.todos)&&v.todos.length&&v.todos.every(isTodo)?v.todos:null);
   const txt=typeof v==='string'?v:JSON.stringify(v,null,2);
-  return `<div class="kv"><div class="k">${k}<button class="copy" onclick="navigator.clipboard.writeText(${JSON.stringify(txt).replace(/"/g,'&quot;')});toast('Copied')">copy</button></div>${msgs?chatHtml(msgs):`<pre>${esc(txt)}</pre>`}</div>`; }
+  return `<div class="kv"><div class="k">${k}<button class="copy" onclick="navigator.clipboard.writeText(${JSON.stringify(txt).replace(/"/g,'&quot;')});toast('Copied')">copy</button></div>${msgs?chatHtml(msgs):(todos?todoHtml(todos):`<pre>${esc(txt)}</pre>`)}</div>`; }
 window.tog=(id,row)=>{ const el=document.getElementById(id); const open=el.style.display==='block';
   el.style.display=open?'none':'block'; row.querySelector('.caret').classList.toggle('open',!open); };
 window.replay=async(steps)=>{ closeAll(); switchView('graph');