ragpick 0.1.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- ragpick/__init__.py +39 -0
- ragpick/blueprints/__init__.py +93 -0
- ragpick/blueprints/agentic.yaml +10 -0
- ragpick/blueprints/corrective.yaml +10 -0
- ragpick/blueprints/graph.yaml +11 -0
- ragpick/blueprints/hybrid.yaml +25 -0
- ragpick/blueprints/naive.yaml +24 -0
- ragpick/blueprints/parent_child.yaml +11 -0
- ragpick/blueprints/sql.yaml +10 -0
- ragpick/cli.py +500 -0
- ragpick/components/__init__.py +23 -0
- ragpick/components/_optional.py +16 -0
- ragpick/components/chunkers.py +139 -0
- ragpick/components/embedders.py +158 -0
- ragpick/components/generators.py +294 -0
- ragpick/components/keyword.py +216 -0
- ragpick/components/loaders.py +145 -0
- ragpick/components/rerankers.py +53 -0
- ragpick/components/retrievers.py +118 -0
- ragpick/components/stores.py +291 -0
- ragpick/config.py +325 -0
- ragpick/errors.py +51 -0
- ragpick/eval/__init__.py +17 -0
- ragpick/eval/dataset.py +60 -0
- ragpick/eval/metrics.py +133 -0
- ragpick/eval/prompts.py +43 -0
- ragpick/eval/runner.py +276 -0
- ragpick/filters.py +69 -0
- ragpick/interfaces.py +139 -0
- ragpick/models.py +71 -0
- ragpick/pipeline.py +293 -0
- ragpick/py.typed +0 -0
- ragpick/registry.py +201 -0
- ragpick/selector/__init__.py +5 -0
- ragpick/selector/rules.py +292 -0
- ragpick-0.1.0.dist-info/METADATA +227 -0
- ragpick-0.1.0.dist-info/RECORD +41 -0
- ragpick-0.1.0.dist-info/WHEEL +4 -0
- ragpick-0.1.0.dist-info/entry_points.txt +2 -0
- ragpick-0.1.0.dist-info/licenses/LICENSE +202 -0
- ragpick-0.1.0.dist-info/licenses/NOTICE +5 -0
ragpick/__init__.py
ADDED
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
"""ragpick: choose, build, evaluate, and run the right RAG architecture.
|
|
2
|
+
|
|
3
|
+
Public API::
|
|
4
|
+
|
|
5
|
+
from ragpick import Pipeline, load_config, registry
|
|
6
|
+
|
|
7
|
+
p = Pipeline.from_yaml("rag.yaml")
|
|
8
|
+
p.ingest("./docs")
|
|
9
|
+
answer = p.query("How do I reset my password?", groups=["support"])
|
|
10
|
+
"""
|
|
11
|
+
|
|
12
|
+
from __future__ import annotations
|
|
13
|
+
|
|
14
|
+
import logging
|
|
15
|
+
|
|
16
|
+
from ragpick.config import RagConfig, load_config
|
|
17
|
+
from ragpick.errors import RagpickError
|
|
18
|
+
from ragpick.models import Answer, Chunk, Document, RetrievedChunk, Usage
|
|
19
|
+
from ragpick.pipeline import Pipeline
|
|
20
|
+
from ragpick.registry import register, registry
|
|
21
|
+
|
|
22
|
+
__version__ = "0.1.0"
|
|
23
|
+
|
|
24
|
+
__all__ = [
|
|
25
|
+
"Answer",
|
|
26
|
+
"Chunk",
|
|
27
|
+
"Document",
|
|
28
|
+
"Pipeline",
|
|
29
|
+
"RagConfig",
|
|
30
|
+
"RagpickError",
|
|
31
|
+
"RetrievedChunk",
|
|
32
|
+
"Usage",
|
|
33
|
+
"__version__",
|
|
34
|
+
"load_config",
|
|
35
|
+
"register",
|
|
36
|
+
"registry",
|
|
37
|
+
]
|
|
38
|
+
|
|
39
|
+
logging.getLogger(__name__).addHandler(logging.NullHandler())
|
|
@@ -0,0 +1,93 @@
|
|
|
1
|
+
"""Blueprints: named, tested RAG architectures shipped as YAML.
|
|
2
|
+
|
|
3
|
+
Each ``<name>.yaml`` in this package has a ``metadata`` header and, for stable
|
|
4
|
+
blueprints, a ``defaults`` section that is merged under the user's config.
|
|
5
|
+
"""
|
|
6
|
+
|
|
7
|
+
from __future__ import annotations
|
|
8
|
+
|
|
9
|
+
from functools import cache
|
|
10
|
+
from importlib import resources
|
|
11
|
+
from typing import Any, Literal
|
|
12
|
+
|
|
13
|
+
import yaml
|
|
14
|
+
from pydantic import BaseModel, Field
|
|
15
|
+
|
|
16
|
+
from ragpick.errors import BlueprintError
|
|
17
|
+
|
|
18
|
+
|
|
19
|
+
class BlueprintMeta(BaseModel):
|
|
20
|
+
"""Descriptive metadata for a blueprint."""
|
|
21
|
+
|
|
22
|
+
name: str
|
|
23
|
+
description: str
|
|
24
|
+
best_for: list[str] = Field(default_factory=list)
|
|
25
|
+
tradeoffs: list[str] = Field(default_factory=list)
|
|
26
|
+
status: Literal["stable", "planned"] = "stable"
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
class Blueprint(BaseModel):
|
|
30
|
+
"""A blueprint: metadata plus default config values."""
|
|
31
|
+
|
|
32
|
+
metadata: BlueprintMeta
|
|
33
|
+
defaults: dict[str, Any] = Field(default_factory=dict)
|
|
34
|
+
|
|
35
|
+
@property
|
|
36
|
+
def name(self) -> str:
|
|
37
|
+
"""Blueprint name."""
|
|
38
|
+
return self.metadata.name
|
|
39
|
+
|
|
40
|
+
@property
|
|
41
|
+
def is_stable(self) -> bool:
|
|
42
|
+
"""Whether the blueprint can be used today."""
|
|
43
|
+
return self.metadata.status == "stable"
|
|
44
|
+
|
|
45
|
+
|
|
46
|
+
_ORDER = ["naive", "hybrid", "parent_child", "sql", "graph", "agentic", "corrective"]
|
|
47
|
+
|
|
48
|
+
|
|
49
|
+
@cache
|
|
50
|
+
def _load_all() -> dict[str, Blueprint]:
|
|
51
|
+
found: dict[str, Blueprint] = {}
|
|
52
|
+
for entry in resources.files(__name__).iterdir():
|
|
53
|
+
if entry.name.endswith(".yaml"):
|
|
54
|
+
data = yaml.safe_load(entry.read_text(encoding="utf-8"))
|
|
55
|
+
bp = Blueprint.model_validate(data)
|
|
56
|
+
found[bp.name] = bp
|
|
57
|
+
order = {n: i for i, n in enumerate(_ORDER)}
|
|
58
|
+
return dict(sorted(found.items(), key=lambda kv: (order.get(kv[0], len(order)), kv[0])))
|
|
59
|
+
|
|
60
|
+
|
|
61
|
+
def list_blueprints(*, include_planned: bool = True) -> list[Blueprint]:
|
|
62
|
+
"""All shipped blueprints, stable ones first in roadmap order."""
|
|
63
|
+
return [bp for bp in _load_all().values() if include_planned or bp.is_stable]
|
|
64
|
+
|
|
65
|
+
|
|
66
|
+
def get_blueprint(name: str) -> Blueprint:
|
|
67
|
+
"""Return blueprint ``name`` (stable or planned).
|
|
68
|
+
|
|
69
|
+
Raises:
|
|
70
|
+
BlueprintError: unknown name.
|
|
71
|
+
"""
|
|
72
|
+
blueprints = _load_all()
|
|
73
|
+
if name not in blueprints:
|
|
74
|
+
raise BlueprintError(
|
|
75
|
+
f"Unknown blueprint '{name}'. Available blueprints: {', '.join(blueprints)}"
|
|
76
|
+
)
|
|
77
|
+
return blueprints[name]
|
|
78
|
+
|
|
79
|
+
|
|
80
|
+
def blueprint_defaults(name: str) -> dict[str, Any]:
|
|
81
|
+
"""Default config values for a *stable* blueprint (a deep copy).
|
|
82
|
+
|
|
83
|
+
Raises:
|
|
84
|
+
BlueprintError: unknown or planned blueprint.
|
|
85
|
+
"""
|
|
86
|
+
bp = get_blueprint(name)
|
|
87
|
+
if not bp.is_stable:
|
|
88
|
+
stable = ", ".join(b.name for b in list_blueprints(include_planned=False))
|
|
89
|
+
raise BlueprintError(
|
|
90
|
+
f"Blueprint '{name}' is planned for a future release and cannot be used yet. "
|
|
91
|
+
f"Stable blueprints: {stable}"
|
|
92
|
+
)
|
|
93
|
+
return yaml.safe_load(yaml.safe_dump(bp.defaults)) or {}
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
metadata:
|
|
2
|
+
name: agentic
|
|
3
|
+
description: >-
|
|
4
|
+
An agent plans, chooses among retrieval tools, and iterates until it can
|
|
5
|
+
answer.
|
|
6
|
+
best_for:
|
|
7
|
+
- complex questions that need several lookups or tools
|
|
8
|
+
tradeoffs:
|
|
9
|
+
- unpredictable latency and cost; harder to evaluate
|
|
10
|
+
status: planned
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
metadata:
|
|
2
|
+
name: corrective
|
|
3
|
+
description: >-
|
|
4
|
+
Corrective RAG: grade retrieved contexts, rewrite the query or fall back to
|
|
5
|
+
another source when retrieval quality is low.
|
|
6
|
+
best_for:
|
|
7
|
+
- noisy corpora where retrieval often misses
|
|
8
|
+
tradeoffs:
|
|
9
|
+
- extra LLM calls per query
|
|
10
|
+
status: planned
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
metadata:
|
|
2
|
+
name: graph
|
|
3
|
+
description: >-
|
|
4
|
+
GraphRAG: extract entities and relations into a knowledge graph and answer
|
|
5
|
+
multi-hop and global questions from graph neighbourhoods and summaries.
|
|
6
|
+
best_for:
|
|
7
|
+
- multi-hop questions across many documents
|
|
8
|
+
- global questions such as "what are the main themes?"
|
|
9
|
+
tradeoffs:
|
|
10
|
+
- expensive indexing (LLM extraction over the whole corpus)
|
|
11
|
+
status: planned
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
metadata:
|
|
2
|
+
name: hybrid
|
|
3
|
+
description: >-
|
|
4
|
+
BM25 keyword search and vector search fused with Reciprocal Rank Fusion,
|
|
5
|
+
with an optional cross-encoder reranker, then generation.
|
|
6
|
+
best_for:
|
|
7
|
+
- the default for commercial systems
|
|
8
|
+
- keyword-heavy domains (product codes, legal terms, IDs)
|
|
9
|
+
- medium and large corpora
|
|
10
|
+
tradeoffs:
|
|
11
|
+
- two indexes to build and keep in sync
|
|
12
|
+
- the optional reranker adds latency (tens to hundreds of ms)
|
|
13
|
+
status: stable
|
|
14
|
+
defaults:
|
|
15
|
+
components:
|
|
16
|
+
loader: {type: directory, params: {glob: "**/*"}}
|
|
17
|
+
chunker: {type: recursive, params: {chunk_size: 800, overlap: 100}}
|
|
18
|
+
embedder: {type: fake, params: {dimension: 256}}
|
|
19
|
+
store: {type: memory}
|
|
20
|
+
keyword_index: {type: bm25, params: {k1: 1.5, b: 0.75}}
|
|
21
|
+
retriever: {type: hybrid, params: {k: 20, rrf_k: 60}}
|
|
22
|
+
reranker: {type: none}
|
|
23
|
+
generator: {type: fake}
|
|
24
|
+
query:
|
|
25
|
+
top_k: 5
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
metadata:
|
|
2
|
+
name: naive
|
|
3
|
+
description: >-
|
|
4
|
+
Recursive chunking, dense embeddings, vector search, then generation.
|
|
5
|
+
The simplest architecture that works.
|
|
6
|
+
best_for:
|
|
7
|
+
- prototypes and demos
|
|
8
|
+
- small corpora (< 1k chunks)
|
|
9
|
+
- natural-language questions over prose
|
|
10
|
+
tradeoffs:
|
|
11
|
+
- misses exact-match terms (product codes, IDs, legal references)
|
|
12
|
+
- quality degrades as the corpus grows
|
|
13
|
+
status: stable
|
|
14
|
+
defaults:
|
|
15
|
+
components:
|
|
16
|
+
loader: {type: directory, params: {glob: "**/*"}}
|
|
17
|
+
chunker: {type: recursive, params: {chunk_size: 800, overlap: 100}}
|
|
18
|
+
embedder: {type: fake, params: {dimension: 256}}
|
|
19
|
+
store: {type: memory}
|
|
20
|
+
retriever: {type: vector, params: {k: 5}}
|
|
21
|
+
reranker: {type: none}
|
|
22
|
+
generator: {type: fake}
|
|
23
|
+
query:
|
|
24
|
+
top_k: 5
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
metadata:
|
|
2
|
+
name: parent_child
|
|
3
|
+
description: >-
|
|
4
|
+
Retrieve small child chunks for precision, then pass their larger parent
|
|
5
|
+
sections to the generator for context.
|
|
6
|
+
best_for:
|
|
7
|
+
- long structured documents (manuals, policies, contracts)
|
|
8
|
+
- questions whose answer needs surrounding context
|
|
9
|
+
tradeoffs:
|
|
10
|
+
- larger prompts and higher token cost
|
|
11
|
+
status: planned
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
metadata:
|
|
2
|
+
name: sql
|
|
3
|
+
description: >-
|
|
4
|
+
Text-to-SQL over structured data: the model writes a query, ragpick runs it
|
|
5
|
+
read-only and answers from the result rows.
|
|
6
|
+
best_for:
|
|
7
|
+
- databases, CSV exports, analytics questions ("how many", "top 10")
|
|
8
|
+
tradeoffs:
|
|
9
|
+
- needs schema descriptions and strict read-only sandboxing
|
|
10
|
+
status: planned
|