144 lines
4.6 KiB
Markdown
144 lines
4.6 KiB
Markdown
# Adapter And Repository Internals
|
|
|
|
## Purpose
|
|
|
|
This document describes implemented adapter/repository boundaries and their current behavior.
|
|
|
|
## Adapter Map
|
|
|
|
- `internal/adapter/cli`: CLI command parsing, app wiring, stdout/stderr handling, exit codes.
|
|
- `internal/adapter/http`: HTTP request/response mapping for `POST /v1/runs`.
|
|
- `internal/promptdef`: filesystem prompt-definition repository.
|
|
- `internal/profile`: filesystem execution-profile repository.
|
|
- `internal/artifact`: input artifact reader.
|
|
- `internal/prompt`: Go-template renderer.
|
|
- `internal/llm`: OpenAI-compatible LLM client implementation.
|
|
- `internal/validate`: output validator.
|
|
- `internal/format`: prepared-run formatters for `render` output.
|
|
|
|
## Inputs And Outputs
|
|
|
|
CLI adapter:
|
|
|
|
- Input: process args, filesystem config/assets, environment.
|
|
- Output: exit code, stdout artifact/prepared output, stderr summaries/errors.
|
|
|
|
HTTP adapter:
|
|
|
|
- Input: JSON request body (`runRequestDTO`).
|
|
- Output: JSON success/error body with mapped status codes.
|
|
|
|
Filesystem repositories:
|
|
|
|
- Input: prompt/profile YAML files under configured directories.
|
|
- Output: normalized domain definitions/profiles or typed errors.
|
|
|
|
Artifact reader:
|
|
|
|
- Input: `domain.ArtifactRef`.
|
|
- Output: loaded `domain.Artifact`.
|
|
|
|
LLM adapter:
|
|
|
|
- Input: `domain.GenerateRequest`.
|
|
- Output: `domain.GenerateResponse`.
|
|
|
|
Validator:
|
|
|
|
- Input: artifact body + output contract.
|
|
- Output: validation result or runtime validation error.
|
|
|
|
## Boundaries
|
|
|
|
- Adapters convert external representations to domain requests and back.
|
|
- Use-case decisions remain in `internal/usecase`.
|
|
- External dependency details stay scoped to adapter packages.
|
|
|
|
## Config Fields Used
|
|
|
|
Primary app settings consumed by adapters:
|
|
|
|
- `prompt_dir`
|
|
- `profile_dir`
|
|
- `schema_dir`
|
|
- `server.addr`
|
|
- `defaults.render_format`
|
|
|
|
Execution profile/request settings used through runner:
|
|
|
|
- `endpoint`, `model`, `temperature`, `max_tokens`, `top_p`, `timeout_seconds`, `service_tier`, `api_key_env`, `reasoning_effort`, `extra_params`
|
|
|
|
## External Dependencies
|
|
|
|
- YAML decoding: `gopkg.in/yaml.v3` (strict known-fields mode in config/prompt/profile loaders).
|
|
- JSON Schema validation: `github.com/santhosh-tekuri/jsonschema/v6`.
|
|
- HTTP client/server: Go standard library.
|
|
|
|
## Failure Behavior
|
|
|
|
Strict decoding and input checks:
|
|
|
|
- config/prompt/profile loaders reject unknown YAML fields.
|
|
- prompt/profile repositories scan nested subdirectories recursively.
|
|
- prompt/profile lookup uses YAML `id` values; subdirectory paths are organizational only.
|
|
- duplicate prompt/profile IDs are invalid and fail instead of using first-match behavior.
|
|
- HTTP DTO decoder rejects unknown JSON fields.
|
|
- raw API key payload fields are rejected by strict decoding in profile/http paths.
|
|
|
|
Artifact refs:
|
|
|
|
- Supported reference types: `inline`, `file`.
|
|
- Unsupported types return `ErrUnsupportedRefType`.
|
|
|
|
LLM adapter:
|
|
|
|
- endpoint appends `/chat/completions`.
|
|
- non-2xx responses map to request failure errors.
|
|
- malformed responses (including missing/empty first choice content) are errors.
|
|
|
|
Validator:
|
|
|
|
- `basic`, `json`, `json_schema` content failures return `ValidationFailed` results.
|
|
- schema load/compile/path failures are runtime errors.
|
|
- schema lookup uses explicit `schema_path` values relative to `schema_dir`; it does not recursively search by basename.
|
|
|
|
HTTP error mapping:
|
|
|
|
- maps domain/use-case errors to stable HTTP code + error code/message.
|
|
- avoids returning internal wrapped-cause details in response payload.
|
|
|
|
## CLI Adapter Semantics
|
|
|
|
Implemented commands:
|
|
|
|
- `run`
|
|
- `render`
|
|
- `serve`
|
|
|
|
Behavior highlights:
|
|
|
|
- `run` exit `2` indicates validation failed after generation.
|
|
- `render` does not call the LLM.
|
|
- `serve` exposes HTTP handler only; no built-in auth.
|
|
- `render` supports `--format text|json`; `render` does not expose `--schema-dir`.
|
|
- deprecated aliases `--prompt-id` and `--profile-id` are still accepted.
|
|
|
|
## Tests To Inspect Before Changing
|
|
|
|
- `internal/adapter/cli/run_test.go`
|
|
- `internal/adapter/http/handler_test.go`
|
|
- `internal/promptdef/repository_test.go`
|
|
- `internal/profile/repository_test.go`
|
|
- `internal/artifact/reader_test.go`
|
|
- `internal/prompt/renderer_test.go`
|
|
- `internal/llm/openai_compatible_client_test.go`
|
|
- `internal/validate/standard_validator_test.go`
|
|
- `internal/format/prepared_run_test.go`
|
|
|
|
## Architectural Invariants
|
|
|
|
- Adapter packages do not own runner decision logic.
|
|
- External request/response strictness is part of contract stability.
|
|
- Prepared-render output never includes resolved API key values.
|
|
- Outbound OpenAI-compatible request includes only currently serialized fields (`model`, `messages`, optional `temperature`, `max_tokens`, `top_p`, optional `response_format`).
|