Route everyday AI work wisely. Blossom Router is a small macOS-friendly CLI in the Blossom ecosystem that sends each prompt to a configurable local or cloud model tier. Routine work stays local or cheap; difficult work can be sent explicitly to stronger models. It remains intentionally limited to a single binary, one YAML file, one OpenAI-compatible protocol, and deterministic routing you can inspect before it runs.
- Save premium-model quota by keeping short, repetitive work local.
- Use one command across Ollama and OpenAI-compatible cloud endpoints.
- Keep provider names, model IDs, endpoints, and credentials out of the binary.
- Preview automatic decisions with
bloom auto --dry-runwithout calling a model. - Avoid hidden retries, fallbacks, model chains, telemetry, and stored conversations.
Requirements: Go 1.24+; Ollama is optional but recommended for local use.
make test
make install
mkdir -p ~/.config/blossom
cp config.example.yaml ~/.config/blossom/router.yamlmake install writes bloom to ~/.local/bin by default. If which bloom still reports not found, activate that directory in the current zsh session:
export PATH="$HOME/.local/bin:$PATH"
rehashTo keep it available in new terminals, add the export to ~/.zshrc, then run source ~/.zshrc. Your existing terminal does not automatically reload a changed shell profile.
To install elsewhere:
make install PREFIX=/usr/localEdit ~/.config/blossom/router.yaml. Every route points to an OpenAI-compatible endpoint; model names are never compiled into cloud commands. API keys can be provided indirectly with api_key_env, or directly with api_key (not recommended).
Each configured provider also supports environment overrides:
export BLOSSOM_LOCAL_MODEL=qwen3:8b
export BLOSSOM_LOCAL_BASE_URL=http://localhost:11434/v1
export BLOSSOM_STRONG_MODEL=your-model
export BLOSSOM_STRONG_BASE_URL=https://api.example.com/v1
export BLOSSOM_STRONG_API_KEY=secretEnvironment override names use BLOSSOM_<PROVIDER>_{MODEL,BASE_URL,API_KEY}. Values from environment variables override YAML.
bloom local "summarize this log"
bloom ask "explain this deployment failure"
git diff | bloom code "review this diff"
bloom strong "compare these architecture options"
bloom auto "translate this release note"
bloom auto --dry-run "design a migration plan"
cat error.log | bloom auto
bloom serveauto uses transparent rules: short general prompts go local; summary/translation/classification and medium prompts go cheap; coding keywords go normal; architecture/security/migration/root-cause keywords and prompts over 3,000 characters go strong. It prints the chosen route to stderr. --dry-run never calls a model.
code is a separate configurable provider slot. It can target any Codex/OpenAI-compatible chat-completions endpoint, but it makes exactly one request and performs no hidden planning, retry, or model chaining.
Run bloom serve to open http://127.0.0.1:7331. The local-only control panel lets you select a route, paste a prompt, preview automatic routing, run the request, and copy the result. It uses the same YAML and environment variables as the CLI; resolved API keys stay server-side. The server refuses non-loopback addresses.
Install and start Ollama, then pull the model named in your config:
brew install ollama
ollama serve
ollama pull qwen3:8b
bloom local "用三句话总结 Kubernetes readiness probe"Choose a Qwen size that fits your Mac memory and change only providers.local.model. Ollama exposes the compatible endpoint at http://localhost:11434/v1; it does not require an API key.
For each cloud tier, set its base_url, model, and api_key_env. Different tiers may use the same vendor with different models, or entirely different compatible vendors. No particular OpenAI model is assumed. If an endpoint does not implement /v1/chat/completions, place a compatible gateway in front of it or extend the Provider interface in internal/provider.
This MVP deliberately excludes RAG, MCP, a web UI, databases, conversation history, streaming, tool calls, and automatic fallback. Those can be added later only when real usage justifies them.
