agentship-voice 0.0.3__tar.gz

agentship_voice-0.0.3/.gitignore

@@ -0,0 +1,27 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+
+# Env / secrets — never commit
+.env
+.env.*
+!.env.example
+
+# Editor / OS
+.DS_Store
+.idea/
+.vscode/
+
+# Docs build
+site/

agentship_voice-0.0.3/PKG-INFO

@@ -0,0 +1,29 @@
+Metadata-Version: 2.5
+Name: agentship-voice
+Version: 0.0.3
+Summary: AgentShip voice — run the same agent over a live audio stream. A cascaded pipeline (transport/VAD → STT → agent → TTS) with barge-in, hosted in either Pipecat or LiveKit Agents. The agent is the one the REST service runs; only the hosting differs.
+License-Expression: Apache-2.0
+Requires-Python: >=3.13
+Requires-Dist: agentship-core==0.0.3
+Provides-Extra: all
+Requires-Dist: livekit-agents<2,>=1.8; extra == 'all'
+Requires-Dist: pipecat-ai<2,>=1.8; extra == 'all'
+Provides-Extra: livekit
+Requires-Dist: livekit-agents<2,>=1.8; extra == 'livekit'
+Provides-Extra: pipecat
+Requires-Dist: pipecat-ai<2,>=1.8; extra == 'pipecat'
+Description-Content-Type: text/markdown
+
+# agentship-voice
+
+Run the same AgentShip agent over a live audio stream.
+
+```bash
+pip install "agentship-voice[pipecat]"   # or [livekit]
+```
+
+The agent is the one the REST service runs — same spec, memory, tools and tracing. A voice
+framework supplies the ears (transport, VAD, STT) and the mouth (TTS); this package supplies
+the agent in the shape that framework expects.
+
+See [`docs/capabilities/voice.md`](../../docs/capabilities/voice.md).

agentship_voice-0.0.3/README.md

@@ -0,0 +1,13 @@
+# agentship-voice
+
+Run the same AgentShip agent over a live audio stream.
+
+```bash
+pip install "agentship-voice[pipecat]"   # or [livekit]
+```
+
+The agent is the one the REST service runs — same spec, memory, tools and tracing. A voice
+framework supplies the ears (transport, VAD, STT) and the mouth (TTS); this package supplies
+the agent in the shape that framework expects.
+
+See [`docs/capabilities/voice.md`](../../docs/capabilities/voice.md).

agentship_voice-0.0.3/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "agentship-voice"
+version = "0.0.3"
+description = "AgentShip voice — run the same agent over a live audio stream. A cascaded pipeline (transport/VAD → STT → agent → TTS) with barge-in, hosted in either Pipecat or LiveKit Agents. The agent is the one the REST service runs; only the hosting differs."
+readme = "README.md"
+requires-python = ">=3.13"
+license = "Apache-2.0"
+# The base install carries NO voice framework. `VoiceTurn` is pure asyncio over
+# agentship-core, so the seam, the config surface and their tests run keyless in CI;
+# a framework arrives only with its extra. Same shape as the observability package,
+# where the vendor SDK is never a hard dependency of the contract.
+dependencies = ["agentship-core==0.0.3"]
+
+[project.optional-dependencies]
+# Pipecat hosts the agent as a FrameProcessor in a frame pipeline.
+pipecat = ["pipecat-ai>=1.8,<2"]
+# LiveKit hosts the agent as an llm.LLM inside an AgentSession — a different shape
+# for the same agent, which is exactly why the seam below is text-in/text-out and
+# not a pipeline node. See adapters/base.py.
+livekit = ["livekit-agents>=1.8,<2"]
+all = ["pipecat-ai>=1.8,<2", "livekit-agents>=1.8,<2"]
+
+[project.entry-points."agentship.voice_frameworks"]
+pipecat = "agentship_voice.adapters.pipecat_adapter:PipecatAdapter"
+livekit = "agentship_voice.adapters.livekit_adapter:LiveKitAdapter"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/agentship_voice"]

agentship_voice-0.0.3/src/agentship_voice/__init__.py

@@ -0,0 +1,25 @@
+"""Run the same AgentShip agent over a live audio stream.
+
+The agent is the one the REST service runs — same spec, same memory, same tools, same tracing.
+Only the hosting differs: a voice framework supplies the ears (transport, VAD, STT) and the
+mouth (TTS), and this package supplies the agent in the shape that framework expects.
+
+The public surface is small on purpose:
+
+* :class:`~agentship_voice.turn.VoiceTurn` — text in, spoken text out. The whole vendor-free
+  seam, and the only thing both frameworks could agree on.
+* :class:`~agentship_voice.trace.LatencyTrace` — where a turn's time went, emitted every turn.
+* :class:`~agentship.spec.VoiceSpec` — the ``voice:`` block. It lives in the **kernel**, beside
+  ``ObservabilitySpec``, because the kernel owns every authoring surface and imports no vendor;
+  the provider *names* in it are validated here, in :mod:`agentship_voice.factories`, which is
+  the half that knows what it can actually build.
+
+Adapters live in :mod:`agentship_voice.adapters` and each needs its own extra installed.
+"""
+
+from agentship.spec import VoiceSpec
+
+from .trace import LatencyTrace
+from .turn import VoiceTurn
+
+__all__ = ["LatencyTrace", "VoiceSpec", "VoiceTurn"]

agentship_voice-0.0.3/src/agentship_voice/adapters/__init__.py

@@ -0,0 +1,40 @@
+"""Framework adapters. Each imports its framework lazily, so importing this package is free.
+
+An adapter is only meaningful with its extra installed (``agentship-voice[pipecat]`` or
+``[livekit]``); the contract they implement lives in :mod:`agentship_voice.adapters.base`.
+
+Adapters are discovered through the ``agentship.voice_frameworks`` entry-point group, the same
+mechanism engines use — so a third party ships a class and one packaging line, and
+``voice.framework: theirs`` works with no edit here. Our own two are registered the same way
+rather than special-cased, because a plugin system its own author bypasses is one that quietly
+stops working for everyone else.
+"""
+
+from agentship.errors import CapabilityError
+from agentship.registry import Registry
+
+from .base import VoiceAdapter
+
+__all__ = ["VOICE_FRAMEWORKS", "VoiceAdapter", "get_adapter"]
+
+#: Voice framework adapters by ``voice.framework`` name.
+VOICE_FRAMEWORKS: Registry[type[VoiceAdapter]] = Registry(
+    "agentship.voice_frameworks", label="voice framework"
+)
+
+
+def get_adapter(name: str) -> VoiceAdapter:
+    """Return the adapter for ``name``, or raise naming the frameworks that exist.
+
+    An unknown framework fails here rather than deep inside a session, and the message lists the
+    real choices instead of leaving the author to guess the spelling.
+
+    Loading is lazy by construction: an entry point is only imported when its name is asked for,
+    so a stack with neither framework installed can still read this package's config and docs —
+    and a broken third-party adapter cannot stop ours from loading.
+    """
+    adapter_class = VOICE_FRAMEWORKS.get(name)
+    if adapter_class is None:
+        known = ", ".join(VOICE_FRAMEWORKS.names()) or "none installed"
+        raise CapabilityError(f"unknown voice framework {name!r} — available: {known}")
+    return adapter_class()

agentship_voice-0.0.3/src/agentship_voice/adapters/base.py

@@ -0,0 +1,62 @@
+"""The contract a voice framework must satisfy to host an AgentShip agent.
+
+Deliberately narrow. An adapter is asked for two things:
+
+1. **host the agent** — wrap a :class:`~agentship_voice.turn.VoiceTurn` in whatever shape its
+   framework requires (a Pipecat ``FrameProcessor``, a LiveKit ``llm.LLM``);
+2. **run a session** — assemble transport, VAD, STT and TTS around it and serve until stopped.
+
+Everything else a voice stack does — endpointing, turn detection, barge-in, jitter buffers,
+audio codecs — belongs to the framework and is not restated here. Restating it would mean
+owning it, and the point of two adapters is that neither framework's model leaks into ours.
+
+**Why this ABC has two implementations from the start.** The engine ABC deliberately waits
+for its second engine before freezing (ADR: the shape of an abstraction is a guess until a
+second thing fits into it). Voice does not get that luxury cheaply: Pipecat and LiveKit
+disagree about something fundamental — where the agent sits — so an ABC drawn against either
+one alone would encode that framework's assumptions. Writing both at once is what proved the
+seam had to be text-in/text-out rather than a pipeline node.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from agentship.spec import VoiceSpec
+
+from ..turn import VoiceTurn
+
+
+class VoiceAdapter(ABC):
+    """Host an AgentShip agent inside one voice framework."""
+
+    #: Name used in ``voice.framework`` to select this adapter.
+    name: str
+
+    @abstractmethod
+    def host(self, turn: VoiceTurn) -> object:
+        """Return ``turn`` wrapped in this framework's own agent shape.
+
+        The return type is deliberately ``object``: a Pipecat ``FrameProcessor`` and a
+        LiveKit ``llm.LLM`` share no base class, and inventing a common one would mean
+        adding a layer neither framework asked for. Callers hand the result straight back
+        to the framework that produced its type.
+        """
+
+    @abstractmethod
+    async def run(self, turn: VoiceTurn, config: VoiceSpec) -> None:
+        """Assemble the pipeline around ``turn`` and serve until cancelled.
+
+        Returns only when the session ends. Cancellation is the normal way to stop, so an
+        implementation must leave the transport and provider connections closed on the way
+        out rather than relying on process exit.
+        """
+
+    @abstractmethod
+    def missing_dependency(self) -> str | None:
+        """Return an actionable message when this framework is not installed, else ``None``.
+
+        Checked before a session is assembled so an absent extra is one clear line naming the
+        install, not an ``ImportError`` from three frames inside the framework. This mirrors
+        ``agentship doctor``: a capability that cannot run should say so up front.
+        """

agentship_voice-0.0.3/src/agentship_voice/adapters/livekit_adapter.py

@@ -0,0 +1,149 @@
+"""Host an AgentShip agent as the LLM inside a LiveKit ``AgentSession``.
+
+LiveKit does not have a pipeline node to drop an agent into. It has an ``AgentSession`` with
+slots — ``stt=``, ``vad=``, ``llm=``, ``tts=`` — and the agent goes in the ``llm`` slot. So
+what we implement is ``llm.LLM``: given a chat context, return a stream of ``ChatChunk``.
+
+That is a genuinely different shape from Pipecat's frame processor, which is why the seam
+these two share had to be smaller than a pipeline node (see :mod:`agentship_voice.turn`).
+
+**Who witnesses what was spoken.** On Pipecat we add a processor after TTS, because nothing
+else reports it. LiveKit already does this work: it emits ``conversation_item_added`` with a
+``ChatMessage`` that carries ``interrupted`` and content **already truncated to what was
+actually spoken**. So here the adapter subscribes rather than measures — using the
+framework's own answer instead of a second, worse one of our own.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+
+from agentship.spec import VoiceSpec
+
+from ..turn import VoiceTurn
+from .base import VoiceAdapter
+
+logger = logging.getLogger("agentship.voice")
+
+
+def _build_llm(turn: VoiceTurn):
+    """Return an ``llm.LLM`` subclass bound to ``turn``.
+
+    Built inside a function for the same reason as the Pipecat processors: importing this
+    package must not require the framework, so the base classes are resolved on use.
+    """
+    from livekit.agents import llm
+
+    class _AgentShipStream(llm.LLMStream):
+        """Streams one AgentShip turn into LiveKit's chunk channel."""
+
+        async def _run(self) -> None:
+            """Run the agent for the newest user message and emit its reply as chunks.
+
+            LiveKit hands the whole chat context, but AgentShip keeps its own conversation
+            through the session id — the same short-term memory the REST path uses. So only
+            the latest user message is taken; replaying LiveKit's history as well would give
+            the agent the conversation twice.
+            """
+            spoken_to = _latest_user_text(self._chat_ctx)
+            if not spoken_to:
+                return  # nothing was said; emit no chunks rather than an empty assistant turn
+
+            async for chunk in turn.say(spoken_to):
+                self._event_ch.send_nowait(
+                    llm.ChatChunk(
+                        id=self._llm._next_chunk_id(),
+                        delta=llm.ChoiceDelta(role="assistant", content=chunk),
+                    )
+                )
+
+    class AgentShipLLM(llm.LLM):
+        """An AgentShip agent in the shape LiveKit's ``AgentSession`` expects."""
+
+        def __init__(self) -> None:
+            """Hold a counter so each emitted chunk carries a distinct id."""
+            super().__init__()
+            self._chunks = 0
+
+        def _next_chunk_id(self) -> str:
+            """Return a per-stream unique chunk id."""
+            self._chunks += 1
+            return f"agentship-{self._chunks}"
+
+        def chat(self, *, chat_ctx, tools=None, conn_options=None, **kwargs):
+            """Return the stream that runs one AgentShip turn.
+
+            Tool arguments are accepted and ignored: tools belong to the agent's own spec and
+            run inside the engine, so letting LiveKit also inject them would give the model
+            two competing tool sets for one turn.
+            """
+            from livekit.agents.types import DEFAULT_API_CONNECT_OPTIONS
+
+            return _AgentShipStream(
+                self,
+                chat_ctx=chat_ctx,
+                tools=tools or [],
+                conn_options=conn_options or DEFAULT_API_CONNECT_OPTIONS,
+            )
+
+    return AgentShipLLM
+
+
+def _latest_user_text(chat_ctx) -> str:
+    """Return the text of the newest user message in ``chat_ctx``, or ``""``."""
+    for item in reversed(getattr(chat_ctx, "items", [])):
+        if getattr(item, "role", None) == "user":
+            return (getattr(item, "text_content", None) or "").strip()
+    return ""
+
+
+class LiveKitAdapter(VoiceAdapter):
+    """Run an AgentShip agent inside a LiveKit ``AgentSession``."""
+
+    name = "livekit"
+
+    def missing_dependency(self) -> str | None:
+        """Return an install line when LiveKit Agents is absent, else ``None``."""
+        try:
+            import livekit.agents  # noqa: F401
+        except ImportError:
+            return (
+                "voice.framework is 'livekit' but livekit-agents is not installed — "
+                'pip install "agentship-voice[livekit]"'
+            )
+        return None
+
+    def host(self, turn: VoiceTurn) -> object:
+        """Return the ``llm.LLM`` to pass as ``AgentSession(llm=...)``."""
+        return _build_llm(turn)()
+
+    def witness(self, session, turn: VoiceTurn) -> None:
+        """Subscribe to the session so what LiveKit actually spoke reaches ``turn``.
+
+        LiveKit truncates an interrupted assistant message to the words that played, so this
+        confirms against the framework's own record rather than a second measurement of ours.
+        Call once, after the session is created and before it starts.
+        """
+
+        def _on_item(event) -> None:
+            """Record an assistant message as spoken, and correct history if it was cut off."""
+            item = getattr(event, "item", None)
+            if item is None or getattr(item, "role", None) != "assistant":
+                return
+            text = getattr(item, "text_content", None) or ""
+            if text:
+                turn.confirm_spoken(text)
+            if getattr(item, "interrupted", False):
+                # LiveKit says so itself, so there is nothing to infer. Scheduled rather than
+                # awaited because this is a synchronous event callback: blocking it would stall
+                # the session's own event loop while we write to a checkpoint store.
+                asyncio.create_task(turn.interrupted())  # noqa: RUF006 — fire-and-forget by design
+
+        session.on("conversation_item_added", _on_item)
+
+    async def run(self, turn: VoiceTurn, config: VoiceSpec) -> None:
+        """Assemble a room session around ``turn`` and serve until cancelled."""
+        raise NotImplementedError(
+            "LiveKitAdapter.run lands with the transport task — host() and witness() work now."
+        )