Add a roadmap and implementation plan for an initial public library package
This commit is contained in:
@@ -2,12 +2,13 @@
|
||||
|
||||
## Purpose
|
||||
|
||||
Project documentation must help four audiences:
|
||||
Project documentation must help five audiences:
|
||||
|
||||
1. users who need to run the application;
|
||||
2. administrators/operators who need to configure and operate it;
|
||||
3. developers who need to understand and change it safely;
|
||||
4. LLM coding agents that need clear scope, boundaries, and invariants.
|
||||
4. LLM coding agents that need clear scope, boundaries, and invariants;
|
||||
5. developers and LLM coding agents integrating this project from another codebase.
|
||||
|
||||
Docs should be accurate, concise, task-oriented, and organized by audience. Prefer links to canonical docs over repetition.
|
||||
|
||||
@@ -42,11 +43,14 @@ Canonical homes:
|
||||
|
||||
- project purpose and quickstart: `README.md`
|
||||
- development principles: `docs/policy/architecture.md`
|
||||
- public HTTP API reference: `docs/api.md`
|
||||
- configuration reference: `docs/config.md`
|
||||
- CLI reference: `docs/cli.md`
|
||||
- operations and recovery: `docs/operations.md`
|
||||
- troubleshooting: `docs/troubleshooting.md`
|
||||
- public API/package consumer guidance: `docs/consumers/`
|
||||
- implemented internals: `docs/internal/`
|
||||
- external protocol, service, and file-format contracts: `docs/integrations/`
|
||||
- future work: `docs/roadmap/`
|
||||
- contributor workflow: `docs/policy/development.md`
|
||||
- copyable examples: `examples/`
|
||||
@@ -106,7 +110,7 @@ Recommended:
|
||||
- `examples/`
|
||||
- `docs/policy/development.md`
|
||||
|
||||
### Modular, staged, service-oriented, or orchestration application
|
||||
### Modular, service-oriented, or orchestration application
|
||||
|
||||
Required:
|
||||
- `docs/cli.md`, if CLI-based
|
||||
@@ -119,6 +123,31 @@ Recommended:
|
||||
- `docs/troubleshooting.md`
|
||||
- validated examples under `examples/`
|
||||
|
||||
### Public HTTP API service
|
||||
|
||||
Required:
|
||||
- `docs/api.md`
|
||||
- `docs/cli.md`, if CLI-based
|
||||
- `docs/config.md`, if config-driven
|
||||
- `docs/operations.md`
|
||||
- `docs/internal/`
|
||||
- `docs/policy/development.md`
|
||||
|
||||
Recommended:
|
||||
- `docs/troubleshooting.md`
|
||||
- `docs/consumers/`, for task-oriented client integration guides
|
||||
- `docs/integrations/`, for upstream/downstream service contracts
|
||||
- validated examples under `examples/`
|
||||
|
||||
### Project with public packages or consumer APIs
|
||||
|
||||
Required:
|
||||
- `docs/consumers/api.md`
|
||||
- one `docs/consumers/pkg-<name>.md` file per public package, if public packages exist
|
||||
|
||||
Recommended:
|
||||
- copyable consumer examples under `examples/`, if practical
|
||||
|
||||
## Required Documents
|
||||
|
||||
### README.md
|
||||
@@ -159,7 +188,35 @@ It should include:
|
||||
- architectural invariants;
|
||||
- explicit non-goals, if useful.
|
||||
|
||||
For small projects, this file may be brief. It may simply state that the project is intentionally narrow, monolithic, and dependency-light.
|
||||
Notably, this file should prescribe a core development *policy* that should remain unchanged as the application evolves. It is not a place for details (e.g., CLI flags) that could change over time.
|
||||
|
||||
The contents of `architecture.md` should be trim and concise. LLMs may be directed to review it routinely via AGENTS.md, CLAUDE.md, or similar.
|
||||
|
||||
### docs/api.md
|
||||
|
||||
**Audience:** external HTTP API consumers, developers, LLM coding agents integrating by HTTP
|
||||
|
||||
Required for projects whose primary public interface is HTTP.
|
||||
|
||||
`docs/api.md` is the canonical public HTTP API contract. It should be normative for external consumers and should not be duplicated by README, operations docs, consumer guides, or integration docs.
|
||||
|
||||
It should include:
|
||||
|
||||
1. base URL conventions;
|
||||
2. authentication and authorization behavior, if implemented;
|
||||
3. response envelope;
|
||||
4. supported media types and content negotiation behavior;
|
||||
5. shared query parameters;
|
||||
6. endpoint reference grouped by route family;
|
||||
7. request parameters and validation rules;
|
||||
8. response fields, units, nullability, and optionality;
|
||||
9. error response shape and status codes;
|
||||
10. pagination, caching, rate-limit, idempotency, and retry behavior, if implemented;
|
||||
11. compact request and response examples.
|
||||
|
||||
It must document only implemented endpoints and behavior. Planned endpoints, proposed fields, future filters, and experimental response shapes belong only under `docs/roadmap/`.
|
||||
|
||||
For HTTP API projects, `docs/consumers/` may provide task-oriented client integration guides, but those guides should link to `docs/api.md` for the authoritative endpoint contract.
|
||||
|
||||
### docs/policy/development.md
|
||||
|
||||
@@ -175,7 +232,7 @@ It should include:
|
||||
- dependency policy;
|
||||
- how to add config fields;
|
||||
- how to add CLI flags;
|
||||
- how to add stages/modules/adapters, if applicable;
|
||||
- how to add modules or adapters, if applicable;
|
||||
- how to update examples;
|
||||
- documentation update expectations.
|
||||
|
||||
@@ -216,7 +273,7 @@ Explain when commands are useful, not just their syntax.
|
||||
|
||||
**Audience:** administrators, operators
|
||||
|
||||
Required for applications that maintain state, support resume behavior, run multiple stages, write durable artifacts, use remote storage, or require recovery procedures.
|
||||
Required for applications that maintain state, support resume behavior, run multi-step workflows, write durable artifacts, use remote storage, or require recovery procedures.
|
||||
|
||||
It should cover:
|
||||
|
||||
@@ -244,11 +301,40 @@ Each entry should include:
|
||||
- safe fix;
|
||||
- relevant links.
|
||||
|
||||
### docs/consumers/
|
||||
|
||||
**Audience:** developers and LLM coding agents integrating this project from another codebase
|
||||
|
||||
Required for projects with public packages, SDKs, client APIs, plugin APIs, or other application-facing integration surfaces.
|
||||
|
||||
This directory describes how an external codebase should consume the project's public API. It should be task-oriented and copyable where useful. It is not the place for internal implementation details or operator procedures.
|
||||
|
||||
For projects whose public API is HTTP, `docs/consumers/` is not required, and it should not duplicate the endpoint reference in `docs/api.md`. If present, it may provide practical integration workflows, client-specific examples, or migration notes that link back to `docs/api.md`.
|
||||
|
||||
`docs/consumers/api.md` should provide the consumer-facing overview and primary implementation workflow. It should include:
|
||||
|
||||
1. intended consumer audience and use cases;
|
||||
2. required inputs supplied by operators or deployment configuration;
|
||||
3. recommended public package or API workflow;
|
||||
4. minimal copyable example;
|
||||
5. consumer responsibilities and boundaries;
|
||||
6. retry, idempotency, or status behavior, if applicable;
|
||||
7. links to package-specific docs and canonical integration contracts.
|
||||
|
||||
Package-specific docs should be named `pkg-<name>.md` and should include:
|
||||
|
||||
1. import path;
|
||||
2. intended use cases;
|
||||
3. primary types and functions needed by consumers;
|
||||
4. minimal examples;
|
||||
5. validation, error, retry, and boundary behavior;
|
||||
6. links to canonical file-format or wire-protocol contracts.
|
||||
|
||||
### docs/internal/
|
||||
|
||||
**Audience:** developers, LLM coding agents
|
||||
|
||||
Required for modular, staged, service-oriented, or orchestration projects.
|
||||
Required for modular, service-oriented, or orchestration projects.
|
||||
|
||||
This directory describes implemented internal components. It is not the roadmap.
|
||||
|
||||
@@ -289,7 +375,9 @@ Roadmap docs should not be confused with current behavior.
|
||||
|
||||
Required for projects that depend on external CLIs, APIs, services, protocols, or file formats where the integration contract is important to maintain.
|
||||
|
||||
This directory contains concise, versioned reference notes for external integration contracts. It should document only the parts of the external system that this project actually uses.
|
||||
This directory contains concise, versioned reference notes for external integration contracts. It should document only the parts of the external system that this project actually uses or exposes.
|
||||
|
||||
For public HTTP API services, `docs/integrations/` should document upstream, downstream, storage, protocol, or runtime contracts that the service depends on or bridges. It should not become a second copy of the public HTTP endpoint reference; that belongs in `docs/api.md`.
|
||||
|
||||
Use one file per integration where useful.
|
||||
|
||||
@@ -346,8 +434,10 @@ Before merging documentation changes, verify:
|
||||
|
||||
- README is concise and orientation-focused.
|
||||
- `docs/policy/architecture.md` describes development principles.
|
||||
- `docs/api.md` is the canonical HTTP contract for HTTP API services.
|
||||
- Future work appears only under `docs/roadmap/`.
|
||||
- User-facing docs avoid unnecessary internals.
|
||||
- Consumer-facing docs explain public APIs without duplicating HTTP endpoint or integration contracts.
|
||||
- Developer-facing docs preserve boundaries and invariants.
|
||||
- Config examples match the schema.
|
||||
- CLI examples match real commands and flags.
|
||||
|
||||
@@ -1,111 +1,144 @@
|
||||
# Runtime Parameter Implementation Plan
|
||||
# Library API Implementation Plan
|
||||
|
||||
This plan implements the target state in `docs/roadmap/params.md`.
|
||||
This plan implements the target state in `docs/roadmap/library.md`.
|
||||
|
||||
Audience: LLM coding agents implementing the feature in order. Follow `docs/policy/architecture.md`, `docs/policy/development.md`, and `docs/policy/documentation.md` before changing code.
|
||||
|
||||
## Constraints
|
||||
|
||||
- Keep adapters thin. CLI and HTTP should capture caller intent and map it into domain request types; merge decisions belong in `internal/usecase`.
|
||||
- Keep external decoding strict. Unknown YAML/JSON fields must continue to fail.
|
||||
- Do not accept or emit raw API key values.
|
||||
- Do not add dependencies unless there is a clear need. This feature should use the standard library plus existing dependencies.
|
||||
- Do not expand the HTTP API surface beyond `POST /v1/runs`.
|
||||
- Do not add provider-specific adapter packages.
|
||||
- Add a public root package named `scriptorium`; keep existing `internal/*` packages internal.
|
||||
- Define public facade types and convert to/from internal domain types. Do not alias internal domain types as the public API.
|
||||
- Do not rewire CLI or HTTP through the public facade in this implementation.
|
||||
- Preserve current CLI, HTTP, prompt/profile loading, validation, secret-handling, and outbound LLM behavior.
|
||||
- Do not add dependencies.
|
||||
- Keep each stage passing `go test ./...` before moving to the next stage.
|
||||
|
||||
## Stage 1: Presence-Aware Request Overrides
|
||||
## Stage 1: Public Types, Engine Construction, And Prepare
|
||||
|
||||
Goal: make per-request numeric execution overrides presence-aware while keeping resolved execution settings concrete.
|
||||
Goal: make prompt preparation usable from an imported root package without calling an LLM.
|
||||
|
||||
### Domain Changes
|
||||
### Public Package
|
||||
|
||||
1. In `internal/domain/domain.go`, add a request-only type:
|
||||
Create Go files at the module root using:
|
||||
|
||||
```go
|
||||
type ExecutionTargetOverride struct {
|
||||
Endpoint string `json:"endpoint,omitempty"`
|
||||
Model string `json:"model,omitempty"`
|
||||
Temperature *float64 `json:"temperature,omitempty"`
|
||||
MaxTokens *int `json:"max_tokens,omitempty"`
|
||||
TopP *float64 `json:"top_p,omitempty"`
|
||||
TimeoutSeconds *int `json:"timeout_seconds,omitempty"`
|
||||
ServiceTier string `json:"service_tier,omitempty"`
|
||||
ReasoningEffort string `json:"reasoning_effort,omitempty"`
|
||||
APIKeyEnv string `json:"api_key_env,omitempty"`
|
||||
ExtraParams map[string]any `json:"extra_params,omitempty"`
|
||||
package scriptorium
|
||||
```
|
||||
|
||||
Expose:
|
||||
|
||||
```go
|
||||
type Engine struct { /* unexported fields */ }
|
||||
|
||||
type Config struct {
|
||||
PromptDir string
|
||||
ProfileDir string
|
||||
SchemaDir string
|
||||
Timeout time.Duration
|
||||
HTTPClient *http.Client
|
||||
}
|
||||
|
||||
type Option func(*engineOptions) error
|
||||
|
||||
func NewEngine(cfg Config, opts ...Option) (*Engine, error)
|
||||
func (e *Engine) Prepare(ctx context.Context, req RunRequest) (*PreparedRun, error)
|
||||
```
|
||||
|
||||
Construction rules:
|
||||
|
||||
- `PromptDir` and `ProfileDir` are required.
|
||||
- `SchemaDir` defaults to the same built-in default used by app config.
|
||||
- `Timeout`, when non-zero, configures the default OpenAI-compatible client timeout.
|
||||
- `HTTPClient`, when non-nil, is used by the default OpenAI-compatible client.
|
||||
- `NewEngine` wires the same internal components used by CLI/HTTP: filesystem prompt/profile repositories, composite artifact reader, Go template renderer, standard validator, and OpenAI-compatible LLM client.
|
||||
- Return public `ErrInvalidConfig` for invalid engine configuration.
|
||||
|
||||
### Public Types
|
||||
|
||||
Define public facade types with exported fields:
|
||||
|
||||
- `RunRequest`
|
||||
- `PreparedRun`
|
||||
- `ArtifactRef`
|
||||
- `Artifact`
|
||||
- `ExecutionTarget`
|
||||
- `ExecutionTargetOverride`
|
||||
- `ExecutionTargetPresence`
|
||||
- `OutputContract`
|
||||
- `ValidationResult`
|
||||
- `TokenUsage`
|
||||
- `RenderedMessage`
|
||||
- `CacheControl`
|
||||
- `StructuredOutputSpec`
|
||||
|
||||
Use the same enum string values as internal domain types for formats, validation modes, validation statuses, artifact ref types, cache-control type, and structured-output type.
|
||||
|
||||
Required request shape:
|
||||
|
||||
```go
|
||||
type RunRequest struct {
|
||||
PromptID string
|
||||
PromptVersion string
|
||||
ProfileID string
|
||||
Inputs map[string]ArtifactRef
|
||||
Vars map[string]string
|
||||
Execution *ExecutionTargetOverride
|
||||
Validation *OutputContract
|
||||
Metadata map[string]string
|
||||
}
|
||||
```
|
||||
|
||||
2. Change `domain.RunRequest.Execution` from `*ExecutionTarget` to `*ExecutionTargetOverride`.
|
||||
3. Change `ExecutionProfile.ExtraParams` and `ExecutionTarget.ExtraParams` from `map[string]string` to `map[string]any`.
|
||||
4. Keep `ExecutionTarget` concrete. It represents the resolved effective runtime target after defaults, profile, and request overrides are merged.
|
||||
`ExecutionTargetOverride` must preserve numeric override presence using pointer fields:
|
||||
|
||||
### Runner Changes
|
||||
```go
|
||||
Temperature *float64
|
||||
MaxTokens *int
|
||||
TopP *float64
|
||||
TimeoutSeconds *int
|
||||
```
|
||||
|
||||
1. Update `internal/usecase/runner.go` so profile values still merge over built-in defaults and request overrides merge over that result.
|
||||
2. Keep the existing concrete profile merge semantics for profile numeric fields.
|
||||
3. Add a separate request override merge path that uses pointer presence:
|
||||
- `nil` numeric pointer means omitted; preserve the current value.
|
||||
- non-nil numeric pointer means explicit override, even when the value is `0`.
|
||||
4. Validate request override numeric values before or during merge:
|
||||
- `temperature`: `0 <= value <= 2`
|
||||
- `max_tokens`: `value >= 0`
|
||||
- `top_p`: `0 <= value <= 1`
|
||||
- `timeout_seconds`: `value >= 0`
|
||||
5. Preserve existing validation after merge:
|
||||
- effective endpoint required
|
||||
- effective model required
|
||||
- `api_key_env`, when set, must name a non-empty environment variable
|
||||
6. Preserve secret handling. The resolved API key value must never be stored in `PreparedRun`, `RunResult`, logs, or HTTP responses.
|
||||
`PreparedRun` should include the same user-observable fields as internal `domain.PreparedRun`, but should not expose internal-only target presence metadata.
|
||||
|
||||
### CLI Changes
|
||||
### Input Helpers
|
||||
|
||||
1. Update `internal/adapter/cli/run.go` request construction to build `domain.ExecutionTargetOverride`.
|
||||
2. Use the existing `flagWasSet` booleans to populate numeric pointers only when the user provided the flag.
|
||||
3. Required behavior:
|
||||
- omitted `--temperature` preserves profile/default temperature;
|
||||
- `--temperature 0` explicitly sets temperature to zero;
|
||||
- omitted `--top-p` preserves profile/default top-p;
|
||||
- `--top-p 0` explicitly sets top-p to zero;
|
||||
- omitted `--max-tokens` preserves profile/default max tokens;
|
||||
- `--max-tokens 0` explicitly sets max tokens to zero;
|
||||
- omitted `--timeout` preserves profile/default timeout;
|
||||
- `--timeout 0s` explicitly sets timeout seconds to zero.
|
||||
4. Do not add new CLI flags in this stage.
|
||||
Expose:
|
||||
|
||||
### HTTP Changes
|
||||
```go
|
||||
func File(path string) ArtifactRef
|
||||
func Inline(body string) ArtifactRef
|
||||
func InlineWithURI(uri string, body string) ArtifactRef
|
||||
```
|
||||
|
||||
1. Update `internal/adapter/http/dto.go` so numeric model override fields are pointers:
|
||||
- `Temperature *float64`
|
||||
- `MaxTokens *int`
|
||||
- `TopP *float64`
|
||||
- `TimeoutSeconds *int`
|
||||
2. Update DTO mapping in `internal/adapter/http/handler.go` to build `domain.ExecutionTargetOverride`.
|
||||
3. Preserve strict JSON decoding and existing error mapping.
|
||||
4. Required behavior:
|
||||
- omitted numeric JSON fields preserve profile/default values;
|
||||
- explicit numeric zero JSON fields override profile/default values.
|
||||
Mapping:
|
||||
|
||||
- `File(path)` maps to artifact type `file` with `URI: path`.
|
||||
- `Inline(body)` maps to artifact type `inline` with `Body: body`.
|
||||
- `InlineWithURI(uri, body)` maps to artifact type `inline` with both fields set.
|
||||
|
||||
### Conversion Layer
|
||||
|
||||
Implement unexported conversion helpers in the public package:
|
||||
|
||||
- public run request to internal `domain.RunRequest`
|
||||
- internal `domain.PreparedRun` to public `PreparedRun`
|
||||
- internal artifacts/messages/contracts/validation/usage/structured-output to public equivalents
|
||||
- public execution override to internal `domain.ExecutionTargetOverride`
|
||||
|
||||
Conversions must deep-copy maps and slices that cross the public/internal boundary.
|
||||
|
||||
### Tests
|
||||
|
||||
Add or update tests in:
|
||||
Add root package tests.
|
||||
|
||||
- `internal/usecase/runner_test.go`
|
||||
- `internal/adapter/cli/run_test.go`
|
||||
- `internal/adapter/http/handler_test.go`
|
||||
Required tests:
|
||||
|
||||
Required test coverage:
|
||||
|
||||
- Runner preserves profile value when request numeric override is omitted.
|
||||
- Runner applies explicit zero request override for `temperature`.
|
||||
- Runner applies explicit zero request override for `top_p`.
|
||||
- Runner applies explicit zero request override for `max_tokens`.
|
||||
- Runner applies explicit zero request override for `timeout_seconds`.
|
||||
- Invalid request override ranges fail as invalid request errors.
|
||||
- CLI `--temperature 0` reaches effective settings as zero.
|
||||
- HTTP `"temperature": 0` reaches effective settings as zero.
|
||||
- HTTP omitted `temperature` preserves profile/default value.
|
||||
- `NewEngine` rejects missing `PromptDir`.
|
||||
- `NewEngine` rejects missing `ProfileDir`.
|
||||
- `Prepare` works with `examples/config.yml` directories when passed directly through `Config`.
|
||||
- `Prepare` works with `File` input refs.
|
||||
- `Prepare` works with `Inline` input refs.
|
||||
- `Prepare` output does not expose raw API-key values or internal target presence metadata in JSON.
|
||||
- Explicit zero execution overrides survive into prepared effective settings.
|
||||
|
||||
### Verification
|
||||
|
||||
@@ -115,85 +148,109 @@ Run:
|
||||
go test ./...
|
||||
```
|
||||
|
||||
## Stage 2: JSON-Compatible `extra_params`
|
||||
## Stage 2: Run, LLM Injection, And Public Errors
|
||||
|
||||
Goal: allow provider-specific parameters to carry JSON-compatible values throughout profile, HTTP, prepared output, metadata, and LLM request construction.
|
||||
Goal: make full execution usable and testable without real provider credentials.
|
||||
|
||||
### Domain And Loader Changes
|
||||
### Public Run Method
|
||||
|
||||
1. Complete all compile fixes from changing `ExtraParams` to `map[string]any`.
|
||||
2. Ensure `internal/profile/filesystem_repository.go` continues to decode profiles strictly while allowing nested JSON-compatible values under `extra_params`.
|
||||
3. Add profile repository tests for `extra_params` containing:
|
||||
- string
|
||||
- number
|
||||
- boolean
|
||||
- nested object or array
|
||||
4. Ensure formatter output remains deterministic:
|
||||
- keep sorting `extra_params` keys in `internal/format/prepared_run.go`;
|
||||
- render non-string values with stable JSON encoding in text output.
|
||||
5. Preserve JSON formatter behavior through normal `encoding/json` output.
|
||||
Expose:
|
||||
|
||||
### HTTP Changes
|
||||
|
||||
1. Change HTTP model override `ExtraParams` to `map[string]any`.
|
||||
2. Add handler tests proving HTTP accepts JSON-compatible `extra_params` values.
|
||||
3. Preserve strict rejection of unknown fields and raw API-key payload fields.
|
||||
|
||||
### Verification
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
go test ./...
|
||||
```go
|
||||
func (e *Engine) Run(ctx context.Context, req RunRequest) (*RunResult, error)
|
||||
```
|
||||
|
||||
## Stage 3: Outbound Serialization
|
||||
`RunResult` should expose:
|
||||
|
||||
Goal: serialize `reasoning_effort` and `extra_params` to the OpenAI-compatible chat-completions request.
|
||||
- run ID
|
||||
- artifact
|
||||
- raw output
|
||||
- validation result
|
||||
- prompt/profile/model metadata
|
||||
- effective model params
|
||||
- input hashes
|
||||
- token/cache usage
|
||||
- start/end/duration timing
|
||||
|
||||
### LLM Adapter Changes
|
||||
Do not expose raw API-key values.
|
||||
|
||||
1. In `internal/llm/openai_compatible_client.go`, add first-class outbound support for `reasoning_effort`.
|
||||
2. Add `extra_params` support by flattening `domain.ExecutionTarget.ExtraParams` into additional top-level JSON request fields.
|
||||
3. Implement reserved-field collision checks before the HTTP request is made.
|
||||
4. Reserved keys must include:
|
||||
- `model`
|
||||
- `session_id`
|
||||
- `messages`
|
||||
- `temperature`
|
||||
- `max_tokens`
|
||||
- `top_p`
|
||||
- `service_tier`
|
||||
- `reasoning_effort`
|
||||
- `response_format`
|
||||
5. Reject empty `extra_params` keys.
|
||||
6. Ensure each `extra_params` value can be marshaled as JSON. If marshaling fails, return `ErrInvalidRequest` with context.
|
||||
7. Keep existing request behavior unchanged when `reasoning_effort` and `extra_params` are unset.
|
||||
### Public LLM Injection
|
||||
|
||||
### Recommended Implementation Shape
|
||||
Expose:
|
||||
|
||||
Use a custom marshal path for the outbound chat request rather than string manipulation.
|
||||
```go
|
||||
type LLMClient interface {
|
||||
Generate(context.Context, GenerateRequest) (*GenerateResponse, error)
|
||||
}
|
||||
|
||||
One acceptable shape:
|
||||
func WithLLMClient(client LLMClient) Option
|
||||
```
|
||||
|
||||
- Add `ReasoningEffort string` and `ExtraParams map[string]any` to the internal `openAIChatRequest`.
|
||||
- Add a helper that converts `openAIChatRequest` into `map[string]any`, inserts first-class fields when set, then inserts `ExtraParams` after collision validation.
|
||||
- Marshal that map with `encoding/json`.
|
||||
Public `GenerateRequest` must include:
|
||||
|
||||
Do not construct outbound JSON with manual string concatenation.
|
||||
- rendered prompt
|
||||
- effective execution target
|
||||
- execution target presence
|
||||
- structured-output spec
|
||||
|
||||
Public `GenerateResponse` must include:
|
||||
|
||||
- content
|
||||
- token usage
|
||||
|
||||
Implementation rule:
|
||||
|
||||
- `WithLLMClient` wraps the public client in an unexported adapter that satisfies `internal/llm.Client`.
|
||||
- The adapter converts internal generate requests to public generate requests and converts public generate responses back to internal responses.
|
||||
- A nil client passed to `WithLLMClient` returns `ErrInvalidConfig`.
|
||||
|
||||
Default behavior:
|
||||
|
||||
- If no custom LLM client is supplied, `NewEngine` uses `internal/llm.NewOpenAICompatibleClient`.
|
||||
- `Config.Timeout` and `Config.HTTPClient` apply only to the default OpenAI-compatible client.
|
||||
|
||||
### Public Errors
|
||||
|
||||
Define public sentinel errors:
|
||||
|
||||
- `ErrInvalidConfig`
|
||||
- `ErrInvalidRequest`
|
||||
- `ErrPromptNotFound`
|
||||
- `ErrProfileNotFound`
|
||||
- `ErrPromptLoad`
|
||||
- `ErrProfileLoad`
|
||||
- `ErrArtifactLoad`
|
||||
- `ErrPromptRender`
|
||||
- `ErrLLMGenerate`
|
||||
- `ErrValidation`
|
||||
|
||||
Public methods must map internal errors to public sentinels while preserving wrapped context. Callers must be able to use `errors.Is`.
|
||||
|
||||
Mapping rules:
|
||||
|
||||
- missing/invalid public engine config -> `ErrInvalidConfig`
|
||||
- internal `usecase.ErrInvalidRequest` -> `ErrInvalidRequest`
|
||||
- internal prompt not found -> `ErrPromptNotFound`
|
||||
- internal profile not found -> `ErrProfileNotFound`
|
||||
- internal prompt load errors -> `ErrPromptLoad`
|
||||
- internal profile load errors -> `ErrProfileLoad`
|
||||
- internal artifact load errors -> `ErrArtifactLoad`
|
||||
- internal prompt render errors -> `ErrPromptRender`
|
||||
- internal LLM generate errors -> `ErrLLMGenerate`
|
||||
- internal validation runtime errors -> `ErrValidation`
|
||||
|
||||
Do not expose internal sentinel values as public API.
|
||||
|
||||
### Tests
|
||||
|
||||
Update `internal/llm/openai_compatible_client_test.go`.
|
||||
Required tests:
|
||||
|
||||
Required test coverage:
|
||||
|
||||
- outbound JSON includes `reasoning_effort` when set;
|
||||
- outbound JSON omits `reasoning_effort` when unset;
|
||||
- outbound JSON includes string, number, boolean, object, and array `extra_params`;
|
||||
- reserved `extra_params` keys fail before provider call;
|
||||
- empty `extra_params` keys fail before provider call;
|
||||
- existing message, cache-control, service-tier, response-format, and usage parsing tests continue to pass.
|
||||
- `Run` succeeds with `WithLLMClient` fake and returns typed artifact, raw output, validation, metadata, and usage.
|
||||
- `Run` passes rendered prompt, effective execution target, and target presence to the injected LLM client.
|
||||
- `Run` validation failure returns a successful result with failed validation, not an error.
|
||||
- public errors support `errors.Is` for invalid request, prompt not found, profile not found, artifact load, render failure, LLM failure, and validation runtime failure.
|
||||
- nil `WithLLMClient(nil)` returns `ErrInvalidConfig`.
|
||||
- default OpenAI-compatible client can still be constructed without real provider credentials.
|
||||
|
||||
### Verification
|
||||
|
||||
@@ -203,39 +260,39 @@ Run:
|
||||
go test ./...
|
||||
```
|
||||
|
||||
## Stage 4: Documentation And Examples
|
||||
## Stage 3: Public Documentation And Consumer Examples
|
||||
|
||||
Goal: move implemented behavior from roadmap to canonical docs after code is complete.
|
||||
Goal: document implemented library behavior in canonical public-consumer docs.
|
||||
|
||||
Update only after Stages 1 through 3 are implemented.
|
||||
### Docs
|
||||
|
||||
### Required Docs
|
||||
After Stages 1 and 2 are implemented, update:
|
||||
|
||||
Update:
|
||||
- `README.md`: add a short link to library usage without turning the README into a manual.
|
||||
- `docs/internal/adapters.md`: list the public library facade as an implemented adapter surface.
|
||||
- `docs/consumers/api.md`: describe the public consumer API at a high level.
|
||||
- `docs/consumers/pkg-scriptorium.md`: document the root package usage, types, errors, and examples.
|
||||
|
||||
- `docs/config.md`
|
||||
- `docs/cli.md`
|
||||
- `docs/integrations/http-api.md`
|
||||
- `docs/integrations/openai-compatible-chat.md`
|
||||
- `docs/internal/runner.md`
|
||||
- `docs/internal/adapters.md`
|
||||
Create `docs/consumers/` if it does not exist.
|
||||
|
||||
Required documentation content:
|
||||
|
||||
- `reasoning_effort` is serialized outbound when set.
|
||||
- `extra_params` serializes as provider-specific top-level outbound JSON fields.
|
||||
- `extra_params` supports JSON-compatible values.
|
||||
- reserved `extra_params` fields are rejected.
|
||||
- per-request numeric overrides distinguish omitted values from explicit zero values.
|
||||
- CLI explicit zero behavior for existing numeric flags.
|
||||
- HTTP explicit zero behavior for model override numeric fields.
|
||||
- no raw API-key values are accepted or emitted.
|
||||
Do not document unimplemented future library features outside `docs/roadmap/`.
|
||||
|
||||
### Examples
|
||||
|
||||
Update examples only if needed to keep them accurate and runnable.
|
||||
Add copyable library examples only if they can be tested without real credentials.
|
||||
|
||||
If adding an `extra_params` example, keep it secret-free and simple. Prefer a harmless provider-routing example over a vendor-specific feature that requires special credentials.
|
||||
Recommended example:
|
||||
|
||||
- `examples/go-library/prepare/main.go` or equivalent prepare-only example using `examples/` prompt/profile/fixture assets.
|
||||
|
||||
If adding a run example, it must use an injected fake LLM client and must not require provider credentials.
|
||||
|
||||
### Tests
|
||||
|
||||
Required tests:
|
||||
|
||||
- doc/example smoke coverage for any added Go example using `go test` or `go test ./...`.
|
||||
- existing CLI/HTTP tests continue to pass unchanged.
|
||||
|
||||
### Verification
|
||||
|
||||
@@ -255,8 +312,10 @@ go run ./cmd/scriptorium render \
|
||||
|
||||
Before considering the feature complete:
|
||||
|
||||
1. Confirm `git diff` contains only intended code, test, doc, and example changes.
|
||||
2. Confirm all non-roadmap docs describe implemented behavior only.
|
||||
3. Confirm no output path exposes raw API key values.
|
||||
4. Confirm `go test ./...` passes.
|
||||
5. Confirm the render smoke command passes.
|
||||
1. Confirm the root package can be imported as `gitea.maximumdirect.net/eric/scriptorium`.
|
||||
2. Confirm public package tests do not require real provider credentials.
|
||||
3. Confirm `go test ./...` passes.
|
||||
4. Confirm the render smoke command passes.
|
||||
5. Confirm non-roadmap docs describe only implemented behavior.
|
||||
6. Confirm no public result or rendered/prepared output exposes raw API-key values.
|
||||
7. Confirm `git diff` does not include unrelated CLI/HTTP behavior changes.
|
||||
|
||||
134
docs/roadmap/library.md
Normal file
134
docs/roadmap/library.md
Normal file
@@ -0,0 +1,134 @@
|
||||
# Library API Roadmap
|
||||
|
||||
This roadmap defines the target behavior for making Scriptorium usable as an imported Go library while retaining the current standalone CLI and HTTP application behavior.
|
||||
|
||||
The implementation plan for this feature lives in `docs/roadmap/implementation.md`.
|
||||
|
||||
## Motivation
|
||||
|
||||
Scriptorium is currently optimized for subprocess use by other applications. That contract remains useful because it is language-neutral, operationally simple, and process-isolated.
|
||||
|
||||
For Go callers, an imported library should provide:
|
||||
|
||||
- typed requests and results instead of stdout/stderr parsing;
|
||||
- direct `context.Context` cancellation;
|
||||
- lower overhead for repeated calls;
|
||||
- easier test integration through injected clients or fixtures;
|
||||
- direct access to prepared-run data without process management;
|
||||
- fewer integration points where secrets or output metadata can be mishandled.
|
||||
|
||||
The library is an additional adapter surface, not a replacement for the CLI or HTTP API.
|
||||
|
||||
## Target State
|
||||
|
||||
Scriptorium should expose a small public Go API suitable for common embedding use cases:
|
||||
|
||||
- construct an engine from app-level settings such as prompt, profile, and schema directories;
|
||||
- prepare a prompt request without calling an LLM;
|
||||
- run a prompt request and receive a typed result;
|
||||
- pass file and inline artifacts;
|
||||
- apply profile selection, runtime overrides, vars, validation behavior, cache-control behavior, and structured-output behavior consistently with CLI/HTTP;
|
||||
- inject a custom LLM client or HTTP client where needed;
|
||||
- preserve existing CLI and HTTP behavior by continuing to route all entry paths through the same use-case layer.
|
||||
|
||||
The public library API should be stable, narrow, and intentionally higher-level than the current `internal/*` package layout.
|
||||
|
||||
## Public Package Policy
|
||||
|
||||
The public package should be the module root:
|
||||
|
||||
```go
|
||||
import "gitea.maximumdirect.net/eric/scriptorium"
|
||||
```
|
||||
|
||||
Recommended usage shape:
|
||||
|
||||
```go
|
||||
engine, err := scriptorium.NewEngine(scriptorium.Config{
|
||||
PromptDir: "./prompts",
|
||||
ProfileDir: "./profiles",
|
||||
SchemaDir: "./schemas",
|
||||
})
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
|
||||
prepared, err := engine.Prepare(ctx, scriptorium.RunRequest{
|
||||
PromptID: "generic.markdown_summary",
|
||||
Inputs: map[string]scriptorium.ArtifactRef{
|
||||
"transcript": scriptorium.File("./transcript.md"),
|
||||
},
|
||||
})
|
||||
|
||||
result, err := engine.Run(ctx, scriptorium.RunRequest{
|
||||
PromptID: "generic.markdown_summary",
|
||||
Inputs: map[string]scriptorium.ArtifactRef{
|
||||
"transcript": scriptorium.File("./transcript.md"),
|
||||
},
|
||||
})
|
||||
```
|
||||
|
||||
## Policy Decisions
|
||||
|
||||
### Public Package Scope
|
||||
|
||||
Expose a narrow root facade package and keep existing `internal/*` packages internal.
|
||||
|
||||
Reasoning:
|
||||
|
||||
This gives callers the workflow they need without freezing the internal architecture as public API. It also preserves the current package-boundary policy and keeps future refactoring possible.
|
||||
|
||||
### Public Type Strategy
|
||||
|
||||
Define public facade types and map them to internal domain types.
|
||||
|
||||
Reasoning:
|
||||
|
||||
Public types can be designed around caller needs and long-term stability. Internal types can continue to evolve with implementation details such as adapter metadata, validation internals, and provider-specific behavior.
|
||||
|
||||
### CLI And HTTP Reuse
|
||||
|
||||
Keep CLI and HTTP on current internal wiring for the initial library release. Consider migrating them to the public facade only after the facade proves stable.
|
||||
|
||||
Reasoning:
|
||||
|
||||
This minimizes risk to the existing subprocess and HTTP contracts while adding the new API. It also avoids forcing the first public facade to satisfy every adapter edge case immediately.
|
||||
|
||||
### Error Surface
|
||||
|
||||
Expose public sentinel errors or typed error categories and map internal errors to them while preserving wrapped context.
|
||||
|
||||
Reasoning:
|
||||
|
||||
Library callers need stable, idiomatic error checks. Mapping internal errors avoids exposing internal package paths as public compatibility promises.
|
||||
|
||||
## Scope
|
||||
|
||||
In scope:
|
||||
|
||||
- Public facade package for library consumers.
|
||||
- Public request, result, prepared-run, artifact reference, execution override, validation, and config types.
|
||||
- Public constructors for common file and inline input references.
|
||||
- Public engine methods for `Prepare` and `Run`.
|
||||
- Optional dependency injection for LLM behavior and HTTP behavior.
|
||||
- Stable error behavior suitable for `errors.Is` and `errors.As`.
|
||||
- Tests proving public API behavior matches CLI/use-case behavior.
|
||||
- Documentation and examples for library usage after implementation.
|
||||
|
||||
Out of scope for the first library release:
|
||||
|
||||
- Making every `internal/*` package public.
|
||||
- Replacing or rewiring the CLI or HTTP adapters.
|
||||
- Adding a durable run store or workflow engine.
|
||||
- Adding broad provider-specific SDK surfaces.
|
||||
- Adding non-Go language bindings.
|
||||
- Adding global mutable configuration.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- A Go caller can import the root module and run a prompt without invoking a subprocess.
|
||||
- A Go caller can prepare a prompt without invoking an LLM.
|
||||
- Public library behavior matches current CLI/HTTP use-case semantics for prompt/profile loading, artifact reading, rendering, validation, and model invocation.
|
||||
- Existing CLI and HTTP behavior remains unchanged.
|
||||
- Library tests use injected/fake LLM behavior and do not require real provider credentials.
|
||||
- Public documentation is concise and limited to implemented behavior once code exists.
|
||||
@@ -1,96 +0,0 @@
|
||||
# Runtime Parameter Feature Roadmap
|
||||
|
||||
This roadmap defines the target behavior for runtime model parameters.
|
||||
|
||||
Current behavior has two limitations:
|
||||
|
||||
- `reasoning_effort` and `extra_params` are parsed into effective execution settings but are not serialized into outbound OpenAI-compatible chat-completions requests.
|
||||
- Per-request numeric execution overrides use zero-value merge semantics, so callers cannot reliably override a profile value with an explicit zero such as `temperature: 0`.
|
||||
|
||||
The implementation plan for this feature lives in `docs/roadmap/implementation.md`.
|
||||
|
||||
## Target State
|
||||
|
||||
Scriptorium should preserve the existing separation between prompt definitions, execution profiles, and per-request execution overrides while making runtime parameter behavior explicit and predictable.
|
||||
|
||||
Expected end state:
|
||||
|
||||
- Effective execution settings remain visible in prepared-run output, run metadata, and HTTP metadata without exposing raw secret values.
|
||||
- `reasoning_effort` is treated as a first-class effective execution setting and is serialized to the outbound OpenAI-compatible request when set.
|
||||
- `extra_params` supports provider-specific OpenAI-compatible request fields.
|
||||
- `extra_params` is serialized as additional top-level outbound JSON fields.
|
||||
- `extra_params` values support JSON-compatible scalar, object, and array values.
|
||||
- `extra_params` cannot override first-class outbound request fields.
|
||||
- Per-request numeric overrides preserve caller intent, including explicit zero values.
|
||||
- Omitted per-request numeric overrides continue to inherit the selected profile and built-in defaults.
|
||||
- External decoding remains strict for config, prompt, profile, and HTTP request payloads.
|
||||
|
||||
## Policy Decisions
|
||||
|
||||
### `extra_params`
|
||||
|
||||
`extra_params` should serialize as additional top-level outbound JSON fields in the OpenAI-compatible chat-completions request.
|
||||
|
||||
Reasoning:
|
||||
|
||||
Most OpenAI-compatible providers expose vendor-specific chat-completions parameters as top-level fields. This keeps Scriptorium's adapter compatible with that ecosystem without adding first-class fields for every provider option.
|
||||
|
||||
`extra_params` must not silently override Scriptorium-owned fields. Reserved outbound fields include at least:
|
||||
|
||||
- `model`
|
||||
- `session_id`
|
||||
- `messages`
|
||||
- `temperature`
|
||||
- `max_tokens`
|
||||
- `top_p`
|
||||
- `service_tier`
|
||||
- `reasoning_effort`
|
||||
- `response_format`
|
||||
|
||||
If a caller supplies a reserved key through `extra_params`, Scriptorium should fail before making the outbound HTTP request.
|
||||
|
||||
`extra_params` should use JSON-compatible values rather than only strings.
|
||||
|
||||
Reasoning:
|
||||
|
||||
Provider-specific parameters commonly need booleans, numbers, objects, or arrays. String-only values would force awkward encoding and would likely require a later compatibility break.
|
||||
|
||||
### Presence-Aware Overrides
|
||||
|
||||
Per-request execution overrides should use a presence-aware type with pointer fields for optional numeric values.
|
||||
|
||||
Reasoning:
|
||||
|
||||
The resolved execution target should remain a concrete value used by prepared runs, generated requests, and metadata. Optionality matters at the request boundary, not after the runner has resolved the effective target.
|
||||
|
||||
This keeps adapter and merge logic precise while avoiding nil checks in formatter, metadata, and LLM serialization paths.
|
||||
|
||||
## Scope
|
||||
|
||||
In scope:
|
||||
|
||||
- Runtime merge behavior for per-request execution overrides.
|
||||
- HTTP model override decoding for explicit zero numeric values.
|
||||
- CLI execution override handling for explicit zero numeric flags.
|
||||
- Outbound serialization of `reasoning_effort`.
|
||||
- Outbound serialization of JSON-compatible `extra_params`.
|
||||
- Tests and documentation for the changed implemented behavior.
|
||||
|
||||
Out of scope:
|
||||
|
||||
- Expanding the HTTP API beyond `POST /v1/runs`.
|
||||
- Adding built-in HTTP authentication or authorization.
|
||||
- Adding durable run state, run history, or multi-step orchestration.
|
||||
- Adding broad provider-specific adapter packages.
|
||||
- Adding new CLI flags for every provider-specific parameter.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- A profile containing `reasoning_effort: medium` produces an outbound request with `reasoning_effort`.
|
||||
- HTTP callers can pass `reasoning_effort` through the existing `model` override object and have it appear outbound.
|
||||
- A profile or HTTP request containing JSON-compatible `extra_params` produces outbound top-level JSON fields according to the reserved-field policy.
|
||||
- Reserved `extra_params` collisions fail before the outbound provider call.
|
||||
- CLI callers can pass `--temperature 0` and observe `temperature: 0` in rendered/effective settings and outbound requests.
|
||||
- HTTP callers can send `"temperature": 0` and observe the same behavior.
|
||||
- Omitting `temperature` continues to preserve the selected profile/default value.
|
||||
- Raw API key values remain unsupported in config, profiles, CLI flags, HTTP payloads, logs, and rendered output.
|
||||
Reference in New Issue
Block a user