Skip to content

v1.5.0 API Additions — POLARIS + LYRA Bridge Promotion

Status: Shipped in v1.5.0. Impact: Additive only — no breaking changes. Drives: ice_ext/STATUS.md §4 (ongoing cross-release ask pattern) and the v1.4.x bridge-preview deprecation window.

Summary

The POLARIS and LYRA bridge symbols that shipped in the fcc.plugins.v1_5_preview preview namespace during the v1.4.x line have been promoted to stable in v1.5.0:

  • fcc.api.PolarisBridgeProtocol
  • fcc.api.PolarisMockBridge
  • fcc.api.get_polaris_bridge
  • fcc.api.LyraBridgeProtocol
  • fcc.api.LyraMockBridge
  • fcc.api.get_lyra_bridge

Module-level stable homes:

  • fcc.archive.polaris_bridge — POLARIS archive coordination.
  • fcc.knowledge.lyra_bridge — LYRA graph-of-thought + harmonic vocabulary.

Why now

The v1_5_preview namespace was introduced in v1.4.4 so that downstream consumers (most notably ice_ext and the 10 constellation vocabularies) could pin against the shape of the forthcoming v1.5.0 stable API without waiting for the v1.5.0 tag. That preview window closes with this release.

ice_ext/STATUS.md §4 flagged both bridges as upstream promotion asks. The new Knowledge Graph Serializer Elevator (KGSE) persona added in v1.5.0 tracks this pattern across future releases so that the next batch of preview-to-stable promotions is never blocked on human memory.

New public symbols

POLARIS bridge

from fcc.api import get_polaris_bridge, PolarisBridgeProtocol, PolarisMockBridge

bridge = get_polaris_bridge()  # live when ice_ext is installed; mock otherwise
archive_id = bridge.push_archive(Path("manifest.yaml"))
path = bridge.pull_archive(archive_id)
models = bridge.query_models(zachman_cell="ENGINEER/WHEN")

LYRA bridge

from fcc.api import get_lyra_bridge, LyraBridgeProtocol, LyraMockBridge

bridge = get_lyra_bridge()  # LyraMockBridge — the lyra package has not shipped
result = bridge.graph_of_thought_query("persona", depth=2)
terms = bridge.vocab_lookup("curiosity", namespace="lyra-seed")
related = bridge.harmonic_expand("persona")

Both accessors follow the same availability-sentinel pattern as distiller_bridge: when the live backend is importable (ice_ext.plugin.bridge for POLARIS, lyra.api for LYRA) the real adapter is returned; otherwise a functional mock implementation is returned so downstream code can exercise the full protocol without any live backend.

Migration from v1.4.x preview imports

Before (v1.4.x):

from fcc.plugins.v1_5_preview.polaris_bridge import get_polaris_bridge
from fcc.plugins.v1_5_preview.lyra_bridge import get_lyra_bridge

After (v1.5.0+):

# Preferred — public API namespace, single import surface
from fcc.api import get_polaris_bridge, get_lyra_bridge

# Also valid — direct stable-module imports
from fcc.archive.polaris_bridge import get_polaris_bridge
from fcc.knowledge.lyra_bridge import get_lyra_bridge

The preview paths keep working throughout the v1.5.x line. A deprecation notice is added to each preview module's docstring pointing consumers at the stable home. Preview paths are removed in v1.6.0 (one-minor-release deprecation window, consistent with the v1_5_preview policy established in v1.4.4).

SemVer commitment

Starting from v1.5.0, both bridges are covered by the 1.x backward-compat guarantee as every other symbol listed in fcc.api.__all__:

  • PolarisBridgeProtocol and LyraBridgeProtocol method signatures will not change incompatibly inside the 1.x series.
  • PolarisMockBridge and LyraMockBridge constructor signatures are stable; additional optional parameters may be added (additive only).
  • get_polaris_bridge() and get_lyra_bridge() return types continue to satisfy the structural protocols — no breaking method changes within 1.x.
  • The availability-sentinel helpers (polaris_available, lyra_available) and the no-op fallbacks (NoOpPolarisBridge, NoOpLyraBridge) are also covered once they're re-exported (no-op classes stay at the module level in fcc.archive.polaris_bridge / fcc.knowledge.lyra_bridge).
  • Knowledge Graph Serializer Elevator (KGSE) persona — governance-style persona that tracks non-public-to-public symbol promotions across future releases (continues ice_ext STATUS.md §4 pattern).
  • Long-Term Archive Steward (LTAS) persona — POLARIS archive coordination, tar-manifest discipline, and IHL liaison for ice_ext model-storage integration.
  • Decision Archaeologist (DAR) persona — reconstructs ADR rationale from ModelHistoryEvent streams at ecosystem scale (complements HNAR from ice_ext).

Test coverage

See:

  • tests/test_api_bridge_promotion.py — pins the v1.5.0 promotion, including symbol-identity checks (fcc.api.get_polaris_bridge is fcc.archive.polaris_bridge.get_polaris_bridge), preview-path backward-compat, and __all__ membership.