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.

This guide walks you through a local Python installation of Spy Search. By the end you’ll have the FastAPI backend and React frontend running, and you’ll have submitted your first query.
Prefer a containerised setup with zero dependency management? Skip to the Docker Setup guide and run the entire stack with a single command.

​
Prerequisites

Before you begin, make sure you have the following available:
  • Python 3.12+ — required by the project runtime (pyproject.toml specifies requires-python = ">=3.12")
  • git — to clone the repository
  • Node.js & npm — for the React frontend (installation.sh runs npm install inside frontend/)
  • An LLM API key — for OpenAI, DeepSeek, Gemini, Grok (xAI), or Anthropic; or Ollama running locally for a fully free setup
  • uv (optional) — the setup script installs it automatically if not found

​
Installation Steps

1

Clone the repository

git clone https://github.com/JasonHonKL/spy-search.git
cd spy-search
2

Run the setup script

python setup.py
This script does the following:
  • Creates a .env file pre-populated with placeholder keys for DeepSeek, Gemini, xAI, and OpenAI
  • Creates the required local directories (./tmp/screenshot, ./local_files)
  • Creates an empty messages.json file used by the agent pipeline
After setup.py completes, run the full dependency installer:
sh installation.sh
installation.sh will:
  • Install uv if it isn’t already on your PATH
  • Create and activate a .venv virtual environment
  • Install all Python dependencies from requirements.txt via uv pip install
  • Run playwright install to download the Chromium browser used for web scraping
  • Run npm install --legacy-peer-deps inside the frontend/ directory
3

Copy and configure config.json

cp config.example.json config.json
Open config.json in your editor. The default example uses OpenRouter to serve a Llama 3.3 70B model via the OpenAI-compatible API:
{
  "provider": "openai",
  "model": "meta-llama/llama-3.3-70b-instruct",
  "agents": ["reporter"],
  "db": "./local_files/test",
  "base_url": "https://openrouter.ai/api/v1",
  "language": "en"
}
FieldDescription
providerLLM provider: openai, deepseek, gemini, xai, anthropic, or ollama
modelModel identifier as expected by the chosen provider
agentsActive agent roles — ["reporter"] enables the full plan → search → report pipeline
dbPath for the local ChromaDB vector store used by the RAG layer
base_urlOverride the provider’s default API base URL (useful for OpenRouter or local Ollama)
languageLanguage code for generated reports (e.g. "en", "zh", "ja")
To use Ollama with a locally running model, set "provider": "ollama", point "base_url" to "http://localhost:11434", and set "model" to any model you have pulled (e.g. "qwen3:8b"). No API key is needed.
{
  "provider": "ollama",
  "model": "qwen3:8b",
  "agents": ["reporter"],
  "db": "./local_files/test",
  "base_url": "http://localhost:11434",
  "language": "en"
}
4

Set your API key in .env

Open the .env file created by setup.py and fill in the key for your chosen provider:
OPENAI_API_KEY=sk-...
If you are using Ollama, no API key is required — leave the placeholder values as-is.
5

Start the backend server

Activate the virtual environment and start the FastAPI backend:
source .venv/bin/activate
uvicorn main:app --reload --port 8000
You should see Uvicorn confirm it is serving on http://127.0.0.1:8000.Alternatively, use the bundled run script to start both the backend and the React frontend together:
sh run.sh
run.sh activates the virtual environment, launches the FastAPI server on port 8000, and starts the React dev server on port 8080 — both as background processes.
6

Open the frontend or call the API

Once both processes are running:

​
Quick API Test

You can test the search endpoint directly from your terminal without opening the frontend: 
curl -X POST http://localhost:8000/quick/"what+is+quantum+computing" \
  -F 'messages=[{"role":"user","content":"what is quantum computing"}]'
A successful response will return the Reporter agent’s synthesized answer based on live web content.

​
Next Steps

Docker Setup

Deploy the full stack with Docker Compose — recommended for team or production use.

Introduction

Learn how the Planner, Searcher, and Reporter agents work together.

Build docs developers (and LLMs) love

Get started for freeTalk to us