xonecas.io
60255
Zn

Zoea-Nova / files

Zoea-Nova / documentation / architecture / OPENAI_COMPATIBILITY.md

3.2 KB
1# OpenAI Chat Completions API Compatibility
2
3This document describes how Zoea Nova maintains compatibility with the OpenAI Chat Completions API specification for all OpenAI-compatible providers.
4
5## Architecture Principles
6
71. **OpenAI Compliance First**: All OpenAI-compatible providers (OpenCode Zen, etc.) MUST follow strict OpenAI Chat Completions API spec
82. **Ollama Isolation**: Ollama-specific customizations stay in `ollama.go` and are NOT used by other providers
93. **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
17These 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
25Uses 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
331. System messages MUST be first
342. User and assistant messages should alternate
353. Tool result messages MUST follow assistant messages with tool calls
364. At least one non-system message MUST be present
37
38### Tool Calls
391. Tool calls must have unique IDs
402. Tool results must reference valid tool call IDs
413. Tool arguments must be valid JSON
424. 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```
53internal/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
67To add a new OpenAI-compatible provider:
68
691. Create `internal/provider/<provider>.go`
702. Import and use `openai_common.go` functions:
71   - `toOpenAIMessages()`
72   - `mergeSystemMessagesOpenAI()`
73   - `toOpenAITools()`
743. Use OpenAI SDK types for requests
754. Use `openaiChatResponse` types for responses
765. DO NOT use Ollama-specific code
776. Test against actual OpenAI API if possible
78
79## Testing OpenAI Compliance
80
81All 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
87See `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`