brainregion 0.1.0

BrainRegion（脑区）：AI collaboration infrastructure for review, consultation, planning, and memory.

脑区 BrainRegion

English | 简体中文

BrainRegion is AI collaboration infrastructure for review, consultation, planning, and memory.

This project was formerly design-review-mcp. The internal Python package has moved to brainregion, while the old CLI command aliases remain available during the rename.

The current MCP server and CLI can fan out a plan, source change, or document to multiple LLM reviewer roles, retrieve project-specific knowledge, normalize duplicate findings, and return consensus-oriented reports that are easier to act on. It also includes external consultation tools for asking another expert model when the main assistant is stuck.

The core pipeline is project-agnostic. Project-specific behavior lives in adapters, so the default experience stays useful for general product, architecture, code, and document design reviews. Optional adapters can add domain knowledge without changing the core pipeline.

Highlights

• Review plans, code, Markdown, ADRs, RFCs, and config documents.
• Use reviewer roles such as planner, safety, architecture, performance, feasibility, and visionary.
• Run one model or a panel of models, including official LiteLLM providers and OpenAI/Anthropic-compatible gateways.
• Retrieve framework and project-local knowledge before review.
• Normalize findings into canonical buckets and separate consensus, majority, and individual issues.
• Render JSON, Markdown, and SARIF output.
• Track review memory with mark_finding so accepted/rejected findings can influence later confidence calibration.
• Ask external consultant models with consult_problem and record useful advice with mark_advice.
• Generate executable task plans with plan_task, then review the plan before implementation.
• Route a goal/problem to likely Brain Regions with route_regions as a local, deterministic precursor to context scheduling.
• Suggest explicit manual next steps with suggest_workflow without auto-calling tools or models.
• Inspect model routing with list_model_routes so bare model names and endpoint-backed models are not confused.
• Attach model profile metadata such as cheap, fast, flagship, sleep, or awake for preflight visibility.
• Merge defaults from builtin values, global config, project config, environment variables, and explicit call arguments.

Architecture

Most pieces are swappable. Adapter-specific behavior stays out of core/.

Layer	Contract	Default implementation
ModelBackend	async complete(...)	LiteLLMBackend
KnowledgeProvider	retrieve/list_cases/add_case	YamlKnowledgeProvider
ProjectAdapter	read_context/version/convention + reviewers/knowledge	GenericAdapter, optional domain adapters
ReportRenderer	render(ReviewReport)	Markdown / JSON / SARIF renderers
Stage	process(ctx) -> ctx	retrieve, context, prompt, review, parse, normalize, consensus, score

Adding another project type should usually mean adding a new adapter package, not changing the core pipeline.

Review Pipeline

ReviewDocument
  -> RetrieveStage
  -> ContextStage
  -> PromptStage
  -> ReviewStage      # fan-out across panel x dimensions
  -> ParseStage
  -> NormalizeStage   # canonical finding buckets
  -> ConsensusStage
  -> ScoreStage
  -> ReviewReport

The pipeline is designed to reduce "confident but unsupported" feedback:

• Findings need evidence quotes.
• Knowledge retrieval can inject project gotchas and version-specific cases.
• Reviewer prompts are role-specific.
• Canonical normalization reduces duplicate phrasing across models.
• Calibrated confidence combines model agreement, severity, retrieval hits, and review memory.

External Consultation

consult_problem is for moments when the main assistant is stuck, uncertain, repeatedly debugging the same issue, or needs another expert perspective. It does not execute commands or edit files; it returns structured advice, hypotheses, next experiments, risks, and a recommended plan.

consult_problem(
    problem="FlowField updates occasionally deadlock",
    context="Unity ECS project; double buffering and JobHandle.CombineDependencies were already tried.",
    logs="Occasionally stalls near CompleteDependency()",
    attempts=["double buffering", "combined JobHandle dependencies"],
    mode="architecture",
)

Common modes:

• debugging: root-cause diagnosis.
• architecture: boundaries, state flow, and maintainability.
• performance: latency, throughput, token/API cost.
• simplicity: YAGNI and smaller MVP slices.
• game_design: gameplay and player experience.
• challenge: adversarial challenge to the current thinking.
• planning: task decomposition, risks, and acceptance criteria.

Recommended config:

{
  "consult_panel": ["modelbridge_openai/gpt-5.4-mini"],
  "consult_consultants": ["debugger", "critic"],
  "consult_max_cost_usd": 0.03,
  "consult_max_input_chars": 24000
}

If consult_panel is not configured, consultation falls back to panel. For day-to-day use, keep a cheaper/faster consult panel so one consultation does not expand the full review panel.

consult_problem returns a consultation_id, and each item in individual has a stable advice id. Mark useful or unhelpful advice with Advice Memory:

mark_advice(
    advice_id="consult-abc123-0",
    consultation_id="consult-abc123",
    decision="accepted",
    reason="identified the real race condition",
    outcome="added the suggested minimal reproduction test",
)

decision is one of accepted, rejected, partial, or unknown. The database stores advice metadata and user feedback, not the original prompt, problem text, or full advice body.

Planning

plan_task turns a goal into a structured, reviewable implementation plan. It is intentionally a thin Planner MVP: it does not execute commands, does not edit files, and does not run a multi-model debate. It tries the configured model panel in order and returns the first parseable plan.

plan_task(
    goal="Add a Planner MVP to BrainRegion",
    context="Python MCP server with existing consult_problem and review_plan tools.",
    constraints=[
        "Do not auto-execute tasks.",
        "Reuse existing budget and input guardrails.",
    ],
    success_criteria=[
        "The MCP tool returns milestones, tasks, risks, acceptance criteria, and tests.",
        "Unit tests cover parsing and routing.",
    ],
)

Recommended flow:

Goal -> plan_task -> review_plan -> implement -> review_code -> mark_finding / mark_advice

Optional config:

{
  "planner_panel": ["modelbridge_openai/gpt-5.4-mini"],
  "planner_max_cost_usd": 0.03,
  "planner_max_input_chars": 24000
}

If planner_panel is not configured, planning falls back to consult_panel, then panel.

Brain Regions

route_regions is the first small step toward region-based context scheduling. It is deliberately local and deterministic: it does not call models, read memory, or trigger review/consult/planner tools. It only ranks static region definitions by explicit triggers and returns an activation trace.

route_regions(
    goal="Optimize a Unity ECS FlowField system that allocates too much memory",
    files={
        "Assets/Scripts/FlowFieldSystem.cs": "...",
    },
    top_k=3,
)

Example result shape:

{
  "selected": [
    {"id": "unity_ecs", "score": 4, "matched_triggers": [...]},
    {"id": "performance", "score": 4, "matched_triggers": [...]}
  ],
  "trace": {
    "strategy": "deterministic_keyword_v1",
    "input": {"file_contents_used": false}
  }
}

Built-in regions currently include planning, review, debugging, performance, security, memory, research, and unity_ecs. This tool is advisory; future schedulers must explicitly decide whether to consume its result.

Workflow Suggestions

suggest_workflow builds on route_regions and returns explicit next tool-call suggestions for the main assistant or user to approve. It is still local and deterministic: it does not call models, run review/consult/planner tools, read memory, or edit files.

suggest_workflow(
    goal="Optimize a Unity ECS FlowField system and review the implementation plan",
    files={"Assets/Scripts/FlowFieldSystem.cs": "..."},
)

Example actions may include plan_task, consult_problem, review_document, or review_code. Every action includes requires_user_approval: true, a short reason, suggested arguments, source regions, and trace metadata. This is the safe bridge between region routing and a future Context Scheduler.

Knowledge Base

Review quality depends heavily on project knowledge. Built-in adapter packages may ship seed cases, but the most useful architecture decisions, historical bugs, and team conventions usually live in project-local knowledge files.

Recommended project-local location:

<project-root>/.brain-region/knowledge/*.yaml

The legacy .design-review/knowledge/ directory is still loaded first for compatibility. New .brain-region/knowledge/ cases load after it and can override legacy cases with the same id.

Example:

- id: API-001
  title: "Keep breaking API changes behind a migration path"
  version: {service: ">=2.0"}
  triggers: ["breaking change", "API contract", "migration"]
  category: compatibility
  bad_pattern: "Change a public request or response shape without a versioned fallback or migration notes."
  recommended_pattern: "Add a compatible path, document the migration window, and test old and new clients."
  source: "ADR-014#api-versioning"

Tips:

• Write one concrete, reproducible gotcha per case.
• Put words that will appear in plans or code into triggers.
• Keep sensitive project knowledge local and ignored by git.
• Use list_knowledge to inspect the loaded framework and local cases.

Installation

cd <path-to-brain-region-mcp>
uv sync --extra dev

Run the test suite:

uv run pytest tests/ -q
uv run --extra dev ruff check .

MCP Setup

Register the stdio server in Codex, Claude Code, or another MCP client:

{
  "type": "stdio",
  "command": "uv",
  "args": [
    "run",
    "--directory",
    "<path-to-brain-region-mcp>",
    "brain-region-mcp"
  ],
  "env": {
    "UNITY_PROJECT_ROOT": "<path-to-project-root>",
    "BRAIN_REGION_CONFIG": "<path-to-brain-region-mcp>/brain_region_config.json"
  }
}

UNITY_PROJECT_ROOT is a historical project-root environment variable name. Point it at the project you want reviewed. Keep API keys in .env or process environment variables. Do not commit .env or local brain_region_config.json.

CLI

The brain-region CLI uses the same pipeline as the MCP server. The legacy design-review command is still available as an alias during the rename.

uv run brain-region plan path/to/plan.md --output markdown
cat plan.md | uv run brain-region plan -
uv run brain-region plan --text "# Plan" --dimensions planner feasibility
uv run brain-region code src/a.py src/b.py --output sarif --output-file review.sarif
uv run brain-region doc docs/rfc.md --type rfc --output markdown

Common options:

• --panel: model list or endpoint shortcuts.
• --dimensions: reviewer dimensions.
• --adapter: auto, generic, or another installed domain adapter.
• --retrieve-top-k: number of knowledge cases to retrieve.
• --effort: reasoning/thinking effort where supported.
• --max-cost-usd: preflight budget cap.
• --timeout: per-model timeout.

Configuration

Defaults are resolved in this order:

builtin < global config < project config < env < explicit tool args

See:

• Config precedence
• Endpoint configuration

Typical local config path:

<path-to-brain-region-mcp>/brain_region_config.json

brain_region_config.json can hold defaults such as:

• panel
• dimensions
• retrieve_top_k
• timeout
• normalizer_model
• effort
• max_cost_usd
• endpoints
• model_profiles
• privacy_policy
• context_modes

Custom Gateway Endpoints

Use endpoints for OpenAI-compatible or Anthropic-compatible gateways such as New API, one-api, OpenRouter-style proxies, or internal model bridges. Use one endpoint per wire protocol.

{
  "endpoints": {
    "modelbridge_openai": {
      "provider": "openai",
      "base_url": "https://www.modelbridge.cloud/v1",
      "api_key_env": "MODEBRIDGE_API_KEY",
      "models": ["gpt-5.5", "gpt-5.4-mini"]
    },
    "modelbridge_anthropic": {
      "provider": "anthropic",
      "base_url": "https://www.modelbridge.cloud",
      "api_key_env": "MODEBRIDGE_API_KEY",
      "models": ["claude-haiku-4-5", "claude-opus-4-8"]
    }
  },
  "panel": ["modelbridge_openai/gpt-5.5", "modelbridge_anthropic/claude-opus-4-8"]
}

Panel shortcuts:

• "endpoints" expands every declared model under every endpoint.
• "endpoint_id" expands every model under one endpoint.
• "endpoint_id/model" runs one model through one endpoint.
• Native LiteLLM strings such as "gpt-4o" or "deepseek/deepseek-chat" bypass endpoint config and use provider env vars.

For example, "claude-opus-4-8" is a bare official-provider route and usually needs ANTHROPIC_API_KEY, while "modelbridge_anthropic/claude-opus-4-8" uses the configured gateway and its MODEBRIDGE_API_KEY. Run list_model_routes when you want to inspect the exact route before spending tokens.

Model profile metadata is optional and descriptive. It is shown in list_model_routes and tool routing metadata, but does not automatically select models yet:

{
  "model_profiles": {
    "modelbridge_openai/gpt-5.4-mini": {
      "activation_role": "sleep",
      "tier": "economy",
      "cost": "low",
      "latency": "fast",
      "tags": ["cheap", "fast"],
      "quality_score": 0.65,
      "cost_score": 0.9,
      "speed_score": 0.85
    },
    "modelbridge_anthropic/claude-opus-4-8": {
      "activation_role": "awake",
      "tier": "flagship",
      "cost": "high",
      "tags": ["deep_reasoning", "architecture"],
      "quality_score": 0.98,
      "cost_score": 0.2
    }
  }
}

Cost And Effort Controls

Two optional controls are available:

• max_cost_usd: preflight cost cap for a review. Jobs are kept in panel order until the estimate would exceed the cap.
• effort: reasoning/thinking intensity for providers that support it. Unsupported providers ignore it.

The report includes estimated budget information and actual usage/cost where the provider returns it.

Privacy Mode

By default, every model in the panel receives the review document. For sensitive plan reviews, privacy_policy can enable a strict mode where a trusted model sees the full document, adversarial reviewers see a redacted summary, and the trusted model later mediates evidence.

{
  "privacy_policy": {
    "policy": "strict",
    "trusted": {"endpoint": "trusted_gateway", "model": "trusted-model", "label": "trusted"},
    "min_coverage": 0.5
  }
}

Strict privacy is most useful for plan review. Code review can lose too much semantic detail after redaction.

Review Memory

Use mark_finding to record whether a finding was useful:

mark_finding(finding_id="gpt-4o-3", decision="accepted", params_hash="...")

Valid decisions are accepted, rejected, and partial. Feedback is stored in the local SQLite review database and is used to calibrate future confidence per (model, dimension).

Output

Reports include:

• consensus: findings all models agreed on.
• majority: findings supported by multiple models.
• individual: one-model findings.
• failed_models: isolated model failures.
• budget, usage, risk, and context_compression metadata.

SARIF output can be uploaded to GitHub Code Scanning or consumed by IDEs.

Project Layout

brainregion/
  server.py              # MCP server entry point
  cli.py                 # brain-region CLI
  core/                  # pipeline, stages, schemas, report models
  adapters/              # generic and optional domain adapters
  providers/             # LLM backends
  knowledge/             # retrieval providers
  privacy/               # privacy policies
  output/                # renderers
tests/                   # pytest coverage
docs/                    # focused docs

Security Notes

• Do not commit .env, .env.local, API keys, generated databases, or local brain_region_config.json files.
• Legacy design_review_config.json files are still supported but should not be committed either.
• Prefer api_key_env over plaintext api_key.
• Generated review databases such as brain_region_reviews.db are local data and should not be used in tests. Legacy design_reviews.db files are still read when present.

License

Apache-2.0