brick-SR1开源AI工具

Setup

brick profile edit claude  # configure providers, models, routing, and thinking
brick start claude         # start the router and wire Claude Code

Then:

1. Open a new Claude Code session (your current session is unaffected). 2. In the /model picker, select brick-claude (it sits alongside the built-in opus/sonnet/haiku aliases, which it does not replace).

To revert:

brick stop claude   # stop the router and restore future Claude Code launches
brick clear claude  # remove the router runtime while preserving the profile

Brick runs one profile at a time. Stop or clear the active profile before starting another one.

Codex setup

brick profile edit codex  # configure the official Codex profile
brick start codex         # start the router and connect Codex

This materializes a dedicated Codex profile (the OpenAI-pool skill router) and adds a managed provider pointing at the local router. Start a new Codex session and it now routes through Brick.

To revert:

brick stop codex     # detaches future Codex launches from Brick, keeps the current thread's Responses bridge
brick clear codex    # remove the runtime and terminate that bridge

Codex exposes the same routing modes as Claude Code. Configure the model pool, model routing, autonomous reasoning_effort, and cache-aware routing in the profile editor; restart an already-running router to apply changes:

brick profile edit codex
brick restart codex
brick status codex           # live dashboard in an interactive terminal
brick status codex --static  # one static snapshot

brick status codex reports wiring, router reachability, and per-model routing and thinking-mode counts. It does not run inference or probe upstream authentication.

The native Codex Responses integration keeps tools in the original session and isolates provider credentials. Official Codex tool cycles have passed against both the subscription upstream and Regolo's Chat Completions endpoint.

---

⚡ Quickstart

The fastest working path today is the CLI, which self-hosts the router and wires it into Claude Code for you. Requires Node 20 or 22+ and Docker.

git clone https://github.com/regolo-ai/brick-SR1.git
cd brick-SR1/apps/cli && npm install && npm run build && npm link

brick profile edit claude  # configure the official Claude profile
brick start claude         # start the router and connect Claude Code

Then open a new Claude Code session and pick brick-claude in the /model picker. Every request now routes to haiku / sonnet / opus by capability and complexity. See Brick + Claude Code for modes, the effort picker, and the live brick status claude dashboard.

<details> <summary><b>Prefer a raw OpenAI-compatible gateway (no CLI)?</b></summary>

The image is published on Docker Hub (public, no login required). Run the gateway directly:

docker run --rm -p 18000:18000 \
  -e REGOLO_API_KEY=$REGOLO_API_KEY \
  docker.io/regolo/brick:latest      # or pin a version: docker.io/regolo/brick:2.2.0

Then call it like any OpenAI endpoint, just set "model": "brick":

curl http://localhost:18000/v1/chat/completions \
  -H "Authorization: Bearer $REGOLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"brick","messages":[{"role":"user","content":"Prove that sqrt(2) is irrational"}]}'

The x-selected-model response header tells you which backend Brick picked. That math prompt routes to a reasoning model; "Hello" routes to the cheapest one.

Until then, brick start <profile> (from the CLI above) runs the same router locally, syncing skill vectors, starting the container, and connecting the harness for official profiles.

</details>

---

Configuration: the profile editor

brick profile edit claude opens the unified editor for the Claude profile.

brick profile edit claude
brick restart claude  # apply changes when the router is already running

The interactive menu has five top-level entries; each one shows its current value inline. When the router is running, apply edits with `brick restart claude`; no Claude Code session restart is required:

- Providers — backend endpoints in the pool (Regolo, Anthropic, local servers, ...) and their credentials. Secrets are stored in the profile .env, never in the YAML. - Models — the Claude models Brick may route to, plus the allowed thinking modes per model. Pick which of haiku / sonnet / opus (and the Anthropic point releases you have access to) are in play. The skill-vector router only ever picks from this pool; a difficulty fallback map covers the case where the skill router is off. - Thinking modes — the per-model allowed reasoning efforts (off / low / medium / high / xhigh / max). - Cache-aware routing — how Brick handles the prompt-cache invalidation that follows a mid-conversation model switch (see below). - Advanced — server port, complexity service, legacy classifier, multimodal preprocessing, and plugins.

Use the editor to configure context-awareness (the last K turns, default `K = 8`), the local or hosted complexity classifier, Claude Code subagent routing, cache-aware routing, providers, models, and allowed thinking modes. Restart the profile after changes made while it is running.

Cache-aware routing

Switching models mid-conversation invalidates the prompt cache: each provider's KV cache is per-model and opaque, so the new model has to reprocess the whole context at full input price. This setting picks how Brick handles that:

- off — per-request routing, no cross-turn memory. The default. - sticky — keep a conversation on its current model unless switching is actually worth it: downswitching to a cheaper model is always free, upswitching only happens when the estimated quality gain clears the cost of re-priming the cache. See docs/proof/sticky-savings.md for measured savings on real traffic. - smartsqueeze — the opposite tack: instead of avoiding switches, make them cheap. Same cache-aware hysteresis as sticky, but when a switch is taken it compacts the forwarded context (clearing older tool_result blocks, keeping recent turns raw) so the new model reprocesses a small prefix instead of the full one. Deterministic and model-agnostic (works across providers, not just Anthropic), never touches the system prompt or first user turn, and only fires on a switch (a warm cache is never disturbed). Ships shadow-first (compact_shadow_only: true measures the saving without changing what is served) so you can quantify the win before turning it on.

4. Understand the generated `config.yaml`

The exact YAML can contain more fields, but these are the blocks that matter for a standalone setup:

model:
  name: brick
  description: Virtual multimodal routing model
server_port: 8000

default_model: qwen3.5-122b

providers:
  regolo:
    type: openai_compatible
    base_url: https://api.regolo.ai/v1

provider_profiles:
  regolo:
    type: openai_compatible
    base_url: https://api.regolo.ai/v1
provider_endpoints:
  - name: regolo
    provider_profile: regolo
    weight: 1

model_config:
  qwen3.5-122b:
    preferred_endpoints: [regolo]
    param_size: 122b
    reasoning_family: qwen3

complexity_service:
  enabled: true
  protocol: openai
  base_url: https://api.regolo.ai
  model_name: brick-complexity-pro
  bearer_token: ${REGOLO_API_KEY}
  timeout_seconds: 8
  auto_spawn: false

skill_router:
  enabled: true
  dynamic_effort: true
  capabilities: [coding, creative_synthesis, instruction_following, math_reasoning, planning_agentic, world_knowledge]
  capability_model:
    model_id: models/modernbert-capability-classifier
    repo_id: regolo/modernbert-capability-classifier
    use_cpu: true
  complexity_model:
    model_id: brick-complexity-pro
    base_model_id: brick-complexity-pro
    base_url: https://api.regolo.ai
    timeout_seconds: 8
    auto_spawn: false
  math:
    routing_preference: 0
  models:
    - model: qwen3.5-122b
      skill_vector: [0.62, 0.48, 0.70, 0.58, 0.66, 0.78]
      skill_source: benchmark
      skill_confidence: [medium, low, medium, low, medium, high]
      cost_weight: 0.6
      use_reasoning: true
  active_models: [qwen3.5-122b]
  keyword_rules: []

brick:
  enabled: true
  stt_model: faster-whisper-large-v3
  stt_endpoint: https://api.regolo.ai/v1/audio/transcriptions
  ocr_model: deepseek-ocr-2
  ocr_endpoint: https://api.regolo.ai/v1/chat/completions
  vision_model: qwen3.5-122b
  vision_endpoint: https://api.regolo.ai/v1/chat/completions
  ocr_min_text_length: 10

Providers and model endpoints

providers describes a backend in the simplest form. provider_profiles gives it a reusable named profile, while provider_endpoints attaches that profile to the router with a weight. A model's model_config.<id>.preferred_endpoints determines where Brick may send it.

For a custom OpenAI-compatible server:

providers:
  local:
    type: openai_compatible
    base_url: http://host.docker.internal:11434/v1
provider_profiles:
  local:
    type: openai_compatible
    base_url: http://host.docker.internal:11434/v1
provider_endpoints:
  - name: local
    provider_profile: local
    weight: 1
model_config:
  llama3.1:
    preferred_endpoints: [local]
    param_size: 8b

The API key belongs in .env (for example OPENAI_API_KEY=...), not in config.yaml. brick add provider <id> and `brick add model <id> --provider <id>` are convenient for adding these entries after initialization.

skill_router: the routing pool

This is the local Brick router. capabilities fixes the six dimensions used for both prompts and models. Each models entry must keep the same vector order. skill_vector is the measured capability vector; cost_weight is relative cost and controls the cost penalty; use_reasoning and reasoning_effort describe how to request reasoning from that backend. skill_source and skill_confidence record provenance, so a hand-edited or measured vector remains auditable.

active_models is the eligible subset. Removing a model from it does not delete its model_config or skill-card. default_model is the fallback model and should belong to this pool.

math.routing_preference is the continuous cost/quality knob from -1 to 1: negative values favor economy, positive values favor quality, and 0 is balanced. The wizard exposes the same idea as eco, lite, mid, pro, and max.

dynamic_effort: true lets Brick derive reasoning effort from the request's complexity. Set it to false when the client should control effort itself. The separate brick.use_model_routing flag can disable model selection and pin traffic to brick.fixed_model.

Keyword rules

Keyword rules are evaluated before the normal skill-distance decision:

skill_router:
  keyword_rules:
    - name: force_coder
      mode: override
      model: qwen3.5-122b
      importance: 10
      operator: OR
      keywords: [debug, refactor, compile]
      case_sensitive: false
    - name: coding_bias
      mode: bias
      capability: coding
      importance: 8
      operator: OR
      keywords: [python, rust, sql]
      case_sensitive: false

override forces a model when the keywords match (subject to that model being available). bias nudges the capability score without pinning a model. importance resolves competing rules; higher values win.

Classifier modes and Docker topology

With api, complexity_service points to Regolo's hosted brick-complexity-pro, .env contains REGOLO_API_KEY, and Compose runs only the router. With local, the YAML points to the classifier service and Compose adds the Qwen3.5-0.8B sidecar plus BRICK_CLASSIFIER_TOKEN. Local mode avoids hosted classifier calls but needs more memory and is slower on CPU.

The capability classifier (capability_model) is separate: it maps the prompt into the six capability dimensions. The complexity classifier (complexity_service / complexity_model) labels the request easy, medium, or hard. If either service is unavailable, Brick keeps the gateway alive and falls back conservatively rather than turning the endpoint into a second client API.

Multimodal preprocessing

The brick block is the fallback path for images and audio. If a selected model advertises native support, Brick forwards the raw modality. Otherwise it uses the configured STT, OCR, or vision endpoint to turn the input into text before routing. ocr_min_text_length controls when OCR output is considered sufficient.

One Query, One Endpoint, Every LLM on Earth

Brick is a Mixture-of-Models (MoM) routing gateway. It reads each prompt's capability and complexity, then routes it to the best backend in a pool of open- and closed-weight LLMs, matching the strongest single model's quality at a fraction of its cost. No cascades. No wasted calls. Drop-in model: "brick".

When to use Brick · Quickstart · Why Brick · Claude Code · Codex · FAQ · Benchmarks · How it works · Paper

</div>

---

3. Call Brick like an OpenAI endpoint

Use the virtual model name brick; the selected backend is returned in the x-selected-model response header.

curl http://127.0.0.1:8000/v1/chat/completions \
  -H "Authorization: Bearer $REGOLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"brick","messages":[{"role":"user","content":"Prove that sqrt(2) is irrational"}]}'

For scripts and quick checks:

brick generate "Summarize the trade-offs between REST and GraphQL"
brick route "Prove that sqrt(2) is irrational"       # route and make a small completion
brick route "..." --no-generate --json              # routing/latency data as JSON
brick chat                                             # interactive terminal chat

generate prints only the assistant answer. chat is an interactive TUI. route is useful when tuning the pool: it reports the selected model, applied thinking mode, HTTP status, and latency; --repeat N shows min/median/max.

🧱 Brick 3.0 workflow

Brick 3.0 stores independent profiles under ~/.brick/profiles. Profile names are explicit for every lifecycle operation.

brick profile create work
brick profile edit work
brick profile show work
brick profile list

brick start work
brick restart work
brick stop work
brick clear work
brick update

clear removes containers and runtime state while preserving profile configuration, .env, managed harness assets, and volumes. For Codex, `brick stop codex` restores future launches to vanilla Codex while preserving the current thread's local Responses bridge; brick clear codex also terminates that bridge. update --cli, update --router, update --profile <name>, and -y are available for targeted or unattended updates.

skill_vectors.csv is the only authoritative skill-vector source. Brick refreshes it during profile lifecycle commands and caches a private copy at ~/.brick/cache/skill_vectors.csv for network outages. The six canonical capabilities are coding, creative_synthesis, instruction_following, math_reasoning, planning_agentic, and world_knowledge.

The official claude and codex profiles are materialized automatically. They begin dormant, without bundled vectors; select models with `brick profile edit claude or brick profile edit codex` before starting them. Starting an official profile connects its corresponding harness after the router becomes healthy.

---

Works with workflows and subagents

Brick routing is per request. In Claude Code workflows and subagents, each agent's call is routed independently as long as that agent uses brick-claude, so a cheap subagent task can land on haiku while a hard one escalates to opus in the same run.

---

❓ FAQ

<details> <summary><b>How is Brick different from a cascade router like FrugalGPT?</b></summary>

A cascade calls models in sequence (cheap first, escalate on low confidence) and pays for every miss in tokens and latency. Brick makes a single forward decision per query from a capability vector and a complexity score, so there is no wasted call. See Why Brick. </details>

<details> <summary><b>Which backend did Brick pick for my request?</b></summary>

Read the x-selected-model response header. Every /v1/chat/completions and /v1/messages response carries it. </details>

<details> <summary><b>How do I trade cost against quality?</b></summary>

Slide the r knob in r ∈ [-1, 1]. At r = -1 Brick favors the cheapest capable model (max-saving), at r = 1 it favors the strongest (max-quality). For Claude Code the same idea is exposed as 5 named modes, see the 5 modes. </details>

<details> <summary><b>Do I need GPUs to run the gateway?</b></summary>

No. The router and both classifiers run on CPU. GPUs only matter if you self-host the backend LLMs; with a hosted pool (Regolo, Anthropic, etc.) a CPU box is enough. </details>

<details> <summary><b>Can I use my own model pool?</b></summary>

Yes. The pool, per-model skill vectors, costs, and the model_map live in config.yaml (skill_router.models). Add or swap any OpenAI-compatible backend. See apps/router/README.md. </details>

<details>

<summary><b>What is the upstream for the OpenAI-compatible endpoint failing with 401/insufficient_quota?</b></summary>

That error comes from the backend provider, not Brick. Check the credential you forward (REGOLO_API_KEY or your own key); Brick passes Authorization through unchanged. </details>

---