raglab 0.1.2__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.2/.gitattributes

@@ -0,0 +1 @@
+*.ipynb linguist-documentation

raglab-0.2.2/.github/workflows/ci.yml

@@ -0,0 +1,48 @@
+# wads CI — calls the reusable workflow hosted in i2mint/wads.
+#
+# All configuration comes from this repo's pyproject.toml [tool.wads.ci.*].
+# To customize the workflow itself (rare), replace this file with the
+# full inline template `wads/data/github_ci_uv.yml` from i2mint/wads.
+#
+# Pinning: `@master` floats with wads. If you need version stability for
+# a release-sensitive repo, change `@master` to a wads tag (e.g. `@v0.1.81`).
+# CI failure does not block a published release — it blocks the publish
+# step itself — so floating master is generally safe.
+#
+# Permissions: GitHub validates that the caller grants AT LEAST the
+# permissions any job in the called workflow requests — at workflow-parse
+# time, not at run-time, even if the job would be skipped via `if:`.
+# The reusable workflow needs:
+#   contents: write   for the publish job's version-bump push-back
+#                     and for the github-pages job's gh-pages branch push
+#   pages: write      for the github-pages job's REST API Pages config
+# Both default to `write` on org-account GITHUB_TOKEN and need to be
+# granted explicitly on personal-account callers (where the default is
+# read-only). No `id-token: write` needed — the publish-github-pages
+# action uses peaceiris/actions-gh-pages (branch-based) + REST API,
+# not the OIDC `actions/deploy-pages` flow.
+name: Continuous Integration
+on: [push, pull_request]
+jobs:
+  ci:
+    uses: i2mint/wads/.github/workflows/uv-ci.yml@master
+    permissions:
+      contents: write
+      pages: write
+    # Explicit pass-through (not `secrets: inherit`) because `inherit` does
+    # not reliably propagate caller-repo secrets to a reusable workflow owned
+    # by a different account (verified empirically: personal-account caller +
+    # i2mint-org workflow → `${{ secrets.PYPI_PASSWORD }}` resolved to empty).
+    #
+    # This list is the per-repo *transport*: it should contain PYPI_PASSWORD
+    # (for publishing) plus every secret your tests/CI need. It is generated
+    # from [tool.wads.ci.env] in pyproject.toml. To add one, run
+    #   wads-secrets add VAR_NAME            # updates pyproject + this block
+    # or just append a line below. *Which* of these become job env vars (and
+    # which are required) is controlled by [tool.wads.ci.env] — passing a
+    # secret here does not by itself put it in the environment.
+    #
+    # A secret name must also be declared in the reusable workflow's superset
+    # (wads/ci_secrets.py). `wads-secrets add` warns if it is not.
+    secrets:
+      PYPI_PASSWORD: ${{ secrets.PYPI_PASSWORD }}

raglab-0.2.2/.gitignore

@@ -0,0 +1,120 @@
+.claude/handoffs/
+.claude/scratch/
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+
+.DS_Store
+# C extensions
+*.so
+
+# TLS certificates
+## Ignore all PEM files anywhere
+*.pem
+## Also ignore any certs directory
+certs/
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+_build
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+docs/*
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# pyenv
+.python-version
+
+# celery beat schedule file
+celerybeat-schedule
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+
+# PyCharm
+.idea

{raglab-0.1.2 → raglab-0.2.2}/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) [year] [fullname]
+Copyright (c) 2026 thorwhalen
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

raglab-0.2.2/PKG-INFO

@@ -0,0 +1,34 @@
+Metadata-Version: 2.4
+Name: raglab
+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
+Project-URL: Documentation, https://thorwhalen.github.io/raglab
+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'
+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
+
+A medley of tools to make RAG-based applications.
+
+To install: ```pip install raglab```
+
+> **Note** — fresh start (v0.2.0+). This is a new project that has taken over the
+> `raglab` name. The earlier `raglab` backend (PyPI 0.0.x–0.1.x) was renamed and
+> now lives at [addaix/raglab_bak](https://github.com/addaix/raglab_bak)
+> (published on PyPI as [`raglab_bak`](https://pypi.org/project/raglab_bak/)).
+> Development of this new `raglab` is just beginning.

raglab-0.2.2/README.md

@@ -0,0 +1,11 @@
+# raglab
+
+A medley of tools to make RAG-based applications.
+
+To install: ```pip install raglab```
+
+> **Note** — fresh start (v0.2.0+). This is a new project that has taken over the
+> `raglab` name. The earlier `raglab` backend (PyPI 0.0.x–0.1.x) was renamed and
+> now lives at [addaix/raglab_bak](https://github.com/addaix/raglab_bak)
+> (published on PyPI as [`raglab_bak`](https://pypi.org/project/raglab_bak/)).
+> Development of this new `raglab` is just beginning.

raglab-0.2.2/pyproject.toml

@@ -0,0 +1,170 @@
+[build-system]
+requires = [
+    "hatchling",
+]
+build-backend = "hatchling.build"
+
+[project]
+name = "raglab"
+version = "0.2.2"
+description = "A medley of tools to make RAG-based applications."
+readme = "README.md"
+requires-python = ">=3.10"
+keywords = []
+authors = [
+    { name = "thorwhalen" },
+]
+# 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"
+
+[project.urls]
+Homepage = "https://github.com/thorwhalen/raglab"
+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",
+    "ruff>=0.1.0",
+]
+docs = [
+    "sphinx>=6.0",
+    "sphinx-rtd-theme>=1.0",
+]
+
+[tool.ruff]
+line-length = 88
+target-version = "py310"
+exclude = [
+    "**/*.ipynb",
+    ".git",
+    ".venv",
+    "build",
+    "dist",
+    "tests",
+    "examples",
+    "scrap",
+]
+
+[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",
+]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.lint.per-file-ignores]
+"**/tests/*" = [
+    "D",
+]
+"**/examples/*" = [
+    "D",
+]
+"**/scrap/*" = [
+    "D",
+]
+
+[tool.pytest.ini_options]
+minversion = "6.0"
+testpaths = [
+    "tests",
+]
+doctest_optionflags = [
+    "NORMALIZE_WHITESPACE",
+    "ELLIPSIS",
+]
+
+[tool.wads.ci]
+project_name = ""
+
+[tool.wads.ci.commands]
+pre_test = []
+test = []
+post_test = []
+lint = []
+format = []
+
+[tool.wads.ci.env]
+required_envvars = []
+test_envvars = []
+extra_envvars = []
+
+[tool.wads.ci.env.defaults]
+
+[tool.wads.ci.quality.ruff]
+enabled = true
+
+[tool.wads.ci.quality.black]
+enabled = false
+
+[tool.wads.ci.quality.mypy]
+enabled = false
+
+[tool.wads.ci.testing]
+enabled = true
+python_versions = [
+    "3.10",
+    "3.12",
+]
+pytest_args = [
+    "-v",
+    "--tb=short",
+]
+coverage_enabled = true
+coverage_threshold = 0
+coverage_report_format = [
+    "term",
+    "xml",
+]
+exclude_paths = [
+    "examples",
+    "scrap",
+]
+test_on_windows = true
+
+[tool.wads.ci.metrics]
+enabled = true
+config_path = ".github/umpyre-config.yml"
+storage_branch = "code-metrics"
+python_version = "3.10"
+force_run = false
+
+[tool.wads.ci.build]
+sdist = true
+wheel = true
+
+[tool.wads.ci.publish]
+enabled = true
+skip_ci_marker = "[skip ci]"
+publish_marker = "[publish]"
+
+[tool.wads.ci.docs]
+enabled = true
+builder = "epythet"
+ignore_paths = [
+    "tests/",
+    "scrap/",
+    "examples/",
+]

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",
+]