hypgraph 0.1.0__py3-none-any.whl

hypgraph/server.py

@@ -0,0 +1,202 @@
+"""
+``hypgraph serve`` — the JSON API and the Atlas explorer, stdlib only.
+
+    GET  /                                  the Atlas
+    GET  /api/graph/investigations          {investigations, stats}
+    GET  /api/graph/subgraph?inv=&types=    nodes (with standing) and live edges
+    GET  /api/graph/node/{id}?history=1     one node, its links, its versions
+    GET  /api/graph/why/{id}                what it rests on        /impact/{id}  what rests on it
+    GET  /api/graph/neighborhood/{id}?depth=
+    GET  /api/graph/search?text=&type=&inv=&limit=
+    GET  /api/graph/events?after=&inv=&limit=
+    GET  /api/graph/next?inv=   /work?inv=   /cost?inv=&node=   /report?inv=   /verify   /schema
+    GET  /api/graph/export?inv=             a verifiable bundle
+    POST /api/graph/write                   only with --writable: {op, author, ...} (create | revise | link | retract |
+                                            withdraw | review | lease); the policy's reserved authors are refused
+
+It binds to 127.0.0.1 by default and refuses requests whose Host isn't the address it serves (DNS rebinding) and
+cross-origin writes. It authenticates nobody: put it behind your own auth before exposing it beyond your machine.
+``dispatch()`` is the routing on its own, for hosts that bring their own web framework.
+"""
+
+from __future__ import annotations
+
+import json
+import mimetypes
+import threading
+import webbrowser
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from pathlib import Path
+from urllib.parse import parse_qs, unquote, urlparse
+
+from .graph import Graph, GraphError
+from .schema import describe
+from .ui import static_dir
+
+WRITES = {
+    "create": ("create", ("type", "fields", "inv", "links", "reason")),
+    "revise": ("revise", ("node", "fields", "reason")),
+    "link": ("link", ("src", "rel", "dst", "why", "data")),
+    "retract": ("retract", ("edge", "why")),
+    "withdraw": ("withdraw", ("node", "why")),
+    "review": ("review", ("target", "verdict", "method", "notes")),
+    "lease": ("lease", ("node", "task", "minutes", "release", "note")),
+}
+
+
+def _int(q: dict, k: str, default: int, lo: int, hi: int) -> int:
+    try:
+        return max(lo, min(int(q.get(k, default)), hi))
+    except (TypeError, ValueError):
+        return default
+
+
+def dispatch(g: Graph, method: str, path: str, query: dict | None = None, body: dict | None = None,
+             writable: bool = False) -> tuple[int, object]:
+    """Route one API call. ``path`` is what follows /api/graph (e.g. "/node/n1a2b"). Returns (status, JSON value)."""
+    q = {k: (v[0] if isinstance(v, list) else v) for k, v in (query or {}).items()}
+    parts = [unquote(p) for p in path.strip("/").split("/") if p]
+    try:
+        if method == "POST":
+            if parts != ["write"]:
+                return 404, {"detail": "no such route"}
+            if not writable:
+                return 403, {"detail": "this server is read-only (start it with --writable to accept writes)"}
+            b = body or {}
+            author = str(b.get("author") or "").strip()
+            if not author or author in g.policy.reserved:
+                return 403, {"detail": "author missing, or reserved (" + ", ".join(sorted(g.policy.reserved)) + ")"}
+            spec = WRITES.get(str(b.get("op") or ""))
+            if not spec:
+                return 400, {"detail": f"op must be one of {', '.join(WRITES)}"}
+            fn, keys = spec
+            return 200, getattr(g, fn)(author=author, **{k: b[k] for k in keys if k in b})
+        if method != "GET" or not parts:
+            return 404, {"detail": "no such route"}
+        head, arg = parts[0], (parts[1] if len(parts) > 1 else "")
+        inv = q.get("inv", "")
+        if head == "investigations":
+            return 200, {"investigations": g.investigations(), "stats": g.stats()}
+        if head == "subgraph":
+            types = [t for t in str(q.get("types", "")).split(",") if t] or None
+            return 200, g.subgraph(inv, types=types)
+        if head == "node" and arg:
+            return 200, g.get(arg, history=q.get("history") in ("1", "true"))
+        if head == "why" and arg:
+            return 200, g.why(arg)
+        if head == "impact" and arg:
+            return 200, g.impact(arg)
+        if head == "neighborhood" and arg:
+            return 200, g.neighborhood(arg, depth=_int(q, "depth", 1, 1, 4))
+        if head == "search":
+            return 200, {"results": g.search(text=q.get("text", ""), type=q.get("type", ""), inv=inv,
+                                              limit=_int(q, "limit", 50, 1, 500))}
+        if head == "events":
+            return 200, g.events(after=_int(q, "after", 0, 0, 10 ** 12), inv=inv, limit=_int(q, "limit", 500, 1, 5000))
+        if head == "next":
+            return 200, g.next_experiments(inv, limit=_int(q, "limit", 20, 1, 100))
+        if head == "work":
+            return 200, g.work_map(inv)
+        if head == "cost":
+            return 200, g.cost(inv, q.get("node", ""))
+        if head == "report":
+            return 200, g.report(inv)
+        if head == "verify":
+            return 200, g.verify_chain()
+        if head == "export":
+            return 200, g.export(inv)
+        if head == "schema":
+            return 200, describe()
+        if head == "stats":
+            return 200, g.stats()
+        return 404, {"detail": "no such route"}
+    except KeyError as e:
+        return 404, {"detail": f"not found: {e.args[0] if e.args else e}"}
+    except (GraphError, ValueError, TypeError) as e:
+        return 400, {"detail": str(e)}
+
+
+def make_handler(g: Graph, *, writable: bool, hosts: set[str], root: Path):
+    class Handler(BaseHTTPRequestHandler):
+        server_version = "hypgraph"
+
+        def log_message(self, fmt, *args):  # quiet by default
+            pass
+
+        def _send(self, status: int, data: bytes, ctype: str) -> None:
+            self.send_response(status)
+            self.send_header("Content-Type", ctype)
+            self.send_header("Content-Length", str(len(data)))
+            self.send_header("X-Content-Type-Options", "nosniff")
+            self.send_header("Cache-Control", "no-store")
+            self.end_headers()
+            self.wfile.write(data)
+
+        def _json(self, status: int, obj) -> None:
+            self._send(status, json.dumps(obj, ensure_ascii=False, default=str).encode(), "application/json")
+
+        def _host_ok(self) -> bool:
+            host = (self.headers.get("Host") or "").rsplit(":", 1)[0].strip("[]").lower()
+            return host in hosts
+
+        def do_GET(self):  # noqa: N802
+            if not self._host_ok():
+                return self._json(421, {"detail": "unexpected Host header"})
+            u = urlparse(self.path)
+            if u.path.startswith("/api/graph"):
+                status, obj = dispatch(g, "GET", u.path[len("/api/graph"):], parse_qs(u.query), writable=writable)
+                return self._json(status, obj)
+            rel = "index.html" if u.path in ("", "/") else unquote(u.path).lstrip("/")
+            f = (root / rel).resolve()
+            if not f.is_relative_to(root) or not f.is_file():
+                return self._json(404, {"detail": "not found"})
+            ctype = mimetypes.guess_type(f.name)[0] or "application/octet-stream"
+            if ctype.startswith("text/") or ctype in ("application/javascript", "image/svg+xml"):
+                ctype += "; charset=utf-8"
+            self._send(200, f.read_bytes(), ctype)
+
+        def do_POST(self):  # noqa: N802
+            if not self._host_ok():
+                return self._json(421, {"detail": "unexpected Host header"})
+            origin = self.headers.get("Origin")
+            if origin and urlparse(origin).hostname not in hosts:
+                return self._json(403, {"detail": "cross-origin write refused"})
+            n = int(self.headers.get("Content-Length") or 0)
+            if n > 2_000_000:
+                return self._json(413, {"detail": "request too large"})
+            try:
+                body = json.loads(self.rfile.read(n) or b"{}")
+            except json.JSONDecodeError:
+                return self._json(400, {"detail": "body must be JSON"})
+            u = urlparse(self.path)
+            if not u.path.startswith("/api/graph"):
+                return self._json(404, {"detail": "no such route"})
+            status, obj = dispatch(g, "POST", u.path[len("/api/graph"):], body=body, writable=writable)
+            self._json(status, obj)
+    return Handler
+
+
+def make_server(graph: Graph | str, host: str = "127.0.0.1", port: int = 8765, *, writable: bool = False):
+    g = graph if isinstance(graph, Graph) else Graph(graph)
+    hosts = {host.lower(), "localhost", "127.0.0.1", "::1"} if host in ("127.0.0.1", "localhost", "::1") else \
+        {host.lower()}
+    root = static_dir().resolve()
+    return ThreadingHTTPServer((host, port), make_handler(g, writable=writable, hosts=hosts, root=root))
+
+
+def serve(db: str, host: str = "127.0.0.1", port: int = 8765, *, writable: bool = False,
+          open_browser: bool = True) -> None:
+    if not Path(db).exists():
+        print(f"{db} doesn't exist yet — `hypgraph demo` builds one to explore, `hypgraph init` starts your own.")
+        return
+    srv = make_server(db, host, port, writable=writable)
+    url = f"http://{host}:{srv.server_address[1]}/"
+    print(f"HypGraph Atlas on {url}  ({db}{', writable' if writable else ', read-only'})  — Ctrl+C to stop")
+    if open_browser:
+        threading.Timer(0.6, lambda: webbrowser.open(url)).start()
+    try:
+        srv.serve_forever()
+    except KeyboardInterrupt:
+        pass
+    finally:
+        srv.server_close()

hypgraph/skill/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: hypgraph
+description: Keep a research record that can't flatter itself — hypotheses with predictions, experiments with expected outcomes written before running, hashed runs, results, and claims whose every number is bound to a result. Use when investigating a question with evidence (science, data analysis, debugging a hypothesis, literature claims, ML evaluation), when asked to record findings, cite what is established, plan the next experiment, or write a summary that must not overclaim. Works through the `hypgraph` CLI or its MCP server.
+---
+
+# HypGraph — test the hyp
+
+HypGraph is an append-only, hash-chained research record. You write nodes (question, hypothesis, experiment, run,
+result, claim, source, decision) and typed links. **You cannot set how well anything is known.** Review state, risk,
+independent support and evidence strength are derived on every read. When the record refuses a write, the message
+says exactly what to fix: fix that, don't route around it.
+
+Prefer the MCP tools if a `hypgraph` server is connected (`overview`, `find`, `show`, `add`, `link`, `review`,
+`register_run`, `next_experiments`, `work_queue`, `report`, `verify`). Otherwise use the CLI below, adding `--json`
+when you need to parse the output. Install it with `pip install hypgraph`.
+
+## Setup (CLI)
+
+```bash
+export HYPGRAPH_DB=study.hypgraph HYPGRAPH_AUTHOR=<your-name>      # or --db / --as on every command
+hypgraph ls                                                         # what investigations exist
+hypgraph init "Title" --objective "What you want to find out, in a sentence." --reviewers <reviewer-names>
+```
+
+The names `lab`, `operator`, `importer` and `system` are reserved. Never write as someone else.
+
+## The method
+
+1. **Read first.** Run `hypgraph ls`, `hypgraph ls --type claim`, `hypgraph show CL3 --why` and `hypgraph work`
+   before re-deriving anything. Don't cite a node whose sentence says CONTESTED, AT RISK or UNSUPPORTED without
+   checking it.
+2. **Hypotheses with predictions.** Name rival hypotheses too.
+   ```bash
+   hypgraph add hypothesis statement="Caching causes the latency spike." predictions='["Spike disappears with cache off."]'
+   hypgraph link H2 alternative_to H1
+   ```
+3. **Experiments that can fail.** Write the expected outcome per hypothesis **before** running:
+   ```bash
+   hypgraph add experiment aim="Toggle the cache under fixed load." protocol="10 runs each, cache on/off, same load script." \
+     success_criteria="Median p99 differs by more than run-to-run spread." power_check="Inject a known 50 ms delay; confirm it is detected."
+   hypgraph link X1 tests H1 expected="p99 drops with cache off"
+   hypgraph link X1 tests H2 expected="no change with cache off"
+   ```
+   `hypgraph next` ranks experiments by how many hypotheses they separate, whether they can show their own power,
+   and their cost.
+4. **Runs and results.** Hash what you ran: `hypgraph.file_sha256(path)` or MCP `register_run`. Results carry values
+   as `{name: {value}}` or `{name: {k, n}}`:
+   ```bash
+   hypgraph add result summary="p99 fell from 840 ms to 210 ms with the cache off." \
+     values='{"p99_on_ms": {"value": 840}, "p99_off_ms": {"value": 210}, "runs": {"value": 10}}' outcome=positive
+   ```
+5. **Claims carry their numbers.**
+   ```bash
+   hypgraph add claim statement="With the cache off, p99 fell from 840 ms to 210 ms." \
+     scope="Staging, fixed load script, 10 runs per condition, build 4f2a." \
+     measurements='[{"name":"on","result":"RS1","key":"p99_on_ms","value":840},{"name":"off","result":"RS1","key":"p99_off_ms","value":210}]' \
+     --link "supports:from:RS1:RS1 is the measurement this claim states"
+   ```
+6. **Ask for review.** Only the investigation's reviewers set standing, never on their own work. Revising a claim
+   makes earlier reviews stale and flags decisions based on it.
+7. **Summaries start from the record.** `hypgraph report -o facts.md` generates the facts, which can't restate a
+   withdrawn claim or override a verdict. Write your interpretation underneath.
+
+## Refusals and their fixes
+
+| The record says | Do this |
+|---|---|
+| `numbers in the statement that no bound measurement … account for: 30` | Add a measurement binding that number to a result field, or put design constants in the scope. Don't delete the number to sneak past. |
+| `'always' is absolute` | Back it with k of n where k = 0 or n, or say "in k of n" / "rarely". |
+| `an exclusion needs a search that recovered a planted answer` | Run a power check (plant a known answer and recover it) and set `power=demonstrated` on the result, or file the claim as `kind=inconclusive`. |
+| `scope: say under which conditions this holds` | Name the data, method and sample. |
+| `link the evidence` | Add a `supports` link from the result, with a reason. |
+| `tests …: give data.expected` | Say what the experiment should show if that hypothesis is true. |
+| `you can't review your own work` | Ask a named reviewer. |
+| `… is published — its record is fixed` | Open a follow-up investigation and link to what you build on. |
+
+## Reading standing
+
+`active claim · checked (fisher:pass, v2) · 2 independent lines of support · replicated on new data · no external replication`
+
+- **review** — `unchecked`, `checked`, `contested`, or `review stale` (vN not yet re-checked).
+- **independent lines** — results sharing a run, data file or source count once.
+- **evidence** — the strongest line: unverified report < agent-reported run < lab-recorded run < reproduced in
+  project < separate implementation < replicated on new data < external source.
+- **AT RISK** — a premise fell. **REVISIT** — a decision's basis changed. **UNSUPPORTED** — every support fell.
+
+Report standing as the record states it. Don't upgrade "unchecked" to "shown", or "1 line, agent-reported" to
+"established".
+
+## Useful commands
+
+`hypgraph show NODE [--why|--impact|--history]` · `hypgraph work` · `hypgraph next` · `hypgraph revise NODE k=v --reason "…"`
+· `hypgraph withdraw NODE --why "…"` · `hypgraph export -o bundle.json` · `hypgraph verify [bundle.json]` ·
+`hypgraph serve` (the Atlas explorer) · `hypgraph schema` (every type and relation).

hypgraph/store.py

@@ -0,0 +1,139 @@
+"""
+Storage: one SQLite file, every table append-only (triggers refuse UPDATE and DELETE), every write an event in a
+SHA-256 hash chain. ``verify()`` recomputes the chain and checks each stored version body and edge against the event
+that wrote it, so an edit made to the file outside the library — even one that drops the triggers first — shows up.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import sqlite3
+from datetime import datetime, timezone
+from typing import Any
+
+SCHEMA = [
+    """CREATE TABLE IF NOT EXISTS nodes (id TEXT PRIMARY KEY, type TEXT NOT NULL, code TEXT NOT NULL DEFAULT '',
+        inv TEXT NOT NULL DEFAULT '', created_at TEXT NOT NULL, created_by TEXT NOT NULL)""",
+    """CREATE TABLE IF NOT EXISTS versions (node TEXT NOT NULL, v INTEGER NOT NULL, at TEXT NOT NULL,
+        by TEXT NOT NULL, reason TEXT NOT NULL DEFAULT '', body TEXT NOT NULL, PRIMARY KEY (node, v))""",
+    """CREATE TABLE IF NOT EXISTS edges (id INTEGER PRIMARY KEY AUTOINCREMENT, src TEXT NOT NULL, src_v INTEGER,
+        rel TEXT NOT NULL, dst TEXT NOT NULL, dst_v INTEGER, data TEXT NOT NULL DEFAULT '{}', at TEXT NOT NULL,
+        by TEXT NOT NULL, why TEXT NOT NULL DEFAULT '')""",
+    """CREATE TABLE IF NOT EXISTS retractions (edge INTEGER PRIMARY KEY, at TEXT NOT NULL, by TEXT NOT NULL,
+        why TEXT NOT NULL)""",
+    """CREATE TABLE IF NOT EXISTS withdrawals (node TEXT PRIMARY KEY, at TEXT NOT NULL, by TEXT NOT NULL,
+        why TEXT NOT NULL)""",
+    """CREATE TABLE IF NOT EXISTS leases (id INTEGER PRIMARY KEY AUTOINCREMENT, node TEXT NOT NULL, agent TEXT NOT NULL,
+        task TEXT NOT NULL DEFAULT '', kind TEXT NOT NULL, at TEXT NOT NULL, expires TEXT NOT NULL DEFAULT '',
+        note TEXT NOT NULL DEFAULT '')""",
+    """CREATE TABLE IF NOT EXISTS events (seq INTEGER PRIMARY KEY AUTOINCREMENT, at TEXT NOT NULL, actor TEXT NOT NULL,
+        kind TEXT NOT NULL, ref TEXT NOT NULL DEFAULT '', payload TEXT NOT NULL DEFAULT '{}', prev TEXT NOT NULL,
+        hash TEXT NOT NULL)""",
+    "CREATE INDEX IF NOT EXISTS idx_nodes_inv ON nodes(inv)",
+    "CREATE INDEX IF NOT EXISTS idx_nodes_inv_type ON nodes(inv, type)",
+    "CREATE INDEX IF NOT EXISTS idx_nodes_inv_code ON nodes(inv, code)",
+    "CREATE INDEX IF NOT EXISTS idx_events_actor ON events(actor, kind, at)",
+    "CREATE INDEX IF NOT EXISTS idx_edges_src ON edges(src)",
+    "CREATE INDEX IF NOT EXISTS idx_edges_dst ON edges(dst)",
+    "CREATE INDEX IF NOT EXISTS idx_leases_node ON leases(node, id)",
+]
+APPEND_ONLY = ("nodes", "versions", "edges", "retractions", "withdrawals", "leases", "events")
+GENESIS = "0" * 64
+
+
+def now() -> str:
+    return datetime.now(timezone.utc).isoformat(timespec="seconds")
+
+
+def canon(obj: Any) -> str:
+    """The canonical JSON every hash is taken over: sorted keys, no spaces, UTF-8 kept as is."""
+    return json.dumps(obj, sort_keys=True, ensure_ascii=False, separators=(",", ":"))
+
+
+def sha(text: str) -> str:
+    return hashlib.sha256(text.encode()).hexdigest()
+
+
+def event_body(at: str, actor: str, kind: str, ref: str, payload: dict, prev: str) -> str:
+    """The exact string an event's hash is over."""
+    return canon({"at": at, "actor": actor, "kind": kind, "ref": ref, "payload": payload, "prev": prev})
+
+
+class Conn(sqlite3.Connection):
+    """A connection kept open per thread (opening a file on a slow host mount costs ~0.2 s). close() is a no-op;
+    really_close() closes it."""
+    def close(self) -> None:  # noqa: D401
+        pass
+
+    def really_close(self) -> None:
+        super().close()
+
+
+def install(con: sqlite3.Connection, *, journal: str = "DELETE") -> None:
+    """Create the tables and the append-only triggers. A rollback journal by default: WAL's shared-memory file isn't
+    reliable on network and VM host mounts, where research data often lives."""
+    try:
+        con.execute(f"PRAGMA journal_mode={journal}")
+    except sqlite3.OperationalError:
+        pass
+    for stmt in SCHEMA:
+        con.execute(stmt)
+    for t in APPEND_ONLY:
+        for op in ("UPDATE", "DELETE"):
+            con.execute(f"CREATE TRIGGER IF NOT EXISTS {t}_no_{op.lower()} BEFORE {op} ON {t} "
+                        f"BEGIN SELECT RAISE(ABORT, '{t} is append-only'); END")
+
+
+def append_event(con: sqlite3.Connection, actor: str, kind: str, ref: str, payload: dict, at: str) -> int:
+    row = con.execute("SELECT hash FROM events ORDER BY seq DESC LIMIT 1").fetchone()
+    prev = row[0] if row else GENESIS
+    h = sha(event_body(at, actor, kind, ref, payload, prev))
+    cur = con.execute("INSERT INTO events (at, actor, kind, ref, payload, prev, hash) VALUES (?,?,?,?,?,?,?)",
+                      (at, actor, kind, ref, canon(payload), prev, h))
+    return cur.lastrowid
+
+
+def verify_connection(con: sqlite3.Connection) -> dict:
+    """Recompute every event hash, then check stored content against what the events recorded: each version body
+    against its create / revise / review event's body_sha, each edge against its link event, and that no row exists
+    without its event."""
+    prev, n = GENESIS, 0
+    bodies: dict[tuple, str] = {}
+    links: dict[int, dict] = {}
+    for r in con.execute("SELECT seq, at, actor, kind, ref, payload, prev, hash FROM events ORDER BY seq"):
+        seq, at, actor, kind, ref, payload_s, prev_s, h = r
+        payload = json.loads(payload_s)
+        if prev_s != prev or sha(event_body(at, actor, kind, ref, payload, prev)) != h:
+            return {"ok": False, "broken_at": seq, "checked": n, "problem": "event hash chain broken"}
+        prev, n = h, n + 1
+        if kind in ("create", "revise"):
+            bodies[(ref, int(payload.get("v", 1)))] = payload.get("body_sha", "")
+        elif kind == "review":
+            bodies[(payload["review"], 1)] = payload.get("body_sha", "")
+        elif kind == "link":
+            links[int(payload["edge"])] = payload
+    for node, v, body in con.execute("SELECT node, v, body FROM versions"):
+        want = bodies.get((node, v))
+        if want is None:
+            return {"ok": False, "checked": n, "problem": f"version {node} v{v} has no event"}
+        if sha(body) != want:
+            return {"ok": False, "checked": n, "problem": f"version {node} v{v} differs from its event"}
+    for eid, rel, dst, dst_v, data in con.execute("SELECT id, rel, dst, dst_v, data FROM edges"):
+        want = links.get(eid)
+        if want is None:
+            return {"ok": False, "checked": n, "problem": f"edge {eid} has no event"}
+        if (want.get("rel"), want.get("dst"), want.get("dst_v")) != (rel, dst, dst_v) or \
+                sha(data) != want.get("data_sha"):
+            return {"ok": False, "checked": n, "problem": f"edge {eid} differs from its event"}
+    return {"ok": True, "checked": n, "head": prev}
+
+
+def verify_file(path: str) -> dict:
+    """Verify a graph file read-only (a backup, a copy someone sent you) without opening it for writing."""
+    from pathlib import Path
+    con = sqlite3.connect(Path(path).resolve().as_uri() + "?mode=ro", uri=True)
+    try:
+        return verify_connection(con)
+    finally:
+        con.close()

hypgraph/ui/__init__.py

@@ -0,0 +1,7 @@
+"""The Atlas explorer's static files (atlas.js, atlas.css, vendored Cytoscape). A host serves ``static_dir()``."""
+
+from pathlib import Path
+
+
+def static_dir() -> Path:
+    return Path(__file__).parent