chunkbuster 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.
@@ -0,0 +1,36 @@
1
+ """Public API for chunkbuster."""
2
+
3
+ from .core import ComponentBindings, Query, RankedItem, Ranking
4
+ from .retrieval import (
5
+ Chunk,
6
+ RetrievalOutput,
7
+ RetrievalPipeline,
8
+ RetrievalPipelineResult,
9
+ )
10
+ from .tree_classification import (
11
+ ClassificationDecision,
12
+ Taxonomy,
13
+ TaxonomyEdge,
14
+ TaxonomyNode,
15
+ TaxonomyPath,
16
+ TreeClassificationPipeline,
17
+ TreeClassificationResult,
18
+ )
19
+
20
+ __all__ = [
21
+ "ClassificationDecision",
22
+ "Chunk",
23
+ "ComponentBindings",
24
+ "Query",
25
+ "RankedItem",
26
+ "Ranking",
27
+ "RetrievalOutput",
28
+ "RetrievalPipeline",
29
+ "RetrievalPipelineResult",
30
+ "Taxonomy",
31
+ "TaxonomyEdge",
32
+ "TaxonomyNode",
33
+ "TaxonomyPath",
34
+ "TreeClassificationPipeline",
35
+ "TreeClassificationResult",
36
+ ]
@@ -0,0 +1,8 @@
1
+ """Small contracts shared by both products."""
2
+
3
+ from .contracts import ComponentBindings
4
+ from .models import Query
5
+ from .ranking import RankedItem, Ranking
6
+
7
+ __all__ = ["ComponentBindings", "Query", "RankedItem", "Ranking"]
8
+
@@ -0,0 +1,11 @@
1
+ """Internal support for sync and async user adapters."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from inspect import isawaitable
6
+ from typing import Any
7
+
8
+
9
+ async def resolve(value: Any) -> Any:
10
+ return await value if isawaitable(value) else value
11
+
@@ -0,0 +1,51 @@
1
+ """Strict configuration loading shared by both products."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import json
6
+ from collections.abc import Mapping
7
+ from copy import deepcopy
8
+ from pathlib import Path
9
+ from typing import Any
10
+
11
+ import yaml
12
+ from pydantic import BaseModel, ConfigDict, ValidationError
13
+
14
+ from ..errors import ConfigurationError
15
+
16
+ ConfigInput = str | Path | Mapping[str, Any] | BaseModel
17
+
18
+
19
+ class StrictConfig(BaseModel):
20
+ """Immutable base for product-specific configurations."""
21
+
22
+ model_config = ConfigDict(extra="forbid", frozen=True, allow_inf_nan=False)
23
+
24
+
25
+ def load_config[ConfigModel: BaseModel](
26
+ source: ConfigInput,
27
+ model: type[ConfigModel],
28
+ ) -> ConfigModel:
29
+ """Load YAML, JSON, a mapping, or another validated model."""
30
+ try:
31
+ if isinstance(source, BaseModel):
32
+ data: Any = source.model_dump(mode="python")
33
+ elif isinstance(source, Mapping):
34
+ data = deepcopy(dict(source))
35
+ else:
36
+ path = Path(source)
37
+ if path.suffix.lower() in {".yaml", ".yml"}:
38
+ data = yaml.safe_load(path.read_text(encoding="utf-8"))
39
+ elif path.suffix.lower() == ".json":
40
+ data = json.loads(path.read_text(encoding="utf-8"))
41
+ else:
42
+ raise ConfigurationError(
43
+ "config path must end in .yaml, .yml, or .json"
44
+ )
45
+ if not isinstance(data, Mapping):
46
+ raise ConfigurationError("config root must be a mapping")
47
+ return model.model_validate(data)
48
+ except ConfigurationError:
49
+ raise
50
+ except (OSError, ValueError, yaml.YAMLError, ValidationError) as exc:
51
+ raise ConfigurationError(f"invalid configuration: {exc}") from exc
@@ -0,0 +1,24 @@
1
+ """Injection container for external components."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from collections.abc import Mapping
6
+ from dataclasses import dataclass, field
7
+ from types import MappingProxyType
8
+ from typing import Any
9
+
10
+
11
+ def _freeze(values: Mapping[str, Any]) -> Mapping[str, Any]:
12
+ return MappingProxyType(dict(values))
13
+
14
+
15
+ @dataclass(frozen=True, slots=True)
16
+ class ComponentBindings:
17
+ """Concrete external objects, keyed by the config's ``binding`` value."""
18
+
19
+ preprocessors: Mapping[str, Any] = field(default_factory=dict)
20
+ retrievers: Mapping[str, Any] = field(default_factory=dict)
21
+
22
+ def __post_init__(self) -> None:
23
+ for name in ("preprocessors", "retrievers"):
24
+ object.__setattr__(self, name, _freeze(getattr(self, name)))
@@ -0,0 +1,62 @@
1
+ """Minimal named-dependency validation using the standard library."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from collections.abc import Mapping
6
+ from dataclasses import dataclass
7
+ from graphlib import CycleError, TopologicalSorter
8
+ from types import MappingProxyType
9
+
10
+ from ..errors import BuildError
11
+
12
+
13
+ @dataclass(frozen=True, slots=True)
14
+ class CompiledDAG:
15
+ order: tuple[str, ...]
16
+ dependencies: Mapping[str, tuple[str, ...]]
17
+
18
+
19
+ def compile_dag(
20
+ dependencies: Mapping[str, tuple[str, ...]],
21
+ outputs: Mapping[str, str],
22
+ ) -> CompiledDAG:
23
+ """Validate references, cycles, outputs, and unused nodes."""
24
+ deps = {name: tuple(values) for name, values in dependencies.items()}
25
+ if not deps:
26
+ raise BuildError("pipeline must declare at least one executable node")
27
+ if not outputs:
28
+ raise BuildError("pipeline must declare at least one output")
29
+ for name, values in deps.items():
30
+ missing = set(values) - set(deps)
31
+ if missing:
32
+ raise BuildError(
33
+ f"node {name!r} references unknown nodes {sorted(missing)!r}"
34
+ )
35
+ if len(values) != len(set(values)):
36
+ raise BuildError(f"node {name!r} repeats an input")
37
+ missing_outputs = set(outputs.values()) - set(deps)
38
+ if missing_outputs:
39
+ raise BuildError(f"outputs reference unknown nodes {sorted(missing_outputs)!r}")
40
+ try:
41
+ order = tuple(TopologicalSorter(deps).static_order())
42
+ except CycleError as exc:
43
+ raise BuildError("pipeline graph contains a cycle") from exc
44
+
45
+ reachable: set[str] = set()
46
+
47
+ def visit(name: str) -> None:
48
+ if name in reachable:
49
+ return
50
+ reachable.add(name)
51
+ for dependency in deps[name]:
52
+ visit(dependency)
53
+
54
+ for terminal in outputs.values():
55
+ visit(terminal)
56
+ unused = set(deps) - reachable
57
+ if unused:
58
+ raise BuildError(f"pipeline contains unused nodes {sorted(unused)!r}")
59
+ return CompiledDAG(
60
+ tuple(name for name in order if name in reachable),
61
+ MappingProxyType(deps),
62
+ )
@@ -0,0 +1,35 @@
1
+ """Shared immutable value objects."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from collections.abc import Mapping
6
+ from dataclasses import dataclass, field
7
+ from types import MappingProxyType
8
+ from typing import Any
9
+
10
+
11
+ def freeze_mapping(value: Mapping[str, Any] | None) -> Mapping[str, Any]:
12
+ """Return a detached, read-only shallow mapping."""
13
+ return MappingProxyType(dict(value or {}))
14
+
15
+
16
+ @dataclass(frozen=True, slots=True)
17
+ class Query:
18
+ """One text query with optional caller identity and metadata."""
19
+
20
+ text: str
21
+ id: str | None = None
22
+ metadata: Mapping[str, Any] = field(default_factory=dict)
23
+
24
+ def __post_init__(self) -> None:
25
+ if not isinstance(self.text, str) or not self.text.strip():
26
+ raise ValueError("query text must be a non-empty string")
27
+ if self.id is not None and (not isinstance(self.id, str) or not self.id):
28
+ raise ValueError("query id must be a non-empty string or None")
29
+ object.__setattr__(self, "metadata", freeze_mapping(self.metadata))
30
+
31
+
32
+ def as_query(value: str | Query) -> Query:
33
+ """Normalize the public query shorthand."""
34
+ return Query(value) if isinstance(value, str) else value
35
+
@@ -0,0 +1,137 @@
1
+ """Immutable rankings and the first shared fusion strategy."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from collections.abc import Mapping
6
+ from dataclasses import dataclass, field, replace
7
+ from math import isfinite
8
+ from types import MappingProxyType
9
+ from typing import Any
10
+
11
+ from ..errors import InvalidModelOutputError
12
+
13
+
14
+ @dataclass(frozen=True, slots=True)
15
+ class RankedItem[Item]:
16
+ """One canonically identified item at one ranking stage."""
17
+
18
+ id: str
19
+ item: Item
20
+ score: float
21
+ rank: int = 0
22
+ provenance: tuple[str, ...] = ()
23
+ metadata: Mapping[str, Any] = field(default_factory=dict)
24
+
25
+ def __post_init__(self) -> None:
26
+ if not isinstance(self.id, str) or not self.id:
27
+ raise ValueError("ranked item id must be a non-empty string")
28
+ if not isfinite(float(self.score)):
29
+ raise ValueError("ranked item score must be finite")
30
+ if self.rank < 0:
31
+ raise ValueError("rank must be non-negative")
32
+ object.__setattr__(self, "score", float(self.score))
33
+ object.__setattr__(self, "metadata", MappingProxyType(dict(self.metadata)))
34
+
35
+
36
+ @dataclass(frozen=True, slots=True)
37
+ class Ranking[Item]:
38
+ """An ordered sequence with unique IDs and normalized one-based ranks."""
39
+
40
+ items: tuple[RankedItem[Item], ...] = ()
41
+ score_semantics: str = "raw"
42
+ origins: frozenset[str] = frozenset()
43
+
44
+ def __post_init__(self) -> None:
45
+ items = tuple(self.items)
46
+ ids = tuple(item.id for item in items)
47
+ if len(ids) != len(set(ids)):
48
+ raise ValueError("ranking item ids must be unique")
49
+ object.__setattr__(
50
+ self,
51
+ "items",
52
+ tuple(replace(item, rank=index) for index, item in enumerate(items, 1)),
53
+ )
54
+ object.__setattr__(self, "origins", frozenset(self.origins))
55
+
56
+ def __iter__(self):
57
+ return iter(self.items)
58
+
59
+ def __len__(self) -> int:
60
+ return len(self.items)
61
+
62
+ def __getitem__(self, index):
63
+ return self.items[index]
64
+
65
+ @property
66
+ def ids(self) -> tuple[str, ...]:
67
+ return tuple(item.id for item in self.items)
68
+
69
+ def top(self, count: int) -> Ranking[Item]:
70
+ if count <= 0:
71
+ raise ValueError("count must be positive")
72
+ return Ranking(self.items[:count], self.score_semantics, self.origins)
73
+
74
+
75
+ def require_ranking(value: Any, *, component: str) -> Ranking[Any]:
76
+ """Reject loose provider output at the component boundary."""
77
+ if not isinstance(value, Ranking):
78
+ raise InvalidModelOutputError(f"{component!r} must return Ranking")
79
+ return value
80
+
81
+
82
+ def require_subset[Item](
83
+ output: Ranking[Item],
84
+ candidates: Ranking[Any],
85
+ *,
86
+ component: str,
87
+ ) -> Ranking[Item]:
88
+ """Ensure a unary/candidate stage cannot invent identities."""
89
+ unknown = set(output.ids) - set(candidates.ids)
90
+ if unknown:
91
+ raise InvalidModelOutputError(
92
+ f"{component!r} returned identities outside its input: {sorted(unknown)!r}"
93
+ )
94
+ canonical = {item.id: item.item for item in candidates}
95
+ items = tuple(replace(item, item=canonical[item.id]) for item in output)
96
+ return Ranking(items, output.score_semantics, candidates.origins)
97
+
98
+
99
+ def reciprocal_rank_fusion[Item](
100
+ rankings: Mapping[str, Ranking[Item]],
101
+ *,
102
+ top_k: int,
103
+ k: int = 60,
104
+ ) -> Ranking[Item]:
105
+ """Fuse named rankings with deterministic reciprocal-rank fusion."""
106
+ if len(rankings) < 2:
107
+ raise ValueError("rrf requires at least two rankings")
108
+ if top_k <= 0 or k <= 0:
109
+ raise ValueError("rrf top_k and k must be positive")
110
+
111
+ totals: dict[str, float] = {}
112
+ examples: dict[str, RankedItem[Item]] = {}
113
+ seen_order: dict[str, int] = {}
114
+ origins: set[str] = set()
115
+ next_order = 0
116
+ for _source, ranking in rankings.items():
117
+ origins.update(ranking.origins)
118
+ for item in ranking:
119
+ totals[item.id] = totals.get(item.id, 0.0) + 1.0 / (k + item.rank)
120
+ examples.setdefault(item.id, item)
121
+ if item.id not in seen_order:
122
+ seen_order[item.id] = next_order
123
+ next_order += 1
124
+
125
+ ordered = sorted(
126
+ totals,
127
+ key=lambda item_id: (-totals[item_id], seen_order[item_id]),
128
+ )
129
+ items = tuple(
130
+ replace(
131
+ examples[item_id],
132
+ score=totals[item_id],
133
+ provenance=examples[item_id].provenance + ("rrf",),
134
+ )
135
+ for item_id in ordered[:top_k]
136
+ )
137
+ return Ranking(items, "rrf", frozenset(origins))
chunkbuster/errors.py ADDED
@@ -0,0 +1,34 @@
1
+ """Public exception hierarchy."""
2
+
3
+
4
+ class ChunkbusterError(Exception):
5
+ """Base error raised by chunkbuster."""
6
+
7
+
8
+ class ConfigurationError(ChunkbusterError):
9
+ """The serialized pipeline configuration is invalid."""
10
+
11
+
12
+ class BuildError(ChunkbusterError):
13
+ """A pipeline cannot be built from otherwise valid inputs."""
14
+
15
+
16
+ class InvalidTaxonomyError(BuildError):
17
+ """A taxonomy violates the strict-forest contract."""
18
+
19
+
20
+ class ExecutionError(ChunkbusterError):
21
+ """A built pipeline failed while processing one query."""
22
+
23
+
24
+ class PreprocessingError(ExecutionError):
25
+ """A query or stable document representation is invalid."""
26
+
27
+
28
+ class RetrievalError(ExecutionError):
29
+ """A retriever failed or returned an invalid ranking."""
30
+
31
+
32
+ class InvalidModelOutputError(ExecutionError):
33
+ """An external component returned identities outside its input."""
34
+
chunkbuster/py.typed ADDED
@@ -0,0 +1 @@
1
+
@@ -0,0 +1,11 @@
1
+ """Retrieval public surface."""
2
+
3
+ from .models import Chunk, RetrievalOutput, RetrievalPipelineResult
4
+ from .pipeline import RetrievalPipeline
5
+
6
+ __all__ = [
7
+ "Chunk",
8
+ "RetrievalOutput",
9
+ "RetrievalPipeline",
10
+ "RetrievalPipelineResult",
11
+ ]
@@ -0,0 +1,43 @@
1
+ """Configuration for the first retrieval vertical."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from typing import Annotated, Literal
6
+
7
+ from pydantic import Field
8
+
9
+ from ..core.config import StrictConfig
10
+
11
+ Name = Annotated[str, Field(min_length=1)]
12
+ PositiveInt = Annotated[int, Field(gt=0)]
13
+
14
+
15
+ class PreprocessorConfig(StrictConfig):
16
+ name: Name
17
+ binding: Name
18
+
19
+
20
+ class RetrieverConfig(StrictConfig):
21
+ name: Name
22
+ binding: Name
23
+ preprocessor: Name
24
+ input: Name | None = None
25
+ top_k: PositiveInt = 20
26
+
27
+
28
+ class RRFFusionConfig(StrictConfig):
29
+ name: Name
30
+ type: Literal["rrf"] = "rrf"
31
+ inputs: Annotated[tuple[Name, ...], Field(min_length=2)]
32
+ k: PositiveInt = 60
33
+ top_k: PositiveInt = 20
34
+
35
+
36
+ class RetrievalConfig(StrictConfig):
37
+ version: Literal[1] = 1
38
+ name: Name
39
+ kind: Literal["retrieve"] = "retrieve"
40
+ preprocessors: tuple[PreprocessorConfig, ...]
41
+ retrievers: tuple[RetrieverConfig, ...]
42
+ fusions: tuple[RRFFusionConfig, ...] = ()
43
+ outputs: dict[Name, Name]
@@ -0,0 +1,43 @@
1
+ """Immutable retrieval value objects."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from collections.abc import Mapping
6
+ from dataclasses import dataclass, field
7
+ from types import MappingProxyType
8
+ from typing import Any, Literal
9
+
10
+ from ..core.ranking import Ranking
11
+
12
+
13
+ @dataclass(frozen=True, slots=True)
14
+ class Chunk:
15
+ id: str
16
+ text: str
17
+ metadata: Mapping[str, Any] = field(default_factory=dict)
18
+
19
+ def __post_init__(self) -> None:
20
+ if not isinstance(self.id, str) or not self.id:
21
+ raise ValueError("chunk id must be a non-empty string")
22
+ if not isinstance(self.text, str) or not self.text:
23
+ raise ValueError("chunk text must be a non-empty string")
24
+ object.__setattr__(self, "metadata", MappingProxyType(dict(self.metadata)))
25
+
26
+
27
+ @dataclass(frozen=True, slots=True)
28
+ class RetrievalOutput:
29
+ terminal_node: str
30
+ ranking: Ranking[Chunk]
31
+
32
+ @property
33
+ def status(self) -> Literal["completed", "empty"]:
34
+ return "completed" if self.ranking else "empty"
35
+
36
+
37
+ @dataclass(frozen=True, slots=True)
38
+ class RetrievalPipelineResult:
39
+ query_id: str | None
40
+ outputs: Mapping[str, RetrievalOutput]
41
+
42
+ def __post_init__(self) -> None:
43
+ object.__setattr__(self, "outputs", MappingProxyType(dict(self.outputs)))