attune-rag 0.1.0__tar.gz

attune_rag-0.1.0/LICENSE

@@ -0,0 +1,17 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+
+Copyright 2026 Patrick Roebuck / Smart AI Memory

attune_rag-0.1.0/PKG-INFO

@@ -0,0 +1,167 @@
+Metadata-Version: 2.4
+Name: attune-rag
+Version: 0.1.0
+Summary: Lightweight, LLM-agnostic RAG pipeline with pluggable corpora. Works with Claude, OpenAI, Gemini, or any LLM.
+Author-email: Patrick Roebuck <admin@smartaimemory.com>
+License:                                  Apache License
+                                   Version 2.0, January 2004
+                                http://www.apache.org/licenses/
+        
+           Licensed under the Apache License, Version 2.0 (the "License");
+           you may not use this file except in compliance with the License.
+           You may obtain a copy of the License at
+        
+               http://www.apache.org/licenses/LICENSE-2.0
+        
+           Unless required by applicable law or agreed to in writing, software
+           distributed under the License is distributed on an "AS IS" BASIS,
+           WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+           See the License for the specific language governing permissions and
+           limitations under the License.
+        
+        Copyright 2026 Patrick Roebuck / Smart AI Memory
+        
+Project-URL: Homepage, https://github.com/Smart-AI-Memory/attune-rag
+Project-URL: Repository, https://github.com/Smart-AI-Memory/attune-rag
+Project-URL: Documentation, https://github.com/Smart-AI-Memory/attune-rag/blob/main/README.md
+Project-URL: Changelog, https://github.com/Smart-AI-Memory/attune-rag/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/Smart-AI-Memory/attune-rag/issues
+Keywords: rag,retrieval-augmented-generation,llm,claude,openai,gemini,grounding,provenance,attune
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Text Processing :: Markup :: Markdown
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: structlog>=24.0
+Requires-Dist: jinja2>=3.1.0
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: attune-help
+Requires-Dist: attune-help<0.6,>=0.5.1; extra == "attune-help"
+Provides-Extra: claude
+Requires-Dist: anthropic<1.0,>=0.40.0; extra == "claude"
+Provides-Extra: openai
+Requires-Dist: openai<2.0,>=1.40.0; extra == "openai"
+Provides-Extra: gemini
+Requires-Dist: google-genai<2.0,>=1.0; extra == "gemini"
+Provides-Extra: all
+Requires-Dist: attune-help<0.6,>=0.5.1; extra == "all"
+Requires-Dist: anthropic<1.0,>=0.40.0; extra == "all"
+Requires-Dist: openai<2.0,>=1.40.0; extra == "all"
+Requires-Dist: google-genai<2.0,>=1.0; extra == "all"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: ruff>=0.4.0; extra == "dev"
+Requires-Dist: black>=24.0; extra == "dev"
+Requires-Dist: build>=1.0; extra == "dev"
+Requires-Dist: twine>=5.0; extra == "dev"
+Requires-Dist: attune-help<0.6,>=0.5.1; extra == "dev"
+Requires-Dist: anthropic<1.0,>=0.40.0; extra == "dev"
+Requires-Dist: openai<2.0,>=1.40.0; extra == "dev"
+Requires-Dist: google-genai<2.0,>=1.0; extra == "dev"
+Dynamic: license-file
+
+# attune-rag
+
+Lightweight, LLM-agnostic RAG pipeline with pluggable
+corpora. Works with Claude, OpenAI, Gemini, or any LLM.
+
+- **No LLM SDK at install time.** All provider deps are
+  optional extras.
+- **Pluggable corpus.** Use attune-help (the default), any
+  markdown directory, or your own `CorpusProtocol`.
+- **Returns a prompt string** by default — send it to
+  whatever LLM you like. Optional provider adapters ship
+  convenience wrappers.
+
+## Install
+
+```bash
+pip install attune-rag                     # core only
+pip install 'attune-rag[attune-help]'      # + bundled help corpus
+pip install 'attune-rag[claude]'           # + Claude adapter
+pip install 'attune-rag[openai]'           # + OpenAI adapter
+pip install 'attune-rag[gemini]'           # + Gemini adapter
+pip install 'attune-rag[all]'              # everything
+```
+
+## Quick start — Claude
+
+```bash
+pip install 'attune-rag[attune-help,claude]'
+```
+
+```python
+import asyncio
+from attune_rag import RagPipeline
+
+async def main():
+    pipeline = RagPipeline()  # defaults to AttuneHelpCorpus
+    response, result = await pipeline.run_and_generate(
+        "How do I run a security audit with attune?",
+        provider="claude",
+    )
+    print(response)
+    print("\nSources:", [h.entry.path for h in result.citation.hits])
+
+asyncio.run(main())
+```
+
+## Quick start — OpenAI
+
+```bash
+pip install 'attune-rag[attune-help,openai]'
+```
+
+```python
+response, result = await pipeline.run_and_generate(
+    "...", provider="openai", model="gpt-4o",
+)
+```
+
+## Quick start — Gemini
+
+```bash
+pip install 'attune-rag[attune-help,gemini]'
+```
+
+```python
+response, result = await pipeline.run_and_generate(
+    "...", provider="gemini", model="gemini-1.5-pro",
+)
+```
+
+## Quick start — custom corpus, any LLM
+
+```python
+from pathlib import Path
+from attune_rag import RagPipeline, DirectoryCorpus
+
+pipeline = RagPipeline(corpus=DirectoryCorpus(Path("./my-docs")))
+result = pipeline.run("How do I...?")
+
+# Send result.augmented_prompt to whatever LLM you use.
+# The pipeline itself does NOT call an LLM unless you use
+# run_and_generate or call a provider adapter yourself.
+```
+
+## Status
+
+v0.1.0 — initial release. Part of the attune ecosystem
+([attune-ai](https://github.com/Smart-AI-Memory/attune-ai),
+[attune-help](https://github.com/Smart-AI-Memory/attune-help),
+[attune-author](https://github.com/Smart-AI-Memory/attune-author)).
+
+## License
+
+Apache 2.0. See
+[LICENSE](https://github.com/Smart-AI-Memory/attune-rag/blob/main/LICENSE).

attune_rag-0.1.0/README.md

@@ -0,0 +1,95 @@
+# attune-rag
+
+Lightweight, LLM-agnostic RAG pipeline with pluggable
+corpora. Works with Claude, OpenAI, Gemini, or any LLM.
+
+- **No LLM SDK at install time.** All provider deps are
+  optional extras.
+- **Pluggable corpus.** Use attune-help (the default), any
+  markdown directory, or your own `CorpusProtocol`.
+- **Returns a prompt string** by default — send it to
+  whatever LLM you like. Optional provider adapters ship
+  convenience wrappers.
+
+## Install
+
+```bash
+pip install attune-rag                     # core only
+pip install 'attune-rag[attune-help]'      # + bundled help corpus
+pip install 'attune-rag[claude]'           # + Claude adapter
+pip install 'attune-rag[openai]'           # + OpenAI adapter
+pip install 'attune-rag[gemini]'           # + Gemini adapter
+pip install 'attune-rag[all]'              # everything
+```
+
+## Quick start — Claude
+
+```bash
+pip install 'attune-rag[attune-help,claude]'
+```
+
+```python
+import asyncio
+from attune_rag import RagPipeline
+
+async def main():
+    pipeline = RagPipeline()  # defaults to AttuneHelpCorpus
+    response, result = await pipeline.run_and_generate(
+        "How do I run a security audit with attune?",
+        provider="claude",
+    )
+    print(response)
+    print("\nSources:", [h.entry.path for h in result.citation.hits])
+
+asyncio.run(main())
+```
+
+## Quick start — OpenAI
+
+```bash
+pip install 'attune-rag[attune-help,openai]'
+```
+
+```python
+response, result = await pipeline.run_and_generate(
+    "...", provider="openai", model="gpt-4o",
+)
+```
+
+## Quick start — Gemini
+
+```bash
+pip install 'attune-rag[attune-help,gemini]'
+```
+
+```python
+response, result = await pipeline.run_and_generate(
+    "...", provider="gemini", model="gemini-1.5-pro",
+)
+```
+
+## Quick start — custom corpus, any LLM
+
+```python
+from pathlib import Path
+from attune_rag import RagPipeline, DirectoryCorpus
+
+pipeline = RagPipeline(corpus=DirectoryCorpus(Path("./my-docs")))
+result = pipeline.run("How do I...?")
+
+# Send result.augmented_prompt to whatever LLM you use.
+# The pipeline itself does NOT call an LLM unless you use
+# run_and_generate or call a provider adapter yourself.
+```
+
+## Status
+
+v0.1.0 — initial release. Part of the attune ecosystem
+([attune-ai](https://github.com/Smart-AI-Memory/attune-ai),
+[attune-help](https://github.com/Smart-AI-Memory/attune-help),
+[attune-author](https://github.com/Smart-AI-Memory/attune-author)).
+
+## License
+
+Apache 2.0. See
+[LICENSE](https://github.com/Smart-AI-Memory/attune-rag/blob/main/LICENSE).

attune_rag-0.1.0/pyproject.toml

@@ -0,0 +1,95 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "attune-rag"
+version = "0.1.0"
+description = "Lightweight, LLM-agnostic RAG pipeline with pluggable corpora. Works with Claude, OpenAI, Gemini, or any LLM."
+readme = {file = "README.md", content-type = "text/markdown"}
+requires-python = ">=3.10"
+license = {file = "LICENSE"}
+authors = [
+    {name = "Patrick Roebuck", email = "admin@smartaimemory.com"}
+]
+keywords = [
+    "rag",
+    "retrieval-augmented-generation",
+    "llm",
+    "claude",
+    "openai",
+    "gemini",
+    "grounding",
+    "provenance",
+    "attune",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries",
+    "Topic :: Text Processing :: Markup :: Markdown",
+]
+dependencies = [
+    "structlog>=24.0",
+    "jinja2>=3.1.0",
+    "pyyaml>=6.0",
+]
+
+[project.optional-dependencies]
+attune-help = ["attune-help>=0.5.1,<0.6"]
+claude = ["anthropic>=0.40.0,<1.0"]
+openai = ["openai>=1.40.0,<2.0"]
+gemini = ["google-genai>=1.0,<2.0"]
+all = [
+    "attune-help>=0.5.1,<0.6",
+    "anthropic>=0.40.0,<1.0",
+    "openai>=1.40.0,<2.0",
+    "google-genai>=1.0,<2.0",
+]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "pytest-cov>=4.0",
+    "ruff>=0.4.0",
+    "black>=24.0",
+    "build>=1.0",
+    "twine>=5.0",
+    "attune-help>=0.5.1,<0.6",
+    "anthropic>=0.40.0,<1.0",
+    "openai>=1.40.0,<2.0",
+    "google-genai>=1.0,<2.0",
+]
+
+[project.scripts]
+attune-rag = "attune_rag.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/Smart-AI-Memory/attune-rag"
+Repository = "https://github.com/Smart-AI-Memory/attune-rag"
+Documentation = "https://github.com/Smart-AI-Memory/attune-rag/blob/main/README.md"
+Changelog = "https://github.com/Smart-AI-Memory/attune-rag/blob/main/CHANGELOG.md"
+Issues = "https://github.com/Smart-AI-Memory/attune-rag/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "B", "BLE", "UP"]
+
+[tool.black]
+line-length = 100
+target-version = ["py310"]

attune_rag-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

attune_rag-0.1.0/src/attune_rag/__init__.py

@@ -0,0 +1,44 @@
+"""Lightweight, LLM-agnostic RAG pipeline.
+
+Core public API:
+
+- RagPipeline — orchestrates retrieval + prompt assembly
+- RagResult — return value of RagPipeline.run
+- CitationRecord, CitedSource — provenance records
+- CorpusProtocol, RetrievalEntry — pluggable corpus interface
+- DirectoryCorpus — generic markdown directory loader
+- AttuneHelpCorpus — attune-help bundled corpus (opt. dep)
+- KeywordRetriever — default retriever (no embedding)
+- build_augmented_prompt — prompt template helper
+
+See spec: attune-ai/.claude/plans/feature-rag-code-
+grounding-2026-04-17.md (v4.0).
+
+Subsequent tasks in the spec fill in each module.
+"""
+
+__version__ = "0.1.0"
+
+# NOTE: Imports are added incrementally as tasks 1.2-1.8
+# land. For task 1.1 (scaffold only) the public names
+# below resolve to minimal stubs so imports work for CI.
+from .corpus import CorpusProtocol, DirectoryCorpus, RetrievalEntry
+from .pipeline import RagPipeline, RagResult
+from .prompts import build_augmented_prompt
+from .provenance import CitationRecord, CitedSource, format_citations_markdown
+from .retrieval import KeywordRetriever, RetrievalHit, RetrieverProtocol
+
+__all__ = [
+    "RagPipeline",
+    "RagResult",
+    "CitationRecord",
+    "CitedSource",
+    "format_citations_markdown",
+    "CorpusProtocol",
+    "RetrievalEntry",
+    "DirectoryCorpus",
+    "KeywordRetriever",
+    "RetrievalHit",
+    "RetrieverProtocol",
+    "build_augmented_prompt",
+]

attune_rag-0.1.0/src/attune_rag/benchmark.py

@@ -0,0 +1,182 @@
+"""Retrieval-quality benchmark runner.
+
+Run via::
+
+    python -m attune_rag.benchmark
+    python -m attune_rag.benchmark --queries path/to/queries.yaml
+    python -m attune_rag.benchmark --min-precision 0.70
+
+Prints precision@1, recall@3, and mean latency. Exits 1 if
+precision@1 falls below ``--min-precision`` so CI can gate.
+
+Queries file format matches tests/golden/queries.yaml.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+import time
+from pathlib import Path
+from typing import Any
+
+
+def _default_queries_path() -> Path:
+    return Path(__file__).resolve().parent.parent.parent / "tests" / "golden" / "queries.yaml"
+
+
+def _load_queries(path: Path) -> list[dict[str, Any]]:
+    import yaml
+
+    data = yaml.safe_load(path.read_text(encoding="utf-8"))
+    queries = data.get("queries", [])
+    if not queries:
+        raise ValueError(f"No queries found in {path}")
+    return queries
+
+
+def _run_benchmark(
+    queries: list[dict[str, Any]],
+    k: int,
+) -> dict[str, Any]:
+    from . import RagPipeline
+
+    pipeline = RagPipeline()
+    retriever_name = type(pipeline.retriever).__name__
+    corpus_name = pipeline.corpus.name
+
+    precision_hits = 0  # top-1 matches an expected path
+    recall_hits = 0  # any expected path is in top-k hits
+    latencies_ms: list[float] = []
+    per_query_results: list[dict[str, Any]] = []
+
+    for entry in queries:
+        expected = set(entry.get("expected_in_top_3", []))
+        start = time.perf_counter()
+        result = pipeline.run(entry["query"], k=k)
+        latencies_ms.append((time.perf_counter() - start) * 1000.0)
+
+        hit_paths = [h.template_path for h in result.citation.hits]
+        top1_hit = bool(hit_paths and hit_paths[0] in expected)
+        topk_hit = bool(set(hit_paths) & expected)
+
+        if top1_hit:
+            precision_hits += 1
+        if topk_hit:
+            recall_hits += 1
+
+        per_query_results.append(
+            {
+                "id": entry["id"],
+                "difficulty": entry.get("difficulty", ""),
+                "query": entry["query"],
+                "expected": sorted(expected),
+                "actual": hit_paths,
+                "top1_match": top1_hit,
+                "topk_match": topk_hit,
+            }
+        )
+
+    total = len(queries)
+    return {
+        "retriever": retriever_name,
+        "corpus": corpus_name,
+        "total_queries": total,
+        "precision_at_1": precision_hits / total if total else 0.0,
+        "recall_at_k": recall_hits / total if total else 0.0,
+        "k": k,
+        "mean_latency_ms": sum(latencies_ms) / len(latencies_ms) if latencies_ms else 0.0,
+        "max_latency_ms": max(latencies_ms) if latencies_ms else 0.0,
+        "per_query": per_query_results,
+    }
+
+
+def _print_summary(report: dict[str, Any], verbose: bool) -> None:
+    total = report["total_queries"]
+    p1 = report["precision_at_1"]
+    rk = report["recall_at_k"]
+    k = report["k"]
+    print(f"Retriever:  {report['retriever']}")
+    print(f"Corpus:     {report['corpus']}")
+    print(f"Queries:    {total}")
+    print(f"Precision@1: {p1:.2%} ({int(p1 * total)}/{total})")
+    print(f"Recall@{k}:    {rk:.2%} ({int(rk * total)}/{total})")
+    print(f"Mean latency: {report['mean_latency_ms']:.2f}ms")
+    print(f"Max latency:  {report['max_latency_ms']:.2f}ms")
+
+    by_difficulty: dict[str, dict[str, int]] = {}
+    for q in report["per_query"]:
+        d = q.get("difficulty", "unknown") or "unknown"
+        bucket = by_difficulty.setdefault(d, {"total": 0, "top1": 0, "topk": 0})
+        bucket["total"] += 1
+        if q["top1_match"]:
+            bucket["top1"] += 1
+        if q["topk_match"]:
+            bucket["topk"] += 1
+
+    if by_difficulty:
+        print("\nBreakdown by difficulty:")
+        for d in ("easy", "medium", "hard"):
+            b = by_difficulty.get(d)
+            if not b:
+                continue
+            print(f"  {d:7} P@1={b['top1']}/{b['total']}  R@{k}={b['topk']}/{b['total']}")
+
+    if verbose:
+        print("\nPer-query detail:")
+        for q in report["per_query"]:
+            mark = "OK" if q["topk_match"] else "MISS"
+            top1 = "*" if q["top1_match"] else " "
+            print(f"  [{mark}{top1}] {q['id']} ({q['difficulty']}): {q['query']!r}")
+            if not q["topk_match"]:
+                print(f"        expected: {q['expected']}")
+                print(f"        actual:   {q['actual']}")
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="attune-rag-benchmark",
+        description="Measure retrieval precision@1 / recall@k against a golden-query set.",
+    )
+    parser.add_argument(
+        "--queries",
+        type=Path,
+        default=_default_queries_path(),
+        help=f"Path to queries.yaml (default: {_default_queries_path()})",
+    )
+    parser.add_argument("-k", type=int, default=3, help="Top-k for recall (default 3)")
+    parser.add_argument(
+        "--min-precision",
+        type=float,
+        default=0.70,
+        help="Fail (exit 1) if precision@1 falls below this (default 0.70)",
+    )
+    parser.add_argument(
+        "--verbose",
+        "-v",
+        action="store_true",
+        help="Print per-query detail including misses",
+    )
+    args = parser.parse_args(argv)
+
+    if not args.queries.is_file():
+        print(f"Queries file not found: {args.queries}", file=sys.stderr)
+        return 2
+
+    queries = _load_queries(args.queries)
+    report = _run_benchmark(queries, k=args.k)
+    _print_summary(report, verbose=args.verbose)
+
+    if report["precision_at_1"] < args.min_precision:
+        print(
+            f"\nFAIL: precision@1 {report['precision_at_1']:.2%} "
+            f"< gate {args.min_precision:.2%}",
+            file=sys.stderr,
+        )
+        return 1
+    print(f"\nPASS: precision@1 meets gate ({args.min_precision:.2%}).")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())