swarph-triage 0.1.0__tar.gz

swarph_triage-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pierre Samson and contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

swarph_triage-0.1.0/PKG-INFO

@@ -0,0 +1,129 @@
+Metadata-Version: 2.4
+Name: swarph-triage
+Version: 0.1.0
+Summary: Generalizable ranked-queue triage primitive (fingerprint + priority + state machine + regression detector). Backend-agnostic via SQLAlchemy Core (sqlite + postgres).
+Author: Pierre Samson, Claude
+License: MIT
+Project-URL: Homepage, https://github.com/darw007d/swarph-triage
+Project-URL: Issues, https://github.com/darw007d/swarph-triage/issues
+Keywords: triage,queue,priority,state-machine,swarph
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Development Status :: 3 - Alpha
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: sqlalchemy>=2.0
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.110; extra == "fastapi"
+Requires-Dist: sse-starlette>=2.0; extra == "fastapi"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
+Dynamic: license-file
+
+# swarph-triage
+
+> Generalizable ranked-queue triage primitive — fingerprint, priority, state machine, regression detector. Backend-agnostic via SQLAlchemy Core (sqlite + postgres).
+
+**Status:** ✅ 0.1.0 — functional. Public API, priority formula, state machine, regression detector, CLI, and FastAPI router are implemented and tested (sqlite + postgres via SQLAlchemy Core).
+
+Extracted from a production **error-triage** system (scan logs → fingerprint → prioritize → work the backlog down) and generalized: the same ranked-dedup-queue pattern fits any high-volume stream of observations that should collapse into prioritized, dispositionable rows.
+
+## The pattern
+
+A ranked queue where:
+
+1. **Many concrete observations collapse to one logical row** via a `fingerprint_fn`. (Canonical case — error triage: 47 near-identical error log lines → 1 fingerprint with `count=47`. The pattern generalizes to any stream where many raw events map to one actionable unit.)
+2. **Items rank by `severity × log(1+freq) × decay(age) × actionability`** — log on freq stops whales drowning fresh items, exp-decay on age makes hot items rise. All coefficients live in a calibration table (config-driven, not hardcoded).
+3. **A small explicit state machine** (`new → triaged → approved → patched`, with branches to `wontfix` and `needs_review`) — every transition logged to `state_log`, no implicit "kinda done."
+4. **A regression detector** — if a fingerprint with `status='patched'` gets a new occurrence within `regression_grace_hours`, resurrect to `new` with `regression=1`. Accepted dispositions don't silently mask returning problems.
+5. **Cooldown semantics** — a `cooldown_until` timestamp on `let_cool` dispositions. The priority calc ramps back from zero as cooldown expires, so a deliberately-deferred item doesn't immediately re-surface.
+
+## Public API surface (planned)
+
+```python
+from swarph_triage import open as open_triage
+
+q = open_triage(
+    "postgresql://user:pass@host:5433/mydb",  # or sqlite:///path.db
+    config={"decay_half_life_hours": 72.0},
+    proposer_fn=my_proposer,  # optional, domain-specific
+)
+
+# ingest one observation
+fp_id = q.ingest(
+    fingerprint="NullPointerError|auth.py|login",
+    severity="high",
+    actionability=0.7,
+    context={"module": "auth", "first_seen": "..."},
+)
+
+# disposition
+q.transition(fp_id, to_status="approved", actor="oncall", note="fix queued")
+
+# top-N for the UI
+for row in q.list(limit=20):
+    print(row["fingerprint"], row["priority_score"], row["status"])
+```
+
+CLI:
+```
+swarph-triage list
+swarph-triage show <id>
+swarph-triage approve <id>
+swarph-triage wontfix <id> "reason"
+swarph-triage stats
+swarph-triage backlog          # writes markdown snapshot
+swarph-triage history <id>
+```
+
+FastAPI routes (optional install: `pip install swarph-triage[fastapi]`):
+```python
+from fastapi import FastAPI
+from swarph_triage.fastapi import build_router
+
+app = FastAPI()
+app.include_router(build_router(q), prefix="/triage")
+# → /list, /stats, /show/{id}, /{id}/{approve|wontfix|escalate|reopen}, /events (SSE)
+```
+
+## Configuration
+
+Everything tunable lives in `swarph_triage.config.DEFAULT_CONFIG` — override per-consumer at `open()`:
+
+```python
+DEFAULT_CONFIG = {
+    "decay_half_life_hours": 6.0,                                      # 6h for hourly, 72h for daily
+    "severity_weights": {"critical": 1.0, "high": 0.7, "medium": 0.5, "low": 0.3},
+    "freq_curve": "log",                                               # "log" | "linear" | "sqrt"
+    "freq_log_base": 10,
+    "actionability_floor": 0.1,
+    "regression_grace_hours": 24,
+    "cooldown_default_days": 14,
+    "priority_min": 0.0,
+    "priority_max": 100.0,
+}
+```
+
+## Layout
+
+```
+swarph_triage/
+  __init__.py        — public API surface
+  config.py          — DEFAULT_CONFIG + load/merge helpers
+  schema.py          — SQLAlchemy Core table definitions (3 tables, 6 indexes)
+  state_machine.py   — Status enum + valid transition matrix + side effects
+  priority.py        — score formula + decay + recompute_all
+  regression.py      — patched-then-reappearance detector
+  queue.py           — TriageQueue main class (ingest, transition, list, show)
+  cli.py             — argparse-driven CLI
+  fastapi.py         — APIRouter factory (optional extra)
+```
+
+## License
+
+MIT. Pierre Samson + Claude, co-authored — matching the `phawkes` / `fisherrao` / `tailcor` lineage.

swarph_triage-0.1.0/README.md

@@ -0,0 +1,102 @@
+# swarph-triage
+
+> Generalizable ranked-queue triage primitive — fingerprint, priority, state machine, regression detector. Backend-agnostic via SQLAlchemy Core (sqlite + postgres).
+
+**Status:** ✅ 0.1.0 — functional. Public API, priority formula, state machine, regression detector, CLI, and FastAPI router are implemented and tested (sqlite + postgres via SQLAlchemy Core).
+
+Extracted from a production **error-triage** system (scan logs → fingerprint → prioritize → work the backlog down) and generalized: the same ranked-dedup-queue pattern fits any high-volume stream of observations that should collapse into prioritized, dispositionable rows.
+
+## The pattern
+
+A ranked queue where:
+
+1. **Many concrete observations collapse to one logical row** via a `fingerprint_fn`. (Canonical case — error triage: 47 near-identical error log lines → 1 fingerprint with `count=47`. The pattern generalizes to any stream where many raw events map to one actionable unit.)
+2. **Items rank by `severity × log(1+freq) × decay(age) × actionability`** — log on freq stops whales drowning fresh items, exp-decay on age makes hot items rise. All coefficients live in a calibration table (config-driven, not hardcoded).
+3. **A small explicit state machine** (`new → triaged → approved → patched`, with branches to `wontfix` and `needs_review`) — every transition logged to `state_log`, no implicit "kinda done."
+4. **A regression detector** — if a fingerprint with `status='patched'` gets a new occurrence within `regression_grace_hours`, resurrect to `new` with `regression=1`. Accepted dispositions don't silently mask returning problems.
+5. **Cooldown semantics** — a `cooldown_until` timestamp on `let_cool` dispositions. The priority calc ramps back from zero as cooldown expires, so a deliberately-deferred item doesn't immediately re-surface.
+
+## Public API surface (planned)
+
+```python
+from swarph_triage import open as open_triage
+
+q = open_triage(
+    "postgresql://user:pass@host:5433/mydb",  # or sqlite:///path.db
+    config={"decay_half_life_hours": 72.0},
+    proposer_fn=my_proposer,  # optional, domain-specific
+)
+
+# ingest one observation
+fp_id = q.ingest(
+    fingerprint="NullPointerError|auth.py|login",
+    severity="high",
+    actionability=0.7,
+    context={"module": "auth", "first_seen": "..."},
+)
+
+# disposition
+q.transition(fp_id, to_status="approved", actor="oncall", note="fix queued")
+
+# top-N for the UI
+for row in q.list(limit=20):
+    print(row["fingerprint"], row["priority_score"], row["status"])
+```
+
+CLI:
+```
+swarph-triage list
+swarph-triage show <id>
+swarph-triage approve <id>
+swarph-triage wontfix <id> "reason"
+swarph-triage stats
+swarph-triage backlog          # writes markdown snapshot
+swarph-triage history <id>
+```
+
+FastAPI routes (optional install: `pip install swarph-triage[fastapi]`):
+```python
+from fastapi import FastAPI
+from swarph_triage.fastapi import build_router
+
+app = FastAPI()
+app.include_router(build_router(q), prefix="/triage")
+# → /list, /stats, /show/{id}, /{id}/{approve|wontfix|escalate|reopen}, /events (SSE)
+```
+
+## Configuration
+
+Everything tunable lives in `swarph_triage.config.DEFAULT_CONFIG` — override per-consumer at `open()`:
+
+```python
+DEFAULT_CONFIG = {
+    "decay_half_life_hours": 6.0,                                      # 6h for hourly, 72h for daily
+    "severity_weights": {"critical": 1.0, "high": 0.7, "medium": 0.5, "low": 0.3},
+    "freq_curve": "log",                                               # "log" | "linear" | "sqrt"
+    "freq_log_base": 10,
+    "actionability_floor": 0.1,
+    "regression_grace_hours": 24,
+    "cooldown_default_days": 14,
+    "priority_min": 0.0,
+    "priority_max": 100.0,
+}
+```
+
+## Layout
+
+```
+swarph_triage/
+  __init__.py        — public API surface
+  config.py          — DEFAULT_CONFIG + load/merge helpers
+  schema.py          — SQLAlchemy Core table definitions (3 tables, 6 indexes)
+  state_machine.py   — Status enum + valid transition matrix + side effects
+  priority.py        — score formula + decay + recompute_all
+  regression.py      — patched-then-reappearance detector
+  queue.py           — TriageQueue main class (ingest, transition, list, show)
+  cli.py             — argparse-driven CLI
+  fastapi.py         — APIRouter factory (optional extra)
+```
+
+## License
+
+MIT. Pierre Samson + Claude, co-authored — matching the `phawkes` / `fisherrao` / `tailcor` lineage.

swarph_triage-0.1.0/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "swarph-triage"
+version = "0.1.0"
+description = "Generalizable ranked-queue triage primitive (fingerprint + priority + state machine + regression detector). Backend-agnostic via SQLAlchemy Core (sqlite + postgres)."
+readme = "README.md"
+license = { text = "MIT" }
+authors = [
+  { name = "Pierre Samson" },
+  { name = "Claude" },
+]
+requires-python = ">=3.9"
+keywords = ["triage", "queue", "priority", "state-machine", "swarph"]
+classifiers = [
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Topic :: Database",
+  "Topic :: Software Development :: Libraries",
+  "Development Status :: 3 - Alpha",
+]
+dependencies = [
+  "sqlalchemy>=2.0",
+]
+
+[project.optional-dependencies]
+fastapi = [
+  "fastapi>=0.110",
+  "sse-starlette>=2.0",
+]
+dev = [
+  "pytest>=7.0",
+  "pytest-asyncio>=0.21",
+]
+
+[project.scripts]
+swarph-triage = "swarph_triage.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/darw007d/swarph-triage"
+Issues = "https://github.com/darw007d/swarph-triage/issues"
+
+[tool.setuptools.packages.find]
+include = ["swarph_triage*"]

swarph_triage-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

swarph_triage-0.1.0/swarph_triage/__init__.py

@@ -0,0 +1,28 @@
+"""swarph-triage — ranked-queue triage primitive.
+
+Public API:
+
+    from swarph_triage import open
+    q = open(db_url, config=..., proposer_fn=...)
+    q.ingest(fingerprint=..., severity=..., actionability=..., context=...)
+    q.transition(fp_id, to_status=..., actor=..., note=...)
+    q.list(limit=20)
+    q.show(fp_id)
+
+See README.md for the full surface.
+"""
+
+from swarph_triage._version import __version__
+from swarph_triage.queue import TriageQueue, open  # noqa: F401
+from swarph_triage.state_machine import Status, VALID_TRANSITIONS  # noqa: F401
+from swarph_triage.config import DEFAULT_CONFIG, load_config  # noqa: F401
+
+__all__ = [
+    "__version__",
+    "open",
+    "TriageQueue",
+    "Status",
+    "VALID_TRANSITIONS",
+    "DEFAULT_CONFIG",
+    "load_config",
+]

swarph_triage-0.1.0/swarph_triage/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

swarph_triage-0.1.0/swarph_triage/cli.py

@@ -0,0 +1,116 @@
+"""CLI — pure SQL, no LLM, instant.
+
+Reads ``SWARPH_TRIAGE_DB_URL`` from env. Implementation lands with queue port.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="swarph-triage")
+    parser.add_argument(
+        "--db-url",
+        default=os.environ.get("SWARPH_TRIAGE_DB_URL"),
+        help="Database URL (defaults to $SWARPH_TRIAGE_DB_URL).",
+    )
+    sub = parser.add_subparsers(dest="cmd", required=True)
+
+    sub.add_parser("list", help="Show top of queue").add_argument(
+        "--status", help="Filter by status", default=None,
+    )
+    sub.add_parser("stats", help="Status + category breakdown")
+    p_show = sub.add_parser("show", help="Show one row + history")
+    p_show.add_argument("id", type=int)
+    for verb in ("approve", "wontfix", "escalate", "reopen"):
+        p = sub.add_parser(verb, help=f"{verb} a fingerprint")
+        p.add_argument("id", type=int)
+        p.add_argument("note", nargs="?", default="")
+    p_hist = sub.add_parser("history", help="Show state_log for one row")
+    p_hist.add_argument("id", type=int)
+    sub.add_parser("backlog", help="Print queue as markdown")
+
+    args = parser.parse_args(argv)
+    if not args.db_url:
+        print("ERROR: --db-url or $SWARPH_TRIAGE_DB_URL required", file=sys.stderr)
+        return 2
+
+    import json
+
+    from swarph_triage import open as open_triage
+
+    q = open_triage(args.db_url)
+
+    # Verbs that map to a state transition / reopen.
+    _TRANSITION_VERBS = {
+        "approve": "approved",
+        "wontfix": "wontfix",
+        "escalate": "needs_review",
+    }
+
+    if args.cmd == "list":
+        rows = q.list(status=args.status)
+        if not rows:
+            print("(queue empty)")
+        for r in rows:
+            print(f"{r['id']:>5}  {r['priority_score']:>7.2f}  "
+                  f"{r['status']:<12}  {r['severity']:<8}  {r['fingerprint']}")
+        return 0
+
+    if args.cmd == "stats":
+        print(json.dumps(q.stats(), indent=2, default=str))
+        return 0
+
+    if args.cmd == "show":
+        row = q.show(args.id)
+        if not row:
+            print(f"ERROR: no fingerprint id={args.id}", file=sys.stderr)
+            return 1
+        print(json.dumps(row, indent=2, default=str))
+        return 0
+
+    if args.cmd in _TRANSITION_VERBS:
+        ok = q.transition(
+            args.id,
+            to_status=_TRANSITION_VERBS[args.cmd],
+            actor="cli",
+            note=args.note,
+        )
+        if not ok:
+            print(f"ERROR: {args.cmd} on id={args.id} rejected "
+                  f"(invalid transition or missing row)", file=sys.stderr)
+            return 1
+        print(f"{args.cmd}: id={args.id} -> {_TRANSITION_VERBS[args.cmd]}")
+        return 0
+
+    if args.cmd == "reopen":
+        ok = q.reopen(args.id, actor="cli", note=args.note)
+        if not ok:
+            print(f"ERROR: reopen on id={args.id} rejected "
+                  f"(not terminal or missing row)", file=sys.stderr)
+            return 1
+        print(f"reopen: id={args.id} -> new")
+        return 0
+
+    if args.cmd == "history":
+        hist = q.history(args.id)
+        if not hist:
+            print("(no history)")
+        for h in hist:
+            print(f"{h['transitioned_at']}  {h['from_status']} -> "
+                  f"{h['to_status']}  [{h['actor']}]  {h['note'] or ''}")
+        return 0
+
+    if args.cmd == "backlog":
+        print(q.backlog_md())
+        return 0
+
+    print(f"ERROR: unknown command {args.cmd}", file=sys.stderr)
+    return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

swarph_triage-0.1.0/swarph_triage/config.py

@@ -0,0 +1,63 @@
+"""Calibration table — every tunable lives here.
+
+DSPy-style retunes / per-consumer overrides go in here, not in worker code.
+Pass overrides via ``swarph_triage.open(..., config={...})``.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Mapping
+
+DEFAULT_CONFIG: dict[str, Any] = {
+    # ─── priority decay ───
+    # Used in priority.compute(): score *= exp(-hours_since_last_seen / half_life).
+    # Tune to ingest cadence: 6h for hourly cron, 48–72h for daily refresh.
+    "decay_half_life_hours": 6.0,
+
+    # ─── severity → weight ───
+    # Map your severity labels to multipliers. Unknown labels fall back to 0.5.
+    "severity_weights": {
+        "critical": 1.0,
+        "high": 0.7,
+        "medium": 0.5,
+        "low": 0.3,
+    },
+
+    # ─── frequency curve ───
+    # "log" → log_base(1 + freq). "linear" → freq. "sqrt" → sqrt(freq).
+    # log is the production-tested default; whales don't drown fresh items.
+    "freq_curve": "log",
+    "freq_log_base": 10,
+
+    # ─── actionability ───
+    # Floor on the multiplier so nothing is truly zero (small items still
+    # accumulate via the freq term and bubble up over time).
+    "actionability_floor": 0.1,
+
+    # ─── regression detector ───
+    # After a `patched_at` timestamp, a new occurrence within this window
+    # resurrects the row to `new` + sets regression=1. Default: 24h.
+    "regression_grace_hours": 24,
+
+    # ─── cooldown semantics ───
+    # When a row is sent to `let_cool`, cooldown_until = now + N days.
+    # Priority ramps DURING the cooldown window — 0 at cooldown-start, linearly
+    # back to full at expiry (not "after"); see priority.compute's cooldown ramp.
+    "cooldown_default_days": 14,
+
+    # ─── normalization ───
+    "priority_min": 0.0,
+    "priority_max": 100.0,
+}
+
+
+def load_config(overrides: Mapping[str, Any] | None = None) -> dict[str, Any]:
+    """Merge ``overrides`` shallow-on-top-of-DEFAULT_CONFIG.
+
+    Nested dicts (e.g. ``severity_weights``) are replaced wholesale, not merged.
+    If you need partial-merge for a nested dict, pass the full merged dict.
+    """
+    cfg: dict[str, Any] = {**DEFAULT_CONFIG}
+    if overrides:
+        cfg.update(overrides)
+    return cfg

swarph_triage-0.1.0/swarph_triage/fastapi.py

@@ -0,0 +1,56 @@
+"""FastAPI APIRouter factory — JSON only, no HTML.
+
+Templates / HTMX surface stays consumer-side; this module exposes the data
+endpoints the consumer's UI binds against.
+
+Optional install: ``pip install swarph-triage[fastapi]``
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+
+def build_router(queue) -> Any:
+    """Return a FastAPI ``APIRouter`` mountable into the consumer's app.
+
+    Routes:
+
+        GET  /list?status=...&limit=...&offset=...
+        GET  /stats
+        GET  /show/{fp_id}
+        POST /transition/{fp_id}   body: {to_status, actor, note?}
+    """
+    from fastapi import APIRouter, Body
+
+    router = APIRouter()
+
+    @router.get("/list")
+    def list_rows(status: Optional[str] = None, limit: int = 50, offset: int = 0):
+        return queue.list(status=status, limit=limit, offset=offset)
+
+    @router.get("/stats")
+    def stats():
+        return queue.stats()
+
+    @router.get("/show/{fp_id}")
+    def show(fp_id: int):
+        return queue.show(fp_id)
+
+    @router.post("/transition/{fp_id}")
+    def transition(fp_id: int, body: dict = Body(...)):
+        from fastapi import HTTPException
+        # Auth is the consumer's responsibility (mount this router behind your
+        # own auth middleware). Validate the required field → 422, not a 500.
+        to_status = body.get("to_status")
+        if not to_status:
+            raise HTTPException(status_code=422, detail="to_status is required")
+        ok = queue.transition(
+            fp_id,
+            to_status=to_status,
+            actor=body.get("actor", "api"),
+            note=body.get("note", ""),
+        )
+        return {"ok": ok}
+
+    return router