@@ -145,6 +145,10 @@ type chatCompletionFunction struct {
145145 Arguments string `json:"arguments"`
146146 }
147147
148+// OLLAMA-SPECIFIC TYPES
149+// These types are custom to Ollama and should NOT be used by other providers.
150+// They differ from OpenAI standard in structure and field names.
151+
148152 type ollamaChatRequest struct {
149153 Model string `json:"model"`
150154 Messages []ollamaReqMessage `json:"messages"`
@@ -181,6 +185,10 @@ type ollamaReqFuncCall struct {
181185 Arguments string `json:"arguments"`
182186 }
183187
188+// reasoning extracts reasoning content from Ollama response.
189+//
190+// OLLAMA-SPECIFIC: Ollama may return reasoning in either "reasoning" or "reasoning_content" fields.
191+// This is an Ollama extension not present in standard OpenAI Chat Completions API.
184192 func (m chatCompletionMessage) reasoning() string {
185193 if m.Reasoning != "" {
186194 return m.Reasoning
@@ -262,6 +270,10 @@ func (p *OllamaProvider) Stream(ctx context.Context, messages []Message) (<-chan
262270 return ch, nil
263271 }
264272
273+// toOllamaMessages converts provider messages to Ollama's custom request format.
274+//
275+// OLLAMA-SPECIFIC: Uses custom ollamaReqMessage type instead of OpenAI SDK types.
276+// Ollama has its own message format and tool call structure.
265277 func toOllamaMessages(messages []Message) []ollamaReqMessage {
266278 result := make([]ollamaReqMessage, len(messages))
267279 for i, m := range messages {
@@ -325,8 +337,13 @@ func toOllamaTools(tools []Tool) []ollamaReqTool {
325337 }
326338
327339 // mergeConsecutiveSystemMessagesOllama merges consecutive system messages into a single message.
328-// This prevents API errors from providers that don't support multiple system messages,
329-// and reduces context waste by deduplicating repeated system prompts.
340+//
341+// OLLAMA-SPECIFIC BEHAVIOR:
342+// Unlike OpenAI, Ollama allows system messages anywhere in the conversation.
343+// This function merges consecutive system messages IN PLACE without moving them to the start.
344+// This preserves Ollama's flexible system message handling.
345+//
346+// DO NOT use this function for OpenAI-compatible providers - use mergeSystemMessagesOpenAI instead.
330347 func mergeConsecutiveSystemMessagesOllama(messages []ollamaReqMessage) []ollamaReqMessage {
331348 if len(messages) == 0 {
332349 return messages