vibe.review.reference_linker

Reference linker for VIBE Review requirements.

Links requirement metadata references (e.g., metadata.ref_dora: "Article 30.3(e)") to actual reference source texts stored in the database.

Design Rationale

Requirements in config.yml reference regulatory texts via metadata fields:

D5-1:
  label: "Audit rights"
  metadata:
    ref_dora: "Article 30.3(e)"
    ref_eba: "GL 29"

The ReferenceLinker resolves these references to actual text by: 1. Parsing metadata keys starting with ref_ 2. Mapping source names (dora -> dora_2022_2554) 3. Looking up ReferencePartModel entries 4. Populating Requirement.reference_text and reference_source

This enables: - Rich context in search queries (search by regulatory text, not just requirement label) - Cross-lingual matching (Swedish contract → English DORA text) - Audit trail linking requirements to source regulations

Usage

linker = ReferenceLinker(db_session)

Link a single requirement

linked_req = linker.link(requirement, config_metadata)

Link all requirements in a set

linked_set = linker.link_requirement_set(requirement_set, config)

LinkedReference

A resolved reference with source text.

ReferenceLinker

Links requirement metadata references to source texts.

Resolves metadata.ref_* fields to actual regulatory text by querying the reference_sources and reference_parts tables.

__init__ 

__init__(session: Session, preferred_languages: list[str] | None = None) -> None

Initialize the linker.

Parameters:
  • session (Session) –

    SQLAlchemy database session.

  • preferred_languages (list[str] | None, default: None ) –

    Language priority order (e.g., ["en", "sv"]). If None, returns first available language.

 
link(requirement: Requirement, metadata: dict[str, Any] | None) -> Requirement

Populate requirement reference fields from metadata.

Parameters:
  • requirement (Requirement) –

    The requirement to link.

  • metadata (dict[str, Any] | None) –

    Metadata dict containing ref_* keys.
Returns:
  • Requirement –

    The requirement with reference_text and reference_source populated.

 
link_requirement_set(requirements: dict[str, Requirement], config: dict[str, Any]) -> dict[str, Requirement]

Link all requirements in a set.

Parameters:
  • requirements (dict[str, Requirement]) –

    Dict mapping req_id -> Requirement.

  • config (dict[str, Any]) –

    Full config dict with review_requirements section.
Returns:
  • dict[str, Requirement] –

    Dict with linked requirements.

clear_cache 

clear_cache() -> None

Clear internal caches.