raglab 0.2.1__tar.gz → 0.2.2__tar.gz

raglab-0.2.2/.claude/CLAUDE.md

@@ -0,0 +1,78 @@
+# raglab — agent instructions
+
+`raglab` is the **agentic-search / RAG orchestration layer**: it turns a
+retrieval substrate into a *Search Agent* (plan → formulate → retrieve →
+evaluate → re-query → rerank → cite) and, later, RAG pipelines on top.
+
+> Fresh start (v0.2.0+). This repo took over the `raglab` PyPI name; the old
+> backend lives at `raglab_bak`. Development is just beginning — greenfield.
+
+## The architecture we're building toward
+
+The reference design is **`ir_09 — A Composable Search Agent`**, in the **ir
+repo** at `$PP/i/ir/misc/docs/ir_09 -- A Composable Search Agent ...md`, and the
+cross-repo plan is **i2mint/ir epic #38**. Read both before non-trivial work.
+
+raglab is the **orchestration layer on top of `ir`** (the retrieval substrate).
+"Structure over concretion": a small set of **roles** (Protocols) wired by a
+control loop, with concrete tools injected at the leaves.
+
+### raglab owns (the *agent*)
+
+- **Value types** (frozen, plain data, ir_09 §3): `Query`, `SubTask(goal, sources)`,
+  `LowLevelQuery(source, spec)`, `Judgement(relevant, sufficient, refinement)`.
+  (`Result` = ir's `SearchHit`/`Disclosure`, reused as-is — do not redefine it.)
+- **Role Protocols** (open-closed strategy seams, injected callables):
+  `Planner`, `Formulator`, `Retriever`, `Evaluator`, `Reranker`, `Citer`.
+- **The control loop with the back-edge** (evaluator → reformulate). v1 = an
+  imperative `while` loop over a mutable `AgentState` (ir_09 §9), not a
+  cyclic-graph runner. This back-edge is what makes it an agent vs a DAG.
+- **Budget governor** (`max_rounds` / `max_sources_per_task` / `max_results_per_task`);
+  termination as a **separately injected policy** (ir_09 §9), not folded into the
+  evaluator.
+- **Source registry** = a live `Mapping[name, Retriever]` across *heterogeneous*
+  backends (ir corpora + web/SQL/graph); cross-source merge + global rerank at
+  the fan-in point.
+- **Two orchestrators behind one interface** (ir_09 §7): `SingleContextAgent`
+  (default, cheap, one ReAct loop) and `MultiAgentAgent` (one subagent per
+  sub-task/source, ~15× cost, breadth-first only). Promotion swaps only the
+  orchestrator, keeping role contracts identical.
+
+### What raglab CONSUMES from ir (do not reimplement these)
+
+- `ir.as_retriever(corpus)` → register an ir corpus as one `Retriever` key (#33).
+- `ir.registry.retrievers()` → the ir-corpus slice of the source registry (#34).
+- `ir.make_llm_formulator` / the `formulate=` seam → the Formulator role (#32).
+- `ir.Selection` + its derived `sufficient` signal → Evaluator input (#35).
+- `ir.disclose(..., store=...)` + `SearchHit.to_dict()` → pointer-passing / lazy
+  deref across the subagent boundary (#36).
+
+### What belongs ELSEWHERE
+
+- **Generation / answer synthesis and the Citer/Verifier** (which needs a
+  generated claim) sit with the RAG/generation layer (`srag`), not the search
+  agent. The agent's deliverable is **pointers + extractions**, not an essay.
+
+## Dependency direction (load-bearing)
+
+**`raglab` imports `ir` (and `oa` for LLM strategies); `ir` NEVER imports
+`raglab`.** Keep LLM ops (`oa`) lazy/opt-in so `import raglab` stays offline.
+
+## Build order (ir_09 §8 / epic #38)
+
+1. `Retriever` Protocol + source registry with 2–3 real backends (ir corpora via
+   `ir.as_retriever`; one web/SQL).
+2. `SingleContextAgent` with a trivial planner + pass-through evaluator wrapping
+   ir's search/select/disclose — the thin slice, **no loop yet**.
+3. LLM `Formulator` + `Evaluator` and **turn on the back-edge**.
+4. Reranker at fan-in; Citer (in `srag`).
+5. Budget governor + run-log / observability.
+6. `MultiAgentAgent` — only if breadth justifies the cost.
+
+## House style (i2mint ecosystem)
+
+Functional > OOP; SOLID when OOP; facades, SSOT, dependency injection;
+progressive disclosure; keyword-only beyond the 3rd positional; `collections.abc`
++ frozen `dataclass`es; `Protocol`s for the role seams; every module has a
+top-level docstring. Never `pip install` local ecosystem packages (`ir`, `ef`,
+`vd`, `dol`, `oa`, …) — they're local via `.pth`. wads CI auto-publishes on merge.

{raglab-0.2.1 → raglab-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: raglab
-Version: 0.2.1
+Version: 0.2.2
 Summary: A medley of tools to make RAG-based applications.
 Project-URL: Homepage, https://github.com/thorwhalen/raglab
 Project-URL: Repository, https://github.com/thorwhalen/raglab
@@ -9,6 +9,7 @@ Author: thorwhalen
 License: mit
 License-File: LICENSE
 Requires-Python: >=3.10
+Requires-Dist: ir>=0.1.12
 Provides-Extra: dev
 Requires-Dist: pytest-cov>=4.0; extra == 'dev'
 Requires-Dist: pytest>=7.0; extra == 'dev'
@@ -16,6 +17,8 @@ Requires-Dist: ruff>=0.1.0; extra == 'dev'
 Provides-Extra: docs
 Requires-Dist: sphinx-rtd-theme>=1.0; extra == 'docs'
 Requires-Dist: sphinx>=6.0; extra == 'docs'
+Provides-Extra: llm
+Requires-Dist: oa; extra == 'llm'
 Description-Content-Type: text/markdown
 
 # raglab

{raglab-0.2.1 → raglab-0.2.2}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "raglab"
-version = "0.2.1"
+version = "0.2.2"
 description = "A medley of tools to make RAG-based applications."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -14,7 +14,12 @@ keywords = []
 authors = [
     { name = "thorwhalen" },
 ]
-dependencies = []
+# raglab orchestrates retrieval via `ir` (the retrieval substrate). LLM
+# strategies (Planner/Formulator/Evaluator) use `oa` lazily — the `llm` extra
+# below — so `import raglab` stays offline by default.
+dependencies = [
+    "ir>=0.1.12",
+]
 
 [project.license]
 text = "mit"
@@ -25,6 +30,9 @@ Repository = "https://github.com/thorwhalen/raglab"
 Documentation = "https://thorwhalen.github.io/raglab"
 
 [project.optional-dependencies]
+llm = [
+    "oa",
+]
 dev = [
     "pytest>=7.0",
     "pytest-cov>=4.0",
@@ -50,13 +58,18 @@ exclude = [
 ]
 
 [tool.ruff.lint]
+# Real lint rules from the start (pyflakes / pycodestyle / bugbear), not just
+# docstring presence. E501 (line length) stays off — long descriptive docstrings.
 select = [
     "D100",
+    "F",
+    "E",
+    "W",
+    "B",
 ]
 ignore = [
     "D203",
     "E501",
-    "B905",
 ]
 
 [tool.ruff.lint.pydocstyle]

raglab-0.2.2/raglab/__init__.py

@@ -0,0 +1,72 @@
+"""``raglab`` — the agentic-search / RAG orchestration layer on top of ``ir``.
+
+`raglab` turns a retrieval substrate into a *Composable Search Agent* (the ir_09
+architecture): a small set of injected **roles** — Planner, Formulator,
+Retriever, Evaluator, Reranker, Citer — wired by a control loop whose back-edge
+(evaluator → reformulate) is what makes it an agent rather than a DAG. Concrete
+tools live at the leaves: an ``ir`` corpus becomes one ``Retriever`` via
+``ir.as_retriever``.
+
+Quick start (the no-LLM thin slice — runs offline)::
+
+    import ir
+    import raglab
+
+    # register ir corpora as the agent's sources, then search across them:
+    sources = raglab.ir_sources("skills", "reports", mode="hybrid")
+    agent = raglab.make_search_agent(sources)
+    results = agent("how do I deploy the app")      # ranked ir.SearchHits
+
+Inject an LLM ``formulator`` (query rewrite/HyDE) and ``evaluator`` (sufficiency
++ refinement) to turn on query understanding and the back-edge. Dependency
+direction is one-way: ``raglab`` imports ``ir``; ``ir`` never imports ``raglab``.
+
+> Fresh start (v0.2.0+). This repo took over the ``raglab`` PyPI name; the older
+> backend now lives at ``raglab_bak``. Development is just beginning.
+"""
+
+from .agent import (
+    Budget,
+    Citer,
+    Evaluator,
+    Formulator,
+    Judgement,
+    LowLevelQuery,
+    Planner,
+    Query,
+    Reranker,
+    Result,
+    Retriever,
+    SingleContextAgent,
+    SubTask,
+    identity_citer,
+    identity_formulator,
+    ir_sources,
+    make_search_agent,
+    passthrough_evaluator,
+    score_reranker,
+    single_subtask_planner,
+)
+
+__all__ = [
+    "Query",
+    "SubTask",
+    "LowLevelQuery",
+    "Judgement",
+    "Result",
+    "Retriever",
+    "Planner",
+    "Formulator",
+    "Evaluator",
+    "Reranker",
+    "Citer",
+    "Budget",
+    "SingleContextAgent",
+    "make_search_agent",
+    "ir_sources",
+    "single_subtask_planner",
+    "identity_formulator",
+    "passthrough_evaluator",
+    "score_reranker",
+    "identity_citer",
+]

raglab-0.2.2/raglab/agent.py

@@ -0,0 +1,293 @@
+"""The Composable Search Agent — roles wired by a control loop (ir_09).
+
+`raglab` is the **orchestration layer on top of `ir`** (the retrieval substrate).
+This module is the v1 foundation: the immutable value types, the role *Protocols*
+(open-closed strategy seams), and a `SingleContextAgent` whose fixed control loop
+is fully parametrized by injected roles. Concrete tools live at the leaves — an
+`ir` corpus becomes one `Retriever` via :func:`ir.as_retriever`.
+
+The shape follows ir_09 §3/§6: a small set of named roles —
+``Planner / Formulator / Retriever / Evaluator / Reranker / Citer`` — and a loop
+whose defining feature is the **back-edge** (evaluator → reformulate) that makes
+it an *agent* rather than a DAG. v1 ships the loop with smart defaults (a trivial
+planner + a pass-through evaluator), so the thin slice runs end-to-end with no
+LLM; turning on the back-edge is just injecting an LLM ``Evaluator`` that returns
+a ``refinement`` (ir_09 §8 step 3).
+
+Progressive disclosure: :func:`make_search_agent` gives sensible defaults for
+every role, so the simple path is ``make_search_agent(sources)("query")``.
+
+Dependency direction is one-way: `raglab` imports `ir`; `ir` never imports
+`raglab`. The ``Result`` type and the ``Retriever`` contract are ir's (SSOT).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass, field
+from typing import Any, Protocol, runtime_checkable
+
+# ir owns the retrieval substrate: the Result type and the Retriever leaf
+# contract live there (one-way dependency, ir is the SSOT).
+from ir import Retriever, SearchHit
+
+#: A retrieved item — ir's :class:`~ir.base.SearchHit` (ir_09's ``Result``):
+#: a *pointer + snippet* (``text``) with a ``score`` and ``metadata``.
+Result = SearchHit
+
+__all__ = [
+    "Query",
+    "SubTask",
+    "LowLevelQuery",
+    "Judgement",
+    "Result",
+    "Retriever",
+    "Planner",
+    "Formulator",
+    "Evaluator",
+    "Reranker",
+    "Citer",
+    "Budget",
+    "SingleContextAgent",
+    "make_search_agent",
+    "ir_sources",
+    "single_subtask_planner",
+    "identity_formulator",
+    "passthrough_evaluator",
+    "score_reranker",
+    "identity_citer",
+]
+
+
+# --------------------------------------------------------------------------- #
+# Value types (immutable, plain data) — ir_09 §3
+# --------------------------------------------------------------------------- #
+
+
+@dataclass(frozen=True)
+class Query:
+    """A user intent: free text plus optional structured constraints."""
+
+    text: str
+    constraints: Mapping[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class SubTask:
+    """A planner's unit of work: a sub-goal bound to a set of registered sources."""
+
+    goal: str
+    sources: tuple[str, ...]
+
+
+@dataclass(frozen=True)
+class LowLevelQuery:
+    """One concrete query against one source.
+
+    ``query`` is the text handed to the source's :data:`Retriever`; ``params``
+    are per-call retriever overrides (e.g. ``mode`` / ``filter`` / ``k`` for an
+    ir corpus). A formulator turns a :class:`SubTask` into these.
+    """
+
+    source: str
+    query: str
+    params: Mapping[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class Judgement:
+    """An evaluator's verdict over a round's results.
+
+    ``relevant`` is the kept subset; ``sufficient`` says whether to stop; a
+    non-``None`` ``refinement`` is the **back-edge** — the next sub-task to
+    re-query with. The pass-through default returns ``sufficient=True`` and no
+    refinement (no loop).
+    """
+
+    relevant: Sequence[Result]
+    sufficient: bool
+    refinement: SubTask | None = None
+
+
+# --------------------------------------------------------------------------- #
+# Role Protocols (the open-closed strategy seams) — ir_09 §3
+# --------------------------------------------------------------------------- #
+
+
+@runtime_checkable
+class Planner(Protocol):
+    """Decompose a query into sub-tasks and select sources for each."""
+
+    def __call__(
+        self, query: Query, sources: Mapping[str, Retriever]
+    ) -> list[SubTask]: ...
+
+
+@runtime_checkable
+class Formulator(Protocol):
+    """Turn a sub-task + one source into concrete low-level queries."""
+
+    def __call__(self, task: SubTask, source: str) -> list[LowLevelQuery]: ...
+
+
+@runtime_checkable
+class Evaluator(Protocol):
+    """Judge relevance + sufficiency; optionally emit a refinement (back-edge)."""
+
+    def __call__(self, task: SubTask, results: Sequence[Result]) -> Judgement: ...
+
+
+@runtime_checkable
+class Reranker(Protocol):
+    """Produce the final ordering over the (cross-source) merged results."""
+
+    def __call__(self, results: Sequence[Result]) -> Sequence[Result]: ...
+
+
+@runtime_checkable
+class Citer(Protocol):
+    """Confirm/annotate that each result supports its use (identity by default)."""
+
+    def __call__(self, results: Sequence[Result]) -> Sequence[Result]: ...
+
+
+# --------------------------------------------------------------------------- #
+# Budget governor — ir_09 §4
+# --------------------------------------------------------------------------- #
+
+
+@dataclass(frozen=True)
+class Budget:
+    """Loop bounds: the safety net under the (harder) sufficiency decision."""
+
+    max_rounds: int = 3
+    max_sources_per_task: int = 4
+    max_results_per_task: int = 50
+
+
+# --------------------------------------------------------------------------- #
+# Default role implementations (the no-LLM thin slice) — ir_09 §8 step 2
+# --------------------------------------------------------------------------- #
+
+
+def single_subtask_planner(
+    query: Query, sources: Mapping[str, Retriever]
+) -> list[SubTask]:
+    """Trivial planner: one sub-task over *all* registered sources, no decomposition."""
+    return [SubTask(goal=query.text, sources=tuple(sources))]
+
+
+def identity_formulator(task: SubTask, source: str) -> list[LowLevelQuery]:
+    """Identity formulator: the sub-goal verbatim as one query (no rewrite/HyDE)."""
+    return [LowLevelQuery(source=source, query=task.goal)]
+
+
+def passthrough_evaluator(task: SubTask, results: Sequence[Result]) -> Judgement:
+    """Pass-through critic: keep everything, declare sufficient, never re-query."""
+    return Judgement(relevant=list(results), sufficient=True, refinement=None)
+
+
+def score_reranker(results: Sequence[Result]) -> Sequence[Result]:
+    """Final ordering by descending ``score`` (the cross-source merge, v1).
+
+    Note: a plain score sort assumes comparable score scales across sources
+    (true when they share an embedder + mode). A rank-based (RRF) cross-source
+    merge for heterogeneous backends is a documented follow-up.
+    """
+    return sorted(results, key=lambda r: float(getattr(r, "score", 0.0)), reverse=True)
+
+
+def identity_citer(results: Sequence[Result]) -> Sequence[Result]:
+    """No-op citer (verification needs a generated claim — that lives in srag)."""
+    return results
+
+
+# --------------------------------------------------------------------------- #
+# The orchestrator — a fixed control loop, fully parametrized by roles
+# --------------------------------------------------------------------------- #
+
+
+@dataclass
+class SingleContextAgent:
+    """One ReAct-style loop, sequential sub-tasks (ir_09 §7 — the cheap default).
+
+    The loop is fixed; every *decision* is an injected role. Promotion to a
+    multi-agent orchestrator (ir_09 §7) swaps this class while keeping the same
+    role contracts. The **back-edge** is the single line ``current =
+    judged.refinement`` in :meth:`_run_task` — that is what makes this an agent.
+    """
+
+    sources: Mapping[str, Retriever]
+    planner: Planner = single_subtask_planner
+    formulator: Formulator = identity_formulator
+    evaluator: Evaluator = passthrough_evaluator
+    reranker: Reranker = score_reranker
+    citer: Citer = identity_citer
+    budget: Budget = field(default_factory=Budget)
+
+    def __call__(self, query: str | Query) -> list[Result]:
+        """Run the agent for *query*; returns the final ranked, cited results."""
+        q = query if isinstance(query, Query) else Query(text=query)
+        accumulated: list[Result] = []
+        for task in self.planner(q, self.sources):
+            accumulated.extend(self._run_task(task))
+        ranked = self.reranker(accumulated)
+        return list(self.citer(ranked))
+
+    def _run_task(self, task: SubTask) -> list[Result]:
+        found: list[Result] = []
+        current = task
+        for _ in range(max(1, self.budget.max_rounds)):
+            for source in current.sources[: self.budget.max_sources_per_task]:
+                retriever = self.sources.get(source)
+                if retriever is None:
+                    continue
+                for llq in self.formulator(current, source):
+                    found.extend(retriever(llq.query, **dict(llq.params)))
+            judged = self.evaluator(current, found[: self.budget.max_results_per_task])
+            found = list(judged.relevant)
+            if judged.sufficient or judged.refinement is None:
+                break
+            current = judged.refinement  # the back-edge: re-query
+        return found
+
+
+def make_search_agent(
+    sources: Mapping[str, Retriever],
+    *,
+    planner: Planner | None = None,
+    formulator: Formulator | None = None,
+    evaluator: Evaluator | None = None,
+    reranker: Reranker | None = None,
+    citer: Citer | None = None,
+    budget: Budget | None = None,
+) -> SingleContextAgent:
+    """Build a :class:`SingleContextAgent` over *sources* with smart defaults.
+
+    ``sources`` is a ``Mapping[name, Retriever]`` — e.g.
+    ``{"skills": ir.as_retriever("skills")}``. Every role defaults to its no-LLM
+    thin-slice implementation, so ``make_search_agent(sources)("query")`` just
+    works; inject an LLM ``formulator`` / ``evaluator`` to turn on rewriting and
+    the back-edge.
+    """
+    return SingleContextAgent(
+        sources=sources,
+        planner=planner or single_subtask_planner,
+        formulator=formulator or identity_formulator,
+        evaluator=evaluator or passthrough_evaluator,
+        reranker=reranker or score_reranker,
+        citer=citer or identity_citer,
+        budget=budget or Budget(),
+    )
+
+
+def ir_sources(*names: str, **search_defaults: Any) -> dict[str, Retriever]:
+    """A source registry ``{name: Retriever}`` backed by named ``ir`` corpora.
+
+    Each name is bound to ``ir.as_retriever(name, **search_defaults)``. A thin
+    convenience; once ir ships ``registry.retrievers()`` (a lazy view), prefer
+    that. ``search_defaults`` (e.g. ``mode="hybrid"``) apply to every source.
+    """
+    import ir
+
+    return {name: ir.as_retriever(name, **search_defaults) for name in names}

raglab-0.2.2/tests/test_agent.py

@@ -0,0 +1,158 @@
+"""Tests for the raglab Composable Search Agent foundation (ir_09).
+
+Hermetic: the control loop is exercised with a fake in-memory retriever (no
+model, no network); one end-to-end test wires a real ``ir`` corpus via
+``ir.as_retriever`` with the light (numpy-only) embedder and an in-memory store.
+"""
+
+import raglab
+from ir import SearchHit
+from raglab import Budget, Judgement, LowLevelQuery, Query, SubTask, make_search_agent
+
+
+def _hits(*specs):
+    """``(artifact_id, score)`` pairs -> ir.SearchHits (no corpus needed)."""
+    return [SearchHit(aid, "k", score, f"text {aid}", {}) for aid, score in specs]
+
+
+def _fake_retriever(hits):
+    """A Retriever that records its calls and returns canned hits."""
+    calls = []
+
+    def retrieve(query, **kw):
+        calls.append((query, kw))
+        return list(hits)
+
+    retrieve.calls = calls
+    return retrieve
+
+
+# ----- value types & protocols --------------------------------------------- #
+
+
+def test_result_is_ir_searchhit():
+    assert raglab.Result is SearchHit
+
+
+def test_defaults_satisfy_role_protocols():
+    assert isinstance(raglab.single_subtask_planner, raglab.Planner)
+    assert isinstance(raglab.identity_formulator, raglab.Formulator)
+    assert isinstance(raglab.passthrough_evaluator, raglab.Evaluator)
+    assert isinstance(raglab.score_reranker, raglab.Reranker)
+    assert isinstance(raglab.identity_citer, raglab.Citer)
+
+
+# ----- the thin-slice loop (no LLM) ----------------------------------------- #
+
+
+def test_make_search_agent_thin_slice_runs():
+    sources = {"s": _fake_retriever(_hits(("a", 0.9), ("b", 0.5)))}
+    results = make_search_agent(sources)("anything")
+    assert [r.artifact_id for r in results] == ["a", "b"]
+
+
+def test_query_string_or_object_equivalent():
+    sources = {"s": _fake_retriever(_hits(("a", 0.9)))}
+    agent = make_search_agent(sources)
+    assert agent("q") == agent(Query(text="q"))
+
+
+def test_cross_source_merge_reranks_by_score():
+    sources = {
+        "s1": _fake_retriever(_hits(("a", 0.3))),
+        "s2": _fake_retriever(_hits(("b", 0.9))),
+    }
+    results = make_search_agent(sources)("q")
+    assert [r.artifact_id for r in results] == ["b", "a"]  # by score desc
+
+
+def test_passthrough_evaluator_does_not_loop():
+    retr = _fake_retriever(_hits(("a", 0.9)))
+    make_search_agent({"s": retr})("q")
+    assert len(retr.calls) == 1  # one round only
+
+
+def test_formulator_fan_out_issues_each_query():
+    retr = _fake_retriever(_hits(("a", 0.9)))
+
+    def multi(task, source):
+        return [
+            LowLevelQuery(source, task.goal),
+            LowLevelQuery(source, task.goal + " alt"),
+        ]
+
+    make_search_agent({"s": retr}, formulator=multi)("q")
+    assert len(retr.calls) == 2
+
+
+def test_unknown_source_is_skipped_not_an_error():
+    retr = _fake_retriever(_hits(("a", 0.9)))
+
+    def planner(query, sources):
+        return [SubTask(query.text, ("s", "missing"))]
+
+    results = make_search_agent({"s": retr}, planner=planner)("q")
+    assert [r.artifact_id for r in results] == ["a"]
+
+
+# ----- the back-edge (the property that makes it an agent) ------------------ #
+
+
+def test_back_edge_reformulates_until_sufficient():
+    retr = _fake_retriever(_hits(("a", 0.9)))
+    rounds = {"n": 0}
+
+    def refining_evaluator(task, results):
+        rounds["n"] += 1
+        if rounds["n"] < 2:  # first round: not enough, re-query (back-edge)
+            return Judgement(
+                relevant=list(results),
+                sufficient=False,
+                refinement=SubTask(goal=task.goal + " more", sources=task.sources),
+            )
+        return Judgement(relevant=list(results), sufficient=True)
+
+    make_search_agent({"s": retr}, evaluator=refining_evaluator)("q")
+    assert rounds["n"] == 2  # looped once via the back-edge
+    assert len(retr.calls) == 2
+
+
+def test_budget_bounds_a_never_sufficient_loop():
+    retr = _fake_retriever(_hits(("a", 0.9)))
+
+    def never_sufficient(task, results):
+        return Judgement(
+            relevant=list(results),
+            sufficient=False,
+            refinement=SubTask(task.goal, task.sources),
+        )
+
+    make_search_agent(
+        {"s": retr}, evaluator=never_sufficient, budget=Budget(max_rounds=3)
+    )("q")
+    assert len(retr.calls) == 3  # exactly max_rounds — the safety net holds
+
+
+# ----- end-to-end over a REAL ir corpus (hermetic: light embedder) ---------- #
+
+
+def test_agent_over_real_ir_corpus():
+    import ir
+    from ir.store import CorpusStore
+
+    docs = {
+        "deploy": "deploy the app to the server with systemd units",
+        "embed": "embed text with a model and cache the vectors",
+        "search": "vector similarity search with metadata filters",
+    }
+    corpus = ir.build(
+        ir.CorpusSource.from_mapping(docs, name="t", strategy=ir.WholeText()),
+        store=CorpusStore.memory(),
+        embedder="light",
+    )
+    agent = make_search_agent({"t": ir.as_retriever(corpus, k=3)})
+    results = agent("deploy the app to the server")
+    assert results
+    assert results[0].artifact_id == "deploy"
+    assert isinstance(results[0], SearchHit)
+    results[0].to_dict()  # the substrate edge is serialization-clean

raglab-0.2.1/raglab/__init__.py

@@ -1,7 +0,0 @@
-"""A medley of tools to make RAG-based applications.
-
-This is a fresh start for the ``raglab`` name (version 0.2.0+). The earlier
-``raglab`` backend (PyPI versions 0.0.x–0.1.x) now lives at
-`addaix/raglab_bak <https://github.com/addaix/raglab_bak>`_ and is published as
-``raglab_bak``. Development of this new ``raglab`` is just beginning.
-"""