# Salyut 🛰️

**A council of AI models you can ask for a second opinion — from inside a coding session, a shell, or your household assistant.**

Salyut is a small [MCP](https://modelcontextprotocol.io) server that fans one question out to several
independent free LLMs (different vendors, different training lineages) and returns their answers side
by side, each attributed to its model. Different models catch different things, so a quick "ask the
panel" is a cheap way to sanity-check a judgment call, break a tie, or get an outside read.

It's named for the Salyut space stations — the place where the crew (here, a panel of models) convenes.

> **Built with Claude (Opus 4.8).** This project — code, tests, and docs — was written collaboratively with Anthropic's Claude.

## The panel

| Provider | Model | Lineage | In the default roster? |
|---|---|---|---|
| Cerebras | `gpt-oss-120b` | OpenAI-lineage, ~0.2s | ✅ |
| Z.ai | `glm-4.7-flash` | Chinese (Zhipu) | ✅ |
| Groq | `llama-3.3-70b-versatile` | Meta | ✅ |
| Google | `gemini-flash-latest` | Google (best-effort — thin free quota) | ✅ |
| Mistral | `mistral-large-latest` | European | ⚠️ opt-in only |

All run on **free API tiers**. Mistral is left **out of the default roster on purpose**: its free tier
trains on submitted data, so it's only ever called when a caller explicitly names it (which the
household assistant never does). See the wiki for the reasoning.

## How it's used

- **In a coding session** — registered as an MCP server, so the assistant can call `consult(...)` mid-task to get an outside opinion.
- **From a shell** — a thin CLI (`consult.cli`) for scripting and model bake-offs (e.g. A/B-testing a prompt across models).
- **By a household assistant** — as one more MCP tool it reaches for *only when genuinely unsure*.

Because every caller goes through the one server, a single **rate-guard** keeps any one of them from
draining a thin free-tier bucket the next caller needs.

<details><summary><b>What's inside</b></summary>

- `consult/core.py` — the providers, the fan-out, and a fail-safe call wrapper (any error becomes an `"ERROR: …"` string, never a crash).
- `consult/ratelimit.py` — the shared rate-guard (per-provider min-interval + daily cap; fails open for unconfigured providers, closed once a cap is hit).
- `consult/server.py` — the MCP server (FastMCP, streamable-HTTP at `/mcp`), exposing `consult` and `listmodels`.
- `consult/cli.py` — the shell client (talks to the server by default so the shared guard applies; `--direct` for offline use).
</details>

<details><summary><b>Personalize (change these for your setup)</b></summary>

- **API keys** — six provider keys via environment (`CEREBRAS_API_KEY`, `ZAI_API_KEY`, `GROQ_API_KEY`, `GEMINI_API_KEY`, `MISTRAL_API_KEY`, `OPENROUTER_API_KEY`). Any you leave unset simply drop out of the roster — no crash. See `.env.example`.
- **The roster** — edit `DEFAULT_ROSTER` / `FULL_ROSTER` in `consult/core.py`. Each model is also overridable by env var (e.g. `CONSULT_CEREBRAS_MODEL`).
- **Rate limits** — `GUARD_MIN_INTERVAL` / `GUARD_DAILY_CAP` in `consult/core.py`, set from each provider's real free-tier limits.
- **Where it listens** — `CONSULT_HOST` / `CONSULT_PORT` (defaults `0.0.0.0:8000`).
- Free-model slugs **rotate** — if a default starts erroring, re-check the provider's model list.
</details>

## Setup & usage

**Install, configure, deploy, and wire it into your tools — see the [wiki](../../wiki).** (The README
describes *what* Salyut is; the wiki is the step-by-step manual.)

## License

GPL-3.0-or-later — see [LICENSE](LICENSE).