windhover 0.12.0__tar.gz → 0.13.0__tar.gz

{windhover-0.12.0 → windhover-0.13.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: windhover
-Version: 0.12.0
+Version: 0.13.0
 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
@@ -17,7 +17,7 @@ Requires-Dist: langgraph>=0.2; extra == 'dev'
 Requires-Dist: pytest; extra == 'dev'
 Description-Content-Type: text/markdown
 
-<p align="center"><img src="docs/logo.svg" width="112" alt="Windhover — a hovering kestrel"></p>
+<p align="center"><img src="https://raw.githubusercontent.com/justfeltlikerunning/windhover/main/docs/logo.svg" width="112" alt="Windhover — a hovering kestrel"></p>
 <h1 align="center">Windhover</h1>
 <p align="center">
   <a href="https://pypi.org/project/windhover/"><img src="https://img.shields.io/pypi/v/windhover" alt="PyPI"></a>
@@ -40,11 +40,11 @@ your own app. No LangSmith account, no cloud tunnel, no fragile websocket. HTTP
 
 | Living graph (parallel fan-out) | Trace drawer — retrievers, LLM calls, cost, state |
 |---|---|
-| ![Graph view](docs/graph.png) | ![Trace drawer](docs/trace.png) |
+| ![Graph view](https://raw.githubusercontent.com/justfeltlikerunning/windhover/main/docs/graph.png) | ![Trace drawer](https://raw.githubusercontent.com/justfeltlikerunning/windhover/main/docs/trace.png) |
 
 | Runs — search, tags, sessions, interrupts | Dashboards — per-day, per-model |
 |---|---|
-| ![Runs table](docs/runs.png) | ![Stats](docs/stats.png) |
+| ![Runs table](https://raw.githubusercontent.com/justfeltlikerunning/windhover/main/docs/runs.png) | ![Stats](https://raw.githubusercontent.com/justfeltlikerunning/windhover/main/docs/stats.png) |
 
 ## Quick start
 ```bash

{windhover-0.12.0 → windhover-0.13.0}/README.md

@@ -1,4 +1,4 @@
-<p align="center"><img src="docs/logo.svg" width="112" alt="Windhover — a hovering kestrel"></p>
+<p align="center"><img src="https://raw.githubusercontent.com/justfeltlikerunning/windhover/main/docs/logo.svg" width="112" alt="Windhover — a hovering kestrel"></p>
 <h1 align="center">Windhover</h1>
 <p align="center">
   <a href="https://pypi.org/project/windhover/"><img src="https://img.shields.io/pypi/v/windhover" alt="PyPI"></a>
@@ -21,11 +21,11 @@ your own app. No LangSmith account, no cloud tunnel, no fragile websocket. HTTP
 
 | Living graph (parallel fan-out) | Trace drawer — retrievers, LLM calls, cost, state |
 |---|---|
-| ![Graph view](docs/graph.png) | ![Trace drawer](docs/trace.png) |
+| ![Graph view](https://raw.githubusercontent.com/justfeltlikerunning/windhover/main/docs/graph.png) | ![Trace drawer](https://raw.githubusercontent.com/justfeltlikerunning/windhover/main/docs/trace.png) |
 
 | Runs — search, tags, sessions, interrupts | Dashboards — per-day, per-model |
 |---|---|
-| ![Runs table](docs/runs.png) | ![Stats](docs/stats.png) |
+| ![Runs table](https://raw.githubusercontent.com/justfeltlikerunning/windhover/main/docs/runs.png) | ![Stats](https://raw.githubusercontent.com/justfeltlikerunning/windhover/main/docs/stats.png) |
 
 ## Quick start
 ```bash

{windhover-0.12.0 → windhover-0.13.0}/docs/GUIDE.md

@@ -187,11 +187,46 @@ for semantic grading, run your own judge and `POST /api/runs/{id}/scores`.
   shows the tool-call JSON as the LLM output instead of an empty box.
 - **Auth**: set `WINDHOVER_TOKEN` to require `Authorization: Bearer …` (or `?token=`)
   on `/api`. The UI prompts once and remembers. The HTML shell itself stays public —
-  it contains no data.
+  it contains no data. External tracers pass it as `WindhoverTracer(url, token="…")`.
+  **Set the token before exposing Windhover beyond localhost** — the HITL endpoints can
+  resume and edit graph state.
+- **Alerts**: `WINDHOVER_WEBHOOK=https://…` POSTs a compact JSON summary whenever a run
+  errors or pauses on an interrupt (`{source, graph, run_id, status, error, text, …}`) —
+  point it at a Slack/Discord webhook or your own receiver. Fire-and-forget.
 - **Retention**: `WINDHOVER_RETENTION_DAYS=30` prunes old runs on startup and every 6h.
   Default keeps everything.
 - **Deep links**: `#runs`, `#sessions`, `#stats`, `#run=<id>`.
 
+## Running it for real
+
+- **The tracer never slows your app.** Events go onto a bounded in-memory queue drained
+  by a background thread; if the Windhover host is slow or down, events are dropped —
+  your pipeline's latency is unchanged. (Sheds oldest-first at 2,000 queued events.)
+- **Systemd** (adjust paths):
+  ```ini
+  [Unit]
+  Description=Windhover
+  After=network.target
+
+  [Service]
+  WorkingDirectory=/opt/myapp
+  Environment=WINDHOVER_GRAPH=myapp.graphs:graph
+  Environment=WINDHOVER_DB=/var/lib/windhover/windhover.db
+  Environment=WINDHOVER_TOKEN=change-me
+  Environment=WINDHOVER_RETENTION_DAYS=30
+  ExecStart=/opt/myapp/.venv/bin/windhover
+  Restart=always
+  TimeoutStopSec=10
+
+  [Install]
+  WantedBy=multi-user.target
+  ```
+  `TimeoutStopSec` matters: open SSE connections otherwise stretch restarts.
+- **Reverse proxy**: plain HTTP + SSE — any proxy works; disable response buffering for
+  `/api/events` and `/api/run` (nginx: `proxy_buffering off;`).
+- **Backups**: runs live in one SQLite file (`WINDHOVER_DB`); copy it (plus `-wal`) or
+  rely on `/api/export` for tabular run data.
+
 ## Try it all on the demo graph
 
 `WINDHOVER_GRAPH=windhover.demo_graph:graph windhover`, then:

{windhover-0.12.0 → windhover-0.13.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "windhover"
-version = "0.12.0"
+version = "0.13.0"
 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.12.0 → windhover-0.13.0}/tests/test_smoke.py

@@ -573,6 +573,26 @@ def test_langgraph_json_discovery():
     print("langgraph.json discovery OK")
 
 
+def test_nonblocking_sink_and_webhook_hook():
+    # sink to an unreachable host must return instantly and never raise
+    from windhover.tracer import http_sink
+    sink = http_sink("http://10.255.255.1:9", max_queue=10)
+    t0 = time.time()
+    for i in range(50):
+        sink({"kind": "span", "i": i})
+    assert time.time() - t0 < 0.5, "sink blocked the caller"
+
+    # store hook fires with the closing status (webhook wiring point)
+    p = tempfile.mktemp(suffix=".db")
+    s = Store(p)
+    fired = []
+    s.on_run_closed = lambda summary: fired.append(summary)
+    s.open_run({"id": "w1", "graph": "g", "started_ms": 1000})
+    s.close_run("w1", "error", 1500, error="Boom: it broke")
+    assert fired and fired[0]["status"] == "error" and "Boom" in fired[0]["error"]
+    print("non-blocking sink + webhook hook OK")
+
+
 if __name__ == "__main__":
     test_cost(); print("cost OK")
     test_store_roundtrip()
@@ -598,4 +618,5 @@ if __name__ == "__main__":
     test_functional_api_tracing()
     test_message_serialization()
     test_langgraph_json_discovery()
+    test_nonblocking_sink_and_webhook_hook()
     print("ALL SMOKE TESTS PASSED")

{windhover-0.12.0 → windhover-0.13.0}/windhover/config.py

@@ -18,6 +18,7 @@ class Config:
     pricing_path: str
     retention_days: int       # 0 = keep runs forever
     token: str                # WINDHOVER_TOKEN: require Bearer/query token on /api ("" = open)
+    webhook: str              # WINDHOVER_WEBHOOK: POST run summaries on error/interrupted ("" = off)
 
     @staticmethod
     def _discover() -> tuple[str, str]:
@@ -58,4 +59,5 @@ class Config:
             pricing_path=os.environ.get("WINDHOVER_PRICING", str(PKG_DIR / "pricing.json")),
             retention_days=int(os.environ.get("WINDHOVER_RETENTION_DAYS", "0") or 0),
             token=os.environ.get("WINDHOVER_TOKEN", ""),
+            webhook=os.environ.get("WINDHOVER_WEBHOOK", ""),
         )

{windhover-0.12.0 → windhover-0.13.0}/windhover/server.py

@@ -140,6 +140,36 @@ if cfg.retention_days > 0:
     threading.Thread(target=_retention_loop, daemon=True).start()
 
 
+def _fire_webhook(summary: dict) -> None:
+    """POST a compact alert when a run needs attention. Fire-and-forget."""
+    if summary.get("status") not in ("error", "interrupted"):
+        return
+    def _post():
+        try:
+            import urllib.request
+            run = store.run_detail(summary["id"]) or summary
+            body = {
+                "source": "windhover", "graph": run.get("graph") or cfg.graph_ref,
+                "run_id": summary["id"], "status": summary["status"],
+                "duration_ms": summary.get("duration_ms"),
+                "session": run.get("session"), "thread_id": run.get("thread_id"),
+                "error": (str(summary.get("error") or "").strip().splitlines() or [None])[-1],
+                "text": f"[windhover] run {summary['id']} {summary['status']}"
+                        f" ({run.get('graph') or cfg.graph_ref})",
+            }
+            req = urllib.request.Request(
+                cfg.webhook, data=json.dumps(body).encode(),
+                headers={"Content-Type": "application/json"})
+            urllib.request.urlopen(req, timeout=5)
+        except Exception:
+            pass
+    threading.Thread(target=_post, daemon=True).start()
+
+
+if cfg.webhook:
+    store.on_run_closed = _fire_webhook
+
+
 def _template(schema: dict) -> dict:
     out = {}
     for k, p in (schema.get("properties") or {}).items():

{windhover-0.12.0 → windhover-0.13.0}/windhover/static/index.html

@@ -459,7 +459,7 @@ th{font-family:var(--mono);letter-spacing:.11em;font-size:10.5px}
       <button data-v="memory" id="nav-mem" style="display:none">${ICON.mem} Memory</button>
       <button data-v="stats">${ICON.chart} Stats</button>
     </nav>
-    <div class="side-foot"><span class="live-dot" id="live-dot" title="live topology"></span><span id="foot-note">watching</span><span class="spacer"></span><span class="mono" id="ver">v0.12</span></div>
+    <div class="side-foot"><span class="live-dot" id="live-dot" title="live topology"></span><span id="foot-note">watching</span><span class="spacer"></span><span class="mono" id="ver">v0.13</span></div>
   </aside>
 
   <main>

{windhover-0.12.0 → windhover-0.13.0}/windhover/store.py

@@ -27,6 +27,7 @@ class Store:
         self.path = path
         self.has_fts = False
         self.has_json1 = False
+        self.on_run_closed = None   # optional hook(run_dict) — used for webhooks
         self._init()
 
     def _conn(self) -> sqlite3.Connection:
@@ -171,6 +172,12 @@ class Store:
                 WHERE id=?""",
                 (status, ended_ms, ended_ms - started, error, agg["nc"], agg["lc"],
                  pt, ct, (pt or 0) + (ct or 0) if (pt or ct) else None, agg["cost"], run_id))
+        if self.on_run_closed is not None:
+            try:
+                self.on_run_closed({"id": run_id, "status": status, "error": error,
+                                    "duration_ms": ended_ms - started})
+            except Exception:
+                pass
 
     def update_run_meta(self, run_id: str, tags: Optional[list] = None,
                         bookmarked: Optional[bool] = None) -> bool:

{windhover-0.12.0 → windhover-0.13.0}/windhover/tracer.py

@@ -456,19 +456,48 @@ def db_sink(store) -> Callable[[dict], None]:
     return lambda ev: apply_to_store(store, ev, source="ui")
 
 
-def http_sink(base_url: str) -> Callable[[dict], None]:
-    import urllib.request
+def http_sink(base_url: str, token: Optional[str] = None,
+              max_queue: int = 2000) -> Callable[[dict], None]:
+    """Non-blocking: events go onto a bounded queue drained by a daemon thread,
+    so a slow or unreachable Windhover host NEVER adds latency to the traced
+    app. On overflow the oldest events are dropped (observability is
+    best-effort; the app comes first)."""
+    import queue as _q, threading as _t, urllib.request
     url = base_url.rstrip("/") + "/api/ingest"
+    headers = {"Content-Type": "application/json"}
+    if token:
+        headers["Authorization"] = f"Bearer {token}"
+    buf: "_q.Queue" = _q.Queue(maxsize=max_queue)
+
+    def _drain():
+        while True:
+            ev = buf.get()
+            try:
+                req = urllib.request.Request(url, data=json.dumps(ev).encode(),
+                                             headers=headers)
+                urllib.request.urlopen(req, timeout=5)
+            except Exception:
+                pass  # drop — never retry-storm a down collector
+
+    _t.Thread(target=_drain, daemon=True).start()
 
     def sink(ev: dict) -> None:
-        req = urllib.request.Request(url, data=json.dumps(ev).encode(),
-                                     headers={"Content-Type": "application/json"})
-        urllib.request.urlopen(req, timeout=3)
+        try:
+            buf.put_nowait(ev)
+        except _q.Full:
+            try:
+                buf.get_nowait()          # shed oldest, keep newest
+                buf.put_nowait(ev)
+            except Exception:
+                pass
     return sink
 
 
 class WindhoverTracer(SpanBuilder):
-    """Drop into any app: config={"callbacks": [WindhoverTracer("http://host:8090")]}."""
+    """Drop into any app: config={"callbacks": [WindhoverTracer("http://host:8090")]}.
+    Non-blocking; pass token= when the collector sets WINDHOVER_TOKEN."""
     def __init__(self, base_url: str, name: str = "external",
-                 session: Optional[str] = None, tags: Optional[list] = None):
-        super().__init__(http_sink(base_url), run_name=name, session=session, tags=tags)
+                 session: Optional[str] = None, tags: Optional[list] = None,
+                 token: Optional[str] = None):
+        super().__init__(http_sink(base_url, token=token),
+                         run_name=name, session=session, tags=tags)