diff --git a/doc.go b/doc.go index 13aea28..37beb6f 100644 --- a/doc.go +++ b/doc.go @@ -4,15 +4,16 @@ // Applications construct an [Engine] with [NewEngine], select ConfigKit // sources for prompts, profiles, and backends, and // call [Engine.InspectConfiguration], [Engine.InspectPrompt], -// [Engine.InspectRequirements], [Engine.InspectProfile], [Engine.Prepare], -// [Engine.PrepareExecution], [Engine.Run], or [Engine.RunPrepared]. Concrete -// registries, repositories, validators, and the built-in OpenAI-compatible -// client remain internal implementation details. +// [Engine.InspectRequirements], [Engine.InspectProfile], [Engine.ListProfiles], +// [Engine.ListPrompts], [Engine.Prepare], [Engine.PrepareExecution], +// [Engine.Run], or [Engine.RunPrepared]. Concrete registries, repositories, +// validators, and the built-in OpenAI-compatible client remain internal +// implementation details. // // # Concurrency and ownership // // An Engine supports concurrent InspectConfiguration, InspectPrompt, -// InspectRequirements, InspectProfile, Prepare, +// InspectRequirements, InspectProfile, ListProfiles, ListPrompts, Prepare, // PrepareExecution, Run, and RunPrepared calls. Engine-local backend policies // bound admitted Run and RunPrepared calls and model generations where // configured, while different backend pools and unlimited backends continue @@ -23,6 +24,7 @@ // Engine. Prepare, PrepareExecution, and Run copy request maps, slices, pointer // values, and JSON-compatible extra parameters before using them. InspectPrompt, // InspectRequirements, and InspectProfile return copied inspection values. +// ListProfiles and ListPrompts return caller-owned identity slices. // Returned values and values passed to extension interfaces are likewise // isolated from engine state. // Callers own those copies and may mutate them after the call that supplied or @@ -58,8 +60,8 @@ // [ConfigurationSources], [ConfigurationInspection], [BackendConfig], // [ProfileConfig], [RunRequest], // [ArtifactRef], [ExecutionTargetOverride], [ProfileInspection], -// [PromptInputDefinition], [PromptInspection], [RequirementInspectionRequest], -// [RequirementInspection], [PreparedExecution], +// [PromptIdentity], [PromptInputDefinition], [PromptInspection], +// [RequirementInspectionRequest], [RequirementInspection], [PreparedExecution], // [CapacityError], [GenerationError], [RetryExhaustedError], and // [ExecutionEvent], do not have stable JSON // representations. Direct API keys are nevertheless excluded from JSON for diff --git a/docs/consumers/pkg-promptkit.md b/docs/consumers/pkg-promptkit.md index d10b69c..b10fbd7 100644 --- a/docs/consumers/pkg-promptkit.md +++ b/docs/consumers/pkg-promptkit.md @@ -118,6 +118,43 @@ engines and prepared handles retain their captured definitions; schema and request artifact resources still follow their runtime lifecycle. Inspection does not watch or reload sources automatically. +## Discover Available Profiles And Prompts + +Use [`Engine.ListProfiles`](../../listing.go) and +[`Engine.ListPrompts`](../../listing.go) to discover exact identities from the +engine's final captured configuration, then inspect a selected prompt: + +```go +profiles, err := engine.ListProfiles(ctx) +if err != nil { + return err +} +if len(profiles) > 0 { + _, err := engine.InspectProfile(ctx, profiles[0]) + if err != nil { + return err + } +} +prompts, err := engine.ListPrompts(ctx) +if err != nil { + return err +} +if len(prompts) > 0 { + selected := prompts[0] + inspection, err := engine.InspectPrompt(ctx, selected.ID, selected.Version) + if err != nil { + return err + } + _ = inspection +} +``` + +These lists describe effective membership, not ConfigKit contribution history, +and do not promise that a profile is ready to execute. Use inspection for +details and preparation to resolve request resources. The linked method GoDoc +owns ordering, ownership, concurrency, and error behavior; identifiers may be +sensitive application data. + ## Inspect The Captured Configuration Use [`Engine.InspectConfiguration`](../../configuration_inspection.go) for an diff --git a/docs/formats.md b/docs/formats.md index f0f9267..6930865 100644 --- a/docs/formats.md +++ b/docs/formats.md @@ -51,7 +51,8 @@ message files on ordinary runs; construct a new engine to observe edits. Schema and request artifact reads still happen during preparation. Use `InspectConfiguration` for an explicit effective-configuration or provenance report, `InspectProfile` for backend-completed profile settings, and preparation -for request-specific rendered details. +for request-specific rendered details. For identity discovery before inspection, +see the consumer guide's [profile and prompt listing](consumers/pkg-promptkit.md#discover-available-profiles-and-prompts). ## Prompt Definitions diff --git a/docs/internal/overview.md b/docs/internal/overview.md index 6585c57..0991714 100644 --- a/docs/internal/overview.md +++ b/docs/internal/overview.md @@ -11,16 +11,16 @@ contributor workflow and validation. | Component | Implemented responsibility | References | | --- | --- | --- | -| Root `promptkit` package | Provides the supported engine facade, ConfigKit source helpers, profile and backend mapping conveniences, injection options, public requests and results, prompt/profile/requirement inspection, observation values, opaque prepared-execution handles, value conversion, redacted formatting, and typed capacity and generation error mapping. | [Package GoDoc](../../doc.go), [observations](../../observations.go), [prepared execution](../../prepared_execution.go), [backend API](../../backends.go), [engine facade](../../engine.go), [requirement facade](../../requirements.go) | +| Root `promptkit` package | Provides the supported engine facade, ConfigKit source helpers, profile and backend mapping conveniences, injection options, public requests and results, prompt/profile/requirement inspection and identity listing, observation values, opaque prepared-execution handles, value conversion, redacted formatting, and typed capacity and generation error mapping. | [Package GoDoc](../../doc.go), [observations](../../observations.go), [prepared execution](../../prepared_execution.go), [backend API](../../backends.go), [engine facade](../../engine.go), [identity listing](../../listing.go), [requirement facade](../../requirements.go) | | `examples/go-library/prepare` | Demonstrates offline preparation and explicit configuration inspection with a prompt file, programmatic profile, and inline input. It is not a public library package. | [Example program](../../examples/go-library/prepare/main.go) | | `examples/go-library/run` | Demonstrates an offline downstream consumer using a prompt file, programmatic profile, inline input, an injected deterministic model client, and `Run`. It is not a public library package. | [Example program](../../examples/go-library/run/main.go) | | `examples/go-library/observe` | Demonstrates offline built-in HTTP retry and synchronous metadata observation across structured proposal and assessment runs using embedded sources, two profiles on one finite backend, and an application decision. It is not a public library package. | [Example program](../../examples/go-library/observe/main.go) | | `internal/backend` | Holds a defensive, immutable lookup and capacity-policy index for final backend definitions validated by the configuration adapter. | [Backend registry](../../internal/backend/registry.go) | | `internal/catalog` | Selects released keyed catalog assets and PromptKit-owned profile definitions as ConfigKit underlays; effective validation belongs to the configuration loader. | [Catalog adapter](../../internal/catalog/catalog.go), [internal sources](sources.md#profiles-and-built-ins) | -| `internal/configuration` | Loads keyed backend, profile, and prompt configuration through ConfigKit; records effective field presence, validates final values, captures indexed prompt definitions, referenced message content, compiled templates, and input metadata snapshots, constructs backend and presence-aware profile snapshots, and retains an explicit read-only inspection view. | [Typed loader](../../internal/configuration/load.go), [internal sources](sources.md#typed-configuration-loading) | +| `internal/configuration` | Loads keyed backend, profile, and prompt configuration through ConfigKit; records effective field presence, validates final values, captures indexed prompt definitions, referenced message content, compiled templates, input metadata snapshots, sorted identity-only profile and prompt inventories, backend and presence-aware profile snapshots, and an explicit read-only inspection view. | [Typed loader](../../internal/configuration/load.go), [identity listing](../../internal/configuration/listing.go), [internal sources](sources.md#typed-configuration-loading) | | `internal/capacity` | Owns engine-local bounded execution admission and FIFO model-generation permits for limited backend IDs, including cancellation-safe waiter removal and client wrapping. | [Internal capacity management](capacity.md) | | `internal/domain` | Defines internal framework values for requests, artifacts, prompt definitions, requirement inspection, profiles, execution targets, rendering, generation, and validation, and owns source-neutral invariants for shared execution settings, OpenAI-compatible base endpoints, session identifiers, and output contracts. Source parsing, required fields, other source-specific normalization, defaulting, and boundary-specific error classification remain with their callers. | [Domain declarations](../../internal/domain/domain.go), [requirement values](../../internal/domain/requirements.go), [endpoint invariant](../../internal/domain/endpoint.go) | -| `internal/engine` | Assembles selected catalog and caller configuration into one snapshot, then constructs capacity, rendering, validation, generation, repair, and the use-case runner for each engine. | [Engine assembly](../../internal/engine/engine.go), [internal sources](sources.md#profiles-and-built-ins), [internal runner](runner.md) | +| `internal/engine` | Assembles selected catalog and caller configuration into one snapshot, then constructs capacity, rendering, validation, generation, repair, and the use-case runner for each engine. It delegates identity listing directly to the captured configuration inventory rather than the runner. | [Engine assembly](../../internal/engine/engine.go), [internal sources](sources.md#profiles-and-built-ins), [internal runner](runner.md) | | `internal/generation` | Coordinates frozen built-in HTTP attempts and one-shot injected calls through active backend permits, including bounded status retries, cancellable backoff, and attempt observations. | [Internal generation coordination](generation.md) | | `internal/defaults` | Defines application-neutral framework constants and constructs the default execution target. It contains no CLI, server, or inbound HTTP limits. | [Framework defaults](../../internal/defaults/defaults.go) | | `internal/filecatalog` | Provides deterministic YAML discovery and path helpers for operating-system filesystems and `fs.FS` sources. | [File catalog](../../internal/filecatalog/catalog.go) | diff --git a/docs/internal/sources.md b/docs/internal/sources.md index 27acd37..d4fcdba 100644 --- a/docs/internal/sources.md +++ b/docs/internal/sources.md @@ -21,6 +21,11 @@ profile inheritance. It retains ConfigKit's result privately for explicit inspection, not for per-run resolution. The runtime/domain packages do not depend on ConfigKit. +After prompt materialization and effective-profile snapshot construction, the +adapter captures lexically ordered, identity-only inventories from the final +prompt and indexed-profile maps. Its listing methods return caller-owned copies +of those inventories without consulting ConfigKit or copying definitions. + The root `DirectoryInputs` and `FilesystemInputs` helpers discover sorted YAML files under an explicit root, provide resource context, and leave imports disabled. Each returned slice belongs to one strict-composition group; file @@ -119,6 +124,10 @@ profile without copying its target or requiring readiness. The target interpretation, while the [catalog tests](../../internal/catalog/catalog_test.go) cover selected released assets. +The internal engine delegates listing through a narrow identity-inventory +interface directly to the configuration snapshot. The execution runner has no +listing responsibility. + ## Ordinary Artifacts `internal/artifact` accepts explicitly typed inline references even when their diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md index c5f2ba4..36a3ff4 100644 --- a/docs/roadmap/implementation.md +++ b/docs/roadmap/implementation.md @@ -2,7 +2,7 @@ Implement the [listing roadmap](listing.md) in the numbered order below. Each stage is scoped for one Luna coding-agent prompt and should leave a -compiling, tested unit. All four stages are pending. +compiling, tested unit. All four stages are complete. This replaces the completed performance plan, preserved in [Git history](https://gitea.maximumdirect.net/eric/promptkit/src/commit/7325a34c070c77c4784ab76c916fc8a4d79b5c46/docs/roadmap/implementation.md). @@ -216,7 +216,11 @@ independent results, concurrent safety, and listing without execution work. ## Stage 4 — Document And Verify The Completed Feature -**Status: Pending.** Depends on Stage 3. +**Status: Complete (2026-10-09).** Verified with the full offline race suite, +repository-wide vet, maintained consumer examples, changed documentation-link +checks, and `git diff --check`. The listing roadmap and canonical consumer, +format, and internal documentation now describe the implemented API. Depends +on Stage 3. **Scope:** owning documentation, final review, and complete offline verification. diff --git a/docs/roadmap/inspection.md b/docs/roadmap/inspection.md index e77cc7a..9b4aaa1 100644 --- a/docs/roadmap/inspection.md +++ b/docs/roadmap/inspection.md @@ -1,7 +1,7 @@ # Effective Prompt Requirement Inspection Status: Implemented (2026-10-08). The -[implementation plan](implementation.md) records the completed work units and +[inspection implementation plan](https://gitea.maximumdirect.net/eric/promptkit/src/commit/481e2d494c5a4e8b7f3a2a6f1cceaeb3f7c71d05/docs/roadmap/implementation.md) records the completed work units and final verification. Current public API details live in GoDoc; the consumer guide, format reference, and internal documents link to those canonical contracts. @@ -194,7 +194,7 @@ template syntax and effective metadata; inspection does not enter artifact, schema, credential, rendering, provider, or execution preparation. The final verification and the commit sequence are recorded in the -[implementation plan](implementation.md). The exact public contract is owned by +[inspection implementation plan](https://gitea.maximumdirect.net/eric/promptkit/src/commit/481e2d494c5a4e8b7f3a2a6f1cceaeb3f7c71d05/docs/roadmap/implementation.md). The exact public contract is owned by [GoDoc](../../requirements.go); consumer usage, framework-format cross-reference, and internal selection/source descriptions are maintained in their respective documents. diff --git a/docs/roadmap/listing.md b/docs/roadmap/listing.md index b990317..2dd8af7 100644 --- a/docs/roadmap/listing.md +++ b/docs/roadmap/listing.md @@ -1,6 +1,8 @@ # Profile And Prompt Listing -Status: Accepted; implementation pending. +Status: Implemented (2026-10-09). All public listing behavior and verification +are complete; see the [implementation plan](implementation.md) for completion +and verification evidence. ## Purpose @@ -10,8 +12,8 @@ history. This supports application selectors, CLI discovery, and configuration editors while keeping PromptKit's public API small. Listing supplies identities; the existing inspection methods supply details. -The [implementation plan](implementation.md) defines staged work. This roadmap -describes the intended feature, not currently available methods. +The [implementation plan](implementation.md) records the completed work. This +roadmap captures feature scope; the public GoDoc owns the current API behavior. ## Current Baseline diff --git a/docs/roadmap/performance.md b/docs/roadmap/performance.md index 5f4b93c..5f59164 100644 --- a/docs/roadmap/performance.md +++ b/docs/roadmap/performance.md @@ -3,7 +3,7 @@ Status: Complete (2026-10-09). The ConfigKit request (item 1) was submitted, and local items 2–7 were implemented or completed with the evidence and conditional ownership decision recorded in the -[implementation plan](implementation.md). No dependency upgrade or public +[performance implementation plan](https://gitea.maximumdirect.net/eric/promptkit/src/commit/7325a34c070c77c4784ab76c916fc8a4d79b5c46/docs/roadmap/implementation.md). No dependency upgrade or public performance guarantee was part of this work. ## Purpose @@ -14,7 +14,7 @@ library use make redundant full-payload copies especially worth addressing. Prefer small, idiomatic improvements over additional framework machinery. This roadmap captures the intended outcomes and recommended changes. The -[implementation plan](implementation.md) owns staged work and verification. +[performance implementation plan](https://gitea.maximumdirect.net/eric/promptkit/src/commit/7325a34c070c77c4784ab76c916fc8a4d79b5c46/docs/roadmap/implementation.md) owns staged work and verification. This roadmap introduces no new public performance guarantee. Existing contracts remain owned by GoDoc, the [format reference](../formats.md), and the diff --git a/docs/roadmap/remediation.md b/docs/roadmap/remediation.md index 12ec2a1..1e436ac 100644 --- a/docs/roadmap/remediation.md +++ b/docs/roadmap/remediation.md @@ -5,7 +5,7 @@ Status: All recorded findings have been resolved in separate remediation units. ## Computational Efficiency Review Review baseline: `8a5c0de`, compared with planning commit `3fde1f6`, the -[performance roadmap](performance.md), and [implementation plan](implementation.md). +[performance roadmap](performance.md), and [performance implementation plan](https://gitea.maximumdirect.net/eric/promptkit/src/commit/7325a34c070c77c4784ab76c916fc8a4d79b5c46/docs/roadmap/implementation.md). ### Finding 1 — Release A Stale File Reservation For An Empty Body (P3) @@ -59,7 +59,7 @@ gaps or strengthened public contracts were identified in this review. Review baseline: `a051edd82d9d20cdc82dfebf25adb689dc58b01f`. Scope: implementation commits after `a6e0ffe`, compared with the simplified -[feature roadmap](inspection.md) and [implementation plan](implementation.md). +[feature roadmap](inspection.md) and [inspection implementation plan](https://gitea.maximumdirect.net/eric/promptkit/src/commit/481e2d494c5a4e8b7f3a2a6f1cceaeb3f7c71d05/docs/roadmap/implementation.md). The existing ReleaseKit documentation finding is retained below. ### Finding 1 — Report Lost Caller-Map Scope As Incomplete (P2)