SpinRAG v0.1.0 - first official release

SpinRAG v0.1.0 - first official release

A typed, self-evolving knowledge graph for RAG over damaged business records - fiscal ledgers, OCR dumps, half-finished wiki entries, ticket exports. SpinRAG treats broken fragments as the input signal and uses the LLM to repair the graph into a self-consistent retrieval index.

This is the first release marketed as production-ready (no alpha, no beta). It ships with a typed, evolving knowledge-graph RAG that runs against OpenRouter (hosted) or a llama.cpp server (local), both via the official OpenAI Python SDK.

Highlights

• OpenAI SDK throughout. LangChain and Ollama are gone; SpinRAG now speaks the OpenAI HTTP protocol directly.
• Two first-class backends, one argument to switch.
  • backend="openrouter" (default) - hosted model catalog; reads OPENROUTER_API_KEY from the env.
  • backend="llamacpp" - self-hosted llama-server; no API key required.
• Document restoration is the explicit design goal. Every LLM prompt is wrapped in a guardrail that tells the model to preserve every noun, number, and relationship from the source fragments. Pure TOP queries are returned verbatim - zero hallucination on that path.
• Bounded hallucination contract per query spin: TOP = verbatim (none), LEFT / RIGHT / BOTTOM = guardrailed synthesis. The user opts in to invention.
• Visible provenance: every generated document carries an epoch_history and graph edges back to the catalyst + base that produced it.
• Dash demo with backend selector, base-URL field, and API-key input.

Install

git clone https://github.com/iblameandrew/spin-rag.git
cd spin-rag
pip install -r requirements.txt
pip install -e .
cp .env.example .env       # set OPENROUTER_API_KEY if using OpenRouter
python demo.py             # http://127.0.0.1:8050

For the self-hosted llama.cpp path, start your server with the embedding flag enabled:

./llama-server -m model.gguf --port 8080 --embedding

then construct SpinRAG with backend="llamacpp", base_url="http://localhost:8080/v1".

Worked example (now business-fiscal)

The repository ships with demo-data.txt containing a realistic fiscal ledger - invoices, expenses, revenues, payroll, plus deliberately damaged rows (Acme Corp. -, Consulting, Pied Piper, Vendor: Initech | Period: 2026 | Type: revenue). SpinRAG's restoration loop turns those damaged rows into complete entries by fusing each with its metrically closest intact neighbour across evolution epochs.

Bug fix in this release

• _log() was being called before verbose_log was initialised; re-ordered the SpinRAG.__init__ body so the first log line always has a target.

Notes

• v0.1.0a1 remains in the README changelog as superseded history.
• The README is now positioning-neutral and enterprise-readable; the cover image, novelty comparison, hallucination contract and detailed changelog remain.

SpinRAG v0.1.0a1 - first public alpha

SpinRAG v0.1.0a1 - first public alpha

The first publicly tagged release of SpinRAG. This alpha is deliberately tuned for document restoration: faithful reconstruction of damaged, partial, or fragmented knowledge bases. Hallucination risk on non-TOP queries is explicitly accepted in exchange for high fidelity on intact inputs.

Restoration-first design

• Every LLM prompt used during evolution is wrapped in a restoration guardrail telling the model to preserve every noun, number, and relationship from the source fragments and mark unknowns with [unknown] instead of guessing.
• Pure TOP-spin queries are returned verbatim from the closest matching document, with no LLM rewriting.
• Only LEFT / RIGHT / BOTTOM queries pass through generative rules. These are the documented hallucination-risk paths.

What landed in this release

Packaging fixes (previously the package would not install):

• setup.py now uses find_packages() and actually installs the spin_rag package.
• spin_rag/__init__.py re-exports SpinRAG, SpinType, Document and exposes __version__.
• requirements.txt adds the missing langchain-ollama dependency.

Core bug fixes:

• Separate embedding model from LLM model. Chat-tuned models reject /api/embeddings and previously crashed initialization; default is now nomic-embed-text.
• Cosine similarity is zero-norm safe at all three call sites.
• Embeddings are cached per text; _find_closest_doc no longer recomputes the entire corpus on every catalyst interaction.
• _get_spin parses LLM replies with a word-boundary regex (no more misclassifications on reasoning prefixes).
• LLM outputs are stripped of whitespace, surrounding quotes, and stray code fences before becoming new documents.
• LLMChain (deprecated) replaced with direct llm.invoke.
• Logging is resilient to Windows cp1252 consoles that cannot encode emoji.

Demo (demo.py):

• Initialize button re-enables when work finishes; live status indicator.
• Separate selectors for LLM and embedding model.
• Thread locks protect the shared RAG instance and log buffer.
• Chat input clears after send; Enter submits.
• Bounded log buffer keeps the UI responsive on long runs.

README:

• Correct import path (from spin_rag import SpinRAG) and constructor signature (content=, embed_model=).
• New section documenting the restoration / hallucination trade-off and known alpha limitations.

Install

git clone https://github.com/iblameandrew/spin-rag.git
cd spin-rag
pip install -r requirements.txt
pip install -e .
ollama pull qwen3:4b-instruct-2507
ollama pull nomic-embed-text

Known alpha limitations

• No persistence; the graph lives in memory.
• No batching; large corpora are slow.
• No automated test suite.
• Restoration guardrail reduces but does not eliminate fabrication. Treat LEFT / RIGHT / BOTTOM query outputs as drafts.