[4.D.7] Workspace config support for LLM provider (llm: block in config.yaml)

[frankbria]

Parent

Part of #542 — Multi-provider LLM support

Depends on

#545 (CLI flags), #544 (env var wiring)

What

Allow per-workspace LLM configuration in .codeframe/config.yaml so teams can commit their provider/model choice alongside the project without requiring env vars on every machine.

Target config format

# .codeframe/config.yaml
llm:
  provider: openai
  model: qwen2.5-coder:7b
  base_url: http://localhost:11434/v1  # optional, for local models

  # optional per-purpose overrides (maps to Purpose enum)
  planning_model: gpt-4o
  execution_model: qwen2.5-coder:7b
  generation_model: qwen2.5-coder:1.5b

Priority order (lowest → highest wins)

1. Config file (.codeframe/config.yaml)
2. Env var (CODEFRAME_LLM_PROVIDER, CODEFRAME_LLM_MODEL)
3. CLI flag (--llm-provider, --llm-model)

Files to modify

• codeframe/core/config.py — add LLMConfig dataclass, load from config.yaml
• codeframe/adapters/llm/base.py — extend ModelSelector to read from LLMConfig
• codeframe/core/runtime.py — load workspace config before resolving provider
• tests/core/test_config.py — test config loading and priority order

Notes

• .codeframe/config.yaml already exists for other settings — add llm: as a new top-level key
• base_url in config lets teams point at a shared Ollama instance without env vars
• Config file should be committed to the repo (not gitignored) — document that API keys must still come from env vars, never the config file

Acceptance criteria

• llm: {provider: openai, model: qwen2.5-coder:7b} in config.yaml selects that provider
• CLI flag overrides config file
• Env var overrides config file but is overridden by CLI flag
• base_url in config routes to custom endpoint
• Tests cover priority order (config < env < CLI)
• CLAUDE.md updated with config file documentation

[traycerai]

Warning

Ticket Assist will be discontinued on May 1, 2026. After that date, the feature will no longer be available. We suggest installing the Traycer IDE Extension for continued AI-powered, spec-driven development. Thank you for choosing Traycer!

Plan

Observations

• EnvironmentConfig in file:codeframe/core/config.py is a @dataclass loaded from .codeframe/config.yaml via load_environment_config(). It already handles nested sub-dataclasses (ContextConfig, AgentBudgetConfig, etc.) through from_dict().
• ModelSelector in file:codeframe/adapters/llm/base.py reads per-purpose model overrides from env vars (CODEFRAME_PLANNING_MODEL, etc.) in __post_init__.
• execute_agent() in file:codeframe/core/runtime.py hard-codes get_provider("anthropic") and has no concept of a workspace-level LLM config yet.
• get_provider() in file:codeframe/adapters/llm/__init__.py only accepts "anthropic" or "mock" — no base_url or model override support.
• No CODEFRAME_LLM_PROVIDER / CODEFRAME_LLM_MODEL env vars or --llm-provider / --llm-model CLI flags exist yet (issues [4.D.2] Provider factory + env var wiring (get_provider, ModelSelector) #544 and [4.D.3] CLI flags: --llm-provider and --llm-model on cf work start / batch run #545 are listed as dependencies but not yet merged).
• tests/core/test_config.py does not exist yet.

Approach

Add an LLMConfig dataclass to config.py, wire it into EnvironmentConfig, extend get_provider() to accept model/base_url overrides, and update execute_agent() to resolve the provider using the three-tier priority (config < env < CLI). This keeps all changes within the files the ticket specifies and avoids touching unrelated code.

---

Implementation Steps

1. Add LLMConfig dataclass to file:codeframe/core/config.py

Add a new @dataclass named LLMConfig near the other sub-config dataclasses (ContextConfig, AgentBudgetConfig, etc.):

Field	Type	Default	Notes
provider	Optional[str]	None	e.g. "openai", "anthropic"
model	Optional[str]	None	default model for all purposes
base_url	Optional[str]	None	for local/custom endpoints
planning_model	Optional[str]	None	maps to Purpose.PLANNING
execution_model	Optional[str]	None	maps to Purpose.EXECUTION
generation_model	Optional[str]	None	maps to Purpose.GENERATION

2. Add llm field to EnvironmentConfig

In EnvironmentConfig:

• Add llm: LLMConfig = dataclass_field(default_factory=LLMConfig) as a new field.
• In from_dict(), handle the "llm" key: if present and a dict, construct LLMConfig(**data["llm"]).
• In to_dict() (via asdict()), this is handled automatically since LLMConfig is a dataclass.

3. Extend get_provider() in file:codeframe/adapters/llm/__init__.py

Update the signature to accept optional overrides:

get_provider(provider_type: str = "anthropic", *, model: Optional[str] = None, base_url: Optional[str] = None) -> LLMProvider

• For "anthropic": pass model and base_url through to AnthropicProvider (which may need a base_url parameter added to its __init__ to pass to the Anthropic client's base_url kwarg).
• For "openai": instantiate an OpenAIProvider (if it exists) or raise a clear ValueError directing users to set up the provider.
• For "mock": unchanged.
• If model is provided, construct a ModelSelector with all purpose-model fields set to that model, then pass it to the provider.

4. Update ModelSelector in file:codeframe/adapters/llm/base.py

Add a class method from_llm_config(llm_config: "LLMConfig") -> "ModelSelector" that:

1. Starts with env-var defaults (existing __post_init__ logic).
2. If llm_config.model is set, uses it as the fallback for any purpose not explicitly overridden.
3. Applies per-purpose overrides (planning_model, execution_model, generation_model) from llm_config if set.

This respects the priority: config file values are the lowest tier, so they only fill in when env vars are absent.

The existing __post_init__ already reads env vars with os.getenv(..., DEFAULT_*). The factory method should be called before __post_init__ runs, or the dataclass fields should be pre-populated so __post_init__ skips them (it already does: if not self.planning_model: ...).

5. Update execute_agent() in file:codeframe/core/runtime.py

Add two new parameters to execute_agent():

• llm_provider_name: Optional[str] = None
• llm_model: Optional[str] = None

Provider resolution logic (inside execute_agent, after resolve_engine):

sequenceDiagram
    participant R as runtime.execute_agent
    participant C as load_environment_config
    participant E as os.getenv
    participant P as get_provider

    R->>C: load_environment_config(workspace.repo_path)
    C-->>R: env_config (with llm block or None)
    R->>R: resolved_provider = env_config.llm.provider if env_config else None
    R->>E: CODEFRAME_LLM_PROVIDER (overrides config)
    E-->>R: env_provider (or None)
    R->>R: if env_provider: resolved_provider = env_provider
    R->>R: if llm_provider_name (CLI flag): resolved_provider = llm_provider_name
    R->>R: resolved_provider = resolved_provider or "anthropic"
    R->>P: get_provider(resolved_provider, model=resolved_model, base_url=resolved_base_url)
    P-->>R: provider instance

The same three-tier resolution applies to model and base_url.

Note: env_config is already loaded earlier in execute_agent for hooks — reuse that same env_config object rather than loading it twice.

6. Update CLI work start command in file:codeframe/cli/app.py

Locate the work start command (the one that calls runtime.execute_agent). Add two new Typer options:

• --llm-provider → passed as llm_provider_name to execute_agent
• --llm-model → passed as llm_model to execute_agent

These are the CLI-flag tier (highest priority). They should be Optional[str] with default=None.

7. Create file:tests/core/test_config.py

Following the pattern of existing test files (e.g., tests/core/test_react_agent.py), add a TestLLMConfig class covering:

• LLMConfig defaults to all None fields.
• EnvironmentConfig.from_dict({"llm": {"provider": "openai", "model": "qwen2.5-coder:7b"}}) populates llm.provider and llm.model.
• load_environment_config with a YAML file containing an llm: block returns the correct LLMConfig.
• Priority order: config file value is overridden by env var, which is overridden by CLI flag — test this via the ModelSelector.from_llm_config factory and the env-var resolution logic in execute_agent (mock os.getenv and load_environment_config).

8. Update CLAUDE.md

In the Environment Variables section (around line 539+), add a subsection documenting:

• The llm: block in .codeframe/config.yaml and all supported keys.
• The priority order (config < env var < CLI flag).
• That API keys must never be placed in config.yaml — only provider, model, and base_url.
• Example YAML snippet matching the ticket's target format.

Import In IDE

🤖 Prompt for AI Agents

## Observations

- `EnvironmentConfig` in `file:codeframe/core/config.py` is a `@dataclass` loaded from `.codeframe/config.yaml` via `load_environment_config()`. It already handles nested sub-dataclasses (`ContextConfig`, `AgentBudgetConfig`, etc.) through `from_dict()`.
- `ModelSelector` in `file:codeframe/adapters/llm/base.py` reads per-purpose model overrides from env vars (`CODEFRAME_PLANNING_MODEL`, etc.) in `__post_init__`.
- `execute_agent()` in `file:codeframe/core/runtime.py` hard-codes `get_provider("anthropic")` and has no concept of a workspace-level LLM config yet.
- `get_provider()` in `file:codeframe/adapters/llm/__init__.py` only accepts `"anthropic"` or `"mock"` — no `base_url` or model override support.
- No `CODEFRAME_LLM_PROVIDER` / `CODEFRAME_LLM_MODEL` env vars or `--llm-provider` / `--llm-model` CLI flags exist yet (issues #544 and #545 are listed as dependencies but not yet merged).
- `tests/core/test_config.py` does not exist yet.

## Approach

Add an `LLMConfig` dataclass to `config.py`, wire it into `EnvironmentConfig`, extend `get_provider()` to accept model/base_url overrides, and update `execute_agent()` to resolve the provider using the three-tier priority (config < env < CLI). This keeps all changes within the files the ticket specifies and avoids touching unrelated code.

---

## Implementation Steps

### 1. Add `LLMConfig` dataclass to `file:codeframe/core/config.py`

Add a new `@dataclass` named `LLMConfig` near the other sub-config dataclasses (`ContextConfig`, `AgentBudgetConfig`, etc.):

| Field | Type | Default | Notes |
|---|---|---|---|
| `provider` | `Optional[str]` | `None` | e.g. `"openai"`, `"anthropic"` |
| `model` | `Optional[str]` | `None` | default model for all purposes |
| `base_url` | `Optional[str]` | `None` | for local/custom endpoints |
| `planning_model` | `Optional[str]` | `None` | maps to `Purpose.PLANNING` |
| `execution_model` | `Optional[str]` | `None` | maps to `Purpose.EXECUTION` |
| `generation_model` | `Optional[str]` | `None` | maps to `Purpose.GENERATION` |

### 2. Add `llm` field to `EnvironmentConfig`

In `EnvironmentConfig`:
- Add `llm: LLMConfig = dataclass_field(default_factory=LLMConfig)` as a new field.
- In `from_dict()`, handle the `"llm"` key: if present and a `dict`, construct `LLMConfig(**data["llm"])`.
- In `to_dict()` (via `asdict()`), this is handled automatically since `LLMConfig` is a dataclass.

### 3. Extend `get_provider()` in `file:codeframe/adapters/llm/__init__.py`

Update the signature to accept optional overrides:

```
get_provider(provider_type: str = "anthropic", *, model: Optional[str] = None, base_url: Optional[str] = None) -> LLMProvider
```

- For `"anthropic"`: pass `model` and `base_url` through to `AnthropicProvider` (which may need a `base_url` parameter added to its `__init__` to pass to the `Anthropic` client's `base_url` kwarg).
- For `"openai"`: instantiate an `OpenAIProvider` (if it exists) or raise a clear `ValueError` directing users to set up the provider.
- For `"mock"`: unchanged.
- If `model` is provided, construct a `ModelSelector` with all purpose-model fields set to that model, then pass it to the provider.

### 4. Update `ModelSelector` in `file:codeframe/adapters/llm/base.py`

Add a class method `from_llm_config(llm_config: "LLMConfig") -> "ModelSelector"` that:
1. Starts with env-var defaults (existing `__post_init__` logic).
2. If `llm_config.model` is set, uses it as the fallback for any purpose not explicitly overridden.
3. Applies per-purpose overrides (`planning_model`, `execution_model`, `generation_model`) from `llm_config` if set.

This respects the priority: config file values are the lowest tier, so they only fill in when env vars are absent.

The existing `__post_init__` already reads env vars with `os.getenv(..., DEFAULT_*)`. The factory method should be called **before** `__post_init__` runs, or the dataclass fields should be pre-populated so `__post_init__` skips them (it already does: `if not self.planning_model: ...`).

### 5. Update `execute_agent()` in `file:codeframe/core/runtime.py`

Add two new parameters to `execute_agent()`:
- `llm_provider_name: Optional[str] = None`
- `llm_model: Optional[str] = None`

**Provider resolution logic** (inside `execute_agent`, after `resolve_engine`):

```
sequenceDiagram
    participant R as runtime.execute_agent
    participant C as load_environment_config
    participant E as os.getenv
    participant P as get_provider

    R->>C: load_environment_config(workspace.repo_path)
    C-->>R: env_config (with llm block or None)
    R->>R: resolved_provider = env_config.llm.provider if env_config else None
    R->>E: CODEFRAME_LLM_PROVIDER (overrides config)
    E-->>R: env_provider (or None)
    R->>R: if env_provider: resolved_provider = env_provider
    R->>R: if llm_provider_name (CLI flag): resolved_provider = llm_provider_name
    R->>R: resolved_provider = resolved_provider or "anthropic"
    R->>P: get_provider(resolved_provider, model=resolved_model, base_url=resolved_base_url)
    P-->>R: provider instance
```

The same three-tier resolution applies to `model` and `base_url`.

Note: `env_config` is already loaded earlier in `execute_agent` for hooks — reuse that same `env_config` object rather than loading it twice.

### 6. Update CLI `work start` command in `file:codeframe/cli/app.py`

Locate the `work start` command (the one that calls `runtime.execute_agent`). Add two new Typer options:
- `--llm-provider` → passed as `llm_provider_name` to `execute_agent`
- `--llm-model` → passed as `llm_model` to `execute_agent`

These are the CLI-flag tier (highest priority). They should be `Optional[str]` with `default=None`.

### 7. Create `file:tests/core/test_config.py`

Following the pattern of existing test files (e.g., `tests/core/test_react_agent.py`), add a `TestLLMConfig` class covering:

- `LLMConfig` defaults to all `None` fields.
- `EnvironmentConfig.from_dict({"llm": {"provider": "openai", "model": "qwen2.5-coder:7b"}})` populates `llm.provider` and `llm.model`.
- `load_environment_config` with a YAML file containing an `llm:` block returns the correct `LLMConfig`.
- Priority order: config file value is overridden by env var, which is overridden by CLI flag — test this via the `ModelSelector.from_llm_config` factory and the env-var resolution logic in `execute_agent` (mock `os.getenv` and `load_environment_config`).

### 8. Update `CLAUDE.md`

In the **Environment Variables** section (around line 539+), add a subsection documenting:
- The `llm:` block in `.codeframe/config.yaml` and all supported keys.
- The priority order (config < env var < CLI flag).
- That API keys must never be placed in `config.yaml` — only `provider`, `model`, and `base_url`.
- Example YAML snippet matching the ticket's target format.

---

Execution Information

Branch: main
Commit: f61db8d

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

[coderabbitai]

🔗 Related PRs

#445 - feat(config): unified CODEFRAME.md workflow config (#398) [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!