musubi-livekit 0.1.0__py3-none-any.whl

musubi_livekit/__init__.py

@@ -0,0 +1,23 @@
+"""LiveKit session callback adapter backed by the Musubi Python SDK.
+
+This package is a library for a LiveKit worker to call from its event
+handlers. It does not install or start a LiveKit worker by itself.
+"""
+
+from musubi_livekit.adapter import LiveKitAdapter
+from musubi_livekit.cache import ContextCache
+from musubi_livekit.config import LiveKitAdapterConfig
+from musubi_livekit.fast_talker import FastTalker
+from musubi_livekit.heuristics import detect_interesting_fact
+from musubi_livekit.redaction import redact_pii
+from musubi_livekit.slow_thinker import SlowThinker
+
+__all__ = [
+    "ContextCache",
+    "FastTalker",
+    "LiveKitAdapter",
+    "LiveKitAdapterConfig",
+    "SlowThinker",
+    "detect_interesting_fact",
+    "redact_pii",
+]

musubi_livekit/adapter.py

@@ -0,0 +1,204 @@
+"""LiveKitAdapter — glues LiveKit session events to Musubi SDK calls.
+
+The adapter owns a :class:`SlowThinker` + :class:`FastTalker` pair sharing one
+:class:`ContextCache`, plus the session-end artifact-upload pipeline
+with bounded retry + a deferred-retry queue for hard failures.
+
+The artifact upload path can be patched via ``client._upload_handler``;
+the fallback captures the transcript in episodic memory.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from typing import Any
+
+from musubi_sdk.exceptions import MusubiError
+
+try:
+    # The old in-tree adapter accepted the in-tree SDK client. Keep its error
+    # hierarchy during the import-path transition without requiring the server.
+    from musubi.sdk.exceptions import MusubiError as CoreMusubiError
+except ImportError:
+    CoreMusubiError = MusubiError
+
+from musubi_livekit.cache import ContextCache, RetrievalStatus
+from musubi_livekit.config import LiveKitAdapterConfig
+from musubi_livekit.fast_talker import FastTalker
+from musubi_livekit.heuristics import detect_interesting_fact
+from musubi_livekit.redaction import redact_pii
+from musubi_livekit.slow_thinker import SlowThinker
+
+log = logging.getLogger("musubi_livekit")
+
+_EPISODE_CONTEXT_TAGS = ["kind:episode", "staleness:episodic"]
+
+
+class LiveKitAdapter:
+    """Per-session wiring of LiveKit events to Musubi SDK calls."""
+
+    def __init__(
+        self,
+        *,
+        client: Any,
+        namespace: str,
+        artifact_namespace: str,
+        config: LiveKitAdapterConfig,
+    ) -> None:
+        self.client = client
+        self.namespace = namespace
+        self.artifact_namespace = artifact_namespace
+        self.config = config
+        self.cache = ContextCache(max_entries=config.cache_max_entries)
+        # RET-007 — the ONE authoritative agent-facing channel; both talkers publish to it (last
+        # retrieval wins = current-turn semantics), so a Slow Thinker pre-fetch failure is visible.
+        self._retrieval_status = RetrievalStatus()
+        self.slow_thinker = SlowThinker(
+            client=client,
+            namespace=namespace,
+            cache=self.cache,
+            deep_limit=config.deep_limit,
+            cache_ttl_s=config.cache_default_ttl_s,
+            status=self._retrieval_status,
+        )
+        self.fast_talker = FastTalker(
+            client=client,
+            namespace=namespace,
+            cache=self.cache,
+            fast_limit=config.fast_limit,
+            match_threshold=config.fast_match_threshold,
+            status=self._retrieval_status,
+        )
+        # Observability/state attached to the adapter for assertions in
+        # tests and for an operator dashboard wiring later.
+        self.upload_history: list[dict[str, Any]] = []
+        self.failed_upload_queue: list[dict[str, Any]] = []
+
+    @property
+    def retrieval_status(self) -> list[str]:
+        """RET-007 — the agent-facing degradation status for the CURRENT turn: the ONE authoritative
+        channel both talkers publish to (most recent retrieval wins). Empty = healthy; bounded
+        ``plane_*`` / ``sparse_embedding_failed`` / ``reranker_failed`` = partial degradation;
+        ``[RETRIEVAL_UNAVAILABLE]`` = no memory this turn (a Slow Thinker pre-fetch failure surfaces
+        here immediately, not only in the talker's own ``last_warnings``). This is the consumer the
+        LiveKit agent reads to render a status message."""
+        return list(self._retrieval_status.warnings)
+
+    # ------------------------------------------------------------------
+    # LiveKit event hooks
+    # ------------------------------------------------------------------
+
+    async def on_transcript_segment(self, transcript_so_far: str) -> None:
+        """``transcript_segment_received`` event — Slow Thinker restart."""
+        await self.slow_thinker.on_user_utterance_segment(transcript_so_far)
+
+    async def on_user_turn_completed(self, full_utterance: str) -> None:
+        """``on_user_turn_completed`` — final deep pre-fetch on the
+        completed utterance. The Fast Talker reads this on the next
+        speech tick."""
+        await self.slow_thinker.on_user_utterance_segment(full_utterance)
+
+    async def on_session_end(
+        self,
+        *,
+        session_id: str,
+        vtt_transcript: str,
+    ) -> None:
+        """``session_ends`` — upload the transcript as an artifact and
+        send a summary thought. Both writes are gated by the privacy
+        flags on :class:`LiveKitAdapterConfig`."""
+        if self.config.capture_transcripts:
+            await self._upload_transcript_with_retry(
+                session_id=session_id, vtt_transcript=vtt_transcript
+            )
+            await self._send_session_thought(session_id=session_id)
+
+    async def maybe_capture_fact(self, utterance: str) -> None:
+        """Heuristic memory capture — runs if ``capture_facts`` is on
+        AND the utterance matches an "interesting fact" pattern."""
+        if not self.config.capture_facts:
+            return
+        if not detect_interesting_fact(utterance):
+            return
+        scrubbed = self.maybe_redact(utterance)
+        try:
+            await self.client.episodic.capture(
+                namespace=self.namespace,
+                content=scrubbed,
+                tags=["livekit-voice", "heuristic-fact", *_EPISODE_CONTEXT_TAGS],
+                importance=6,
+            )
+        except (MusubiError, CoreMusubiError):
+            log.warning("livekit fact-capture failed", exc_info=True)
+
+    # ------------------------------------------------------------------
+    # Helpers
+    # ------------------------------------------------------------------
+
+    def maybe_redact(self, payload: str) -> str:
+        """Pass-through unless ``redact_pii`` is on."""
+        return redact_pii(payload) if self.config.redact_pii else payload
+
+    async def _upload_transcript_with_retry(
+        self,
+        *,
+        session_id: str,
+        vtt_transcript: str,
+    ) -> None:
+        """Upload the VTT transcript with bounded exponential retry.
+        On exhaustion, enqueue for deferred retry instead of dropping."""
+        scrubbed = self.maybe_redact(vtt_transcript)
+        if not scrubbed.strip():
+            return
+        payload = {
+            "namespace": self.artifact_namespace,
+            "title": f"Voice session {session_id}",
+            "content_type": "text/vtt",
+            "source_system": "livekit-session",
+            "source_ref": session_id,
+            "content": scrubbed.encode("utf-8"),
+        }
+        last_exc: Exception | None = None
+        for attempt in range(1, self.config.upload_max_attempts + 1):
+            if attempt > 1 and self.config.upload_backoff_s > 0:
+                await asyncio.sleep(self.config.upload_backoff_s)
+            try:
+                handler = getattr(self.client, "_upload_handler", None)
+                if callable(handler):
+                    handler(**payload)
+                else:
+                    # Fall back to the SDK's canonical artifacts.upload
+                    # surface when it ships; until then, route through
+                    # episodic.capture so the adapter is always live.
+                    await self.client.episodic.capture(
+                        namespace=self.namespace,
+                        content=scrubbed,
+                        tags=["livekit-voice", "session-transcript", *_EPISODE_CONTEXT_TAGS],
+                        importance=4,
+                    )
+                self.upload_history.append(payload)
+                return
+            except (MusubiError, CoreMusubiError) as exc:
+                last_exc = exc
+                continue
+        # Retries exhausted — enqueue for deferred retry instead of
+        # losing the session.
+        log.warning("livekit transcript upload exhausted retries; queued for deferred retry")
+        self.failed_upload_queue.append(
+            {"session_id": session_id, "payload": payload, "last_error": last_exc}
+        )
+
+    async def _send_session_thought(self, *, session_id: str) -> None:
+        """Optional summary thought emitted at session end."""
+        try:
+            await self.client.thoughts.send(
+                namespace=self.namespace,
+                from_presence="livekit-voice",
+                to_presence="all",
+                channel="scheduler",
+                content=f"Session {session_id} captured.",
+                importance=3,
+            )
+        except (MusubiError, CoreMusubiError):
+            log.warning("livekit summary thought failed", exc_info=True)

musubi_livekit/cache.py

@@ -0,0 +1,120 @@
+"""In-memory per-session retrieval cache for the LiveKit voice adapter.
+
+Per [[07-interfaces/livekit-adapter]] § ContextCache. Bounded
+(`max_entries` defaults to 10), TTL'd, and ages out the oldest
+entries first when full. ``get_best_match`` does a cheap token-overlap
+match — not a vector lookup, since pre-fetch queries are usually
+substrings or rephrasings of the live query.
+"""
+
+from __future__ import annotations
+
+import time
+from collections import deque
+from dataclasses import dataclass, field
+from typing import Any
+
+#: RET-007 — the agent-facing status code for a TOTAL retrieval failure (the SDK call raised / returned
+#: no usable body). Distinct from the bounded per-plane degradation codes; it means "no memory this turn".
+RETRIEVAL_UNAVAILABLE = "retrieval_unavailable"
+
+
+class RetrievalStatus:
+    """The ONE authoritative agent-facing retrieval status for the current turn (RET-007 Blocker 4).
+
+    Both the Slow Thinker (pre-fetch) and the Fast Talker (speech turn) publish to it on EVERY
+    retrieval — success, degraded, or total failure. To get correct current-turn semantics under
+    OVERLAP (requests can complete out of order — an older slow request may finish after a newer fast
+    one), publication is guarded by a monotonic GENERATION: a caller allocates a generation with
+    :meth:`begin` at retrieval START, and :meth:`publish` only takes effect if that generation is not
+    older than the last one published. So a stale (older) completion can never clobber the status of
+    the context actually delivered, while a newer completion (healthy or degraded) always wins.
+
+    All mutation is synchronous (no ``await`` inside), so under asyncio's single-threaded scheduling
+    ``begin``/``publish`` are atomic and no lock is needed.
+    """
+
+    def __init__(self) -> None:
+        self.warnings: list[str] = []
+        self._counter = 0
+        self._published_generation = 0
+
+    def begin(self) -> int:
+        """Allocate a monotonically increasing generation at the START of a retrieval."""
+        self._counter += 1
+        return self._counter
+
+    def publish(self, generation: int, warnings: list[str]) -> None:
+        """Publish ``warnings`` only if ``generation`` is not older than the last published one."""
+        if generation >= self._published_generation:
+            self._published_generation = generation
+            self.warnings = list(warnings)
+
+
+@dataclass(frozen=True)
+class _CacheEntry:
+    key: str
+    results: list[dict[str, Any]]
+    expires_at: float
+    #: RET-007 — the retrieval degradation warnings that accompanied these cached results, so a Fast
+    #: Talker cache-hit surfaces the SAME degradation status the Slow Thinker recorded (not a stale one).
+    warnings: list[str] = field(default_factory=list)
+
+
+def _token_overlap(a: str, b: str) -> float:
+    """Cheap Jaccard-ish overlap of lowercased token sets. Returns 0.0
+    if either side has no tokens — keeps the threshold gate honest
+    instead of a divide-by-zero."""
+    ta = {t for t in a.lower().split() if t}
+    tb = {t for t in b.lower().split() if t}
+    if not ta or not tb:
+        return 0.0
+    inter = len(ta & tb)
+    union = len(ta | tb)
+    return inter / union if union else 0.0
+
+
+class ContextCache:
+    """Bounded TTL'd retrieval cache. One per voice session."""
+
+    def __init__(self, max_entries: int = 10) -> None:
+        self._max_entries = max_entries
+        self._entries: deque[_CacheEntry] = deque(maxlen=max_entries)
+
+    def put(
+        self,
+        key: str,
+        results: list[dict[str, Any]],
+        ttl: float,
+        warnings: list[str] | None = None,
+    ) -> None:
+        """Store results (+ their RET-007 degradation ``warnings``) under ``key`` with a TTL. When
+        full, the oldest entry is evicted (FIFO via ``deque(maxlen=...)``)."""
+        self._entries.append(
+            _CacheEntry(
+                key=key,
+                results=results,
+                expires_at=time.monotonic() + ttl,
+                warnings=list(warnings or []),
+            )
+        )
+
+    def match(self, query: str, threshold: float) -> _CacheEntry | None:
+        """Return the highest-overlap unexpired ENTRY (results + warnings), if any beat ``threshold``.
+        The Fast Talker uses this so a cache-hit carries the cached degradation status."""
+        now = time.monotonic()
+        best_score = 0.0
+        best: _CacheEntry | None = None
+        for entry in self._entries:
+            if entry.expires_at <= now:
+                continue
+            score = _token_overlap(query, entry.key)
+            if score > best_score:
+                best_score = score
+                best = entry
+        return best if best is not None and best_score >= threshold else None
+
+    def get_best_match(self, query: str, threshold: float) -> list[dict[str, Any]] | None:
+        """Backward-compatible results-only view of :meth:`match` (``None`` on miss)."""
+        entry = self.match(query, threshold)
+        return entry.results if entry is not None else None

musubi_livekit/config.py

@@ -0,0 +1,37 @@
+"""Adapter-local configuration for the LiveKit voice adapter.
+
+Configuration is passed at construction time. A consuming worker owns
+environment loading and secret handling.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class LiveKitAdapterConfig:
+    """Tunables for a single :class:`LiveKitAdapter` instance."""
+
+    # --- Privacy gates (per spec § Privacy) -------------------------------
+    capture_transcripts: bool = True
+    """If False, ``on_session_end`` never uploads the VTT transcript."""
+
+    capture_facts: bool = True
+    """If False, the heuristic ``maybe_capture_fact`` never writes."""
+
+    redact_pii: bool = False
+    """If True, payloads pass through ``redact_pii`` before any write."""
+
+    # --- Cache shape (per spec § ContextCache) ---------------------------
+    cache_max_entries: int = 10
+    cache_default_ttl_s: float = 120.0
+
+    # --- Retrieval shape (per spec § Components) -------------------------
+    deep_limit: int = 15
+    fast_limit: int = 5
+    fast_match_threshold: float = 0.5
+
+    # --- Upload retry (per spec § Error handling) ------------------------
+    upload_max_attempts: int = 3
+    upload_backoff_s: float = 0.5

musubi_livekit/fast_talker.py

@@ -0,0 +1,84 @@
+"""Fast Talker — speech-generation context fetch with hard 200ms budget.
+
+Per [[07-interfaces/livekit-adapter]] § FastTalker. Reads from the
+shared :class:`ContextCache` first; on miss, falls back to a
+fast-path SDK call (mode="fast", ~150ms p50). Never blocks speech
+on Musubi: any retrieval failure surfaces as an empty result list
+and the agent speaks generically.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from musubi_livekit.cache import (
+    RETRIEVAL_UNAVAILABLE,
+    ContextCache,
+    RetrievalStatus,
+)
+
+log = logging.getLogger("musubi_livekit.fast_talker")
+
+
+class FastTalker:
+    """Per-session fast-path retrieval wrapper."""
+
+    def __init__(
+        self,
+        *,
+        client: Any,
+        namespace: str,
+        cache: ContextCache,
+        fast_limit: int = 5,
+        match_threshold: float = 0.5,
+        status: RetrievalStatus | None = None,
+    ) -> None:
+        self.client = client
+        self.namespace = namespace
+        self.cache = cache
+        self._fast_limit = fast_limit
+        self._match_threshold = match_threshold
+        #: RET-007 — the allowlisted degradation codes from the most recent retrieval, surfaced so the
+        #: agent can render a non-memory status message. Empty when the last retrieval was healthy.
+        self.last_warnings: list[str] = []
+        #: The shared authoritative agent channel (set by the adapter). The Fast Talker drives the turn.
+        self._status = status
+
+    def _publish(self, warnings: list[str], generation: int) -> None:
+        self.last_warnings = list(warnings)
+        if self._status is not None:
+            self._status.publish(generation, self.last_warnings)
+
+    async def get_context(self, query_text: str) -> list[dict[str, Any]]:
+        """Return retrieval results for the live query — cache first,
+        SDK fast path on miss. Returns ``[]`` on any error so the
+        speech loop is never blocked."""
+        # Allocate the generation at the START so an out-of-order completion cannot clobber a newer turn.
+        generation = self._status.begin() if self._status is not None else 0
+        cached = self.cache.match(query_text, threshold=self._match_threshold)
+        if cached is not None:
+            # RET-007: a cache-hit must reflect the CACHED degradation status, not a stale one from a
+            # previous turn — the Slow Thinker stored the warnings alongside the results.
+            self._publish(list(cached.warnings), generation)
+            return cached.results
+        try:
+            response = await self.client.retrieve(
+                namespace=self.namespace,
+                query_text=query_text,
+                mode="fast",
+                limit=self._fast_limit,
+            )
+        except Exception:
+            log.warning("fast-talker fallback failed", exc_info=True)
+            # RET-007: a total failure is VISIBLE on the agent-facing channel — never a silent [] that
+            # leaves a stale "healthy" (or stale-degraded) status from the previous turn.
+            self._publish([RETRIEVAL_UNAVAILABLE], generation)
+            return []
+        if not isinstance(response, dict):
+            self._publish([RETRIEVAL_UNAVAILABLE], generation)
+            return []
+        warnings = response.get("warnings", [])
+        self._publish(warnings if isinstance(warnings, list) else [], generation)
+        results = response.get("results", [])
+        return results if isinstance(results, list) else []

musubi_livekit/heuristics.py

@@ -0,0 +1,24 @@
+"""Cheap heuristics for opportunistic memory capture during voice sessions.
+
+Per [[07-interfaces/livekit-adapter]] § Event mapping —
+``interesting_fact_detected`` is described as optional and pattern-based.
+Keeping it as a small, explicit regex set lets the adapter capture
+"remember…" / "I always forget…" style asides without needing an
+LLM judge in the speech loop.
+"""
+
+from __future__ import annotations
+
+import re
+
+_INTERESTING_PATTERNS: tuple[re.Pattern[str], ...] = (
+    re.compile(r"\bremember\b", re.IGNORECASE),
+    re.compile(r"\bI (?:always )?forget\b", re.IGNORECASE),
+    re.compile(r"\b(?:save|store|note) (?:this|that) (?:to|in) memory\b", re.IGNORECASE),
+    re.compile(r"\bnever forget\b", re.IGNORECASE),
+)
+
+
+def detect_interesting_fact(utterance: str) -> bool:
+    """True if the utterance matches any of the heuristic patterns."""
+    return any(p.search(utterance) for p in _INTERESTING_PATTERNS)

musubi_livekit/redaction.py

@@ -0,0 +1,32 @@
+"""Minimal PII redaction pass for the LiveKit voice adapter.
+
+Per [[07-interfaces/livekit-adapter]] § Privacy. Off by default; the
+adapter only invokes this when ``LiveKitAdapterConfig.redact_pii=True``.
+Patterns cover the common voice-transcript cases (email, US SSN,
+phone-ish digit groups). The full canonical redactor lives in
+[[10-security/redaction]] and is not in scope for this slice.
+"""
+
+from __future__ import annotations
+
+import re
+
+_REDACTED = "[REDACTED]"
+
+_PII_PATTERNS: tuple[re.Pattern[str], ...] = (
+    # Emails.
+    re.compile(r"\b[\w.+-]+@[\w-]+\.[\w.-]+\b"),
+    # US SSN-shaped digit groups.
+    re.compile(r"\b\d{3}-\d{2}-\d{4}\b"),
+    # Phone-ish 10-digit groups with separators.
+    re.compile(r"\b\d{3}[-.\s]\d{3}[-.\s]\d{4}\b"),
+)
+
+
+def redact_pii(text: str) -> str:
+    """Return ``text`` with email / SSN / phone shapes replaced by
+    ``[REDACTED]``. Idempotent — running twice is a no-op."""
+    out = text
+    for pattern in _PII_PATTERNS:
+        out = pattern.sub(_REDACTED, out)
+    return out

musubi_livekit/slow_thinker.py

@@ -0,0 +1,92 @@
+"""Slow Thinker — pre-fetches deep-path retrieval between turns.
+
+Per [[07-interfaces/livekit-adapter]] § The dual-agent pattern. Runs
+its own asyncio task that the caller cancels and restarts whenever
+new transcript material arrives. Cancellation is silent: the cancelled
+task does not propagate ``CancelledError`` into the LiveKit event
+loop, so a fast user-interrupt never crashes the speech path.
+
+Read-only against Musubi (calls ``client.retrieve(mode="deep")``);
+result writes land in the shared :class:`ContextCache` for the Fast
+Talker to consume on the next 200ms tick.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from typing import Any
+
+from musubi_livekit.cache import (
+    RETRIEVAL_UNAVAILABLE,
+    ContextCache,
+    RetrievalStatus,
+)
+
+log = logging.getLogger("musubi_livekit.slow_thinker")
+
+
+class SlowThinker:
+    """Per-session deep-pre-fetch worker."""
+
+    def __init__(
+        self,
+        *,
+        client: Any,
+        namespace: str,
+        cache: ContextCache,
+        deep_limit: int = 15,
+        cache_ttl_s: float = 120.0,
+        status: RetrievalStatus | None = None,
+    ) -> None:
+        self.client = client
+        self.namespace = namespace
+        self.cache = cache
+        self._deep_limit = deep_limit
+        self._cache_ttl_s = cache_ttl_s
+        #: RET-007 — allowlisted degradation codes from the most recent pre-fetch (empty when healthy).
+        self.last_warnings: list[str] = []
+        #: The shared authoritative agent channel (set by the adapter) — a pre-fetch total failure must
+        #: be visible on it, not only on ``last_warnings``.
+        self._status = status
+        self._task: asyncio.Task[None] | None = None
+
+    def _publish(self, warnings: list[str], generation: int) -> None:
+        self.last_warnings = list(warnings)
+        if self._status is not None:
+            self._status.publish(generation, self.last_warnings)
+
+    async def on_user_utterance_segment(self, transcript_so_far: str) -> None:
+        """Cancel any in-flight pre-fetch, then start a new one with
+        the latest transcript. Idempotent if the same string lands
+        twice in a row — the new task simply replays the deep call."""
+        if self._task is not None and not self._task.done():
+            self._task.cancel()
+        self._task = asyncio.create_task(self._prefetch(transcript_so_far))
+
+    async def _prefetch(self, transcript: str) -> None:
+        # Allocate the generation at the START so a slow request that completes AFTER a newer request
+        # cannot clobber the newer one's status.
+        generation = self._status.begin() if self._status is not None else 0
+        try:
+            response = await self.client.retrieve(
+                namespace=self.namespace,
+                query_text=transcript,
+                mode="deep",
+                limit=self._deep_limit,
+            )
+        except asyncio.CancelledError:
+            # Surfacing this as a normal cancel keeps the LiveKit loop
+            # quiet — the new task replaces us.
+            raise
+        except Exception:
+            log.warning("slow-thinker pre-fetch failed", exc_info=True)
+            # RET-007: a total pre-fetch failure is a visible impairment on the agent channel, not a
+            # silent no-op that leaves a stale status from the previous turn.
+            self._publish([RETRIEVAL_UNAVAILABLE], generation)
+            return
+        warnings = response.get("warnings", []) if isinstance(response, dict) else []
+        self._publish(warnings if isinstance(warnings, list) else [], generation)
+        results = response.get("results", []) if isinstance(response, dict) else []
+        # Cache the warnings WITH the results so a later Fast Talker cache-hit preserves the status.
+        self.cache.put(transcript, results, ttl=self._cache_ttl_s, warnings=self.last_warnings)

musubi_livekit-0.1.0.dist-info/METADATA

@@ -0,0 +1,108 @@
+Metadata-Version: 2.5
+Name: musubi-livekit
+Version: 0.1.0
+Summary: LiveKit session callback adapter for the Musubi memory SDK
+Project-URL: Homepage, https://github.com/sourceblender/musubi-livekit
+Project-URL: Repository, https://github.com/sourceblender/musubi-livekit
+Project-URL: Issues, https://github.com/sourceblender/musubi-livekit/issues
+License-Expression: Apache-2.0
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: musubi-sdk>=0.1.0
+Description-Content-Type: text/markdown
+
+# musubi-livekit
+
+`musubi-livekit` connects a LiveKit voice session's callbacks to the Musubi
+memory API. It provides a `LiveKitAdapter`, a slow prefetcher, a fast context
+reader, a bounded cache, optional fact capture, and transcript handling. The
+package is a Python library: your LiveKit worker still owns the session,
+event subscriptions, credentials, and user-facing responses.
+
+## Install
+
+Requires Python 3.12 or later. The adapter depends on the standalone
+[`musubi-sdk`](https://pypi.org/project/musubi-sdk/) client, not the Musubi server.
+The SDK is installed from PyPI as a dependency:
+
+```bash
+pip install 'git+https://github.com/sourceblender/musubi-livekit.git'
+```
+
+The plugin itself is not published to PyPI yet; the GitHub install above is
+the current supported install path.
+
+## Use in a worker
+
+Construct one adapter per voice session. Feed it the transcript and session
+events from your own LiveKit worker. These are callbacks to wire into the
+worker, not an automatically installed LiveKit plugin.
+
+```python
+from musubi_sdk import AsyncMusubiClient
+from musubi_livekit import LiveKitAdapter, LiveKitAdapterConfig
+
+client = AsyncMusubiClient(base_url=api_url, token=token)
+adapter = LiveKitAdapter(
+    client=client,
+    namespace="assistant/voice/episodic",
+    artifact_namespace="assistant/voice/artifact",
+    config=LiveKitAdapterConfig(
+        capture_transcripts=False,
+        capture_facts=False,
+    ),
+)
+
+# Call from the matching LiveKit worker events:
+await adapter.on_transcript_segment(partial_text)
+await adapter.on_user_turn_completed(final_text)
+context = await adapter.fast_talker.get_context(final_text)
+warnings = adapter.retrieval_status
+await adapter.on_session_end(session_id=session_id, vtt_transcript=vtt_text)
+```
+
+Fact and transcript capture are enabled in the default config. Set the privacy
+flags deliberately for your application before handling a real session.
+`retrieval_status` exposes degradation warnings so the worker can tell the
+user when memory is unavailable. A successful callback call is not a guarantee
+that a transcript reached artifact storage: until the SDK has `artifacts.upload`,
+the adapter falls back to episodic capture. See the code and tests before
+promising artifact storage or delivery guarantees.
+
+## Development
+
+```bash
+uv sync --locked --python 3.12
+uv run pytest -q
+uv run ruff check src tests
+uv run ruff format --check src tests
+uv run mypy src/musubi_livekit
+```
+
+The unit suite exercises the extracted adapter and retrieval degradation
+channel. Three historical tests remain skipped because they require a running
+Musubi stack and a LiveKit session simulator; they are not release evidence.
+
+Five integration tests exercise the adapter through the real Musubi SDK and API.
+They write memories and thoughts, so point them only at a disposable test stack
+with an operator-scoped test token:
+
+```bash
+MUSUBI_TEST_API_URL=http://127.0.0.1:8100/v1 \
+MUSUBI_TEST_TOKEN=<disposable-test-token> \
+uv run pytest -q -m integration tests/integration/test_livekit_e2e.py
+```
+
+The default test command excludes these integration tests. Their fixture
+skips when either variable is missing. Linux CI also runs them against
+Musubi's disposable Docker integration stack; the pinned TEI test image has
+no ARM64 manifest, so that stack does not boot natively on Apple Silicon.
+
+## Contributing and security
+
+Discuss substantial changes in an issue first. Follow the
+[Sourceblender contributing guide](https://github.com/sourceblender/.github/blob/main/CONTRIBUTING.md).
+Report security issues privately through the repository Security tab or the
+[organization policy](https://github.com/sourceblender/.github/blob/main/SECURITY.md).
+
+Licensed under Apache-2.0. See [LICENSE](LICENSE).

musubi_livekit-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+musubi_livekit/__init__.py,sha256=B-mGo20pZJqz_DnJrhf03txvRSzKoz6Oe8iMjYbl5bs,746
+musubi_livekit/adapter.py,sha256=Ypcf9Ei2HZJGXdoeGVTjgfCw_j5evgMtWeYeb2rsHHU,8608
+musubi_livekit/cache.py,sha256=MnklF10zaefgiozSUJhsS4yRCH-pFMEA6tnhOPxDC2Y,5047
+musubi_livekit/config.py,sha256=lEodaRpn7dq9zRy4owBNReOLufteDkikSFvTmFppPHw,1224
+musubi_livekit/fast_talker.py,sha256=YzvY4azzaq7ALGu-zqeVa9MNhTcfP8zCpA5NiKvqk7s,3508
+musubi_livekit/heuristics.py,sha256=kXLzU_IhR7MIFWeM_0k-rOJXLOvyjicxXpk-Cpdy_ok,928
+musubi_livekit/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+musubi_livekit/redaction.py,sha256=0xraLjc8ZRoQaaPYeEHTIdBEsJPC54UbVwjdZAIaB_E,1034
+musubi_livekit/slow_thinker.py,sha256=eho3msSlD-RyMG8j2wRY7iWUYG6McBtzdfUFHpDyPUw,3889
+musubi_livekit-0.1.0.dist-info/METADATA,sha256=E8Uh_yrC_sFwPObuHRhqKx3v-_8DkaSp1Qdd7pJwFoE,4250
+musubi_livekit-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+musubi_livekit-0.1.0.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
+musubi_livekit-0.1.0.dist-info/RECORD,,

musubi_livekit-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

musubi_livekit-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.