base-layer/promptkit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 4 Wiki Activity

Expand backend roadmap with configuration API recommendations

Browse Source
This commit is contained in:
Eric Rakestraw
2026-11-06 02:40:56 +00:00
parent d7007eb072
commit ffaaf552c8
1 changed files with 97 additions and 13 deletions
Download Patch File Download Diff File Expand all files Collapse all files

110
docs/roadmap/inspect-backend.md
View File

@@ -1,10 +1,13 @@
# Backend Inspection Roadmap
# Backend Inspection And Configuration API Roadmap
## Purpose And Status
Add `Engine.InspectBackend` so applications can retrieve one backend's effective
definition by its runtime identity. The direction is accepted for planning;
implementation has not begun. The open decisions below remain to be resolved.
definition by its runtime identity, and expose existing backend inheritance
through `BackendConfig` and `BackendSource`. These additions are selected for
planning; implementation has not begun. The open decisions below remain to be
resolved. Typed prompt construction is a separate discussion item, and listing
return-type consistency is a possible later cleanup.
The consumer benefit is backend-detail reporting without selecting an arbitrary
profile or reconstructing domain settings from ConfigKit paths and list indexes.
@@ -13,9 +16,10 @@ capacity settings, provider defaults, and diagnostic configuration. Promptkit
owns this reusable interpretation; downstream applications own presentation,
disclosure, CLI commands, and exit codes.
API symmetry alone does not justify the addition. The scope is a small typed
view over captured information that Promptkit already owns, with no new source
composition, validation framework, or execution lifecycle.
API symmetry alone does not justify additions. Prioritize backend inspection
with the recommended missing-backend error, followed by typed backend
inheritance. Both expose behavior or information Promptkit already owns, with
no new source composition, validation framework, or execution lifecycle.
## Relationship To Existing APIs
@@ -31,7 +35,7 @@ See the [consumer guide](../consumers/pkg-promptkit.md#discover-available-resour
for the implemented inspection and discovery boundaries, and the
[architecture policy](../policy/architecture.md) for library responsibilities.
## Proposed Public Contract
## Proposed Backend Inspection Contract
```go
func (e *Engine) InspectBackend(
@@ -103,6 +107,57 @@ credentials or silently substitute ConfigKit's redacted reporting values for
the typed settings. Operator provenance and redacted configuration reporting
remain available through `InspectConfiguration`.
## Typed Backend Inheritance
Add `Extends *string` to `BackendConfig`, matching `ProfileConfig.Extends`.
When non-nil, `BackendSource` should encode it as `extends: {id: value}` in the
backend record. Nil omits the field. Preserve the supplied value and let
ConfigKit resolve and validate inheritance through the existing source-loading
path, just as it does for profiles.
The purpose is to let programmatic callers derive a backend variant without
switching from `BackendSource` to a raw mapping. The helper must not resolve a
parent, fill inherited fields, or become a second inheritance implementation.
It remains a source constructor rather than an engine registry mutation API.
This exposes existing sibling inheritance, not a new configuration feature.
Parent IDs select siblings in the same root or collection resource list;
namespace views do not qualify these configuration references. Existing
same-ID replacement, omitted-field, and explicit-null behavior remain owned by
ConfigKit composition. Raw mappings remain available when callers need explicit
null or other generic configuration controls that the typed helper cannot express.
See the [inheritance reference](../formats.md#resource-inheritance) and the
existing [profile source helper](../../profiles.go).
## Scope Of API Consistency
Backends, profiles, and prompts already share source layering, collection
membership, namespace selection, sibling inheritance, and construction-time
definition validation. The gaps addressed here are in public convenience and
inspection APIs, not in those underlying configuration capabilities.
Inspection remains purpose-specific: `InspectPrompt` reports prompt interface
metadata, `InspectProfile` reports backend-completed execution settings, and
`InspectBackend` will describe an effective backend. This work does not turn
them into uniform complete-definition retrieval APIs. Expanding prompt inspection
to return descriptions, message templates, or session templates should follow a
concrete consumer need rather than the new backend result's shape.
`ListPrompts` currently returns `[]PromptIdentity`, whose only field is `ID`;
`ListProfiles` and `ListBackends` return `[]string`. At a suitable breaking-change
window, prefer considering `[]string` for all three over adding thin identity
wrappers for backends and profiles. That would simplify consumer code, but
requires a deliberate compatibility decision and migration instructions. Keep
the existing return types in this work; listing consistency does not block the
backend additions.
Collections, schemas, and engine configuration remain distinct concepts rather
than additional peers requiring identical resource APIs. Prompt requirement
inspection and backend capacity/diagnostic settings retain their specialized
roles. Profile/backend hashes are not added for symmetry; the existing
[deferred fingerprint proposal](deferred.md#semantic-execution-target-fingerprints)
owns that separate question.
## Open Decisions
### 1. Declared Diagnostic Settings Or Derived Destinations?
@@ -143,9 +198,29 @@ invalid selection. Consumers needing different presentation would then require
an inventory lookup or additional error detail. A sentinel is the smaller
consumer-facing solution when that distinction matters.
### 3. Should Typed Prompt Construction Be Added In This Round?
**Recommendation:** Keep `PromptConfig` and `PromptSource` as a separate
discussion item until a programmatic prompt-authoring use case establishes
their value. File sources and ConfigKit mappings already support prompt
definitions. The absence of a helper is a Go convenience gap, not a missing
configuration capability, and does not block the backend additions.
**Alternative:** Add a typed prompt source alongside the existing backend and
profile helpers. It would improve discoverability, compiler assistance, and
consistency for applications constructing prompts in Go. Its cost is a larger
public input model covering messages, inline/file content, inputs, output
contracts, session templates, and omission semantics. If selected, define that
scope separately, including sibling inheritance and source context for relative
content files, while retaining ConfigKit's ownership of composition and raw
mapping support for explicit null. Do not implement a second prompt parser or
validation path merely to provide the helper.
## Implementation Scope And Verification
1. Resolve the two public-contract decisions and define the result and GoDoc.
1. Resolve backend inspection decisions 1–2 and define the result and GoDoc.
Decide separately whether to expand this round for typed prompt construction;
the recommended backend scope does not depend on that expansion.
2. Connect namespace-aware engine selection to the existing captured backend
lookup and project the result at the public facade. Introduce only the
private collaborators needed for this path; no new backend cache or loader.
@@ -155,15 +230,24 @@ consumer-facing solution when that distinction matters.
Cover a missing smoke default profile and absent credential environment
variable to establish that inspection does not perform execution readiness
checks. Use controlled local fixtures; no live provider calls are needed.
4. Update the consumer guide and relevant internal documentation when the API
4. Add `BackendConfig.Extends` and encode it through `BackendSource`. Verify
an inherited backend through real ConfigKit composition, including an
overridden field and a retained parent field. Reuse existing inheritance
coverage for generic missing-parent, cycle, and replacement semantics rather
than retesting ConfigKit's entire feature set.
5. Update the consumer guide and relevant internal documentation when the API
lands, with a short `ListBackends` followed by `InspectBackend` example.
Record the additive API and selected error behavior in release notes.
Include typed backend inheritance guidance. Record the additive APIs and
selected error behavior in release notes.
Reuse meaningful existing namespace, configuration, and ownership coverage;
avoid tests that merely mirror private projection helpers. Run checks appropriate
to the implementation under the [testing policy](../policy/testing.md).
Completion means consumers can inspect a backend without selecting a profile or
navigating raw configuration, while existing execution, inspection, diagnostic,
and configuration-composition behavior remains intact. No separate provider
capability registry, live capacity monitor, or backend health API is included.
navigating raw configuration, and derive a backend through the typed source
helper without constructing a raw mapping. Existing execution, inspection,
diagnostic, and configuration-composition behavior remains intact. No separate
provider capability registry, live capacity monitor, or backend health API is
included. Typed prompt construction and listing return-type changes are not
completion requirements for the selected backend scope.