[4.D.1] OpenAI-compatible LLM adapter (adapters/llm/openai.py)

[frankbria]

Parent

Part of #542 — Multi-provider LLM support

What

Create codeframe/adapters/llm/openai.py implementing the LLMProvider ABC.

A single implementation with a configurable base_url covers the entire OpenAI-compatible ecosystem: OpenAI, Ollama, vLLM, LM Studio, Qwen, GLM, Deepseek, Groq, Together, etc.

Files to create/modify

• Create codeframe/adapters/llm/openai.py — OpenAIProvider(LLMProvider)
• Create tests/adapters/test_llm_openai.py

Implementation notes

• Use openai SDK (pip install openai) — already OpenAI-compatible
• Constructor: OpenAIProvider(api_key, model, base_url=None)
  • base_url=None → OpenAI production
  • base_url="http://localhost:11434/v1" → Ollama
• complete(): translate Message list → openai.chat.completions.create(), return LLMResponse
• stream(): use stream=True, yield LLMResponse chunks
• Tool use: OpenAI uses tool_calls / function format; translate to/from ToolCall / ToolResult from base.py
• Map Anthropic stop reasons (end_turn, tool_use) ↔ OpenAI stop reasons (stop, tool_calls)

Tests

• Unit tests with respx or pytest-httpx mocking the OpenAI endpoint
• Test complete() with and without tools
• Test stream()
• Test base_url override routes to custom endpoint
• Test error handling (rate limit, auth error, model not found)

Acceptance criteria

• OpenAIProvider passes same interface contract as AnthropicProvider
• Works with real OpenAI API key in integration test
• Works with Ollama via base_url override
• Tool use round-trip works (tool call → tool result → final answer)
• All new tests pass, existing tests unaffected

[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

• file:codeframe/adapters/llm/base.py defines LLMProvider (ABC), LLMResponse, Message, ToolCall, ToolResult, and Tool — all the shared types the new adapter must use.
• file:codeframe/adapters/llm/anthropic.py is the reference implementation: lazy-loads its SDK client, converts messages/tools to provider format, parses the response back into LLMResponse, and maps stop reasons.
• openai>=1.12.0 is already declared in pyproject.toml — no new dependency needed.
• file:codeframe/adapters/llm/__init__.py exposes get_provider() and __all__; both must be updated to include OpenAIProvider.
• file:tests/adapters/test_llm.py is the existing test file; the ticket asks for a separate tests/adapters/test_llm_openai.py.

Approach

Mirror AnthropicProvider exactly in structure — lazy client init, _convert_messages, _convert_tools, _parse_response helpers — but translate to/from the OpenAI Chat Completions API format. The base_url constructor parameter routes to any OpenAI-compatible endpoint. Stop-reason mapping (stop ↔ end_turn, tool_calls ↔ tool_use) is the only non-trivial translation.

---

Implementation Steps

1. Create codeframe/adapters/llm/openai.py

Class signature

OpenAIProvider(LLMProvider) with constructor:

OpenAIProvider(api_key=None, model="gpt-4o", base_url=None, model_selector=None, credential_manager=None)

• api_key resolution order: direct param → CredentialManager (using a new CredentialProvider.LLM_OPENAI key if it exists, otherwise skip) → OPENAI_API_KEY env var → raise ValueError with a helpful message matching the Anthropic pattern.
• Store self.model (the default model string) and self.base_url.
• Lazy-load self._client via a client property that calls openai.OpenAI(api_key=..., base_url=...).

complete() method

• Resolve the model: use self.get_model(purpose) when a ModelSelector override is active; fall back to self.model when the selector returns a Claude model name (i.e., when no custom selector was provided). A clean approach: override get_model() to return self.model by default, or accept that callers using ModelSelector will pass OpenAI model names.
• Build kwargs: model, max_tokens, messages (via _convert_messages), temperature.
• If system is provided, prepend a {"role": "system", "content": system} entry to the messages list.
• If tools is provided, add tools=_convert_tools(tools) and tool_choice="auto".
• Call self.client.chat.completions.create(**kwargs).
• Return _parse_response(response).

stream() method

• Same kwargs as complete() but add stream=True.
• Iterate over the streaming response; for each chunk, extract chunk.choices[0].delta.content (guard for None) and yield it.

_convert_messages() helper

Translate the internal list[dict] format (produced by Message.to_dict()) to OpenAI's format:

Internal field	OpenAI format
Simple role/content	{"role": ..., "content": ...}
tool_calls on assistant msg	{"role": "assistant", "content": ..., "tool_calls": [{"id": ..., "type": "function", "function": {"name": ..., "arguments": json.dumps(input)}}]}
tool_results on user msg	One {"role": "tool", "tool_call_id": ..., "content": ...} message per result

Note: OpenAI requires tool results as separate role: "tool" messages, not embedded in a user message. Iterate tool_results and emit one dict per result.

_convert_tools() helper

Map Tool objects to OpenAI's function-calling format:

{"type": "function", "function": {"name": ..., "description": ..., "parameters": tool.input_schema}}

_parse_response() helper

Extract from response.choices[0]:

• message.content → LLMResponse.content (default "" if None)
• message.tool_calls → list of ToolCall(id=tc.id, name=tc.function.name, input=json.loads(tc.function.arguments))
• finish_reason → map to internal stop reason:
  • "stop" → "end_turn"
  • "tool_calls" → "tool_use"
  • others → pass through as-is
• response.usage.prompt_tokens → input_tokens
• response.usage.completion_tokens → output_tokens
• response.model → model

Error handling

Catch openai.AuthenticationError, openai.RateLimitError, openai.NotFoundError and re-raise as ValueError or a domain-appropriate exception, consistent with how AnthropicProvider surfaces errors.

---

2. Update codeframe/adapters/llm/__init__.py

• Import OpenAIProvider from .openai.
• Add "OpenAIProvider" to __all__.
• Extend get_provider() to handle provider_type == "openai", returning OpenAIProvider().

---

3. Create tests/adapters/test_llm_openai.py

Structure mirrors TestAnthropicProvider in file:tests/adapters/test_llm.py. Use unittest.mock.patch (already available in stdlib — no extra dependency) to mock openai.OpenAI and its chat.completions.create return value.

Test classes and cases

Class	Test cases
TestOpenAIProviderInit	No API key raises ValueError; direct api_key param accepted; base_url stored; default model stored
TestOpenAIProviderComplete	Simple text response; response with tool calls; system prompt prepended; temperature > 0 forwarded; stop reason mapping (stop→end_turn, tool_calls→tool_use)
TestOpenAIProviderStream	Yields concatenated content chunks; handles None delta content gracefully
TestOpenAIProviderBaseUrl	Client is constructed with the custom base_url when provided (assert openai.OpenAI called with correct args)
TestOpenAIProviderErrors	AuthenticationError surfaces correctly; RateLimitError surfaces correctly
TestOpenAIProviderToolRoundTrip	Tool call in response → tool result in next message → final answer (multi-turn)

For each test that exercises complete(), build a mock ChatCompletion object with the expected shape (choices[0].message.content, choices[0].message.tool_calls, choices[0].finish_reason, usage.prompt_tokens, usage.completion_tokens, model).

---

4. Sequence of data flow

sequenceDiagram
    participant Caller
    participant OpenAIProvider
    participant openai.OpenAI

    Caller->>OpenAIProvider: complete(messages, purpose, tools, system)
    OpenAIProvider->>OpenAIProvider: _convert_messages(messages)
    OpenAIProvider->>OpenAIProvider: _convert_tools(tools)
    OpenAIProvider->>openai.OpenAI: chat.completions.create(model, messages, tools, ...)
    openai.OpenAI-->>OpenAIProvider: ChatCompletion response
    OpenAIProvider->>OpenAIProvider: _parse_response(response)
    OpenAIProvider-->>Caller: LLMResponse(content, tool_calls, stop_reason, ...)

Loading

Import In IDE

🤖 Prompt for AI Agents

## Observations

- `file:codeframe/adapters/llm/base.py` defines `LLMProvider` (ABC), `LLMResponse`, `Message`, `ToolCall`, `ToolResult`, and `Tool` — all the shared types the new adapter must use.
- `file:codeframe/adapters/llm/anthropic.py` is the reference implementation: lazy-loads its SDK client, converts messages/tools to provider format, parses the response back into `LLMResponse`, and maps stop reasons.
- `openai>=1.12.0` is already declared in `pyproject.toml` — no new dependency needed.
- `file:codeframe/adapters/llm/__init__.py` exposes `get_provider()` and `__all__`; both must be updated to include `OpenAIProvider`.
- `file:tests/adapters/test_llm.py` is the existing test file; the ticket asks for a **separate** `tests/adapters/test_llm_openai.py`.

## Approach

Mirror `AnthropicProvider` exactly in structure — lazy client init, `_convert_messages`, `_convert_tools`, `_parse_response` helpers — but translate to/from the OpenAI Chat Completions API format. The `base_url` constructor parameter routes to any OpenAI-compatible endpoint. Stop-reason mapping (`stop` ↔ `end_turn`, `tool_calls` ↔ `tool_use`) is the only non-trivial translation.

---

## Implementation Steps

### 1. Create `codeframe/adapters/llm/openai.py`

**Class signature**

`OpenAIProvider(LLMProvider)` with constructor:
```
OpenAIProvider(api_key=None, model="gpt-4o", base_url=None, model_selector=None, credential_manager=None)
```

- `api_key` resolution order: direct param → `CredentialManager` (using a new `CredentialProvider.LLM_OPENAI` key if it exists, otherwise skip) → `OPENAI_API_KEY` env var → raise `ValueError` with a helpful message matching the Anthropic pattern.
- Store `self.model` (the default model string) and `self.base_url`.
- Lazy-load `self._client` via a `client` property that calls `openai.OpenAI(api_key=..., base_url=...)`.

**`complete()` method**

- Resolve the model: use `self.get_model(purpose)` when a `ModelSelector` override is active; fall back to `self.model` when the selector returns a Claude model name (i.e., when no custom selector was provided). A clean approach: override `get_model()` to return `self.model` by default, or accept that callers using `ModelSelector` will pass OpenAI model names.
- Build `kwargs`: `model`, `max_tokens`, `messages` (via `_convert_messages`), `temperature`.
- If `system` is provided, prepend a `{"role": "system", "content": system}` entry to the messages list.
- If `tools` is provided, add `tools=_convert_tools(tools)` and `tool_choice="auto"`.
- Call `self.client.chat.completions.create(**kwargs)`.
- Return `_parse_response(response)`.

**`stream()` method**

- Same kwargs as `complete()` but add `stream=True`.
- Iterate over the streaming response; for each chunk, extract `chunk.choices[0].delta.content` (guard for `None`) and `yield` it.

**`_convert_messages()` helper**

Translate the internal `list[dict]` format (produced by `Message.to_dict()`) to OpenAI's format:

| Internal field | OpenAI format |
|---|---|
| Simple `role`/`content` | `{"role": ..., "content": ...}` |
| `tool_calls` on assistant msg | `{"role": "assistant", "content": ..., "tool_calls": [{"id": ..., "type": "function", "function": {"name": ..., "arguments": json.dumps(input)}}]}` |
| `tool_results` on user msg | One `{"role": "tool", "tool_call_id": ..., "content": ...}` message per result |

Note: OpenAI requires tool results as separate `role: "tool"` messages, not embedded in a user message. Iterate `tool_results` and emit one dict per result.

**`_convert_tools()` helper**

Map `Tool` objects to OpenAI's function-calling format:
```
{"type": "function", "function": {"name": ..., "description": ..., "parameters": tool.input_schema}}
```

**`_parse_response()` helper**

Extract from `response.choices[0]`:
- `message.content` → `LLMResponse.content` (default `""` if `None`)
- `message.tool_calls` → list of `ToolCall(id=tc.id, name=tc.function.name, input=json.loads(tc.function.arguments))`
- `finish_reason` → map to internal stop reason:
  - `"stop"` → `"end_turn"`
  - `"tool_calls"` → `"tool_use"`
  - others → pass through as-is
- `response.usage.prompt_tokens` → `input_tokens`
- `response.usage.completion_tokens` → `output_tokens`
- `response.model` → `model`

**Error handling**

Catch `openai.AuthenticationError`, `openai.RateLimitError`, `openai.NotFoundError` and re-raise as `ValueError` or a domain-appropriate exception, consistent with how `AnthropicProvider` surfaces errors.

---

### 2. Update `codeframe/adapters/llm/__init__.py`

- Import `OpenAIProvider` from `.openai`.
- Add `"OpenAIProvider"` to `__all__`.
- Extend `get_provider()` to handle `provider_type == "openai"`, returning `OpenAIProvider()`.

---

### 3. Create `tests/adapters/test_llm_openai.py`

Structure mirrors `TestAnthropicProvider` in `file:tests/adapters/test_llm.py`. Use `unittest.mock.patch` (already available in stdlib — no extra dependency) to mock `openai.OpenAI` and its `chat.completions.create` return value.

**Test classes and cases**

| Class | Test cases |
|---|---|
| `TestOpenAIProviderInit` | No API key raises `ValueError`; direct `api_key` param accepted; `base_url` stored; default model stored |
| `TestOpenAIProviderComplete` | Simple text response; response with tool calls; `system` prompt prepended; `temperature > 0` forwarded; stop reason mapping (`stop`→`end_turn`, `tool_calls`→`tool_use`) |
| `TestOpenAIProviderStream` | Yields concatenated content chunks; handles `None` delta content gracefully |
| `TestOpenAIProviderBaseUrl` | Client is constructed with the custom `base_url` when provided (assert `openai.OpenAI` called with correct args) |
| `TestOpenAIProviderErrors` | `AuthenticationError` surfaces correctly; `RateLimitError` surfaces correctly |
| `TestOpenAIProviderToolRoundTrip` | Tool call in response → tool result in next message → final answer (multi-turn) |

For each test that exercises `complete()`, build a mock `ChatCompletion` object with the expected shape (`choices[0].message.content`, `choices[0].message.tool_calls`, `choices[0].finish_reason`, `usage.prompt_tokens`, `usage.completion_tokens`, `model`).

---

### 4. Sequence of data flow

```mermaid
sequenceDiagram
    participant Caller
    participant OpenAIProvider
    participant openai.OpenAI

    Caller->>OpenAIProvider: complete(messages, purpose, tools, system)
    OpenAIProvider->>OpenAIProvider: _convert_messages(messages)
    OpenAIProvider->>OpenAIProvider: _convert_tools(tools)
    OpenAIProvider->>openai.OpenAI: chat.completions.create(model, messages, tools, ...)
    openai.OpenAI-->>OpenAIProvider: ChatCompletion response
    OpenAIProvider->>OpenAIProvider: _parse_response(response)
    OpenAIProvider-->>Caller: LLMResponse(content, tool_calls, stop_reason, ...)
```

---

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.