Add OpenAI-compatible model client

docs/internal/llm.md

@@ -0,0 +1,53 @@
+# Internal Model Client
+
+## Purpose
+
+This document describes Promptkit's internal model-client implementation. The
+[architecture policy](../policy/architecture.md) owns the library boundary,
+and the
+[OpenAI-compatible chat integration](../integrations/openai-compatible-chat.md)
+owns the observable outbound HTTP contract.
+
+The client is implemented only under `internal/llm`. The root package does not
+yet assemble it into a usable public engine.
+
+## Components And Flow
+
+`Client` is the provider-neutral generation boundary consumed by later
+orchestration. `OpenAICompatibleClient` is the built-in implementation. It
+uses internal domain values for rendered prompts, execution targets,
+structured output, responses, and token usage.
+
+Construction validates the configured base URL and clones any supplied
+`http.Client` so Promptkit can apply its timeout default without mutating the
+caller's client. Generation then:
+
+1. validates request-level timeout and endpoint requirements;
+2. maps the internal request into the OpenAI-compatible chat payload;
+3. validates and merges extra parameters;
+4. resolves authentication;
+5. performs the outbound request under the applicable deadlines; and
+6. decodes the first response choice and token usage.
+
+The implementation has no retry loop, tool-call support, provider catalog,
+inbound HTTP behavior, or durable session store.
+
+## Failure Categories
+
+The package preserves distinct error identities for invalid client
+configuration, invalid generation requests, request execution failures,
+non-success provider statuses, and malformed successful responses. Provider
+response bodies are not included in non-success errors.
+
+Caller cancellation and deadline failures during the outbound request are
+reported as request execution failures. The future runner can classify these
+identities without depending on HTTP status mapping.
+
+## Test Ownership
+
+The
+[OpenAI-compatible client tests](../../internal/llm/openai_compatible_client_test.go)
+own configuration, client cloning, deterministic deadline precedence,
+authentication, request and response mapping, malformed data, error identity,
+cancellation, and response-body suppression. They use local test servers and
+test transports; the default suite makes no live or paid provider requests.

docs/internal/overview.md

@@ -21,10 +21,11 @@ contributor workflow and validation.
 | `internal/prompt` | Renders prompt messages from Go templates with artifact, variable, session, and cache-control data. | [Go-template renderer](../../internal/prompt/go_renderer.go) |
 | `internal/artifact` | Resolves ordinary inline and unrestricted caller-selected file references into copied artifacts with metadata and hashes. | [Internal sources and validation](sources.md) |
 | `internal/validate` | Validates basic, JSON, and JSON Schema output using operating-system filesystem or `fs.FS` schema sources. | [Internal sources and validation](sources.md) |
+| `internal/llm` | Defines the internal generation boundary and implements outbound OpenAI-compatible chat requests, response decoding, authentication, and deadline handling. | [Internal model client](llm.md) |
 
-These packages provide the internal model, source, and rendering foundation.
-Model clients, orchestration, and a usable public engine are not implemented in
-Promptkit yet.
+These packages provide the internal model, source, rendering, validation, and
+model-client foundation. Orchestration and a usable public engine are not
+implemented in Promptkit yet.
 
 ## Maintenance