MINI_RAG is a local-first Retrieval-Augmented Generation service built on FastAPI, ChromaDB, sentence-transformers, and pluggable LLM backends. It now supports:

• web crawling with in-domain restrictions and cache support
• durable background crawl jobs with status endpoints
• file ingestion for pdf, txt, md, and docx
• metadata-aware chunking and persistent vector storage
• provider-based generation with ollama, openai, anthropic, or google
• optional API-key authentication and remote Chroma connectivity
• grounded query responses and streamed query output
• document lifecycle endpoints for upload, list, and delete
• a reusable swarm CLI for multi-agent crawl -> analyze -> reduce workflows
• an Apex-Dalal Streamlit GUI (mini_rag/gui/app.py) wrapping a LangGraph multi-agent pipeline (recall → triage → macro → sector → final → persist) with Neo4j-backed institutional memory
• structured logging, basic Prometheus-style metrics, and containerized deployment

The current app entrypoint is mini_rag/app/main.py. Core ingestion and retrieval logic lives in:

• mini_rag/core/document_loader.py
• mini_rag/core/metadata_manager.py
• mini_rag/core/text_splitter.py
• mini_rag/core/ingestion_orchestrator.py
• mini_rag/services/vector_store_service.py
• mini_rag/services/crawler_service.py
• mini_rag/services/retrieval_service.py
• mini_rag/services/llm_service.py

The architectural roadmap and component breakdown remain in ARCHITECTURE.md.

• Python 3.11+
• one configured LLM provider:
  • Ollama running locally or reachable over the network, or
  • valid cloud credentials for OpenAI, Anthropic, or Google
• a locally available embedding model cache for all-MiniLM-L6-v2, or outbound access the first time it is loaded

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
uvicorn mini_rag.app.main:app --reload

The main API will be available at http://127.0.0.1:8000.

The baseline environment template is in .env.example. Key variables:

• CHROMADB_PERSIST_DIR: persistent storage path for Chroma
• CHROMA_HOST / CHROMA_PORT / CHROMA_SSL: optional remote Chroma connection
• DOCUMENTS_DIR: uploaded file storage path
• AUTH_ENABLED / API_KEYS / AUTH_HEADER_NAME: API-key protection for non-health endpoints
• API_KEY_TENANT_ID: optional tenant scope for API-key authenticated requests
• OIDC_ENABLED / OIDC_ISSUER_URL / OIDC_AUDIENCE / OIDC_JWKS_URL: bearer-token validation against an OpenID Connect provider
• AUTH_TENANT_CLAIM / AUTH_ROLES_CLAIM: claim paths used to extract tenant and role data from OIDC tokens
• TENANT_ENFORCEMENT_ENABLED: reject authenticated bearer tokens that lack a tenant claim
• JOBS_DB_PATH / JOB_WORKER_ENABLED: durable crawl job queue configuration
• LLM_PROVIDER: one of ollama, openai, anthropic, google
• LLM_MODEL_NAME: provider-specific model override
• LLM_TIMEOUT_SECONDS: generation timeout across providers
• OLLAMA_BASE_URL: Ollama host, default http://localhost:11434
• OLLAMA_MODEL_NAME: generation model, default qwen2.5-coder:14b
• OPENAI_API_KEY / OPENAI_BASE_URL: OpenAI credentials and optional compatible endpoint
• ANTHROPIC_API_KEY: Anthropic credential
• GOOGLE_API_KEY: Google GenAI credential
• DEFAULT_CHUNK_SIZE / DEFAULT_CHUNK_OVERLAP: ingestion chunking settings
• CRAWL_CACHE_TTL_SECONDS: TTL for cached crawl responses
• CRAWL_MAX_CONCURRENCY: in-process crawl concurrency cap

• GET /health
• GET /status
• GET /metrics

• POST /documents/upload
• POST /documents/batch-upload
• GET /documents
• DELETE /documents/{source_id}

• POST /crawl
• POST /crawl/batch
• POST /crawl/jobs
• POST /crawl/jobs/batch
• GET /crawl/jobs
• GET /crawl/jobs/{job_id}

• POST /query
• POST /query/stream

Tenant-aware requests now work end-to-end for document upload, crawl, and query routes when OIDC is enabled and a tenant claim is present. The backend injects the authenticated tenant into stored metadata and automatically constrains retrieval and job visibility to that tenant.

Upload a document:

curl -X POST http://127.0.0.1:8000/documents/upload \
  -F "file=@README.md"

Crawl a site:

curl -X POST http://127.0.0.1:8000/crawl \
  -H "Content-Type: application/json" \
  -d '{"start_url":"https://example.com","max_pages":5,"max_depth":1}'

Query indexed content:

curl -X POST http://127.0.0.1:8000/query \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"query":"What information is available?","top_k":5}'

Stream a query:

curl -N -X POST http://127.0.0.1:8000/query/stream \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"query":"Summarize the indexed content"}'

Enqueue a background crawl job:

curl -X POST http://127.0.0.1:8000/crawl/jobs \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"start_url":"https://example.com","max_pages":10,"max_depth":2}'

Run the reusable multi-agent crawl/analyze/reduce workflow with the default GRC template:

python run_swarm.py --missions templates/grc_swarm.yaml

Or use the built-in template selector:

python run_swarm.py --template grc --api-base http://127.0.0.1:8000

If auth is enabled, pass the API key and the CLI will send it as Authorization: Bearer ...:

python run_swarm.py \
  --template grc \
  --api-key your-api-key \
  --output-dir artifacts

Each run writes:

• artifacts/swarm_<timestamp>.json
• artifacts/swarm_<timestamp>.md

The JSON artifact includes mission/job/report metadata. The Markdown artifact includes every scout report plus the final synthesis and remediation plan.

Run the current automated suite:

source mini_rag/venv/bin/activate
pytest -q mini_rag/tests test_ingestion_orchestrator.py

The test suite covers:

• embedding and retrieval services
• crawler and crawl routes
• auth and status routes
• text splitting and metadata grouping
• vector store adapter behavior
• document, query, and integration API flows

A simple threaded load tool is included in scripts/load_test.py.

Examples:

python scripts/load_test.py \
  --url http://127.0.0.1:8000/health \
  --method GET \
  --requests 100 \
  --concurrency 20

python scripts/load_test.py \
  --url http://127.0.0.1:8000/query \
  --method POST \
  --payload '{"query":"ping"}' \
  --requests 20 \
  --concurrency 5

Build and run the API container:

docker build -t mini-rag .
docker run --rm -p 8000:8000 --env-file .env mini-rag

For the full stack (Streamlit GUI + FastAPI + Neo4j memory, pointed at a host-side Ollama):

docker compose up --build

That brings up three services:

• gui at http://localhost:8501 — the Apex-Dalal Streamlit app (mini_rag/gui/app.py). Sidebar shows Ollama/Neo4j health, per-stage LLM routing, and recent briefs. Click 🚀 Run Apex-Dalal pipeline to generate a brief.
• app at http://localhost:8000 — the main FastAPI RAG backend.
• neo4j at http://localhost:7474 (browser) and bolt://localhost:7687 — institutional memory for the Apex-Dalal agent.

Ollama is intentionally not a compose service — both gui and app point at host.docker.internal:11434. Pull the models you need on the host daemon before running:

ollama pull qwen2.5-coder:14b
ollama pull codestral:22b

If you prefer a containerized Ollama, uncomment the ollama service block at the bottom of docker-compose.yml and flip OLLAMA_BASE_URL on both gui and app back to http://ollama:11434.

• request logs are structured with structlog
• GET /metrics exposes a Prometheus-style plaintext metrics snapshot
• GET /status exposes auth, job queue, vector store, active LLM provider/model readiness, and embedding readiness
• rotating logs are written under the configured LOGS_DIR

Deployment notes and operational guidance are in DEPLOYMENT.md.