v0.1.0 — first public release

First public release, under MIT. On PyPI: pypi.org/project/ragsage

pip install ragsage

ragsage is a model-agnostic, tenancy-agnostic Retrieval-Augmented Generation engine. It owns
the whole RAG domain — parsing, chunking, contextualizing, embedding, hybrid retrieval,
reranking, grounded generation, and verifiable citations — behind typing.Protocol ports, so any
model or store is swapped by implementing an interface rather than by editing the engine.

The library never imports web, auth, or tenant concepts. Callers pass an opaque Scope — a
namespace plus optional metadata filters — which the engine treats as an untyped label. That one
boundary is what lets the same engine run single-tenant from a script and multi-tenant behind a
SaaS backend, unchanged.

Runs offline, out of the box

Every port ships with an in-memory fake, so the full ingest-and-query loop needs no database, no
server, and no API key:

$ ragsage ingest ./docs
  + france.txt: 2 chunks
  corpus saved to .ragsage/state.json

$ ragsage query "What is the capital of France?"
Paris is the capital of France. It sits on the Seine river. [1]

Sources:
  [1] f9d8ec95d8be4f2e (page 1)

What's in it

• 13 ports, all Protocols, conformance by shape — an adapter imports and subclasses nothing
  from ragsage: DocumentParser, PageClassifier, Chunker, Contextualizer, Embedder,
  Reranker, LLMClient, QueryRewriter, VectorStore, LexicalStore, DocumentStore,
  Cache, Tracer.
• Façades: IngestionPipeline.ingest, QueryEngine.query, Evaluator.evaluate — or
  RagSage.from_config(...) to migrate, ingest, query and purge from one config object instead
  of hand-wiring ports.
• A heuristic, model-free parser covering PDF, DOCX, PPTX, HTML, Markdown and text, with
  column-gutter reading order, modal-font heading detection, ruled and borderless tables, and a
  per-page vision fallback for pages that don't parse. Its import graph carries no torch, no
  numpy≥2, no transformers, no onnxruntime, no magika — a deliberate portability promise
  (x86-64-v1 hosts included), enforced by a test that probes the graph in a clean subprocess
  rather than by convention.
• Postgres storage: pgvector dense retrieval over an HNSW cosine index alongside a generated
  tsvector lexical column with GIN, Row-Level-Security-scoped, and a migrate() that reads the
  live column width and refuses to run onto a table of a different embedding dimension — before
  any DDL, not after the first insert fails.
• Provider adapters as core dependencies, so pip install ragsage plus two API keys is a
  working engine: VoyageEmbedder, VoyageReranker, OpenAIContextualizer,
  OpenAIQueryRewriter, OpenAILLMClient.
• A CLI: ragsage info | ingest | query | eval.
• Four runnable examples, argument-free and type-checked in CI, starting from ten lines of
  wiring against the fakes.

Known limits

Alpha, and the parser is heuristic by decision
(ADR-0001),
which buys portability at a cost in fidelity. The weak spots are written down rather than left to
be discovered:
docs/failure-modes.md
lists them symptom-first, with how to confirm each from the parser's own output and what to do
about it.

Python 3.12+.

Verifying these artifacts

Published by .github/workflows/release.yml
via PyPI Trusted Publishing — no API token exists
anywhere, and the job holding the OIDC credential runs no project code. The files attached here
are byte-identical to what PyPI serves:

sha256  3ac4b66ff890bbe6d944e1dd3b25b9a53ecdcd2aecc7c994480c83052d0fcaaa  ragsage-0.1.0-py3-none-any.whl
sha256  1be2ae805e250b9fdd138176a37a9fec37429c7ff616211f1c12a73f5221d607  ragsage-0.1.0.tar.gz

Licensed MIT.