nexrag 0.1.0__tar.gz

nexrag-0.1.0/PKG-INFO

@@ -0,0 +1,186 @@
+Metadata-Version: 2.3
+Name: nexrag
+Version: 0.1.0
+Summary: Framework-agnostic RAG pipeline SDK. Plug in any component, swap any stage, configure everything in YAML
+Keywords: rag,retrieval-augmented-generation,llm,vector-database,embeddings,ai,nlp,pipeline,sdk
+Author: KevinRawal
+Author-email: KevinRawal <kevinrawal30@gmail.com>
+License: TBD
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: nexrag[all-providers] ; extra == 'all'
+Requires-Dist: nexrag[all-loaders] ; extra == 'all'
+Requires-Dist: nexrag[pdf] ; extra == 'all-loaders'
+Requires-Dist: nexrag[word] ; extra == 'all-loaders'
+Requires-Dist: nexrag[excel] ; extra == 'all-loaders'
+Requires-Dist: nexrag[html] ; extra == 'all-loaders'
+Requires-Dist: nexrag[openai] ; extra == 'all-providers'
+Requires-Dist: nexrag[anthropic] ; extra == 'all-providers'
+Requires-Dist: nexrag[ollama] ; extra == 'all-providers'
+Requires-Dist: nexrag[chromadb] ; extra == 'all-providers'
+Requires-Dist: nexrag[huggingface] ; extra == 'all-providers'
+Requires-Dist: anthropic>=0.20 ; extra == 'anthropic'
+Requires-Dist: chromadb>=0.5 ; extra == 'chromadb'
+Requires-Dist: pytest>=8.0 ; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0 ; extra == 'dev'
+Requires-Dist: ruff>=0.4 ; extra == 'dev'
+Requires-Dist: mypy>=1.10 ; extra == 'dev'
+Requires-Dist: pre-commit>=3.7 ; extra == 'dev'
+Requires-Dist: types-pyyaml ; extra == 'dev'
+Requires-Dist: openpyxl>=3.1 ; extra == 'excel'
+Requires-Dist: beautifulsoup4>=4.12 ; extra == 'html'
+Requires-Dist: lxml>=5.0 ; extra == 'html'
+Requires-Dist: sentence-transformers>=2.0 ; extra == 'huggingface'
+Requires-Dist: ollama>=0.1 ; extra == 'ollama'
+Requires-Dist: openai>=1.0 ; extra == 'openai'
+Requires-Dist: pypdf>=4.0 ; extra == 'pdf'
+Requires-Dist: python-docx>=1.0 ; extra == 'word'
+Requires-Python: >=3.12
+Project-URL: Homepage, https://github.com/kevinrawal/nexrag
+Project-URL: Repository, https://github.com/kevinrawal/nexrag
+Project-URL: Issues, https://github.com/kevinrawal/nexrag/issues
+Project-URL: Changelog, https://github.com/kevinrawal/nexrag/blob/main/CHANGELOG.md
+Provides-Extra: all
+Provides-Extra: all-loaders
+Provides-Extra: all-providers
+Provides-Extra: anthropic
+Provides-Extra: chromadb
+Provides-Extra: dev
+Provides-Extra: excel
+Provides-Extra: html
+Provides-Extra: huggingface
+Provides-Extra: ollama
+Provides-Extra: openai
+Provides-Extra: pdf
+Provides-Extra: word
+Description-Content-Type: text/markdown
+
+# NexRAG
+
+> Framework-agnostic RAG pipeline SDK. Plug in any component, swap any stage, configure everything in YAML.
+
+[![PyPI version](https://img.shields.io/pypi/v/nexrag.svg)](https://pypi.org/project/nexrag/)
+[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
+[![License](https://img.shields.io/badge/license-TBD-lightgrey.svg)]()
+
+---
+
+## What is NexRAG?
+
+NexRAG is a production-grade RAG (Retrieval-Augmented Generation) pipeline SDK for Python.
+
+**NexRAG owns the pipeline shape. You own the components.**
+
+Every stage — loading, chunking, embedding, retrieval, generation — is a clean interface. NexRAG ships default implementations for each. You can swap any of them by implementing the interface and declaring it in YAML. No framework lock-in. No magic. No hidden behavior.
+
+---
+
+## Quickstart
+
+> **Note:** NexRAG v1.0 is under active development. This section will be updated on first release.
+
+```python
+from nexrag import NexRAG
+
+pipeline = NexRAG.from_config("nexrag.yaml")
+
+# Ingest documents
+pipeline.ingest("docs/contracts/")
+
+# Query
+result = pipeline.query("What are the termination clauses?")
+print(result.answer)
+print(result.source_chunks)
+```
+
+```yaml
+# nexrag.yaml
+nexrag:
+  version: "1.0"
+
+ingestion:
+  chunker:
+    strategy: recursive
+    chunk_size: 512
+  embedder:
+    provider: openai
+    model: text-embedding-3-small
+  vector_db:
+    provider: chroma
+    default_collection: contracts
+
+query:
+  llm:
+    provider: openai
+    model: gpt-4o
+```
+
+---
+
+## Installation
+
+```bash
+# Core only
+pip install nexrag
+
+# With OpenAI support
+pip install "nexrag[openai]"
+
+# With everything
+pip install "nexrag[all]"
+```
+
+---
+
+## Design Principles
+
+| Principle | What it means |
+|---|---|
+| Interface-first | Every stage is a contract. Implementation is secondary. |
+| Config-driven | YAML configures the pipeline. Code defines the logic. |
+| Zero lock-in | Core has no dependency on LangChain, LlamaIndex, or any AI SDK. |
+| Explicit over implicit | No hidden defaults. Every behavior is declared or documented. |
+| Extensible by design | New components plug in without touching core. |
+
+---
+
+## Architecture
+
+NexRAG has two independent pipelines:
+
+```
+INGESTION  →  Loader → Sanitizer → Chunker → Embedder → VectorDB
+QUERY      →  Embedder → Retriever → PromptBuilder → LLM → PipelineResult
+```
+
+See [Architecture Documentation](docs/) for full pipeline diagrams.
+
+---
+
+## Supported Providers (V1)
+
+| Category | Providers |
+|---|---|
+| Embedders | OpenAI, HuggingFace, Ollama |
+| Vector DBs | ChromaDB (local + remote) |
+| LLMs | OpenAI, Anthropic, Ollama |
+| Loaders | PDF, TXT/MD, Word, Excel, JSON, HTML, Code |
+
+---
+
+## Contributing
+
+NexRAG is in early development. Contribution guidelines will be published with v1.0.
+
+---
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md).

nexrag-0.1.0/README.md

@@ -0,0 +1,122 @@
+# NexRAG
+
+> Framework-agnostic RAG pipeline SDK. Plug in any component, swap any stage, configure everything in YAML.
+
+[![PyPI version](https://img.shields.io/pypi/v/nexrag.svg)](https://pypi.org/project/nexrag/)
+[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
+[![License](https://img.shields.io/badge/license-TBD-lightgrey.svg)]()
+
+---
+
+## What is NexRAG?
+
+NexRAG is a production-grade RAG (Retrieval-Augmented Generation) pipeline SDK for Python.
+
+**NexRAG owns the pipeline shape. You own the components.**
+
+Every stage — loading, chunking, embedding, retrieval, generation — is a clean interface. NexRAG ships default implementations for each. You can swap any of them by implementing the interface and declaring it in YAML. No framework lock-in. No magic. No hidden behavior.
+
+---
+
+## Quickstart
+
+> **Note:** NexRAG v1.0 is under active development. This section will be updated on first release.
+
+```python
+from nexrag import NexRAG
+
+pipeline = NexRAG.from_config("nexrag.yaml")
+
+# Ingest documents
+pipeline.ingest("docs/contracts/")
+
+# Query
+result = pipeline.query("What are the termination clauses?")
+print(result.answer)
+print(result.source_chunks)
+```
+
+```yaml
+# nexrag.yaml
+nexrag:
+  version: "1.0"
+
+ingestion:
+  chunker:
+    strategy: recursive
+    chunk_size: 512
+  embedder:
+    provider: openai
+    model: text-embedding-3-small
+  vector_db:
+    provider: chroma
+    default_collection: contracts
+
+query:
+  llm:
+    provider: openai
+    model: gpt-4o
+```
+
+---
+
+## Installation
+
+```bash
+# Core only
+pip install nexrag
+
+# With OpenAI support
+pip install "nexrag[openai]"
+
+# With everything
+pip install "nexrag[all]"
+```
+
+---
+
+## Design Principles
+
+| Principle | What it means |
+|---|---|
+| Interface-first | Every stage is a contract. Implementation is secondary. |
+| Config-driven | YAML configures the pipeline. Code defines the logic. |
+| Zero lock-in | Core has no dependency on LangChain, LlamaIndex, or any AI SDK. |
+| Explicit over implicit | No hidden defaults. Every behavior is declared or documented. |
+| Extensible by design | New components plug in without touching core. |
+
+---
+
+## Architecture
+
+NexRAG has two independent pipelines:
+
+```
+INGESTION  →  Loader → Sanitizer → Chunker → Embedder → VectorDB
+QUERY      →  Embedder → Retriever → PromptBuilder → LLM → PipelineResult
+```
+
+See [Architecture Documentation](docs/) for full pipeline diagrams.
+
+---
+
+## Supported Providers (V1)
+
+| Category | Providers |
+|---|---|
+| Embedders | OpenAI, HuggingFace, Ollama |
+| Vector DBs | ChromaDB (local + remote) |
+| LLMs | OpenAI, Anthropic, Ollama |
+| Loaders | PDF, TXT/MD, Word, Excel, JSON, HTML, Code |
+
+---
+
+## Contributing
+
+NexRAG is in early development. Contribution guidelines will be published with v1.0.
+
+---
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md).

nexrag-0.1.0/pyproject.toml

@@ -0,0 +1,161 @@
+[build-system]
+requires = ["uv_build>=0.11.16,<0.12.0"]
+build-backend = "uv_build"
+
+[project]
+name = "nexrag"
+version = "0.1.0"
+description = "Framework-agnostic RAG pipeline SDK. Plug in any component, swap any stage, configure everything in YAML"
+readme = "README.md"
+license = { text = "TBD" }
+authors = [
+    { name = "KevinRawal", email = "kevinrawal30@gmail.com" }
+]
+requires-python = ">=3.12"
+keywords = [
+    "rag",
+    "retrieval-augmented-generation",
+    "llm",
+    "vector-database",
+    "embeddings",
+    "ai",
+    "nlp",
+    "pipeline",
+    "sdk",
+]
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+
+# Keep this minimal. Only what the pipeline skeleton needs.
+dependencies = [
+    "pydantic>=2.0",   # config schema validation
+    "pyyaml>=6.0",     # YAML config loading
+]
+
+[project.optional-dependencies]
+
+# Provider extras — install only what you use
+openai = [
+    "openai>=1.0",
+]
+anthropic = [
+    "anthropic>=0.20",
+]
+ollama = [
+    "ollama>=0.1",
+]
+chromadb = [
+    "chromadb>=0.5",
+]
+huggingface = [
+    "sentence-transformers>=2.0",
+]
+
+# Document loaders
+pdf = [
+    "pypdf>=4.0",
+]
+word = [
+    "python-docx>=1.0",
+]
+excel = [
+    "openpyxl>=3.1",
+]
+html = [
+    "beautifulsoup4>=4.12",
+    "lxml>=5.0",
+]
+
+# Convenience bundles
+all-providers = [
+    "nexrag[openai]",
+    "nexrag[anthropic]",
+    "nexrag[ollama]",
+    "nexrag[chromadb]",
+    "nexrag[huggingface]",
+]
+all-loaders = [
+    "nexrag[pdf]",
+    "nexrag[word]",
+    "nexrag[excel]",
+    "nexrag[html]",
+]
+all = [
+    "nexrag[all-providers]",
+    "nexrag[all-loaders]",
+]
+
+# Dev dependencies
+dev = [
+    "pytest>=8.0",
+    "pytest-cov>=5.0",
+    "ruff>=0.4",        # linter + formatter
+    "mypy>=1.10",       # type checker
+    "pre-commit>=3.7",
+    "types-pyyaml",
+]
+
+[project.urls]
+Homepage = "https://github.com/kevinrawal/nexrag"
+Repository = "https://github.com/kevinrawal/nexrag"
+Issues = "https://github.com/kevinrawal/nexrag/issues"
+Changelog = "https://github.com/kevinrawal/nexrag/blob/main/CHANGELOG.md"
+
+# Ruff (linter + formatter)
+
+[tool.ruff]
+target-version = "py312"
+line-length = 100
+src = ["src"]
+
+[tool.ruff.lint]
+select = [
+    "E",   # pycodestyle errors
+    "W",   # pycodestyle warnings
+    "F",   # pyflakes
+    "I",   # isort
+    "B",   # flake8-bugbear
+    "UP",  # pyupgrade
+]
+ignore = ["E501"]  # line length handled by formatter
+
+[tool.ruff.lint.isort]
+known-first-party = ["nexrag"]
+
+# Mypy
+
+[tool.mypy]
+python_version = "3.12"
+strict = true
+warn_return_any = true
+warn_unused_configs = true
+mypy_path = "src"
+
+# Pytest
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-v --tb=short"
+markers = [
+    "integration: marks tests that require live services (deselect with '-m not integration')",
+    "unit: marks fast, isolated unit tests",
+]
+
+[tool.coverage.run]
+source = ["src/nexrag"]
+omit = ["*/tests/*"]
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "def __repr__",
+    "raise NotImplementedError",
+    "if TYPE_CHECKING:",
+]

nexrag-0.1.0/src/nexrag/__init__.py

@@ -0,0 +1,38 @@
+"""
+NexRAG — Framework-agnostic RAG pipeline SDK.
+
+Public API surface. Import from here, not from internal modules.
+
+    from nexrag import NexRAG, PipelineResult
+    from nexrag.exceptions import NexRAGError
+
+Everything under nexrag.core, nexrag.adapters, nexrag.loaders, etc.
+is internal. Internal APIs may change between minor versions.
+The public surface below is stable across minor versions.
+"""
+
+from nexrag.exceptions import NexRAGError
+
+__version__ = "0.1.0"
+__all__ = [
+    "NexRAG",
+    "PipelineResult",
+    "NexRAGError",
+    "__version__",
+]
+
+
+class NexRAG:
+    """Placeholder — real implementation comes in Phase 3."""
+
+    def __init__(self) -> None:
+        raise NotImplementedError(
+            "NexRAG entrypoint is not yet implemented. "
+            "Core interfaces and config system are next."
+        )
+
+
+class PipelineResult:
+    """Placeholder — real implementation comes in Phase 0 data models."""
+    def __init__(self) -> None:
+        raise NotImplementedError("PipelineResult is not yet implemented.")

nexrag-0.1.0/src/nexrag/exceptions.py

@@ -0,0 +1,140 @@
+"""
+NexRAG exception hierarchy.
+
+Every exception carries: stage name, component name, pipeline_id, and the
+original exception. No generic "something went wrong" — every failure is
+traceable to an exact stage and component.
+"""
+
+from __future__ import annotations
+
+
+class NexRAGError(Exception):
+    """Base exception for all NexRAG errors."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        stage: str | None = None,
+        component: str | None = None,
+        pipeline_id: str | None = None,
+        cause: BaseException | None = None,
+    ) -> None:
+        self.stage = stage
+        self.component = component
+        self.pipeline_id = pipeline_id
+        self.cause = cause
+        super().__init__(self._format(message))
+
+    def _format(self, message: str) -> str:
+        parts = [message]
+        if self.stage:
+            parts.append(f"stage={self.stage}")
+        if self.component:
+            parts.append(f"component={self.component}")
+        if self.pipeline_id:
+            parts.append(f"pipeline_id={self.pipeline_id}")
+        if self.cause:
+            parts.append(f"cause={type(self.cause).__name__}: {self.cause}")
+        return " | ".join(parts)
+
+
+# Configuration
+
+class ConfigError(NexRAGError):
+    """Bad or missing nexrag.yaml values."""
+
+
+class ClassResolutionError(ConfigError):
+    """Dotted class path not found, not importable, or wrong interface."""
+
+
+# Ingestion stages
+
+class LoaderError(NexRAGError):
+    """Failed to read or parse a source file."""
+
+
+class SanitizerError(NexRAGError):
+    """User-provided sanitizer raised an exception."""
+
+
+class ChunkError(NexRAGError):
+    """Chunking failed — empty output, invalid config, or runtime error."""
+
+
+class EmbedderError(NexRAGError):
+    """Embedding API failed or returned an unexpected shape."""
+
+
+class EmbedderMismatchError(EmbedderError):
+    """
+    Embedding model changed since the collection was created.
+
+    Vectors produced by different models are incompatible.
+    Resolution: run with --rebuild to wipe and re-ingest the collection.
+    """
+
+    def __init__(
+        self,
+        stored_model: str,
+        configured_model: str,
+        collection: str,
+        **kwargs: object,
+    ) -> None:
+        self.stored_model = stored_model
+        self.configured_model = configured_model
+        self.collection = collection
+        message = (
+            f"Embedding model mismatch in collection '{collection}'. "
+            f"Stored: '{stored_model}', configured: '{configured_model}'. "
+            f"Vectors are incompatible. Run: nexrag rebuild --config nexrag.yaml"
+        )
+        super().__init__(message, **kwargs)  # type: ignore[arg-type]
+
+
+class VectorDBError(NexRAGError):
+    """Vector database operation failed."""
+
+
+class VectorDBConnectionError(VectorDBError):
+    """Could not connect to the vector database."""
+
+
+class VectorDBUpsertError(VectorDBError):
+    """Failed to write chunks to the vector database."""
+
+
+# Query stages
+
+class RetrieverError(NexRAGError):
+    """Retrieval failed or returned no results."""
+
+
+class PromptError(NexRAGError):
+    """Prompt template rendering failed."""
+
+
+class LLMError(NexRAGError):
+    """LLM API call failed."""
+
+
+class LLMTimeoutError(LLMError):
+    """LLM call exceeded the configured timeout."""
+
+
+class LLMRateLimitError(LLMError):
+    """LLM provider rate limit hit."""
+
+
+# Pipeline orchestration
+
+class PipelineError(NexRAGError):
+    """
+    Orchestration-level error.
+
+    Wraps a stage-level exception with pipeline context.
+    Inspect .cause for the original stage error.
+    """
+