ltcai 11.0.1 → 11.2.0

package/latticeai/core/workspace_reorganization.py

@@ -0,0 +1,335 @@
+"""Agent-native workspace reorganization — proposals, never a silent tidy-up.
+
+"이 프로젝트를 정리해줘" is a request an agent can now answer without being
+trusted with the filesystem. The Brain looks at a folder, asks the graph what
+each file is *about*, and stages one review proposal describing every move it
+would make. Nothing on disk changes until a person approves it, and approving
+applies exactly the moves that were reviewed.
+
+Three rules make this safe enough to hand to a long-running session:
+
+* **No deletions, ever.** The planner emits moves only. There is no code path
+  here that removes a file, so the worst outcome of a bad proposal is a file
+  in a folder you did not want (recoverable) rather than a file that is gone
+  (not). Plan §10's conservative mitigation, made structural.
+* **Only what the Brain actually knows.** A file is moved because the graph
+  links it to a topic — never because of a guess from its extension. Files the
+  Brain has nothing to say about are reported as ``unplaced`` with a reason
+  instead of being swept somewhere plausible.
+* **Deterministic.** The same folder and the same graph produce the same plan,
+  in the same order: candidates are sorted, topics are chosen by
+  (weight, title), and collisions resolve to the first path alphabetically.
+
+Every path in and out of this module is workspace-relative and resolved
+through the caller's sandboxed ``resolve_path`` (the agent-root resolver), so
+a proposal can never name a target outside the workspace.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import re
+from pathlib import Path
+from typing import Any, Callable, Dict, List, Optional, Tuple
+
+from latticeai.core.timeutil import now_iso as _now
+
+LOGGER = logging.getLogger(__name__)
+
+#: Review-queue kind for a reorganization proposal. Source stays
+#: ``change_proposal`` so the Review Center's approve path applies it through
+#: :class:`~latticeai.services.change_proposals.ChangeProposalService`.
+REORG_KIND = "folder_reorganization"
+
+#: Folder the plan groups into. One level, named after the topic, so the result
+#: is legible without a map.
+TOPIC_ROOT = "topics"
+
+#: Node types that stand for a file on disk, and the ones that stand for what a
+#: file is about.
+FILE_NODE_TYPES = frozenset(
+    {
+        "File", "CodeFile", "Document", "Image", "Spreadsheet", "SlideDeck",
+        "ImageText", "Audio",
+    }
+)
+TOPIC_NODE_TYPES = frozenset({"Topic", "Concept", "Project", "Feature"})
+
+DEFAULT_MAX_MOVES = 20
+DEFAULT_SCAN_LIMIT = 400
+DEFAULT_GRAPH_LIMIT = 800
+
+_SLUG_RE = re.compile(r"[^0-9A-Za-z가-힣._-]+")
+
+
+def _slug(value: str) -> str:
+    """Folder-safe topic name (Korean kept — the user reads these folders)."""
+    return _SLUG_RE.sub("-", str(value or "").strip()).strip("-.").lower()[:48]
+
+
+def _rel(path: Path, base: Path) -> str:
+    return path.relative_to(base).as_posix()
+
+
+def _scan(base: Path, limit: int) -> List[Path]:
+    """Visible files under ``base``, deepest-stable order, capped at ``limit``."""
+    found: List[Path] = []
+    for path in sorted(base.rglob("*")):
+        if len(found) >= limit:
+            break
+        if not path.is_file():
+            continue
+        if any(part.startswith(".") for part in path.relative_to(base).parts):
+            continue
+        found.append(path)
+    return found
+
+
+def _file_node_index(graph: Any, limit: int) -> Tuple[Dict[str, str], str]:
+    """``{file name → graph node id}`` plus the basis for the plan.
+
+    A missing or unreadable graph yields an empty index and a basis that says
+    so, which is what makes an empty plan honest rather than mysterious.
+    """
+    if graph is None:
+        return {}, "no_graph"
+    try:
+        data = graph.graph(limit)
+    except Exception:  # noqa: BLE001 — a broken read proposes nothing
+        LOGGER.exception("workspace reorganization graph read failed")
+        return {}, "graph_unavailable"
+    index: Dict[str, str] = {}
+    for node in data.get("nodes") or []:
+        if str(node.get("type")) not in FILE_NODE_TYPES:
+            continue
+        for key in _file_keys(node):
+            index.setdefault(key, str(node.get("id")))
+    return index, "graph"
+
+
+def _topic_for(graph: Any, node_id: str) -> str:
+    """The topic a file node belongs to, or ``""`` when the Brain has none.
+
+    One hop, strongest edge first; ties break on the topic title so the same
+    graph always produces the same folder.
+    """
+    try:
+        data = graph.neighbors(node_id)
+    except Exception:  # noqa: BLE001 — one unreadable node is not a failure
+        LOGGER.exception("workspace reorganization neighbour read failed")
+        return ""
+    by_id = {str(node.get("id")): node for node in data.get("neighbors") or []}
+    best: Optional[Tuple[float, str]] = None
+    for edge in data.get("edges") or []:
+        far = edge.get("to") if str(edge.get("from")) == node_id else edge.get("from")
+        node = by_id.get(str(far))
+        if node is None or str(node.get("type")) not in TOPIC_NODE_TYPES:
+            continue
+        title = str(node.get("title") or "").strip()
+        if not title:
+            continue
+        candidate = (-float(edge.get("weight") or 1.0), title)
+        if best is None or candidate < best:
+            best = candidate
+    return best[1] if best is not None else ""
+
+
+def _file_keys(node: Dict[str, Any]) -> List[str]:
+    """Every name a graph file node might be matched by (lowercased)."""
+    metadata = node.get("metadata") or {}
+    candidates = [
+        metadata.get("relative_path"),
+        metadata.get("filename"),
+        metadata.get("path"),
+        node.get("title"),
+    ]
+    keys: List[str] = []
+    for candidate in candidates:
+        text = str(candidate or "").strip()
+        if not text:
+            continue
+        for key in (text.lower(), Path(text).name.lower()):
+            if key and key not in keys:
+                keys.append(key)
+    return keys
+
+
+def plan_reorganization(
+    *,
+    root: str = "",
+    resolve_path: Callable[[str], Path],
+    graph: Any = None,
+    max_moves: int = DEFAULT_MAX_MOVES,
+    scan_limit: int = DEFAULT_SCAN_LIMIT,
+    graph_limit: int = DEFAULT_GRAPH_LIMIT,
+) -> Dict[str, Any]:
+    """What the Brain would move, and what it deliberately would not.
+
+    Read-only: this touches no file and creates no proposal.
+    """
+    base = resolve_path(root)
+    if not base.is_dir():
+        return _empty_plan(root, "folder_missing")
+    index, basis = _file_node_index(graph, graph_limit)
+    moves: List[Dict[str, Any]] = []
+    unplaced: List[Dict[str, Any]] = []
+    claimed: set = set()
+    for path in _scan(base, scan_limit):
+        source = _rel(path, base)
+        node_id = index.get(source.lower()) or index.get(path.name.lower())
+        topic = _topic_for(graph, node_id) if node_id else ""
+        if not topic:
+            unplaced.append({"path": source, "reason": "brain_has_no_topic"})
+            continue
+        target = f"{TOPIC_ROOT}/{_slug(topic)}/{path.name}"
+        if target == source:
+            unplaced.append({"path": source, "reason": "already_in_place"})
+            continue
+        if target in claimed or (base / target).exists():
+            unplaced.append({"path": source, "reason": "target_taken"})
+            continue
+        claimed.add(target)
+        moves.append({
+            "source": source,
+            "target": target,
+            "topic": topic,
+            "reason": f"'{topic}' 주제와 이어져 있습니다",
+        })
+    trimmed = len(moves) > max_moves
+    return {
+        "available": True,
+        "root": root,
+        "basis": basis,
+        "moves": moves[: max(0, int(max_moves))],
+        "move_count": len(moves[: max(0, int(max_moves))]),
+        "truncated": trimmed,
+        "unplaced": unplaced,
+        "unplaced_count": len(unplaced),
+        # Structural, not a policy toggle: this planner has no delete path.
+        "deletes": [],
+        "generated_at": _now(),
+    }
+
+
+def _empty_plan(root: str, reason: str) -> Dict[str, Any]:
+    return {
+        "available": False,
+        "root": root,
+        "basis": reason,
+        "moves": [],
+        "move_count": 0,
+        "truncated": False,
+        "unplaced": [],
+        "unplaced_count": 0,
+        "deletes": [],
+        "generated_at": _now(),
+    }
+
+
+def propose_reorganization(
+    *,
+    root: str = "",
+    resolve_path: Callable[[str], Path],
+    review_queue: Any,
+    graph: Any = None,
+    user_email: Optional[str] = None,
+    workspace_id: Optional[str] = None,
+    max_moves: int = DEFAULT_MAX_MOVES,
+    audit: Optional[Callable[..., None]] = None,
+) -> Dict[str, Any]:
+    """Stage one review proposal describing the whole reorganization.
+
+    Returns ``{"proposed": None, ...}`` when there is nothing to propose — an
+    empty proposal is noise, and a Brain that knows nothing about a folder
+    should say so rather than invent a structure.
+    """
+    plan = plan_reorganization(
+        root=root, resolve_path=resolve_path, graph=graph, max_moves=max_moves
+    )
+    if not plan["moves"]:
+        return {"proposed": None, "plan": plan, "reason": plan["basis"]}
+    preview = ", ".join(move["source"] for move in plan["moves"][:3])
+    item = review_queue.create(
+        title=f"폴더 정리 제안: {root or '작업 폴더'} 파일 {plan['move_count']}개",
+        summary=(
+            f"{preview} 등 {plan['move_count']}개 파일을 주제별 폴더로 옮기는 제안입니다. "
+            "삭제는 제안하지 않으며, 승인하기 전에는 아무것도 움직이지 않습니다."
+        ),
+        source="change_proposal",
+        kind=REORG_KIND,
+        payload={
+            "root": root,
+            "moves": plan["moves"],
+            "unplaced": plan["unplaced"],
+            "basis": plan["basis"],
+            "contract": {"moves": "proposal", "deletions": "never_proposed"},
+        },
+        provenance={
+            "proposed_by": "agent",
+            "reason": "workspace reorganization",
+            "source_detail": "brain topic grouping",
+        },
+        user_email=user_email,
+        workspace_id=workspace_id,
+    )
+    if audit is not None:
+        audit(
+            "workspace_reorg_proposed",
+            user_email=user_email,
+            proposal_id=item.get("id"),
+            moves=plan["move_count"],
+        )
+    return {"proposed": item, "plan": plan, "reason": ""}
+
+
+def apply_reorganization(
+    payload: Dict[str, Any], *, resolve_path: Callable[[str], Path]
+) -> Dict[str, Any]:
+    """Carry out the reviewed moves. Nothing is ever deleted or overwritten.
+
+    Each move is checked again at apply time: a source that vanished and a
+    target that appeared are both reported as skipped rather than forced, so a
+    stale proposal degrades into an honest partial result.
+    """
+    applied: List[Dict[str, Any]] = []
+    skipped: List[Dict[str, Any]] = []
+    for move in payload.get("moves") or []:
+        source_rel = str(move.get("source") or "")
+        target_rel = str(move.get("target") or "")
+        if not source_rel or not target_rel:
+            skipped.append({"source": source_rel, "reason": "incomplete_move"})
+            continue
+        source = resolve_path(_join(payload, source_rel))
+        target = resolve_path(_join(payload, target_rel))
+        if not source.is_file():
+            skipped.append({"source": source_rel, "reason": "source_missing"})
+            continue
+        if target.exists():
+            skipped.append({"source": source_rel, "reason": "target_exists"})
+            continue
+        target.parent.mkdir(parents=True, exist_ok=True)
+        os.replace(source, target)
+        applied.append({"source": source_rel, "target": target_rel})
+    return {
+        "applied": applied,
+        "applied_count": len(applied),
+        "skipped": skipped,
+        "skipped_count": len(skipped),
+        "deleted": 0,
+    }
+
+
+def _join(payload: Dict[str, Any], relative: str) -> str:
+    root = str(payload.get("root") or "").strip("/")
+    return f"{root}/{relative}" if root else relative
+
+
+__all__ = [
+    "DEFAULT_MAX_MOVES",
+    "REORG_KIND",
+    "TOPIC_ROOT",
+    "apply_reorganization",
+    "plan_reorganization",
+    "propose_reorganization",
+]

package/latticeai/models/model_providers.py

@@ -32,7 +32,11 @@ OPENAI_COMPATIBLE_PROVIDERS = {
     "xai": {
         "env_key": "XAI_API_KEY",
         "base_url": "https://api.x.ai/v1",
-        "default_model": "grok-beta",
+        # ``grok-beta`` was xAI's 2024 preview id and has been decommissioned;
+        # a request naming it now 404s at the provider. ``grok-4.5`` is the
+        # current flagship on api.x.ai and is multimodal, which is also why the
+        # separate ``grok-vision-beta`` row below is gone rather than renamed.
+        "default_model": "grok-4.5",
     },
     "ollama": {
         "env_key": "OLLAMA_API_KEY",
@@ -83,7 +87,7 @@ PROVIDER_MODEL_CATALOG = {
         {"id": "anthropic/claude-haiku-4.5", "name": "Claude Haiku 4.5 via OpenRouter", "family": "Claude"},
         {"id": "qwen/qwen3-vl-235b-a22b-instruct", "name": "Qwen3-VL 235B A22B via OpenRouter", "family": "Qwen"},
         {"id": "google/gemma-4-12b-it", "name": "Gemma 4 12B via OpenRouter", "family": "Gemma"},
-        {"id": "x-ai/grok-2", "name": "Grok 2 via OpenRouter", "family": "Grok"},
+        {"id": "x-ai/grok-4.5", "name": "Grok 4.5 via OpenRouter", "family": "Grok"},
         {"id": "meta-llama/llama-4-scout-17b-16e-instruct", "name": "Llama 4 Scout via OpenRouter", "family": "Llama"},
         {"id": "google/gemini-2.5-flash", "name": "Gemini 2.5 Flash via OpenRouter", "family": "Gemini"},
     ],
@@ -96,8 +100,12 @@ PROVIDER_MODEL_CATALOG = {
         {"id": "meta-llama/Llama-4-Scout-17B-16E-Instruct", "name": "Llama 4 Scout", "family": "Llama"},
     ],
     "xai": [
-        {"id": "grok-beta", "name": "Grok Beta", "family": "Grok"},
-        {"id": "grok-vision-beta", "name": "Grok Vision Beta", "family": "Grok"},
+        # One current generation only, per MODEL_POLICY's "do not keep old
+        # same-family generations" rule. The retired preview ids
+        # (grok-beta / grok-vision-beta) are not carried as fallbacks: a model
+        # the provider no longer serves is not compatibility, it is a 404 the
+        # user has to discover for themselves.
+        {"id": "grok-4.5", "name": "Grok 4.5", "family": "Grok"},
     ],
 }
 

package/latticeai/runtime/build_phases.py

@@ -542,6 +542,7 @@ def phase_brain(ctx: RuntimeContext) -> None:
         "BRAIN_INTELLIGENCE",
         "AUTOMATION_INTELLIGENCE",
         "INGESTION_PIPELINE",
+        "MULTIMODAL_PORTS",
         "DEVICE_IDENTITY",
         "KG_PORTABILITY",
         "FUNNEL_METRICS",
@@ -620,6 +621,29 @@ def phase_domain(ctx: RuntimeContext) -> None:
     )
 
 
+def self_model_port(workspace_graph: Any) -> Any:
+    """The agent loop's Self-Model port (v11.2.0).
+
+    11.1.0 built ``executor_prompt_for(self_model_summary=…)`` and had nothing
+    to pass it; this is what the composition root passes. ``summary_for_prompt``
+    never raises and answers ``""`` for a Brain that knows nothing about its
+    owner — which produces exactly the pre-11.2.0 prompt bytes.
+
+    A module-level factory rather than a closure inside ``phase_services``
+    because a port that cannot be called on its own cannot be tested on its own.
+    """
+
+    def _summary(*, user_email: Any = None, workspace_id: Any = None) -> str:
+        from lattice_brain.self_model import summary_for_prompt
+
+        graph = workspace_graph()
+        if graph is None:
+            return ""
+        return summary_for_prompt(graph, workspace_id=workspace_id)
+
+    return _summary
+
+
 # ── phase 6b: retrieval, agent runtime, and the typed AppContext ─────────────
 def phase_services(ctx: RuntimeContext) -> None:
     """Retrieval/context assembly, the chat agent runtime, and the AppContext.
@@ -755,6 +779,9 @@ def phase_services(ctx: RuntimeContext) -> None:
             audit=ctx.append_audit_event,
             hooks=ctx.HOOKS_REGISTRY,
             brain_memory=ctx.BRAIN_MEMORY,
+            self_model_summary=self_model_port(
+                lambda: ctx.KNOWLEDGE_GRAPH if ctx.ENABLE_GRAPH else None
+            ),
         )
     )
 
@@ -802,6 +829,8 @@ def phase_services(ctx: RuntimeContext) -> None:
             require_graph=ctx._require_graph,
             workspace_graph=ctx._workspace_graph,
             graph_stats=ctx._graph_stats_safe,
+            # Provider, not a value: REVIEW_QUEUE lands two phases later.
+            review_queue=lambda: ctx.REVIEW_QUEUE,
             workspace_models=_workspace_models_payload,
             workspace_settings=_workspace_settings_payload,
             scan_environment=scan_environment,
@@ -1197,11 +1226,13 @@ def phase_platform_features(ctx: RuntimeContext) -> None:
 
     # Voice memo capture (v9.9.7): the shortest path from a thought to the
     # Brain. Transcription is an optional local port — absent, the memo is
-    # still stored and the response says it is not searchable.
+    # still stored and the response says it is not searchable. v11.1.0 shares
+    # that one port with multi-modal ingestion, so a memo and a scanned
+    # recording can never disagree about whether this machine can hear.
     ctx.set(
         VOICE_CAPTURE=VoiceCaptureService(
             pipeline=ctx.INGESTION_PIPELINE if ctx.ENABLE_GRAPH else None,
-            transcriber=None,
+            transcriber=ctx.MULTIMODAL_PORTS.transcriber,
         )
     )
     ctx.app.include_router(

package/latticeai/runtime/chat_wiring.py

@@ -25,6 +25,7 @@ def build_chat_agent_runtime_from_context(
     audit: Any,
     hooks: Any,
     brain_memory: Any,
+    self_model_summary: Any = None,
 ) -> Any:
     # Ensure dispatch + agent share the same autonomy dial before the runtime
     # is constructed (process-wide service; data_dir refined later at router mount).
@@ -39,6 +40,9 @@ def build_chat_agent_runtime_from_context(
         hooks=hooks,
         brain_memory=brain_memory,
         permission_mode=resolve_active_permission_mode,
+        # v11.2.0: a scoped resolver, not a snapshot — the profile a run sees is
+        # the one the Brain holds when the run starts, per user and workspace.
+        self_model_summary=self_model_summary,
     )
 
 

package/latticeai/runtime/feature_toggle_wiring.py

@@ -0,0 +1,163 @@
+"""Wire the feature switchboard into the running app (v11.2.0).
+
+Same shape as ``permission_mode_wiring``: one process-wide service, an
+idempotent router mount guarded on ``app.state``, and explicit arguments that
+*rebind* an already-created service rather than being dropped — a lazy first
+caller must not pin the store to a fallback data dir with no audit sink.
+
+The one job unique to this module is :func:`bind_feature_gates`: it points each
+opt-in gate's resolver at the service, which is the step that turns a persisted
+preference into behaviour. Every gate is imported inside the function so
+importing this module costs nothing; ``lattice_brain.synthesis`` in particular
+drags in the graph layer.
+
+Unbinding is a supported operation (:func:`unbind_feature_gates`) because these
+gates are module-level singletons: a test that bound them must be able to give
+them back, and "the environment answers again" has to be reachable.
+"""
+
+from __future__ import annotations
+
+import os
+import threading
+from pathlib import Path
+from typing import Any, Callable, List, Optional, Tuple
+
+from latticeai.services.feature_toggles import FeatureToggleService
+
+_LOCK = threading.Lock()
+_SHARED: Optional[FeatureToggleService] = None
+
+#: ``feature id -> (module, attribute)`` for every boolean gate. Resolved lazily
+#: by :func:`_boolean_gates` so the table stays readable next to the catalog it
+#: mirrors, and a rename that breaks the pairing fails loudly at wiring time.
+GATE_BINDINGS: Tuple[Tuple[str, str, str], ...] = (
+    ("allow_multimodal", "lattice_brain.ingestion", "MULTIMODAL_GATE"),
+    ("video_ingest", "lattice_brain.ingestion", "VIDEO_GATE"),
+    ("auto_vector_index", "lattice_brain.ingestion", "AUTO_VECTOR_INDEX_GATE"),
+    ("brain_network", "lattice_brain.portability", "BRAIN_NETWORK_GATE"),
+    ("synthesis", "lattice_brain.synthesis", "SYNTHESIS_GATE"),
+    ("fusion_rrf", "lattice_brain.graph.fusion", "FUSION_RRF_GATE"),
+    ("graph_expansion", "lattice_brain.graph.fusion", "GRAPH_EXPANSION_GATE"),
+    ("vault_watch", "latticeai.services.folder_watch", "VAULT_WATCH_GATE"),
+    ("auto_late_fusion", "latticeai.services.search_service", "IMAGE_QUERY_FUSION_GATE"),
+)
+
+#: The one non-boolean seam: the vector backend is a pick-one-of-three.
+CHOICE_FEATURE = "vector_backend"
+
+
+def _default_data_dir() -> Path:
+    raw = os.environ.get("LATTICEAI_DATA_DIR", "").strip()
+    if raw:
+        return Path(raw)
+    return Path.home() / ".ltcai"
+
+
+def _boolean_gates() -> List[Tuple[str, Any]]:
+    """``[(feature id, gate)]`` — imports are here, not at module import."""
+    from importlib import import_module
+
+    return [
+        (feature_id, getattr(import_module(module), attribute))
+        for feature_id, module, attribute in GATE_BINDINGS
+    ]
+
+
+def _bind_vector_index(resolver: Any) -> None:
+    from lattice_brain.graph.vector_index.selector import bind_vector_index_resolver
+
+    bind_vector_index_resolver(resolver)
+
+
+def get_feature_toggle_service(
+    *,
+    data_dir: Optional[Path] = None,
+    audit: Optional[Callable[..., None]] = None,
+) -> FeatureToggleService:
+    """Process-wide singleton; explicit arguments rebind an existing one."""
+    global _SHARED
+    with _LOCK:
+        if _SHARED is None:
+            _SHARED = FeatureToggleService(
+                data_dir=Path(data_dir) if data_dir is not None else _default_data_dir(),
+                audit=audit,
+            )
+            return _SHARED
+        if data_dir is not None:
+            _SHARED.rebind_data_dir(Path(data_dir))
+        if audit is not None:
+            _SHARED.rebind_audit(audit)
+        return _SHARED
+
+
+def bind_feature_gates(service: Optional[FeatureToggleService] = None) -> None:
+    """Point every opt-in gate at the switchboard.
+
+    After this, a persisted preference beats the environment variable for every
+    feature in the catalog — which is the whole point, since the panel is the
+    only control surface most people will ever use.
+    """
+    resolved = service or get_feature_toggle_service()
+    for feature_id, gate in _boolean_gates():
+        # ``gate.local`` is the fallback on purpose: the switchboard speaks only
+        # for switches this person actually moved. Everything else still answers
+        # from the gate's own override → env → default, so binding changes
+        # nothing at all for an install that never opened the panel.
+        gate.bind(resolved.resolver(feature_id, gate.local))
+    _bind_vector_index(resolved.choice_resolver(CHOICE_FEATURE))
+
+
+def unbind_feature_gates() -> None:
+    """Hand every gate back to its environment variable."""
+    for _feature_id, gate in _boolean_gates():
+        gate.bind(None)
+    _bind_vector_index(None)
+
+
+def reset_feature_toggle_service() -> None:
+    """Drop the singleton *and* the bindings that pointed at it (tests)."""
+    global _SHARED
+    unbind_feature_gates()
+    with _LOCK:
+        _SHARED = None
+
+
+def register_features_router(
+    app: Any,
+    *,
+    require_user: Callable[..., str],
+    data_dir: Optional[Path] = None,
+    append_audit_event: Optional[Callable[..., None]] = None,
+) -> FeatureToggleService:
+    """Install GET/POST /api/features on ``app`` and bind the gates. Idempotent.
+
+    The guard is a flag on ``app.state`` rather than a scan of route paths: a
+    router included through fastapi >= 0.140 has no flat ``path`` to introspect,
+    so path scanning silently stopped seeing the mount (see
+    ``permission_mode_wiring`` for the same note).
+    """
+    from latticeai.api.features import create_features_router
+
+    service = get_feature_toggle_service(data_dir=data_dir, audit=append_audit_event)
+    bind_feature_gates(service)
+    state = getattr(app, "state", None)
+    if state is not None and getattr(state, "_ltcai_features_mounted", False):
+        return service
+    app.include_router(
+        create_features_router(service=service, require_user=require_user)
+    )
+    if state is not None:
+        state._ltcai_features_mounted = True
+    return service
+
+
+__all__ = [
+    "CHOICE_FEATURE",
+    "GATE_BINDINGS",
+    "bind_feature_gates",
+    "get_feature_toggle_service",
+    "register_features_router",
+    "reset_feature_toggle_service",
+    "unbind_feature_gates",
+]