tensor-truth 0.1.8

Local RAG pipeline for fixing LLM hallucinations using high-precision documentation indexing.

A local RAG pipeline for reducing hallucinations in LLMs by indexing technical documentation and research papers. Built for personal use on local hardware, shared here in case others find it useful. Web UI is built with Streamlit, with high level of configurability for the pipeline.

What It Does

Indexes technical documentation and research papers into vector databases, then uses retrieval-augmented generation to ground LLM responses in source material. Uses hierarchical node parsing with auto-merging retrieval and cross-encoder reranking to balance accuracy and context window constraints.

Quick Start

Install the tool via PyPI. But before you do, I advise you prep the environment because of large volume of dependencies (use Python 3.11+):

python -m venv venv
source venv/bin/activate  # or .\venv\Scripts\activate(.ps1) on Windows CMD/PowerShell

Or via conda:

conda create -n tensor-truth python=3.11
conda activate tensor-truth

If using CUDA, make sure to first install the appropriate PyTorch version from pytorch.org. I used torch 2.9 and CUDA 12.8 in environments with CUDA.

If not, just install tensor-truth via pip, which includes CPU-only PyTorch.

pip install tensor-truth

Make sure ollama is installed and set up. Start the server:

ollama serve

Run the app:

tensor-truth

On first launch, pre-built indexes will auto-download from Google Drive (takes a few minutes). Also a small qwen2.5:0.5b will be pulled automatically for assigning automatic titles to chats.

Docker Deployment

For easier deployment without managing virtual environments or CUDA installations, a pre-built Docker image is available. This approach is useful if you want to avoid setting up PyTorch with CUDA manually, though you still need a machine with NVIDIA GPU and drivers installed.

Pull and run from Docker Hub:

docker run -d \
  --name tensor-truth \
  --gpus all \
  -p 8501:8501 \
  -v ~/.tensortruth:/root/.tensortruth \
  -e OLLAMA_HOST=http://host.docker.internal:11434 \
  ljubobratovicrelja/tensor-truth:latest

Access the app at http://localhost:8501. The -v flag mounts your local data directory for persistence across container restarts. Change the port mapping with -p HOST_PORT:8501 if needed (e.g., -p 8080:8501 to serve on port 8080).

If Ollama runs on a different host or port, override the OLLAMA_HOST environment variable:

-e OLLAMA_HOST=http://192.168.1.50:11434

Build locally (optional):

docker build -t tensor-truth .
docker run -d --name tensor-truth --gpus all -p 8501:8501 -v ~/.tensortruth:/root/.tensortruth tensor-truth

Data Storage

All user data (chat history, presets, indexes) is stored in ~/.tensortruth on macOS/Linux or %USERPROFILE%\.tensortruth on Windows. This keeps your working directory clean while maintaining persistent state across sessions.

Pre-built indexes download automatically to this directory on startup. If Google Drive rate limits prevent auto-download, manually fetch indexes.tar and extract to ~/.tensortruth/indexes.

For index contents, see config/api.json and config/papers.json. These are curated lists of useful libraries and research papers. Fork and customize as needed.

Requirements

Tested on:

• MacBook M1 Max (32GB unified memory)
• Desktop with RTX 3090 Ti (24GB VRAM)

Minimum recommended: 16GB RAM, Python 3.11+. GPU optional but significantly faster.

Recommended Models

Any Ollama model works, but these are tested:

General Purpose:

ollama pull deepseek-r1:8b     # Balanced
ollama pull deepseek-r1:14b    # High quality
ollama pull deepseek-r1:32b    # Best quality (24GB+)

Code/Technical Docs:

ollama pull deepseek-coder-v2:16b
ollama pull deepseek-coder-v2

DeepSeek-R1 models include chain-of-thought reasoning. Coder-V2 variants are optimized for technical content and work particularly well with programming documentation.

Building Your Own Indexes

Pre-built indexes cover common libraries, but you can create custom knowledge bases:

Scrape Documentation:

tensor-truth-docs --list          # Show available libraries
tensor-truth-docs pytorch         # Scrape PyTorch docs

Fetch Research Papers:

tensor-truth-papers --config ./config/papers.json --category your_category --ids 2301.12345
tensor-truth-papers --rebuild your_category

Build Vector Index:

tensor-truth-build --modules module_name

Configuration

This system is configured for personal research workflows with these assumptions:

• ChromaDB for vector storage (persistent, single-process)
• HuggingFace sentence-transformers for embeddings
• BGE cross-encoder models for reranking
• Ollama for local LLM inference
• All processing runs locally

If you need different chunking strategies or retrieval parameters, you'll need to modify the source files. The current setup is tuned for technical documentation and research papers.

License

MIT License - see LICENSE for details.

Built for personal use but released publicly. Provided as-is with no warranty.

Disclaimer & Content Ownership

1. Software License: The source code of tensor-truth is licensed under the MIT License. This covers the logic, UI, and retrieval pipelines created for this project.

2. Third-Party Content: This tool is designed to fetch and index publicly available technical documentation, research papers (via ArXiv), and educational textbooks.

• I do not own the rights to the indexed content. All PDF files, textbooks, and research papers fetched by this tool remain the intellectual property of their respective authors and publishers.
• Source Links: The configuration files (config/papers.json, etc.) point exclusively to official sources, author-hosted pages, or open-access repositories (like ArXiv).
• Usage: This tool is intended for personal, non-commercial research and educational use.

3. Takedown Request: If you are an author or copyright holder of any material referenced in the default configurations or included in the pre-built indexes and wish for it to be removed, please open an issue or contact me at [e-mail], and the specific references/data will be removed immediately.