2026-02-27 20:10:59 -05:00
|
|
|
# Timmy Time — System Architecture
|
|
|
|
|
|
|
|
|
|
## Changelog
|
|
|
|
|
|
|
|
|
|
| Date | Change |
|
|
|
|
|
|------|--------|
|
|
|
|
|
| 2026-02-27 | Full restructure — autonomous agent vision, daily briefing, escalation system, embodiment research, self-improvement loop |
|
|
|
|
|
| 2026-02-26 | Initial architecture-v2 covering 6 features (Event Log, Ledger, Memory, Upgrade Queue, Cascade Router, Activity Feed) |
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
## Vision & Philosophy
|
|
|
|
|
|
|
|
|
|
Timmy is a **sovereign, always-on, local-first AI agent** — not a reactive chatbot.
|
|
|
|
|
He thinks continuously, manages his own task list, modifies his own code, and
|
|
|
|
|
operates 24/7 with full visibility into his activity. The owner's role shifts from
|
|
|
|
|
directing every action to reviewing briefings, approving escalations, and steering
|
|
|
|
|
at the strategic level.
|
|
|
|
|
|
|
|
|
|
**Core Tenets:**
|
|
|
|
|
|
|
|
|
|
1. **Sovereignty** — All inference runs locally. Data never leaves the machine. No
|
|
|
|
|
vendor lock-in. Swappable LLM backends, swappable infrastructure.
|
|
|
|
|
2. **Autonomy** — Timmy thinks unprompted, proposes actions, reprioritizes tasks,
|
|
|
|
|
and self-improves. He chooses his next thought based on what feels generative.
|
|
|
|
|
3. **Transparency** — Every thought, decision, escalation, and self-modification is
|
|
|
|
|
observable in the dashboard. Nothing happens in the dark.
|
|
|
|
|
|
|
|
|
|
**Status Legend:** Throughout this document, each feature is tagged with its
|
|
|
|
|
implementation status:
|
|
|
|
|
|
|
|
|
|
| Tag | Meaning |
|
|
|
|
|
|-----|---------|
|
|
|
|
|
| `[LIVE]` | Fully implemented and running |
|
|
|
|
|
| `[PARTIAL]` | Core infrastructure exists, extensions needed |
|
|
|
|
|
| `[PLANNED]` | Designed but no code yet |
|
|
|
|
|
| `[RESEARCH]` | Open question, on roadmap for investigation |
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
## System Architecture
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
┌──────────────────────────────────────────────────────────────────────────────────┐
|
|
|
|
|
│ DASHBOARD UI │
|
|
|
|
|
│ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌──────────┐ ┌────────────────┐ │
|
|
|
|
|
│ │ Thought │ │ Task │ │ Briefing │ │ Event │ │ Upgrade Queue │ │
|
|
|
|
|
│ │ Stream │ │ Queue │ │ View │ │ Log │ │ & Bug Reports │ │
|
|
|
|
|
│ │ /thinking │ │ /tasks │ │ /briefing │ │/swarm/ev.│ │ /self-modify │ │
|
|
|
|
|
│ └─────┬──────┘ └─────┬──────┘ └─────┬──────┘ └────┬─────┘ └───────┬────────┘ │
|
|
|
|
|
│ └───────────────┴──────────────┴─────────────┴───────────────┘ │
|
|
|
|
|
│ │ WebSocket + HTMX │
|
|
|
|
|
└────────────────────────────────────┼─────────────────────────────────────────────┘
|
|
|
|
|
│
|
|
|
|
|
┌────────────────────────────────────┼─────────────────────────────────────────────┐
|
|
|
|
|
│ API LAYER (FastAPI) │
|
2026-03-07 07:28:14 -05:00
|
|
|
│ Route modules registered in src/dashboard/app.py │
|
2026-02-27 20:10:59 -05:00
|
|
|
└────────────────────────────────────┼─────────────────────────────────────────────┘
|
|
|
|
|
│
|
|
|
|
|
┌────────────────────────────────────┼─────────────────────────────────────────────┐
|
|
|
|
|
│ CORE SERVICES │
|
|
|
|
|
│ │ │
|
|
|
|
|
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────────┐ │
|
|
|
|
|
│ │ Thinking │ │ Task │ │ Briefing │ │ Self-Modify │ │
|
|
|
|
|
│ │ Engine │ │ Queue │ │ Engine │ │ Loop │ │
|
|
|
|
|
│ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ └────────┬─────────┘ │
|
|
|
|
|
│ │ │ │ │ │
|
|
|
|
|
│ ┌──────┴───────┐ ┌──────┴───────┐ ┌──────┴───────┐ ┌────────┴─────────┐ │
|
|
|
|
|
│ │ Event Log │ │ Approvals │ │ Notifier │ │ Error Capture │ │
|
|
|
|
|
│ │ Service │ │ Governance │ │ (Push) │ │ & Bug Reports │ │
|
|
|
|
|
│ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ └────────┬─────────┘ │
|
|
|
|
|
│ └─────────────────┴─────────────────┴──────────────────┘ │
|
|
|
|
|
│ │ │
|
|
|
|
|
│ ┌─────────────────────────────────┴──────────────────────────────────────────┐ │
|
|
|
|
|
│ │ CASCADE ROUTER │ │
|
|
|
|
|
│ │ Ollama (local) → AirLLM (local) → API (optional) → Metrics │ │
|
|
|
|
|
│ └────────────────────────────────────────────────────────────────────────────┘ │
|
|
|
|
|
│ │ │
|
|
|
|
|
│ ┌─────┴──────┐ │
|
|
|
|
|
│ │ Timmy │ │
|
|
|
|
|
│ │ Agent │ │
|
|
|
|
|
│ └────────────┘ │
|
|
|
|
|
│ │
|
|
|
|
|
│ ┌──────────────────────────────────────────────────────────────────────────┐ │
|
|
|
|
|
│ │ INTEGRATIONS: Telegram · Discord · Siri · Voice NLU · Mobile · Hands │ │
|
|
|
|
|
│ └──────────────────────────────────────────────────────────────────────────┘ │
|
|
|
|
|
└──────────────────────────────────────────────────────────────────────────────────┘
|
|
|
|
|
|
|
|
|
|
PERSISTENCE:
|
|
|
|
|
timmy.db — Agno agent memory
|
|
|
|
|
data/swarm.db — tasks, agents, event_log, ledger, memory_entries, upgrades,
|
|
|
|
|
provider_metrics, task_queue
|
|
|
|
|
data/thoughts.db — thought stream
|
|
|
|
|
~/.timmy/briefings.db — briefing cache
|
|
|
|
|
~/.timmy/approvals.db — governance items
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### Component Index
|
|
|
|
|
|
|
|
|
|
| Component | Module | Import |
|
|
|
|
|
|-----------|--------|--------|
|
|
|
|
|
| Timmy Agent | `src/timmy/agent.py` | `from timmy.agent import timmy` |
|
|
|
|
|
| Thinking Engine | `src/timmy/thinking.py` | `from timmy.thinking import thinking_engine` |
|
|
|
|
|
| Briefing Engine | `src/timmy/briefing.py` | `from timmy.briefing import engine` |
|
|
|
|
|
| Session Logger | `src/timmy/session_logger.py` | `from timmy.session_logger import get_session_logger` |
|
|
|
|
|
| Approvals | `src/timmy/approvals.py` | `from timmy.approvals import GOLDEN_TIMMY` |
|
2026-03-07 07:28:14 -05:00
|
|
|
| Task Queue | *(not yet implemented)* | — |
|
|
|
|
|
| Coordinator | *(not yet implemented)* | — |
|
2026-02-27 20:10:59 -05:00
|
|
|
| Cascade Router | `src/infrastructure/router/cascade.py` | `from infrastructure.router.cascade import get_router` |
|
|
|
|
|
| Event Bus | `src/infrastructure/events/bus.py` | `from infrastructure.events.bus import event_bus` |
|
|
|
|
|
| WebSocket Mgr | `src/infrastructure/ws_manager/handler.py` | `from infrastructure.ws_manager.handler import ws_manager` |
|
|
|
|
|
| Push Notifier | `src/infrastructure/notifications/push.py` | `from infrastructure.notifications.push import notifier` |
|
|
|
|
|
| Error Capture | `src/infrastructure/error_capture.py` | `from infrastructure.error_capture import capture_error` |
|
2026-03-07 07:28:14 -05:00
|
|
|
| Self-Modify | *(not yet implemented)* | — |
|
2026-02-27 20:10:59 -05:00
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
## Core Agent
|
|
|
|
|
|
|
|
|
|
### Always-On Autonomous Agent `[LIVE]`
|
|
|
|
|
|
|
|
|
|
Timmy operates as a persistent, always-on agent. He continuously maintains an
|
|
|
|
|
active thought queue, manages his own task list dynamically — adding,
|
|
|
|
|
reprioritizing, shelving, and resuming tasks — and chooses his own next thought
|
|
|
|
|
based on what feels generative. He runs 24/7 with visibility into his activity at
|
|
|
|
|
all times.
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
Server Startup → ThinkingEngine.start_loop()
|
|
|
|
|
↓
|
|
|
|
|
Seed Selection (existential | swarm | scripture | creative | memory | freeform)
|
|
|
|
|
↓
|
|
|
|
|
Continuity Context (3 most recent thoughts)
|
|
|
|
|
↓
|
|
|
|
|
LLM Inference (Ollama) → Thought
|
|
|
|
|
↓
|
|
|
|
|
SQLite thoughts.db + Event Log + WebSocket Broadcast
|
|
|
|
|
↓
|
|
|
|
|
Next Seed → Loop
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
| Aspect | File | Notes |
|
|
|
|
|
|--------|------|-------|
|
|
|
|
|
| ThinkingEngine | `src/timmy/thinking.py` | Seed types, continuity context, WS broadcast |
|
2026-03-07 07:28:14 -05:00
|
|
|
| Task Queue | *(task queue — not yet implemented)* | SQLite-backed, 8 statuses, 4 priority levels |
|
|
|
|
|
| Auto-approve rules | *(task queue — not yet implemented)* | Tasks matching rules execute without human gate |
|
|
|
|
|
| Startup drain | *(task queue — not yet implemented)* | `get_all_actionable_tasks()` processes queue on boot |
|
2026-02-27 20:10:59 -05:00
|
|
|
| Config | `src/config.py` | `thinking_enabled`, `thinking_interval_seconds` (300s default) |
|
|
|
|
|
|
|
|
|
|
The task queue supports 8 statuses (`PENDING_APPROVAL`, `APPROVED`, `RUNNING`,
|
|
|
|
|
`PAUSED`, `COMPLETED`, `VETOED`, `FAILED`, `BACKLOGGED`) and 4 priority levels
|
|
|
|
|
(`LOW`, `NORMAL`, `HIGH`, `URGENT`). Tasks can be backlogged with a reason and
|
|
|
|
|
resumed later.
|
|
|
|
|
|
|
|
|
|
### Meditative Thought Mode — Pondering the Orb `[PARTIAL]`
|
|
|
|
|
|
|
|
|
|
A special cognitive mode where Timmy clears his memory context, thinks freely
|
|
|
|
|
without extraneous memory affecting the process, and dwells on a topic for an
|
|
|
|
|
extended period. When the process completes, it produces an insight artifact.
|
|
|
|
|
Unfinished thoughts can be shelved back onto the task queue as "cliffhangers" to
|
|
|
|
|
revisit later. This is analogous to putting a thought on the back burner and
|
|
|
|
|
letting it cook.
|
|
|
|
|
|
|
|
|
|
**What exists today:** The ThinkingEngine supports 6 seed types (existential,
|
|
|
|
|
swarm, scripture, creative, memory, freeform) and maintains continuity context
|
|
|
|
|
between thoughts via `parent_id` chaining. The `freeform` and `existential` seed
|
|
|
|
|
types provide the foundation for meditative thought.
|
|
|
|
|
|
|
|
|
|
**Gaps to implement:**
|
|
|
|
|
|
|
|
|
|
- Context-clear mode — explicit memory wipe for a meditation session
|
|
|
|
|
- Extended dwell time — configurable longer thinking intervals per session
|
|
|
|
|
- Insight artifact format — structured output beyond raw thought text
|
|
|
|
|
- Cliffhanger shelving — mechanism to save an unfinished thought and park it on the
|
|
|
|
|
task queue for later retrieval
|
|
|
|
|
|
|
|
|
|
### Self-Improving Loop `[LIVE]`
|
|
|
|
|
|
|
|
|
|
Timmy can recognize what needs improving in his own systems, modify his own prompt
|
|
|
|
|
chains, task management logic, and tool usage, and maintain source control and
|
|
|
|
|
redundancy. He can spin himself up from a clean state using version-controlled
|
|
|
|
|
config. The goal is compounding capability over time rather than requiring constant
|
|
|
|
|
human engineering.
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
Trigger (work order | self-diagnosis | error feedback)
|
|
|
|
|
↓
|
|
|
|
|
SelfModifyLoop.run()
|
|
|
|
|
↓
|
|
|
|
|
Read Source → LLM Edit → Validate Syntax
|
|
|
|
|
↓
|
|
|
|
|
Write to Disk → Run pytest
|
|
|
|
|
↓ pass ↓ fail
|
|
|
|
|
Git Commit Revert + Diagnose → Retry (up to 3 cycles)
|
|
|
|
|
↓
|
|
|
|
|
Modification Journal (data/self_modify_reports/)
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
| Aspect | File | Notes |
|
|
|
|
|
|--------|------|-------|
|
2026-03-07 07:28:14 -05:00
|
|
|
| Core loop | *(self-coding — not yet implemented)* | Read-edit-test-commit cycle |
|
|
|
|
|
| Git safety | *(self-coding — not yet implemented)* | Atomic operations with rollback |
|
|
|
|
|
| Modification journal | *(self-coding — not yet implemented)* | Persistent report log |
|
|
|
|
|
| Reflection | *(self-coding — not yet implemented)* | Lessons-learned generator |
|
|
|
|
|
| Upgrade queue | *(self-coding — not yet implemented)* | Approval queue for proposed changes |
|
2026-02-27 20:10:59 -05:00
|
|
|
| Error capture | `src/infrastructure/error_capture.py` | Auto-creates bug reports from exceptions |
|
|
|
|
|
| Error dedup | `src/infrastructure/error_capture.py` | Hash-based deduplication (5-min window) |
|
|
|
|
|
|
|
|
|
|
The autonomous self-correction cycle reads its own failure report, calls the LLM
|
|
|
|
|
for meta-analysis, diagnoses the root cause, and restarts with a corrected
|
|
|
|
|
instruction — up to 3 autonomous cycles with 6 retries each.
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
## Intelligence Surface
|
|
|
|
|
|
|
|
|
|
### Daily Morning Briefing `[PARTIAL]`
|
|
|
|
|
|
|
|
|
|
**Target architecture:** Once per day, Timmy delivers a high-density morning
|
|
|
|
|
briefing as a video narration with slides. It covers overnight progress,
|
|
|
|
|
escalations, insights from pondering, and task status updates. The briefing is
|
|
|
|
|
interactive — the owner responds in real-time as Timmy presents (yes/no,
|
|
|
|
|
redirections, feedback). Timmy listens and adjusts based on reactions during the
|
|
|
|
|
briefing. After the briefing, Timmy has 24 hours of autonomous operation before the
|
|
|
|
|
next sync. This is the primary structured touchpoint — it replaces constant
|
|
|
|
|
notification spam.
|
|
|
|
|
|
|
|
|
|
**Phase 1 — Text Briefing (current):**
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
Cron / Dashboard Request → BriefingEngine.generate()
|
|
|
|
|
↓
|
|
|
|
|
_gather_swarm_summary() ← data/swarm.db (completed/failed tasks, new agents)
|
|
|
|
|
_gather_chat_summary() ← message_log (last 10 messages)
|
|
|
|
|
_gather_approvals() ← ~/.timmy/approvals.db (pending items)
|
|
|
|
|
↓
|
|
|
|
|
LLM Summarization (Ollama)
|
|
|
|
|
↓
|
|
|
|
|
Briefing Dataclass → SQLite Cache (~/.timmy/briefings.db, 30-min TTL)
|
|
|
|
|
↓
|
|
|
|
|
Dashboard /briefing + Push Notification (if pending approvals)
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
| Aspect | File | Notes |
|
|
|
|
|
|--------|------|-------|
|
|
|
|
|
| BriefingEngine | `src/timmy/briefing.py` | Core generation, 335 lines |
|
|
|
|
|
| Dashboard route | `src/dashboard/routes/briefing.py` | Serves briefing page |
|
|
|
|
|
| Background schedule | `src/dashboard/app.py` | Regenerates every 6 hours |
|
|
|
|
|
|
|
|
|
|
**Phase 2 roadmap:** Audio narration (local TTS via pyttsx3), slide generation from
|
|
|
|
|
artifacts, interactive approval buttons within briefing view, reaction tracking to
|
|
|
|
|
feed escalation calibration.
|
|
|
|
|
|
|
|
|
|
### Escalation System `[PARTIAL]`
|
|
|
|
|
|
|
|
|
|
Timmy can escalate decisions and questions to the owner when needed, but
|
|
|
|
|
escalations are not delivered as constant notifications — they are batched. Over
|
|
|
|
|
time, Timmy learns the owner's attention economy by tracking which escalations get
|
|
|
|
|
engaged with vs. ignored. If too many low-value escalations are sent, the owner
|
|
|
|
|
disengages — so Timmy must calibrate. The feedback loop trains Timmy's escalation
|
|
|
|
|
threshold, making him increasingly discerning about what warrants human attention.
|
|
|
|
|
|
|
|
|
|
**What exists today:**
|
|
|
|
|
|
|
|
|
|
| Component | File | What It Does |
|
|
|
|
|
|-----------|------|-------------|
|
|
|
|
|
| Push Notifier | `src/infrastructure/notifications/push.py` | In-memory queue (200 max), 6 categories, macOS native support |
|
2026-03-07 07:28:14 -05:00
|
|
|
| Risk Scoring | *(not yet implemented)* | Priority/category weights, sensitive-path detection |
|
2026-02-27 20:10:59 -05:00
|
|
|
| Approval Governance | `src/timmy/approvals.py` | `GOLDEN_TIMMY` flag, pending/approved/rejected states, 7-day expiry |
|
|
|
|
|
| Briefing integration | `src/timmy/briefing.py` | Surfaces pending approvals in briefing |
|
|
|
|
|
|
|
|
|
|
**Gaps to implement:**
|
|
|
|
|
|
|
|
|
|
- Attention economy tracker — log owner engagement: dismissals, time-spent,
|
|
|
|
|
action-taken per escalation
|
|
|
|
|
- Engagement-based threshold calibration — adjust escalation priority cutoff based
|
|
|
|
|
on engagement history
|
|
|
|
|
- Batch grouping logic — collect escalations over a window, present as cohort
|
|
|
|
|
rather than individual pings
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
## Operations Infrastructure
|
|
|
|
|
|
|
|
|
|
### Task & Thought Dashboard `[LIVE]`
|
|
|
|
|
|
|
|
|
|
A real-time dashboard accessible on phone, iPad, and desktop that shows active
|
|
|
|
|
thoughts, the thought queue, a dynamic task list, thought logs, artifacts, and a
|
|
|
|
|
live feed via WebSocket. The owner can interact directly — reorder tasks, inject new
|
|
|
|
|
thoughts, review artifacts, and provide feedback.
|
|
|
|
|
|
2026-03-07 07:28:14 -05:00
|
|
|
The dashboard is built with FastAPI + Jinja2 + HTMX with route modules including:
|
2026-02-27 20:10:59 -05:00
|
|
|
|
|
|
|
|
| Route | Prefix | Purpose |
|
|
|
|
|
|-------|--------|---------|
|
|
|
|
|
| health | `/` | Main dashboard, system health |
|
|
|
|
|
| thinking | `/thinking` | Live thought stream |
|
|
|
|
|
| tasks | — | Task queue management |
|
|
|
|
|
| briefing | `/briefing` | Morning briefing view |
|
|
|
|
|
| events | `/swarm` | Event log / activity feed |
|
|
|
|
|
| agents | `/agents` | Agent registry |
|
|
|
|
|
| swarm | `/swarm` | Swarm coordinator |
|
|
|
|
|
| hands | `/hands` | Autonomous Hand agents |
|
|
|
|
|
| bugs | — | Bug report tracker |
|
|
|
|
|
| self_coding | `/self-coding` | Self-modification status |
|
|
|
|
|
| upgrades | `/self-modify` | Upgrade approval queue |
|
|
|
|
|
| ledger | `/lightning` | Payment ledger |
|
|
|
|
|
| memory | `/memory` | Semantic memory browser |
|
|
|
|
|
| router | `/router` | LLM router status |
|
|
|
|
|
| spark | `/spark` | Intelligence engine |
|
|
|
|
|
| mobile | — | iOS-optimized layout |
|
|
|
|
|
| voice | `/voice` | Voice NLU interface |
|
|
|
|
|
|
|
|
|
|
**Activity Feed data flow:**
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
Event Logged → EventBroadcaster → ws_manager.broadcast()
|
|
|
|
|
↓
|
|
|
|
|
WebSocket Clients
|
|
|
|
|
↓
|
|
|
|
|
Dashboard Activity Panel
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### LLM Router — Cascade `[LIVE]`
|
|
|
|
|
|
|
|
|
|
The system uses an LLM router that cascades through available models. Free-tier
|
|
|
|
|
and local providers are tried first, then falls back through the chain. The router
|
|
|
|
|
handles model unavailability gracefully with circuit-breaker failover.
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
Request → Cascade Router → Ollama (primary, local)
|
|
|
|
|
↓ fail / circuit open
|
|
|
|
|
AirLLM (fallback, local)
|
|
|
|
|
↓ fail
|
|
|
|
|
API Provider (optional, e.g. Grok — opt-in)
|
|
|
|
|
↓
|
|
|
|
|
Metrics Tracking (provider_metrics table)
|
|
|
|
|
↓
|
|
|
|
|
Dashboard /router/status
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
| Aspect | File | Notes |
|
|
|
|
|
|--------|------|-------|
|
|
|
|
|
| CascadeRouter | `src/infrastructure/router/cascade.py` | Provider chain, circuit breaker |
|
|
|
|
|
| Router API | `src/infrastructure/router/api.py` | HTTP interface |
|
|
|
|
|
| Cascade Adapter | `src/timmy/cascade_adapter.py` | Timmy agent integration |
|
|
|
|
|
| Backends | `src/timmy/backends.py` | Ollama, AirLLM, Grok backends |
|
|
|
|
|
| Dashboard | `src/dashboard/routes/router.py` | Status page |
|
|
|
|
|
|
|
|
|
|
### Data Layer `[LIVE]`
|
|
|
|
|
|
|
|
|
|
All persistence uses SQLite — no external database dependencies.
|
|
|
|
|
|
|
|
|
|
| Table | Database | Purpose | Source |
|
|
|
|
|
|-------|----------|---------|--------|
|
|
|
|
|
| `tasks` | `data/swarm.db` | Swarm task management | Existing |
|
|
|
|
|
| `agents` | `data/swarm.db` | Agent registry | Existing |
|
|
|
|
|
| `event_log` | `data/swarm.db` | Audit trail | ADR-017 |
|
|
|
|
|
| `ledger` | `data/swarm.db` | Lightning payments | ADR-018 |
|
|
|
|
|
| `memory_entries` | `data/swarm.db` | Semantic memory (with embeddings) | ADR-019 |
|
|
|
|
|
| `upgrades` | `data/swarm.db` | Self-modification queue | ADR-021 |
|
|
|
|
|
| `provider_metrics` | `data/swarm.db` | LLM router metrics | ADR-020 |
|
2026-03-07 07:28:14 -05:00
|
|
|
| `task_queue` | `data/swarm.db` | Human-in-the-loop task queue | *(not yet implemented)* |
|
2026-02-27 20:10:59 -05:00
|
|
|
| `thoughts` | `data/thoughts.db` | Thought stream | `timmy/thinking.py` |
|
|
|
|
|
| `briefings` | `~/.timmy/briefings.db` | Briefing cache | `timmy/briefing.py` |
|
|
|
|
|
| `approvals` | `~/.timmy/approvals.db` | Governance items | `timmy/approvals.py` |
|
|
|
|
|
|
|
|
|
|
**Existing data flows preserved:**
|
|
|
|
|
|
|
|
|
|
Event Log:
|
feat: complete Event Log, Ledger, Memory, Cascade Router, Upgrade Queue, Activity Feed
This commit implements six major features:
1. Event Log System (src/swarm/event_log.py)
- SQLite-based audit trail for all swarm events
- Task lifecycle tracking (created, assigned, completed, failed)
- Agent lifecycle tracking (joined, left, status changes)
- Integrated with coordinator for automatic logging
- Dashboard page at /swarm/events
2. Lightning Ledger (src/lightning/ledger.py)
- Transaction tracking for Lightning Network payments
- Balance calculations (incoming, outgoing, net, available)
- Integrated with payment_handler for automatic logging
- Dashboard page at /lightning/ledger
3. Semantic Memory / Vector Store (src/memory/vector_store.py)
- Embedding-based similarity search for Echo agent
- Fallback to keyword matching if sentence-transformers unavailable
- Personal facts storage and retrieval
- Dashboard page at /memory
4. Cascade Router Integration (src/timmy/cascade_adapter.py)
- Automatic LLM failover between providers (Ollama → AirLLM → API)
- Circuit breaker pattern for failing providers
- Metrics tracking per provider (latency, error rates)
- Dashboard status page at /router/status
5. Self-Upgrade Approval Queue (src/upgrades/)
- State machine for self-modifications: proposed → approved/rejected → applied/failed
- Human approval required before applying changes
- Git integration for branch management
- Dashboard queue at /self-modify/queue
6. Real-Time Activity Feed (src/events/broadcaster.py)
- WebSocket-based live activity streaming
- Bridges event_log to dashboard clients
- Activity panel on /swarm/live
Tests:
- 101 unit tests passing
- 4 new E2E test files for Selenium testing
- Run with: SELENIUM_UI=1 pytest tests/functional/ -v --headed
Documentation:
- 6 ADRs (017-022) documenting architecture decisions
- Implementation summary in docs/IMPLEMENTATION_SUMMARY.md
- Architecture diagram in docs/architecture-v2.md
2026-02-26 08:01:01 -05:00
|
|
|
```
|
|
|
|
|
Coordinator Action → log_event() → SQLite event_log table
|
|
|
|
|
↓
|
|
|
|
|
WebSocket Broadcast (ADR-022)
|
|
|
|
|
↓
|
|
|
|
|
Dashboard Activity Feed
|
|
|
|
|
```
|
|
|
|
|
|
2026-02-27 20:10:59 -05:00
|
|
|
Lightning Ledger:
|
feat: complete Event Log, Ledger, Memory, Cascade Router, Upgrade Queue, Activity Feed
This commit implements six major features:
1. Event Log System (src/swarm/event_log.py)
- SQLite-based audit trail for all swarm events
- Task lifecycle tracking (created, assigned, completed, failed)
- Agent lifecycle tracking (joined, left, status changes)
- Integrated with coordinator for automatic logging
- Dashboard page at /swarm/events
2. Lightning Ledger (src/lightning/ledger.py)
- Transaction tracking for Lightning Network payments
- Balance calculations (incoming, outgoing, net, available)
- Integrated with payment_handler for automatic logging
- Dashboard page at /lightning/ledger
3. Semantic Memory / Vector Store (src/memory/vector_store.py)
- Embedding-based similarity search for Echo agent
- Fallback to keyword matching if sentence-transformers unavailable
- Personal facts storage and retrieval
- Dashboard page at /memory
4. Cascade Router Integration (src/timmy/cascade_adapter.py)
- Automatic LLM failover between providers (Ollama → AirLLM → API)
- Circuit breaker pattern for failing providers
- Metrics tracking per provider (latency, error rates)
- Dashboard status page at /router/status
5. Self-Upgrade Approval Queue (src/upgrades/)
- State machine for self-modifications: proposed → approved/rejected → applied/failed
- Human approval required before applying changes
- Git integration for branch management
- Dashboard queue at /self-modify/queue
6. Real-Time Activity Feed (src/events/broadcaster.py)
- WebSocket-based live activity streaming
- Bridges event_log to dashboard clients
- Activity panel on /swarm/live
Tests:
- 101 unit tests passing
- 4 new E2E test files for Selenium testing
- Run with: SELENIUM_UI=1 pytest tests/functional/ -v --headed
Documentation:
- 6 ADRs (017-022) documenting architecture decisions
- Implementation summary in docs/IMPLEMENTATION_SUMMARY.md
- Architecture diagram in docs/architecture-v2.md
2026-02-26 08:01:01 -05:00
|
|
|
```
|
|
|
|
|
Payment Handler → create_invoice_entry() → SQLite ledger table
|
|
|
|
|
↓
|
|
|
|
|
mark_settled()
|
|
|
|
|
↓
|
|
|
|
|
Dashboard /lightning/ledger
|
|
|
|
|
```
|
|
|
|
|
|
2026-02-27 20:10:59 -05:00
|
|
|
Semantic Memory:
|
feat: complete Event Log, Ledger, Memory, Cascade Router, Upgrade Queue, Activity Feed
This commit implements six major features:
1. Event Log System (src/swarm/event_log.py)
- SQLite-based audit trail for all swarm events
- Task lifecycle tracking (created, assigned, completed, failed)
- Agent lifecycle tracking (joined, left, status changes)
- Integrated with coordinator for automatic logging
- Dashboard page at /swarm/events
2. Lightning Ledger (src/lightning/ledger.py)
- Transaction tracking for Lightning Network payments
- Balance calculations (incoming, outgoing, net, available)
- Integrated with payment_handler for automatic logging
- Dashboard page at /lightning/ledger
3. Semantic Memory / Vector Store (src/memory/vector_store.py)
- Embedding-based similarity search for Echo agent
- Fallback to keyword matching if sentence-transformers unavailable
- Personal facts storage and retrieval
- Dashboard page at /memory
4. Cascade Router Integration (src/timmy/cascade_adapter.py)
- Automatic LLM failover between providers (Ollama → AirLLM → API)
- Circuit breaker pattern for failing providers
- Metrics tracking per provider (latency, error rates)
- Dashboard status page at /router/status
5. Self-Upgrade Approval Queue (src/upgrades/)
- State machine for self-modifications: proposed → approved/rejected → applied/failed
- Human approval required before applying changes
- Git integration for branch management
- Dashboard queue at /self-modify/queue
6. Real-Time Activity Feed (src/events/broadcaster.py)
- WebSocket-based live activity streaming
- Bridges event_log to dashboard clients
- Activity panel on /swarm/live
Tests:
- 101 unit tests passing
- 4 new E2E test files for Selenium testing
- Run with: SELENIUM_UI=1 pytest tests/functional/ -v --headed
Documentation:
- 6 ADRs (017-022) documenting architecture decisions
- Implementation summary in docs/IMPLEMENTATION_SUMMARY.md
- Architecture diagram in docs/architecture-v2.md
2026-02-26 08:01:01 -05:00
|
|
|
```
|
|
|
|
|
Conversation → store_memory() → SQLite memory_entries (with embedding)
|
|
|
|
|
↓
|
|
|
|
|
search_memories(query)
|
|
|
|
|
↓
|
|
|
|
|
Dashboard /memory
|
|
|
|
|
```
|
|
|
|
|
|
2026-02-27 20:10:59 -05:00
|
|
|
Self-Upgrade Queue:
|
feat: complete Event Log, Ledger, Memory, Cascade Router, Upgrade Queue, Activity Feed
This commit implements six major features:
1. Event Log System (src/swarm/event_log.py)
- SQLite-based audit trail for all swarm events
- Task lifecycle tracking (created, assigned, completed, failed)
- Agent lifecycle tracking (joined, left, status changes)
- Integrated with coordinator for automatic logging
- Dashboard page at /swarm/events
2. Lightning Ledger (src/lightning/ledger.py)
- Transaction tracking for Lightning Network payments
- Balance calculations (incoming, outgoing, net, available)
- Integrated with payment_handler for automatic logging
- Dashboard page at /lightning/ledger
3. Semantic Memory / Vector Store (src/memory/vector_store.py)
- Embedding-based similarity search for Echo agent
- Fallback to keyword matching if sentence-transformers unavailable
- Personal facts storage and retrieval
- Dashboard page at /memory
4. Cascade Router Integration (src/timmy/cascade_adapter.py)
- Automatic LLM failover between providers (Ollama → AirLLM → API)
- Circuit breaker pattern for failing providers
- Metrics tracking per provider (latency, error rates)
- Dashboard status page at /router/status
5. Self-Upgrade Approval Queue (src/upgrades/)
- State machine for self-modifications: proposed → approved/rejected → applied/failed
- Human approval required before applying changes
- Git integration for branch management
- Dashboard queue at /self-modify/queue
6. Real-Time Activity Feed (src/events/broadcaster.py)
- WebSocket-based live activity streaming
- Bridges event_log to dashboard clients
- Activity panel on /swarm/live
Tests:
- 101 unit tests passing
- 4 new E2E test files for Selenium testing
- Run with: SELENIUM_UI=1 pytest tests/functional/ -v --headed
Documentation:
- 6 ADRs (017-022) documenting architecture decisions
- Implementation summary in docs/IMPLEMENTATION_SUMMARY.md
- Architecture diagram in docs/architecture-v2.md
2026-02-26 08:01:01 -05:00
|
|
|
```
|
|
|
|
|
Self-Modify Loop → Propose Change → SQLite upgrades table (status: proposed)
|
|
|
|
|
↓
|
|
|
|
|
Dashboard Review
|
|
|
|
|
↓
|
|
|
|
|
Approve → Apply → Git Commit
|
|
|
|
|
or
|
|
|
|
|
Reject → Cleanup
|
|
|
|
|
```
|
|
|
|
|
|
2026-02-27 20:10:59 -05:00
|
|
|
---
|
feat: complete Event Log, Ledger, Memory, Cascade Router, Upgrade Queue, Activity Feed
This commit implements six major features:
1. Event Log System (src/swarm/event_log.py)
- SQLite-based audit trail for all swarm events
- Task lifecycle tracking (created, assigned, completed, failed)
- Agent lifecycle tracking (joined, left, status changes)
- Integrated with coordinator for automatic logging
- Dashboard page at /swarm/events
2. Lightning Ledger (src/lightning/ledger.py)
- Transaction tracking for Lightning Network payments
- Balance calculations (incoming, outgoing, net, available)
- Integrated with payment_handler for automatic logging
- Dashboard page at /lightning/ledger
3. Semantic Memory / Vector Store (src/memory/vector_store.py)
- Embedding-based similarity search for Echo agent
- Fallback to keyword matching if sentence-transformers unavailable
- Personal facts storage and retrieval
- Dashboard page at /memory
4. Cascade Router Integration (src/timmy/cascade_adapter.py)
- Automatic LLM failover between providers (Ollama → AirLLM → API)
- Circuit breaker pattern for failing providers
- Metrics tracking per provider (latency, error rates)
- Dashboard status page at /router/status
5. Self-Upgrade Approval Queue (src/upgrades/)
- State machine for self-modifications: proposed → approved/rejected → applied/failed
- Human approval required before applying changes
- Git integration for branch management
- Dashboard queue at /self-modify/queue
6. Real-Time Activity Feed (src/events/broadcaster.py)
- WebSocket-based live activity streaming
- Bridges event_log to dashboard clients
- Activity panel on /swarm/live
Tests:
- 101 unit tests passing
- 4 new E2E test files for Selenium testing
- Run with: SELENIUM_UI=1 pytest tests/functional/ -v --headed
Documentation:
- 6 ADRs (017-022) documenting architecture decisions
- Implementation summary in docs/IMPLEMENTATION_SUMMARY.md
- Architecture diagram in docs/architecture-v2.md
2026-02-26 08:01:01 -05:00
|
|
|
|
2026-02-27 20:10:59 -05:00
|
|
|
## Platform
|
|
|
|
|
|
|
|
|
|
### Multi-Platform Presence `[LIVE]`
|
|
|
|
|
|
|
|
|
|
Timmy maintains presence across multiple channels with a consistent identity and
|
|
|
|
|
memory. The dashboard is the central hub for monitoring all activity.
|
|
|
|
|
|
|
|
|
|
| Platform | Module | Status |
|
|
|
|
|
|----------|--------|--------|
|
|
|
|
|
| Web Dashboard | `src/dashboard/` | `[LIVE]` — FastAPI + HTMX + WebSocket |
|
|
|
|
|
| Telegram | `src/integrations/telegram_bot/` | `[LIVE]` — Bridge to Timmy agent |
|
|
|
|
|
| Discord | `src/integrations/chat_bridge/vendors/discord.py` | `[LIVE]` — Chat bridge vendor |
|
|
|
|
|
| Siri Shortcuts | `src/integrations/shortcuts/` | `[LIVE]` — API endpoints for Shortcuts |
|
|
|
|
|
| Voice / NLU | `src/integrations/voice/` | `[LIVE]` — Local intent detection |
|
|
|
|
|
| Mobile | `/mobile` route | `[LIVE]` — iOS-optimized layout (safe area, 44px touch) |
|
|
|
|
|
| WhatsApp | — | `[PLANNED]` |
|
|
|
|
|
|
|
|
|
|
The chat bridge architecture (`src/integrations/chat_bridge/`) provides a
|
|
|
|
|
vendor-agnostic base class (`ChatPlatform`) with a registry
|
|
|
|
|
(`platform_registry`) for adding new platforms.
|
|
|
|
|
|
|
|
|
|
### Embodied AI / Persistent Spatial Environment `[RESEARCH]`
|
|
|
|
|
|
|
|
|
|
Timmy will eventually exist in a persistent 3D environment rather than as a
|
|
|
|
|
text-only agent. The environment would have built-in cameras that Timmy controls,
|
|
|
|
|
and the owner could "FaceTime" into Timmy's world to watch and interact with him
|
|
|
|
|
visually. Timmy would be able to update assets and control the environment
|
|
|
|
|
programmatically.
|
|
|
|
|
|
|
|
|
|
**This is an open research task for Timmy.** Rather than having his embodiment
|
|
|
|
|
imposed, Timmy should investigate the options himself:
|
|
|
|
|
|
|
|
|
|
- Evaluate engines: Unity WebGL, Babylon.js, Three.js, other game/3D engines
|
|
|
|
|
- Consider local-first constraints — no cloud rendering dependencies
|
|
|
|
|
- Research aesthetic choices and spatial design
|
|
|
|
|
- Present findings and a proposed architecture in a morning briefing
|
feat: complete Event Log, Ledger, Memory, Cascade Router, Upgrade Queue, Activity Feed
This commit implements six major features:
1. Event Log System (src/swarm/event_log.py)
- SQLite-based audit trail for all swarm events
- Task lifecycle tracking (created, assigned, completed, failed)
- Agent lifecycle tracking (joined, left, status changes)
- Integrated with coordinator for automatic logging
- Dashboard page at /swarm/events
2. Lightning Ledger (src/lightning/ledger.py)
- Transaction tracking for Lightning Network payments
- Balance calculations (incoming, outgoing, net, available)
- Integrated with payment_handler for automatic logging
- Dashboard page at /lightning/ledger
3. Semantic Memory / Vector Store (src/memory/vector_store.py)
- Embedding-based similarity search for Echo agent
- Fallback to keyword matching if sentence-transformers unavailable
- Personal facts storage and retrieval
- Dashboard page at /memory
4. Cascade Router Integration (src/timmy/cascade_adapter.py)
- Automatic LLM failover between providers (Ollama → AirLLM → API)
- Circuit breaker pattern for failing providers
- Metrics tracking per provider (latency, error rates)
- Dashboard status page at /router/status
5. Self-Upgrade Approval Queue (src/upgrades/)
- State machine for self-modifications: proposed → approved/rejected → applied/failed
- Human approval required before applying changes
- Git integration for branch management
- Dashboard queue at /self-modify/queue
6. Real-Time Activity Feed (src/events/broadcaster.py)
- WebSocket-based live activity streaming
- Bridges event_log to dashboard clients
- Activity panel on /swarm/live
Tests:
- 101 unit tests passing
- 4 new E2E test files for Selenium testing
- Run with: SELENIUM_UI=1 pytest tests/functional/ -v --headed
Documentation:
- 6 ADRs (017-022) documenting architecture decisions
- Implementation summary in docs/IMPLEMENTATION_SUMMARY.md
- Architecture diagram in docs/architecture-v2.md
2026-02-26 08:01:01 -05:00
|
|
|
|
2026-02-27 20:10:59 -05:00
|
|
|
No code exists. No implementation timeline set. This is a long-term roadmap item.
|
feat: complete Event Log, Ledger, Memory, Cascade Router, Upgrade Queue, Activity Feed
This commit implements six major features:
1. Event Log System (src/swarm/event_log.py)
- SQLite-based audit trail for all swarm events
- Task lifecycle tracking (created, assigned, completed, failed)
- Agent lifecycle tracking (joined, left, status changes)
- Integrated with coordinator for automatic logging
- Dashboard page at /swarm/events
2. Lightning Ledger (src/lightning/ledger.py)
- Transaction tracking for Lightning Network payments
- Balance calculations (incoming, outgoing, net, available)
- Integrated with payment_handler for automatic logging
- Dashboard page at /lightning/ledger
3. Semantic Memory / Vector Store (src/memory/vector_store.py)
- Embedding-based similarity search for Echo agent
- Fallback to keyword matching if sentence-transformers unavailable
- Personal facts storage and retrieval
- Dashboard page at /memory
4. Cascade Router Integration (src/timmy/cascade_adapter.py)
- Automatic LLM failover between providers (Ollama → AirLLM → API)
- Circuit breaker pattern for failing providers
- Metrics tracking per provider (latency, error rates)
- Dashboard status page at /router/status
5. Self-Upgrade Approval Queue (src/upgrades/)
- State machine for self-modifications: proposed → approved/rejected → applied/failed
- Human approval required before applying changes
- Git integration for branch management
- Dashboard queue at /self-modify/queue
6. Real-Time Activity Feed (src/events/broadcaster.py)
- WebSocket-based live activity streaming
- Bridges event_log to dashboard clients
- Activity panel on /swarm/live
Tests:
- 101 unit tests passing
- 4 new E2E test files for Selenium testing
- Run with: SELENIUM_UI=1 pytest tests/functional/ -v --headed
Documentation:
- 6 ADRs (017-022) documenting architecture decisions
- Implementation summary in docs/IMPLEMENTATION_SUMMARY.md
- Architecture diagram in docs/architecture-v2.md
2026-02-26 08:01:01 -05:00
|
|
|
|
2026-02-27 20:10:59 -05:00
|
|
|
---
|
feat: complete Event Log, Ledger, Memory, Cascade Router, Upgrade Queue, Activity Feed
This commit implements six major features:
1. Event Log System (src/swarm/event_log.py)
- SQLite-based audit trail for all swarm events
- Task lifecycle tracking (created, assigned, completed, failed)
- Agent lifecycle tracking (joined, left, status changes)
- Integrated with coordinator for automatic logging
- Dashboard page at /swarm/events
2. Lightning Ledger (src/lightning/ledger.py)
- Transaction tracking for Lightning Network payments
- Balance calculations (incoming, outgoing, net, available)
- Integrated with payment_handler for automatic logging
- Dashboard page at /lightning/ledger
3. Semantic Memory / Vector Store (src/memory/vector_store.py)
- Embedding-based similarity search for Echo agent
- Fallback to keyword matching if sentence-transformers unavailable
- Personal facts storage and retrieval
- Dashboard page at /memory
4. Cascade Router Integration (src/timmy/cascade_adapter.py)
- Automatic LLM failover between providers (Ollama → AirLLM → API)
- Circuit breaker pattern for failing providers
- Metrics tracking per provider (latency, error rates)
- Dashboard status page at /router/status
5. Self-Upgrade Approval Queue (src/upgrades/)
- State machine for self-modifications: proposed → approved/rejected → applied/failed
- Human approval required before applying changes
- Git integration for branch management
- Dashboard queue at /self-modify/queue
6. Real-Time Activity Feed (src/events/broadcaster.py)
- WebSocket-based live activity streaming
- Bridges event_log to dashboard clients
- Activity panel on /swarm/live
Tests:
- 101 unit tests passing
- 4 new E2E test files for Selenium testing
- Run with: SELENIUM_UI=1 pytest tests/functional/ -v --headed
Documentation:
- 6 ADRs (017-022) documenting architecture decisions
- Implementation summary in docs/IMPLEMENTATION_SUMMARY.md
- Architecture diagram in docs/architecture-v2.md
2026-02-26 08:01:01 -05:00
|
|
|
|
2026-02-27 20:10:59 -05:00
|
|
|
## Sovereignty & Local-First `[LIVE]`
|
|
|
|
|
|
|
|
|
|
All architecture decisions respect these non-negotiable principles:
|
|
|
|
|
|
|
|
|
|
- **Local-first** — No hard dependencies on cloud services. All inference runs on
|
|
|
|
|
localhost (Ollama, AirLLM).
|
|
|
|
|
- **Data sovereignty** — The owner owns all data. All persistence is SQLite files on
|
|
|
|
|
disk. Data can be backed up and restored independently.
|
|
|
|
|
- **No vendor lock-in** — LLM backends are swappable (Ollama → AirLLM → optional
|
|
|
|
|
API). Infrastructure components are interchangeable.
|
|
|
|
|
- **Graceful degradation** — Optional services (Ollama, Redis, AirLLM, Telegram,
|
|
|
|
|
Discord) degrade gracefully. Log the error, return a fallback, never crash.
|
|
|
|
|
- **Persistence** — Timmy survives service outages, API changes, and platform
|
|
|
|
|
shifts. Version-controlled config enables spin-up from a clean state.
|
|
|
|
|
|
|
|
|
|
Sovereignty score: **9.2/10** — see `docs/SOVEREIGNTY_AUDIT.md` for full audit.
|
|
|
|
|
|
|
|
|
|
Enforcement points: `CLAUDE.md` conventions, `AGENTS.md` non-negotiable rules,
|
|
|
|
|
`config.py` pydantic-settings pattern (never `os.environ.get()` in app code).
|
|
|
|
|
|
|
|
|
|
---
|
feat: complete Event Log, Ledger, Memory, Cascade Router, Upgrade Queue, Activity Feed
This commit implements six major features:
1. Event Log System (src/swarm/event_log.py)
- SQLite-based audit trail for all swarm events
- Task lifecycle tracking (created, assigned, completed, failed)
- Agent lifecycle tracking (joined, left, status changes)
- Integrated with coordinator for automatic logging
- Dashboard page at /swarm/events
2. Lightning Ledger (src/lightning/ledger.py)
- Transaction tracking for Lightning Network payments
- Balance calculations (incoming, outgoing, net, available)
- Integrated with payment_handler for automatic logging
- Dashboard page at /lightning/ledger
3. Semantic Memory / Vector Store (src/memory/vector_store.py)
- Embedding-based similarity search for Echo agent
- Fallback to keyword matching if sentence-transformers unavailable
- Personal facts storage and retrieval
- Dashboard page at /memory
4. Cascade Router Integration (src/timmy/cascade_adapter.py)
- Automatic LLM failover between providers (Ollama → AirLLM → API)
- Circuit breaker pattern for failing providers
- Metrics tracking per provider (latency, error rates)
- Dashboard status page at /router/status
5. Self-Upgrade Approval Queue (src/upgrades/)
- State machine for self-modifications: proposed → approved/rejected → applied/failed
- Human approval required before applying changes
- Git integration for branch management
- Dashboard queue at /self-modify/queue
6. Real-Time Activity Feed (src/events/broadcaster.py)
- WebSocket-based live activity streaming
- Bridges event_log to dashboard clients
- Activity panel on /swarm/live
Tests:
- 101 unit tests passing
- 4 new E2E test files for Selenium testing
- Run with: SELENIUM_UI=1 pytest tests/functional/ -v --headed
Documentation:
- 6 ADRs (017-022) documenting architecture decisions
- Implementation summary in docs/IMPLEMENTATION_SUMMARY.md
- Architecture diagram in docs/architecture-v2.md
2026-02-26 08:01:01 -05:00
|
|
|
|
|
|
|
|
## Integration Points
|
|
|
|
|
|
2026-02-27 20:10:59 -05:00
|
|
|
| Source | → | Target | Mechanism |
|
|
|
|
|
|--------|---|--------|-----------|
|
2026-03-07 07:28:14 -05:00
|
|
|
| Coordinator | → | Event Log | `log_event()` for all lifecycle events *(planned)* |
|
|
|
|
|
| Payment handler | → | Ledger | Creates entries on invoice/settlement *(planned)* |
|
|
|
|
|
| Self-modify loop | → | Upgrade Queue | Stops at proposal, waits for approval *(planned)* |
|
2026-02-27 20:10:59 -05:00
|
|
|
| `timmy/agent.py` | → | Cascade Router | Uses router instead of direct backends |
|
|
|
|
|
| `ws_manager/handler.py` | → | Activity Feed | Broadcasts events to WebSocket clients |
|
|
|
|
|
| Event Log | → | Briefing Engine | `_gather_swarm_summary()` reads events |
|
|
|
|
|
| Approval Items | → | Briefing Engine | `_gather_approvals()` reads pending items |
|
|
|
|
|
| ThinkingEngine | → | WebSocket | Broadcasts thoughts in real-time |
|
|
|
|
|
| ThinkingEngine | → | Event Log | Logs `TIMMY_THOUGHT` events |
|
|
|
|
|
| Error Capture | → | Task Queue | Auto-files bug reports as `task_type="bug_report"` |
|
|
|
|
|
| Error Capture | → | Session Logger | Records errors with context |
|
|
|
|
|
| Error Capture | → | Push Notifier | Sends notification when bug report filed |
|
|
|
|
|
| Event Bus | → | All Subscribers | Pub/sub with wildcard patterns (`agent.task.*`) |
|
|
|
|
|
|
|
|
|
|
---
|
feat: complete Event Log, Ledger, Memory, Cascade Router, Upgrade Queue, Activity Feed
This commit implements six major features:
1. Event Log System (src/swarm/event_log.py)
- SQLite-based audit trail for all swarm events
- Task lifecycle tracking (created, assigned, completed, failed)
- Agent lifecycle tracking (joined, left, status changes)
- Integrated with coordinator for automatic logging
- Dashboard page at /swarm/events
2. Lightning Ledger (src/lightning/ledger.py)
- Transaction tracking for Lightning Network payments
- Balance calculations (incoming, outgoing, net, available)
- Integrated with payment_handler for automatic logging
- Dashboard page at /lightning/ledger
3. Semantic Memory / Vector Store (src/memory/vector_store.py)
- Embedding-based similarity search for Echo agent
- Fallback to keyword matching if sentence-transformers unavailable
- Personal facts storage and retrieval
- Dashboard page at /memory
4. Cascade Router Integration (src/timmy/cascade_adapter.py)
- Automatic LLM failover between providers (Ollama → AirLLM → API)
- Circuit breaker pattern for failing providers
- Metrics tracking per provider (latency, error rates)
- Dashboard status page at /router/status
5. Self-Upgrade Approval Queue (src/upgrades/)
- State machine for self-modifications: proposed → approved/rejected → applied/failed
- Human approval required before applying changes
- Git integration for branch management
- Dashboard queue at /self-modify/queue
6. Real-Time Activity Feed (src/events/broadcaster.py)
- WebSocket-based live activity streaming
- Bridges event_log to dashboard clients
- Activity panel on /swarm/live
Tests:
- 101 unit tests passing
- 4 new E2E test files for Selenium testing
- Run with: SELENIUM_UI=1 pytest tests/functional/ -v --headed
Documentation:
- 6 ADRs (017-022) documenting architecture decisions
- Implementation summary in docs/IMPLEMENTATION_SUMMARY.md
- Architecture diagram in docs/architecture-v2.md
2026-02-26 08:01:01 -05:00
|
|
|
|
|
|
|
|
## Configuration
|
|
|
|
|
|
2026-02-27 20:10:59 -05:00
|
|
|
All config via `from config import settings` — never `os.environ.get()` in app code.
|
feat: complete Event Log, Ledger, Memory, Cascade Router, Upgrade Queue, Activity Feed
This commit implements six major features:
1. Event Log System (src/swarm/event_log.py)
- SQLite-based audit trail for all swarm events
- Task lifecycle tracking (created, assigned, completed, failed)
- Agent lifecycle tracking (joined, left, status changes)
- Integrated with coordinator for automatic logging
- Dashboard page at /swarm/events
2. Lightning Ledger (src/lightning/ledger.py)
- Transaction tracking for Lightning Network payments
- Balance calculations (incoming, outgoing, net, available)
- Integrated with payment_handler for automatic logging
- Dashboard page at /lightning/ledger
3. Semantic Memory / Vector Store (src/memory/vector_store.py)
- Embedding-based similarity search for Echo agent
- Fallback to keyword matching if sentence-transformers unavailable
- Personal facts storage and retrieval
- Dashboard page at /memory
4. Cascade Router Integration (src/timmy/cascade_adapter.py)
- Automatic LLM failover between providers (Ollama → AirLLM → API)
- Circuit breaker pattern for failing providers
- Metrics tracking per provider (latency, error rates)
- Dashboard status page at /router/status
5. Self-Upgrade Approval Queue (src/upgrades/)
- State machine for self-modifications: proposed → approved/rejected → applied/failed
- Human approval required before applying changes
- Git integration for branch management
- Dashboard queue at /self-modify/queue
6. Real-Time Activity Feed (src/events/broadcaster.py)
- WebSocket-based live activity streaming
- Bridges event_log to dashboard clients
- Activity panel on /swarm/live
Tests:
- 101 unit tests passing
- 4 new E2E test files for Selenium testing
- Run with: SELENIUM_UI=1 pytest tests/functional/ -v --headed
Documentation:
- 6 ADRs (017-022) documenting architecture decisions
- Implementation summary in docs/IMPLEMENTATION_SUMMARY.md
- Architecture diagram in docs/architecture-v2.md
2026-02-26 08:01:01 -05:00
|
|
|
|
|
|
|
|
```python
|
2026-02-27 20:10:59 -05:00
|
|
|
# LLM / Inference
|
|
|
|
|
ollama_url: str = "http://localhost:11434"
|
|
|
|
|
ollama_model: str = "llama3.1:8b-instruct"
|
|
|
|
|
timmy_model_backend: str = "ollama" # ollama | airllm | grok | auto
|
|
|
|
|
|
feat: complete Event Log, Ledger, Memory, Cascade Router, Upgrade Queue, Activity Feed
This commit implements six major features:
1. Event Log System (src/swarm/event_log.py)
- SQLite-based audit trail for all swarm events
- Task lifecycle tracking (created, assigned, completed, failed)
- Agent lifecycle tracking (joined, left, status changes)
- Integrated with coordinator for automatic logging
- Dashboard page at /swarm/events
2. Lightning Ledger (src/lightning/ledger.py)
- Transaction tracking for Lightning Network payments
- Balance calculations (incoming, outgoing, net, available)
- Integrated with payment_handler for automatic logging
- Dashboard page at /lightning/ledger
3. Semantic Memory / Vector Store (src/memory/vector_store.py)
- Embedding-based similarity search for Echo agent
- Fallback to keyword matching if sentence-transformers unavailable
- Personal facts storage and retrieval
- Dashboard page at /memory
4. Cascade Router Integration (src/timmy/cascade_adapter.py)
- Automatic LLM failover between providers (Ollama → AirLLM → API)
- Circuit breaker pattern for failing providers
- Metrics tracking per provider (latency, error rates)
- Dashboard status page at /router/status
5. Self-Upgrade Approval Queue (src/upgrades/)
- State machine for self-modifications: proposed → approved/rejected → applied/failed
- Human approval required before applying changes
- Git integration for branch management
- Dashboard queue at /self-modify/queue
6. Real-Time Activity Feed (src/events/broadcaster.py)
- WebSocket-based live activity streaming
- Bridges event_log to dashboard clients
- Activity panel on /swarm/live
Tests:
- 101 unit tests passing
- 4 new E2E test files for Selenium testing
- Run with: SELENIUM_UI=1 pytest tests/functional/ -v --headed
Documentation:
- 6 ADRs (017-022) documenting architecture decisions
- Implementation summary in docs/IMPLEMENTATION_SUMMARY.md
- Architecture diagram in docs/architecture-v2.md
2026-02-26 08:01:01 -05:00
|
|
|
# Cascade Router
|
|
|
|
|
cascade_providers: list[ProviderConfig]
|
|
|
|
|
circuit_breaker_threshold: int = 5
|
|
|
|
|
|
2026-02-27 20:10:59 -05:00
|
|
|
# Thinking
|
|
|
|
|
thinking_enabled: bool = True
|
|
|
|
|
thinking_interval_seconds: int = 300
|
|
|
|
|
|
|
|
|
|
# Error Feedback
|
|
|
|
|
error_feedback_enabled: bool = True
|
|
|
|
|
error_dedup_window_seconds: int = 300
|
|
|
|
|
error_log_enabled: bool = True
|
|
|
|
|
error_log_dir: str = "logs"
|
|
|
|
|
|
feat: complete Event Log, Ledger, Memory, Cascade Router, Upgrade Queue, Activity Feed
This commit implements six major features:
1. Event Log System (src/swarm/event_log.py)
- SQLite-based audit trail for all swarm events
- Task lifecycle tracking (created, assigned, completed, failed)
- Agent lifecycle tracking (joined, left, status changes)
- Integrated with coordinator for automatic logging
- Dashboard page at /swarm/events
2. Lightning Ledger (src/lightning/ledger.py)
- Transaction tracking for Lightning Network payments
- Balance calculations (incoming, outgoing, net, available)
- Integrated with payment_handler for automatic logging
- Dashboard page at /lightning/ledger
3. Semantic Memory / Vector Store (src/memory/vector_store.py)
- Embedding-based similarity search for Echo agent
- Fallback to keyword matching if sentence-transformers unavailable
- Personal facts storage and retrieval
- Dashboard page at /memory
4. Cascade Router Integration (src/timmy/cascade_adapter.py)
- Automatic LLM failover between providers (Ollama → AirLLM → API)
- Circuit breaker pattern for failing providers
- Metrics tracking per provider (latency, error rates)
- Dashboard status page at /router/status
5. Self-Upgrade Approval Queue (src/upgrades/)
- State machine for self-modifications: proposed → approved/rejected → applied/failed
- Human approval required before applying changes
- Git integration for branch management
- Dashboard queue at /self-modify/queue
6. Real-Time Activity Feed (src/events/broadcaster.py)
- WebSocket-based live activity streaming
- Bridges event_log to dashboard clients
- Activity panel on /swarm/live
Tests:
- 101 unit tests passing
- 4 new E2E test files for Selenium testing
- Run with: SELENIUM_UI=1 pytest tests/functional/ -v --headed
Documentation:
- 6 ADRs (017-022) documenting architecture decisions
- Implementation summary in docs/IMPLEMENTATION_SUMMARY.md
- Architecture diagram in docs/architecture-v2.md
2026-02-26 08:01:01 -05:00
|
|
|
# Self-Upgrade
|
|
|
|
|
auto_approve_upgrades: bool = False
|
|
|
|
|
upgrade_timeout_hours: int = 24
|
|
|
|
|
|
|
|
|
|
# Activity Feed
|
2026-02-27 20:10:59 -05:00
|
|
|
websocket_event_throttle: int = 10 # events/sec
|
|
|
|
|
activity_feed_buffer: int = 100 # events to buffer
|
|
|
|
|
|
|
|
|
|
# L402 Lightning
|
|
|
|
|
l402_hmac_secret: str # change in prod
|
|
|
|
|
l402_macaroon_secret: str # change in prod
|
|
|
|
|
lightning_backend: str = "mock" # mock | lnd
|
feat: complete Event Log, Ledger, Memory, Cascade Router, Upgrade Queue, Activity Feed
This commit implements six major features:
1. Event Log System (src/swarm/event_log.py)
- SQLite-based audit trail for all swarm events
- Task lifecycle tracking (created, assigned, completed, failed)
- Agent lifecycle tracking (joined, left, status changes)
- Integrated with coordinator for automatic logging
- Dashboard page at /swarm/events
2. Lightning Ledger (src/lightning/ledger.py)
- Transaction tracking for Lightning Network payments
- Balance calculations (incoming, outgoing, net, available)
- Integrated with payment_handler for automatic logging
- Dashboard page at /lightning/ledger
3. Semantic Memory / Vector Store (src/memory/vector_store.py)
- Embedding-based similarity search for Echo agent
- Fallback to keyword matching if sentence-transformers unavailable
- Personal facts storage and retrieval
- Dashboard page at /memory
4. Cascade Router Integration (src/timmy/cascade_adapter.py)
- Automatic LLM failover between providers (Ollama → AirLLM → API)
- Circuit breaker pattern for failing providers
- Metrics tracking per provider (latency, error rates)
- Dashboard status page at /router/status
5. Self-Upgrade Approval Queue (src/upgrades/)
- State machine for self-modifications: proposed → approved/rejected → applied/failed
- Human approval required before applying changes
- Git integration for branch management
- Dashboard queue at /self-modify/queue
6. Real-Time Activity Feed (src/events/broadcaster.py)
- WebSocket-based live activity streaming
- Bridges event_log to dashboard clients
- Activity panel on /swarm/live
Tests:
- 101 unit tests passing
- 4 new E2E test files for Selenium testing
- Run with: SELENIUM_UI=1 pytest tests/functional/ -v --headed
Documentation:
- 6 ADRs (017-022) documenting architecture decisions
- Implementation summary in docs/IMPLEMENTATION_SUMMARY.md
- Architecture diagram in docs/architecture-v2.md
2026-02-26 08:01:01 -05:00
|
|
|
```
|
|
|
|
|
|
2026-02-27 20:10:59 -05:00
|
|
|
---
|
|
|
|
|
|
feat: complete Event Log, Ledger, Memory, Cascade Router, Upgrade Queue, Activity Feed
This commit implements six major features:
1. Event Log System (src/swarm/event_log.py)
- SQLite-based audit trail for all swarm events
- Task lifecycle tracking (created, assigned, completed, failed)
- Agent lifecycle tracking (joined, left, status changes)
- Integrated with coordinator for automatic logging
- Dashboard page at /swarm/events
2. Lightning Ledger (src/lightning/ledger.py)
- Transaction tracking for Lightning Network payments
- Balance calculations (incoming, outgoing, net, available)
- Integrated with payment_handler for automatic logging
- Dashboard page at /lightning/ledger
3. Semantic Memory / Vector Store (src/memory/vector_store.py)
- Embedding-based similarity search for Echo agent
- Fallback to keyword matching if sentence-transformers unavailable
- Personal facts storage and retrieval
- Dashboard page at /memory
4. Cascade Router Integration (src/timmy/cascade_adapter.py)
- Automatic LLM failover between providers (Ollama → AirLLM → API)
- Circuit breaker pattern for failing providers
- Metrics tracking per provider (latency, error rates)
- Dashboard status page at /router/status
5. Self-Upgrade Approval Queue (src/upgrades/)
- State machine for self-modifications: proposed → approved/rejected → applied/failed
- Human approval required before applying changes
- Git integration for branch management
- Dashboard queue at /self-modify/queue
6. Real-Time Activity Feed (src/events/broadcaster.py)
- WebSocket-based live activity streaming
- Bridges event_log to dashboard clients
- Activity panel on /swarm/live
Tests:
- 101 unit tests passing
- 4 new E2E test files for Selenium testing
- Run with: SELENIUM_UI=1 pytest tests/functional/ -v --headed
Documentation:
- 6 ADRs (017-022) documenting architecture decisions
- Implementation summary in docs/IMPLEMENTATION_SUMMARY.md
- Architecture diagram in docs/architecture-v2.md
2026-02-26 08:01:01 -05:00
|
|
|
## Security Considerations
|
|
|
|
|
|
|
|
|
|
| Feature | Risk | Mitigation |
|
|
|
|
|
|---------|------|------------|
|
|
|
|
|
| Event Log | Log injection | Sanitize all data fields |
|
|
|
|
|
| Ledger | Payment forgery | Verify with Lightning node |
|
|
|
|
|
| Memory | Data exposure | Filter by user permissions |
|
|
|
|
|
| Upgrade Queue | Unauthorized changes | Require approval, audit log |
|
2026-02-27 20:10:59 -05:00
|
|
|
| Cascade Router | API key exposure | Use `config.settings`, never hardcoded |
|
|
|
|
|
| Activity Feed | Data leak | Authenticate WebSocket connections |
|
|
|
|
|
| Self-Modify | Malicious code injection | Git safety rollback, pytest gate, `GOLDEN_TIMMY` |
|
|
|
|
|
| Task Queue | Unauthorized execution | Auto-approve rules, status gates |
|
|
|
|
|
| Approvals | Bypass governance | `GOLDEN_TIMMY` flag, 7-day expiry |
|
|
|
|
|
| Coordinator | Security-sensitive module | Review required before changes |
|
|
|
|
|
| L402 Proxy | Payment manipulation | HMAC signing, macaroon verification |
|
|
|
|
|
| Error Capture | Info leak in stack traces | Truncate to 2000 chars, sanitize context |
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
## Roadmap
|
|
|
|
|
|
|
|
|
|
| Phase | Name | Status | Features |
|
|
|
|
|
|-------|------|--------|----------|
|
|
|
|
|
| 1 | Genesis (v1.0) | `[LIVE]` | Core agent, Ollama, SQLite, dashboard |
|
|
|
|
|
| 2 | Exodus (v2.0) | `[LIVE]` | Swarm, L402, Voice, Marketplace, Hands |
|
|
|
|
|
| 3 | Always-On | `[LIVE]` | ThinkingEngine, Task Queue, continuous thought loop |
|
|
|
|
|
| 4 | Self-Sovereignty | `[LIVE]` | Self-modify loop, error feedback, bug tracker |
|
|
|
|
|
| 5 | Multi-Platform | `[LIVE]` | Telegram, Discord, Siri, mobile layout |
|
|
|
|
|
| 6 | Intelligence Surface | `[PARTIAL]` | Text briefing, push notifications, approval governance |
|
|
|
|
|
| 7 | Briefing v2 | `[PLANNED]` | Audio narration, slides, interactive approvals |
|
|
|
|
|
| 8 | Attention Economy | `[PLANNED]` | Engagement tracking, escalation threshold calibration |
|
|
|
|
|
| 9 | Embodied AI | `[RESEARCH]` | 3D environment investigation — Timmy researches his own form |
|
|
|
|
|
| 10 | Revelation (v3.0) | `[PLANNED]` | Lightning treasury, `.app` bundle, federation |
|