converse-framework 0.2.0__py3-none-any.whl

converse_framework/providers/llamacpp.py

@@ -0,0 +1,264 @@
+"""llama.cpp HTTP provider (OpenAI-compatible API).
+
+The ``httpx`` package is imported lazily inside async methods so the base
+:mod:`converse_framework` package stays light. Install with::
+
+    pip install 'converse-framework[llamacpp]'
+
+Sampler values are provided either through the ``sampler`` config key at
+construction time, or at runtime through :meth:`set_sampler_provider`, which
+takes a zero-argument callable returning a dict of sampler overrides. The
+framework never imports the harness ``RuntimeSettings`` -- the harness is
+responsible for wiring the callable that resolves effective sampler values.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import AsyncIterator, Callable
+
+from converse_framework.protocols import (
+    LLMProvider,
+    ProviderCapabilities,
+    ProviderStatus,
+)
+
+SamplerProvider = Callable[[], dict]
+
+
+class LlamaCppProvider(LLMProvider):
+    def __init__(self, config: dict):
+        self.base_url = str(config.get("base_url", "http://127.0.0.1:8080")).rstrip("/")
+        self.model = str(config.get("model", "auto"))
+        self.temperature = float(config.get("temperature", 0.7))
+        self.max_tokens = int(config.get("max_tokens", 256))
+        self._sampler_provider: SamplerProvider | None = None
+        self._resolved_model: str | None = None
+
+    def set_sampler_provider(self, provider: SamplerProvider | None) -> None:
+        """Inject a callable that returns the current sampler overrides.
+
+        The framework never imports the harness ``RuntimeSettings``; the
+        harness wires this by passing ``RUNTIME_SETTINGS.effective_sampler``
+        (a bound method) or an equivalent lambda.
+        """
+        self._sampler_provider = provider
+
+    @property
+    def status(self) -> ProviderStatus:
+        return ProviderStatus(
+            name="llama.cpp",
+            kind="llm",
+            ready=False,
+            message=(
+                f"Configured for OpenAI-compatible llama.cpp server at {self.base_url}."
+            ),
+            capabilities=ProviderCapabilities(),
+            provider_id="llamacpp",
+            status_level="configured",
+        )
+
+    async def check_status(self) -> ProviderStatus:
+        return await self._http_check_status()
+
+    async def probe_status(self) -> ProviderStatus:
+        """Cheap probe: check httpx is importable; no HTTP call."""
+        try:
+            pass  # type: ignore[import-not-found]
+        except Exception as exc:  # pragma: no cover - import path
+            return ProviderStatus(
+                name="llama.cpp",
+                kind="llm",
+                ready=False,
+                message=(
+                    f"llama.cpp provider requires httpx; install with "
+                    f"pip install 'converse-framework[llamacpp]'. ({exc})"
+                ),
+                capabilities=ProviderCapabilities(),
+                provider_id="llamacpp",
+                status_level="unavailable",
+            )
+        # httpx is available; return existing cached status.
+        return self.status
+
+    async def load_status(self) -> ProviderStatus:
+        """Alias for probe_status - HTTP provider has no model loading."""
+        return await self.probe_status()
+
+    async def _http_check_status(self) -> ProviderStatus:
+        try:
+            import httpx  # type: ignore[import-not-found]
+        except Exception as exc:  # pragma: no cover - import path
+            return ProviderStatus(
+                name="llama.cpp",
+                kind="llm",
+                ready=False,
+                message=(
+                    f"llama.cpp provider requires httpx; install with "
+                    f"pip install 'converse-framework[llamacpp]'. ({exc})"
+                ),
+                capabilities=ProviderCapabilities(),
+                provider_id="llamacpp",
+            )
+        timeout = httpx.Timeout(connect=1.0, read=2.0, write=1.0, pool=1.0)
+        async with httpx.AsyncClient(timeout=timeout) as client:
+            try:
+                health = await client.get(f"{self.base_url}/health")
+                health.raise_for_status()
+                health_payload = health.json()
+            except Exception as exc:
+                return ProviderStatus(
+                    name="llama.cpp",
+                    kind="llm",
+                    ready=False,
+                    message=f"Cannot reach llama.cpp at {self.base_url}: {exc}",
+                    capabilities=ProviderCapabilities(),
+                    provider_id="llamacpp",
+                )
+
+            if health_payload.get("status") != "ok":
+                message = health_payload.get("error", {}).get(
+                    "message", "server did not report ready"
+                )
+                return ProviderStatus(
+                    name="llama.cpp",
+                    kind="llm",
+                    ready=False,
+                    message=f"llama.cpp reachable but not ready: {message}",
+                    capabilities=ProviderCapabilities(),
+                    provider_id="llamacpp",
+                )
+
+            try:
+                models = await client.get(f"{self.base_url}/v1/models")
+                models.raise_for_status()
+                models_payload = models.json()
+            except Exception as exc:
+                return ProviderStatus(
+                    name="llama.cpp",
+                    kind="llm",
+                    ready=False,
+                    message=f"llama.cpp health OK, but /v1/models failed: {exc}",
+                    capabilities=ProviderCapabilities(),
+                    provider_id="llamacpp",
+                )
+
+        model_ids = [
+            str(item.get("id", "unknown")) for item in models_payload.get("data", [])
+        ]
+        if not model_ids:
+            return ProviderStatus(
+                name="llama.cpp",
+                kind="llm",
+                ready=False,
+                message=(
+                    "llama.cpp health OK, but no loaded model was reported by "
+                    "/v1/models."
+                ),
+                capabilities=ProviderCapabilities(),
+                provider_id="llamacpp",
+            )
+        model_list = ", ".join(model_ids[:3])
+        selected_model = self.model if self.model != "auto" else model_ids[0]
+        if self.model != "auto" and self.model not in model_ids:
+            return ProviderStatus(
+                name="llama.cpp",
+                kind="llm",
+                ready=False,
+                message=(
+                    f"llama.cpp is ready, but configured model '{self.model}' is "
+                    f"not in /v1/models. Loaded: {model_list}"
+                ),
+                capabilities=ProviderCapabilities(),
+                provider_id="llamacpp",
+            )
+        if self._resolved_model is not None and selected_model != self._resolved_model:
+            self._resolved_model = None
+        active = "auto-selected" if self.model == "auto" else "selected"
+        return ProviderStatus(
+            name="llama.cpp",
+            kind="llm",
+            ready=True,
+            message=(
+                f"Ready at {self.base_url}; {active} model: {selected_model}; "
+                f"loaded: {model_list}"
+            ),
+            capabilities=ProviderCapabilities(),
+            provider_id="llamacpp",
+        )
+
+    async def stream_response(
+        self, messages: list[dict[str, str]]
+    ) -> AsyncIterator[str]:
+        if self._resolved_model is None:
+            self._resolved_model = await self._resolve_model()
+        model = self._resolved_model
+        sampler = self._build_sampler()
+        payload: dict = {
+            "model": model,
+            "messages": messages,
+            "stream": True,
+        }
+        for key, value in sampler.items():
+            payload[key] = value
+        url = f"{self.base_url}/v1/chat/completions"
+        try:
+            import httpx  # type: ignore[import-not-found]
+        except Exception as exc:  # pragma: no cover - import path
+            raise RuntimeError(
+                "llama.cpp provider requires httpx; install with "
+                "pip install 'converse-framework[llamacpp]'."
+            ) from exc
+        timeout = httpx.Timeout(connect=3.0, read=60.0, write=10.0, pool=3.0)
+        try:
+            async with httpx.AsyncClient(timeout=timeout) as client:
+                async with client.stream("POST", url, json=payload) as response:
+                    response.raise_for_status()
+                    async for line in response.aiter_lines():
+                        if not line.startswith("data: "):
+                            continue
+                        data = line[6:].strip()
+                        if data == "[DONE]":
+                            break
+                        chunk = json.loads(data)
+                        delta = chunk.get("choices", [{}])[0].get("delta", {})
+                        content = delta.get("content")
+                        if content:
+                            yield content
+        except Exception:
+            self._resolved_model = None
+            raise
+
+    def _build_sampler(self) -> dict:
+        defaults = {
+            "temperature": self.temperature,
+            "max_tokens": self.max_tokens,
+        }
+        if self._sampler_provider is not None:
+            return self._sampler_provider()
+        return defaults
+
+    async def _resolve_model(self) -> str:
+        if self.model != "auto":
+            return self.model
+        try:
+            import httpx  # type: ignore[import-not-found]
+        except Exception as exc:  # pragma: no cover - import path
+            raise RuntimeError(
+                "llama.cpp provider requires httpx; install with "
+                "pip install 'converse-framework[llamacpp]'."
+            ) from exc
+        timeout = httpx.Timeout(connect=1.0, read=2.0, write=1.0, pool=1.0)
+        async with httpx.AsyncClient(timeout=timeout) as client:
+            response = await client.get(f"{self.base_url}/v1/models")
+            response.raise_for_status()
+            payload = response.json()
+        model_data = payload.get("data", [])
+        if not model_data:
+            raise RuntimeError(
+                "llama.cpp did not report a loaded model from /v1/models"
+            )
+        return str(model_data[0].get("id", "unknown"))
+
+    async def unload(self) -> ProviderStatus:
+        return self.status

converse_framework/providers/mock.py

@@ -0,0 +1,171 @@
+"""Mock provider implementations with no external dependencies.
+
+These are always available and useful for testing pipeline orchestration
+without real model backends.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import AsyncIterator
+
+from converse_framework.audio_utils import make_tone_wav
+from converse_framework.protocols import (
+    ASRProvider,
+    AudioChunk,
+    LLMProvider,
+    ProviderCapabilities,
+    ProviderStatus,
+    TTSProvider,
+    TranscriptEvent,
+    VADProvider,
+)
+
+
+class MockVADProvider(VADProvider):
+    def __init__(self, config: dict):
+        self.config = config
+
+    @property
+    def status(self) -> ProviderStatus:
+        return ProviderStatus(
+            name="mock-vad",
+            kind="vad",
+            ready=True,
+            message="Mock VAD accepts browser speech-start/speech-end events.",
+            capabilities=ProviderCapabilities(supports_barge_in=True),
+            provider_id="mock",
+        )
+
+    async def check_status(self) -> ProviderStatus:
+        return self.status
+
+    async def process_frame(self, frame) -> list:
+        return []
+
+    async def unload(self) -> ProviderStatus:
+        return self.status
+
+
+class MockASRProvider(ASRProvider):
+    def __init__(self, config: dict):
+        self.config = config
+
+    @property
+    def status(self) -> ProviderStatus:
+        return ProviderStatus(
+            name="mock-asr",
+            kind="asr",
+            ready=True,
+            message="Text input is treated as the final transcript.",
+            capabilities=ProviderCapabilities(supports_partials=True),
+            provider_id="mock",
+        )
+
+    async def check_status(self) -> ProviderStatus:
+        return self.status
+
+    async def load(self) -> ProviderStatus:
+        return self.status
+
+    async def transcribe_text_input(self, text: str) -> AsyncIterator[TranscriptEvent]:
+        words = text.strip().split()
+        if not words:
+            return
+        partial = []
+        for word in words:
+            partial.append(word)
+            await asyncio.sleep(0.01)
+            yield TranscriptEvent(text=" ".join(partial), final=False)
+        yield TranscriptEvent(text=" ".join(words), final=True)
+
+    async def transcribe_audio(
+        self, pcm_s16le: bytes, sample_rate: int, progress=None
+    ) -> AsyncIterator[TranscriptEvent]:
+        if progress:
+            await progress(
+                "asr.progress",
+                {"stage": "mock", "message": "Mock ASR transcribing audio."},
+            )
+        yield TranscriptEvent(text="Mock ASR heard audio input.", final=True)
+
+    async def unload(self) -> ProviderStatus:
+        return self.status
+
+
+class MockLLMProvider(LLMProvider):
+    def __init__(self, config: dict):
+        self.first_token_delay = float(config.get("first_token_delay_ms", 120)) / 1000
+        self.token_delay = float(config.get("token_delay_ms", 28)) / 1000
+
+    @property
+    def status(self) -> ProviderStatus:
+        return ProviderStatus(
+            name="mock-llm",
+            kind="llm",
+            ready=True,
+            message="Mock LLM streams a deterministic local response.",
+            capabilities=ProviderCapabilities(),
+            provider_id="mock",
+        )
+
+    async def check_status(self) -> ProviderStatus:
+        return self.status
+
+    async def stream_response(
+        self, messages: list[dict[str, str]]
+    ) -> AsyncIterator[str]:
+        user_text = messages[-1]["content"] if messages else ""
+        response = (
+            f"I heard: {user_text}. This is the harness running in mock mode, "
+            "with provider boundaries and latency events active."
+        )
+        await asyncio.sleep(self.first_token_delay)
+        for token in response.split(" "):
+            yield token + " "
+            await asyncio.sleep(self.token_delay)
+
+
+class MockTTSProvider(TTSProvider):
+    def __init__(self, config: dict):
+        self.first_chunk_delay = float(config.get("first_chunk_delay_ms", 80)) / 1000
+        self.chunk_delay = float(config.get("chunk_delay_ms", 40)) / 1000
+
+    @property
+    def status(self) -> ProviderStatus:
+        return ProviderStatus(
+            name="mock-tts",
+            kind="tts",
+            ready=True,
+            message="Mock TTS emits short WAV tones so playback paths can be tested.",
+            capabilities=ProviderCapabilities(supports_streaming_tts=True),
+            provider_id="mock",
+        )
+
+    async def check_status(self) -> ProviderStatus:
+        return self.status
+
+    async def load(self) -> ProviderStatus:
+        return self.status
+
+    async def unload(self) -> ProviderStatus:
+        return self.status
+
+    async def stream_audio(self, text: str) -> AsyncIterator[AudioChunk]:
+        await asyncio.sleep(self.first_chunk_delay)
+        frequency = 420 + (len(text) % 160)
+        yield AudioChunk(
+            data=make_tone_wav(frequency=frequency), mime_type="audio/wav", final=True
+        )
+        await asyncio.sleep(self.chunk_delay)
+
+    async def stream_audio_with_progress(
+        self, text: str, progress=None
+    ) -> AsyncIterator[AudioChunk]:
+        if progress:
+            await progress(
+                "tts.progress",
+                {"stage": "mock", "message": "Mock TTS generating tone."},
+            )
+        async for chunk in self.stream_audio(text):
+            yield chunk