Tự động đánh giá từng model (provider/model do user cấu hình), chấm điểm phù hợp cho mỗi loại task, rồi định tuyến mỗi lượt chat/agent tới model phù hợp nhất — theo 3 chế độ Off / Auto / Manual bật ngay trên màn hình chat (Cowork, Co4E, AI-Edit).

Module này được xây dựng để hoà vào đúng stack sẵn có của Cowork-Local (PySide6 desktop app), thay vì dựng một service FastAPI riêng:

Bản mô tả gốc (đề bài)	Hiện thực trong app này
Config YAML	Config JSON `~/.cowork_local/config.json` (chuẩn của app) + file assessment riêng
FastAPI REST endpoints	`RoutingService` (Python facade) — các method ánh xạ 1-1 với endpoint
`httpx` async + `asyncio.Semaphore`	Tái dùng `providers/` (requests) + `ThreadPoolExecutor` với semaphore theo từng provider
APScheduler	`QTimer` (giống `core/task_scheduler.py`) — không thêm dependency
`clients.py` (Anthropic/OpenAI)	`AppProbeClient` bọc `AppContext.build_provider_for` (đã có sẵn TLS-trust, retry 429, gateway)

Kiến trúc

core/routing/
  models.py            # Pydantic v2: ModelMetadata, ProbeResult, ModelAssessment,
                       #   SwitchDecision, PendingSwitch, TaskType/Policy/SwitchMode
  store.py             # AssessmentStore: JSON, atomic write (temp+rename), history backup
  metadata.py          # STATIC_METADATA + enrich() (dùng lại core/model_pricing cho giá)
  clients.py           # AppProbeClient (bọc Provider có sẵn) + ProbeClient protocol
  prober.py            # BENCHMARK_TASKS, probe_model(), make_judge(), semaphore/provider
  scorer.py            # compute_fit_score() + POLICY_WEIGHTS
  selector.py          # rank_models()/best_model() — tính lại fit theo policy, không probe lại
  classifier.py        # classify(prompt) -> TaskType (heuristic, fallback LLM tuỳ chọn)
  switch_controller.py # decide() (thuần) + PendingSwitchRegistry (TTL, idempotent)
  orchestrator.py      # check_and_update(): enrich -> probe -> score -> store
  service.py           # RoutingService — facade UI gọi
  scheduler.py         # RoutingScheduler (QTimer): reassess định kỳ + dọn pending hết hạn

Công thức fit score

fit = w_quality * quality
    + w_cost    * 1/(1 + cost)
    + w_latency * 1/(1 + latency_s)

POLICY_WEIGHTS (mỗi hàng cộng = 1.0):

Policy	quality	cost	latency
`quality`	0.80	0.10	0.10
`cost`	0.20	0.70	0.10
`latency`	0.20	0.10	0.70
`balanced`	0.50	0.25	0.25

Probe fail → fit = 0 (model không dùng được thì không bao giờ được chọn).
Giá không rõ → để None, đánh dấu metadata_incomplete=True (không đoán bừa).

Config (trong `config.json`, mục `routing`)

"routing": {
  "switch_mode": "off",            // mặc định toàn cục: "off" | "auto" | "manual"
  "policy": "balanced",            // "quality" | "cost" | "latency" | "balanced"
  "min_score_gain": 0.05,          // chỉ chuyển nếu model mới hơn model hiện tại ≥ ngưỡng này
  "confirm_timeout_sec": 60,       // (manual) hết giờ chờ confirm → giữ model hiện tại
  "reassess_interval_hours": 24,   // lịch reassess; 0 = tắt
  "per_provider_concurrency": 2,   // số probe song song tối đa mỗi provider (chống rate limit)
  "judge_provider": "",            // provider của judge ("" → active provider)
  "judge_model": "",               // model chấm điểm cố định ("" → default rẻ theo provider)
  "candidates": [                  // model muốn đánh giá; rỗng → tự lấy model đang cấu hình
    {"provider": "anthropic", "model_id": "claude-opus-4-8", "tier": "powerful"},
    {"provider": "anthropic", "model_id": "claude-haiku-4-5", "tier": "fast"}
  ],
  "auto_reassess_on_add": true,    // thêm model mới → reassess ngay
  "surface_modes": {               // toggle Off/Auto/Manual của TỪNG màn hình ("" = theo switch_mode)
    "cowork": "", "co4e": "", "ai_edit": ""
  }
}

Kết quả assessment KHÔNG nằm trong config.json mà ở file riêng: ~/.cowork_local/assessments.json (+ backup lịch sử ở assessments_history/<timestamp>.json).

Toggle Off / Auto / Manual (trên màn hình chat)

Mỗi màn hình chat có một toggle nhỏ cạnh ô chọn model:

Off — tắt định tuyến, luôn dùng model đang chọn.
Auto — tự động chuyển sang model phù hợp nhất (nếu gain ≥ min_score_gain), chạy luôn, hiện dòng thông báo ↪ Auto-routed to ….
Manual — hiện hộp thoại xác nhận (có đếm ngược confirm_timeout_sec); user đồng ý mới chuyển, từ chối / hết giờ thì giữ model hiện tại.

Toggle được lưu riêng cho từng màn hình (surface_modes) và ghi đè switch_mode toàn cục.

Logical API (RoutingService)

Method	Tương đương REST trong đề bài
`reassess(policy=None)` / `reassess_background()`	`POST /models/reassess`
`best_for(task_type, policy)`	`GET /models/best`
`status()` / `assessments()`	`GET /models/assessments`
`add_candidate(provider, model_id, tier)`	`POST /models/add` (tự trigger reassess)
`route(surface, prompt, provider, model)`	phần quyết định của `POST /task/execute`
`create_pending()` / `resolve_pending(id, approve, run)`	`POST /task/confirm-switch` (idempotent)
`get_routing_config()` / `update_routing_config(**)`	`GET`/`PATCH /routing/config`

Bảo mật & chi phí

API key đọc từ env (qua api_key_env của provider) — không ghi key vào config/log.
Probe tốn tiền → chỉ chạy theo lịch / khi thêm model / khi bấm "Reassess now". Mỗi lần reassess ghi log số lượng API call.
Idempotent — reassess ổn định (chỉ latency dao động ~µs, dưới xa min_score_gain); ghi atomic nên ngắt giữa chừng không hỏng config.
Không gọi API thật trong test — clients.py/judge() được mock hoàn toàn.

Chạy test

# từ thư mục cha của package (…/cowork_local_20260722)
python -m pytest cowork_local/tests/routing/ -q

Bao phủ: scorer, store (atomic + history), selector, switch_controller (Auto/Manual/Off, timeout, idempotent), orchestrator (mock client), classifier, và service (end-to-end reassess → route → confirm).

README.md

Auto Model Assessment & Routing