labelrag 0.0.0__tar.gz

labelrag-0.0.0/.gitignore

@@ -0,0 +1,18 @@
+.DS_Store
+.venv/
+venv/
+__pycache__/
+.pytest_cache/
+.ruff_cache/
+.pyright/
+.mypy_cache/
+coverage.xml
+.coverage
+dist/
+build/
+*.egg-info/
+site/
+docs/
+!docs/
+docs/*
+!docs/public_api.md

labelrag-0.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 huruilizhen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

labelrag-0.0.0/PKG-INFO

@@ -0,0 +1,212 @@
+Metadata-Version: 2.4
+Name: labelrag
+Version: 0.0.0
+Summary: A label-driven RAG pipeline built on top of paralabelgen.
+Project-URL: Homepage, https://github.com/HuRuilizhen/labelrag
+Project-URL: Repository, https://github.com/HuRuilizhen/labelrag
+Project-URL: Issues, https://github.com/HuRuilizhen/labelrag/issues
+Author-email: huruilizhen <huruilizhen@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: evaluation,labels,llm,paragraphs,rag,retrieval
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Requires-Dist: paralabelgen==0.2.0
+Provides-Extra: dev
+Requires-Dist: build>=1.2.0; extra == 'dev'
+Requires-Dist: pyright>=1.1.390; extra == 'dev'
+Requires-Dist: pytest-cov>=6.0.0; extra == 'dev'
+Requires-Dist: pytest>=8.3.0; extra == 'dev'
+Requires-Dist: ruff>=0.11.0; extra == 'dev'
+Requires-Dist: twine>=6.1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# labelrag
+
+`labelrag` is a Python library for label-driven retrieval-augmented generation
+pipelines built on top of `paralabelgen`.
+
+- PyPI distribution: `labelrag`
+- Python import package: `labelrag`
+- Core dependency target: `paralabelgen==0.2.0`
+- Default extraction path: spaCy via `paralabelgen`
+
+## Install
+
+```bash
+pip install labelrag
+```
+
+If you want to use the default spaCy-backed labeling path, install a compatible
+English pipeline such as:
+
+```bash
+python -m spacy download en_core_web_sm
+```
+
+`en_core_web_sm` is the recommended default model, but you can point the
+underlying `LabelGeneratorConfig` at another installed compatible spaCy
+pipeline.
+
+## Quick Start
+
+### Retrieval-only workflow
+
+```python
+from labelrag import RAGPipeline, RAGPipelineConfig
+
+paragraphs = [
+    "OpenAI builds language models for developers.",
+    "Developers use language models in production systems.",
+    "Production systems need monitoring and evaluation tooling.",
+]
+
+pipeline = RAGPipeline(RAGPipelineConfig())
+pipeline.fit(paragraphs)
+
+retrieval = pipeline.build_context("How do developers use language models?")
+print(retrieval.prompt_context)
+print(retrieval.metadata)
+```
+
+### Retrieval plus provider-backed answer generation
+
+```python
+from labelrag import (
+    OpenAICompatibleAnswerGenerator,
+    OpenAICompatibleConfig,
+    RAGPipeline,
+    RAGPipelineConfig,
+)
+
+paragraphs = [
+    "OpenAI builds language models for developers.",
+    "Developers use language models in production systems.",
+    "Production systems need monitoring and evaluation tooling.",
+]
+
+pipeline = RAGPipeline(RAGPipelineConfig())
+pipeline.fit(paragraphs)
+
+generator = OpenAICompatibleAnswerGenerator(
+    OpenAICompatibleConfig(
+        model="mistral-small-latest",
+        api_key_env_var="MISTRAL_API_KEY",
+        base_url="https://api.mistral.ai/v1",
+    )
+)
+
+answer = pipeline.answer_with_generator(
+    "How do developers use language models?",
+    generator,
+)
+print(answer.answer_text)
+print(answer.metadata)
+```
+
+## Retrieval Model
+
+The current retrieval layer is deterministic and label-driven.
+
+- `fit(...)` delegates paragraph analysis to `labelgen.LabelGenerator`
+- `build_context(...)` maps the question into the fitted label space
+- retrieval uses greedy coverage over query label IDs
+- label-free queries can fall back to deterministic concept overlap
+- `require_full_label_coverage=True` suppresses partial retrieval results while
+  preserving attempted coverage trace in metadata
+
+Tie-break order for greedy retrieval is:
+
+1. larger overlap with remaining query labels
+2. larger overlap on query concept IDs
+3. larger total paragraph label count
+4. lexicographically smaller `paragraph_id`
+
+## OpenAI-Compatible Provider Notes
+
+The built-in answer-generation adapter targets a minimal OpenAI-compatible
+chat-completions API surface.
+
+It supports:
+
+- standard base URLs such as `https://api.openai.com/v1`
+- full endpoint URLs such as `https://api.mistral.ai/v1/chat/completions`
+- API key injection through config or environment variables
+- non-streaming text generation for `answer_with_generator(...)`
+
+This adapter is intended to cover providers such as OpenAI, Mistral, and Qwen
+when they expose an OpenAI-compatible endpoint shape.
+
+## Public API
+
+The main public entrypoints are:
+
+- `RAGPipeline`
+- `RAGPipelineConfig`, `RetrievalConfig`, `PromptConfig`
+- `IndexedParagraph`, `QueryAnalysis`, `RetrievedParagraph`
+- `RetrievalResult`, `RAGAnswerResult`
+- `GeneratedAnswer`, `AnswerGenerator`
+- `OpenAICompatibleAnswerGenerator`, `OpenAICompatibleConfig`
+- convenience re-export: `Paragraph`
+
+Detailed API notes are available in [`docs/public_api.md`](docs/public_api.md).
+
+## Examples
+
+Runnable examples are available in [`examples/`](examples/):
+
+- [`examples/basic_usage.py`](examples/basic_usage.py)
+- [`examples/custom_config.py`](examples/custom_config.py)
+- [`examples/save_and_load.py`](examples/save_and_load.py)
+- [`examples/provider_answer.py`](examples/provider_answer.py)
+
+## Persistence Notes
+
+`save(path)` produces a human-inspectable directory containing:
+
+- `config.json`
+- `label_generator.json`
+- `corpus_index.json`
+- `fit_result.json`
+
+Public guarantee:
+
+- a saved and reloaded pipeline should preserve retrieval behavior for the same
+  fitted state, question, and config
+
+## Configuration Notes
+
+- `RetrievalConfig.max_paragraphs` sets the hard retrieval limit
+- `RetrievalConfig.allow_label_free_fallback` enables deterministic concept
+  overlap fallback for label-free queries
+- `RetrievalConfig.require_full_label_coverage` suppresses partial retrieval
+  output when not all query labels can be covered
+- `PromptConfig.include_paragraph_ids` includes stable paragraph IDs in the
+  rendered prompt context
+- `PromptConfig.include_label_annotations` includes paragraph label annotations
+  in rendered prompt context
+- `PromptConfig.max_context_characters` applies a hard cap to rendered context
+  length
+
+## Development Checks
+
+```bash
+.venv/bin/ruff check . --fix
+.venv/bin/pyright
+.venv/bin/pytest
+```
+
+## Release Checks
+
+```bash
+.venv/bin/python -m build
+.venv/bin/python -m twine check dist/*
+```

labelrag-0.0.0/README.md

@@ -0,0 +1,181 @@
+# labelrag
+
+`labelrag` is a Python library for label-driven retrieval-augmented generation
+pipelines built on top of `paralabelgen`.
+
+- PyPI distribution: `labelrag`
+- Python import package: `labelrag`
+- Core dependency target: `paralabelgen==0.2.0`
+- Default extraction path: spaCy via `paralabelgen`
+
+## Install
+
+```bash
+pip install labelrag
+```
+
+If you want to use the default spaCy-backed labeling path, install a compatible
+English pipeline such as:
+
+```bash
+python -m spacy download en_core_web_sm
+```
+
+`en_core_web_sm` is the recommended default model, but you can point the
+underlying `LabelGeneratorConfig` at another installed compatible spaCy
+pipeline.
+
+## Quick Start
+
+### Retrieval-only workflow
+
+```python
+from labelrag import RAGPipeline, RAGPipelineConfig
+
+paragraphs = [
+    "OpenAI builds language models for developers.",
+    "Developers use language models in production systems.",
+    "Production systems need monitoring and evaluation tooling.",
+]
+
+pipeline = RAGPipeline(RAGPipelineConfig())
+pipeline.fit(paragraphs)
+
+retrieval = pipeline.build_context("How do developers use language models?")
+print(retrieval.prompt_context)
+print(retrieval.metadata)
+```
+
+### Retrieval plus provider-backed answer generation
+
+```python
+from labelrag import (
+    OpenAICompatibleAnswerGenerator,
+    OpenAICompatibleConfig,
+    RAGPipeline,
+    RAGPipelineConfig,
+)
+
+paragraphs = [
+    "OpenAI builds language models for developers.",
+    "Developers use language models in production systems.",
+    "Production systems need monitoring and evaluation tooling.",
+]
+
+pipeline = RAGPipeline(RAGPipelineConfig())
+pipeline.fit(paragraphs)
+
+generator = OpenAICompatibleAnswerGenerator(
+    OpenAICompatibleConfig(
+        model="mistral-small-latest",
+        api_key_env_var="MISTRAL_API_KEY",
+        base_url="https://api.mistral.ai/v1",
+    )
+)
+
+answer = pipeline.answer_with_generator(
+    "How do developers use language models?",
+    generator,
+)
+print(answer.answer_text)
+print(answer.metadata)
+```
+
+## Retrieval Model
+
+The current retrieval layer is deterministic and label-driven.
+
+- `fit(...)` delegates paragraph analysis to `labelgen.LabelGenerator`
+- `build_context(...)` maps the question into the fitted label space
+- retrieval uses greedy coverage over query label IDs
+- label-free queries can fall back to deterministic concept overlap
+- `require_full_label_coverage=True` suppresses partial retrieval results while
+  preserving attempted coverage trace in metadata
+
+Tie-break order for greedy retrieval is:
+
+1. larger overlap with remaining query labels
+2. larger overlap on query concept IDs
+3. larger total paragraph label count
+4. lexicographically smaller `paragraph_id`
+
+## OpenAI-Compatible Provider Notes
+
+The built-in answer-generation adapter targets a minimal OpenAI-compatible
+chat-completions API surface.
+
+It supports:
+
+- standard base URLs such as `https://api.openai.com/v1`
+- full endpoint URLs such as `https://api.mistral.ai/v1/chat/completions`
+- API key injection through config or environment variables
+- non-streaming text generation for `answer_with_generator(...)`
+
+This adapter is intended to cover providers such as OpenAI, Mistral, and Qwen
+when they expose an OpenAI-compatible endpoint shape.
+
+## Public API
+
+The main public entrypoints are:
+
+- `RAGPipeline`
+- `RAGPipelineConfig`, `RetrievalConfig`, `PromptConfig`
+- `IndexedParagraph`, `QueryAnalysis`, `RetrievedParagraph`
+- `RetrievalResult`, `RAGAnswerResult`
+- `GeneratedAnswer`, `AnswerGenerator`
+- `OpenAICompatibleAnswerGenerator`, `OpenAICompatibleConfig`
+- convenience re-export: `Paragraph`
+
+Detailed API notes are available in [`docs/public_api.md`](docs/public_api.md).
+
+## Examples
+
+Runnable examples are available in [`examples/`](examples/):
+
+- [`examples/basic_usage.py`](examples/basic_usage.py)
+- [`examples/custom_config.py`](examples/custom_config.py)
+- [`examples/save_and_load.py`](examples/save_and_load.py)
+- [`examples/provider_answer.py`](examples/provider_answer.py)
+
+## Persistence Notes
+
+`save(path)` produces a human-inspectable directory containing:
+
+- `config.json`
+- `label_generator.json`
+- `corpus_index.json`
+- `fit_result.json`
+
+Public guarantee:
+
+- a saved and reloaded pipeline should preserve retrieval behavior for the same
+  fitted state, question, and config
+
+## Configuration Notes
+
+- `RetrievalConfig.max_paragraphs` sets the hard retrieval limit
+- `RetrievalConfig.allow_label_free_fallback` enables deterministic concept
+  overlap fallback for label-free queries
+- `RetrievalConfig.require_full_label_coverage` suppresses partial retrieval
+  output when not all query labels can be covered
+- `PromptConfig.include_paragraph_ids` includes stable paragraph IDs in the
+  rendered prompt context
+- `PromptConfig.include_label_annotations` includes paragraph label annotations
+  in rendered prompt context
+- `PromptConfig.max_context_characters` applies a hard cap to rendered context
+  length
+
+## Development Checks
+
+```bash
+.venv/bin/ruff check . --fix
+.venv/bin/pyright
+.venv/bin/pytest
+```
+
+## Release Checks
+
+```bash
+.venv/bin/python -m build
+.venv/bin/python -m twine check dist/*
+```

labelrag-0.0.0/pyproject.toml

@@ -0,0 +1,85 @@
+[build-system]
+requires = ["hatchling>=1.27.0"]
+build-backend = "hatchling.build"
+
+[project]
+name = "labelrag"
+version = "0.0.0"
+description = "A label-driven RAG pipeline built on top of paralabelgen."
+readme = "README.md"
+license = { text = "MIT" }
+authors = [
+  { name = "huruilizhen", email = "huruilizhen@gmail.com" },
+]
+requires-python = ">=3.11"
+dependencies = [
+  "paralabelgen==0.2.0",
+]
+keywords = ["rag", "retrieval", "labels", "evaluation", "paragraphs", "llm"]
+classifiers = [
+  "Development Status :: 2 - Pre-Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Scientific/Engineering :: Artificial Intelligence",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+]
+
+[project.urls]
+Homepage = "https://github.com/HuRuilizhen/labelrag"
+Repository = "https://github.com/HuRuilizhen/labelrag"
+Issues = "https://github.com/HuRuilizhen/labelrag/issues"
+
+[project.optional-dependencies]
+dev = [
+  "build>=1.2.0",
+  "pyright>=1.1.390",
+  "pytest>=8.3.0",
+  "pytest-cov>=6.0.0",
+  "ruff>=0.11.0",
+  "twine>=6.1.0",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/labelrag"]
+
+[tool.hatch.build.targets.sdist]
+only-include = [
+  "/src/labelrag",
+  "/README.md",
+  "/LICENSE",
+  "/pyproject.toml",
+]
+
+[tool.pytest.ini_options]
+minversion = "8.0"
+testpaths = ["tests"]
+addopts = [
+  "--strict-config",
+  "--strict-markers",
+]
+
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP"]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+
+[tool.pyright]
+include = ["src", "tests", "examples"]
+pythonVersion = "3.11"
+typeCheckingMode = "strict"
+# `paralabelgen` does not currently ship type stubs, so this remains an
+# intentional deviation from the sibling `labelgen` repository.
+reportMissingTypeStubs = false
+venvPath = "."
+venv = ".venv"

labelrag-0.0.0/src/labelrag/__init__.py

@@ -0,0 +1,35 @@
+"""Public package exports for the `labelrag` package."""
+
+from labelgen import Paragraph
+
+from labelrag.config import PromptConfig, RAGPipelineConfig, RetrievalConfig
+from labelrag.generation.generator import AnswerGenerator, GeneratedAnswer
+from labelrag.generation.openai_compatible import (
+    OpenAICompatibleAnswerGenerator,
+    OpenAICompatibleConfig,
+)
+from labelrag.pipeline.rag_pipeline import RAGPipeline
+from labelrag.types import (
+    IndexedParagraph,
+    QueryAnalysis,
+    RAGAnswerResult,
+    RetrievalResult,
+    RetrievedParagraph,
+)
+
+__all__ = [
+    "AnswerGenerator",
+    "GeneratedAnswer",
+    "IndexedParagraph",
+    "OpenAICompatibleAnswerGenerator",
+    "OpenAICompatibleConfig",
+    "Paragraph",
+    "PromptConfig",
+    "QueryAnalysis",
+    "RAGAnswerResult",
+    "RAGPipeline",
+    "RAGPipelineConfig",
+    "RetrievalConfig",
+    "RetrievalResult",
+    "RetrievedParagraph",
+]

labelrag-0.0.0/src/labelrag/config.py

@@ -0,0 +1,33 @@
+"""Public configuration models for `labelrag`."""
+
+from dataclasses import dataclass, field
+
+from labelgen import LabelGeneratorConfig
+
+
+@dataclass(slots=True)
+class RetrievalConfig:
+    """Configuration for paragraph retrieval behavior."""
+
+    max_paragraphs: int = 8
+    require_full_label_coverage: bool = False
+    allow_label_free_fallback: bool = True
+
+
+@dataclass(slots=True)
+class PromptConfig:
+    """Configuration for prompt context rendering."""
+
+    include_paragraph_ids: bool = True
+    include_label_annotations: bool = False
+    max_context_characters: int | None = None
+
+
+@dataclass(slots=True)
+class RAGPipelineConfig:
+    """Top-level public configuration for `RAGPipeline`."""
+
+    labelgen: LabelGeneratorConfig = field(default_factory=LabelGeneratorConfig)
+    retrieval: RetrievalConfig = field(default_factory=RetrievalConfig)
+    prompt: PromptConfig = field(default_factory=PromptConfig)
+

labelrag-0.0.0/src/labelrag/generation/__init__.py

@@ -0,0 +1,14 @@
+"""Generation boundaries for `labelrag`."""
+
+from labelrag.generation.generator import AnswerGenerator, GeneratedAnswer
+from labelrag.generation.openai_compatible import (
+    OpenAICompatibleAnswerGenerator,
+    OpenAICompatibleConfig,
+)
+
+__all__ = [
+    "AnswerGenerator",
+    "GeneratedAnswer",
+    "OpenAICompatibleAnswerGenerator",
+    "OpenAICompatibleConfig",
+]

labelrag-0.0.0/src/labelrag/generation/generator.py

@@ -0,0 +1,21 @@
+"""Generator protocol definitions."""
+
+from dataclasses import dataclass, field
+from typing import Any, Protocol
+
+
+@dataclass(slots=True)
+class GeneratedAnswer:
+    """Model-agnostic generated answer payload."""
+
+    text: str
+    metadata: dict[str, Any] = field(default_factory=lambda: {})
+
+
+class AnswerGenerator(Protocol):
+    """Protocol for injected synchronous answer generation."""
+
+    def generate(self, question: str, context: str) -> GeneratedAnswer:
+        """Generate an answer from the provided question and context."""
+
+        ...