MARS - Multi Agent Regulation System

MARS is a high-performance RAG application designed for compliance and regulation management.

Project Structure

.
├── backend/
│   ├── app/              # FastAPI app, RAG engine, API routes, skills
│   ├── data_temp/        # Runtime upload/session files
│   └── sql/              # Supabase SQL helpers
├── data/                 # User drop folder for base knowledge files
├── frontend/
│   ├── index.html
│   └── static/           # CSS and browser JavaScript served at /static
├── public/               # Favicons, gateway config, public HTML templates
├── scripts/              # Indexing and maintenance scripts
├── tests/                # Diagnostic and test scripts
├── config.json           # App channel/gateway configuration
├── main.py               # Production entrypoint
└── requirements.txt

Setup

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt
Copy-Item .env.example .env

Fill .env with your Supabase values. Set OLLAMA_URL if Ollama is not running on http://127.0.0.1:11434. If Ollama is not installed or not reachable, python main.py prompts for an API provider, key, chat model, and embedding model. Known providers use documented endpoints automatically; only Other / manual endpoint asks for a custom endpoint. Provider order is GitHub Models, OpenAI, Anthropic Claude, Google Gemini, xAI Grok, OpenRouter, DeepSeek, then manual.

API keys are normalized. The explicit names still work, but Mars also accepts simpler/common aliases:

MARS_API_KEY=...
MARS_API=...
MARS_TOKEN=...
GITHUB_TOKEN=...
GH_TOKEN=...
OPENAI_API_KEY=...
ANTHROPIC_API_KEY=...
GEMINI_API_KEY=...
XAI_API_KEY=...
GROK_API_KEY=...
OPENROUTER_API_KEY=...
DEEPSEEK_API_KEY=...

Provider-specific aliases are selected from MARS_LLM_PROVIDER and the known endpoint. Embeddings can still use MARS_EMBEDDING_API_KEY when the embedding provider needs a different token.

GitHub Models example:

MARS_LLM_PROVIDER=github
MARS_LLM_API_STYLE=openai-compatible
GITHUB_TOKEN=your_github_token
MARS_CHAT_MODEL=openai/gpt-4.1
MARS_EMBEDDING_PROVIDER=github
MARS_EMBEDDING_API_STYLE=openai-compatible
MARS_EMBEDDING_MODEL=openai/text-embedding-3-small

OpenAI example:

MARS_LLM_PROVIDER=openai
MARS_LLM_API_STYLE=openai-compatible
OPENAI_API_KEY=your_openai_key
MARS_CHAT_MODEL=gpt-4.1-mini
MARS_EMBEDDING_PROVIDER=openai
MARS_EMBEDDING_API_STYLE=openai-compatible
MARS_EMBEDDING_MODEL=text-embedding-3-small

Claude chat with separate embeddings example:

MARS_LLM_PROVIDER=anthropic
MARS_LLM_API_STYLE=anthropic
ANTHROPIC_API_KEY=your_anthropic_key
MARS_CHAT_MODEL=claude-sonnet-4-20250514
MARS_EMBEDDING_PROVIDER=openai
MARS_EMBEDDING_API_STYLE=openai-compatible
OPENAI_API_KEY=your_embedding_api_key
MARS_EMBEDDING_MODEL=text-embedding-3-small

Gemini example:

MARS_LLM_PROVIDER=gemini
MARS_LLM_API_STYLE=openai-compatible
GEMINI_API_KEY=your_gemini_key
MARS_CHAT_MODEL=gemini-2.5-flash
MARS_EMBEDDING_PROVIDER=gemini
MARS_EMBEDDING_API_STYLE=openai-compatible
MARS_EMBEDDING_MODEL=gemini-embedding-001

xAI Grok chat with OpenRouter embeddings example:

MARS_LLM_PROVIDER=xai
MARS_LLM_API_STYLE=openai-compatible
XAI_API_KEY=your_xai_key
MARS_CHAT_MODEL=grok-4.20-reasoning
MARS_EMBEDDING_PROVIDER=openrouter
MARS_EMBEDDING_API_STYLE=openai-compatible
OPENROUTER_API_KEY=your_openrouter_key
MARS_EMBEDDING_MODEL=openai/text-embedding-3-small

OpenRouter example:

MARS_LLM_PROVIDER=openrouter
MARS_LLM_API_STYLE=openai-compatible
OPENROUTER_API_KEY=your_openrouter_key
MARS_CHAT_MODEL=openai/gpt-4.1
MARS_EMBEDDING_PROVIDER=openrouter
MARS_EMBEDDING_API_STYLE=openai-compatible
MARS_EMBEDDING_MODEL=openai/text-embedding-3-small

Run

python main.py

The app binds to 0.0.0.0:8080 by default. Set PORT to override it.

Docker

Build:

docker build -t mars-rag .

The Docker build uses requirements.docker.txt, which leaves out optional/dev-only dependencies such as spacy and direct Postgres setup helpers to keep image builds practical.

Run with your local .env mounted as runtime configuration:

docker run --rm -it --env-file .env -p 8080:8080 mars-rag

If you want the container to call Ollama running on the host, set OLLAMA_URL to the host address in .env, for example http://host.docker.internal:11434. Otherwise configure the MARS_* API fallback variables in .env.

Docker --env-file keeps wrapping quotes literally. Mars normalizes quoted values at startup, but new values are best written without quotes.

Base Knowledge

Fresh npm installs create an empty data/ folder. Drop .pdf, .xlsx, .csv, or .docx files there, then run:

mars refresh

mars refresh indexes into the configured storage backend. Local mode writes to backend/data_temp/local_db/chunks.json; cloud mode writes to Supabase.

The packaged local install also contains a sanitized seed index for the built-in baseline knowledge, so backend/data_temp/local_db/chunks.json is initialized on first local run without shipping session uploads or personal runtime state.

Scripts

python scripts\index_documents.py --help
python scripts\reindex_documents.py
mars refresh

Notes

• Runtime paths are resolved from the repository root, not from machine-specific absolute paths.
• public/active_mindmap.html, backend/data_temp/, logs, and Python caches are generated at runtime.