153 lines
6.7 KiB
Markdown
153 lines
6.7 KiB
Markdown
# Application Fallback Profiles
|
|
|
|
Status: Selected for implementation.
|
|
|
|
## Purpose
|
|
|
|
Promptkit will allow a consuming application to supply an embedded fallback
|
|
profile source below operator-configured profiles and above Promptkit's
|
|
built-in profile catalog.
|
|
|
|
This gives consumers stable, application-owned profile IDs with useful
|
|
packaged defaults while preserving the existing ability for an operator to
|
|
replace those definitions. Promptkit will own the reusable source layer and
|
|
lookup semantics without owning downstream profile names, model assignments,
|
|
or application configuration policy.
|
|
|
|
## Consumer Outcome
|
|
|
|
A consumer such as Weatherreporter can embed profiles named for application
|
|
workloads or execution tiers, such as `weather-light`, `weather-balanced`, and
|
|
`weather-deep`. Prompts can select those logical IDs without coupling the
|
|
application to a particular provider or model.
|
|
|
|
An operator can define the same profile ID in the application's ordinary
|
|
configured profile source to replace the packaged default. If no operator
|
|
definition exists, Promptkit resolves the application's embedded definition.
|
|
If neither source contains the ID, Promptkit retains access to its own built-in
|
|
profile catalog.
|
|
|
|
## Scope
|
|
|
|
Promptkit will add one optional `fs.FS`-backed application fallback profile
|
|
source to engine construction. The intended public surface is:
|
|
|
|
```go
|
|
promptkit.WithFallbackProfileFS(profileFS, ".")
|
|
```
|
|
|
|
The source will use the existing profile YAML format, discovery behavior,
|
|
strict decoding, validation rules, and credential restrictions. The option
|
|
will accept a non-nil filesystem and nonblank root. Repeating the option will
|
|
follow Promptkit's same-category convention: the last valid value replaces the
|
|
earlier fallback source, while an invalid option still fails construction when
|
|
it is applied.
|
|
|
|
No programmatic fallback-profile option is included. Consumers that need the
|
|
new precedence relationship can embed YAML assets, while `WithProfiles`
|
|
continues to serve the distinct highest-precedence in-memory use case.
|
|
|
|
## Profile Selection And Source Precedence
|
|
|
|
Profile ID selection remains separate from profile definition lookup. An
|
|
explicit request profile ID continues to take precedence over a prompt's
|
|
`default_profile`. After an ID has been selected, matching definitions resolve
|
|
in this order:
|
|
|
|
1. in-memory profiles supplied through `WithProfiles`;
|
|
2. the ordinary configured profile source selected through `WithProfileFile`,
|
|
`WithProfileFS`, or `Config.ProfileDir`;
|
|
3. the application fallback profile source; and
|
|
4. Promptkit's embedded built-in profiles.
|
|
|
|
A higher-precedence source falls through only when the requested profile ID is
|
|
absent. An unreadable, malformed, duplicate, ambiguous, or otherwise invalid
|
|
matching definition is an error and does not permit lookup in a lower layer.
|
|
Profiles are selected as complete values; sources do not merge fields or
|
|
inherit from one another.
|
|
|
|
The fallback source remains lazily read and validated when a requested ID
|
|
reaches that layer. This feature does not introduce engine-wide eager source
|
|
validation, and an unrelated malformed asset does not acquire stronger
|
|
validation guarantees than it has in an ordinary profile source.
|
|
|
|
## Consistent Engine Behavior
|
|
|
|
The engine will assemble one profile repository with the complete precedence
|
|
chain. Exact profile inspection, ordinary preparation, prepared execution, and
|
|
ordinary execution will all use that same repository and therefore observe the
|
|
same definition for a given profile ID.
|
|
|
|
Exact profile inspection remains side-effect free and does not contact a model
|
|
provider. Existing public error identities remain applicable to cancellation,
|
|
profile-not-found and profile-load failures, invalid fallback definitions,
|
|
credential resolution, and unknown backends. The feature does not add a new
|
|
fallback-specific public error category.
|
|
|
|
Internally, the root facade will own composition of all profile-source layers.
|
|
The application fallback is another use of the profile repository's existing
|
|
error-preserving overlay semantics; it is not a separate profile-loading or
|
|
validation implementation.
|
|
|
|
## Compatibility
|
|
|
|
The feature is additive. An engine that does not configure an application
|
|
fallback source retains its current behavior and profile precedence. Existing
|
|
uses of `Config.ProfileDir`, `WithProfileFile`, `WithProfileFS`, and
|
|
`WithProfiles` keep their meanings.
|
|
|
|
The application fallback is deliberately below every existing
|
|
consumer-configured profile source. An ordinary configured profile therefore
|
|
continues to override any packaged definition with the same ID. A missing or
|
|
invalid configured source also retains its current behavior; the new layer
|
|
does not turn configuration failures into silent fallthrough.
|
|
|
|
## Ownership Boundaries
|
|
|
|
Promptkit owns:
|
|
|
|
- the additional source layer and its construction option;
|
|
- deterministic lookup and fallthrough semantics;
|
|
- use of the existing profile format, validation, and public error mapping;
|
|
- consistent repository use across inspection, preparation, and execution;
|
|
and
|
|
- canonical public, format, consumer, and contributor documentation for the
|
|
implemented capability.
|
|
|
|
The consuming application owns:
|
|
|
|
- whether to supply a fallback source;
|
|
- application-specific profile IDs and their domain meaning;
|
|
- embedded profile contents, backend selections, and model choices;
|
|
- application configuration discovery and operator override policy;
|
|
- assignment of profiles to reports or other workloads; and
|
|
- credential policy and operator-facing error presentation beyond Promptkit's
|
|
public contract.
|
|
|
|
## Non-Goals
|
|
|
|
This scope does not add:
|
|
|
|
- downstream-specific profiles to Promptkit's built-in catalog;
|
|
- profile inheritance, aliases, or field-level merging;
|
|
- provider failover after a selected profile or generation attempt fails;
|
|
- automatic endpoint discovery, probing, benchmarking, or tier selection;
|
|
- application configuration discovery;
|
|
- eager validation of every profile in every source;
|
|
- source-provenance fields in profile inspection or preparation results; or
|
|
- an in-memory companion to `WithFallbackProfileFS`.
|
|
|
|
## Target End State
|
|
|
|
The feature is complete when a consumer can embed an application fallback
|
|
profile source through the root facade and rely on the documented four-layer
|
|
precedence everywhere profiles are resolved. Operator definitions override
|
|
application defaults, application defaults override Promptkit built-ins,
|
|
invalid matching definitions never silently fall through, and engines that do
|
|
not use the new option remain behaviorally compatible.
|
|
|
|
The implemented public option and precedence contract will be owned by GoDoc
|
|
and the framework format reference. Consumer guidance will show the embedded
|
|
application-default workflow without making this temporary roadmap a second
|
|
current-state reference.
|