Module Responsibilities

DATA_DIR: Path  # ~/.klaus/
CONFIG_PATH: Path  # ~/.klaus/config.toml
DB_PATH: Path  # ~/.klaus/klaus.db

@dataclass
class RuntimeSettings:
    anthropic_api_key: str
    openai_api_key: str
    tavily_api_key: str
    camera_device_index: int
    mic_device_index: int
    tts_voice: str
    tts_speed: float
    # ... more fields

def get_runtime_settings() -> RuntimeSettings
def reload() -> None  # Re-read config.toml
def save_setting(key: str, value: Any) -> None

class KlausApp(QObject):
    def __init__(self, app: QApplication)
    def _init_components(self) -> None  # Deferred until after wizard
    def _on_question_received(self, audio_bytes: bytes) -> None
    def _switch_camera_device(self, new_index: int) -> None
    def _switch_mic_device(self, new_index: int) -> None
    @_safe_slot  # Decorator catches exceptions to prevent Qt abort()

if not settings.setup_complete:
    wizard = SetupWizard()
    if wizard.exec() != QDialog.DialogCode.Accepted:
        sys.exit(0)
    config.reload()

def _safe_slot(func: Callable) -> Callable:
    def wrapper(*args, **kwargs):
        try:
            return func(*args, **kwargs)
        except Exception:
            logger.exception("Uncaught exception in slot %s", func.__name__)
    return wrapper

class Brain:
    def decide_route(self, question: str) -> RouteDecision
    def ask(
        self,
        question: str,
        image_base64: str | None,
        memory_context: str | None,
        notes_context: str | None,
        on_sentence: Callable[[str], None] | None,
        route_decision: RouteDecision | None,
    ) -> Exchange
    def clear_history(self) -> None
    def trim_history(self, max_turns: int = 20) -> None

with self._client.messages.stream(
    model=CLAUDE_MODEL,
    system=system,
    messages=messages,
    tools=self._tools,
) as stream:
    for event in stream:
        if event.type == "content_block_delta":
            text_buf += event.delta.text
            sentences, text_buf = _extract_sentences(text_buf)
            for sentence in sentences:
                on_sentence(sentence)

class RouteMode(str, Enum):
    STANDALONE_DEFINITION = "standalone_definition"
    PAGE_GROUNDED_DEFINITION = "page_grounded_definition"
    GENERAL_CONTEXTUAL = "general_contextual"

_POLICY = {
    "standalone": {
        "use_image": False,
        "use_history": False,
        "use_memory_context": False,
        "use_notes_context": False,
        "max_sentences": 2,
        "history_turn_window": 0,
    },
    "page_definition": {
        "use_image": True,
        "use_history": True,
        "max_sentences": 2,
        "history_turn_window": 2,
    },
    "contextual": {
        "use_image": True,
        "use_history": True,
        "use_memory_context": True,
        "use_notes_context": True,
        "max_sentences": None,
        "history_turn_window": 0,
    },
}

class PushToTalkRecorder:
    def start_recording(self) -> None
    def stop_recording(self) -> bytes | None  # WAV bytes

class VoiceActivatedRecorder:
    def __init__(
        self,
        on_speech_start: Callable[[], None],
        on_speech_end: Callable[[bytes], None],
        on_speech_discard: Callable[[str], None] | None,
        sensitivity: int = 2,  # 0-3
        silence_timeout: float = 1.5,
    )
    def start(self) -> None
    def stop(self) -> None
    def pause(self) -> None
    def resume(self) -> None
    def suspend_stream(self) -> None  # Free CoreAudio device
    def resume_stream(self) -> None

class AudioPlayer:
    def play_wav_bytes(self, wav_data: bytes) -> None
    def stop(self) -> None

class Camera:
    def start(self) -> None
    def stop(self) -> None
    def get_frame(self) -> np.ndarray | None  # BGR
    def get_frame_rgb(self) -> np.ndarray | None
    def capture_base64_jpeg(self, quality: int = 85) -> str | None
    def capture_thumbnail_bytes(self, max_width: int = 320) -> bytes | None

def _capture_loop(self) -> None:
    while self._running:
        ret, frame = self._cap.read()
        if ret:
            if self._rotation is not None:
                frame = cv2.rotate(frame, self._rotation)
            with self._lock:
                self._frame = frame

class TextToSpeech:
    def speak(self, text: str, on_sentence_start: Callable = None) -> None
    def speak_streaming(self, sentence_queue: queue.Queue[str | None]) -> None
    def stop(self) -> None
    def reload_client(self, settings: RuntimeSettings | None = None) -> None

def _split_into_chunks(text: str) -> list[str]:
    sentences = SENTENCE_SPLIT.split(text.strip())
    chunks = []
    current = ""
    for sentence in sentences:
        if len(current) + len(sentence) + 1 > MAX_CHUNK_CHARS:
            chunks.append(current)
            current = sentence
        else:
            current = f"{current} {sentence}".strip()
    return chunks

class MoonshineSTT:
    def __init__(self, model_size: str = "medium", language: str = "en")
    def transcribe(self, audio_bytes: bytes) -> str

CREATE TABLE sessions (
    id INTEGER PRIMARY KEY,
    title TEXT,
    created_at TEXT
);

CREATE TABLE exchanges (
    id INTEGER PRIMARY KEY,
    session_id INTEGER,
    user_text TEXT,
    assistant_text TEXT,
    image_base64 TEXT,
    created_at TEXT
);

CREATE TABLE knowledge_profile (
    id INTEGER PRIMARY KEY,
    summary TEXT,
    updated_at TEXT
);

class Memory:
    def create_session(self, title: str) -> int
    def save_exchange(self, session_id: int, user_text: str, assistant_text: str,
                      image_base64: str | None = None) -> None
    def load_session(self, session_id: int) -> list[Exchange]
    def list_sessions(self) -> list[dict]

class NotesManager:
    def __init__(self, vault_path: str | None)
    def set_file(self, file_path: str) -> str  # Returns confirmation message
    def save_note(self, content: str) -> str
    @property
    def changed(self) -> bool  # Did we write notes this turn?

SET_NOTES_FILE_TOOL = {
    "name": "set_notes_file",
    "description": "Set the active markdown file in the Obsidian vault",
    "input_schema": {"type": "object", "properties": {"file_path": {"type": "string"}}},
}

SAVE_NOTE_TOOL = {
    "name": "save_note",
    "description": "Append content to the active note file",
    "input_schema": {"type": "object", "properties": {"content": {"type": "string"}}},
}

TOOL_DEFINITION = {
    "name": "web_search",
    "description": "Search the web for current information",
    "input_schema": {"type": "object", "properties": {"query": {"type": "string"}}},
}

class WebSearch:
    def search(self, query: str) -> str  # Returns formatted search results

@dataclass
class CameraDevice:
    index: int
    display_name: str
    width: int
    height: int

@dataclass
class MicDevice:
    index: int
    display_name: str
    is_default: bool

def list_camera_devices(max_index: int = 10) -> list[CameraDevice]
def list_input_devices() -> list[MicDevice]

def application_stylesheet() -> str
def apply_dark_titlebar(hwnd: int) -> None  # Windows only
def load_fonts() -> None  # Register Inter font family

COLORS = {
    "bg_primary": "#1a1a1a",
    "bg_secondary": "#242424",
    "text_primary": "#e0e0e0",
    "accent": "#4a9eff",
    # ...
}