Skip to content

epic: config simplification — unified [[llm.providers]] schema #2134

@bug-ops

Description

@bug-ops

Overview

Unify the LLM configuration schema by replacing 6 separate provider structs and dual orchestrator/router concepts with a single [[llm.providers]] array. Each provider is defined exactly once; routing is a routing field on [llm].

Spec: .local/specs/022-config-simplification/spec.md

Problem

Currently a single Claude provider must be declared in up to 3 places:

  • [llm] top-level fields
  • [llm.cloud] section
  • [llm.orchestrator.providers.claude] entry

orchestrator and router are two separate concepts doing the same thing.

Result

# Before: 35 lines, triplicated model/base_url
[llm]
provider = "orchestrator"
model = "claude-sonnet-4-6"
[llm.cloud]
model = "claude-sonnet-4-6"
max_tokens = 4096
[llm.orchestrator.providers.claude]
type = "claude"
model = "claude-sonnet-4-6"

# After: 18 lines, single source of truth
[llm]
routing = "task"
[llm.routes]
chat = ["claude", "ollama"]
[[llm.providers]]
name = "claude"
type = "claude"
model = "claude-sonnet-4-6"
max_tokens = 4096
default = true
[[llm.providers]]
name = "ollama"
type = "ollama"
model = "qwen3.5:9b"
embedding_model = "qwen3-embedding"
embed = true

Breaking Change

Released as a minor version bump. Old-format configs produce a startup error with --migrate-config hint. All changes documented in CHANGELOG.

Phases

  • Phase 1: New config types (ProviderEntry, RoutingStrategy)
  • Phase 2: Migration tooling (--migrate-config) + startup error for old format
  • Phase 3: Bootstrap unification (single build_provider_from_entry())
  • Phase 4: Env override update (ZEPH_LLM_*)
  • Phase 5: CHANGELOG + minor version release
  • Phase 6: Cleanup — remove old structs

Success Criteria

Metric Target
Provider config structs 1 (ProviderEntry) instead of 6
Bootstrap construction paths 1 instead of 6 parallel
Minimal working config ≤ 8 lines
Tests 6397+ green

Metadata

Metadata

Assignees

No one assigned

    Labels

    breaking-changeIntroduces breaking changesconfigConfiguration file changesenhancementNew feature or requestepicMilestone-level tracking issuellmzeph-llm crate (Ollama, Claude)

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions