[4.D.2] Provider factory + env var wiring (get_provider, ModelSelector)

[frankbria]

Parent

Part of #542 — Multi-provider LLM support

Depends on

#543 — OpenAI adapter must exist first

What

Wire the provider factory and ModelSelector to support OpenAI-compatible providers via environment variables. No CLI changes yet (that is #545).

Files to modify

• codeframe/adapters/llm/__init__.py — extend get_provider()
• codeframe/adapters/llm/base.py — extend ModelSelector defaults
• codeframe/core/runtime.py — read provider from env, pass to get_provider()
• tests/adapters/test_llm.py — extend existing tests

Implementation notes

get_provider() factory:

def get_provider(provider_type: str = "anthropic", **kwargs) -> LLMProvider:
    if provider_type in ("openai", "ollama", "vllm", "compatible"):
        from codeframe.adapters.llm.openai import OpenAIProvider
        return OpenAIProvider(
            api_key=os.environ.get("OPENAI_API_KEY", ""),
            model=kwargs.get("model", os.environ.get("CODEFRAME_LLM_MODEL", "gpt-4o")),
            base_url=os.environ.get("OPENAI_BASE_URL"),
        )
    # existing anthropic + mock paths unchanged

New env vars to document:

CODEFRAME_LLM_PROVIDER=openai      # selects provider (default: anthropic)
CODEFRAME_LLM_MODEL=qwen2.5-coder  # overrides model for all purposes
OPENAI_API_KEY=...                  # required when provider=openai
OPENAI_BASE_URL=http://...          # optional, for local models

ModelSelector defaults: When provider is openai, default model should be gpt-4o (overrideable via CODEFRAME_LLM_MODEL or purpose-specific vars). Existing Anthropic defaults unchanged.

runtime.py: Where get_provider("anthropic") is hardcoded today, read CODEFRAME_LLM_PROVIDER env var instead.

Acceptance criteria

• CODEFRAME_LLM_PROVIDER=openai uv run cf work start <id> --execute uses OpenAI provider
• OPENAI_BASE_URL=http://localhost:11434/v1 routes to Ollama
• No flags set → Anthropic behavior unchanged
• Tests cover all three paths: anthropic, openai, mock

[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

• get_provider() in file:codeframe/adapters/llm/__init__.py currently only handles "anthropic" and "mock" — no os import exists there yet.
• ModelSelector in file:codeframe/adapters/llm/base.py uses Anthropic-specific defaults (claude-sonnet-4, claude-opus-4, etc.) with no concept of a provider-scoped default.
• execute_agent() in file:codeframe/core/runtime.py hardcodes get_provider("anthropic") at line 649 and separately guards on ANTHROPIC_API_KEY for all non-external engines.
• file:codeframe/adapters/llm/openai.py does not yet exist — it is the output of the prerequisite ticket [4.D.1] OpenAI-compatible LLM adapter (adapters/llm/openai.py) #543 and must be present before this ticket's changes compile.
• file:tests/adapters/test_llm.py already has TestGetProvider and TestAnthropicProvider classes to extend.

Approach

Extend the three production files minimally — no new abstractions — then add targeted test cases. The ModelSelector gains an openai-aware default resolution path driven by CODEFRAME_LLM_MODEL. get_provider() gains the OpenAI branch with lazy import. execute_agent() reads CODEFRAME_LLM_PROVIDER instead of the hardcoded string.

---

Implementation Steps

1. file:codeframe/adapters/llm/base.py — OpenAI defaults in ModelSelector

• Add a module-level constant OPENAI_DEFAULT_MODEL = "gpt-4o".

• In ModelSelector.__post_init__, before the existing per-purpose env-var lookups, read CODEFRAME_LLM_MODEL into a local variable (e.g. global_model_override).

• When resolving each purpose field (planning, execution, generation, correction, supervision), use global_model_override as the fallback between the purpose-specific env var and the Anthropic default constant. The priority chain becomes:

  1. Constructor argument (already handled by the if not self.X guard)
  2. Purpose-specific env var (CODEFRAME_PLANNING_MODEL, etc.)
  3. CODEFRAME_LLM_MODEL (new global override)
  4. Existing Anthropic default constant

  This means no Anthropic-specific logic changes — the Anthropic defaults simply become the last resort, and OpenAI users set CODEFRAME_LLM_MODEL=gpt-4o (or any model) to override all purposes at once.

2. file:codeframe/adapters/llm/__init__.py — Extend get_provider()

• Add import os at the top of the module (currently absent).
• Update the docstring of get_provider() to accept **kwargs and document the new provider_type values.
• Change the signature to get_provider(provider_type: str = "anthropic", **kwargs) -> LLMProvider.
• Add an elif branch before the else raise, matching provider_type in ("openai", "ollama", "vllm", "compatible"):
  • Lazily import OpenAIProvider from codeframe.adapters.llm.openai inside the branch.
  • Construct and return OpenAIProvider with:
    • api_key=os.environ.get("OPENAI_API_KEY", "")
    • model=kwargs.get("model", os.environ.get("CODEFRAME_LLM_MODEL", "gpt-4o"))
    • base_url=os.environ.get("OPENAI_BASE_URL") (pass as None when unset)
• Add "OpenAIProvider" to __all__ (import it at module level only if the file exists, otherwise keep the lazy import inside get_provider() to avoid hard dependency at import time — use the lazy-import-only pattern matching the ticket's implementation note).

3. file:codeframe/core/runtime.py — Read provider from env in execute_agent()

• Inside execute_agent(), locate the two lines at ~642–649 that check ANTHROPIC_API_KEY and call get_provider("anthropic").
• Replace the hardcoded "anthropic" string with os.environ.get("CODEFRAME_LLM_PROVIDER", "anthropic") stored in a local variable (e.g. llm_provider_type).
• Update the ANTHROPIC_API_KEY guard: only raise when llm_provider_type == "anthropic" (or more precisely, when not is_external_engine(engine) and llm_provider_type == "anthropic" and the key is absent). OpenAI-compatible providers do not require ANTHROPIC_API_KEY.
• Pass llm_provider_type to get_provider(llm_provider_type).

The flow becomes:

sequenceDiagram
    participant CLI
    participant runtime as execute_agent()
    participant factory as get_provider()
    participant openai as OpenAIProvider
    participant anthropic as AnthropicProvider

    CLI->>runtime: execute_agent(...)
    runtime->>runtime: llm_provider_type = os.getenv("CODEFRAME_LLM_PROVIDER", "anthropic")
    alt provider == "anthropic"
        runtime->>runtime: guard ANTHROPIC_API_KEY
        runtime->>factory: get_provider("anthropic")
        factory->>anthropic: AnthropicProvider()
    else provider in openai/ollama/vllm/compatible
        runtime->>factory: get_provider("openai")
        factory->>openai: OpenAIProvider(api_key, model, base_url)
    end
    runtime->>runtime: continue agent execution with provider

Loading

4. file:tests/adapters/test_llm.py — Extend tests

• TestModelSelector: Add a test test_global_model_override that sets CODEFRAME_LLM_MODEL=custom-global via monkeypatch.setenv, instantiates ModelSelector(), and asserts all five purpose models equal "custom-global". Also verify that a purpose-specific env var (CODEFRAME_PLANNING_MODEL) still takes precedence over the global override.

• TestGetProvider: Add two new test methods:

  • test_get_openai_provider: Use monkeypatch.setenv("OPENAI_API_KEY", "test-key"), call get_provider("openai"), assert the returned instance is OpenAIProvider.
  • test_get_openai_compatible_aliases: Verify that "ollama", "vllm", and "compatible" all return an OpenAIProvider instance (with OPENAI_API_KEY set).
  • test_get_openai_uses_base_url: Set OPENAI_BASE_URL=http://localhost:11434/v1, call get_provider("openai"), assert provider.base_url equals that URL.

• New TestRuntimeProviderSelection class (or extend existing runtime tests if present): Mock get_provider and assert that when CODEFRAME_LLM_PROVIDER=openai is set, execute_agent calls get_provider("openai") rather than "anthropic". Assert the default (no env var) still calls get_provider("anthropic").

Note: OpenAIProvider must exist (from #543) before these tests will pass. The import in test_get_openai_provider should use from codeframe.adapters.llm.openai import OpenAIProvider for the isinstance check.

Import In IDE

🤖 Prompt for AI Agents

## Observations

- `get_provider()` in `file:codeframe/adapters/llm/__init__.py` currently only handles `"anthropic"` and `"mock"` — no `os` import exists there yet.
- `ModelSelector` in `file:codeframe/adapters/llm/base.py` uses Anthropic-specific defaults (`claude-sonnet-4`, `claude-opus-4`, etc.) with no concept of a provider-scoped default.
- `execute_agent()` in `file:codeframe/core/runtime.py` hardcodes `get_provider("anthropic")` at line 649 and separately guards on `ANTHROPIC_API_KEY` for all non-external engines.
- `file:codeframe/adapters/llm/openai.py` does **not yet exist** — it is the output of the prerequisite ticket #543 and must be present before this ticket's changes compile.
- `file:tests/adapters/test_llm.py` already has `TestGetProvider` and `TestAnthropicProvider` classes to extend.

## Approach

Extend the three production files minimally — no new abstractions — then add targeted test cases. The `ModelSelector` gains an `openai`-aware default resolution path driven by `CODEFRAME_LLM_MODEL`. `get_provider()` gains the OpenAI branch with lazy import. `execute_agent()` reads `CODEFRAME_LLM_PROVIDER` instead of the hardcoded string.

---

## Implementation Steps

### 1. `file:codeframe/adapters/llm/base.py` — OpenAI defaults in `ModelSelector`

- Add a module-level constant `OPENAI_DEFAULT_MODEL = "gpt-4o"`.
- In `ModelSelector.__post_init__`, before the existing per-purpose env-var lookups, read `CODEFRAME_LLM_MODEL` into a local variable (e.g. `global_model_override`).
- When resolving each purpose field (planning, execution, generation, correction, supervision), use `global_model_override` as the fallback **between** the purpose-specific env var and the Anthropic default constant. The priority chain becomes:
  1. Constructor argument (already handled by the `if not self.X` guard)
  2. Purpose-specific env var (`CODEFRAME_PLANNING_MODEL`, etc.)
  3. `CODEFRAME_LLM_MODEL` (new global override)
  4. Existing Anthropic default constant

  This means no Anthropic-specific logic changes — the Anthropic defaults simply become the last resort, and OpenAI users set `CODEFRAME_LLM_MODEL=gpt-4o` (or any model) to override all purposes at once.

### 2. `file:codeframe/adapters/llm/__init__.py` — Extend `get_provider()`

- Add `import os` at the top of the module (currently absent).
- Update the docstring of `get_provider()` to accept `**kwargs` and document the new `provider_type` values.
- Change the signature to `get_provider(provider_type: str = "anthropic", **kwargs) -> LLMProvider`.
- Add an `elif` branch before the `else` raise, matching `provider_type in ("openai", "ollama", "vllm", "compatible")`:
  - Lazily import `OpenAIProvider` from `codeframe.adapters.llm.openai` inside the branch.
  - Construct and return `OpenAIProvider` with:
    - `api_key=os.environ.get("OPENAI_API_KEY", "")`
    - `model=kwargs.get("model", os.environ.get("CODEFRAME_LLM_MODEL", "gpt-4o"))`
    - `base_url=os.environ.get("OPENAI_BASE_URL")` (pass as `None` when unset)
- Add `"OpenAIProvider"` to `__all__` (import it at module level only if the file exists, otherwise keep the lazy import inside `get_provider()` to avoid hard dependency at import time — use the lazy-import-only pattern matching the ticket's implementation note).

### 3. `file:codeframe/core/runtime.py` — Read provider from env in `execute_agent()`

- Inside `execute_agent()`, locate the two lines at ~642–649 that check `ANTHROPIC_API_KEY` and call `get_provider("anthropic")`.
- Replace the hardcoded `"anthropic"` string with `os.environ.get("CODEFRAME_LLM_PROVIDER", "anthropic")` stored in a local variable (e.g. `llm_provider_type`).
- Update the `ANTHROPIC_API_KEY` guard: only raise when `llm_provider_type == "anthropic"` (or more precisely, when `not is_external_engine(engine)` **and** `llm_provider_type == "anthropic"` and the key is absent). OpenAI-compatible providers do not require `ANTHROPIC_API_KEY`.
- Pass `llm_provider_type` to `get_provider(llm_provider_type)`.

The flow becomes:

```mermaid
sequenceDiagram
    participant CLI
    participant runtime as execute_agent()
    participant factory as get_provider()
    participant openai as OpenAIProvider
    participant anthropic as AnthropicProvider

    CLI->>runtime: execute_agent(...)
    runtime->>runtime: llm_provider_type = os.getenv("CODEFRAME_LLM_PROVIDER", "anthropic")
    alt provider == "anthropic"
        runtime->>runtime: guard ANTHROPIC_API_KEY
        runtime->>factory: get_provider("anthropic")
        factory->>anthropic: AnthropicProvider()
    else provider in openai/ollama/vllm/compatible
        runtime->>factory: get_provider("openai")
        factory->>openai: OpenAIProvider(api_key, model, base_url)
    end
    runtime->>runtime: continue agent execution with provider
```

### 4. `file:tests/adapters/test_llm.py` — Extend tests

- **`TestModelSelector`**: Add a test `test_global_model_override` that sets `CODEFRAME_LLM_MODEL=custom-global` via `monkeypatch.setenv`, instantiates `ModelSelector()`, and asserts all five purpose models equal `"custom-global"`. Also verify that a purpose-specific env var (`CODEFRAME_PLANNING_MODEL`) still takes precedence over the global override.

- **`TestGetProvider`**: Add two new test methods:
  - `test_get_openai_provider`: Use `monkeypatch.setenv("OPENAI_API_KEY", "test-key")`, call `get_provider("openai")`, assert the returned instance is `OpenAIProvider`.
  - `test_get_openai_compatible_aliases`: Verify that `"ollama"`, `"vllm"`, and `"compatible"` all return an `OpenAIProvider` instance (with `OPENAI_API_KEY` set).
  - `test_get_openai_uses_base_url`: Set `OPENAI_BASE_URL=http://localhost:11434/v1`, call `get_provider("openai")`, assert `provider.base_url` equals that URL.

- **New `TestRuntimeProviderSelection` class** (or extend existing runtime tests if present): Mock `get_provider` and assert that when `CODEFRAME_LLM_PROVIDER=openai` is set, `execute_agent` calls `get_provider("openai")` rather than `"anthropic"`. Assert the default (no env var) still calls `get_provider("anthropic")`.

> **Note:** `OpenAIProvider` must exist (from #543) before these tests will pass. The import in `test_get_openai_provider` should use `from codeframe.adapters.llm.openai import OpenAIProvider` for the `isinstance` check.

---

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.