Add integration and artifact contract documentation

docs/integrations/openai-compatible.md

@@ -0,0 +1,128 @@
+# OpenAI-Compatible Structured Output
+
+This document describes the external LLM provider contract implemented by the
+production Notarius LLM client.
+
+## Provider
+
+- Provider key: `openai-compatible`
+- HTTP method: `POST`
+- Endpoint: `<base_url>/chat/completions`
+- Request body: JSON
+- Response mode: chat completions with structured JSON schema output
+
+`base_url` is trimmed of trailing slashes before `/chat/completions` is
+appended. Configure provider settings in [Configuration](../config.md).
+
+## Request
+
+The client sends a JSON object with:
+
+```json
+{
+  "model": "configured-model",
+  "messages": [
+    {
+      "role": "system",
+      "content": "..."
+    },
+    {
+      "role": "user",
+      "content": "..."
+    }
+  ],
+  "response_format": {
+    "type": "json_schema",
+    "json_schema": {
+      "name": "schema_name",
+      "strict": true,
+      "schema": {}
+    }
+  }
+}
+```
+
+Implemented request behavior:
+
+- `model` comes from the structured completion request when set, otherwise from
+  the configured LLM profile.
+- `messages` must be non-empty; each role and content must be non-empty after
+  trimming.
+- `response_format.type` is always `json_schema`.
+- `response_format.json_schema.strict` is always `true`.
+- `response_format.json_schema.name` and `schema` come from the extractor or
+  validator making the call.
+
+If an API key is configured, the client sends:
+
+```text
+Authorization: Bearer <api-key>
+```
+
+The client always sends `Content-Type: application/json`.
+
+## Response
+
+The client expects a JSON response with at least one choice:
+
+```json
+{
+  "model": "provider-model",
+  "choices": [
+    {
+      "message": {
+        "content": "{\"field\":\"value\"}"
+      }
+    }
+  ],
+  "usage": {
+    "prompt_tokens": 10,
+    "completion_tokens": 5,
+    "total_tokens": 15
+  }
+}
+```
+
+`choices[0].message.content` may be either:
+
+- a JSON string whose contents are valid JSON; or
+- raw JSON.
+
+The decoded content is unmarshaled into the caller-provided structured output
+target. If `usage` is present, prompt, completion, and total token counts are
+copied into the completion response.
+
+## Errors And Retries
+
+The client validates base URL, model, response schema name, response schema
+JSON, messages, and output target before or during the call.
+
+Retryable failures:
+
+- HTTP request failure;
+- response body read failure;
+- HTTP `429`;
+- HTTP `5xx`;
+- malformed provider response envelope;
+- missing choices;
+- missing, empty, or invalid assistant JSON content;
+- structured-output decode failure.
+
+Non-retryable provider status codes include non-`429` `4xx` responses.
+
+Provider error bodies are parsed for `error.message` or `message` when present.
+Configured API key values and bearer-token values are redacted from returned
+provider errors.
+
+## Timeouts And Concurrency
+
+The configured profile timeout is applied per provider request when greater
+than zero. Context cancellation is respected.
+
+The production CLI wraps the provider client with the LLM scheduler. Effective
+concurrency is described in [LLM runtime internals](../internal/llm.md).
+
+## Limits
+
+This contract documents only the fields the implemented client sends and reads.
+Provider-specific extensions are ignored unless they affect those fields.