# Skill: Configure OpenAI

Use when you want to use OpenAI's GPT or o-series models as your LLM provider.
OpenAI models work out of the box — `OPENAI_API_KEY` is already in `Settings`.

## API Key Setup

```bash
# .env
OPENAI_API_KEY=sk-proj-...
```

`arccrew/config.py` already declares `openai_api_key: str = ""` in `Settings` and exports it
to `os.environ` in `_export_api_keys()`. No `arccrew/config.py` changes needed.

Get your key at: https://platform.openai.com/api-keys

## Model Strings

```bash
AGENT_MODEL=openai/gpt-4o                # Capable, multimodal flagship
AGENT_MODEL=openai/gpt-4o-mini           # Fast and cheap, similar to Haiku
AGENT_MODEL=openai/o3                    # Reasoning model — thinks internally
AGENT_MODEL=openai/o4-mini              # Lightweight reasoning model
```

## Install

```bash
pip install langchain-openai
```

## Model Comparison

### GPT-4o
```
openai/gpt-4o
```
- Balanced capability and speed
- Best for: general-purpose agents, code generation, structured output
- Supports vision (images in tool results)
- Equivalent tier to Claude Sonnet

### GPT-4o-mini
```
openai/gpt-4o-mini
```
- Fast and cheap
- Best for: tool-calling agents, classifiers, verifiers
- Equivalent tier to Claude Haiku — use as a cost-effective default
- Good alternative to Haiku if you have existing OpenAI usage

### o3 (Reasoning Model)
```
openai/o3
```
- Thinks internally before responding (chain-of-thought embedded)
- Best for: tasks requiring deep multi-step reasoning, math, complex planning
- Slower and more expensive than GPT-4o
- Temperature should be set to `1.0` (see below)

### o4-mini
```
openai/o4-mini
```
- Lightweight reasoning model
- Best for: reasoning-needed tasks where o3 is overkill
- Faster and cheaper than o3 with good reasoning quality

## Reasoning Models (o-series) — Special Configuration

OpenAI's reasoning models (o3, o4-mini) have specific requirements:

### Temperature Must Be 1.0

Reasoning models do not support low temperature values. Set in `.env`:

```bash
LLM_TEMPERATURE=1.0
```

If you mix regular and reasoning models, set temperature to 1.0 only for reasoning agents.
This currently requires a code-level override since `llm_temperature` is global. One approach:

```python
# In your agent's __init__, bypass get_model() for this agent
from langchain.chat_models import init_chat_model
self.model = init_chat_model("openai:o3", temperature=1.0, max_tokens=16000)
```

### Reasoning Models Think Internally

The "thinking" happens inside the model — you do not see the reasoning chain in the output.
The final response is the answer. This means:

- `extract_json()` works normally — the response is just the final answer
- The response may be longer and more detailed than GPT-4o for the same prompt
- Tool calling works the same way

### When NOT to Use o-series

- Simple tool-calling agents (web search, file ops) → use gpt-4o-mini instead
- Tasks where speed matters → o-series is noticeably slower
- Tasks with many short sequential calls → the latency compounds

## GPT-4o-mini as Haiku Alternative

If you are already paying for OpenAI and want to minimize API key count:

```bash
# Replace Claude Haiku with GPT-4o-mini
AGENT_MODEL=openai/gpt-4o-mini
```

Both are in the same tier: fast, cheap, good at tool calling, suitable for most agent tasks.

## Per-Agent OpenAI Overrides

Mix OpenAI and Anthropic:

```bash
# .env
AGENT_MODEL=anthropic/claude-haiku-4-5-20251001   # default
ANALYST_MODEL=openai/o3                            # this agent uses o3 reasoning
WRITER_MODEL=openai/gpt-4o                         # this agent uses GPT-4o
```

Add to `arccrew/config.py` Settings:
```python
analyst_model: str = ""
writer_model: str = ""
```

## Azure OpenAI

If you use Azure OpenAI instead of direct OpenAI API:

```bash
# .env
OPENAI_API_KEY=your-azure-api-key
AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com/
AZURE_OPENAI_API_VERSION=2024-02-01
```

Azure uses a different model string format and a different LangChain class. The standard
`init_chat_model("openai/gpt-4o")` will use the direct OpenAI API. For Azure:

```python
from langchain_openai import AzureChatOpenAI

self.model = AzureChatOpenAI(
    azure_deployment="your-deployment-name",
    azure_endpoint=os.environ["AZURE_OPENAI_ENDPOINT"],
    api_key=os.environ["OPENAI_API_KEY"],
    api_version="2024-02-01",
)
```

Use this in `__init__` instead of `get_model()` for Azure-specific agents.

## Verify Configuration

```bash
arccrew check
```

Common errors:
- `AuthenticationError` → wrong or expired `OPENAI_API_KEY`
- `model_not_found` → model name typo, check the model strings above
- `langchain_openai not found` → run `pip install langchain-openai`
