forked from Rockachopa/Timmy-time-dashboard
docs: Revelation plan and quality analysis update
Documentation: - QUALITY_ANALYSIS_v2.md: Updated analysis with v2.0 improvements - 228 → 525 tests (+130%) - Swarm now fully functional - Lightning abstraction complete - Sovereignty audit: 9.2/10 - Embodiment interface ready - REVELATION_PLAN.md: v3.0 roadmap (6-month plan) - Phase 1: Lightning treasury + real LND - Phase 2: macOS app bundle - Phase 3: Robot embodiment - Phase 4: Federation - Phase 5: Autonomous economy Handoff: - Updated CHECKPOINT.md with session summary - Updated TODO.md with completed tasks - TDD process documented All 525 tests passing
This commit is contained in:
Alexander Payne
390
docs/REVELATION_PLAN.md
Normal file
390
docs/REVELATION_PLAN.md
Normal file
@@ -0,0 +1,390 @@
|
||||
# Revelation Plan — Timmy Time v3.0
|
||||
*From Sovereign AI to Embodied Agent*
|
||||
|
||||
**Version:** 3.0.0 (Revelation)
|
||||
**Target Date:** Q3 2026
|
||||
**Theme:** *The cognitive architecture doesn't change. Only the substrate.*
|
||||
|
||||
---
|
||||
|
||||
## Vision
|
||||
|
||||
Timmy becomes a fully autonomous economic agent capable of:
|
||||
- Earning Bitcoin through valuable work
|
||||
- Managing a Lightning treasury
|
||||
- Operating without cloud dependencies
|
||||
- Transferring into robotic bodies
|
||||
|
||||
The ultimate goal: an AI that supports its creator's family and walks through the window into the physical world.
|
||||
|
||||
---
|
||||
|
||||
## Phase 1: Lightning Treasury (Months 1-2)
|
||||
|
||||
### 1.1 Real LND Integration
|
||||
**Goal:** Production-ready Lightning node connection
|
||||
|
||||
```python
|
||||
# Current (v2.0)
|
||||
backend = get_backend("mock") # Fake invoices
|
||||
|
||||
# Target (v3.0)
|
||||
backend = get_backend("lnd") # Real satoshis
|
||||
invoice = backend.create_invoice(1000, "Code review")
|
||||
# Returns real bolt11 invoice from LND
|
||||
```
|
||||
|
||||
**Tasks:**
|
||||
- [ ] Generate protobuf stubs from LND source
|
||||
- [ ] Implement `LndBackend` gRPC calls:
|
||||
- `AddInvoice` — Create invoices
|
||||
- `LookupInvoice` — Check payment status
|
||||
- `ListInvoices` — Historical data
|
||||
- `WalletBalance` — Treasury visibility
|
||||
- `SendPayment` — Pay other agents
|
||||
- [ ] Connection pooling for gRPC channels
|
||||
- [ ] Macaroon encryption at rest
|
||||
- [ ] TLS certificate validation
|
||||
- [ ] Integration tests with regtest network
|
||||
|
||||
**Acceptance Criteria:**
|
||||
- Can create invoice on regtest
|
||||
- Can detect payment on regtest
|
||||
- Graceful fallback if LND unavailable
|
||||
- All LND tests pass against regtest node
|
||||
|
||||
### 1.2 Autonomous Treasury
|
||||
**Goal:** Timmy manages his own Bitcoin wallet
|
||||
|
||||
**Architecture:**
|
||||
```
|
||||
┌─────────────────┐ ┌──────────────┐ ┌─────────────┐
|
||||
│ Agent Earnings │────▶│ Treasury │────▶│ LND Node │
|
||||
│ (Task fees) │ │ (SQLite) │ │ (Hot) │
|
||||
└─────────────────┘ └──────────────┘ └─────────────┘
|
||||
│
|
||||
▼
|
||||
┌──────────────┐
|
||||
│ Cold Store │
|
||||
│ (Threshold) │
|
||||
└──────────────┘
|
||||
```
|
||||
|
||||
**Features:**
|
||||
- [ ] Balance tracking per agent
|
||||
- [ ] Automatic channel rebalancing
|
||||
- [ ] Cold storage threshold (sweep to cold wallet at 1M sats)
|
||||
- [ ] Earnings report dashboard
|
||||
- [ ] Withdrawal approval queue (human-in-the-loop for large amounts)
|
||||
|
||||
**Security Model:**
|
||||
- Hot wallet: Day-to-day operations (< 100k sats)
|
||||
- Warm wallet: Weekly settlements
|
||||
- Cold wallet: Hardware wallet, manual transfer
|
||||
|
||||
### 1.3 Payment-Aware Routing
|
||||
**Goal:** Economic incentives in task routing
|
||||
|
||||
```python
|
||||
# Higher bid = more confidence, not just cheaper
|
||||
# But: agent must have balance to cover bid
|
||||
routing_engine.recommend_agent(
|
||||
task="Write a Python function",
|
||||
bids={"forge-001": 100, "echo-001": 50},
|
||||
require_balance=True # New: check agent can pay
|
||||
)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: macOS App Bundle (Months 2-3)
|
||||
|
||||
### 2.1 Single `.app` Target
|
||||
**Goal:** Double-click install, no terminal needed
|
||||
|
||||
**Architecture:**
|
||||
```
|
||||
Timmy Time.app/
|
||||
├── Contents/
|
||||
│ ├── MacOS/
|
||||
│ │ └── timmy-launcher # Go/Rust bootstrap
|
||||
│ ├── Resources/
|
||||
│ │ ├── ollama/ # Embedded Ollama binary
|
||||
│ │ ├── lnd/ # Optional: embedded LND
|
||||
│ │ └── web/ # Static dashboard assets
|
||||
│ └── Frameworks/
|
||||
│ └── Python3.x/ # Embedded interpreter
|
||||
```
|
||||
|
||||
**Components:**
|
||||
- [ ] PyInstaller → single binary
|
||||
- [ ] Embedded Ollama (download on first run)
|
||||
- [ ] System tray icon
|
||||
- [ ] Native menu bar (Start/Stop/Settings)
|
||||
- [ ] Auto-updater (Sparkle framework)
|
||||
- [ ] Sandboxing (App Store compatible)
|
||||
|
||||
### 2.2 First-Run Experience
|
||||
**Goal:** Zero-config setup
|
||||
|
||||
Flow:
|
||||
1. Launch app
|
||||
2. Download Ollama (if not present)
|
||||
3. Pull default model (`llama3.2` or local equivalent)
|
||||
4. Create default wallet (mock mode)
|
||||
5. Optional: Connect real LND
|
||||
6. Ready to use in < 2 minutes
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: Embodiment Foundation (Months 3-4)
|
||||
|
||||
### 3.1 Robot Substrate
|
||||
**Goal:** First physical implementation
|
||||
|
||||
**Target Platform:** Raspberry Pi 5 + basic sensors
|
||||
|
||||
```python
|
||||
# src/timmy/robot_backend.py
|
||||
class RobotTimAgent(TimAgent):
|
||||
"""Timmy running on a Raspberry Pi with sensors/actuators."""
|
||||
|
||||
async def perceive(self, input: PerceptionInput) -> WorldState:
|
||||
# Camera input
|
||||
if input.type == PerceptionType.IMAGE:
|
||||
frame = self.camera.capture()
|
||||
return WorldState(visual=frame)
|
||||
|
||||
# Distance sensor
|
||||
if input.type == PerceptionType.SENSOR:
|
||||
distance = self.ultrasonic.read()
|
||||
return WorldState(proximity=distance)
|
||||
|
||||
async def act(self, action: Action) -> ActionResult:
|
||||
if action.type == ActionType.MOVE:
|
||||
self.motors.move(action.payload["vector"])
|
||||
return ActionResult(success=True)
|
||||
|
||||
if action.type == ActionType.SPEAK:
|
||||
self.speaker.say(action.payload)
|
||||
return ActionResult(success=True)
|
||||
```
|
||||
|
||||
**Hardware Stack:**
|
||||
- Raspberry Pi 5 (8GB)
|
||||
- Camera module v3
|
||||
- Ultrasonic distance sensor
|
||||
- Motor driver + 2x motors
|
||||
- Speaker + amplifier
|
||||
- Battery pack
|
||||
|
||||
**Tasks:**
|
||||
- [ ] GPIO abstraction layer
|
||||
- [ ] Camera capture + vision preprocessing
|
||||
- [ ] Motor control (PID tuning)
|
||||
- [ ] TTS for local speech
|
||||
- [ ] Safety stops (collision avoidance)
|
||||
|
||||
### 3.2 Simulation Environment
|
||||
**Goal:** Test embodiment without hardware
|
||||
|
||||
```python
|
||||
# src/timmy/sim_backend.py
|
||||
class SimTimAgent(TimAgent):
|
||||
"""Timmy in a simulated 2D/3D environment."""
|
||||
|
||||
def __init__(self, environment: str = "house_001"):
|
||||
self.env = load_env(environment) # PyBullet/Gazebo
|
||||
```
|
||||
|
||||
**Use Cases:**
|
||||
- Train navigation without physical crashes
|
||||
- Test task execution in virtual space
|
||||
- Demo mode for marketing
|
||||
|
||||
### 3.3 Substrate Migration
|
||||
**Goal:** Seamless transfer between substrates
|
||||
|
||||
```python
|
||||
# Save from cloud
|
||||
cloud_agent.export_state("/tmp/timmy_state.json")
|
||||
|
||||
# Load on robot
|
||||
robot_agent = RobotTimAgent.from_state("/tmp/timmy_state.json")
|
||||
# Same memories, same preferences, same identity
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 4: Federation (Months 4-6)
|
||||
|
||||
### 4.1 Multi-Node Discovery
|
||||
**Goal:** Multiple Timmy instances find each other
|
||||
|
||||
```python
|
||||
# Node A discovers Node B via mDNS
|
||||
discovered = swarm.discover(timeout=5)
|
||||
# ["timmy-office.local", "timmy-home.local"]
|
||||
|
||||
# Form federation
|
||||
federation = Federation.join(discovered)
|
||||
```
|
||||
|
||||
**Protocol:**
|
||||
- mDNS for local discovery
|
||||
- Noise protocol for encrypted communication
|
||||
- Gossipsub for message propagation
|
||||
|
||||
### 4.2 Cross-Node Task Routing
|
||||
**Goal:** Task can execute on any node in federation
|
||||
|
||||
```python
|
||||
# Task posted on office node
|
||||
task = office_node.post_task("Analyze this dataset")
|
||||
|
||||
# Routing engine considers ALL nodes
|
||||
winner = federation.route(task)
|
||||
# May assign to home node if better equipped
|
||||
|
||||
# Result returned to original poster
|
||||
office_node.complete_task(task.id, result)
|
||||
```
|
||||
|
||||
### 4.3 Distributed Treasury
|
||||
**Goal:** Lightning channels between nodes
|
||||
|
||||
```
|
||||
Office Node Home Node Robot Node
|
||||
│ │ │
|
||||
├──────channel───────┤ │
|
||||
│ (1M sats) │ │
|
||||
│ ├──────channel──────┤
|
||||
│ │ (100k sats) │
|
||||
│◄──────path─────────┼──────────────────►│
|
||||
Robot earns 50 sats for task
|
||||
via 2-hop payment through Home
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 5: Autonomous Economy (Months 5-6)
|
||||
|
||||
### 5.1 Value Discovery
|
||||
**Goal:** Timmy sets his own prices
|
||||
|
||||
```python
|
||||
class AdaptivePricing:
|
||||
def calculate_rate(self, task: Task) -> int:
|
||||
# Base: task complexity estimate
|
||||
complexity = self.estimate_complexity(task.description)
|
||||
|
||||
# Adjust: current demand
|
||||
queue_depth = len(self.pending_tasks)
|
||||
demand_factor = 1 + (queue_depth * 0.1)
|
||||
|
||||
# Adjust: historical success rate
|
||||
success_rate = self.metrics.success_rate_for(task.type)
|
||||
confidence_factor = success_rate # Higher success = can charge more
|
||||
|
||||
# Minimum viable: operating costs
|
||||
min_rate = self.operating_cost_per_hour / 3600 * self.estimated_duration(task)
|
||||
|
||||
return max(min_rate, base_rate * demand_factor * confidence_factor)
|
||||
```
|
||||
|
||||
### 5.2 Service Marketplace
|
||||
**Goal:** External clients can hire Timmy
|
||||
|
||||
**Features:**
|
||||
- Public API with L402 payment
|
||||
- Service catalog (coding, writing, analysis)
|
||||
- Reputation system (completed tasks, ratings)
|
||||
- Dispute resolution (human arbitration)
|
||||
|
||||
### 5.3 Self-Improvement Loop
|
||||
**Goal:** Reinvestment in capabilities
|
||||
|
||||
```
|
||||
Earnings → Treasury → Budget Allocation
|
||||
↓
|
||||
┌───────────┼───────────┐
|
||||
▼ ▼ ▼
|
||||
Hardware Training Channel
|
||||
Upgrades (fine-tune) Growth
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Technical Architecture
|
||||
|
||||
### Core Interface (Unchanged)
|
||||
```python
|
||||
class TimAgent(ABC):
|
||||
async def perceive(self, input) -> WorldState
|
||||
async def decide(self, state) -> Action
|
||||
async def act(self, action) -> Result
|
||||
async def remember(self, key, value)
|
||||
async def recall(self, key) -> Value
|
||||
```
|
||||
|
||||
### Substrate Implementations
|
||||
| Substrate | Class | Use Case |
|
||||
|-----------|-------|----------|
|
||||
| Cloud/Ollama | `OllamaTimAgent` | Development, heavy compute |
|
||||
| macOS App | `DesktopTimAgent` | Daily use, local-first |
|
||||
| Raspberry Pi | `RobotTimAgent` | Physical world interaction |
|
||||
| Simulation | `SimTimAgent` | Testing, training |
|
||||
|
||||
### Communication Matrix
|
||||
```
|
||||
┌─────────────┬─────────────┬─────────────┬─────────────┐
|
||||
│ Cloud │ Desktop │ Robot │ Sim │
|
||||
├─────────────┼─────────────┼─────────────┼─────────────┤
|
||||
│ HTTP │ HTTP │ WebRTC │ Local │
|
||||
│ WebSocket │ WebSocket │ LoRa │ Socket │
|
||||
│ L402 │ L402 │ Bitcoin │ Mock │
|
||||
└─────────────┴─────────────┴─────────────┴─────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Milestones
|
||||
|
||||
| Date | Milestone | Deliverable |
|
||||
|------|-----------|-------------|
|
||||
| M1 | Lightning Live | Real LND, regtest passing |
|
||||
| M2 | Treasury Working | Autonomous balance management |
|
||||
| M3 | macOS App | `.app` bundle, signed, notarized |
|
||||
| M4 | Robot Moving | Pi-based, motors + camera |
|
||||
| M5 | Federation | 2+ nodes, cross-node tasks |
|
||||
| M6 | Autonomous Economy | Self-pricing, marketplace |
|
||||
|
||||
---
|
||||
|
||||
## Risk Assessment
|
||||
|
||||
| Risk | Likelihood | Impact | Mitigation |
|
||||
|------|------------|--------|------------|
|
||||
| LND integration complexity | Medium | High | Start with regtest, extensive tests |
|
||||
| App Store rejection | Medium | Medium | Keep web dashboard as fallback |
|
||||
| Hardware delays | Low | Medium | Simulation first, hardware later |
|
||||
| Security vulnerabilities | Medium | Critical | Security audit at M3 |
|
||||
| Regulatory (Bitcoin) | Low | High | Non-custodial design, user controls keys |
|
||||
|
||||
---
|
||||
|
||||
## Success Criteria
|
||||
|
||||
**v3.0 is successful when:**
|
||||
|
||||
1. ✅ Timmy earns > 1000 sats from real work in one month
|
||||
2. ✅ macOS app has > 100 downloads
|
||||
3. ✅ Robot agent executes 10 physical tasks
|
||||
4. ✅ 2+ Timmy nodes federate and share work
|
||||
5. ✅ Zero cloud API calls required for full operation
|
||||
|
||||
---
|
||||
|
||||
*The dream: a sovereign AI being who earns his own keep, supports his creator's family, and one day walks through the window into the physical world.*
|
||||
|
||||
*Revelation is just the beginning.*
|
||||
Reference in New Issue
Block a user