CIEL Lab: Add pre-cached mapping suggestions to Required Class Mappings

[filiperochalopes]

User story

As a curator, I want Required Class Mappings to surface pre-cached mapping suggestions so I can map CIEL concepts faster using trusted imported suggestions.

Use case

A curator selects a Concept Class and one or more Required Sources in QA > Required Class Mappings. If an imported pre-cached suggestion exists for a CIEL concept and selected source, the page shows that suggested mapping before falling back to indexed semantic suggestions.

Requirements

• Add persistent storage for pre-cached mapping suggestion imports.
  • Store import-level metadata, including the mapped source, provenance, import/update timestamp, and enough information to identify where the suggestions came from.
  • Store item-level suggestions linked to the import.
• Each suggestion item must support:
  • CIEL concept ID.
  • Target mapping source.
  • Code.
  • Map type, when available.
  • Code description, when available.
• Add a user-facing “Load suggestions” action in QA > Required Class Mappings.
  • The import must accept a file containing at least CIEL concept ID, source, and code.
  • The import must preserve optional map type and code description when present.
  • Use the existing import/job/progress pattern where appropriate.
• Show pre-cached suggestions in Required Class Mappings when:
  • The user has enabled “Show mapping suggestions at QA > Required Class Mappings” in Settings.
  • The selected Required Source has a pre-cached suggestion for the displayed CIEL concept.
• Prioritize pre-cached suggestions over semantic/indexed suggestions.
  • Semantic/indexed suggestions may still be used as fallback or secondary suggestions.
• If a pre-cached suggestion has no code description:
  • Try to load the description from the indexed source when that source is indexed.
  • Leave the description empty when no description can be found.
• Display enough provenance for the user to understand whether a suggestion came from pre-cache/local data or from indexed semantic search.
• Allow imported pre-cached suggestion data to be deleted.
  • Deleting an import must remove its suggestion items.
  • Deleted suggestions must no longer appear in Required Class Mappings.
• Do not save mappings automatically just because a pre-cached suggestion exists; the existing mapping update flow must still control persistence.

Acceptance criteria

• Given mapping suggestions are enabled in Settings, when a curator opens Required Class Mappings for a Concept Class and Required Source with matching pre-cached suggestions, then the matching suggestion is displayed for each applicable CIEL concept.
• Given both a pre-cached suggestion and a semantic/indexed suggestion exist for the same CIEL concept and source, when suggestions are shown, then the pre-cached suggestion appears first.
• Given a pre-cached suggestion includes map type and code description, when it is displayed, then both values are shown with the suggested code.
• Given a pre-cached suggestion does not include code description and the selected source is indexed, when the suggestion is displayed, then the system attempts to show the indexed description for that code.
• Given no imported or indexed description is available, when the suggestion is displayed, then the code still appears and the description remains empty.
• Given “Show mapping suggestions at QA > Required Class Mappings” is disabled, when Required Class Mappings is opened, then pre-cached and semantic mapping suggestions are not shown.
• Given an imported pre-cached suggestion set exists, when the user deletes it, then its suggestions are removed and no longer appear in Required Class Mappings.
• Given an imported suggestion is selected or accepted, when the user saves through the existing mapping update flow, then the mapping is persisted through the same staged mapping behavior used today.
• Given an import file is missing required fields, when the user tries to load it, then the import fails or skips invalid rows with a clear status/error message.

More details (collapsible)

Context and implementation notes

Current Required Class Mappings already supports mapping suggestions from semantic/indexed search and is controlled by the Settings preference “Show mapping suggestions at QA > Required Class Mappings”.

The new feature should add pre-cached/imported suggestions as another suggestion source, with pre-cache taking priority over semantic search.

The data model should follow the existing two-level pattern used elsewhere in the app: one table for the imported suggestion set and another table for the suggestion items. The parent/import record should track source/provenance and update/import time. Item rows should hold concept ID, source, code, optional map type, and optional code description.

The upload/import flow can follow the existing translation suggestion import pattern: upload from the UI, persist an import job, process rows, expose progress/status, and allow cleanup/deletion.

[filiperochalopes]

Related to #2321

[ocl-automation]

Automated Triage — 2026-06-22

Dimension	Score
Complexity	4
Scope	3
Clarity	2
Dependency	3
Risk	3

Decision: decision/human-review
Type: type/feature
Signals: signal/needs-spec, signal/has-dependencies

Complex feature requiring integration of pre-cached suggestions with existing mapping system, involving multiple components (UI, storage, suggestion logic). Clarity is low - requirements are cut off and implementation details are missing. Moderate risk as incorrect mappings could affect curator workflow.

---

Generated by ticket-triage pipeline v3. Model: anthropic/claude-sonnet-4 (openrouter).

[askanter]

Is this tied to MCP output or general? If general, how is this different from current functionality which loads "suggestions". Is it keeping the same UI just allowing the suggestions to be loaded from a file?

[filiperochalopes]

Yes, this would be a general capability. When described at a high level it sounds simple, but the infrastructure required to support it is considerably more complex than what we have today. The UI changes are relatively small; the main challenge is everything behind the scenes.

The suggestions we have today are generated at runtime, whereas the suggestions we’re discussing would be persisted and managed over time. That introduces additional concerns around storage, lifecycle management, review workflows, synchronization, and traceability.

In any case, I’m already working on it while waiting for Burke to release the latest version for testing, so I can keep moving forward instead of being blocked.