9.6 KiB
Prompt input requirements for Narratio
Status: the native interface and focused consumer scenarios are implemented. The implementation plan tracks final assembled verification. This proposal records Narratio's consumer needs and their mapping to the native interface; the CLI contract owns current behavior. The CommandKit notepad records the migration decisions.
Consumer need
Narratio produces transcripts, extraction outputs, and generated artifacts in
a staged pipeline. It binds named inputs to a Scriptorium prompt when generating
each analysis artifact. A Narratio source ID and a prompt input name are separate
identities: for example, the source
narratio.transcript.final_trimmed_markdown might be supplied under the prompt
input name transcript.
Narratio needs to discover expected input names before running expensive upstream stages and before the eventual input files exist. It can then show operators how prompt inputs map to pipeline products and identify missing bindings without reading prompt definitions or reproducing PromptKit's analysis.
Selected native operation
Expose scriptorium promptkit requirements show PROMPT_ID through ckprompt.
Subprocess consumers select JSON with the standard --format json flag.
Default and explicit text output use the native YAML presentation.
The upstream CLI contract owns syntax and report details.
Use the same application configuration and framework source selection as
execution, including --config and --overlay. There are no application-defined
source/schema selectors. The preferred native aliases --profile, --var, --session-id, and
prompt/profile namespace flags supply the relevant discovery context.
Preserve upstream selection semantics, including the prompt's default profile
when an explicit profile is omitted. Qualified IDs identify installed resources;
there is no separate prompt-version selector or reported prompt-version field.
The selected profile establishes identity, not execution readiness. Selecting another profile does not itself change the prompt's discovered requirements. Scriptorium's loading and request mapping must preserve the same effective selection and applicable caller context across discovery and execution.
Discovery requires no input bindings or output-artifact path. PromptKit performs no artifact loading, schema loading, credential resolution, message rendering, capacity reservation, or model call for this operation. Reading configuration and prompt resources needed to build the captured engine is expected. The PromptKit discovery contract owns the analysis and its limits.
Native response and consumer interpretation
Consume the native JSON report directly, without a Scriptorium-specific wrapper or schema-version field. Successful report delivery writes one JSON document to stdout, with diagnostics on stderr under CommandKit's standard reporting rules. Consumers requesting a report should not enable quiet mode.
| Field | Consumer meaning |
|---|---|
prompt_id, profile_id |
Exact selected resource identities. |
inputs |
Declared and recognizable template-referenced inputs, including exact name, requirement kind, declared, content_type, description, and explanation. |
variables |
Recognizable caller-variable keys with name, requirement kind, supplied, and explanation. |
complete |
Whether the supported dependency analysis is complete for the supplied context. |
issues |
Structured discovery limitations with a code, associated input or variable names where known, and a human-readable description. |
PromptKit sorts input and variable entries by exact name, and deduplicates and orders issues by their code and associated names. Preserve empty inventories and false values. Input metadata distinguishes absent/null values from an explicitly empty string. Explanations and issue descriptions are for display; Narratio must use structured fields rather than parse their prose.
The native input metadata includes content type and description. Current
PromptKit inputs have no per-input schema declaration to project. Do not infer
constraints from names or treat the output-validation schema as an input schema.
Variable supplied records exact-key presence, including an explicitly empty
value; this interface does not introduce a separate variable-default system.
Requirements reports exclude artifact payloads, prompt contents, and unrelated supplied variable values. A supplied value used to resolve an input identifier can appear as that identifier. Keep this native behavior without adding a custom projection of the report.
The upstream report contract and adopted dependency versions govern the shape. Migration documentation must identify relevant consumer changes; this proposal adds no independent response-versioning mechanism or stronger compatibility guarantee.
Conditional and incomplete discovery
PromptKit classifies dependencies as required, optional, or conditional using the supplied context and its supported template analysis. Recognizable references only on known skipped paths can be optional. Explicit required declarations still apply. Unavailable input contents, unresolved variable values or dynamic names, and unsupported dependency-relevant constructs can leave discovery incomplete. Valid templates are not rejected merely because the analysis cannot fully resolve them.
Narratio must inspect both the requirements and discovery completeness:
complete: trueestablishes discovery coverage, not satisfied bindings, valid future input bytes, or execution readiness. Required inputs or missing required variables may still be present.complete: falsepreserves useful findings and structured issues. An empty partial inventory does not prove that no inputs are needed.- A partial report can return status zero. An issue is not itself an invocation failure. Narratio owns its policy for proceeding with incomplete dependency information.
Once input artifacts exist, native promptkit requirements validate can check
a concrete request through preparation. It is a separate operation and must not
replace early discovery. Neither operation guarantees later generation success.
Changes to configuration or resources between invocations can change findings.
Failures
Use CommandKit's native nonzero outcomes and diagnostic messages for selection, configuration, operational, and report-delivery failures. JSON report selection does not turn diagnostic messages into a categorized JSON error response. Narratio can attach the diagnostic to its own artifact or pipeline context; it must not depend on parsing the message to recover a stable error category.
Structured discovery issue codes belong to successful inspection reports and are distinct from invocation failures. Follow PromptKit's distinction between partial discovery and failures that return no inspection. Absence of a future input artifact is not a discovery failure because discovery does not load it.
The accepted consumer requirement is a nonzero return code plus failure information. If programmatic failure categories or separate schema versioning become necessary, discuss them upstream rather than introducing local wrappers. Neither is a prerequisite for this migration.
Consumer acceptance scenarios
- A prompt requires
transcript, but Narratio binds onlysession_transcript. The native inventory identifies the exact required name before either file exists, allowing Narratio to identify the missing binding. - A template references an undeclared input. Recognizable references appear in
the inventory with
declared: false; unsupported dependency analysis is explicitly incomplete rather than silently claiming full coverage. - An optional glossary is reported with its native classification, allowing Narratio to distinguish it from a required binding.
- Variables resolve a supported conditional dependency. Unknown conditions retain conditional findings or discovery issues according to PromptKit.
- Selecting another qualified prompt or profile reports the corresponding identities. Prompt selection changes the analyzed definition; profile selection alone does not change its requirements.
- Discovery works with no generated input files, model access, or generation credentials when the selected configuration and resources are readable and valid for discovery.
- An unknown prompt or invalid profile selection returns nonzero with native diagnostics suitable for Narratio to associate with the affected artifact.
- Narratio treats a complete report with missing required bindings differently from a complete, satisfied dependency check, and handles partial reports without assuming that status zero establishes completeness.
- Scriptorium's adapter uses consistent configuration, namespaces, and applicable request context across discovery, validation, preview, and execution.
Scope boundary
Narratio owns its source catalog, stage ordering, source-to-input bindings, artifact dependency graph, and session availability checks. Scriptorium exposes PromptKit's native requirements through CommandKit. Narratio source IDs and pipeline concepts do not become part of that interface. A graph renderer, HTTP endpoint, batch operation, and changes to generation behavior are outside this request.