Vector Store

A local RAG (Retrieval-Augmented Generation) agent with a web UI. Point it at a folder of documents, ask questions in plain English, and get answers grounded in your content — all running on your machine with no external API calls.

Built on llm + sqlite-utils. Supports two backends:

- Ollama — runs models locally via Ollama - LM Studio — runs models locally via LM Studio

---

How it works

1. Ingest — ingest.py crawls a directory of documents, splits them into chunks, embeds each chunk, and stores the vectors in a local SQLite database. 2. Query — agent.py (or the web UI) takes your question, finds the most relevant chunks via similarity search, and passes them as context to a local LLM to generate an answer. 3. Web UI — server.py runs a Flask web server that wraps the same query and ingest logic behind a browser-based interface on http://localhost:8080.

---

Prerequisites

- Python 3.10+ - One of the following model backends running locally:

Ollama

Install Ollama, then pull the required models:

ollama pull nomic-embed-text   # embedding model
ollama pull llama3.2           # generation model (or any other)

Set BACKEND to "ollama" in source/config.json.

LM Studio

Install LM Studio, load your models, and enable the local server (default: http://localhost:1234). You need one model for embeddings and one for generation — nomic-embed-text-v1.5 and any chat model work well.

Set BACKEND to "lmstudio" in source/config.json and update LMSTUDIO_EMBEDDING_MODEL and LMSTUDIO_LLM_MODEL to match what you have loaded.

---

Installation

The project ships with an installer that handles everything — including downloading uv if you don't have it.

bash install.sh

That will: 1. Install uv if it isn't already on your PATH 2. Create a .venv virtual environment inside this directory 3. Install all Python dependencies into it

Once it finishes, activate the environment:

source .venv/bin/activate

Manual install (without the script)

pip install uv                          # or: brew install uv
uv venv .venv
source .venv/bin/activate
uv pip install -r source/requirements.txt

---

Usage

Web UI (recommended)

source .venv/bin/activate
cd source
python ingest.py   # index your documents first
python server.py   # starts at http://localhost:8080

Open http://localhost:8080 in your browser. The sidebar shows your active backend and model configuration. Type a question and press Ask or hit Enter.

Command-line agent

source .venv/bin/activate
cd source
python ingest.py   # index your documents first
python agent.py    # interactive prompt in the terminal

RAG Agent ready
  Model:      gemma-4-26b-a4b (LM Studio)
  Embeddings: nomic-embed-text-v1.5 (LM Studio)
  Collection: documents

You: What are the key findings in the report?

Thinking...

Agent: Based on the provided documents, the key findings are...

You: quit
Goodbye.

Type quit, exit, or q to stop.

Adding documents

Drop files into source/input/ then run ingest.py:

mkdir -p source/input
cp path/to/your/docs/* source/input/
cd source && python ingest.py

Supported formats: .txt, .md, .py, .json, .csv, .html, and any other UTF-8 text file. Binary files are skipped automatically.

Re-indexing

If you change CHUNK_SIZE, switch backends, or add/remove documents, re-index from scratch:

cd source
python reindex.py

---

Configuration

All settings live in source/config.json. Set BACKEND to "ollama" or "lmstudio", then fill in the matching model names.

Ollama settings

| Key | Default | Description | |-----|---------|-------------| | BACKEND | "ollama" | Set to "ollama" to use Ollama | | BASE_URL | "http://127.0.0.1:11434" | Ollama server address | | EMBEDDING_MODEL | "nomic-embed-text" | Ollama embedding model (must be pulled) | | LLM_MODEL | "llama3.2" | Ollama generation model (must be pulled) |

LM Studio settings

| Key | Default | Description | |-----|---------|-------------| | BACKEND | "ollama" | Set to "lmstudio" to use LM Studio | | LMSTUDIO_BASE_URL | "http://localhost:1234/v1" | LM Studio server address | | LMSTUDIO_EMBEDDING_MODEL | "nomic-embed-text-v1.5" | Embedding model loaded in LM Studio | | LMSTUDIO_LLM_MODEL | "local-model" | Generation model loaded in LM Studio |

Shared settings

| Key | Default | Description | |-----|---------|-------------| | SOURCE_FOLDER | "input" | Directory to crawl for documents (relative to source/) | | COLLECTION_NAME | "documents" | Name of the embedding collection in SQLite | | DB_PATH | "./cache/embeddings.db" | Path to the SQLite database (relative to source/) | | CHUNK_SIZE | 4000 | Characters per chunk | | CHUNK_OVERLAP | 400 | Overlap between consecutive chunks | | TOP_K | 5 | Number of chunks retrieved per query |

---

Project structure

vector-store/
├── install.sh              # uv-based installer
├── source/
│   ├── server.py           # Flask web server (port 8080)
│   ├── agent.py            # Interactive RAG agent (CLI)
│   ├── backends.py         # Ollama and LM Studio backend adapters
│   ├── ingest.py           # Document ingestion pipeline
│   ├── reindex.py          # Clear and re-ingest from scratch
│   ├── crawl.py            # Recursive directory crawler
│   ├── file_collection.py  # File collection with deduplication
│   ├── file_wrapper.py     # Per-file metadata and checksums
│   ├── config.json         # Configuration
│   ├── requirements.txt    # Python dependencies
│   ├── static/             # Web UI assets (HTML + json-control library)
│   ├── input/              # Put your documents here (git-ignored)
│   └── cache/              # SQLite database lives here (git-ignored)
└── test/
    ├── test_crawl.py
    ├── test_file_collections.py
    ├── test_file_meta_data.py
    └── test_file_wrapper.py

---

Running tests

source .venv/bin/activate
cd source
python -m pytest ../test/

---

Dependencies

| Package | Purpose | |---------|---------| | flask | Web server for the browser UI | | llm | Core embedding and generation interface | | llm-ollama | Ollama backend plugin for llm | | openai | LM Studio OpenAI-compatible API client | | sqlite-utils | SQLite database access for embedding storage |