Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/JasonHonKL/spy-search/llms.txt

Use this file to discover all available pages before exploring further.

The Local RAG feature lets you search your own documents alongside live web content. Instead of (or in addition to) querying the internet, Spy Search converts your files to Markdown, indexes them in a local ChromaDB vector store, retrieves the most relevant passages at query time, and passes them to the LLM as context.

​
How It Works

  1. Document conversion — Every file in your configured directory is converted to Markdown using MarkItDown. MarkItDown handles PDF, Word, Excel, PowerPoint, plain text, and Markdown natively, preserving structure and formatting as plain text.
  2. Chunking — The Markdown text is indexed using a 1500-character boundary. The _file_handler method iterates over every character and stores a snapshot of the accumulated text into ChromaDB at every 1500th character position. Each stored document includes metadata recording the source file path.
  3. Embedding and indexing — ChromaDB uses an Ollama embedding function (nomic-embed-text:latest by default, served at http://localhost:11434) to convert each chunk into a vector and persist it under ./local_db.
  4. Retrieval at query time — When the local-retrieval agent runs, it calls db.query(task, 2) to fetch the top-2 most relevant chunks via vector similarity search.
  5. LLM synthesis — Each retrieved chunk is passed through a retrieval_prompt and sent to the LLM, which generates a structured summary. The summaries are appended to the shared data array and forwarded to the next agent in the pipeline (typically the Reporter).
The RAG agent calls db.reset() at initialisation on every run. This clears and re-creates the ChromaDB collection, ensuring the index always reflects the current contents of your files directory rather than a stale snapshot.

​
Enabling Local RAG

Add "local-retrieval" to the agents array in your config.json and set the db field to the directory containing your documents: 
{
  "provider": "ollama",
  "model": "llama3.2",
  "agents": ["local-retrieval", "reporter"],
  "db": "./local_files/my_docs"
}
If the db key is absent, the agent defaults to ./local_files.

​
Managing Files via the API

Use the following endpoints to manage your document library without touching the filesystem directly.
MethodEndpointDescription
GET/folder_listList all available folders
POST/create_folderCreate a new folder
GET/select_folder?folder_name=<name>Set the active folder for indexing
POST/upload_fileUpload a file (multipart form)
POST/delete_fileDelete a file by path
For full request/response schemas, see the File Management API reference.

​
Upload a file

curl -X POST http://localhost:8000/upload_file \
  -F 'file=@report.pdf' \
  -F 'filepath=my_project'

​
Create a folder

curl -X POST http://localhost:8000/create_folder \
  -H 'Content-Type: application/json' \
  -d '{"filepath": "my_project"}'

​
Select a folder

curl "http://localhost:8000/select_folder?folder_name=my_project"

​
Supported File Types

MarkItDown handles any format it can meaningfully convert to Markdown text. Confirmed supported types include:
File typeExtension(s)
PDF.pdf
Word document.docx, .doc
Excel spreadsheet.xlsx, .xls
PowerPoint presentation.pptx, .ppt
Plain text.txt
Markdown.md, .mdx
Any file format that MarkItDown cannot parse will be skipped silently.

​
ChromaDB Configuration

SettingValue
Database path./local_db
Embedding modelnomic-embed-text:latest
Embedding serverhttp://localhost:11434 (Ollama)
Collection namelocal_search
Chunk boundaryEvery 1500 characters
Results returned per query2 chunks
The VectorSearch class wraps ChromaDB’s PersistentClient with allow_reset=True, so the full database can be wiped and rebuilt in a single client.reset() call.

​
Example: Local RAG + Report Pipeline

{
  "agents": ["local-retrieval", "reporter"],
  "db": "./local_files/research_papers"
}

curl -X POST "http://localhost:8000/report/summarise+Q3+financial+results" \
  -F 'messages=[{"role":"user","content":"summarise Q3 financial results"}]'
With this configuration, the RAG agent indexes all documents in ./local_files/research_papers, retrieves the most relevant passages, and the Reporter agent writes a structured report grounded in your own files.

Build docs developers (and LLMs) love

Get started for freeTalk to us