drydock-cli 2.8.15__tar.gz → 2.8.16__tar.gz

drydock_cli-2.8.16/.auto_release.lock

@@ -0,0 +1 @@
+542177

{drydock_cli-2.8.15 → drydock_cli-2.8.16}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: drydock-cli
-Version: 2.8.15
+Version: 2.8.16
 Summary: Local-first CLI coding agent — tested with Gemma 4 26B via vLLM
 Project-URL: Homepage, https://github.com/fbobe321/drydock
 Project-URL: Repository, https://github.com/fbobe321/drydock

{drydock_cli-2.8.15 → drydock_cli-2.8.16}/drydock/graphrag/__main__.py

@@ -58,6 +58,26 @@ def _build_parser() -> argparse.ArgumentParser:
 
     sub.add_parser("stats", help="Show DB counts")
 
+    sp_we = sub.add_parser(
+        "worked_example",
+        help="Manage worked examples (problem + reasoning chain + answer)",
+    )
+    we_sub = sp_we.add_subparsers(dest="we_cmd", required=True)
+
+    sp_we_add = we_sub.add_parser(
+        "add", help="Add a worked example from a JSON file"
+    )
+    sp_we_add.add_argument(
+        "json_path",
+        help=(
+            "Path to a JSON file with keys: problem_text, reasoning_steps "
+            "(list[str]), final_answer, optional category, subject, source"
+        ),
+    )
+
+    sp_we_list = we_sub.add_parser("list", help="List worked examples")
+    sp_we_list.add_argument("--limit", type=int, default=20)
+
     return p
 
 
@@ -110,10 +130,43 @@ def main(argv: list[str] | None = None) -> int:
             f"symbols: {s['symbols']}\n"
             f"text chunks: {s['chunks']}\n"
             f"unique terms: {s['unique_terms']}\n"
+            f"worked examples: {s.get('worked_examples', 0)}\n"
             f"DB: {args.db}"
         )
         return 0
 
+    if args.cmd == "worked_example":
+        if args.we_cmd == "add":
+            import json as _json
+            payload = _json.loads(Path(args.json_path).read_text())
+            problem = payload.get("problem_text", "").strip()
+            steps = payload.get("reasoning_steps", [])
+            answer = payload.get("final_answer", "").strip()
+            if not problem or not answer:
+                print("ERROR: problem_text and final_answer are required",
+                      file=sys.stderr)
+                return 2
+            eid = idx.ingest_worked_example(
+                problem_text=problem,
+                reasoning_steps=list(steps),
+                final_answer=answer,
+                category=payload.get("category", ""),
+                subject=payload.get("subject", ""),
+                source=payload.get("source", "manual"),
+            )
+            print(f"Ingested worked example id={eid} (source={payload.get('source','manual')})")
+            return 0
+        if args.we_cmd == "list":
+            hits = idx.list_worked_examples(limit=args.limit)
+            if not hits:
+                print("(no worked examples)")
+                return 1
+            for h in hits:
+                print(h.format())
+                print()
+            return 0
+        return 1
+
     return 1
 
 

{drydock_cli-2.8.15 → drydock_cli-2.8.16}/drydock/graphrag/retriever.py

@@ -61,17 +61,56 @@ class TextHit:
         return f"{head}\n{body}"
 
 
+@dataclass(frozen=True)
+class WorkedExampleHit:
+    """A previously-solved problem with its full reasoning chain.
+
+    The "second brain" payload — when the model retrieves this, it sees
+    not just facts but how a similar problem was worked through:
+    intermediate steps, mistakes corrected, the final answer. Closer to
+    how a human reasons by analogy than flat-chunk retrieval.
+    """
+    problem_text: str         # the original problem statement
+    category: str             # e.g. "Physics", "Math" — coarse domain
+    subject: str              # finer subdomain, e.g. "holographic-models"
+    reasoning_steps: tuple[str, ...]   # ordered: first step → last step
+    final_answer: str
+    source: str               # where it came from: "hle:<id>", "manual", "session:<sid>"
+    score: float              # backend-defined; higher == more relevant
+    citation_id: str = ""
+
+    def format(self) -> str:
+        head = (
+            f"[worked example] {self.category}"
+            + (f" / {self.subject}" if self.subject else "")
+            + f" (score={self.score:.3f}) source={self.source}"
+        )
+        body_lines = [head, "Problem:", "  " + self.problem_text.strip()[:500]]
+        if self.reasoning_steps:
+            body_lines.append("Reasoning:")
+            for i, step in enumerate(self.reasoning_steps, 1):
+                body_lines.append(f"  {i}. {step.strip()[:300]}")
+        body_lines.append(f"Answer: {self.final_answer.strip()[:200]}")
+        return "\n".join(body_lines)
+
+
 @dataclass
 class RetrievalResult:
-    """Output of a retrieve() call. Either or both lists may be empty."""
+    """Output of a retrieve() call. Any subset of lists may be empty."""
     symbols: list[SymbolHit] = field(default_factory=list)
     text: list[TextHit] = field(default_factory=list)
+    worked_examples: list[WorkedExampleHit] = field(default_factory=list)
 
     def is_empty(self) -> bool:
-        return not self.symbols and not self.text
+        return not self.symbols and not self.text and not self.worked_examples
 
     def format(self) -> str:
         sections: list[str] = []
+        # Worked examples first — they're the highest-signal payload when
+        # they match. The model's prompt-attention is biased to the start.
+        if self.worked_examples:
+            sections.append("=== WORKED EXAMPLES ===")
+            sections.extend(h.format() for h in self.worked_examples)
         if self.symbols:
             sections.append("=== SYMBOLS ===")
             sections.extend(h.format() for h in self.symbols)

{drydock_cli-2.8.15 → drydock_cli-2.8.16}/drydock/graphrag/storage.py

@@ -33,11 +33,15 @@ from contextlib import contextmanager
 from pathlib import Path
 from typing import Iterable, Iterator
 
+import json
+from datetime import datetime, timezone
+
 from drydock.graphrag.code_indexer import SymbolRecord, index_path as index_code
 from drydock.graphrag.retriever import (
     RetrievalResult,
     SymbolHit,
     TextHit,
+    WorkedExampleHit,
 )
 from drydock.graphrag.text_indexer import TextChunk, index_path as index_text
 
@@ -85,6 +89,47 @@ CREATE TABLE IF NOT EXISTS meta (
     key TEXT PRIMARY KEY,
     value TEXT NOT NULL
 );
+
+-- "Second brain" payload: previously-solved problems with full reasoning
+-- chains. The model retrieves these alongside flat-chunk text so it sees
+-- not just facts but how analogous problems were worked through.
+CREATE TABLE IF NOT EXISTS worked_examples (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    problem_text TEXT NOT NULL,
+    category TEXT NOT NULL DEFAULT '',
+    subject TEXT NOT NULL DEFAULT '',
+    -- JSON-encoded list[str]; ordered first→last reasoning step
+    reasoning_json TEXT NOT NULL DEFAULT '[]',
+    final_answer TEXT NOT NULL DEFAULT '',
+    -- Provenance: "manual", "hle:<qid>", "session:<sid>", etc.
+    source TEXT NOT NULL DEFAULT 'manual',
+    created_at TEXT NOT NULL,
+    -- Dedup key: same problem text + same source = single canonical row.
+    UNIQUE(problem_text, source)
+);
+CREATE INDEX IF NOT EXISTS idx_worked_examples_category
+    ON worked_examples(category);
+CREATE INDEX IF NOT EXISTS idx_worked_examples_source
+    ON worked_examples(source);
+
+-- TF-IDF on the *problem statement only* (not the reasoning chain). We
+-- want a query like "Gauss-Bonnet coupling holographic D3/D7" to match
+-- problems that share that physical setup, not problems whose answer
+-- chains happen to mention "Gauss" downstream.
+CREATE TABLE IF NOT EXISTS worked_example_terms (
+    example_id INTEGER NOT NULL,
+    term TEXT NOT NULL,
+    tf INTEGER NOT NULL,
+    PRIMARY KEY (example_id, term),
+    FOREIGN KEY (example_id) REFERENCES worked_examples(id) ON DELETE CASCADE
+);
+CREATE INDEX IF NOT EXISTS idx_worked_example_terms_term
+    ON worked_example_terms(term);
+
+CREATE TABLE IF NOT EXISTS worked_example_df (
+    term TEXT PRIMARY KEY,
+    df INTEGER NOT NULL
+);
 """
 
 # Token regex: word chars + apostrophe. Lowercased, length-filtered.
@@ -316,6 +361,7 @@ class Index:
         *,
         symbol_limit: int = 5,
         text_limit: int = 5,
+        worked_example_limit: int = 3,
     ) -> RetrievalResult:
         symbols: list[SymbolHit] = []
         # Heuristic: if the query is one or two CamelCase / snake_case
@@ -325,9 +371,11 @@ class Index:
             for tok in tokens[:1]:
                 symbols.extend(self.find_symbol(tok)[:symbol_limit])
         text = self._retrieve_text(query, text_limit)
+        examples = self._retrieve_worked_examples(query, worked_example_limit)
         return RetrievalResult(
             symbols=symbols[:symbol_limit],
             text=text,
+            worked_examples=examples,
         )
 
     def _retrieve_text(self, query: str, limit: int) -> list[TextHit]:
@@ -427,6 +475,182 @@ class Index:
             ))
         return out
 
+    # ------------------------------------------------------------------
+    # Worked examples ("second brain")
+    # ------------------------------------------------------------------
+
+    def ingest_worked_example(
+        self,
+        *,
+        problem_text: str,
+        reasoning_steps: list[str],
+        final_answer: str,
+        category: str = "",
+        subject: str = "",
+        source: str = "manual",
+    ) -> int:
+        """Insert a single worked example. Returns the row id (or the
+        existing id if (problem_text, source) already in the table).
+
+        TF-IDF tokens are computed from `problem_text` only — the
+        reasoning chain isn't searched, since we want similarity on the
+        problem statement, not on the answer text."""
+        if not problem_text.strip():
+            raise ValueError("problem_text cannot be empty")
+        if not isinstance(reasoning_steps, list):
+            raise TypeError("reasoning_steps must be a list[str]")
+        now = datetime.now(timezone.utc).isoformat(timespec="seconds")
+        with self._connect() as cx:
+            cur = cx.execute(
+                """INSERT OR IGNORE INTO worked_examples
+                   (problem_text, category, subject, reasoning_json,
+                    final_answer, source, created_at)
+                   VALUES (?, ?, ?, ?, ?, ?, ?)""",
+                (
+                    problem_text,
+                    category,
+                    subject,
+                    json.dumps(list(reasoning_steps)),
+                    final_answer,
+                    source,
+                    now,
+                ),
+            )
+            if cur.rowcount == 0:
+                # Already present — return the existing id.
+                row = cx.execute(
+                    "SELECT id FROM worked_examples WHERE problem_text = ? AND source = ?",
+                    (problem_text, source),
+                ).fetchone()
+                return int(row[0]) if row else -1
+            example_id = int(cur.lastrowid)
+            tokens = _tokenize(problem_text)
+            term_freq = Counter(tokens)
+            for term, tf in term_freq.items():
+                cx.execute(
+                    """INSERT INTO worked_example_terms
+                       (example_id, term, tf) VALUES (?, ?, ?)""",
+                    (example_id, term, tf),
+                )
+            self._recompute_worked_df(cx)
+        return example_id
+
+    def _recompute_worked_df(self, cx: sqlite3.Connection) -> None:
+        cx.execute("DELETE FROM worked_example_df")
+        cx.execute(
+            """INSERT INTO worked_example_df(term, df)
+               SELECT term, COUNT(DISTINCT example_id) FROM worked_example_terms
+               GROUP BY term"""
+        )
+
+    def list_worked_examples(self, *, limit: int = 50) -> list[WorkedExampleHit]:
+        """Return all worked examples (most recent first), with score=0.0."""
+        with self._connect() as cx:
+            rows = cx.execute(
+                """SELECT problem_text, category, subject, reasoning_json,
+                          final_answer, source, id
+                   FROM worked_examples
+                   ORDER BY created_at DESC
+                   LIMIT ?""",
+                (limit,),
+            ).fetchall()
+        return [self._row_to_worked_example(r, score=0.0) for r in rows]
+
+    def _retrieve_worked_examples(
+        self, query: str, limit: int
+    ) -> list[WorkedExampleHit]:
+        if limit <= 0:
+            return []
+        q_tokens = _tokenize_query(query)
+        if not q_tokens:
+            q_tokens = _tokenize(query)
+        if not q_tokens:
+            return []
+
+        with self._connect() as cx:
+            n_row = cx.execute(
+                "SELECT COUNT(*) FROM worked_examples"
+            ).fetchone()
+            n = int(n_row[0]) if n_row else 0
+            if n == 0:
+                return []
+
+            placeholders = ",".join("?" for _ in q_tokens)
+            df_rows = cx.execute(
+                f"SELECT term, df FROM worked_example_df WHERE term IN ({placeholders})",
+                tuple(q_tokens),
+            ).fetchall()
+            df = {term: cnt for term, cnt in df_rows}
+            if not df:
+                return []
+
+            q_idf = {
+                term: math.log((n + 1) / (df.get(term, 0) + 1)) + 1.0
+                for term in q_tokens
+            }
+
+            cand_rows = cx.execute(
+                f"""SELECT DISTINCT example_id FROM worked_example_terms
+                    WHERE term IN ({placeholders})""",
+                tuple(q_tokens),
+            ).fetchall()
+            cand_ids = [r[0] for r in cand_rows]
+            if not cand_ids:
+                return []
+
+            scored: list[tuple[int, float]] = []
+            for eid in cand_ids:
+                rows = cx.execute(
+                    "SELECT term, tf FROM worked_example_terms WHERE example_id = ?",
+                    (eid,),
+                ).fetchall()
+                tf_map = {term: tf for term, tf in rows}
+                score = sum(
+                    tf_map.get(term, 0) * q_idf.get(term, 0.0)
+                    for term in q_tokens
+                )
+                if score > 0:
+                    scored.append((eid, score))
+            scored.sort(key=lambda x: x[1], reverse=True)
+            top = scored[:limit]
+            if not top:
+                return []
+
+            ids_clause = ",".join("?" for _ in top)
+            rows = cx.execute(
+                f"""SELECT problem_text, category, subject, reasoning_json,
+                           final_answer, source, id
+                    FROM worked_examples WHERE id IN ({ids_clause})""",
+                tuple(eid for eid, _ in top),
+            ).fetchall()
+
+        score_by_id = dict(top)
+        out: list[WorkedExampleHit] = []
+        for r in rows:
+            eid = int(r[6])
+            out.append(self._row_to_worked_example(r, score=score_by_id.get(eid, 0.0)))
+        # Re-sort because the IN clause doesn't preserve scoring order.
+        out.sort(key=lambda h: h.score, reverse=True)
+        return out
+
+    @staticmethod
+    def _row_to_worked_example(row: tuple, *, score: float) -> WorkedExampleHit:
+        problem_text, category, subject, reasoning_json, final_answer, source, eid = row
+        try:
+            steps = tuple(json.loads(reasoning_json))
+        except (json.JSONDecodeError, TypeError):
+            steps = ()
+        return WorkedExampleHit(
+            problem_text=problem_text,
+            category=category or "",
+            subject=subject or "",
+            reasoning_steps=steps,
+            final_answer=final_answer or "",
+            source=source or "manual",
+            score=float(score),
+            citation_id=f"worked_example:{eid}",
+        )
+
     # ------------------------------------------------------------------
     # Stats / admin
     # ------------------------------------------------------------------
@@ -436,4 +660,12 @@ class Index:
             symbols = cx.execute("SELECT COUNT(*) FROM symbols").fetchone()[0]
             chunks = cx.execute("SELECT COUNT(*) FROM text_chunks").fetchone()[0]
             terms = cx.execute("SELECT COUNT(*) FROM text_df").fetchone()[0]
-        return {"symbols": symbols, "chunks": chunks, "unique_terms": terms}
+            worked = cx.execute(
+                "SELECT COUNT(*) FROM worked_examples"
+            ).fetchone()[0]
+        return {
+            "symbols": symbols,
+            "chunks": chunks,
+            "unique_terms": terms,
+            "worked_examples": worked,
+        }

{drydock_cli-2.8.15 → drydock_cli-2.8.16}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "drydock-cli"
-version = "2.8.15"
+version = "2.8.16"
 description = "Local-first CLI coding agent — tested with Gemma 4 26B via vLLM"
 readme = "README.md"
 requires-python = ">=3.12"

drydock_cli-2.8.16/tests/test_graphrag_worked_examples.py

@@ -0,0 +1,173 @@
+"""Phase 1 of the GraphRAG-as-second-brain plan: worked examples.
+
+These tests pin the contract for the new worked_examples table, ingest
+path, and TF-IDF retrieval scored on problem-text similarity.
+"""
+from __future__ import annotations
+
+import json
+
+import pytest
+
+from drydock.graphrag.retriever import RetrievalResult, WorkedExampleHit
+from drydock.graphrag.storage import Index
+
+
+def _make_index(tmp_path) -> Index:
+    return Index(tmp_path / "test.sqlite")
+
+
+def test_ingest_returns_id_and_persists(tmp_path):
+    idx = _make_index(tmp_path)
+    eid = idx.ingest_worked_example(
+        problem_text="What is the critical chemical potential in Einstein-Gauss-Bonnet holography?",
+        reasoning_steps=[
+            "Identify the bulk metric: Einstein-Gauss-Bonnet in 5D.",
+            "Set up the probe brane action with the scalar field.",
+            "Solve for the condensation chemical potential at GB coupling=0.1.",
+        ],
+        final_answer="2.2",
+        category="Physics",
+        subject="holography",
+        source="manual",
+    )
+    assert eid > 0
+    s = idx.stats()
+    assert s["worked_examples"] == 1
+
+
+def test_ingest_is_idempotent_per_source(tmp_path):
+    idx = _make_index(tmp_path)
+    args = dict(
+        problem_text="Same problem statement",
+        reasoning_steps=["step a", "step b"],
+        final_answer="42",
+        source="manual",
+    )
+    eid1 = idx.ingest_worked_example(**args)
+    eid2 = idx.ingest_worked_example(**args)
+    assert eid1 == eid2, "duplicate (problem_text, source) should return same id"
+    assert idx.stats()["worked_examples"] == 1
+
+
+def test_retrieve_finds_similar_problem(tmp_path):
+    idx = _make_index(tmp_path)
+    idx.ingest_worked_example(
+        problem_text="Drosophila Dilp2 secretion drives stem cell reactivation via hemolymph transport",
+        reasoning_steps=["Dilp2 is secreted to hemolymph", "Crosses BBB", "Reactivates NSCs"],
+        final_answer="B",
+        category="Biology/Medicine",
+        source="hle:test1",
+    )
+    idx.ingest_worked_example(
+        problem_text="Holographic D3/D7 brane Einstein-Gauss-Bonnet critical chemical potential",
+        reasoning_steps=["EGB metric", "D3/D7 setup", "Solve scalar condensation"],
+        final_answer="2.2",
+        category="Physics",
+        source="hle:test2",
+    )
+
+    # Query that strongly resembles the second problem
+    res = idx.retrieve("Gauss-Bonnet holographic D3/D7 chemical potential", text_limit=0, symbol_limit=0)
+    assert len(res.worked_examples) >= 1
+    top = res.worked_examples[0]
+    assert top.category == "Physics"
+    assert top.final_answer == "2.2"
+    assert top.score > 0
+
+
+def test_retrieve_orders_by_problem_similarity(tmp_path):
+    idx = _make_index(tmp_path)
+    idx.ingest_worked_example(
+        problem_text="alpha beta gamma delta epsilon",
+        reasoning_steps=["irrelevant"], final_answer="A",
+        source="t1",
+    )
+    idx.ingest_worked_example(
+        problem_text="zeta eta theta iota kappa",
+        reasoning_steps=["irrelevant"], final_answer="B",
+        source="t2",
+    )
+    idx.ingest_worked_example(
+        problem_text="lambda mu nu xi omicron",
+        reasoning_steps=["irrelevant"], final_answer="C",
+        source="t3",
+    )
+    res = idx.retrieve("zeta eta theta", text_limit=0, symbol_limit=0)
+    assert res.worked_examples
+    assert res.worked_examples[0].final_answer == "B"
+
+
+def test_retrieve_returns_empty_when_no_match(tmp_path):
+    idx = _make_index(tmp_path)
+    idx.ingest_worked_example(
+        problem_text="cats and dogs are pets",
+        reasoning_steps=["step"], final_answer="X",
+        source="t1",
+    )
+    res = idx.retrieve("xenobiology proteomics", text_limit=0, symbol_limit=0)
+    assert res.worked_examples == []
+
+
+def test_format_includes_reasoning_chain_and_answer(tmp_path):
+    idx = _make_index(tmp_path)
+    idx.ingest_worked_example(
+        problem_text="Compute the area of a circle with radius 5",
+        reasoning_steps=[
+            "Recall: area = pi * r^2",
+            "Substitute r=5: area = pi * 25",
+            "Compute: area approximately 78.54",
+        ],
+        final_answer="78.54",
+        category="Math",
+        source="manual",
+    )
+    res = idx.retrieve("circle area radius", text_limit=0, symbol_limit=0)
+    formatted = res.format()
+    assert "WORKED EXAMPLES" in formatted
+    assert "Reasoning:" in formatted
+    assert "Recall: area" in formatted
+    assert "Answer: 78.54" in formatted
+
+
+def test_retrieval_result_is_empty_handles_worked_examples_field():
+    """Regression: adding worked_examples to RetrievalResult must not break is_empty()."""
+    r = RetrievalResult()
+    assert r.is_empty()
+    r.worked_examples.append(WorkedExampleHit(
+        problem_text="x", category="c", subject="", reasoning_steps=("a",),
+        final_answer="y", source="manual", score=1.0,
+    ))
+    assert not r.is_empty()
+
+
+def test_existing_text_retrieval_still_works(tmp_path):
+    """The new table must not regress the existing flat-text retrieval path."""
+    idx = _make_index(tmp_path)
+    # Drop a small file under tmp so ingest_path has something to chew.
+    proj = tmp_path / "proj"
+    proj.mkdir()
+    (proj / "notes.md").write_text(
+        "# Holography notes\n\nThe Einstein-Gauss-Bonnet metric in 5 dimensions "
+        "is a particular bulk background used in bottom-up holographic models. "
+        "The probe limit applies when the brane density is small."
+    )
+    counts = idx.ingest_path(proj)
+    assert counts["chunks"] >= 1
+    res = idx.retrieve("Einstein Gauss-Bonnet metric")
+    assert res.text  # text path still produces hits
+
+
+def test_list_worked_examples(tmp_path):
+    idx = _make_index(tmp_path)
+    for i in range(3):
+        idx.ingest_worked_example(
+            problem_text=f"Problem number {i}",
+            reasoning_steps=[f"step for {i}"],
+            final_answer=f"answer {i}",
+            source=f"manual:{i}",
+        )
+    listed = idx.list_worked_examples(limit=10)
+    assert len(listed) == 3
+    # All have score=0.0 in list mode (no query)
+    assert all(h.score == 0.0 for h in listed)