# zhan-zip/model-switch-optimize architecture

> Architecture diagram of the GitHub repository zhan-zip/model-switch-optimize, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/zhan-zip/model-switch-optimize
- Repository: https://github.com/zhan-zip/model-switch-optimize

## Overview

Model Switch is a standalone model-failover and self-repair manager. A host submits a task through the Python API or CLI; the pipeline uses model-based decisions and a toolbox to choose and call a provider, then records failures, switches models, and tries configuration-ordered mechanical fallback when needed. Separate capabilities cover provider diagnosis and gated repair, onboarding, recovery probes, MCP/tool integration, and run history/statistics. Edges reflect the excerpts, SOURCE INDEX references, and README; several subsystem internals were not sampled, so uncertain wiring is omitted.

Main entry points: [`model_switch/pipeline.py`](https://github.com/zhan-zip/model-switch-optimize/blob/master/model_switch/pipeline.py) (Run pipeline), [`model_switch/tools.py`](https://github.com/zhan-zip/model-switch-optimize/blob/master/model_switch/tools.py) (Toolbox), [`model_switch/switcher.py`](https://github.com/zhan-zip/model-switch-optimize/blob/master/model_switch/switcher.py) (Python API), [`model_switch/manager.py`](https://github.com/zhan-zip/model-switch-optimize/blob/master/model_switch/manager.py) (Decision manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry and integration"]
  node_cli["CLI<br/>[cli.py]"]
  node_api["Python API<br/>[switcher.py]"]
  node_mcp["MCP adapter<br/>[mcp.py]"]
end

subgraph group_runtime["Task runtime"]
  node_pipeline["Run pipeline<br/>[pipeline.py]"]
  node_manager["Decision manager<br/>[manager.py]"]
  node_toolbox["Toolbox<br/>[tools.py]"]
  node_client["Model client<br/>[client.py]"]
  node_registry["Model registry<br/>[model.py]"]
end

subgraph group_recovery["Recovery and setup"]
  node_diagnosis["Provider diagnosis<br/>[diagnose.py]"]
  node_repair["Gated repair<br/>[fix.py]"]
  node_onboarding["Model onboarding<br/>[onboarding.py]"]
  node_probe["Recovery probes<br/>[probe.py]"]
  node_websearch["Web search<br/>[websearch.py]"]
end

subgraph group_state["State and observability"]
  node_probequeue[("Probe queue<br/>[probe.py]")]
  node_prefs["Model preferences<br/>[prefs.py]"]
  node_stats[("Run statistics<br/>[stats.py]")]
  node_history[("Fault history<br/>[history.py]")]
  node_events["Event stream<br/>[events.py]"]
end

subgraph group_foundation["Configuration and safeguards"]
  node_config["Model configuration<br/>[config.py]"]
  node_safety["Secret redaction<br/>[safety.py]"]
end

node_host(("Host / user"))
node_provider{{"Model provider"}}
node_console{{"Provider console"}}
node_mcp_host(("MCP host"))

node_host -->|"runs command"| node_cli
node_host -->|"submits task"| node_api
node_host -->|"uses tools"| node_mcp_host
node_cli -->|"runs task"| node_pipeline
node_api -->|"runs task"| node_pipeline
node_api -->|"exposes dispatch"| node_toolbox
node_mcp_host -->|"requests tools"| node_mcp
node_mcp -->|"uses runtime"| node_api
node_pipeline -->|"requests decisions"| node_manager
node_pipeline -->|"calls models"| node_toolbox
node_pipeline -->|"records faults"| node_history
node_pipeline -->|"queues failures"| node_probequeue
node_pipeline -->|"uses switch preferences"| node_prefs
node_pipeline -->|"records runs"| node_stats
node_pipeline -->|"emits events"| node_events
node_manager -->|"queries models"| node_toolbox
node_manager -->|"uses preferences"| node_prefs
node_manager -->|"uses experience scores"| node_stats
node_manager -->|"emits decisions"| node_events
node_toolbox -->|"reads model status"| node_registry
node_toolbox -->|"calls provider"| node_client
node_client -->|"sends model request"| node_provider
node_toolbox -->|"emits call results"| node_events
node_registry -->|"builds model states"| node_config
node_cli -->|"loads and validates"| node_config
node_api -->|"loads configuration"| node_config
node_probe -->|"tests connectivity"| node_toolbox
node_probe -->|"reads and updates"| node_probequeue
node_cli -->|"runs probes"| node_probe
node_api -->|"exposes probing"| node_probe
node_onboarding -->|"checks connectivity"| node_toolbox
node_onboarding -->|"saves model labels"| node_prefs
node_cli -->|"runs onboarding"| node_onboarding
node_api -->|"exposes diagnosis"| node_diagnosis
node_diagnosis -->|"requests conclusion"| node_manager
node_diagnosis -->|"checks provider"| node_console
node_repair -->|"applies approved fix"| node_console
node_repair -->|"records repair"| node_events
node_toolbox -->|"serves fault history"| node_history
node_websearch -.->|"searches web"| node_provider
node_events -->|"redacts event data"| node_safety
node_client -->|"redacts errors"| node_safety

click node_cli "https://github.com/zhan-zip/model-switch-optimize/blob/master/model_switch/cli.py"
click node_api "https://github.com/zhan-zip/model-switch-optimize/blob/master/model_switch/switcher.py"
click node_mcp "https://github.com/zhan-zip/model-switch-optimize/blob/master/model_switch/mcp.py"
click node_pipeline "https://github.com/zhan-zip/model-switch-optimize/blob/master/model_switch/pipeline.py"
click node_manager "https://github.com/zhan-zip/model-switch-optimize/blob/master/model_switch/manager.py"
click node_toolbox "https://github.com/zhan-zip/model-switch-optimize/blob/master/model_switch/tools.py"
click node_client "https://github.com/zhan-zip/model-switch-optimize/blob/master/model_switch/client.py"
click node_registry "https://github.com/zhan-zip/model-switch-optimize/blob/master/model_switch/model.py"
click node_config "https://github.com/zhan-zip/model-switch-optimize/blob/master/model_switch/config.py"
click node_diagnosis "https://github.com/zhan-zip/model-switch-optimize/blob/master/model_switch/diagnose.py"
click node_repair "https://github.com/zhan-zip/model-switch-optimize/blob/master/model_switch/fix.py"
click node_onboarding "https://github.com/zhan-zip/model-switch-optimize/blob/master/model_switch/onboarding.py"
click node_probe "https://github.com/zhan-zip/model-switch-optimize/blob/master/model_switch/probe.py"
click node_probequeue "https://github.com/zhan-zip/model-switch-optimize/blob/master/model_switch/probe.py"
click node_prefs "https://github.com/zhan-zip/model-switch-optimize/blob/master/model_switch/prefs.py"
click node_stats "https://github.com/zhan-zip/model-switch-optimize/blob/master/model_switch/stats.py"
click node_history "https://github.com/zhan-zip/model-switch-optimize/blob/master/model_switch/history.py"
click node_events "https://github.com/zhan-zip/model-switch-optimize/blob/master/model_switch/events.py"
click node_safety "https://github.com/zhan-zip/model-switch-optimize/blob/master/model_switch/safety.py"
click node_websearch "https://github.com/zhan-zip/model-switch-optimize/blob/master/model_switch/websearch.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_api,node_mcp,node_host toneBlue
class node_pipeline,node_manager,node_toolbox,node_client,node_registry toneAmber
class node_diagnosis,node_repair,node_onboarding,node_probe,node_websearch toneMint
class node_probequeue,node_prefs,node_stats,node_history,node_events toneRose
class node_config,node_safety,node_provider,node_console,node_mcp_host toneIndigo
```

## Components

### Entry and integration

- [CLI](https://github.com/zhan-zip/model-switch-optimize/blob/master/model_switch/cli.py): `model_switch/cli.py`
- [Python API](https://github.com/zhan-zip/model-switch-optimize/blob/master/model_switch/switcher.py): `model_switch/switcher.py`
- [MCP adapter](https://github.com/zhan-zip/model-switch-optimize/blob/master/model_switch/mcp.py): `model_switch/mcp.py`

### Task runtime

- [Run pipeline](https://github.com/zhan-zip/model-switch-optimize/blob/master/model_switch/pipeline.py): `model_switch/pipeline.py`
- [Decision manager](https://github.com/zhan-zip/model-switch-optimize/blob/master/model_switch/manager.py): `model_switch/manager.py`
- [Toolbox](https://github.com/zhan-zip/model-switch-optimize/blob/master/model_switch/tools.py): `model_switch/tools.py`
- [Model client](https://github.com/zhan-zip/model-switch-optimize/blob/master/model_switch/client.py): `model_switch/client.py`
- [Model registry](https://github.com/zhan-zip/model-switch-optimize/blob/master/model_switch/model.py): `model_switch/model.py`

### Recovery and setup

- [Provider diagnosis](https://github.com/zhan-zip/model-switch-optimize/blob/master/model_switch/diagnose.py): `model_switch/diagnose.py`
- [Gated repair](https://github.com/zhan-zip/model-switch-optimize/blob/master/model_switch/fix.py): `model_switch/fix.py`
- [Model onboarding](https://github.com/zhan-zip/model-switch-optimize/blob/master/model_switch/onboarding.py): `model_switch/onboarding.py`
- [Recovery probes](https://github.com/zhan-zip/model-switch-optimize/blob/master/model_switch/probe.py): `model_switch/probe.py`
- [Web search](https://github.com/zhan-zip/model-switch-optimize/blob/master/model_switch/websearch.py): `model_switch/websearch.py`

### State and observability

- [Probe queue](https://github.com/zhan-zip/model-switch-optimize/blob/master/model_switch/probe.py): `model_switch/probe.py`
- [Model preferences](https://github.com/zhan-zip/model-switch-optimize/blob/master/model_switch/prefs.py): `model_switch/prefs.py`
- [Run statistics](https://github.com/zhan-zip/model-switch-optimize/blob/master/model_switch/stats.py): `model_switch/stats.py`
- [Fault history](https://github.com/zhan-zip/model-switch-optimize/blob/master/model_switch/history.py): `model_switch/history.py`
- [Event stream](https://github.com/zhan-zip/model-switch-optimize/blob/master/model_switch/events.py): `model_switch/events.py`

### Configuration and safeguards

- [Model configuration](https://github.com/zhan-zip/model-switch-optimize/blob/master/model_switch/config.py): `model_switch/config.py`
- [Secret redaction](https://github.com/zhan-zip/model-switch-optimize/blob/master/model_switch/safety.py): `model_switch/safety.py`

### Other components

- **Host / user**
- **Model provider**
- **Provider console**
- **MCP host**

## Connections

- Host / user → CLI: runs command (evidence: `README.md`)
- Host / user → Python API: submits task (evidence: `model_switch/switcher.py`)
- Host / user → MCP host: uses tools (evidence: `README.md`)
- CLI → Run pipeline: runs task (evidence: `model_switch/cli.py`)
- Python API → Run pipeline: runs task (evidence: `model_switch/switcher.py`)
- Python API → Toolbox: exposes dispatch (evidence: `model_switch/switcher.py`)
- MCP host → MCP adapter: requests tools (evidence: `README.md`)
- MCP adapter → Python API: uses runtime (evidence: `model_switch/mcp.py`)
- Run pipeline → Decision manager: requests decisions (evidence: `model_switch/pipeline.py`)
- Run pipeline → Toolbox: calls models (evidence: `model_switch/pipeline.py`)
- Run pipeline → Fault history: records faults (evidence: `model_switch/pipeline.py`)
- Run pipeline → Probe queue: queues failures (evidence: `README.md`)
- Run pipeline → Model preferences: uses switch preferences (evidence: `model_switch/pipeline.py`)
- Run pipeline → Run statistics: records runs (evidence: `model_switch/pipeline.py`)
- Run pipeline → Event stream: emits events (evidence: `model_switch/pipeline.py`)
- Decision manager → Toolbox: queries models (evidence: `model_switch/manager.py`)
- Decision manager → Model preferences: uses preferences (evidence: `model_switch/manager.py`)
- Decision manager → Run statistics: uses experience scores (evidence: `model_switch/manager.py`)
- Decision manager → Event stream: emits decisions (evidence: `model_switch/manager.py`)
- Toolbox → Model registry: reads model status (evidence: `model_switch/tools.py`)
- Toolbox → Model client: calls provider (evidence: `model_switch/tools.py`)
- Model client → Model provider: sends model request (evidence: `model_switch/client.py`)
- Toolbox → Event stream: emits call results (evidence: `model_switch/tools.py`)
- Model registry → Model configuration: builds model states (evidence: `model_switch/model.py`)
- CLI → Model configuration: loads and validates (evidence: `model_switch/cli.py`)
- Python API → Model configuration: loads configuration (evidence: `model_switch/switcher.py`)
- Recovery probes → Toolbox: tests connectivity (evidence: `model_switch/probe.py`)
- Recovery probes → Probe queue: reads and updates (evidence: `model_switch/probe.py`)
- CLI → Recovery probes: runs probes (evidence: `model_switch/cli.py`)
- Python API → Recovery probes: exposes probing (evidence: `model_switch/switcher.py`)
- Model onboarding → Toolbox: checks connectivity (evidence: `model_switch/onboarding.py`)
- Model onboarding → Model preferences: saves model labels (evidence: `model_switch/onboarding.py`)
- CLI → Model onboarding: runs onboarding (evidence: `model_switch/cli.py`)
- Python API → Provider diagnosis: exposes diagnosis (evidence: `model_switch/switcher.py`)
- Provider diagnosis → Decision manager: requests conclusion (evidence: `model_switch/diagnose.py`)
- Provider diagnosis → Provider console: checks provider (evidence: `model_switch/diagnose.py`)
- Gated repair → Provider console: applies approved fix (evidence: `model_switch/fix.py`)
- Gated repair → Event stream: records repair (evidence: `model_switch/fix.py`)
- Toolbox → Fault history: serves fault history (evidence: `model_switch/tools.py`)
- Web search → Model provider: searches web
- Event stream → Secret redaction: redacts event data (evidence: `model_switch/events.py`)
- Model client → Secret redaction: redacts errors (evidence: `model_switch/client.py`)