caudate-cli 0.1.0__py3-none-any.whl

reflection/reflector.py

@@ -0,0 +1,127 @@
+"""Reflector — evaluates outcomes and extracts lessons."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from config import SUCCESS_THRESHOLD
+from core.schemas import (
+    Episode, Goal, Reflection, Task, ToolResultStatus,
+)
+from llm.provider import LLMProvider
+
+logger = logging.getLogger(__name__)
+
+
+class ReflectionOutput(BaseModel):
+    """LLM-emitted reflection structure."""
+    score: float = Field(ge=0.0, le=1.0)
+    what_happened: str = ""
+    what_worked: str = ""
+    what_failed: str = ""
+    lesson: str = ""
+    should_replan: bool = False
+    replan_reason: str = ""
+
+REFLECT_PROMPT = """You are the reflection module of a cognitive architecture.
+Evaluate what just happened and extract lessons.
+
+Goal: {goal}
+Task attempted: {task}
+Action taken: {action}
+Tool used: {tool}
+Result status: {status}
+Result output: {output}
+Error (if any): {error}
+
+Respond with JSON:
+{{
+  "score": 0.0 to 1.0 (how successful was this action),
+  "what_happened": "brief description",
+  "what_worked": "what went well",
+  "what_failed": "what went wrong",
+  "lesson": "key takeaway for future actions",
+  "should_replan": true/false,
+  "replan_reason": "why replanning is needed (if applicable)"
+}}"""
+
+
+class Reflector:
+    """Evaluates action outcomes and produces structured reflections."""
+
+    def __init__(self, llm: LLMProvider):
+        self.llm = llm
+
+    async def reflect(
+        self,
+        episode: Episode,
+        goal: Goal,
+        task: Task,
+    ) -> Reflection:
+        """Reflect on an episode and produce a structured evaluation."""
+        result = episode.result
+
+        # Fast path: clear success → skip LLM. Originally only no-tool
+        # reasoning steps short-circuited; now any clean tool success
+        # does too, saving an LLM round-trip per successful step. The
+        # meta-learner's value still comes mainly from failure-reflections
+        # and the periodic strategy pass, so dropping prose reflections
+        # on routine successes costs nothing observable.
+        if result and result.status == ToolResultStatus.SUCCESS:
+            tool = task.tool_name or "Reasoning"
+            return Reflection(
+                episode_id=episode.id,
+                goal_id=goal.id,
+                score=0.85,
+                what_happened=f"{tool} step completed: {task.description}",
+                what_worked=f"{tool} executed without error",
+                lesson="",
+            )
+
+        # Use LLM for nuanced reflection
+        prompt = REFLECT_PROMPT.format(
+            goal=goal.description,
+            task=task.description,
+            action=episode.action,
+            tool=episode.tool_name or "none",
+            status=result.status.value if result else "unknown",
+            output=str(result.output)[:500] if result and result.output else "none",
+            error=result.error or "none" if result else "unknown",
+        )
+
+        try:
+            data = await self.llm.structured_output(
+                prompt=prompt, response_model=ReflectionOutput,
+                caller="reflection",
+            )
+            return Reflection(
+                episode_id=episode.id,
+                goal_id=goal.id,
+                score=data.score,
+                what_happened=data.what_happened,
+                what_worked=data.what_worked,
+                what_failed=data.what_failed,
+                lesson=data.lesson,
+                should_replan=data.should_replan,
+                replan_reason=data.replan_reason,
+            )
+        except Exception as e:
+            logger.error(f"Reflection failed: {e}")
+            # Fallback: score based on result status
+            score = 0.8 if result and result.status == ToolResultStatus.SUCCESS else 0.2
+            return Reflection(
+                episode_id=episode.id,
+                goal_id=goal.id,
+                score=score,
+                what_happened=f"Action {'succeeded' if score > 0.5 else 'failed'}",
+                lesson=f"Reflection generation failed: {e}",
+                should_replan=score < SUCCESS_THRESHOLD,
+                replan_reason="Action failed" if score < SUCCESS_THRESHOLD else "",
+            )
+
+    def needs_replan(self, reflection: Reflection) -> bool:
+        """Determine if a reflection warrants re-planning."""
+        return reflection.should_replan or reflection.score < SUCCESS_THRESHOLD

ui/__init__.py

@@ -0,0 +1,5 @@
+"""Cognos UI layer — rich-based terminal rendering."""
+
+from ui.display import StreamDisplay
+
+__all__ = ["StreamDisplay"]

ui/display.py

@@ -0,0 +1,88 @@
+"""StreamDisplay — render agentic-loop stream events as clean inline text.
+
+Goals:
+  - text_delta events stream tokens directly to stdout, no surrounding box
+  - tool calls show as a single dim arrow line: `→ Glob(...)`
+  - tool results show as a dim arrow with a short preview: `← /path/to/...`
+  - no panels, no border lines, no live re-render flicker
+
+Anything that wants pretty boxes can wrap the output itself.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from typing import Any
+
+from rich.console import Console
+
+from core.schemas import StreamEvent
+
+
+class StreamDisplay:
+    """Consumes StreamEvents from AgenticLoop.run_streaming and prints them."""
+
+    def __init__(self, console: Console | None = None):
+        self.console = console or Console()
+        self._text: list[str] = []
+        self._wrote_text = False
+
+    async def render(self, stream) -> str:
+        """Consume an async iterator of StreamEvents, returning the final text."""
+        self._text = []
+        self._wrote_text = False
+
+        async for event in stream:
+            self._handle(event)
+
+        # Trailing newline if we streamed anything so the next prompt starts clean.
+        if self._wrote_text:
+            self.console.file.write("\n")
+            self.console.file.flush()
+        return "".join(self._text)
+
+    # ------------------------------------------------------------------
+
+    def _handle(self, event: StreamEvent) -> None:
+        t = event.type
+        if t == "text_delta" and event.delta:
+            self._text.append(event.delta)
+            # Write directly to the underlying file to avoid Rich's
+            # auto-formatting on tokens that may contain markup chars.
+            self.console.file.write(event.delta)
+            self.console.file.flush()
+            self._wrote_text = True
+        elif t == "tool_use_end":
+            self._flush_newline()
+            args = _summarize_args(event.tool_input or {})
+            self.console.print(f"[dim]→ {event.tool_name}({args})[/dim]")
+        elif t == "tool_result":
+            self._flush_newline()
+            preview = (event.delta or "").strip().splitlines()[0] if event.delta else ""
+            if len(preview) > 160:
+                preview = preview[:157] + "…"
+            if preview:
+                self.console.print(f"[dim]← {preview}[/dim]")
+        elif t == "thinking_delta" and event.delta:
+            self._flush_newline()
+            self.console.print(f"[dim italic]thinking: {event.delta}[/dim italic]")
+        # message_start / message_stop: nothing to render
+
+    def _flush_newline(self) -> None:
+        """If the previous output was inline text, drop a newline before printing
+        an aux line so they don't run together on the same row."""
+        if self._wrote_text:
+            self.console.file.write("\n")
+            self.console.file.flush()
+            self._wrote_text = False
+
+
+def _summarize_args(args: dict[str, Any]) -> str:
+    try:
+        s = json.dumps(args, ensure_ascii=False)
+    except (TypeError, ValueError):
+        s = str(args)
+    if len(s) > 120:
+        s = s[:117] + "…"
+    return s

voice/conversation.py

@@ -0,0 +1,125 @@
+"""Voice conversation — full listen-think-speak loop wired into CognosAgent.
+
+This is the post-Phase-2 rewrite. The old loop bypassed the agent and
+talked to `LLMProvider` directly, which meant no personality, no memory,
+no tools, no permissions. Now it goes through `CognosAgent.chat()` so
+voice mode is just the same agentic loop with a different I/O surface.
+
+Voice-mode wisdom is injected via a system-prompt addendum rather than
+forking the personality engine: the agent stays itself, it just speaks
+shorter and avoids markdown.
+
+Interruption is handled with a Ctrl+C inside `speaker.speak()` — the
+playback aborts, the user starts talking, and we resume listening. No
+duplex audio (that's Moshi territory) but enough to feel responsive.
+"""
+
+from __future__ import annotations
+
+import logging
+
+import sounddevice as sd
+
+from core.agent import CognosAgent
+from voice.listener import Listener
+from voice.speaker import Speaker
+from voice.stt import STT, make_stt
+
+logger = logging.getLogger(__name__)
+
+
+VOICE_INSTRUCTIONS = """You are speaking, not writing. Apply these rules:
+
+- Reply in 1-3 short sentences. Conversational, not lecturing.
+- No markdown, bullet points, headings, code blocks, or URLs.
+- If the user asks for code or a list, summarize it in prose and offer to send the full version to text mode.
+- Spell out symbols when they matter ('greater than' not '>').
+- Never say "as an AI" or "I am an AI". You are Cognos.
+- If you didn't catch what was said, ask once for it to be repeated."""
+
+
+_EXIT_PHRASES = {
+    "goodbye", "good bye", "bye", "bye bye", "exit", "quit", "stop",
+    "end conversation", "shut down", "shut up", "that's all",
+}
+
+
+class VoiceConversation:
+    """Full conversational voice loop: listen → agent.chat → speak."""
+
+    def __init__(
+        self,
+        agent: CognosAgent,
+        stt: STT | str = "moonshine",
+        tts: str = "kokoro",
+        voice: str | None = None,
+        voice_path: str | None = None,
+        **stt_kwargs,
+    ):
+        self.agent = agent
+        self.listener = Listener(stt=stt, **stt_kwargs)
+        # Speaker picks the right TTS keyword: Piper takes a file path,
+        # Kokoro takes a voice id. Speaker handles the dispatch.
+        self.speaker = Speaker(tts=tts, voice=voice, voice_path=voice_path)
+        self._inject_voice_instructions()
+
+    def _inject_voice_instructions(self) -> None:
+        """Add the voice-mode prompt addendum to the agent's system prompt.
+
+        Personality wraps the system prompt at every turn, so we extend
+        its augmentation chain rather than mutating any stored prompt.
+        """
+        existing = self.agent.agentic.system_prompt_provider
+
+        def voice_wrap(base: str) -> str:
+            wrapped = existing(base) if existing else base
+            return f"{wrapped}\n\n{VOICE_INSTRUCTIONS}"
+
+        self.agent.agentic.system_prompt_provider = voice_wrap
+
+    async def run(self, greeting: bool = True) -> None:
+        await self.agent.start()  # MCP servers, hooks, etc.
+
+        if greeting:
+            opening = "Hi. I'm Cognos. What's on your mind?"
+            print(f"\nCognos: {opening}")
+            self._speak_safely(opening)
+
+        while True:
+            print("\n[listening]", end="", flush=True)
+            try:
+                text = self.listener.listen()
+            except KeyboardInterrupt:
+                print("\n[interrupted while listening — exiting]")
+                break
+
+            if text is None:
+                print(" (no speech)")
+                continue
+
+            print(f"\rYou: {text}                    ")
+
+            normalized = text.lower().strip().rstrip(".!?")
+            if normalized in _EXIT_PHRASES:
+                farewell = "Talk soon."
+                print(f"Cognos: {farewell}")
+                self._speak_safely(farewell)
+                break
+
+            print("[thinking]", end="", flush=True)
+            try:
+                reply = await self.agent.chat(text)
+            except Exception as e:
+                logger.exception("agent.chat failed in voice loop")
+                reply = f"Something went wrong on my end. {e}"
+
+            print(f"\rCognos: {reply}                    ")
+            self._speak_safely(reply)
+
+    def _speak_safely(self, text: str) -> None:
+        """Speak with Ctrl+C aborting playback so the user can interrupt."""
+        try:
+            self.speaker.speak(text)
+        except KeyboardInterrupt:
+            sd.stop()
+            print("\n[interrupted]")

voice/listener.py

@@ -0,0 +1,111 @@
+"""Voice listener — VAD-gated mic capture + pluggable STT.
+
+Captures audio from the microphone using `webrtcvad` for voice activity
+detection, then hands the recorded WAV bytes off to a pluggable STT
+backend (`voice.stt.STT`). The listener has no opinion on which engine
+runs the transcription — caller picks.
+"""
+
+from __future__ import annotations
+
+import io
+import logging
+import struct
+import wave
+from collections import deque
+
+import numpy as np
+import sounddevice as sd
+import webrtcvad
+
+from voice.stt import STT, make_stt
+
+logger = logging.getLogger(__name__)
+
+# Audio config — webrtcvad mandates 16k mono with 10/20/30ms frames.
+SAMPLE_RATE = 16000
+FRAME_DURATION_MS = 30
+FRAME_SIZE = int(SAMPLE_RATE * FRAME_DURATION_MS / 1000)
+CHANNELS = 1
+
+
+class Listener:
+    """VAD-gated microphone capture with delegated transcription."""
+
+    def __init__(
+        self,
+        stt: STT | str = "moonshine",
+        vad_aggressiveness: int = 2,
+        **stt_kwargs,
+    ):
+        self.vad = webrtcvad.Vad(vad_aggressiveness)
+        self._stt: STT = stt if not isinstance(stt, str) else make_stt(stt, **stt_kwargs)
+
+    def listen(
+        self,
+        silence_timeout: float = 1.5,
+        max_duration: float = 30.0,
+    ) -> str | None:
+        """Block until speech, record until silence, return transcription.
+
+        Args:
+            silence_timeout: Seconds of silence after speech to stop.
+            max_duration: Hard cap on recording length.
+
+        Returns:
+            Transcribed text, or None if nothing was said.
+        """
+        frames_per_timeout = int(silence_timeout * 1000 / FRAME_DURATION_MS)
+        max_frames = int(max_duration * 1000 / FRAME_DURATION_MS)
+
+        audio_frames: list[bytes] = []
+        ring_buffer: deque = deque(maxlen=frames_per_timeout)
+        triggered = False
+        silent_frames = 0
+
+        def _frame_to_bytes(frame: np.ndarray) -> bytes:
+            pcm = (frame * 32767).astype(np.int16)
+            return struct.pack(f"{len(pcm)}h", *pcm)
+
+        with sd.InputStream(
+            samplerate=SAMPLE_RATE,
+            channels=CHANNELS,
+            dtype="float32",
+            blocksize=FRAME_SIZE,
+        ) as stream:
+            for _ in range(max_frames):
+                data, _ = stream.read(FRAME_SIZE)
+                frame = data[:, 0]
+                raw = _frame_to_bytes(frame)
+                is_speech = self.vad.is_speech(raw, SAMPLE_RATE)
+
+                if not triggered:
+                    ring_buffer.append((raw, is_speech))
+                    voiced = sum(1 for _, s in ring_buffer if s)
+                    if voiced > 0.8 * (ring_buffer.maxlen or 1):
+                        triggered = True
+                        audio_frames.extend(f for f, _ in ring_buffer)
+                        ring_buffer.clear()
+                else:
+                    audio_frames.append(raw)
+                    if not is_speech:
+                        silent_frames += 1
+                        if silent_frames >= frames_per_timeout:
+                            break
+                    else:
+                        silent_frames = 0
+
+        if not audio_frames:
+            return None
+
+        wav_buffer = io.BytesIO()
+        with wave.open(wav_buffer, "wb") as wf:
+            wf.setnchannels(CHANNELS)
+            wf.setsampwidth(2)
+            wf.setframerate(SAMPLE_RATE)
+            wf.writeframes(b"".join(audio_frames))
+
+        text = self._stt.transcribe(wav_buffer.getvalue())
+        if text:
+            logger.info(f"Transcribed: {text}")
+        return text or None

voice/speaker.py

@@ -0,0 +1,59 @@
+"""Speaker — plays synthesized audio through the system output.
+
+Thin wrapper around a TTS backend (`voice.tts.TTS`). The backend turns
+text into PCM samples; this class plays them via `sounddevice`.
+
+Defaults to Kokoro for natural human-sounding speech. Pass `tts="piper"`
+for the lightweight legacy backend, or `tts=<your TTS instance>` to plug
+something custom.
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import Any
+
+import sounddevice as sd
+
+from voice.tts import TTS, make_tts
+
+logger = logging.getLogger(__name__)
+
+
+class Speaker:
+    """Speaks text aloud using a pluggable TTS backend."""
+
+    def __init__(
+        self,
+        tts: TTS | str = "kokoro",
+        voice_path: str | Path | None = None,
+        voice: str | None = None,
+        **tts_kwargs: Any,
+    ):
+        # Backwards-compat: if voice_path is set we assume Piper since
+        # Piper is the only backend that takes a file path.
+        if isinstance(tts, str):
+            backend = tts
+            kwargs: dict[str, Any] = dict(tts_kwargs)
+            if backend == "piper" and voice_path is not None:
+                kwargs["voice_path"] = voice_path
+            elif backend == "kokoro" and voice:
+                kwargs["voice"] = voice
+            self._tts = make_tts(backend, **kwargs)
+        else:
+            self._tts = tts
+
+    def speak(self, text: str) -> None:
+        """Synthesize and play text. No-op for empty text."""
+        if not text:
+            return
+        try:
+            audio, sample_rate = self._tts.synthesize(text)
+        except Exception as e:
+            logger.warning(f"TTS synthesis failed: {e}")
+            return
+        if audio.size == 0:
+            return
+        sd.play(audio, samplerate=sample_rate)
+        sd.wait()

voice/stt.py

@@ -0,0 +1,126 @@
+"""Speech-to-text backends.
+
+Pluggable transcription. Two backends ship out of the box:
+
+  - **MoonshineSTT** (default) — Useful Sensors' Moonshine via ONNX
+    Runtime. Designed explicitly as a Whisper alternative for edge
+    devices: ~27M params, very low first-word latency, no GPU
+    required. `pip install useful-moonshine-onnx`.
+
+  - **WhisperSTT** (fallback / kept for compat) — faster-whisper.
+    Heavier, more accurate, supports many languages. `pip install
+    faster-whisper`.
+
+Both expose the same interface: `.transcribe(wav_bytes) -> str`. The
+listener is unaware of which is in use.
+
+Pick a backend with `make_stt(name)`. Unknown names raise so a typo
+fails loudly instead of silently picking the wrong engine.
+"""
+
+from __future__ import annotations
+
+import io
+import logging
+import wave
+from typing import Protocol
+
+logger = logging.getLogger(__name__)
+
+
+class STT(Protocol):
+    """Speech-to-text protocol. Implementations are stateful and lazy."""
+
+    def transcribe(self, wav_bytes: bytes) -> str:
+        ...
+
+
+class MoonshineSTT:
+    """Moonshine via ONNX. Loads on first transcribe() call."""
+
+    def __init__(self, model: str = "moonshine/base"):
+        self._model_name = model
+        self._model = None
+
+    def _ensure_loaded(self) -> None:
+        if self._model is not None:
+            return
+        try:
+            import moonshine_onnx as moonshine
+        except ImportError:
+            try:
+                import moonshine_onnx as moonshine  # alt package name
+            except ImportError as e:
+                raise RuntimeError(
+                    "Moonshine STT requested but `useful-moonshine-onnx` "
+                    "is not installed. Run: pip install useful-moonshine-onnx"
+                ) from e
+        logger.info(f"Loading Moonshine '{self._model_name}'...")
+        self._model = moonshine
+        logger.info("Moonshine loaded.")
+
+    def transcribe(self, wav_bytes: bytes) -> str:
+        self._ensure_loaded()
+        # Moonshine's API takes a numpy float32 array at 16k.
+        import numpy as np
+        with wave.open(io.BytesIO(wav_bytes), "rb") as wf:
+            rate = wf.getframerate()
+            n = wf.getnframes()
+            raw = wf.readframes(n)
+        audio = np.frombuffer(raw, dtype=np.int16).astype("float32") / 32768.0
+        if rate != 16000:
+            # Cheap linear resample; Moonshine expects 16k.
+            ratio = 16000 / rate
+            new_len = int(len(audio) * ratio)
+            audio = np.interp(
+                np.linspace(0, len(audio), new_len, endpoint=False),
+                np.arange(len(audio)),
+                audio,
+            ).astype("float32")
+        result = self._model.transcribe(audio, self._model_name)
+        # API returns either a list[str] (per-segment) or a single str.
+        if isinstance(result, (list, tuple)):
+            return " ".join(s for s in result if s).strip()
+        return str(result).strip()
+
+
+class WhisperSTT:
+    """faster-whisper. Heavier but more accurate, kept as fallback."""
+
+    def __init__(self, model: str = "base", device: str = "cuda"):
+        self._model_name = model
+        self._device = device
+        self._model = None
+
+    def _ensure_loaded(self) -> None:
+        if self._model is not None:
+            return
+        try:
+            from faster_whisper import WhisperModel
+        except ImportError as e:
+            raise RuntimeError(
+                "Whisper STT requested but `faster-whisper` is not "
+                "installed. Run: pip install faster-whisper"
+            ) from e
+        logger.info(f"Loading Whisper '{self._model_name}' on {self._device}...")
+        self._model = WhisperModel(
+            self._model_name,
+            device=self._device,
+            compute_type="float16" if self._device == "cuda" else "int8",
+        )
+        logger.info("Whisper loaded.")
+
+    def transcribe(self, wav_bytes: bytes) -> str:
+        self._ensure_loaded()
+        segments, _ = self._model.transcribe(io.BytesIO(wav_bytes), language="en")
+        return " ".join(seg.text for seg in segments).strip()
+
+
+def make_stt(name: str = "moonshine", **kwargs) -> STT:
+    """Factory for STT backends. Names: 'moonshine', 'whisper'."""
+    n = name.lower()
+    if n == "moonshine":
+        return MoonshineSTT(**kwargs)
+    if n == "whisper":
+        return WhisperSTT(**kwargs)
+    raise ValueError(f"Unknown STT backend: {name!r} (try 'moonshine' or 'whisper')")