92 lines
3.8 KiB
Markdown
92 lines
3.8 KiB
Markdown
# Audita Modules
|
|
|
|
## Scope
|
|
|
|
This document covers internal module contracts and packages. User-selectable keys
|
|
and the default sequence belong to [configuration](../config.md#settings).
|
|
|
|
## Module Contract
|
|
|
|
Modules implement `contracts.TranscriptModule`:
|
|
- `Key()`
|
|
- `ReplacementPolicy()`
|
|
- `Validators()`
|
|
- `Propose(ctx, req)`
|
|
|
|
Runner resolves configured module specs to module instances through `internal/framework/modules`.
|
|
|
|
## Built-In Modules
|
|
|
|
Current module packages:
|
|
- `internal/modules/glossary`
|
|
- `internal/modules/homophones`
|
|
- `internal/modules/spoken_word`
|
|
- `internal/modules/grammar`
|
|
|
|
Current replacement policies:
|
|
- `glossary`: `replace_all`
|
|
- `homophones`: `require_unique`
|
|
- `spoken_word`: `require_unique`
|
|
- `grammar`: `require_unique`
|
|
|
|
## Proposal Generation Ownership
|
|
|
|
Shared proposal-generation plumbing is centralized in:
|
|
- `internal/framework/proposal_generation`
|
|
|
|
Module packages own:
|
|
- prompt selection (`internal/prompts` prompt IDs).
|
|
|
|
`proposal_generation.BuildProposalVariables` encodes the glossary, selected
|
|
transcript section, and trimmed description once for all four modules. PromptKit
|
|
renders their embedded definitions from those variables and validates the
|
|
correction-set schema before Audita maps proposals. Domain validators still
|
|
check confidence, applicability, protected glossary terms, and replacement
|
|
policy. Model-facing segment IDs are one-based positions within the proposal
|
|
request. Generation maps returned references back to the current chunk's actual
|
|
segment IDs, preserving response order and multiple proposals per segment.
|
|
Unknown references become invalid-target candidates for the existing domain
|
|
checks; they are never interpreted as actual transcript IDs. Debug request
|
|
metadata records `segment_ids` in local-reference order (reference 1 is the
|
|
first entry). Shared context encoding lives in `internal/framework/promptcontext`.
|
|
An empty `corrected_text` deletes the identified span when the resulting segment
|
|
remains nonblank. Whitespace-only original spans can express spacing corrections;
|
|
matching stays literal under each module's replacement policy. No automatic
|
|
whitespace cleanup follows application.
|
|
|
|
## Validator Chain Ownership
|
|
|
|
Built-in chains are resolved in `internal/validators` per module key.
|
|
Module packages call the built-in chain resolver at construction.
|
|
|
|
## Failure and Outcome Behavior
|
|
|
|
Module construction failures are fatal. Recoverable proposal model failures
|
|
record an unsuccessful operation and yield no candidates for that section;
|
|
other sections and module instances continue. Fatal adapter or application
|
|
failures cancel peers and retain partial observations. Consumer-visible
|
|
outcomes are defined by the [report contract](../integrations/output-files.md).
|
|
|
|
## Changing Modules
|
|
|
|
1. Add or update the narrowly scoped package under `internal/modules/<module_key>`.
|
|
2. Keep module prompt selection in the module and its definition in
|
|
`internal/prompts`; see [prompt assets](prompts.md).
|
|
3. Wire module registration and catalog resolution through framework module
|
|
registration and the core module catalog. Update selectable keys in the
|
|
[configuration contract](../config.md) when they change.
|
|
4. Verify replacement policy and validator-chain selection against the
|
|
[architecture requirements](../policy/architecture.md#correction-and-concurrency-invariants).
|
|
5. Review module, prompt-variable, and proposal-generation tests. Inspect parity
|
|
and release fixtures when public output changes, choosing sufficient coverage
|
|
under the [testing policy](../policy/testing.md).
|
|
6. Update this document for implementation changes and the appropriate public
|
|
contract owner for externally visible changes.
|
|
|
|
## Key Tests
|
|
|
|
- `internal/modules/*/module_test.go`
|
|
- `internal/framework/modules/registry_test.go`
|
|
- `internal/framework/proposal_generation/*_test.go`
|
|
- `internal/cli/run_test.go` (pipeline/report integration)
|