Add development policy and internal architecture docs
This commit is contained in:
139
docs/internal/adapters.md
Normal file
139
docs/internal/adapters.md
Normal file
@@ -0,0 +1,139 @@
|
||||
# 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.
|
||||
- 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`, `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.
|
||||
- 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.
|
||||
|
||||
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`).
|
||||
146
docs/internal/runner.md
Normal file
146
docs/internal/runner.md
Normal file
@@ -0,0 +1,146 @@
|
||||
# Runner Internals
|
||||
|
||||
## Purpose
|
||||
|
||||
`internal/usecase.Runner` is the core use case orchestrator for prompt preparation and execution.
|
||||
|
||||
It owns request validation, prompt/profile resolution, runtime-parameter merge, artifact loading, prompt rendering, structured-output setup, LLM invocation, output validation, and result metadata.
|
||||
|
||||
## Inputs And Outputs
|
||||
|
||||
Primary input type:
|
||||
|
||||
- `domain.RunRequest`
|
||||
|
||||
Primary output types:
|
||||
|
||||
- `domain.PreparedRun` from `Prepare`
|
||||
- `domain.RunResult` from `Run`
|
||||
|
||||
LLM boundary types:
|
||||
|
||||
- `domain.GenerateRequest`
|
||||
- `domain.GenerateResponse`
|
||||
|
||||
## Boundaries
|
||||
|
||||
`Runner` coordinates the following interfaces:
|
||||
|
||||
- `promptdef.Repository`
|
||||
- `profile.Repository`
|
||||
- `artifact.Reader`
|
||||
- `prompt.Renderer`
|
||||
- `llm.Client`
|
||||
- `validate.Validator`
|
||||
- optional `usecase.OutputRepairer`
|
||||
|
||||
Transport concerns (CLI flags, HTTP DTO parsing, status-code mapping) stay outside runner.
|
||||
|
||||
## Config Fields Used
|
||||
|
||||
`Runner` does not read app config files directly.
|
||||
|
||||
It receives fully constructed repositories/readers/validators from adapters. Effective behavior depends on adapter wiring, including:
|
||||
|
||||
- prompt/profile directories
|
||||
- schema base directory
|
||||
- selected profile/runtime overrides in request
|
||||
|
||||
## External Adapters Used
|
||||
|
||||
`Runner` works with adapter implementations via interfaces. Current wiring from CLI/HTTP uses:
|
||||
|
||||
- filesystem prompt/profile repositories
|
||||
- composite artifact reader
|
||||
- Go-template prompt renderer
|
||||
- OpenAI-compatible LLM client
|
||||
- standard validator
|
||||
|
||||
## State And Resume Behavior
|
||||
|
||||
`Runner` is stateless across requests.
|
||||
|
||||
- No durable run-state storage.
|
||||
- No built-in resume/skip checkpoints.
|
||||
- Each `Run`/`Prepare` executes from request inputs and current repositories.
|
||||
|
||||
## Failure Behavior
|
||||
|
||||
Key error classes surfaced from `Runner`:
|
||||
|
||||
- `ErrInvalidRequest`: invalid prompt/profile/request/runtime/API-key-env prerequisites.
|
||||
- `ErrProfileLoad`: prompt or profile load failures.
|
||||
- `ErrArtifactLoad`: artifact read failures.
|
||||
- `ErrPromptRender`: template render failures.
|
||||
- `ErrLLMGenerate`: model request failures.
|
||||
- `ErrValidation`: validation runtime failures (including schema load/compile failures).
|
||||
|
||||
Validation content failures are not run errors:
|
||||
|
||||
- `Run` can succeed with `Validation.Status == failed`.
|
||||
- CLI maps this to exit code `2`.
|
||||
- HTTP returns `200` with failed validation details.
|
||||
|
||||
## Prepare Flow
|
||||
|
||||
`Prepare` performs:
|
||||
|
||||
1. validate request basics (prompt ID present).
|
||||
2. load prompt definition by ID/version.
|
||||
3. select profile ID:
|
||||
- explicit request profile ID
|
||||
- prompt `default_profile`
|
||||
- otherwise request error
|
||||
4. load execution profile.
|
||||
5. merge effective runtime target:
|
||||
- built-in execution defaults
|
||||
- selected profile values
|
||||
- request overrides
|
||||
6. verify required `api_key_env` environment variable (name only; value is not returned).
|
||||
7. resolve output contract and structured-output schema payload when `json_schema` mode is active.
|
||||
8. read input artifacts.
|
||||
9. render prompt messages.
|
||||
10. compute prompt/input/render hashes and return `PreparedRun`.
|
||||
|
||||
`Prepare` does not call the LLM.
|
||||
|
||||
## Run Flow
|
||||
|
||||
`Run` performs:
|
||||
|
||||
1. generate run ID.
|
||||
2. call `Prepare`.
|
||||
3. call LLM with prepared messages/effective target/structured-output spec.
|
||||
4. build output artifact content type from output format.
|
||||
5. validate output.
|
||||
6. optionally attempt bounded repair when repairer is injected and contract allows it.
|
||||
7. return `RunResult` with artifact, raw output, validation, hashes, profile/model metadata, usage, and timestamps.
|
||||
|
||||
## Repair Hook Boundary
|
||||
|
||||
Repair attempts occur only when all are true:
|
||||
|
||||
- repairer is injected
|
||||
- `repair_attempts > 0`
|
||||
- validation status is `failed`
|
||||
- validation mode is `json` or `json_schema`
|
||||
|
||||
Current production wiring boundary:
|
||||
|
||||
- CLI and HTTP adapters call `usecase.NewRunner(...)` (no repairer argument).
|
||||
- Therefore normal CLI/HTTP execution does not perform repair attempts today.
|
||||
|
||||
## Tests To Inspect Before Changing
|
||||
|
||||
- `internal/usecase/runner_test.go`
|
||||
- `internal/usecase/integration_test.go`
|
||||
- `internal/adapter/cli/run_test.go`
|
||||
- `internal/adapter/http/handler_test.go`
|
||||
|
||||
## Architectural Invariants
|
||||
|
||||
- `Run` reuses `Prepare`; prepare logic is not duplicated.
|
||||
- Effective API-key environment-variable name may appear; resolved secret value must not.
|
||||
- Structured-output schema document must load before LLM call for `json_schema` mode.
|
||||
- Repair loops are bounded by `repair_attempts` and repairer presence.
|
||||
- Runner stays transport-agnostic.
|
||||
Reference in New Issue
Block a user