Metadata-Version: 2.4
Name: substrate-setup
Version: 0.6.0
Summary: One-shot local configurator for coding agents against a Substrate gateway
Project-URL: Homepage, https://github.com/FrankXiaA/substrate-solutions
Project-URL: Source, https://github.com/FrankXiaA/substrate-solutions/tree/main/substrate-api/substrate_setup
Project-URL: Issues, https://github.com/FrankXiaA/substrate-solutions/issues
Author: Substrate Solutions
License: MIT
Keywords: aider,continue,gateway,hermes,llm,openai-compatible,substrate
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Code Generators
Classifier: Topic :: Utilities
Requires-Python: >=3.8
Requires-Dist: httpx>=0.27
Requires-Dist: ruamel-yaml>=0.18
Requires-Dist: tomli-w>=1.0
Requires-Dist: tomli>=2.0; python_version < '3.11'
Provides-Extra: dev
Requires-Dist: mypy<2,>=1.13; extra == 'dev'
Requires-Dist: pytest-httpx>=0.30; (python_version >= '3.9') and extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff<1,>=0.7; extra == 'dev'
Description-Content-Type: text/markdown

# substrate-setup

One-shot configurator that points local coding agents at a Substrate gateway.

## Install

`substrate-setup` runs on **Python 3.8 or newer** — including Anaconda's default 3.9 and the system Python on older Linux/macOS boxes. Plain `pip` works:

```bash
pip install substrate-setup
```

If you'd rather keep the tool in its own isolated environment (recommended, so it can't clash with a project's dependencies), use `uv` or `pipx`:

```bash
# Option A — uv (also downloads a Python for the tool if needed)
uv tool install substrate-setup

# Option B — pipx
pipx install substrate-setup
```

Don't have `uv`? Install it once with:

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh   # macOS / Linux
# or on Windows:
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```

## Use

```bash
substrate-setup configure          # detect installed agents and wire them up
substrate-setup verify             # read-only: confirm everything points at the gateway
substrate-setup verify --probe-endpoints   # also check /v1/messages + /v1/responses are live (free, no generation)
substrate-setup remove             # strip the substrate-managed entries
substrate-setup --help
```

### After running configure

`substrate-setup configure` writes the API key for you automatically. On Windows it lands in `HKCU\Environment\SUBSTRATE_API_KEY` (visible to Codex Desktop and other GUI agents on next launch). On macOS / Linux it lands in your shell rc (`~/.zshrc`, `~/.bashrc`, or `~/.config/fish/config.fish` depending on `$SHELL`) inside a marker-fenced block — re-running configure replaces the block in place, no duplicates.

You should not need to set `SUBSTRATE_API_KEY` by hand. If auto-persistence fails (the printed message will say `API key WARNING: …`), you can set it manually:

- **Windows:** `[Environment]::SetEnvironmentVariable("SUBSTRATE_API_KEY", "<your-key>", "User")` then re-launch the agent.
- **macOS / Linux:** add `export SUBSTRATE_API_KEY=<your-key>` to your shell rc and `source` it.

Supported agents: `hermes`, `cursor`, `aider`, `continue`, `claude-code`, `codex`.

Subset with `--agents-only hermes,aider`. Preview without writing: `--dry-run`. Override the gateway base URL: `--base-url https://your-gateway.example.com`.

### Per-agent catalog UX (0.3.0+)

| Agent | How it learns about Substrate's models |
|---|---|
| `hermes` | Live URL fetch via `model_catalog.providers.substrate.url`. Picker shows all chat-capable Substrate models, refreshed on Hermes' 24h TTL. |
| `cursor` | Walkthrough printed after configure — copy the base URL, key, and model ids into Cursor's Settings → Models. |
| `aider` | `~/.aider.model.metadata.json` written with one entry per chat-capable Substrate model. Use `--model openai/<id>` to switch. |
| `continue` | All chat-capable Substrate models written as separate `models:` entries in `~/.continue/config.yaml`. |
| `claude-code` | `~/.claude/settings.json` env block (`ANTHROPIC_BASE_URL`, `ANTHROPIC_AUTH_TOKEN`, `ANTHROPIC_MODEL`). The `/model` picker stays opus/sonnet/haiku — use `claude --model openai/<id>` for any other Substrate model. Requires Substrate's `/v1/messages` endpoint — shipped in gateway Phase 1. |
| `codex` | `~/.codex/config.toml` `[model_providers.substrate]` block with `wire_api = "responses"`. API key is auto-persisted (see above). Requires Substrate's `/v1/responses` endpoint — shipped in gateway Phase 2. |

### Coexisting with account switchers (cc-switch, cockpit) — 0.5.0+

If you use an account-switcher like [cc-switch](https://github.com/farion1231/cc-switch)
or [cockpit](https://github.com/jlcodes99/cockpit-tools), it already owns
`~/.claude/settings.json` and/or `~/.codex/config.toml` — it rewrites the
`ANTHROPIC_*` env block / `[model_providers.*]` on every switch. substrate-setup
and the switcher can't both own the same keys, so `configure` **detects the
switcher and leaves those files untouched**, printing guidance instead of
fighting it. (`hermes`, `cursor`, `aider`, `continue` are unaffected — they use
their own files.)

**Recommended: add Substrate as a provider inside your switcher**, then switch to
it when you want the gateway:

- **Claude Code** — `ANTHROPIC_BASE_URL = https://substrate-solutions-api.fly.dev`
  (no `/v1`), `ANTHROPIC_AUTH_TOKEN = <your sk-substrate-… key>`
- **Codex** — `base_url = https://substrate-solutions-api.fly.dev/v1`,
  `wire_api = "responses"`, key = your `sk-substrate-…`

Alternatives:
- **One-off Claude Code session:** `export ANTHROPIC_BASE_URL=… ANTHROPIC_AUTH_TOKEN=…`
  before `claude` — shell env overrides the switcher's settings file, touches nothing.
- **Let substrate-setup own the file anyway:** re-run with `--force` (it backs up
  the file first). Note your switcher will then overwrite it on its next switch.

### Heads-up: tool calling on Gemini 3.1 Pro Preview

If your CLI agent (Hermes, Aider, etc.) uses tool calling against
`google/gemini-3.1-pro-preview`, expect occasional misses (~20-30% of
attempts). All other Substrate models hit ≥95% reliability for tool calls.

## Troubleshooting

### Windows: Defender SmartScreen prompts on every Codex click

Codex Desktop spawns helper binaries (`codex-command-runner.exe`,
`node_repl.exe`) per UI action. With `sandbox = "elevated"` in
`~/.codex/config.toml`, each spawn triggers Windows Defender
SmartScreen, prompting you on every click until the Codex install
directory is whitelisted.

One-time fix — open an **Administrator** PowerShell window and run:

```powershell
Add-MpPreference -ExclusionPath "$env:LOCALAPPDATA\OpenAI\Codex"
```

This excludes Codex's binaries from real-time scanning. Reverse with
`Remove-MpPreference -ExclusionPath "$env:LOCALAPPDATA\OpenAI\Codex"`.

`substrate-setup configure --agents-only codex` also prints this
command at the end of its walkthrough on Windows.
