119 lines
6.0 KiB
Markdown
119 lines
6.0 KiB
Markdown
# Profile And Prompt Listing
|
|
|
|
Status: Accepted; implementation pending.
|
|
|
|
## Purpose
|
|
|
|
Let consumers discover the profiles and prompt versions available in an engine
|
|
without knowing their identifiers in advance or interpreting configuration
|
|
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.
|
|
|
|
## Current Baseline
|
|
|
|
Review baseline: `03c44923c8a14565dca30f65d93bde79e0962ea2`.
|
|
|
|
- `Engine.InspectProfile` and `Engine.InspectPrompt` inspect a known identity.
|
|
Neither enumerates available entries.
|
|
- `Engine.InspectConfiguration` exposes ConfigKit's captured inspection view.
|
|
Consumers can enumerate historical paths and filter for surviving effective
|
|
entries, but that is an indirect configuration-inspection workflow.
|
|
- The configuration adapter already captures profiles by literal ID and prompts
|
|
by literal ID/version pair. Those execution-facing indexes are sufficient
|
|
for listing; no new configuration loading or registry is needed.
|
|
|
|
The [consumer guide](../consumers/pkg-promptkit.md) describes existing inspection
|
|
workflows. The [format reference](../formats.md) owns keyed definitions and
|
|
literal identifier semantics. Preserve the final-configuration boundary in
|
|
[ADR 0001](../adr/0001-configuration-boundary.md) and the facade ownership in
|
|
the [architecture policy](../policy/architecture.md).
|
|
|
|
## Target End State
|
|
|
|
### Small Public Listing API
|
|
|
|
Add two engine methods, following the context and error conventions of the
|
|
existing prompt/profile inspection methods:
|
|
|
|
- `ListProfiles(ctx)` returns profile IDs.
|
|
- `ListPrompts(ctx)` returns small identity values containing `ID` and `Version`.
|
|
|
|
Expose only the identity value needed for prompt listing. GoDoc will own the
|
|
exact signatures and behavior when implemented. Callers can pass the returned
|
|
identities to `InspectProfile`, `InspectPrompt`, or their execution requests.
|
|
Bulk inspection results, prompt text, execution targets, source provenance,
|
|
and credential information do not belong in these results.
|
|
|
|
### Effective Captured Inventory
|
|
|
|
List the identities present in the engine's final captured configuration,
|
|
including maintained catalog profiles and consumer-defined profiles and
|
|
prompts after ConfigKit layering and inheritance. A profile's configured alias
|
|
or inherited identity remains its own list entry, not its base profile's name.
|
|
Historical or superseded contributions do not create additional entries.
|
|
|
|
Each effective profile ID appears once. Each effective prompt ID/version pair
|
|
appears once, including every configured version of a multi-version prompt.
|
|
Listing does not choose a default or latest version; the existing omitted-version
|
|
selection behavior remains unchanged.
|
|
|
|
Preserve exact identifier spelling. Return profiles in ascending lexical ID
|
|
order and prompts in ascending lexical ID order, then lexical version order.
|
|
Version ordering is for deterministic presentation, not semantic-version
|
|
comparison or a recommendation about which version to execute.
|
|
|
|
### Lightweight Snapshot Read
|
|
|
|
Listing reads the engine's captured identity indexes. It does not reload sources
|
|
or files, analyze configuration provenance, resolve credentials, read artifacts
|
|
or schemas, render, acquire backend capacity, or contact providers.
|
|
|
|
A profile need not be execution-ready to be listed. Presence in the inventory
|
|
does not promise valid credentials, provider availability, or successful
|
|
execution. Catalog entries remain subject to the existing
|
|
[catalog compatibility policy](../policy/release.md#catalog-profile-compatibility).
|
|
|
|
Returned slices are caller-owned; modifying one result cannot change the
|
|
engine or later results. Listing supports concurrent engine use without adding
|
|
mutable registry state. An empty inventory is a successful result. A nil engine
|
|
uses `ErrInvalidConfig`, and cancellation preserves the context error under the
|
|
existing inspection conventions.
|
|
|
|
## Work Needed From The Baseline
|
|
|
|
- Add identity-only enumeration to the captured configuration adapter and route
|
|
it through the internal engine to the public facade. Keep internal
|
|
representations behind the existing package boundary.
|
|
- Add the two public methods and the small prompt identity value, with GoDoc.
|
|
Avoid obtaining each item's full inspection or copying profile parameters
|
|
and prompt content merely to list its identity.
|
|
- Keep traversal and allocation proportional to the inventory returned.
|
|
Prefer straightforward reuse of captured indexes; ordering can be prepared
|
|
during construction rather than repeatedly sorting unchanged identities.
|
|
Exact storage layouts and allocation counts are implementation choices.
|
|
- Add focused tests for effective inventory membership, multiple prompt
|
|
versions, literal identities and ordering, caller ownership, empty results,
|
|
and the selected error/cancellation behavior. Include a representative public
|
|
workflow that lists entries and inspects a returned identity. Reuse existing
|
|
construction coverage rather than retesting ConfigKit's resolution machinery.
|
|
- Add concise listing guidance to the consumer guide and update the relevant
|
|
internal documentation when implemented. Preserve existing inspection and
|
|
execution contracts.
|
|
|
|
Backend enumeration, filtering, pagination, runtime registration, and live
|
|
catalog/provider discovery are outside this feature's scope. No new caller
|
|
limits, readiness checks, release gates, or performance guarantees are needed.
|
|
|
|
## Completion
|
|
|
|
Consumers can enumerate effective profiles and exact prompt versions through
|
|
the public facade, obtain independent deterministic results, and use those
|
|
identities with existing operations. Verification follows the
|
|
[testing policy](../policy/testing.md), including focused ownership and
|
|
concurrent-use checks proportionate to the implementation. Current documentation
|
|
describes the implemented API without duplicating ConfigKit history semantics.
|