## At a Glance

8 Python Packages
643+ Passing Tests
73%+ Code Coverage
58 API Endpoints

## Tech Stack

FastAPI + HTMX Server-rendered UI with real-time updates
Agno Framework Multi-agent orchestration with tool calling
Ollama Local LLM inference, no cloud dependencies
SQLite + WAL Agent memory, swarm registry, task queue
WebSockets Live event feeds and push notifications
Docker Multi-stage builds, dev and prod configs

## Architecture

    Browser / Phone
          | HTTP + HTMX + WebSocket
          v
    +-----------------------------------------+
    |          FastAPI (dashboard.app)         |
    |  routes: agents, health, swarm,         |
    |          marketplace, voice, mobile     |
    +---+-------------+----------+-----------+
        |             |          |
        v             v          v
     Jinja2       Timmy       Infrastructure
     Templates    Agent       +- LLM Router (cascade)
     (HTMX)      |           +- WebSocket manager
                 +- Ollama   +- Notifications
                 +- AirLLM   +- Events bus
        |
        +-- Integrations (voice NLU, Telegram, Siri)
        +-- WebSocket live feed
        +-- Push notifications
        +-- Spark (events, predictions, advisory)

    Persistence: SQLite (Agno memory + swarm registry)
    External:    Ollama :11434, optional Redis, optional LND

## Modules

Package | Purpose
--- | ---
timmy/ | Core agent, personas, interface, semantic memory
dashboard/ | FastAPI web UI, routes, Jinja2 templates
infrastructure/ | WebSocket, notifications, events, LLM router
integrations/ | Discord, Telegram, Siri Shortcuts, voice NLU
spark/ | Event capture, predictions, advisory engine
brain/ | Identity system, memory interface
timmy_serve/ | API server, L402 Lightning gating
config.py | Pydantic settings — single source for all env vars

## Quality

CI/CD GitHub Actions: lint, test, Docker build
Testing tox-managed: unit, integration, functional, e2e
Linting black + isort + bandit security scanning
Security CSRF, XSS prevention, no hardcoded secrets