@@ -0,0 +1,92 @@
1+# OpenAI Chat Completions API Compatibility
2+
3+This document describes how Zoea Nova maintains compatibility with the OpenAI Chat Completions API specification for all OpenAI-compatible providers.
4+
5+## Architecture Principles
6+
7+1. **OpenAI Compliance First**: All OpenAI-compatible providers (OpenCode Zen, etc.) MUST follow strict OpenAI Chat Completions API spec
8+2. **Ollama Isolation**: Ollama-specific customizations stay in `ollama.go` and are NOT used by other providers
9+3. **Shared OpenAI Types**: Common OpenAI-compliant code lives in `openai_common.go`
10+
11+## Provider Types
12+
13+### OpenAI-Compatible Providers
14+- **OpenCode Zen**: Strict OpenAI compliance
15+- **Future providers**: Any provider following OpenAI Chat Completions API
16+
17+These providers use:
18+- `openai_common.go` types and functions
19+- `mergeSystemMessagesOpenAI()` for system message handling
20+- OpenAI SDK types (`openai.ChatCompletionRequest`, etc.)
21+
22+### Ollama Provider
23+- **Ollama**: Custom provider with flexible API
24+
25+Uses Ollama-specific code:
26+- Custom types (`ollamaReqMessage`, `chatCompletionResponse`, etc.)
27+- `mergeConsecutiveSystemMessagesOllama()` for flexible system handling
28+- Custom `reasoning()` method for Ollama extensions
29+
30+## OpenAI Chat Completions API Requirements
31+
32+### Message Ordering
33+1. System messages MUST be first
34+2. User and assistant messages should alternate
35+3. Tool result messages MUST follow assistant messages with tool calls
36+4. At least one non-system message MUST be present
37+
38+### Tool Calls
39+1. Tool calls must have unique IDs
40+2. Tool results must reference valid tool call IDs
41+3. Tool arguments must be valid JSON
42+4. Tool results must follow the corresponding tool call message
43+
44+### Validation Rules
45+- Empty tool_call_id → skip message
46+- Orphaned tool results (no matching tool call) → remove message
47+- Invalid JSON in tool arguments → use empty object `{}`
48+- Only system messages → add fallback user message "Begin."
49+
50+## Code Structure
51+
52+```
53+internal/provider/
54+├── openai_common.go # Shared OpenAI-compliant code
55+│ ├── toOpenAIMessages()
56+│ ├── mergeSystemMessagesOpenAI()
57+│ └── toOpenAITools()
58+├── opencode.go # OpenCode Zen (uses openai_common.go)
59+└── ollama.go # Ollama (isolated, custom types)
60+ ├── toOllamaMessages()
61+ ├── mergeConsecutiveSystemMessagesOllama()
62+ └── reasoning() method
63+```
64+
65+## Adding New OpenAI-Compatible Providers
66+
67+To add a new OpenAI-compatible provider:
68+
69+1. Create `internal/provider/<provider>.go`
70+2. Import and use `openai_common.go` functions:
71+ - `toOpenAIMessages()`
72+ - `mergeSystemMessagesOpenAI()`
73+ - `toOpenAITools()`
74+3. Use OpenAI SDK types for requests
75+4. Use `openaiChatResponse` types for responses
76+5. DO NOT use Ollama-specific code
77+6. Test against actual OpenAI API if possible
78+
79+## Testing OpenAI Compliance
80+
81+All OpenAI-compatible providers must pass:
82+- Message ordering validation tests
83+- Tool call/result association tests
84+- System message merging tests
85+- Edge case handling (orphaned tools, malformed data, etc.)
86+
87+See `internal/provider/provider_test.go` for test patterns.
88+
89+## References
90+
91+- [OpenAI Chat Completions API](https://platform.openai.com/docs/api-reference/chat/create)
92+- `documentation/guides/OPENCODE_ZEN_MODELS.md`