Documentation

# Radiology Transcript Interpreter Implementation Plan ## Status This document is the initial executable R&D implementation plan. It is governed by: 1. `RADIOLOGY-TRANSCRIPT-INTERPRETATION-CONCEPTUAL-SPEC.md`; 2. `RADIOLOGY-TRANSCRIPT-LINGUISTIC-SEMANTIC-REFINEMENT-SPEC.md`. The conceptual specification defines the meaning and invariants of transcript interpretation. The refinement specification defines the initial linguistic and semantic profile. This plan organizes the work required to realize them. If this plan conflicts with either specification, the specifications are authoritative in the order above. This is an R&D plan. Construction definitions, frame alignments, and semantic rules are expected to improve as examples expose better distinctions. Such refinement is planned work, not a reason to defer implementation. --- # 1. Outcome and Execution Strategy ## 1.1 Intended Outcome The implementation accepts one generated radiology transcription and produces an immutable, inspectable interpretation execution containing: ```text source transcription linguistic observations mentions constructs and construction elements referents frames and composition RadLex grounding candidates and accepted groundings ambiguities diagnostics validated structured output provenance ``` The execution must answer: > How did this transcription become this structured interpretation? ## 1.2 Governing Implementation Strategy Development proceeds through vertical semantic slices. The first slice interprets one useful expression inside one complete retained transcription, carries it from exact source characters through validated frames, and explicitly records partial interpretation elsewhere. Later slices expand the supported linguistic phenomena without replacing the representation model ad hoc. Every milestone must leave behind an executable behavior and a regression example. A milestone is not complete merely because a component API or rule file exists. ## 1.3 Input Boundary The interpreter input is exactly: ```text record.transcript_text ``` The retained local development corpus contains 3,573 generated transcription records. Historical source reports are not retained and are not available to the interpreter. Record identifiers, historical row identifiers, heuristic phenomenon labels, and generation metadata may support provenance and test selection but may not supply linguistic or semantic evidence. An independently maintained LLM-generated transcription collection may be introduced through the same input contract. Creating that collection is not part of this plan. Future real human transcription is a later validation source. It is not a prerequisite for the R&D implementation. ## 1.4 Initial Output Decision Validated frame structures are valid R5 output for the initial implementation. Canonical application predicates may be added later when examples and consumers justify a stable projection. The absence of those predicates does not block an end-to-end implementation. ## 1.5 Partial Success The interpreter is not required to understand every expression in a transcription before it may return a valid result. A valid partial result: - preserves the complete source; - identifies which source regions contributed to accepted interpretations; - emits diagnostics for consequential unsupported or unresolved material; - does not manufacture structure to create the appearance of completeness; - validates every object it does accept. --- # 2. Existing Baseline ## 2.1 Proven Toolchain The existing research baseline has already demonstrated: ```text plain text → Stanza → Universal Dependencies / CoNLL-U → Grew / UCxn annotations → SWI-Prolog transport ``` It also provides resident access to MoCCA, FrameNet, and the generated RadLex runtime bundle. The setup and infrastructure verification suites are existing prerequisites, not work to repeat in this plan. ## 2.2 Proven Process Boundaries The current local topology is retained as the R&D baseline: | Boundary | Existing responsibility | New application responsibility | | --- | --- | --- | | Go hub | Routing, evaluation records, UI, identity checks | Interpretation execution lifecycle, orchestration, persistence, and debugger routes. | | Python linguistics service | Stanza, Grew/UCxn, MoCCA, FrameNet | Source-preserving linguistic analysis and local construct recognition. | | SWI-Prolog service | CoNLL-U inspection and RadLex queries | Semantic composition, grounding decisions, ambiguity, diagnostics, and validation. | No new service boundary is introduced unless an observed limitation requires one. Internal application modules may remain separately testable without becoming processes. ## 2.3 Infrastructure/Application Separation Existing toolchain evaluations and new interpretation executions are distinct: ```text TOOLCHAIN EVALUATION Proves that installed components and service seams work. INTERPRETATION EXECUTION Records what the application concluded about one transcription and why. ``` Passing infrastructure verification does not imply semantic correctness. Failing semantic interpretation does not necessarily imply infrastructure failure. --- # 3. Target Software Shape ## 3.1 Proposed Repository Layout The initial application work should use an explicit application area: ```text interpreter/ README.md contracts/ interpretation-ir.schema.json interpretation-request.schema.json interpretation-result.schema.json examples/ selected.jsonl annotations/ expected/ constructicon/ definitions/ rules/ tests/ semantics/ frames.pl composition.pl discourse.pl grounding.pl diagnostics.pl validation.pl tests/ contract/ examples/ counterexamples/ integration/ ``` This layout is a working default. Existing infrastructure code remains in `infrastructure/`; application semantics do not move into setup smoke tests. ## 3.2 Application Capabilities Three versioned capabilities are added to the existing service model. ### Linguistic analysis ```text linguistics.analyze ``` Input: ```text document identity exact transcription text analysis profile version ``` Output: ```text source spans and sentence/token boundaries UD observations CoNLL-U representation UCxn and local construction candidates component and rule identities diagnostics ``` ### Semantic interpretation ```text semantics.interpret ``` Input: ```text versioned linguistic result interpretation profile version ``` Output: ```text mentions constructs referents frames groundings ambiguities diagnostics validation R5 frame output ``` ### Complete execution ```text interpreter.run ``` The Go hub owns the complete execution, invokes the two capabilities, validates their envelopes, records artifacts, and publishes the immutable completed interpretation. The exact route names may follow existing API conventions. Capability identity and semantic responsibility are normative; URL spelling is not. ## 3.3 Stable Identity Every interpretation object receives an execution-local stable identifier. Identifiers must survive serialization, persistence, hub restart, and UI navigation. No persistent object may be identified by: - process identifier; - Python object identity; - Prolog variable name; - transient Grew graph handle; - array position without an explicit containing identity. ## 3.4 Source Locations Character spans in the exact transcription are the canonical source locations. Sentence and token identifiers are derived indexes. The linguistic service must prove: ```text stored_span_text = source_text[start:end] ``` for every emitted span. Tokenization or CoNLL-U serialization must not make it impossible to recover exact source characters. ## 3.5 Rule and Resource Identity Every interpretation records the identities of materially relevant resources: ```text IR contract linguistic profile parser and model UCxn rules local constructicon MoCCA database FrameNet data RadLex bundle semantic rules validation rules ``` An execution produced under changed rule or resource identities is a new execution. Existing completed executions remain immutable. --- # 4. Executable Example Method ## 4.1 Selected Example Record The example catalog contains references to retained transcription records and human-reviewed source spans. It does not copy facts from unavailable source reports. Each selected example records: ```text example identity corpus record identity exact transcript checksum exact focus spans phenomenon under examination expected accepted objects expected alternatives expected diagnostics expected validation result annotation status and profile version ``` The complete transcription remains the execution input even when an example focuses on one sentence or fragment. ## 4.2 First Vertical Slice The first slice uses retained record: ```text kaggle-rad-reports-000048-sectionless_dictation ``` and focuses initially on: ```text There is an 8mm nodule in the left lower lobe ``` The expected semantic spine is: ```text exact source spans ↓ measured-entity and located-finding constructs ↓ nodule and anatomy mentions ↓ finding and anatomical referents ↓ Measurement(Entity=finding, Value=8, Unit=mm) Location(Figure=finding, Relation=in, Ground=anatomy) ↓ RadLex grounding candidates ↓ validated frame output with complete provenance ``` The slice succeeds even if other portions of the transcription remain unsupported, provided their status is represented honestly. ## 4.3 Counterexample Obligation Every accepted construction or semantic rule must have at least one positive example and one contrastive example capable of detecting a shallow implementation. The first required contrast is: ```text 8 mm nodule versus tube tip is 5 cm above the carina ``` The first is an entity measurement. The second is a measured spatial relation. The implementation must not attach both quantities using the same nearest-noun rule. ## 4.4 Annotation Is Development Work There is no minimum corpus size gate. Examples are selected and annotated as needed to drive a semantic slice or investigate a failure. Annotations may begin as hypotheses. An annotation becomes an executable expectation after review against the refinement specification and relevant external authorities. --- # 5. Milestones and Tickets ## 5.1 Milestone Summary | Milestone | Ticket | Outcome | Gate | | --- | --- | --- | --- | | M0 | `INT-000` | Application skeleton and versioned IR contract | Contract tests pass. | | M1 | `INT-001` | Executable example catalog | First selected transcription and counterexample are reviewable. | | M2 | `INT-002` | Source-preserving linguistic analysis | Exact spans, UD, and construction evidence survive transport. | | M3 | `INT-003` | First semantic vertical slice | Measurement and location frames compile in Prolog. | | M4 | `INT-004` | RadLex grounding and candidate semantics | Mention and referent grounding retain evidence and ambiguity. | | M5 | `INT-005` | Semantic validation and R5 frame output | First execution is valid end to end. | | M6 | `INT-006` | Negation and coordination | Positive and negative content remain distinct. | | M7 | `INT-007` | Spatial measurement and comparison | Distance, entity size, stability, and baseline remain distinct. | | M8 | `INT-008` | Uncertainty and recommendation | Epistemic alternatives and future actions remain distinct from findings. | | M9 | `INT-009` | Discourse identity and ambiguity | Anaphora and unresolved candidates are explicit. | | M10 | `INT-010` | Durable interpretation executions | Hub runs and persists immutable interpretations. | | M11 | `INT-011` | Semantic interpretation debugger | One execution is intelligible from source through validation. | | M12 | `INT-012` | Corpus expansion and final R&D handoff | All selected examples and full verification pass. | ## 5.2 `INT-000` — Application Foundation and IR Contract ### Work - Create the `interpreter/` application layout. - Translate the provisional refinement IR into versioned JSON Schemas. - Define object identifiers, statuses, evidence references, and resource identities. - Define interpretation request, in-progress internal record, completed result, and structured failure envelopes. - Define forward-compatible extension points without permitting unknown core object types to pass validation silently. - Add schema fixtures for minimal valid, full valid, and representative invalid structures. ### Acceptance - Every conceptual object required by the first slice is representable. - Every accepted derived object can reference source evidence and derivation. - Ambiguity and diagnostics are valid result content rather than transport failures. - Invalid references, spans, roles, and statuses fail contract validation. - Contract tests run without starting resident services. ## 5.3 `INT-001` — Executable Example Catalog ### Work - Select the first retained transcription and record its checksum. - Annotate exact focus spans for entity measurement and location. - Select the spatial-measurement counterexample. - Store expected objects by semantic identity rather than unstable ordering. - Build a test loader that verifies record existence, checksum, and exact span text before semantic tests run. ### Acceptance - A changed transcription causes an explicit fixture mismatch. - Expected annotations refer only to characters in `transcript_text`. - Heuristic corpus labels do not appear as semantic evidence. - The entity-size/spatial-distance contrast is executable. ## 5.4 `INT-002` — Source-Preserving Linguistic Analysis ### Work - Add `linguistics.analyze` to the Python boundary. - Accept exact text and return character-addressable sentences and tokens. - Preserve Stanza UD observations and CoNLL-U without treating them as final semantic truth. - Apply official UCxn rules where relevant. - Add the first local Grew construction definitions and construction-element bindings. - Emit imported, local, and alternative analyses with distinct authority and rule identities. - Verify source-span integrity at the service boundary. ### Acceptance - The first complete transcription parses through the resident service. - The focus phrase maps back to exact input characters. - Measurement, finding, and anatomical expressions are recoverable from the returned analysis. - Local construction evidence is distinguishable from official UCxn evidence. - Parser or rule failure produces structured diagnostics. - Existing infrastructure verification continues to pass. ## 5.5 `INT-003` — First Semantic Vertical Slice ### Work - Add a separately testable Prolog semantic kernel. - Import the versioned linguistic result into semantic facts. - Create mentions from construction elements and source spans. - Create source-licensed discourse referents. - Implement the `Measurement` and `Location` frame definitions and role checks. - Compose both frames through the shared finding referent. - Retain construct-to-frame and mention-to-referent provenance. - Return an interpretation graph before grounding. ### Acceptance - The first focus phrase produces the expected mentions, referents, and frames. - `8mm` normalizes to value `8` and unit `mm` while preserving its exact span. - Measurement and location share the nodule referent for stated structural reasons. - No RadLex or FrameNet fact creates a transcript referent. - Removing the construction evidence prevents the semantic result rather than causing a proximity fallback. - The Prolog unit suite and service integration test both pass. ## 5.6 `INT-004` — RadLex Grounding ### Work - Extend RadLex lookup beyond the current exact-label research operation as examples require, using the generated runtime bundle rather than an RDF runtime. - Produce mention grounding candidates with lexical evidence. - Produce referent grounding only from composed, source-backed evidence. - Implement the working acceptance rule from the refinement specification: accept grounding only at uniquely supported semantic specificity; otherwise preserve candidates. - Retain ontology and bundle identity with every grounding result. - Test that ontology existential restrictions constrain abstract knowledge but never create transcript referents. ### Acceptance - Finding and anatomy mentions produce inspectable grounding candidates. - Accepted referent grounding cites its mention and composition evidence. - Multiple undominated candidates remain explicit. - Unknown expressions return an empty candidate set plus an appropriate diagnostic, not a fabricated concept. - Grounding does not change polarity, certainty, or discourse identity. ## 5.7 `INT-005` — Validation and Initial R5 Output ### Work - Implement structural, source, construction, discourse, frame, grounding, ambiguity, diagnostic, and provenance validators. - Assign stable validation-rule identifiers. - Distinguish fatal invalidity from a valid partial interpretation containing unresolved material. - Emit accepted validated frames as the initial R5 structured output. - Add deliberately invalid fixtures for each invariant family. ### Acceptance - The first vertical slice traverses R0 through R5. - Every accepted frame and grounding has a derivation path to exact source characters. - Dangling references, illegal roles, unlicensed referents, invalid groundings, and missing provenance are rejected. - Explicit ambiguity and diagnostics can coexist with `valid: true`. - No canonical application predicate is required to complete the slice. ## 5.8 `INT-006` — Negation and Coordination ### Work - Add `negated_finding`, `coordination`, and relevant presentational constructions. - Represent scope before distributing polarity. - Add `FindingAssertion` with explicit polarity and source cue. - Cover finite and telegraphic forms such as `There is no ...` and `No ...`. - Add counterexamples involving `difficult to exclude` and other forms where a negation word does not create an absence assertion. ### Acceptance - `There is no pneumothorax or pleural effusion` yields two negative contents with shared scope provenance. - The same grounded concepts in positive contexts do not inherit negative polarity. - `difficult to exclude` remains an uncertain live characterization. - Coordination outside negation scope is not distributed as negative. ## 5.9 `INT-007` — Spatial Measurement and Comparison ### Work - Add `SpatialMeasurement` distinct from entity `Measurement`. - Recognize figure, distance, spatial relation, and ground. - Add the initial `Comparison` frame and unchanged/increased/decreased directions. - Preserve explicit or unresolved baselines. - Infer a measurement dimension only from explicit language or a tested construction rule. ### Acceptance - `tube tip is 5 cm above the carina` measures the relation, not tube-tip size. - `stable from prior radiographs` produces unchanged comparison without implying normality or benignity. - Missing or redacted baseline details remain unresolved. - Nearest-token attachment cannot satisfy the counterexample suite. ## 5.10 `INT-008` — Uncertainty, Characterization, and Recommendation ### Work - Add epistemic-qualification and alternative-characterization constructions. - Preserve exact cues alongside the minimal normalized certainty vocabulary. - Add the `Characterization` and `Recommendation` frames. - Keep observed content, proposed characterization, and recommended future action semantically distinct. - Extend the certainty vocabulary only when a reviewed example requires it. ### Acceptance - `probably scarring ... difficult to exclude a cavitary lesion` preserves both characterizations and their different cues. - `CT chest with contrast is recommended` does not imply that CT occurred. - An uncertain characterization is not promoted to a certain finding by grounding. - A recommendation is not serialized as a present patient finding. ## 5.11 `INT-009` — Discourse Identity and Ambiguity ### Work - Add candidate-based anaphora and repeated-reference handling. - Use only transcript-internal evidence: constructional role, semantic type, agreement, salience, and locality. - Preserve distinct mentions even when they resolve to one referent. - Represent attachment, reference, and grounding ambiguities through a common alternative structure. - Retain preference and rejection reasons for consequential candidates. ### Acceptance - `There is a nodule. It measures 6 mm.` uses one referent and two mentions. - Multiple undominated antecedents yield reference ambiguity. - Similar wording does not automatically merge referents. - No historical report section or row information participates in identity. ## 5.12 `INT-010` — Durable Interpretation Executions ### Work - Add a versioned complete-interpretation request to the Go hub. - Orchestrate linguistic and semantic capabilities with existing deadline, identity, and structured-error conventions. - Persist source, intermediate artifacts, final IR, validation, and component identities under one execution identity. - Publish only complete immutable executions as history. - Keep toolchain evaluation history distinct from interpretation history. - Define duplicate-request behavior through source and profile identities. ### Acceptance - One request produces one addressable completed interpretation. - Restarting the hub does not change completed content or object links. - Changed rules or resources produce a distinct execution identity or explicit stale status. - Partial infrastructure failure cannot publish a semantically complete record. - Stored artifacts pass digest verification. ## 5.13 `INT-011` — Semantic Interpretation Debugger ### Work - Implement the execution workspace from `research/ui-specifications/Radiology Transcript Interpreter Interactive Execution UI Specification.md`. - Present source, mentions, constructs, referents, frames, grounding, ambiguity, diagnostics, output, and validation as the primary narrative. - Make every accepted semantic object navigable to its source evidence and derivation. - Keep raw CoNLL-U, JSON, Grew evidence, and Prolog facts available as secondary implementation evidence. - Expose domain identities and relationships in a semantic DOM. - Add accessibility and no-JavaScript tests consistent with the existing UI. ### Acceptance - An engineer can explain the first vertical slice without reconstructing it from logs. - Mention and referent identities are visually distinct. - Candidate and accepted grounding are visually distinct. - Ambiguity and diagnostics are not presented as generic crashes. - Validation displays individual semantic obligations, not only a green badge. - Every UI claim links to the same immutable execution record exposed by the API. ## 5.14 `INT-012` — Corpus Expansion and R&D Handoff ### Work - Add examples opportunistically across the implemented phenomenon families. - Record newly discovered construction distinctions and counterexamples in the refinement specification or constructicon documentation. - Add regression tests for every corrected semantic defect. - Measure coverage by reviewed phenomenon examples and semantic obligations, not by an arbitrary corpus annotation quota. - Run application, service, UI, and existing infrastructure verification from a stopped state. - Produce a concise experiment report separating demonstrated behavior from future production claims. ### Acceptance - Every implemented construction and frame has positive and contrastive tests. - Every selected executable example produces its expected valid result, ambiguity, or diagnostic. - The complete verification suite runs without accessing historical reports. - The interpreter consumes only transcription text as semantic input. - The handoff report identifies unsupported phenomena without treating them as implementation failures or silently claiming coverage. --- # 6. Dependency Order The required dependency spine is: ```text INT-000 IR contract ↓ INT-001 example catalog ↓ INT-002 linguistic analysis ↓ INT-003 semantic slice ↓ INT-004 grounding ↓ INT-005 validation / R5 ↓ INT-010 durable execution ↓ INT-011 debugger ↓ INT-012 final handoff ``` Phenomenon expansions `INT-006` through `INT-009` depend on `INT-005`. They may proceed independently where their rule and example files do not overlap, but all must complete before `INT-012`. The UI may begin as soon as a stable first-slice IR exists. Its final acceptance depends on durable executions. --- # 7. Testing Strategy ## 7.1 Contract Tests JSON Schema and Prolog boundary tests verify valid and invalid IR shapes, reference integrity, enumeration values, and capability envelopes. ## 7.2 Golden Example Tests Golden tests compare semantic objects by stable identity and relations, not raw serialization order. Expected output may deliberately contain ambiguity or diagnostics. A golden test must not require every parser detail to remain byte-identical unless that detail materially supports the semantic expectation. ## 7.3 Counterexample Tests Counterexamples prevent shallow generalization across superficially similar forms. They are required for scope, attachment, measurement target, recommendation, certainty, and referent identity. ## 7.4 Invariant Tests Each conceptual invariant receives at least one deliberately invalid fixture. The test asserts both rejection and the appropriate validation diagnostic. ## 7.5 Metamorphic Tests Where appropriate, controlled source changes verify semantic consequences: ```text no nodule → negative polarity nodule → positive polarity possible nodule → uncertain characterization 8 mm nodule → entity measurement 5 cm above → spatial measurement ``` Metamorphic inputs are explicitly synthetic tests and do not enter the corpus as empirical observations. ## 7.6 Integration Tests Integration tests exercise the resident Python, Prolog, and Go boundaries, including structured error handling, deadlines, component identities, restart behavior, and immutable artifacts. ## 7.7 Debugger Tests UI tests verify source links, semantic DOM relationships, ambiguity rendering, validation detail, raw-evidence access, accessibility, and no-JavaScript behavior. --- # 8. Completion Contract The R&D implementation is complete when: 1. A retained generated transcription traverses R0 through R5. 2. Accepted output consists of validated frames with complete provenance. 3. Measurement, location, negation, coordination, spatial distance, comparison, uncertainty, recommendation, and basic discourse reference have executable examples. 4. RadLex grounding preserves candidates and never creates transcript referents. 5. Ambiguity and diagnostics are first-class valid results. 6. Completed interpretations are immutable, addressable, and reproducible under recorded rule and resource identities. 7. The semantic debugger explains every accepted object from source evidence. 8. Positive, contrastive, invariant, service, and UI tests pass. 9. Existing setup and infrastructure verification continue to pass. 10. No interpreter behavior depends on historical report content or hidden report structure. Completion establishes a working research interpreter. It does not establish clinical correctness, production readiness, or performance on real human transcription. --- # 9. Working Rules for Plan Execution - Implement the smallest complete semantic slice before broadening coverage. - Let reviewed examples refine local construction and frame definitions. - Treat ordinary empirical refinements as engineering work, not owner approval gates. - Escalate only choices that change the higher-level conceptual contract or the public meaning of R5 output. - Preserve user changes and keep application work separate from setup evidence. - Update this plan when dependency order or acceptance criteria materially change; do not rewrite completed evidence to fit a later design. - Record observed limitations plainly rather than converting them into broad framework work.