Refresh documentation and policies and simplify releases
This commit is contained in:
@@ -1,119 +1,76 @@
|
||||
# OpenAI-Compatible LLM Integration
|
||||
|
||||
## Scope
|
||||
This document owns the external protocol used by Audita's structured LLM adapter.
|
||||
Settings, inheritance, defaults, and credential supply belong to
|
||||
[configuration](../config.md#llm-settings); implementation and scheduling belong to
|
||||
[LLM runtime internals](../internal/llm-runtime.md).
|
||||
|
||||
This document defines the external LLM endpoint contract Audita currently uses.
|
||||
## Endpoint and Authentication
|
||||
|
||||
It covers:
|
||||
- endpoint and auth expectations;
|
||||
- structured request and response shape;
|
||||
- retry and timeout behavior;
|
||||
- diagnostics and secret redaction.
|
||||
Audita sends an HTTP `POST` to the configured base URL with trailing slashes
|
||||
removed and `/chat/completions` appended. Supply an HTTP or HTTPS base URL that
|
||||
makes this the intended endpoint; the adapter does not require HTTPS in code.
|
||||
Requests have `Content-Type: application/json`. A non-empty configured API key
|
||||
adds `Authorization: Bearer <api_key>`; otherwise that header is omitted.
|
||||
|
||||
For user-facing CLI flags and config keys, see [`docs/cli.md`](../cli.md) and [`docs/config.md`](../config.md).
|
||||
|
||||
## Endpoint Contract
|
||||
|
||||
Audita sends HTTPS `POST` requests to:
|
||||
|
||||
- `<base_url>/chat/completions`
|
||||
|
||||
`base_url` comes from primary or validation LLM config and is required.
|
||||
|
||||
## Authentication Contract
|
||||
|
||||
When an API key is configured, Audita sends:
|
||||
|
||||
- `Authorization: Bearer <api_key>`
|
||||
|
||||
When no API key is configured, the `Authorization` header is omitted.
|
||||
The endpoint must support the configured model and structured JSON-schema
|
||||
responses. Local configuration validation does not probe that support.
|
||||
|
||||
## Request Shape
|
||||
|
||||
Audita sends a chat-completions payload with:
|
||||
- `model`;
|
||||
- `messages` (role/content pairs);
|
||||
- `response_format` using JSON Schema strict mode.
|
||||
|
||||
Representative shape:
|
||||
The payload contains `model`, an array of `messages` with string `role`/`content`,
|
||||
and `response_format`. The structured-output portion has this illustrative shape:
|
||||
|
||||
```json
|
||||
{
|
||||
"model": "example-model",
|
||||
"messages": [
|
||||
{"role": "system", "content": "..."},
|
||||
{"role": "user", "content": "..."}
|
||||
],
|
||||
"response_format": {
|
||||
"type": "json_schema",
|
||||
"json_schema": {
|
||||
"name": "correction_set",
|
||||
"strict": true,
|
||||
"schema": {"type": "object"}
|
||||
}
|
||||
"type": "json_schema",
|
||||
"json_schema": {
|
||||
"name": "correction_set",
|
||||
"strict": true,
|
||||
"schema": {"type": "object"}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Behavioral requirements enforced by Audita:
|
||||
- `model` must resolve to a non-empty value;
|
||||
- each message must have non-empty `role` and `content`;
|
||||
- `response_format.type` is always `json_schema`;
|
||||
- `response_format.json_schema.name` and `schema` must be present;
|
||||
- request schema JSON must be valid JSON.
|
||||
The actual schema is supplied for the call; the fragment above is not a complete
|
||||
request schema. Runtime calls use `correction_set` and `validator_decision_set`
|
||||
identities. The adapter requires a non-empty resolved model, non-empty message
|
||||
roles/content, a schema name, and valid schema JSON. It sends strict mode to the
|
||||
provider; local typed decoding and proposal/decision checks still apply afterward.
|
||||
|
||||
## Response Handling Contract
|
||||
|
||||
Audita expects a successful JSON response with at least one choice and assistant content that can be interpreted as JSON.
|
||||
A successful response must be a JSON envelope with at least one `choices` item.
|
||||
Audita reads the first choice's `message.content`, accepting a non-empty string
|
||||
containing JSON or a non-null raw JSON value that can decode into the expected
|
||||
output type. Empty content, missing choices, and incompatible payloads fail.
|
||||
The adapter also reads optional `model` and token-usage metadata.
|
||||
|
||||
Supported assistant content forms:
|
||||
- string containing JSON;
|
||||
- raw JSON value.
|
||||
|
||||
Audita then decodes the JSON against the expected structured output type.
|
||||
|
||||
Current structured schema identities used by Audita runtime:
|
||||
- `correction_set`
|
||||
- `validator_decision_set`
|
||||
There is no streaming protocol or provider SDK dependency in this integration.
|
||||
Audita uses this chat-completions contract, not other provider API shapes.
|
||||
|
||||
## Retries and Timeouts
|
||||
|
||||
Retry behavior:
|
||||
- default max retries is `3` when unset;
|
||||
- retries apply to retryable transport/decode/server-side errors;
|
||||
- HTTP `429` and `5xx` responses are retryable;
|
||||
- retry stops immediately when context is canceled or deadline expires.
|
||||
The effective adapter retry count is additional attempts after the initial request;
|
||||
see [configuration](../config.md#llm-settings) for the current zero-value behavior.
|
||||
Transport/read errors, malformed response envelopes/content, typed decode failures,
|
||||
HTTP `429`, and server-error responses are retryable. Other non-success HTTP
|
||||
responses and a response missing choices are not retried by the adapter.
|
||||
Cancellation or an expired context stops retrying.
|
||||
|
||||
Timeout behavior:
|
||||
- request timeout is derived from configured LLM timeout settings;
|
||||
- timeout/cancellation propagate through HTTP requests and return nonzero process failures.
|
||||
The configured HTTP timeout applies per request; it is not a whole-process time
|
||||
budget. A parent process can impose its own overall timeout. See
|
||||
[configuration](../config.md#llm-settings) for timeout and retry values and
|
||||
[subprocess guidance](subprocess.md) for parent responsibilities.
|
||||
|
||||
## Error Behavior
|
||||
|
||||
Non-2xx responses fail the request.
|
||||
For non-success responses, error detail comes from provider `error.message`, then
|
||||
a top-level `message`, otherwise the HTTP status and response body. Configured
|
||||
keys are redacted from surfaced errors and LLM diagnostic payloads.
|
||||
|
||||
Error message extraction behavior:
|
||||
- if provider JSON includes `error.message`, Audita surfaces that message;
|
||||
- else if provider JSON includes top-level `message`, Audita surfaces that;
|
||||
- otherwise Audita surfaces status code plus response body text.
|
||||
|
||||
Malformed or incompatible structured responses fail safely and are surfaced as runtime errors or validator/proposal warnings depending on call site.
|
||||
|
||||
## Secret Redaction
|
||||
|
||||
Configured LLM secrets are redacted from:
|
||||
- surfaced adapter/runtime errors;
|
||||
- LLM diagnostics request/response/error artifacts;
|
||||
- effective config/report artifacts that include LLM configuration material.
|
||||
|
||||
Redaction marker:
|
||||
- `[REDACTED]`
|
||||
|
||||
## Compatibility Boundaries
|
||||
|
||||
This integration documentation applies only to the implemented OpenAI-compatible chat completions flow.
|
||||
|
||||
Not part of current behavior:
|
||||
- provider SDK integration;
|
||||
- non-OpenAI-compatible API contracts;
|
||||
- server-side model routing features beyond explicitly configured model/base URL.
|
||||
Malformed structured responses can become section/batch warnings and rejected
|
||||
proposals rather than fatal run errors, depending on the call site. Other adapter
|
||||
failures can terminate processing with partial results. Consult the
|
||||
[report contract](output-files.md#module-outcomes) for those outcomes and
|
||||
[operations](../operations.md#artifact-handling) for handling diagnostic contents.
|
||||
|
||||
Reference in New Issue
Block a user