[4.D.4] Refactor worker_agent.py to use LLMProvider abstraction

[frankbria]

Parent

Part of #542 — Multi-provider LLM support

Depends on

#543 (OpenAI adapter), #544 (factory wiring)

What

worker_agent.py currently hardcodes AsyncAnthropic() directly. Replace with the LLMProvider abstraction so any provider can be used.

Current problem

# codeframe/agents/worker_agent.py — today
from anthropic import AsyncAnthropic, AuthenticationError, RateLimitError, APIConnectionError

class WorkerAgent:
    async def execute_task(self, task, model_name="claude-sonnet-4-5"):
        client = AsyncAnthropic(api_key=self.api_key)
        response = await client.messages.create(...)  # Anthropic-only

Target state

# after refactor
from codeframe.adapters.llm.base import LLMProvider, Purpose
from codeframe.adapters.llm import get_provider

class WorkerAgent:
    def __init__(self, ..., llm_provider: LLMProvider | None = None):
        self.llm_provider = llm_provider or get_provider()

    async def execute_task(self, task, ...):
        response = await self.llm_provider.async_complete(...)

Files to modify

• codeframe/agents/worker_agent.py — replace AsyncAnthropic with LLMProvider
• codeframe/adapters/llm/base.py — add async_complete() / async_stream() to LLMProvider ABC if not present
• codeframe/adapters/llm/anthropic.py — implement async_complete() wrapping existing async path
• codeframe/adapters/llm/openai.py — implement async_complete()
• tests/integration/test_worker_agent_integration.py — update fixtures

Notes

• Keep provider constructor param for backwards compat ("anthropic", "openai")
• Error translation: map provider-specific errors (openai.RateLimitError) to a common LLMRateLimitError base exception in base.py so callers don't need to handle per-provider exceptions
• The SUPPORTED_MODELS list and MODEL_PRICING dict should move to provider implementations (each knows its own models/prices)

Acceptance criteria

• WorkerAgent has no import anthropic anywhere
• WorkerAgent(llm_provider=OpenAIProvider(...)) works in tests
• Existing integration tests still pass with Anthropic provider
• New integration test passes with OpenAI provider (or mocked OpenAI)

[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

• worker_agent.py directly imports AsyncAnthropic, AuthenticationError, RateLimitError, and APIConnectionError from anthropic, and instantiates the client inside execute_task. The retry decorator is also typed against Anthropic-specific exceptions.
• LLMProvider in base.py only defines synchronous complete() and stream() — no async_complete() exists yet.
• AnthropicProvider only has a synchronous client (via Anthropic, not AsyncAnthropic).
• get_provider() in __init__.py supports "anthropic" and "mock" — no "openai" branch yet.
• openai>=1.12.0 is already a declared dependency in pyproject.toml, so an OpenAIProvider can be added safely.
• SUPPORTED_MODELS and MODEL_PRICING are module-level constants in worker_agent.py that need to migrate to provider implementations.

Approach

The refactor follows the ticket's target state exactly: add async_complete() to the ABC and both provider implementations, define common LLM exceptions in base.py, wire "openai" into get_provider(), then replace all Anthropic-specific code in WorkerAgent with the provider abstraction. SUPPORTED_MODELS/MODEL_PRICING move to each provider. The provider string constructor param is preserved for backwards compatibility.

---

Implementation Steps

1. Add common LLM exceptions to file:codeframe/adapters/llm/base.py

Add the following exception classes above LLMProvider:

• LLMError(Exception) — base for all LLM errors
• LLMAuthenticationError(LLMError) — maps from provider-specific auth errors
• LLMRateLimitError(LLMError) — maps from provider-specific rate-limit errors
• LLMConnectionError(LLMError) — maps from provider-specific connection errors

2. Add async_complete() abstract method to LLMProvider in file:codeframe/adapters/llm/base.py

Add an @abstractmethod async def async_complete(...) with the same signature as complete() (same parameters: messages, purpose, tools, max_tokens, temperature, system), returning LLMResponse. Also add a default async_stream() that falls back to async_complete() (mirroring how stream() falls back to complete()).

Update typing imports to include AsyncIterator.

3. Implement async_complete() in file:codeframe/adapters/llm/anthropic.py

• Add a separate _async_client property that lazy-loads AsyncAnthropic(api_key=self.api_key) (analogous to the existing synchronous client property).
• Implement async_complete(): build the same kwargs dict as complete(), call await self._async_client.messages.create(**kwargs), parse via the existing _parse_response().
• Wrap Anthropic-specific exceptions (anthropic.AuthenticationError, anthropic.RateLimitError, anthropic.APIConnectionError) and re-raise as the common LLMAuthenticationError, LLMRateLimitError, LLMConnectionError respectively.
• Add SUPPORTED_MODELS and MODEL_PRICING as class-level attributes (or module-level constants) in this file, migrated from worker_agent.py.

4. Create file:codeframe/adapters/llm/openai.py

Model it after AnthropicProvider:

• OpenAIProvider(LLMProvider) with __init__(api_key, model_selector, credential_manager) — reads OPENAI_API_KEY env var as fallback.
• Lazy client property loading openai.OpenAI(api_key=...).
• Lazy _async_client property loading openai.AsyncOpenAI(api_key=...).
• Implement complete() using self.client.chat.completions.create(...), mapping the messages list and tools to OpenAI's format, then parsing the response into LLMResponse.
• Implement async_complete() using await self._async_client.chat.completions.create(...).
• Wrap openai.AuthenticationError → LLMAuthenticationError, openai.RateLimitError → LLMRateLimitError, openai.APIConnectionError → LLMConnectionError.
• Add SUPPORTED_MODELS and MODEL_PRICING class-level attributes for OpenAI models.
• Add _convert_messages() and _convert_tools() helpers for OpenAI's chat format (OpenAI uses function/tool calling format, distinct from Anthropic's).

5. Update file:codeframe/adapters/llm/__init__.py

• Import OpenAIProvider from .openai.
• Import the new exception classes from .base.
• Add "openai" branch to get_provider(): return OpenAIProvider().
• Add OpenAIProvider and all exception classes to __all__.

6. Refactor file:codeframe/agents/worker_agent.py

This is the core change. The sequence of modifications:

a. Remove imports
b. Add provider imports
c. Update __init__
d. Replace _call_llm_with_retry
e. Replace execute_task body
f. Remove SUPPORTED_MODELS / MODEL_PRICING

a. Remove Anthropic-specific imports

Remove the entire from anthropic import (AsyncAnthropic, AuthenticationError, RateLimitError, APIConnectionError) block.

b. Add provider imports

from codeframe.adapters.llm.base import LLMProvider, LLMAuthenticationError, LLMRateLimitError, LLMConnectionError
from codeframe.adapters.llm import get_provider

c. Update __init__

• Add llm_provider: LLMProvider | None = None parameter (keep provider: str for backwards compat).
• In the body: self.llm_provider = llm_provider or get_provider(provider).
• Remove self.model_name (model selection now belongs to the provider via Purpose); or keep it as an optional override that gets passed to async_complete() if callers still pass model_name explicitly.

d. Replace _call_llm_with_retry

• Remove the current method (it takes client: AsyncAnthropic and calls client.messages.create).
• Replace with a new async _call_llm_with_retry(self, messages, system, max_tokens, timeout) that calls await self.llm_provider.async_complete(messages=messages, system=system, max_tokens=max_tokens) and wraps it in asyncio.wait_for(..., timeout=timeout).
• Update the @retry decorator's retry_if_exception_type to use (LLMRateLimitError, LLMConnectionError, TimeoutError) instead of Anthropic-specific types.

e. Replace execute_task body

• Remove the api_key retrieval, AsyncAnthropic instantiation, and Anthropic key format validation (sk-ant- check).
• Remove the SUPPORTED_MODELS validation block (each provider validates its own models).
• Remove MODEL_PRICING cost estimation (delegate to provider, or keep a provider-agnostic fallback using self.llm_provider.get_model(Purpose.EXECUTION) to determine the model name for cost lookup).
• Change the call to _call_llm_with_retry to pass messages and system instead of client.
• Change response parsing: async_complete() returns an LLMResponse, so replace response.content[0].text with llm_response.content, and response.usage.input_tokens / response.usage.output_tokens with llm_response.input_tokens / llm_response.output_tokens.
• Update exception handlers: catch LLMAuthenticationError, LLMRateLimitError, LLMConnectionError instead of Anthropic-specific ones.

f. Remove SUPPORTED_MODELS and MODEL_PRICING module-level constants

These move to provider implementations. Update _estimate_cost() to either accept a pricing dict from the provider or use a safe default if the model is unknown.

7. Update file:tests/integration/test_worker_agent_integration.py

• Change the pytestmark skip condition to check for either ANTHROPIC_API_KEY or OPENAI_API_KEY (or keep Anthropic-only for existing tests).
• Update the agent fixture: remove the provider="anthropic" string arg (or keep it — it still works via get_provider("anthropic")). Optionally add an llm_provider kwarg fixture using AnthropicProvider() directly.
• Remove assertions on result["model"] == "claude-sonnet-4-5" (the model name is now provider-internal); assert on result["model"] being non-empty instead, or assert it starts with "claude-" for Anthropic tests.
• Add a new test class TestOpenAIProvider with a fixture that constructs WorkerAgent(llm_provider=MockProvider(...)) to verify the abstraction works without a real API key.
• Update our_record["model_name"] assertion in TestTokenUsageDatabase similarly.

---

Data flow after refactor

sequenceDiagram
    participant Caller
    participant WorkerAgent
    participant LLMProvider
    participant AnthropicProvider
    participant OpenAIProvider

    Caller->>WorkerAgent: execute_task(task)
    WorkerAgent->>WorkerAgent: _call_llm_with_retry(messages, system, ...)
    WorkerAgent->>LLMProvider: async_complete(messages, purpose, ...)
    alt provider = anthropic
        LLMProvider->>AnthropicProvider: async_complete(...)
        AnthropicProvider-->>LLMProvider: LLMResponse
    else provider = openai
        LLMProvider->>OpenAIProvider: async_complete(...)
        OpenAIProvider-->>LLMProvider: LLMResponse
    end
    LLMProvider-->>WorkerAgent: LLMResponse
    WorkerAgent-->>Caller: {status, output, usage, model}

Loading

Exception mapping

Provider exception	Common exception
anthropic.AuthenticationError	LLMAuthenticationError
anthropic.RateLimitError	LLMRateLimitError
anthropic.APIConnectionError	LLMConnectionError
openai.AuthenticationError	LLMAuthenticationError
openai.RateLimitError	LLMRateLimitError
openai.APIConnectionError	LLMConnectionError

Import In IDE

🤖 Prompt for AI Agents

## Observations

- `worker_agent.py` directly imports `AsyncAnthropic`, `AuthenticationError`, `RateLimitError`, and `APIConnectionError` from `anthropic`, and instantiates the client inside `execute_task`. The retry decorator is also typed against Anthropic-specific exceptions.
- `LLMProvider` in `base.py` only defines synchronous `complete()` and `stream()` — no `async_complete()` exists yet.
- `AnthropicProvider` only has a synchronous `client` (via `Anthropic`, not `AsyncAnthropic`).
- `get_provider()` in `__init__.py` supports `"anthropic"` and `"mock"` — no `"openai"` branch yet.
- `openai>=1.12.0` is already a declared dependency in `pyproject.toml`, so an `OpenAIProvider` can be added safely.
- `SUPPORTED_MODELS` and `MODEL_PRICING` are module-level constants in `worker_agent.py` that need to migrate to provider implementations.

## Approach

The refactor follows the ticket's target state exactly: add `async_complete()` to the ABC and both provider implementations, define common LLM exceptions in `base.py`, wire `"openai"` into `get_provider()`, then replace all Anthropic-specific code in `WorkerAgent` with the provider abstraction. `SUPPORTED_MODELS`/`MODEL_PRICING` move to each provider. The `provider` string constructor param is preserved for backwards compatibility.

---

## Implementation Steps

### 1. Add common LLM exceptions to `file:codeframe/adapters/llm/base.py`

Add the following exception classes above `LLMProvider`:

- `LLMError(Exception)` — base for all LLM errors
- `LLMAuthenticationError(LLMError)` — maps from provider-specific auth errors
- `LLMRateLimitError(LLMError)` — maps from provider-specific rate-limit errors
- `LLMConnectionError(LLMError)` — maps from provider-specific connection errors

### 2. Add `async_complete()` abstract method to `LLMProvider` in `file:codeframe/adapters/llm/base.py`

Add an `@abstractmethod async def async_complete(...)` with the same signature as `complete()` (same parameters: `messages`, `purpose`, `tools`, `max_tokens`, `temperature`, `system`), returning `LLMResponse`. Also add a default `async_stream()` that falls back to `async_complete()` (mirroring how `stream()` falls back to `complete()`).

Update `typing` imports to include `AsyncIterator`.

### 3. Implement `async_complete()` in `file:codeframe/adapters/llm/anthropic.py`

- Add a separate `_async_client` property that lazy-loads `AsyncAnthropic(api_key=self.api_key)` (analogous to the existing synchronous `client` property).
- Implement `async_complete()`: build the same `kwargs` dict as `complete()`, call `await self._async_client.messages.create(**kwargs)`, parse via the existing `_parse_response()`.
- Wrap Anthropic-specific exceptions (`anthropic.AuthenticationError`, `anthropic.RateLimitError`, `anthropic.APIConnectionError`) and re-raise as the common `LLMAuthenticationError`, `LLMRateLimitError`, `LLMConnectionError` respectively.
- Add `SUPPORTED_MODELS` and `MODEL_PRICING` as class-level attributes (or module-level constants) in this file, migrated from `worker_agent.py`.

### 4. Create `file:codeframe/adapters/llm/openai.py`

Model it after `AnthropicProvider`:

- `OpenAIProvider(LLMProvider)` with `__init__(api_key, model_selector, credential_manager)` — reads `OPENAI_API_KEY` env var as fallback.
- Lazy `client` property loading `openai.OpenAI(api_key=...)`.
- Lazy `_async_client` property loading `openai.AsyncOpenAI(api_key=...)`.
- Implement `complete()` using `self.client.chat.completions.create(...)`, mapping the `messages` list and `tools` to OpenAI's format, then parsing the response into `LLMResponse`.
- Implement `async_complete()` using `await self._async_client.chat.completions.create(...)`.
- Wrap `openai.AuthenticationError` → `LLMAuthenticationError`, `openai.RateLimitError` → `LLMRateLimitError`, `openai.APIConnectionError` → `LLMConnectionError`.
- Add `SUPPORTED_MODELS` and `MODEL_PRICING` class-level attributes for OpenAI models.
- Add `_convert_messages()` and `_convert_tools()` helpers for OpenAI's chat format (OpenAI uses `function`/`tool` calling format, distinct from Anthropic's).

### 5. Update `file:codeframe/adapters/llm/__init__.py`

- Import `OpenAIProvider` from `.openai`.
- Import the new exception classes from `.base`.
- Add `"openai"` branch to `get_provider()`: `return OpenAIProvider()`.
- Add `OpenAIProvider` and all exception classes to `__all__`.

### 6. Refactor `file:codeframe/agents/worker_agent.py`

This is the core change. The sequence of modifications:

```
a. Remove imports
b. Add provider imports
c. Update __init__
d. Replace _call_llm_with_retry
e. Replace execute_task body
f. Remove SUPPORTED_MODELS / MODEL_PRICING
```

**a. Remove Anthropic-specific imports**

Remove the entire `from anthropic import (AsyncAnthropic, AuthenticationError, RateLimitError, APIConnectionError)` block.

**b. Add provider imports**

```
from codeframe.adapters.llm.base import LLMProvider, LLMAuthenticationError, LLMRateLimitError, LLMConnectionError
from codeframe.adapters.llm import get_provider
```

**c. Update `__init__`**

- Add `llm_provider: LLMProvider | None = None` parameter (keep `provider: str` for backwards compat).
- In the body: `self.llm_provider = llm_provider or get_provider(provider)`.
- Remove `self.model_name` (model selection now belongs to the provider via `Purpose`); or keep it as an optional override that gets passed to `async_complete()` if callers still pass `model_name` explicitly.

**d. Replace `_call_llm_with_retry`**

- Remove the current method (it takes `client: AsyncAnthropic` and calls `client.messages.create`).
- Replace with a new `async _call_llm_with_retry(self, messages, system, max_tokens, timeout)` that calls `await self.llm_provider.async_complete(messages=messages, system=system, max_tokens=max_tokens)` and wraps it in `asyncio.wait_for(..., timeout=timeout)`.
- Update the `@retry` decorator's `retry_if_exception_type` to use `(LLMRateLimitError, LLMConnectionError, TimeoutError)` instead of Anthropic-specific types.

**e. Replace `execute_task` body**

- Remove the `api_key` retrieval, `AsyncAnthropic` instantiation, and Anthropic key format validation (`sk-ant-` check).
- Remove the `SUPPORTED_MODELS` validation block (each provider validates its own models).
- Remove `MODEL_PRICING` cost estimation (delegate to provider, or keep a provider-agnostic fallback using `self.llm_provider.get_model(Purpose.EXECUTION)` to determine the model name for cost lookup).
- Change the call to `_call_llm_with_retry` to pass `messages` and `system` instead of `client`.
- Change response parsing: `async_complete()` returns an `LLMResponse`, so replace `response.content[0].text` with `llm_response.content`, and `response.usage.input_tokens` / `response.usage.output_tokens` with `llm_response.input_tokens` / `llm_response.output_tokens`.
- Update exception handlers: catch `LLMAuthenticationError`, `LLMRateLimitError`, `LLMConnectionError` instead of Anthropic-specific ones.

**f. Remove `SUPPORTED_MODELS` and `MODEL_PRICING` module-level constants**

These move to provider implementations. Update `_estimate_cost()` to either accept a pricing dict from the provider or use a safe default if the model is unknown.

### 7. Update `file:tests/integration/test_worker_agent_integration.py`

- Change the `pytestmark` skip condition to check for either `ANTHROPIC_API_KEY` or `OPENAI_API_KEY` (or keep Anthropic-only for existing tests).
- Update the `agent` fixture: remove the `provider="anthropic"` string arg (or keep it — it still works via `get_provider("anthropic")`). Optionally add an `llm_provider` kwarg fixture using `AnthropicProvider()` directly.
- Remove assertions on `result["model"] == "claude-sonnet-4-5"` (the model name is now provider-internal); assert on `result["model"]` being non-empty instead, or assert it starts with `"claude-"` for Anthropic tests.
- Add a new test class `TestOpenAIProvider` with a fixture that constructs `WorkerAgent(llm_provider=MockProvider(...))` to verify the abstraction works without a real API key.
- Update `our_record["model_name"]` assertion in `TestTokenUsageDatabase` similarly.

---

## Data flow after refactor

```mermaid
sequenceDiagram
    participant Caller
    participant WorkerAgent
    participant LLMProvider
    participant AnthropicProvider
    participant OpenAIProvider

    Caller->>WorkerAgent: execute_task(task)
    WorkerAgent->>WorkerAgent: _call_llm_with_retry(messages, system, ...)
    WorkerAgent->>LLMProvider: async_complete(messages, purpose, ...)
    alt provider = anthropic
        LLMProvider->>AnthropicProvider: async_complete(...)
        AnthropicProvider-->>LLMProvider: LLMResponse
    else provider = openai
        LLMProvider->>OpenAIProvider: async_complete(...)
        OpenAIProvider-->>LLMProvider: LLMResponse
    end
    LLMProvider-->>WorkerAgent: LLMResponse
    WorkerAgent-->>Caller: {status, output, usage, model}
```

## Exception mapping

| Provider exception | Common exception |
|---|---|
| `anthropic.AuthenticationError` | `LLMAuthenticationError` |
| `anthropic.RateLimitError` | `LLMRateLimitError` |
| `anthropic.APIConnectionError` | `LLMConnectionError` |
| `openai.AuthenticationError` | `LLMAuthenticationError` |
| `openai.RateLimitError` | `LLMRateLimitError` |
| `openai.APIConnectionError` | `LLMConnectionError` |

---

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

#125 - Implement WorkerAgent execute_task method [merged]
#126 - Add token tracking to WorkerAgent execute_task method [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!