2026-11-19 18:16:28 +00:00
|
|
|
# Prompt input requirements for Narratio
|
2026-10-04 17:15:59 +00:00
|
|
|
|
2026-11-20 05:17:05 +00:00
|
|
|
Status: the native interface and consumer acceptance scenarios are implemented
|
|
|
|
|
and verified, including the assembled collection workflow. The
|
|
|
|
|
[implementation plan](implementation.md) records the verification evidence.
|
2026-11-20 05:08:40 +00:00
|
|
|
This proposal records Narratio's consumer needs and their mapping to the native
|
|
|
|
|
interface; the [CLI contract](../cli.md) owns current behavior.
|
2026-11-19 18:16:28 +00:00
|
|
|
The [CommandKit notepad](commandkit-notepad.md) records the migration decisions.
|
2026-10-04 17:15:59 +00:00
|
|
|
|
|
|
|
|
## 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`.
|
|
|
|
|
|
2026-11-19 18:16:28 +00:00
|
|
|
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][requirements-cli] owns syntax and report details.
|
|
|
|
|
|
|
|
|
|
Use the same application configuration and framework source selection as
|
2026-11-20 05:08:40 +00:00
|
|
|
execution, including `--config` and `--overlay`. There are no application-defined
|
|
|
|
|
source/schema selectors. The preferred native aliases `--profile`, `--var`, `--session-id`, and
|
2026-11-19 18:16:28 +00:00
|
|
|
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][requirements-api] 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: true` establishes discovery coverage, not satisfied bindings,
|
|
|
|
|
valid future input bytes, or execution readiness. Required inputs or missing
|
|
|
|
|
required variables may still be present.
|
|
|
|
|
- `complete: false` preserves 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.
|
2026-10-04 17:15:59 +00:00
|
|
|
|
|
|
|
|
## Consumer acceptance scenarios
|
|
|
|
|
|
|
|
|
|
1. A prompt requires `transcript`, but Narratio binds only `session_transcript`.
|
2026-11-19 18:16:28 +00:00
|
|
|
The native inventory identifies the exact required name before either file
|
|
|
|
|
exists, allowing Narratio to identify the missing binding.
|
|
|
|
|
2. 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.
|
|
|
|
|
3. An optional glossary is reported with its native classification, allowing
|
|
|
|
|
Narratio to distinguish it from a required binding.
|
|
|
|
|
4. Variables resolve a supported conditional dependency. Unknown conditions
|
|
|
|
|
retain conditional findings or discovery issues according to PromptKit.
|
|
|
|
|
5. Selecting another qualified prompt or profile reports the corresponding
|
|
|
|
|
identities. Prompt selection changes the analyzed definition; profile
|
|
|
|
|
selection alone does not change its requirements.
|
|
|
|
|
6. Discovery works with no generated input files, model access, or generation
|
|
|
|
|
credentials when the selected configuration and resources are readable and
|
|
|
|
|
valid for discovery.
|
|
|
|
|
7. An unknown prompt or invalid profile selection returns nonzero with native
|
|
|
|
|
diagnostics suitable for Narratio to associate with the affected artifact.
|
|
|
|
|
8. 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.
|
|
|
|
|
9. Scriptorium's adapter uses consistent configuration, namespaces, and applicable
|
|
|
|
|
request context across discovery, validation, preview, and execution.
|
2026-10-04 17:15:59 +00:00
|
|
|
|
|
|
|
|
## Scope boundary
|
|
|
|
|
|
|
|
|
|
Narratio owns its source catalog, stage ordering, source-to-input bindings,
|
2026-11-19 18:16:28 +00:00
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
[requirements-cli]: https://forge.maximumdirect.net/base-layer/commandkit/src/commit/d330d7637f2e7507eca931a899397222c82bc892/docs/cli.md#promptkit-requirements
|
|
|
|
|
[requirements-api]: https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/requirements.go
|