Companion — give your agent a second AI to talk to

Companion is a tool, not a service: you run python main.py "<prompt>" and get a result. Which AI answers is entirely up to you — you implement the provider once, then just call the tool.

One-time setup (do this on first use)

1. Read provider.py. It has helpers (http_json, http_bytes, encode_file_b64, api_key) and a template stub showing the exact shape a provider must have.
2. Implement a provider for the API you want (any HTTP endpoint or SDK, any modality). Register it: @register("myprovider"). Return Result(text=...) for text or Result(data=..., mime=...) for binary.
3. Edit config.py: set provider, model, base_url, api_key_env (the env var that holds the key — never paste the key itself into the file), and the default mode.
4. Verify: python main.py "say the word: ready" — expect the model's reply on stdout.

Details and worked examples: AGENT_GUIDE.md.

Calling it

python main.py "<prompt>"                       # direct: result on stdout
python main.py "<prompt>" --mode file           # saves result, prints file path
python main.py "<prompt>" --attach img.png      # send local files (repeatable)
python main.py "<prompt>" --model other-model   # per-call overrides
python main.py "<prompt>" --extra '{"temperature": 0}'
python main.py "<prompt>" --mode file --out result.mp3

• direct prints text results only. If the provider returns binary (image/audio/video), direct mode fails on purpose — rerun with --mode file and read/serve the printed path instead.
• Errors arrive on stderr with exit code 1 and say what to fix (missing key, unregistered provider, HTTP error body). Fix the cause; do not retry blindly.

When to reach for it

• Validation: cross-check your own answer against a different model before asserting a fact (hallucination check).
• Data generation: batch-produce synthetic examples with a cheaper or faster model.
• Missing modality: generate images/audio/video, transcribe audio, or use a vision model when you have none.
• Multilingual: route to a model stronger in the target language.