coding-os 0.3.2__py3-none-any.whl

core/graph_os/vec_index.py

@@ -0,0 +1,277 @@
+"""graph_os — ANN index over graph_node embeddings, with a fallback chain.
+
+Backends, in preference order:
+  1. usearch HNSW   — true sublinear O(log N) kNN; the scale answer (Wave 5).
+  2. sqlite-vec vec0 — SIMD-accelerated *exact* (flat) scan; ~5x faster than
+     numpy but still O(N) — a constant-factor win, not algorithmic (measured).
+  3. brute force    — the caller's streaming numpy scan (knn returns None).
+
+The ``embeddings`` BLOB table stays the source of truth; every index here is a
+derived cache, rebuilt from it. Each layer degrades cleanly to the next, so the
+``knn()`` contract holds regardless of what is installed.
+
+DEPENDS: usearch (optional), sqlite-vec (optional), the embeddings table.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import logging
+from pathlib import Path
+
+logger = logging.getLogger("graph_os.vec_index")
+
+_VEC_TABLE = "graph_vec"
+# Loaded usearch indexes, keyed by db-file path (or conn id for :memory:).
+# Value: (index, indexed_row_count) — count drives cheap staleness detection.
+_HNSW_CACHE: dict = {}
+
+
+# ---------------------------------------------------------------------------
+# Shared helpers
+# ---------------------------------------------------------------------------
+
+
+def _index_dim(conn) -> int | None:
+    row = conn.execute(
+        "SELECT LENGTH(embedding) FROM embeddings "
+        "WHERE source_table='graph_nodes' AND embedding IS NOT NULL LIMIT 1"
+    ).fetchone()
+    if not row or not row[0] or row[0] % 4:
+        return None
+    return row[0] // 4
+
+
+def _graph_node_count(conn) -> int:
+    try:
+        return conn.execute(
+            "SELECT COUNT(*) FROM embeddings WHERE source_table='graph_nodes'"
+        ).fetchone()[0]
+    except Exception:
+        return 0
+
+
+# ---------------------------------------------------------------------------
+# Backend 1 — usearch HNSW (sublinear)
+# ---------------------------------------------------------------------------
+
+
+def has_usearch() -> bool:
+    """True iff usearch + numpy are importable (the sublinear HNSW backend)."""
+    try:
+        import numpy  # noqa: F401
+        import usearch.index  # noqa: F401
+
+        return True
+    except ImportError:
+        return False
+
+
+def _db_file(conn) -> str:
+    try:
+        for _seq, name, file in conn.execute("PRAGMA database_list").fetchall():
+            if name == "main":
+                return file or ""
+    except Exception as exc:
+        logger.debug("db_file probe failed: %s", exc)
+    return ""
+
+
+def _hnsw_path(conn) -> str | None:
+    dbf = _db_file(conn)
+    if not dbf:
+        return None  # :memory: — no on-disk index, rebuild per process
+    return str(Path(dbf).with_name(".graph-hnsw.usearch"))
+
+
+def _hnsw_build(conn) -> dict:
+    import numpy as np
+    from usearch.index import Index
+
+    dim = _index_dim(conn)
+    if dim is None:
+        return {"status": "empty", "rows": 0}
+    idx = Index(ndim=dim, metric="cos", dtype="f32")
+    cur = conn.execute(
+        "SELECT source_id, embedding FROM embeddings WHERE source_table='graph_nodes'"
+    )
+    n = 0
+    while True:
+        batch = cur.fetchmany(4096)
+        if not batch:
+            break
+        keys, vecs = [], []
+        for sid, blob in batch:
+            if blob and len(blob) // 4 == dim:
+                keys.append(int(sid))
+                vecs.append(np.frombuffer(blob, dtype=np.float32))
+        if keys:
+            idx.add(np.array(keys, dtype=np.int64), np.vstack(vecs))
+            n += len(keys)
+    path = _hnsw_path(conn)
+    if path:
+        with contextlib.suppress(Exception):
+            idx.save(path)
+    _HNSW_CACHE[path or id(conn)] = (idx, n)
+    return {"status": "ok", "rows": n, "dim": dim, "backend": "usearch-hnsw"}
+
+
+def _hnsw_load(conn):
+    from usearch.index import Index
+
+    key = _hnsw_path(conn) or id(conn)
+    count = _graph_node_count(conn)
+    cached = _HNSW_CACHE.get(key)
+    if cached and cached[1] == count:
+        return cached[0]
+    path = _hnsw_path(conn)
+    if path and Path(path).exists():
+        try:
+            idx = Index.restore(path)
+            if idx is not None and len(idx) == count:
+                _HNSW_CACHE[key] = (idx, count)
+                return idx
+        except Exception as exc:
+            logger.debug("hnsw restore failed (%s); rebuilding", exc)
+    if _hnsw_build(conn).get("status") != "ok":
+        return None
+    entry = _HNSW_CACHE.get(key)
+    return entry[0] if entry else None
+
+
+def _hnsw_knn(conn, query_blob: bytes, k: int) -> list[tuple[int, float]] | None:
+    import numpy as np
+
+    try:
+        idx = _hnsw_load(conn)
+        if idx is None or len(idx) == 0:
+            return None
+        q = np.frombuffer(query_blob, dtype=np.float32)
+        res = idx.search(q, max(1, int(k)))
+        # usearch 'cos' returns cosine DISTANCE in [0,2]; similarity = 1 - dist.
+        return [(int(key), 1.0 - float(dist)) for key, dist in zip(res.keys, res.distances)]
+    except Exception as exc:
+        logger.debug("hnsw knn failed (%s); falling back", exc)
+        return None
+
+
+# ---------------------------------------------------------------------------
+# Backend 2 — sqlite-vec vec0 (flat SIMD exact)
+# ---------------------------------------------------------------------------
+
+
+def is_vec_available() -> bool:
+    """True iff sqlite-vec is importable and this python's sqlite3 can load it."""
+    try:
+        import sqlite3
+
+        import sqlite_vec  # noqa: F401
+
+        return hasattr(sqlite3.Connection, "enable_load_extension")
+    except ImportError:
+        return False
+
+
+def ensure_loaded(conn) -> bool:
+    """Load the sqlite-vec extension into conn. Returns True on success."""
+    if not is_vec_available():
+        return False
+    try:
+        import sqlite_vec
+
+        conn.enable_load_extension(True)
+        sqlite_vec.load(conn)
+        conn.enable_load_extension(False)
+        return True
+    except Exception as exc:
+        logger.debug("sqlite-vec load failed: %s", exc)
+        return False
+
+
+def _vec0_exists(conn) -> bool:
+    return (
+        conn.execute(
+            "SELECT 1 FROM sqlite_master WHERE type='table' AND name=?", (_VEC_TABLE,)
+        ).fetchone()
+        is not None
+    )
+
+
+def _vec0_build(conn) -> dict:
+    if not ensure_loaded(conn):
+        return {"status": "unavailable", "rows": 0}
+    dim = _index_dim(conn)
+    if dim is None:
+        return {"status": "empty", "rows": 0}
+    conn.execute(f"DROP TABLE IF EXISTS {_VEC_TABLE}")
+    conn.execute(f"CREATE VIRTUAL TABLE {_VEC_TABLE} USING vec0(embedding float[{dim}])")
+    n = 0
+    cur = conn.execute(
+        "SELECT source_id, embedding FROM embeddings WHERE source_table='graph_nodes'"
+    )
+    while True:
+        batch = cur.fetchmany(2000)
+        if not batch:
+            break
+        for sid, blob in batch:
+            if blob and len(blob) // 4 == dim:
+                conn.execute(
+                    f"INSERT INTO {_VEC_TABLE}(rowid, embedding) VALUES (?, ?)", (sid, blob)
+                )
+                n += 1
+    conn.commit()
+    return {"status": "ok", "rows": n, "dim": dim, "backend": "sqlite-vec"}
+
+
+def _vec0_knn(conn, query_blob: bytes, k: int) -> list[tuple[int, float]] | None:
+    if not ensure_loaded(conn):
+        return None
+    try:
+        if not _vec0_exists(conn) and _vec0_build(conn).get("status") != "ok":
+            return None
+        rows = conn.execute(
+            f"SELECT rowid, distance FROM {_VEC_TABLE} "
+            "WHERE embedding MATCH ? ORDER BY distance LIMIT ?",
+            (query_blob, max(1, int(k))),
+        ).fetchall()
+    except Exception as exc:
+        logger.debug("vec0 knn failed (%s); caller falls back to brute force", exc)
+        return None
+    # Unit-normalised vectors: vec0 L2 distance d → cosine = 1 - d²/2.
+    return [(int(r[0]), 1.0 - (float(r[1]) ** 2) / 2.0) for r in rows]
+
+
+# ---------------------------------------------------------------------------
+# Public API — dispatch across the fallback chain
+# ---------------------------------------------------------------------------
+
+
+def rebuild(conn) -> dict:
+    """(Re)build the best available ANN index from graph_node embeddings."""
+    if has_usearch():
+        return _hnsw_build(conn)
+    return _vec0_build(conn)
+
+
+def knn(conn, query_blob: bytes, k: int) -> list[tuple[int, float]] | None:
+    """kNN over graph_node vectors → [(graph_nodes.id, cosine_similarity)].
+
+    Tries usearch HNSW (sublinear) → sqlite-vec flat → None (caller brute-forces).
+    Builds the chosen index lazily on first use.
+    """
+    if not query_blob:
+        return None
+    if has_usearch():
+        out = _hnsw_knn(conn, query_blob, k)
+        if out is not None:
+            return out
+    return _vec0_knn(conn, query_blob, k)
+
+
+__all__ = [
+    "has_usearch",
+    "is_vec_available",
+    "ensure_loaded",
+    "rebuild",
+    "knn",
+]

core/graph_os/viewer/__init__.py

@@ -0,0 +1,12 @@
+# DEPRECATED for human use (S5, 2026-04-21): superseded by core/web/ui/ React SPA. Kept for `cos graph-viz` CLI compat through S6.
+"""graph_os HTML viewer (I.10).
+
+Builds a self-contained HTML page backed by Sigma.js + Graphology for
+WebGL rendering. The exporter lives in `exporter.py`; the HTML
+template in `template.py`. A pure-Python accessibility list-view is
+rendered server-side so screen readers have a meaningful fallback.
+"""
+
+from .exporter import ViewerExporter, build_view
+
+__all__ = ["ViewerExporter", "build_view"]

core/graph_os/viewer/exporter.py

@@ -0,0 +1,93 @@
+"""graph_os viewer exporter (I.10).
+
+DEPENDS:  stdlib + template.py + backend.
+"""
+
+from __future__ import annotations
+
+import secrets
+from collections.abc import Sequence
+from dataclasses import dataclass
+from pathlib import Path
+
+from ..backend import GraphBackend
+from ..types import GraphEdge, GraphNode
+from .template import render
+
+
+@dataclass
+class ViewerExporter:
+    backend: GraphBackend
+    title: str = "graph_os"
+    max_nodes: int = 500
+    max_edges: int = 2000
+    bundled: bool = False
+
+    def collect(
+        self,
+        *,
+        root_uid: str | None = None,
+        edge_types: Sequence[str] | None = None,
+    ) -> tuple[list[GraphNode], list[GraphEdge]]:
+        if root_uid is not None:
+            # Walk up to max_nodes via BFS.
+            from ..tools.graph import _walk_bfs  # local import to avoid cycle
+
+            nodes, edges = _walk_bfs(
+                self.backend,
+                root_uid=root_uid,
+                direction="both",
+                max_hops=3,
+                confidence_min=0.0,
+                edge_types=edge_types,
+                visit_limit=self.max_nodes,
+            )
+            return nodes, edges[: self.max_edges]
+        edges = self.backend.list_edges(edge_types=edge_types, limit=self.max_edges)
+        uids: set[str] = set()
+        for e in edges:
+            uids.add(e.source_uid)
+            uids.add(e.target_uid)
+        nodes = [n for n in (self.backend.get_node(u) for u in uids) if n is not None]
+        return nodes[: self.max_nodes], edges
+
+    def export(
+        self,
+        path: str | Path,
+        *,
+        root_uid: str | None = None,
+        edge_types: Sequence[str] | None = None,
+    ) -> Path:
+        nodes, edges = self.collect(root_uid=root_uid, edge_types=edge_types)
+        nonce = secrets.token_urlsafe(16)
+        html_out = render(
+            nodes,
+            edges,
+            title=self.title,
+            nonce=nonce,
+            bundled=self.bundled,
+        )
+        out_path = Path(path)
+        out_path.parent.mkdir(parents=True, exist_ok=True)
+        out_path.write_text(html_out, encoding="utf-8")
+        return out_path
+
+
+def build_view(
+    backend: GraphBackend,
+    out_path: str | Path,
+    *,
+    title: str = "graph_os",
+    root_uid: str | None = None,
+    edge_types: Sequence[str] | None = None,
+    bundled: bool = False,
+) -> Path:
+    exporter = ViewerExporter(
+        backend=backend,
+        title=title,
+        bundled=bundled,
+    )
+    return exporter.export(out_path, root_uid=root_uid, edge_types=edge_types)
+
+
+__all__ = ["ViewerExporter", "build_view"]

core/graph_os/viewer/template.py

@@ -0,0 +1,189 @@
+"""graph_os viewer template (I.10) — Sigma.js + Graphology + CSP nonce.
+
+DEPENDS:  stdlib only.
+"""
+
+from __future__ import annotations
+
+import html
+import json
+from collections.abc import Iterable
+
+from ..types import GraphEdge, GraphNode
+
+_CDN_DEPS = [
+    (
+        "https://cdn.jsdelivr.net/npm/graphology@0.25.4/dist/graphology.umd.min.js",
+        "graphology",
+    ),
+    (
+        "https://cdn.jsdelivr.net/npm/graphology-layout-forceatlas2@0.10.1/"
+        "umd/graphology-layout-forceatlas2.min.js",
+        "forceatlas2",
+    ),
+    (
+        "https://cdn.jsdelivr.net/npm/sigma@3.0.0/dist/sigma.min.js",
+        "sigma",
+    ),
+]
+
+_STYLE = """
+  html, body { margin: 0; height: 100%; font: 14px/1.4 system-ui, sans-serif; background: #0e1116; color: #e6e7eb; }
+  main { display: grid; grid-template-columns: 1fr 320px; grid-template-rows: 48px 1fr; height: 100vh; }
+  header { grid-column: 1 / -1; display: flex; align-items: center; gap: 12px; padding: 0 16px; background: #1b1f27; border-bottom: 1px solid #2a2f39; }
+  #canvas { position: relative; background: #11151c; }
+  aside { padding: 16px; background: #151a22; border-left: 1px solid #2a2f39; overflow: auto; }
+  .badge { font-size: 11px; padding: 2px 6px; border-radius: 4px; background: #2a2f39; color: #9ea4ae; }
+  ul.a11y { list-style: none; padding-left: 0; margin: 0; font-size: 12px; }
+  ul.a11y li { padding: 4px 0; border-bottom: 1px solid #1f242c; }
+  .edge-type { color: #7fd4a0; }
+  .node-kind { color: #c68fff; }
+  details > summary { cursor: pointer; padding: 4px 0; }
+"""
+
+
+def render(
+    nodes: Iterable[GraphNode],
+    edges: Iterable[GraphEdge],
+    *,
+    title: str,
+    nonce: str,
+    bundled: bool = False,
+) -> str:
+    """Return the final HTML document."""
+    node_list = list(nodes)
+    edge_list = list(edges)
+    payload = {
+        "nodes": [_node_to_public(n) for n in node_list],
+        "edges": [_edge_to_public(e) for e in edge_list],
+    }
+    payload_json = json.dumps(payload, separators=(",", ":"), default=str)
+
+    cdn_host = "'self'" if bundled else "https://cdn.jsdelivr.net"
+    csp = (
+        "default-src 'none'; "
+        f"script-src 'nonce-{nonce}' {cdn_host}; "
+        f"style-src 'nonce-{nonce}'; "
+        "img-src 'self' data:; "
+        "connect-src 'self'; "
+        "font-src 'self'; "
+        "base-uri 'none'; "
+        "frame-ancestors 'none';"
+    )
+    scripts = "\n".join(
+        f'  <script nonce="{nonce}" src="{url}" crossorigin="anonymous"></script>'
+        for url, _ in _CDN_DEPS
+    )
+    a11y_html = _render_a11y(node_list, edge_list)
+
+    return (
+        "<!doctype html>\n"
+        '<html lang="en">\n'
+        "<head>\n"
+        '  <meta charset="utf-8">\n'
+        f'  <meta http-equiv="Content-Security-Policy" content="{csp}">\n'
+        f"  <title>{html.escape(title)}</title>\n"
+        f'  <style nonce="{nonce}">{_STYLE}</style>\n'
+        "</head>\n"
+        "<body>\n"
+        "  <main>\n"
+        f"    <header><strong>{html.escape(title)}</strong>"
+        f' <span class="badge">nodes: {len(node_list)}</span>'
+        f' <span class="badge">edges: {len(edge_list)}</span></header>\n'
+        '    <div id="canvas" role="img" aria-label="graph canvas"></div>\n'
+        '    <aside aria-label="accessible graph listing">\n' + a11y_html + "    </aside>\n"
+        "  </main>\n" + scripts + "\n"
+        f'  <script type="application/json" id="graph-data">{payload_json}</script>\n'
+        f'  <script nonce="{nonce}">{_BOOTSTRAP_JS}</script>\n'
+        "</body>\n"
+        "</html>\n"
+    )
+
+
+_BOOTSTRAP_JS = """
+  (function() {
+    var el = document.getElementById('graph-data');
+    if (!el) return;
+    var data;
+    try { data = JSON.parse(el.textContent || '{}'); } catch (e) { return; }
+    if (typeof graphology === 'undefined' || typeof Sigma === 'undefined') return;
+    var g = new graphology.Graph();
+    (data.nodes || []).forEach(function(n) {
+      try {
+        g.addNode(n.uid, {
+          label: n.label,
+          size: 4,
+          x: Math.random(),
+          y: Math.random(),
+          color: kindColor(n.kind)
+        });
+      } catch (e) { /* duplicate uid — ignore */ }
+    });
+    (data.edges || []).forEach(function(e) {
+      try {
+        g.addEdgeWithKey(
+          e.source + '->' + e.target + ':' + e.edge_type,
+          e.source, e.target,
+          { label: e.edge_type, color: '#444a55' }
+        );
+      } catch (err) { /* missing endpoints — ignore */ }
+    });
+    new Sigma(g, document.getElementById('canvas'));
+    function kindColor(kind) {
+      if (!kind) return '#888';
+      if (kind.indexOf('doc:') === 0) return '#5aa8ff';
+      if (kind.indexOf('task:') === 0) return '#ffa64d';
+      if (kind.indexOf('cos:') === 0) return '#c68fff';
+      return '#7fd4a0';
+    }
+  })();
+"""
+
+
+def _node_to_public(node: GraphNode) -> dict:
+    return {
+        "uid": node.uid,
+        "kind": node.kind,
+        "label": node.label,
+        "file_path": node.file_path,
+        "start_line": node.start_line,
+    }
+
+
+def _edge_to_public(edge: GraphEdge) -> dict:
+    return {
+        "source": edge.source_uid,
+        "target": edge.target_uid,
+        "edge_type": edge.edge_type,
+        "confidence": edge.confidence,
+    }
+
+
+def _render_a11y(nodes: list[GraphNode], edges: list[GraphEdge]) -> str:
+    """Serve a list-view fallback for screen readers / no-WebGL."""
+    by_uid = {n.uid: n for n in nodes}
+    items: list[str] = []
+    for node in nodes:
+        outgoing = [e for e in edges if e.source_uid == node.uid]
+        lines = [
+            f'<li><details><summary><span class="node-kind">{html.escape(node.kind)}</span> '
+            f"— {html.escape(node.label or node.uid)}</summary>"
+        ]
+        if outgoing:
+            lines.append("<ul>")
+            for e in outgoing:
+                target = by_uid.get(e.target_uid)
+                target_label = target.label if target and target.label else e.target_uid
+                lines.append(
+                    f'<li><span class="edge-type">{html.escape(e.edge_type)}</span>'
+                    f" → {html.escape(target_label)}</li>"
+                )
+            lines.append("</ul>")
+        else:
+            lines.append('<div class="badge">no outgoing edges</div>')
+        lines.append("</details></li>")
+        items.append("".join(lines))
+    return '<ul class="a11y">' + "".join(items) + "</ul>"
+
+
+__all__ = ["render"]

core/hooks/_helpers/_paths.py

@@ -0,0 +1,40 @@
+"""Shared project-root resolver for hook helpers (no DB import on the hot path).
+
+Hooks fire on every Write/Edit; importing thinking_os.database costs ~20-60ms.
+Since cos-env.sh already sets COS_STATE_DIR (absolute), tiers 1-2 answer without
+that import — tier 3 (lazy database.project_root) only runs in the rare case
+where neither env var is set, and tier 4 (cwd) is the fail-open last resort.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+
+def resolve_project_root() -> Path:
+    explicit = os.environ.get("COS_PROJECT_ROOT")
+    if explicit:
+        return Path(explicit).resolve()
+
+    state = os.environ.get("COS_STATE_DIR")
+    if state:
+        state_path = Path(state)
+        if state_path.is_absolute():
+            parent = state_path.resolve().parent
+            # $HOME hard-stop: COS_STATE_DIR == $HOME/.coding-os is the global
+            # hub (set by `cos hub`), not a project root. Mirrors the boundary
+            # in database.project_root() + cos-env.sh::_cos_find_project_root.
+            try:
+                home = Path.home().resolve()
+            except (OSError, RuntimeError):
+                home = None
+            if home is None or parent != home:
+                return parent
+
+    try:
+        from thinking_os.database import project_root as _resolve_root  # type: ignore
+
+        return _resolve_root()
+    except ImportError:
+        return Path.cwd().resolve()

core/hooks/_helpers/advance_role.py

@@ -0,0 +1,72 @@
+"""Advance the active role (.role) along the composed chain by work phase.
+
+Called by advance-role.sh (PostToolUse). Maps the tool just used to a work
+phase and asks roles_state.advance_role to set .role to the chain member that
+best matches — so the banner's roles= field reflects what the agent is DOING
+(analyze → build → verify), not a frozen chain lead (TASK-057 F2.3).
+
+Prints the new active role (for the hook log); prints nothing on no-op.
+
+USAGE
+    python3 advance_role.py <tool_name> <target_dir> [bash_command]
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+import sys
+from pathlib import Path
+
+logger = logging.getLogger("advance_role")
+
+_THIS = Path(__file__).resolve()
+_THINKING_OS = _THIS.parents[2] / "thinking_os"
+if _THINKING_OS.is_dir() and str(_THINKING_OS) not in sys.path:
+    sys.path.insert(0, str(_THINKING_OS))
+
+# Bash commands that signal a verification phase (tests, linters, type checks).
+_VERIFY_CMD = re.compile(
+    r"\b(pytest|jest|vitest|go test|make (?:verify|test)|"
+    r"npm test|ruff|mypy|eslint|tsc|coverage|verify-hooks)\b"
+)
+
+
+def _phase_for(tool: str, command: str, file_path: str = "") -> str | None:
+    if tool in ("Write", "Edit", "MultiEdit"):
+        # A doc/markdown write is a documentation phase; code edits are build.
+        fp = (file_path or "").lower()
+        if fp.endswith((".md", ".mdx", ".rst", ".txt")) or "/docs/" in fp:
+            return "doc"
+        return "edit"
+    if tool == "Bash" and command and _VERIFY_CMD.search(command):
+        return "verify"
+    return None
+
+
+def main(argv: list[str]) -> int:
+    if len(argv) < 3:
+        return 0
+    tool = argv[1] or ""
+    target_dir = argv[2] or None
+    command = argv[3] if len(argv) > 3 else ""
+    file_path = argv[4] if len(argv) > 4 else ""
+
+    phase = _phase_for(tool, command, file_path)
+    if phase is None:
+        return 0
+
+    try:
+        import roles_state
+    except ImportError as exc:
+        logger.debug("roles_state import unavailable: %s", exc)
+        return 0
+
+    chosen = roles_state.advance_role(phase, target_dir)
+    if chosen:
+        print(chosen)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv))