TIMMY TIME

A local-first, sovereign AI agent system

Python 3.11+ FastAPI HTMX Ollama SQLite MIT License

GitHub Repository README Developer Guide

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