Ollama Adapter

1. The real problem: changing the base URL is not a production adapter

A provider-neutral gateway can use Ollama safely only when a bounded adapter maps the canonical contract to actual Ollama semantics. One successful OpenAI-compatible call proves a happy path, not complete field support, usage preservation, stream termination, error behavior, provenance, or required capabilities.

2. Keep the domain/provider boundary intact

Domain code should not make business decisions from Ollama-specific fields such as done_reason, prompt_eval_count, or native error shapes. The adapter accepts a canonical request, checks capability, selects a native or compatibility mapping, and returns normalized state while preserving raw evidence separately for audit.

3. Model the native /api/chat surface explicitly

The current native chat contract can accept fields such as model, messages, tools, format, options, stream, think, and keep_alive. Map only fields supported by evidence for the recorded adapter/runtime context, and do not confuse a documented API field with support by every model.

4. Treat OpenAI compatibility as partial

Ollama documents OpenAI-compatible endpoints such as chat completions and responses, while explicitly describing compatibility with parts of the OpenAI API. Mapping therefore remains operation-by-operation and field-by-field rather than assuming full behavioral equivalence.

5. Run the capability map before the endpoint call

For each canonical requirement, record whether the adapter/runtime/model fixture is SUPPORTED, UNSUPPORTED, or UNKNOWN. Unsupported or unknown requirements must not become success through silent field dropping or prompt rewriting; routing receives the typed state.

6. Non-stream and stream have different terminal contracts

For non-stream responses, HTTP status and body can normally be evaluated together. In a stream, valid content chunks may arrive before an error object. The adapter must preserve partial-output provenance, mark the terminal result failed, and prevent downstream code from treating incomplete output as success.

7. Do not invent an HTTP error after streaming starts

Once a response stream has begun, its HTTP status cannot be changed. If an NDJSON stream later contains an error object, normalize the state to something like STREAM_FAILED_AFTER_PARTIAL while retaining the raw error and evidence about prior chunks.

8. Missing usage is not zero usage

A native response may expose prompt/eval token counts and timing metrics, while a compatibility path or another fixture may omit the same evidence. Preserve missing values as UNKNOWN or UNAVAILABLE; zero means a measured zero and is semantically different.

9. Model identity and adapter version are evidence

A mutable model name is insufficient for replay. The conformance record should retain reconstructable model identity, adapter version, API surface, and mapping version so a later reviewer can determine which contract produced the result.

10. Worked example: a valid native response

Suppose canonical chat maps to native /api/chat, the fixture supports JSON-schema output and non-streaming, model identity and adapter version are present, and a clean terminal response includes valid usage/timing evidence. The adapter may issue PASS, but only for that mapping and declared capability set.

11. Worked failure: missing model 404

A 404 should normalize to a state such as MODEL_NOT_FOUND while retaining HTTP status and the raw error payload. The adapter must not reinterpret it as retry success, empty completion, or a model-selection decision; model choice belongs to another lesson boundary.

12. Lab: eight deterministic fixtures

The lab covers native success, compatibility with missing usage, a mid-stream error, an unsupported capability, missing-model 404, incomplete provenance, an unmapped format requirement, and transfer with a new capability. The goal is to implement a state machine, not memorize documentation prose.

13. Decision order: provenance → mapping → capability → terminal/error → usage

First establish which model/adapter/surface is being evaluated. Then verify mapping and capability. Only then evaluate terminal/error state and usage completeness. Convenience or the presence of generated text cannot override an earlier hard gate.

14. Separate conformance evidence from product qualification

This lesson proves that the adapter maps its owned contract and preserves negative states. It does not prove that the hosted model is qualified for a task/locale/risk slice or that local-first routing should choose it. Those decisions require evidence from their owning lessons.

15. Exit checklist and transfer

Before exit, verify explicit field mappings, a versioned capability map, preservation of raw plus normalized errors, no success after mid-stream failure, no zero-filling of missing usage, complete provenance, and UNSUPPORTED for a newly required capability without a mapping. For transfer, add a new requirement and rebuild the decision from evidence.