LYRA Bridge¶

The LYRA bridge is FCC's seam to graph-of-thought querying and harmonic vocabulary expansion. v1.5.0 promoted the preview surface at fcc.plugins.v1_5_preview.lyra_bridge to a stable public import path at src/fcc/knowledge/lyra_bridge.py. The LYRA package (lyra.api.LyraAdapter) is not yet published — the bridge is stable, the live backend is pending — so get_lyra_bridge() currently always returns the functional :class:LyraMockBridge backed by a :class:KnowledgeGraph. ADR-009 captures the decision to wire LYRA as a cross-ecosystem universal service with a mock-first contract.

The diagram below details the protocol, the KG-backed mock implementation, the no-op fallback, and the accessor that chooses between live and fallback paths.

classDiagram
    class LyraBridgeProtocol {
        <<Protocol>>
        +graph_of_thought_query(query: str, depth: int) dict
        +vocab_lookup(term: str, namespace: str) list~str~
        +harmonic_expand(concept: str) list~str~
    }

    class LyraMockBridge {
        -_graph : KnowledgeGraph
        +graph_of_thought_query(query, depth) dict
        +vocab_lookup(term, namespace) list~str~
        +harmonic_expand(concept) list~str~
        -_nodes_matching(query) list~KnowledgeNode~
        -_bfs(seeds, depth) tuple
    }

    class NoOpLyraBridge {
        -_UNAVAILABLE_MSG : str
        +graph_of_thought_query(query, depth) dict
        +vocab_lookup(term, namespace) list~str~
        +harmonic_expand(concept) list~str~
    }

    class LyraAdapter {
        <<external : lyra.api>>
        +graph_of_thought_query(query, depth) dict
        +vocab_lookup(term, namespace) list~str~
        +harmonic_expand(concept) list~str~
    }

    class KnowledgeGraph {
        +all_nodes() list~KnowledgeNode~
        +all_edges() list~KnowledgeEdge~
        +get_node(id) KnowledgeNode | None
    }

    class SeedGraphBuilder {
        <<module-level>>
        +_build_seed_graph() KnowledgeGraph
        Note: seeds 7 concepts + 6 edges<br/>(persona, riscear, discernment,<br/>curiosity, humility, workflow, fcc)
    }

    class SkosProxyEdges {
        <<module constants>>
        +_SKOS_BROADER = DEPENDS_ON
        +_SKOS_RELATED = MAPS_TO
        +_SKOS_NARROWER = INTERACTS_WITH
    }

    class lyra_available {
        <<module-level fn>>
        +lyra_available() bool
        -_LYRA_AVAILABLE : bool | None
    }

    class get_lyra_bridge {
        <<factory>>
        +get_lyra_bridge() LyraBridgeProtocol
    }

    class FccApi {
        <<re-export : fcc.api>>
        +get_lyra_bridge
        +LyraMockBridge
        +LyraBridgeProtocol
    }

    LyraMockBridge ..|> LyraBridgeProtocol : implements
    NoOpLyraBridge ..|> LyraBridgeProtocol : implements
    LyraAdapter ..|> LyraBridgeProtocol : implements (external, pending)
    LyraMockBridge "1" *-- "1" KnowledgeGraph : _graph
    LyraMockBridge ..> SkosProxyEdges : uses for harmonic_expand
    SeedGraphBuilder ..> KnowledgeGraph : builds
    get_lyra_bridge ..> lyra_available : probes
    get_lyra_bridge ..> LyraAdapter : returns when available
    get_lyra_bridge ..> LyraMockBridge : returns otherwise (current default)
    FccApi ..> get_lyra_bridge : re-exports
    FccApi ..> LyraMockBridge : re-exports
    FccApi ..> LyraBridgeProtocol : re-exports

Three notes on the promotion. First, src/fcc/knowledge/lyra_bridge.py is a pure re-export module — the preview path keeps working through the v1.5.x line with a DeprecationWarning on import. Second, the default KG used by LyraMockBridge is a tiny 7-node / 6-edge seed graph built by _build_seed_graph(); callers with a real KG pass it via the constructor (LyraMockBridge(graph=my_kg)). Third, the mock's BFS walk for graph_of_thought_query is synchronous and deterministic — the sequence of visited IDs depends only on the graph and the query, which keeps GraphRAG's LYRA augmentation replayable in tests.

The bridge is the mechanism GraphRAG uses for cross-namespace concept expansion (see ../sequence-diagrams/graphrag-zachman-filter.md); it is also exposed as a standalone surface for callers that only need harmonic expansion without the full GraphRAG pipeline. Migrate to from fcc.knowledge.lyra_bridge import get_lyra_bridge (or fcc.api.get_lyra_bridge) before the v1.6.0 preview removal.

Key contracts¶

LyraBridgeProtocol — three-method structural protocol covering the three capabilities LYRA exposes.
graph_of_thought_query(query, depth) — BFS walk from query-matching seeds; returns {query, depth, nodes, edges, paths}. Mock returns a concrete dict; live shape is TBD until LYRA ships.
vocab_lookup(term, namespace) — returns node IDs whose label or id contains term. Optional namespace filter.
harmonic_expand(concept) — follows SKOS-proxy edges (DEPENDS_ON / MAPS_TO / INTERACTS_WITH) from seeds matching concept, returns related concept IDs. Empty list = graceful degradation.
LyraMockBridge — KG-backed mock; default graph is _build_seed_graph() output.
NoOpLyraBridge — empty-return fallback with UserWarning; retained for tests asserting silent-no-op behaviour.
LyraAdapter — the external live adapter at lyra.api.LyraAdapter. The lyra package does not exist yet; lyra_available() will flip to True when it lands.
lyra_available() — cached sentinel for the lyra.api import.
get_lyra_bridge() — factory; returns the live adapter when available, else LyraMockBridge() with the default seed graph.

LYRA Bridge¶

Key contracts¶

See also¶