ragxpy 0.1.0__tar.gz

ragxpy-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,70 @@
+name: Bug Report
+description: Something isn't working as expected
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: "Thanks for taking the time to report a bug. Please fill in as much detail as possible."
+
+  - type: input
+    id: version
+    attributes:
+      label: ragx version
+      placeholder: "e.g. 0.1.0 — run: pip show ragx"
+    validations:
+      required: true
+
+  - type: input
+    id: python
+    attributes:
+      label: Python version
+      placeholder: "e.g. 3.11.9 — run: python --version"
+    validations:
+      required: true
+
+  - type: input
+    id: os
+    attributes:
+      label: Operating system
+      placeholder: "e.g. macOS 15, Ubuntu 24.04, Windows 11"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: install
+    attributes:
+      label: How did you install ragx?
+      options:
+        - pip install ragx
+        - pip install -e . (editable)
+        - Other
+    validations:
+      required: true
+
+  - type: textarea
+    id: repro
+    attributes:
+      label: Minimal reproduction
+      description: The smallest snippet of code that reproduces the bug
+      render: python
+      placeholder: |
+        from ragx import RAG
+        async with RAG(llm="openai/gpt-4o-mini") as rag:
+            ...
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behaviour
+    validations:
+      required: true
+
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual behaviour
+      description: Include the full traceback if there is one
+    validations:
+      required: true

ragxpy-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,47 @@
+name: Feature Request
+description: Suggest a new capability or improvement
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: "Before opening a feature request, search existing issues and discussions to avoid duplicates."
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: What problem does this solve?
+      description: Describe the gap or pain point you are experiencing
+      placeholder: "When I try to do X, I have to work around it by Y, which is tedious because..."
+    validations:
+      required: true
+
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed solution
+      description: What API or behaviour would you like to see?
+      render: python
+      placeholder: |
+        async with RAG(chunker="contextual", ...) as rag:
+            ...
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: Other approaches you looked at and why they fell short
+    validations:
+      required: false
+
+  - type: dropdown
+    id: willing
+    attributes:
+      label: Would you be willing to implement this?
+      options:
+        - "Yes — I can open a PR"
+        - "Maybe — I could help if guided"
+        - "No — submitting for someone else to pick up"
+    validations:
+      required: true

ragxpy-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,20 @@
+## Summary
+
+<!-- One or two sentences describing what this PR does and why. Link the related issue: "Closes #123" -->
+
+Closes #
+
+## Changes
+
+<!-- Bullet list of what changed -->
+
+-
+
+## Checklist
+
+- [ ] `pytest tests/ -x -q` passes locally
+- [ ] `ruff check src/ --fix` — no remaining violations
+- [ ] `mypy src/ragx/` — no errors
+- [ ] New or changed behaviour has tests
+- [ ] `CHANGELOG.md` updated under `[Unreleased]`
+- [ ] Docstrings updated for any modified public API

ragxpy-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,61 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Cache pip
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/pip
+          key: ${{ runner.os }}-pip-${{ hashFiles('pyproject.toml') }}
+          restore-keys: ${{ runner.os }}-pip-
+
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Lint (ruff)
+        run: ruff check src/
+
+      - name: Type check (mypy)
+        run: mypy src/ragx/
+
+      - name: Test (pytest + coverage)
+        run: pytest tests/ -x -q --cov=src/ragx --cov-report=xml --cov-report=term-missing
+
+      - name: Upload coverage to Codecov
+        if: matrix.python-version == '3.11'
+        uses: codecov/codecov-action@v4
+        with:
+          file: coverage.xml
+          fail_ci_if_error: false
+
+  build:
+    runs-on: ubuntu-latest
+    needs: test
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Build wheel
+        run: pip install build && python -m build --wheel
+      - name: Check dist
+        run: pip install twine && twine check dist/*

ragxpy-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,67 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install build
+        run: pip install build
+
+      - name: Build wheel and sdist
+        run: python -m build
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish-testpypi:
+    name: Publish to TestPyPI
+    needs: build
+    runs-on: ubuntu-latest
+    if: contains(github.ref, 'dev') || contains(github.ref, 'rc')
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/p/ragx
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  publish-pypi:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    if: "!contains(github.ref, 'dev') && !contains(github.ref, 'rc')"
+    environment:
+      name: pypi
+      url: https://pypi.org/p/ragx
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - uses: pypa/gh-action-pypi-publish@release/v1

ragxpy-0.1.0/.gitignore

@@ -0,0 +1,18 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
+.env
+*.env
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+htmlcov/
+.coverage
+ragx-index/
+*.lance/
+.claude/
+ragx_config.py

ragxpy-0.1.0/.readthedocs.yml

@@ -0,0 +1,17 @@
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.11"
+
+mkdocs:
+  configuration: mkdocs.yml
+
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs
+        - dev

ragxpy-0.1.0/CHANGELOG.md

@@ -0,0 +1,72 @@
+# Changelog
+
+All notable changes to ragx will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-04-16
+
+### Added
+
+**Hybrid search — on by default**
+- `HybridSearcher` — fuses BM25 sparse search with dense vector search via Reciprocal Rank Fusion (RRF, k=60)
+- `InMemoryStore` — numpy cosine + rank-bm25, zero dependencies, for development and tests
+- `LanceDBStore` — embedded persistent store, no server required (`pip install ragx[lance]`)
+- `PgVectorStore` — PostgreSQL + pgvector + native FTS hybrid search (`pip install ragx[postgres]`)
+- `CrossEncoderReranker` — optional re-ranking step (`pip install ragx[local-emb]`)
+- `SufficiencyChecker` — cosine-based check before calling the LLM
+
+**Streaming**
+- `rag.stream_query()` — async generator yielding tokens as they arrive; works with OpenAI, Anthropic, Ollama
+- `StreamingLLMProtocol` — protocol for LLMs that support streaming; graceful fallback for custom LLMs
+
+**Agent tools**
+- `rag.search()` — public method returning raw `list[SearchResult]` for use as an agent tool
+- `ragx.agent.as_claude_tool()` — Anthropic-compatible tool schema for Claude agents
+- `ragx.agent.as_openai_tool()` — OpenAI-compatible function tool schema
+- `SearchResult` exported from `ragx` top-level
+
+**Multi-tenant isolation**
+- `ingest(tenant_id=...)` — tag documents with a tenant identifier at ingest time
+- `QueryConfig(tenant_id=..., allowed_sources=[...])` — filter results by tenant or source glob at query time
+
+**Core pipeline**
+- `RAG` async context manager — the 4-line API: `async with RAG(llm=...) as rag:`
+- `RAGConfig`, `QueryConfig`, `Answer`, `IngestResult`, `Document`, `EvalSchema` typed dataclasses
+- Incremental indexing — `ingest()` hashes each file and skips unchanged documents on re-runs
+- `force=True` flag on `ingest()` to bypass incremental check
+
+**Ingestion**
+- `AutoLoader` — dispatches by file extension (`.txt`, `.md`, `.pdf`, `.html`)
+- `TextLoader`, `MarkdownLoader` (extracts headings), `PDFLoader` (pypdf), `HTMLLoader` (bs4)
+- Graceful per-file failure — a bad PDF is captured in `IngestResult.errors`, never raises
+- `RecursiveChunker` — Chonkie-backed, 512-token default, benchmark winner (69% E2E accuracy, FloTorch Feb 2026)
+- `StructureAwareChunker` — splits at Markdown/HTML headings before recursive chunking
+- `ContextualChunker` — prepends LLM-generated context summary per chunk, bounded concurrency
+- `HierarchicalChunker` — small child chunks for retrieval, parent text stored for generation
+
+**Generation**
+- `LLMProtocol` + `resolve_llm()` — string shorthand: `"openai/gpt-4o-mini"`, `"anthropic/claude-haiku-4-5"`, `"ollama/llama3"`
+- `OpenAILLM`, `AnthropicLLM`, `OllamaLLM` — all async, lazy client init
+- `LLMCache` — in-memory cache with optional Redis backend; SHA-256 keyed
+
+**Evaluation**
+- `EvalSchema` — unified dataclass: faithfulness, answer_relevance, context_recall, context_precision, latency_ms
+- `rag.eval(dataset)` — RAGAS wrapper (`pip install ragx[eval]`)
+- `assert_eval_passes(scores, ...)` — pytest helper for CI quality gates
+- `LangfuseTracer` — production tracing via Langfuse (`pip install ragx[eval]`)
+
+**Embedding**
+- `OpenAIEmbedder` — async, batched, lazy client init
+- `SentenceTransformerEmbedder` — offline, thread-pool inference (`pip install ragx[local-emb]`)
+- `resolve_embedder()` — string shorthand: `"openai/text-embedding-3-small"`, `"local/all-MiniLM-L6-v2"`
+
+**CLI**
+- `ragxpy init` — generates `ragx_config.py` with typed defaults and inline comments
+- `ragxpy serve` — Starlette HTTP API on `localhost:8000` with `/health`, `/query`, `/ingest` (`pip install ragx[serve]`)
+
+[Unreleased]: https://github.com/laxmikanta415/ragx/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/laxmikanta415/ragx/releases/tag/v0.1.0

ragxpy-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,26 @@
+# Code of Conduct
+
+## Our commitment
+
+ragx is an open, welcoming project. Everyone who participates — through issues, PRs, discussions, or any other channel — is expected to treat others with respect and good faith.
+
+## Expected behaviour
+
+- Be constructive and specific in feedback
+- Assume good intent; ask for clarification before criticising
+- Accept that maintainers have final say on design decisions
+- Keep discussions focused on the technical matter at hand
+
+## Unacceptable behaviour
+
+- Personal attacks, insults, or harassment of any kind
+- Posting others' private information without permission
+- Sustained disruption of discussions
+
+## Reporting
+
+If you experience or witness behaviour that violates this policy, email **lax@insummary.com** with subject `[CoC] ragx`. All reports are handled confidentially. We aim to respond within 72 hours.
+
+## Enforcement
+
+Maintainers may remove comments, close issues, or ban contributors who repeatedly or severely violate these expectations.

ragxpy-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,75 @@
+# Contributing to ragx
+
+Thank you for your interest in contributing! This guide covers everything you need to get started.
+
+## Development setup
+
+```bash
+git clone https://github.com/laxmikanta415/ragx.git
+cd ragx
+python -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
+pip install -e ".[dev]"
+```
+
+Verify your setup:
+
+```bash
+python -m pytest tests/ -x -q      # all tests pass
+python -m ruff check src/           # no lint errors
+python -m mypy src/ragx/            # no type errors
+```
+
+## Branch naming
+
+| Type | Prefix | Example |
+|------|--------|---------|
+| New feature | `feature/` | `feature/streaming-responses` |
+| Bug fix | `fix/` | `fix/lance-fts-index` |
+| Documentation | `docs/` | `docs/evaluation-guide` |
+| Chore / deps | `chore/` | `chore/bump-chonkie` |
+
+All PRs target `main`.
+
+## Commit style
+
+Use the imperative mood. Reference the issue number if one exists.
+
+```
+add HyPE pre-indexing to HybridSearcher (#42)
+fix incremental ingest skipping on Windows paths (#38)
+docs: add PostgreSQL production guide
+```
+
+## Before submitting a PR
+
+- [ ] `pytest tests/ -x -q` passes
+- [ ] `ruff check src/ --fix` — no remaining violations
+- [ ] `mypy src/ragx/` — no errors
+- [ ] New behaviour has tests
+- [ ] `CHANGELOG.md` has an entry under `[Unreleased]`
+- [ ] PR description links the related issue
+
+## Adding a new store backend
+
+1. Subclass `VectorStore` in `src/ragx/indexing/base.py`
+2. Implement all five abstract methods: `upsert`, `dense_search`, `sparse_search`, `delete`, `get_indexed_sources`
+3. Guard the optional import with `try/except ImportError`
+4. Add a string shorthand to `_resolve_store()` in `src/ragx/pipeline.py`
+5. Add tests in `tests/test_indexing.py`
+6. Document the new store in `docs/stores.md`
+
+## Running only specific tests
+
+```bash
+pytest tests/test_pipeline.py -x -q       # pipeline only
+pytest tests/ -k "test_rag_query" -v      # by name pattern
+pytest tests/ --co -q                     # list collected tests
+```
+
+## Reporting bugs
+
+Please open an issue using the [bug report template](https://github.com/laxmikanta415/ragx/issues/new?template=bug_report.yml).
+
+## Questions
+
+Open a [GitHub Discussion](https://github.com/laxmikanta415/ragx/discussions) in the Q&A category.

ragxpy-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Laxmikanta (lax@insummary.com)
+
+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.