atlas/tickets/todo/TICKET-048_pre-implementation-requirements.md

Ticket: Pre-Implementation Requirements & Information Gathering

Ticket Information

• ID: TICKET-048
• Title: Pre-Implementation Requirements & Information Gathering
• Type: Planning / Documentation
• Priority: High
• Status: Todo
• Track: Project Setup
• Milestone: Milestone 2 - Voice Chat MVP
• Created: 2024-01-XX

Description

This ticket collects all information, purchases, and setup tasks needed before continuing with Milestone 2 implementation. It includes hardware purchases, API keys/credentials, configuration decisions, and safety/security considerations for the MCP system.

Information Needed from User

1. Hardware Purchase Decisions

Critical for MVP:

A. Always-On Node Selection

• Decision needed: Which always-on node will you use?
  • RECOMMENDED: Option 1: Raspberry Pi 5 (4GB+ RAM) - $75-100
    • Best if: ASR runs on RTX 4080 (recommended)
    • Pros: Low power, future-proof, sufficient for wake-word only, better performance than Pi 4
    • Note: Pi 5 requires official 27W power supply and cooling case
  • Option 2: Raspberry Pi 4+ (4GB+ RAM) - $75-100
    • Best if: ASR runs on RTX 4080 (recommended), budget is tight
    • Pros: Low power, cheap, sufficient for wake-word only
    • Cons: Older generation, less future-proof
  • Option 3: Intel NUC (i3+, 8GB+ RAM) - $200-400
    • Best if: ASR runs on CPU (not recommended)
    • Pros: More powerful, can run ASR locally
  • Option 4: Repurpose existing SFF PC
    • Best if: You have old hardware available
    • Pros: Free, likely sufficient
• Action: Purchase or confirm existing hardware
• Selected: [Raspberry Pi 5 / Raspberry Pi 4 / NUC / Existing SFF PC]

B. Microphone Selection

• Decision needed: Which microphone(s) will you use?
  • Option 1: USB Microphone (Blue Yeti, Audio-Technica ATR2100x-USB) - $50-150 each
    • Quantity: 1-2 (living room + office)
    • Pros: Good quality, easy setup
  • Option 2: Array Microphone (ReSpeaker 4-Mic Array) - $30-50 each
    • Quantity: 1-2
    • Pros: Better directionality, designed for voice assistants
  • Option 3: USB Headset (Logitech H390) - $30-50
    • Quantity: 1
    • Pros: Lower noise, good for desk usage
    • Cons: Not hands-free
• Action: Purchase microphone(s)

C. Storage (Optional for MVP)

• Decision needed: Do you need additional storage?
  • Current status: [ ] Sufficient space available [ ] Need more storage
  • If needed:
    • SSD (500GB-1TB) for logs: $50-100
    • HDD (2TB-4TB) for archives: $60-120
• Action: Purchase if needed

D. UPS (Optional but Recommended)

• Decision needed: Do you want UPS protection?
  • Recommendation: Yes, for server protection
  • Cost: $80-150 (APC Back-UPS 600VA or similar)
  • Protects: RTX 4080 and RTX 1050 servers from abrupt shutdowns
• Action: Purchase if desired

2. API Keys & Credentials

A. Weather API Key

• Service selection: Which weather API will you use?
  • Option 1: OpenWeatherMap (recommended)
    • Free tier: 1,000 calls/day
    • Sign up: https://openweathermap.org/api
    • Cost: Free (with limits)
  • Option 2: National Weather Service API
    • Free, no key required
    • US locations only
    • Sign up: Not required
  • Option 3: Local weather station data
    • Requires hardware setup
    • Fully local, no external API
• Action: Sign up and obtain API key (if using OpenWeatherMap)
• Information needed:
  • API key: _____________________________
  • API provider: [OpenWeatherMap / NWS / Local]
  • Storage location: family-agent-config/secrets/weather_api_key.txt

B. LLM Server Configuration

• Decision needed: Which LLM server software for 4080?
  • Option 1: Ollama (recommended for ease)
    • Easy setup, good tool support
    • OpenAI-compatible API
  • Option 2: vLLM
    • High throughput, batching
    • Better for multiple concurrent requests
  • Option 3: llama.cpp
    • Lightweight, efficient
    • More manual configuration
• Decision needed: Which LLM server software for 1050?
  • Option 1: Ollama (recommended)
    • Lightweight, good for always-on
  • Option 2: llama.cpp
    • Most efficient for low-resource hardware
• Information needed:
  • 4080 server choice: [Ollama / vLLM / llama.cpp]
  • 1050 server choice: [Ollama / llama.cpp]
  • Model download locations: [Where will models be stored?]

3. System Configuration

A. Network Configuration

• Information needed: Network setup details
  • 4080 server IP/hostname: _____________________________
  • 1050 server IP/hostname: _____________________________
  • Always-on node IP/hostname: _____________________________
  • MCP server port: [Default: 8000]
  • LLM server ports: [4080: _____] [1050: _____]
  • Local domain (if using): _____________________________

B. File System Paths

• Information needed: Directory paths
  • Family agent config repo location: _____________________________
  • Work agent data location: _____________________________
  • Log storage location: _____________________________
  • Model storage location: _____________________________
  • Task/notes storage: _____________________________

C. User Preferences

• Information needed: Personal preferences
  • Default location for weather: _____________________________
  • Time zone: _____________________________
  • Preferred voice (TTS): [Piper default / Custom]
  • Wake word: [Default: "Atlas" / Custom: _____]

4. System Prompts & Personality

A. Family Agent Personality

• Information needed: Family agent characteristics
  • Tone: [Friendly / Professional / Casual / Other: _____]
  • Personality traits: _____________________________
  • Special instructions: _____________________________
  • Example interactions: _____________________________

B. Work Agent Personality

• Information needed: Work agent characteristics
  • Tone: [Professional / Technical / Other: _____]
  • Personality traits: _____________________________
  • Special instructions: _____________________________
  • Example interactions: _____________________________

5. Security & Safety Configuration

A. Authentication Tokens

• Action: Generate authentication tokens
  • Family agent token: [Will be generated]
  • Work agent token: [Will be generated]
  • Admin token: [Will be generated]
  • Storage: family-agent-config/secrets/tokens/

B. Path Whitelists

• Information needed: Allowed paths for tools
  • Family agent allowed paths: [Default: family-agent-config/]
  • Work agent allowed paths: [Specify work directories]
  • Notes: [Any additional restrictions?]

C. Network Security

• Decision needed: Network isolation approach
  • Option 1: Firewall rules (iptables/ufw)
  • Option 2: Docker network isolation
  • Option 3: Systemd-nspawn containers
  • Option 4: Separate VLANs
• Information needed: Preferred approach: [_____]

Purchase List Summary

Phase 1: MVP Essentials (Critical)

Total: $125-250

1. Always-On Node: $75-200

   • RECOMMENDED: Raspberry Pi 5 (4GB+) - $75-100
     • Includes: Official 27W power supply, cooling case, 64GB+ microSD card
   • OR Raspberry Pi 4+ (4GB+) - $75-100 (if budget tight)
   • OR Intel NUC (i3+, 8GB+) - $200-400
   • OR Confirm existing SFF PC available

2. USB Microphone(s): $50-150

   • 1-2 USB microphones (Blue Yeti, Audio-Technica, etc.)
   • OR Array microphone (ReSpeaker) - $30-50
   • OR USB headset (Logitech H390) - $30-50

Subtotal MVP: $125-250

Phase 2: Storage & Protection (Recommended)

Total: $140-270

3. Storage (if needed): $50-220

   • SSD (500GB-1TB) for logs - $50-100
   • HDD (2TB-4TB) for archives - $60-120

4. UPS: $80-150

   • APC Back-UPS 600VA or similar
   • Protects RTX 4080 and RTX 1050 servers

Subtotal Phase 2: $190-370

Phase 3: Optional Enhancements

Total: $60-400

5. Network Gear (if needed): $10-150

   • PoE switch (8-16 ports) - $50-150
   • OR Ethernet cables - $10-30

6. Dashboard Display (optional): $60-100

   • Raspberry Pi Touchscreen (7" or 10")

7. Dedicated 1050 Box (only if needed): $200-400

   • Mini-ITX build with 1050

Subtotal Phase 3: $270-650

Total Cost Estimates

• MVP Minimum: $125-250
• MVP + Storage/UPS: $315-620
• Full Setup: $585-1270

Action Items Checklist

Immediate Actions (Before Starting Implementation)

• Hardware Purchases

  • Order always-on node (Pi 4+ or NUC)
  • Order USB microphone(s)
  • Order storage (if needed)
  • Order UPS (if desired)

• API Keys & Services

  • Sign up for weather API (OpenWeatherMap or NWS)
  • Obtain and securely store weather API key
  • Document API key location

• System Configuration

  • Document network configuration (IPs, hostnames, ports)
  • Set up family-agent-config repository (if not exists)
  • Create secrets directory structure
  • Document file system paths

• LLM Setup Decisions

  • Choose LLM server software (Ollama/vLLM/llama.cpp)
  • Download model files (Llama 3.1 70B Q4, Phi-3 Mini 3.8B Q4)
  • Document model storage locations
  • Test model loading on both GPUs

• Security Setup

  • Generate authentication tokens
  • Define path whitelists
  • Plan network isolation approach
  • Set up firewall rules (if using)

Pre-Implementation Setup

• Repository Setup

  • Create family-agent-config/ repository (if not exists)
  • Set up directory structure:
    • family-agent-config/prompts/
    • family-agent-config/secrets/
    • family-agent-config/tools/
    • family-agent-config/tasks/home/
  • Initialize git repository
  • Set up .gitignore for secrets

• Development Environment

  • Set up Python virtual environments
  • Install development dependencies
  • Configure IDE/editor
  • Set up testing framework

• Documentation

  • Document all configuration decisions
  • Create setup guide for new hardware
  • Document API key storage procedures
  • Create runbook for common operations

MCP Safety & Strength Analysis

How Strong Can We Make the MCP?

Current MCP Capabilities (Planned)

Core Tools (Milestone 2):

• ✅ Weather lookup (external API - documented exception)
• ✅ Time/date queries
• ✅ Timers and reminders
• ✅ Home tasks (Kanban board)

Advanced Tools (Future):

• Notes and file management
• Email integration (with confirmations)
• Calendar integration (with confirmations)
• Smart home control (with confirmations)

Strength Limitations

Technical Limitations:

1. Model Capabilities: Limited by LLM model size and quality
   • Work Agent (Llama 3.1 70B Q4): Strong reasoning, good tool use
   • Family Agent (Phi-3 Mini 3.8B Q4): Good instruction following, smaller context
2. Tool Complexity: Tools must be deterministic and well-defined
3. Context Window: Limited by model context size (8K-16K tokens)
4. Latency: Tool calls add latency to responses

Safety Limitations:

1. Path Whitelists: Tools can only access whitelisted directories
2. Network Isolation: External network access blocked by default
3. Confirmation Flows: High-risk actions require explicit user approval
4. Boundary Enforcement: Strict separation between work and family agents

How to Maximize MCP Strength

1. Tool Design Best Practices:

• ✅ Clear, well-defined tool schemas
• ✅ Comprehensive error handling
• ✅ Input validation and sanitization
• ✅ Rate limiting for external APIs
• ✅ Caching for frequently accessed data
• ✅ Batch operations where possible

2. LLM Integration:

• ✅ Clear system prompts with tool descriptions
• ✅ Function calling format (OpenAI-compatible)
• ✅ Tool result formatting for LLM consumption
• ✅ Error message handling
• ✅ Multi-step tool orchestration support

3. Performance Optimization:

• ✅ Parallel tool execution where possible
• ✅ Tool result caching
• ✅ Streaming responses for long operations
• ✅ Timeout handling
• ✅ Retry logic for transient failures

4. Safety Enhancements:

• ✅ Path whitelist enforcement at tool level
• ✅ Permission checks before tool execution
• ✅ Audit logging for all tool calls
• ✅ Confirmation token system for high-risk actions
• ✅ Network isolation (containers/firewall)
• ✅ Static analysis in CI/CD

How Safe Can We Make the MCP?

Current Safety Measures (Planned)

1. Path Whitelists:

• ✅ Tools can only access explicitly whitelisted directories
• ✅ Family agent: Only family-agent-config/ paths
• ✅ Work agent: Only work-related paths
• ✅ Enforced at tool execution time

2. Network Isolation:

• ✅ External network access blocked by default
• ✅ Only approved tools can make external requests (weather API)
• ✅ Local network access restricted
• ✅ Firewall rules prevent cross-access

3. Confirmation Flows:

• ✅ High-risk actions require explicit user confirmation
• ✅ Confirmation tokens (signed, not just LLM intent)
• ✅ User must approve via client (not just model decision)
• ✅ Audit logging for all confirmations

4. Boundary Enforcement:

• ✅ Separate repositories (family-agent-config vs work)
• ✅ Separate credentials and tokens
• ✅ Network-level separation (containers, firewall)
• ✅ Static analysis checks in CI/CD

5. Authentication & Authorization:

• ✅ Token-based authentication
• ✅ Separate tokens for work vs family agents
• ✅ Token revocation capability
• ✅ Admin controls and kill switches

Additional Safety Measures (Recommended)

1. Sandboxing:

• Option A: Docker containers for each tool
  • Pros: Strong isolation, easy cleanup
  • Cons: Overhead, complexity
• Option B: Systemd-nspawn containers
  • Pros: Lightweight, good isolation
  • Cons: Linux-specific
• Option C: Python sandboxing (restricted execution)
  • Pros: Simple, no extra infrastructure
  • Cons: Weaker isolation

2. Resource Limits:

• CPU time limits per tool call
• Memory limits per tool execution
• Disk I/O limits
• Network bandwidth limits

3. Input Validation:

• Schema validation for all tool inputs
• Sanitization of user-provided data
• SQL injection prevention (if using databases)
• Path traversal prevention
• Command injection prevention

4. Monitoring & Alerting:

• Real-time monitoring of tool calls
• Anomaly detection (unusual patterns)
• Alert on security violations
• Audit log analysis

5. Rate Limiting:

• Per-tool rate limits
• Per-user rate limits
• Per-IP rate limits
• Global rate limits

6. Backup & Recovery:

• Regular backups of critical data
• Point-in-time recovery capability
• Disaster recovery plan
• Data integrity checks

Safety Rating Assessment

Current Safety Level: HIGH ✅

Strengths:

• ✅ Strict path whitelists
• ✅ Network isolation
• ✅ Confirmation flows for high-risk actions
• ✅ Boundary enforcement (work vs family)
• ✅ Audit logging

Areas for Enhancement:

• ⚠️ Sandboxing (currently relies on path whitelists)
• ⚠️ Resource limits (currently unlimited)
• ⚠️ Advanced monitoring (basic logging planned)
• ⚠️ Automated security scanning

Recommended Safety Enhancements:

1. Priority 1: Implement sandboxing (Docker or systemd-nspawn)
2. Priority 2: Add resource limits (CPU, memory, disk)
3. Priority 3: Enhanced monitoring and alerting
4. Priority 4: Automated security scanning in CI/CD

Dependencies

• TICKET-047 (Hardware & Purchases) - Hardware planning complete
• TICKET-003 (Privacy & Safety Constraints) - Safety requirements defined
• TICKET-004 (High-Level Architecture) - Architecture defined
• TICKET-028 (MCP Foundation) - MCP concepts documented

Related Files

• docs/HARDWARE.md - Hardware requirements
• docs/SAFETY_CONSTRAINTS.md - Safety requirements
• docs/MCP_ARCHITECTURE.md - MCP architecture
• ARCHITECTURE.md - System architecture
• tickets/done/TICKET-047_hardware-purchases.md - Purchase plan

Notes

Critical Path Items:

1. Hardware purchases (always-on node, microphones) - Blocks wake-word and ASR work
2. Weather API key - Blocks weather tool implementation
3. LLM server software selection - Blocks LLM server setup
4. Network configuration - Blocks service deployment

Non-Critical (Can Proceed Without):

• Storage (can use existing)
• UPS (can add later)
• Dashboard display (optional)
• Advanced safety features (can add incrementally)

Recommendation:

• Start with MVP essentials (hardware + API key)
• Proceed with implementation using defaults where possible
• Enhance safety and add optional features incrementally

Progress Log

• 2024-01-XX - Ticket created with comprehensive requirements checklist
• 2024-01-XX - MCP safety and strength analysis completed
• 2024-01-XX - Purchase list consolidated from HARDWARE.md
• 2024-01-XX - Action items organized by priority

---

Next Steps:

1. Review this ticket and fill in all information sections
2. Make hardware purchase decisions
3. Obtain API keys and credentials
4. Complete system configuration details
5. Mark items as complete as you gather information
6. Once critical items are complete, proceed with TICKET-021 (4080 LLM Server) and TICKET-022 (1050 LLM Server)