Files
scriptorium/docs/roadmap/narratio-feature-request.md

169 lines
9.6 KiB
Markdown

# Prompt input requirements for Narratio
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.
This proposal records Narratio's consumer needs and their mapping to the native
interface; the [CLI contract](../cli.md) owns current behavior.
The [CommandKit notepad](commandkit-notepad.md) 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][requirements-cli] 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][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.
## Consumer acceptance scenarios
1. A prompt requires `transcript`, but Narratio binds only `session_transcript`.
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.
## 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.
[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