search-as-code 0.0.1__py3-none-any.whl

search_as_code/explore/engine.py

@@ -0,0 +1,160 @@
+"""The exploration engine — a resumable, validate-before-keep stage runner.
+
+``explore(session, out=...)`` walks an ordered list of :class:`Stage` objects. Each
+stage reads/writes artifacts on the :class:`ProfilePack`. The engine:
+
+- **skips** stages already done (artifacts present) unless ``force`` or the corpus
+  fingerprint changed (drift);
+- runs a stage, then calls its ``validate`` gate — a stage whose output does not beat
+  baseline is recorded as ``rejected`` and its artifacts are *not* trusted downstream
+  (the honesty rule: keep only tunings that help);
+- records status/timing/summary for every stage in the manifest, and never lets one
+  stage's failure abort the rest.
+"""
+
+from __future__ import annotations
+
+import abc
+import hashlib
+import time
+from dataclasses import dataclass, field
+from typing import Any, Optional
+
+from .pack import ProfilePack
+
+
+@dataclass
+class ExploreContext:
+    """Everything a stage needs: the live Session, the pack to write to, and config."""
+
+    session: Any                     # search_as_code.Session
+    pack: ProfilePack
+    config: dict = field(default_factory=dict)
+
+    @property
+    def store(self):
+        return self.session.store
+
+    @property
+    def embedder(self):
+        return self.session.embedder
+
+    @property
+    def generator(self):
+        return self.session.generator
+
+    def cfg(self, key: str, default: Any = None) -> Any:
+        return self.config.get(key, default)
+
+
+class Stage(abc.ABC):
+    """One unit of exploration. Subclasses declare what they produce/require."""
+
+    name: str = "stage"
+    produces: list[str] = []          # artifact filenames written on success
+    requires: list[str] = []          # names of stages that must be ``ok`` first
+
+    @abc.abstractmethod
+    def run(self, ctx: ExploreContext) -> dict:
+        """Do the work, write artifacts, return a small summary dict for the manifest."""
+
+    def validate(self, ctx: ExploreContext, summary: dict) -> tuple[bool, str]:
+        """Gate: return (keep, reason). Default keeps everything. Learning stages
+        override this to reject output that does not beat baseline."""
+        return True, ""
+
+
+def corpus_fingerprint(store, k: int = 12) -> str:
+    """Cheap, stable signature of the corpus so we can detect drift. Combines the
+    doc count with a hash of a small deterministic-ish text sample."""
+    try:
+        count = store.count()
+    except Exception:
+        count = -1
+    texts = []
+    try:
+        for d in store.sample(k):
+            texts.append((d.text or "")[:120])
+    except Exception:
+        pass
+    h = hashlib.sha1(("|".join(sorted(texts))).encode("utf-8", "ignore")).hexdigest()[:12]
+    return f"n{count}-{h}"
+
+
+def explore(session, out: str, stages: Optional[list[Stage]] = None, *,
+            force: bool = False, config: Optional[dict] = None) -> ProfilePack:
+    """Run the exploration pipeline over ``session``'s corpus into a ProfilePack at ``out``.
+
+    Parameters
+    ----------
+    session : Session   the bound corpus (store + embedder + optional generator).
+    out     : str       directory for the ProfilePack (created if absent).
+    stages  : list      ordered Stage instances; defaults to :func:`default_pipeline`.
+    force   : bool       re-run every stage even if its artifacts exist.
+    config  : dict       knobs passed through to stages (sample sizes, k, etc.).
+    """
+    pack = ProfilePack.open(out)
+    ctx = ExploreContext(session=session, pack=pack, config=config or {})
+
+    fp = corpus_fingerprint(session.store)
+    drift = pack.fingerprint_changed(fp)
+    pack.set_fingerprint(fp)
+    if stages is None:
+        stages = default_pipeline()
+
+    done: set[str] = set()
+    for stage in stages:
+        missing = [r for r in stage.requires if r not in done]
+        if missing:
+            pack.record_stage(stage.name, "skipped",
+                              note=f"unmet requires: {', '.join(missing)}")
+            continue
+        if pack.is_done(stage.name) and not force and not drift:
+            done.add(stage.name)
+            continue
+
+        t0 = time.time()
+        try:
+            summary = stage.run(ctx)
+            keep, reason = stage.validate(ctx, summary)
+            secs = time.time() - t0
+            if keep:
+                pack.record_stage(stage.name, "ok", seconds=secs, summary=summary,
+                                  artifacts=list(stage.produces), note=reason)
+                done.add(stage.name)
+            else:
+                pack.record_stage(stage.name, "rejected", seconds=secs, summary=summary,
+                                  note=reason or "did not beat baseline")
+        except NotImplementedError as e:
+            pack.record_stage(stage.name, "planned", seconds=time.time() - t0, note=str(e))
+        except Exception as e:  # never let one stage abort the pipeline
+            pack.record_stage(stage.name, "error", seconds=time.time() - t0,
+                              note=f"{type(e).__name__}: {e}")
+    return pack
+
+
+def default_pipeline() -> list[Stage]:
+    """The full seven-stage pipeline. Stages not yet implemented raise
+    NotImplementedError and are recorded as ``planned`` — the pipeline still runs
+    end-to-end and the pack shows the roadmap."""
+    from .stages import (
+        CodegenStage,
+        CrossDocStage,
+        OntologyStage,
+        ProfileStage,
+        RouterStage,
+        SampleStage,
+        SynthesizeStage,
+        ValidateStage,
+    )
+
+    return [
+        SampleStage(),
+        ProfileStage(),
+        OntologyStage(),
+        CrossDocStage(),
+        SynthesizeStage(),
+        RouterStage(),
+        CodegenStage(),
+        ValidateStage(),
+    ]

search_as_code/explore/pack.py

@@ -0,0 +1,127 @@
+"""ProfilePack — the on-disk artifact produced by ``sac.explore``.
+
+A ProfilePack is a *versioned directory* holding everything the exploration phase
+learns about a corpus (schema, content profile, ontology, synthetic queries, a
+primitive router, few-shots/templates, prompt overrides). A ``Session`` loads it
+at query time to tune retrieval to the data — and works fine without it.
+
+Design goals (robustness):
+- **Everything serializes here** — nothing the explorer learns is implicit.
+- **Resumable** — each stage writes its own artifact; a crash re-runs only what's missing.
+- **Drift-aware** — the manifest stores a corpus *fingerprint*; when the data changes
+  enough, stages are re-run.
+- **Self-describing** — the manifest records every stage's status/timestamp/summary so a
+  human (or agent) can see exactly what was built and what was rejected.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from pathlib import Path
+from typing import Any, Optional
+
+SCHEMA_VERSION = 1
+MANIFEST_NAME = "manifest.json"
+
+
+class ProfilePack:
+    """A directory of exploration artifacts + a manifest tracking stage status."""
+
+    def __init__(self, root: Path, manifest: dict):
+        self.root = root
+        self.manifest = manifest
+
+    # ---- lifecycle -------------------------------------------------------
+    @classmethod
+    def open(cls, path: str | Path) -> "ProfilePack":
+        """Open an existing pack or initialise a fresh one at ``path``."""
+        root = Path(path)
+        root.mkdir(parents=True, exist_ok=True)
+        mpath = root / MANIFEST_NAME
+        if mpath.exists():
+            manifest = json.loads(mpath.read_text())
+        else:
+            manifest = {
+                "schema_version": SCHEMA_VERSION,
+                "created": time.time(),
+                "fingerprint": None,
+                "stages": {},  # name -> {status, ts, seconds, summary, artifacts, note}
+            }
+        pack = cls(root, manifest)
+        pack.save_manifest()
+        return pack
+
+    def save_manifest(self) -> None:
+        self.manifest["updated"] = time.time()
+        (self.root / MANIFEST_NAME).write_text(json.dumps(self.manifest, indent=2, default=str))
+
+    # ---- artifacts -------------------------------------------------------
+    def path(self, name: str) -> Path:
+        return self.root / name
+
+    def has(self, name: str) -> bool:
+        return (self.root / name).exists()
+
+    def write_json(self, name: str, obj: Any) -> None:
+        self.path(name).write_text(json.dumps(obj, indent=2, default=str))
+
+    def read_json(self, name: str, default: Any = None) -> Any:
+        p = self.path(name)
+        return json.loads(p.read_text()) if p.exists() else default
+
+    def write_jsonl(self, name: str, rows: list) -> None:
+        with self.path(name).open("w") as f:
+            for r in rows:
+                f.write(json.dumps(r, default=str) + "\n")
+
+    def read_jsonl(self, name: str) -> list:
+        p = self.path(name)
+        if not p.exists():
+            return []
+        return [json.loads(ln) for ln in p.read_text().splitlines() if ln.strip()]
+
+    # ---- stage bookkeeping ----------------------------------------------
+    def stage(self, name: str) -> dict:
+        return self.manifest["stages"].get(name, {})
+
+    def stage_status(self, name: str) -> Optional[str]:
+        return self.stage(name).get("status")
+
+    def is_done(self, name: str) -> bool:
+        """A stage counts as done if it succeeded and its artifacts still exist."""
+        st = self.stage(name)
+        if st.get("status") != "ok":
+            return False
+        return all(self.has(a) for a in st.get("artifacts", []))
+
+    def record_stage(self, name: str, status: str, *, seconds: float = 0.0,
+                     summary: Optional[dict] = None, artifacts: Optional[list[str]] = None,
+                     note: str = "") -> None:
+        self.manifest["stages"][name] = {
+            "status": status,          # ok | rejected | error | planned | skipped
+            "ts": time.time(),
+            "seconds": round(seconds, 3),
+            "summary": summary or {},
+            "artifacts": artifacts or [],
+            "note": note,
+        }
+        self.save_manifest()
+
+    # ---- drift -----------------------------------------------------------
+    def set_fingerprint(self, fp: str) -> None:
+        self.manifest["fingerprint"] = fp
+        self.save_manifest()
+
+    def fingerprint_changed(self, fp: str) -> bool:
+        prev = self.manifest.get("fingerprint")
+        return prev is not None and prev != fp
+
+    # ---- summary ---------------------------------------------------------
+    def report(self) -> str:
+        lines = [f"ProfilePack {self.root}  (schema v{self.manifest.get('schema_version')})"]
+        for name, st in self.manifest["stages"].items():
+            summ = ", ".join(f"{k}={v}" for k, v in (st.get("summary") or {}).items())
+            lines.append(f"  [{st.get('status','?'):8}] {name:14} {summ}"
+                         + (f"  # {st['note']}" if st.get("note") else ""))
+        return "\n".join(lines)

search_as_code/explore/report.py

@@ -0,0 +1,72 @@
+"""CSV export for a ProfilePack — flat tables for spreadsheets / quick review.
+
+Writes up to three CSVs next to the pack (or a chosen dir):
+- ``stages.csv``     one row per pipeline stage (status/timing/summary)
+- ``clusters.csv``   one row per sample cluster (size, content-type mix, LLM profile)
+- ``documents.csv``  one row per sampled document (cluster, content_type, snippet)
+"""
+
+from __future__ import annotations
+
+import csv
+from collections import Counter
+from pathlib import Path
+
+from ..primitives import content_type
+from .pack import ProfilePack
+
+
+def write_csv_report(pack: ProfilePack, out_dir: str | None = None) -> dict[str, str]:
+    """Write the CSV tables; return {name: path}. Missing artifacts are skipped."""
+    out = Path(out_dir) if out_dir else pack.root
+    out.mkdir(parents=True, exist_ok=True)
+    written: dict[str, str] = {}
+
+    # ---- stages.csv ------------------------------------------------------
+    spath = out / "stages.csv"
+    with spath.open("w", newline="") as f:
+        w = csv.writer(f)
+        w.writerow(["stage", "status", "seconds", "summary", "artifacts", "note"])
+        for name, st in pack.manifest.get("stages", {}).items():
+            summary = "; ".join(f"{k}={v}" for k, v in (st.get("summary") or {}).items())
+            w.writerow([name, st.get("status", ""), st.get("seconds", ""),
+                        summary, " ".join(st.get("artifacts", [])), st.get("note", "")])
+    written["stages"] = str(spath)
+
+    sample = pack.read_jsonl("sample.jsonl")
+    profile = pack.read_json("content_profile.json") or {}
+    llm_by_cluster = profile.get("llm_by_cluster") or {}
+    sizes = (pack.read_json("sample_meta.json") or {}).get("cluster_sizes", {})
+
+    if sample:
+        # ---- documents.csv ----------------------------------------------
+        dpath = out / "documents.csv"
+        with dpath.open("w", newline="") as f:
+            w = csv.writer(f)
+            w.writerow(["id", "cluster", "content_type", "chars", "snippet"])
+            for r in sample:
+                text = r.get("text") or ""
+                snippet = " ".join(text.split())[:200]
+                w.writerow([r.get("id"), r.get("cluster"),
+                            content_type(text), len(text), snippet])
+        written["documents"] = str(dpath)
+
+        # ---- clusters.csv -----------------------------------------------
+        by_cluster: dict = {}
+        for r in sample:
+            by_cluster.setdefault(r.get("cluster"), []).append(r)
+        cpath = out / "clusters.csv"
+        with cpath.open("w", newline="") as f:
+            w = csv.writer(f)
+            w.writerow(["cluster", "pool_size", "n_sampled", "content_types",
+                        "llm_profile", "example_snippet"])
+            for c in sorted(by_cluster, key=lambda x: (x is None, x)):
+                rows = by_cluster[c]
+                cts = Counter(content_type(r.get("text") or "") for r in rows)
+                ct_str = ", ".join(f"{k}:{v}" for k, v in cts.most_common())
+                example = " ".join((rows[0].get("text") or "").split())[:160]
+                w.writerow([c, sizes.get(str(c), ""), len(rows), ct_str,
+                            (llm_by_cluster.get(str(c)) or "").strip(), example])
+        written["clusters"] = str(cpath)
+
+    return written