152 lines
7.1 KiB
Markdown
152 lines
7.1 KiB
Markdown
# Notarius Configuration Profile Selection
|
|
|
|
Status: Implemented.
|
|
|
|
## Goal and Authority
|
|
|
|
Implement the consumer behavior in the
|
|
[feature request](feature-request-notarius-config-profile.yml): let a Narratio
|
|
configuration overlay explicitly select a Notarius configuration overlay.
|
|
Operators can select testing once in Narratio while each application retains
|
|
ownership of its own model choices and other settings.
|
|
|
|
This roadmap describes the target state and required change areas, not an
|
|
implementation sequence; the [implementation plan](implementation.md) owns
|
|
the ordered work and implementation decisions. The feature request is the scope
|
|
authority; the mechanisms suggested below do not establish additional
|
|
user-facing contracts.
|
|
|
|
## Underlying Issue
|
|
|
|
Narratio can select its own testing profile, but extraction currently invokes
|
|
Notarius without a configuration-profile selector. Consequently, a Narratio
|
|
testing invocation cannot explicitly select the independently deployed Notarius
|
|
testing overlay through pipeline configuration.
|
|
|
|
Adding individual downstream model or tuning fields would duplicate Notarius's
|
|
configuration responsibilities. Passing its existing profile selector provides
|
|
the requested flexibility without that duplication.
|
|
|
|
## Targeted End State
|
|
|
|
### Explicit Configuration Composition
|
|
|
|
`pipeline.notarius.config_profile` is an optional Notarius configuration-profile
|
|
name, usable in Narratio's base configuration and ordinary overlays. For
|
|
example, Narratio's `profiles/testing.yml` may contain:
|
|
|
|
```yaml
|
|
notarius:
|
|
config_profile: testing
|
|
```
|
|
|
|
Selecting Narratio's `--profile testing` then selects that explicit downstream
|
|
profile whenever extraction executes. The two profile names need not match.
|
|
Narratio does not automatically forward its own profile name.
|
|
|
|
When supplied, the selection is passed through Notarius's `--config-profile`
|
|
argument. Omitted or null values add no profile-selection flag and preserve
|
|
existing downstream selection behavior. Notarius's selector semantics remain
|
|
authoritative, including empty and `default` selections for the composed base
|
|
configuration. Narratio does not introduce a stricter profile-name policy.
|
|
|
|
This field selects a ConfigKit configuration overlay, not a PromptKit profile
|
|
through `--llm-profile`. The Notarius overlay owns any resulting LLM-profile
|
|
selection. Notarius resolves overlays relative to its own configuration root;
|
|
Narratio neither resolves those files against its own root nor rewrites them.
|
|
|
|
### Execution, Reuse, and Failure
|
|
|
|
A changed downstream profile selection must not silently reuse Narratio's
|
|
completed extraction from the previous selection. Existing dependent-stage
|
|
invalidation applies when extraction changes; the feature does not change the
|
|
pipeline order or transcript-generation behavior.
|
|
|
|
Notarius continues to own downstream overlay discovery, composition, validation,
|
|
and cache compatibility. A missing or invalid selected overlay must fail
|
|
extraction through the existing subprocess error path, without silently falling
|
|
back to production or reporting successful extraction.
|
|
|
|
Existing resume and chunk-cache controls, including force precedence, remain
|
|
in place. Profile selection does not itself mean forced regeneration or cache
|
|
deletion. Narratio's decision to execute extraction and Notarius's decision to
|
|
reuse compatible work remain separate responsibilities.
|
|
|
|
Changes to private Notarius configuration behind an unchanged selector retain
|
|
the existing operator responsibility to force extraction when needed. There is
|
|
no new downstream file inspection or content-tracking requirement.
|
|
|
|
Credential forwarding remains independently configured through
|
|
`notarius.llm_api_key`. A Narratio testing overlay may select a different
|
|
credential reference alongside the downstream profile; no new credential
|
|
discovery or provider-name mapping is introduced.
|
|
|
|
## Required Change Areas
|
|
|
|
### Configuration and Inspection
|
|
|
|
Extend the typed Notarius configuration and its existing safe effective-YAML
|
|
projection to carry the optional field. Preserve the ordinary configuration
|
|
composition behavior for base values, overlay overrides, and null values.
|
|
Configuration inspection must reflect the selected field without exposing
|
|
credential values. No replacement configuration loader or downstream preflight
|
|
loader is needed.
|
|
|
|
### Stage and Adapter Boundary
|
|
|
|
Carry the selection from resolved configuration through the extraction request
|
|
to the subprocess adapter. Construct the optional CLI flag using the existing
|
|
argument-vector mechanism, alongside the current configuration path, references,
|
|
credential forwarding, and cache controls. Retain normal Notarius error handling.
|
|
|
|
### Extraction Reuse Evidence
|
|
|
|
Account for the downstream selection in the existing extraction reuse evidence.
|
|
The current semantic-configuration and invocation fingerprints are the relevant
|
|
change points. Keep their treatment of selection consistent so that a profile
|
|
change cannot bypass the required rerun and downstream invalidation.
|
|
|
|
This roadmap does not require a new manifest schema, separate profile-indexed
|
|
workspaces, historical per-profile result retention, or an upgrade-wide forced
|
|
rerun.
|
|
|
|
### Verification and Documentation
|
|
|
|
Use focused behavioral coverage for configuration composition and inspection,
|
|
explicit argument forwarding and omission, changed-selection reuse decisions,
|
|
and ordinary subprocess failure handling. Reuse existing test coverage where
|
|
it already protects unchanged credentials, force behavior, and invalidation;
|
|
do not duplicate Notarius's complete profile-validation or cache test suites.
|
|
|
|
When implemented, update the canonical
|
|
[configuration reference](../config.md),
|
|
[Notarius integration contract](../integrations/notarius.md),
|
|
[extract internals](../internal/stage-extract.md), and relevant maintained
|
|
examples. The development workflow in [Operations](../operations.md) should
|
|
explain explicit profile composition and the existing need to force extraction
|
|
after private downstream edits. Clarify that profile selection does not create
|
|
an isolated testing workspace or separate current extraction state.
|
|
|
|
## Compatibility and Scope Boundaries
|
|
|
|
Notarius v0.7.0 already documents `--config-profile`; no upstream change is
|
|
required. Document the capability needed when the option is used, without adding
|
|
an unconditional runtime version gate for existing unconfigured deployments.
|
|
|
|
This feature adds no Narratio CLI selector, automatic profile propagation,
|
|
Notarius LLM-profile selector, downstream configuration rewriting, new
|
|
credential mechanism, or generalized recursive orchestration. Existing output
|
|
and receipt contracts remain unchanged.
|
|
|
|
The consumer's Ansible role and suite updates are follow-up work outside this
|
|
repository. They can deploy downstream overlays and populate this field after
|
|
the interface is released.
|
|
|
|
## Scope Review
|
|
|
|
No stronger requirements or new invariants are proposed beyond the feature
|
|
request and existing repository contracts. In particular, minimizing one-time
|
|
upgrade invalidation and avoiding reruns between equivalent base selectors are
|
|
implementation considerations, not additional acceptance guarantees imposed
|
|
by this roadmap. No user decisions are currently required before planning.
|