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`