# Overview

## Purpose

GenieClaw is the local agent layer for GeniePod Home and the broader Genie
ecosystem.

The repo is optimized around a narrow goal:

- run locally on Jetson-class hardware
- keep the system understandable and debuggable
- provide everyday household usefulness before broad platform ambition
- preserve privacy, bounded behavior, and graceful degradation

This is not a cloud orchestration shell and not a generic agent runtime.

## Ecosystem Role

The long-term Genie stack is split by responsibility:

- custom Jetson hardware
- `genie-os` for custom L4T, drivers, OTA, diagnostics, and service supervision
- `genie-home-runtime` for device graph, automations, MCP, and final actuation safety
- `genie-ai-runtime` for Jetson-only LLM inference optimization
- `genie-claw` for voice, memory, tools, skills, and agent interaction
- web/mobile apps for setup, control, memory management, and confirmations

This repository is `genie-claw`. Some current integrations still live here as
transitional adapters, especially `llama.cpp` and Home Assistant, but the code
should keep those behind narrow boundaries.

For the exact implemented/partial/planned breakdown, use
[implementation-status.md](implementation-status.md). In short, this repo
implements the agent runtime, memory, tools, voice pipeline boundaries, local
HTTP/CLI surfaces, safety gates, and deploy assets. It does not implement the
final `genie-home-runtime`, `genie-ai-runtime`, `genie-os`, or full
Matter/Thread device stack.

## Main Runtime Modes

`genie-core` supports three primary modes:

1. HTTP server mode
   The default daemon mode. It serves the local chat UI, local API consumers,
   OpenAI-compatible adapters, and direct tool surfaces.
2. REPL mode
   When stdin is interactive, `genie-core` starts a local text REPL instead of
   daemon-only behavior.
3. Voice mode
   Enabled by config, `--voice`, or `GENIEPOD_VOICE=1`. The voice loop runs a
   microphone -> STT -> prompt/tool execution -> TTS pipeline.

In daemon mode, Telegram can also be enabled as a side-channel adapter.

## High-Level Process Topology

Typical Jetson deployment:

```text
llama-server (:8080)
        ^
        |
genie-core (:3000) <---- genie-ctl
        |
        +---- local chat UI / OpenAI-compatible clients
        +---- optional Telegram adapter
        +---- optional Home Assistant provider
        +---- optional ESP32-C6 connectivity controller boundary

genie-governor ---- controls service modes and pressure response
genie-health   ---- polls health endpoints and stores health history
genie-api      ---- serves dashboard/status data
```

Target topology:

```text
genie-ai-runtime
        ^
        |
genie-claw
        |
        +---- web/mobile apps and local channels
        +---- voice, memory, tools, skills
        v
genie-home-runtime
        |
        v
GenieOS + custom Jetson hardware
```

## Core User Flows

### Chat HTTP Flow

1. Client sends `POST /api/chat` or `POST /v1/chat/completions`.
2. `genie-core` appends the user message to the conversation store.
3. Fast-path routing may intercept deterministic requests.
   Examples: time, memory diagnostics, system status, explicit web search.
4. If not intercepted, GenieClaw builds the system prompt and injects relevant memory.
5. The LLM returns plain text or tool JSON.
6. If tool JSON is detected, the tool dispatcher executes it.
7. The result is either returned raw or summarized, depending on tool type.
8. Memory auto-capture runs on the user message.

### Voice Flow

1. Record audio from ALSA or auto-detected device.
2. Apply DSP, gating, and optional cleanup.
3. Send audio to Whisper CLI/server.
4. Detect language if configured as `auto`.
5. Run the same routing/prompt/tool pipeline as text.
6. Use Piper for spoken output, optionally with language-specific voices.

Current multilingual support is a pipeline capability, not a certified
full-language product guarantee. Quality depends on the installed Whisper and
Piper models for each language and on device-level audio testing.

### Governor Flow

1. Poll tegrastats and memory state.
2. Track day/night/media modes.
3. Stop or defer optional services under pressure.
4. Expose status and mode change control through the Unix control socket.

## Data At Rest

The runtime primarily stores data under `data_dir`.

Main current databases:

- `memory.db`: persistent memory and FTS-backed recall
- `conversations.db`: conversation history and exports
- `governor.db`: tegrastats history and governor state data
- `health.db`: service health history

The default production `data_dir` is `/opt/geniepod/data`.
The default development `data_dir` is `./data`.

## Why The Repo Is Split Into Small Crates

The crate split is pragmatic, not academic.

- `genie-common` keeps config and shared types reusable across binaries.
- `genie-core` currently contains the agent runtime and transitional runtime adapters.
- `genie-governor`, `genie-health`, and `genie-api` stay small and operationally separate.
- `genie-ctl` gives you a narrow operator interface without needing a browser.
- `genie-skill-sdk` keeps the native skill ABI explicit.

The result is easier bring-up on Jetson and clearer failure boundaries.
