Onboarding Agent: conversational persona interview and smart install recommendations

[kovtcharov]

Summary

Build a first-class GAIA agent that conducts the first-run experience: scans the system, interviews the user about their goals and persona, cross-references against the agent capability registry, and generates an optimized install plan. This agent is itself registered via manifest and can be re-invoked anytime via `gaia setup`.

Design

Interview Flow

1. Welcome + permission to scan system
   "Welcome to GAIA! Can I scan your system to find the best setup for you?"
   [Yes] → run SystemScanner    [Skip] → manual selection

2. System scan results (2-3 seconds)
   "Here's what I found:"
   ✅ Windows 11, 32GB RAM, 120GB free disk
   ✅ AMD Ryzen 9 with NPU
   ✅ Docker installed and running
   ✅ Git available
   ✅ Jira credentials configured
   ❌ Blender not installed
   ❌ Node.js not installed

3. Use case selection (multi-select)
   "What would you like to use GAIA for?"
   □ Chat with documents / Research assistant
   □ Write and edit code
   □ Voice assistant
   □ 3D automation (Blender)
   □ Project management (Jira)
   □ Container management (Docker)
   □ Image generation
   □ Browse the web for me
   □ Control my desktop
   □ I'm just exploring

4. Technical level (determines verbosity and defaults)
   "What's your experience level?"
   ○ Beginner — guide me through everything
   ○ Intermediate — standard setup
   ○ Advanced — show me all options

5. Context-dependent follow-ups (based on scan + selections)
   "I see Docker is running — enable the Docker agent? (1.2GB additional)"
   "Jira credentials found — set up Jira integration? (no additional download)"
   "You have an AMD NPU — enable hardware acceleration?"

6. Install plan confirmation
   "Here's my recommendation:"
   
   ┌─────────────────────────────────────────────┐
   │ Install Plan                                │
   │                                             │
   │ Agents: Chat, Code, Docker, Jira            │
   │ Models: Qwen3-Coder-30B (18GB)              │
   │         nomic-embed (0.5GB)                  │
   │         Qwen3-VL-4B (3GB)                   │
   │ Extras: rag, mcp                            │
   │                                             │
   │ Total download: ~21.5 GB                    │
   │ Estimated time: ~12 minutes                 │
   │ Disk after install: 98.5 GB free            │
   └─────────────────────────────────────────────┘
   
   [Install] [Customize] [Cancel]

Persona → Agent Mapping

PERSONA_AGENTS = {
    "documents":  ["chat"],           # RAG-powered Q&A
    "code":       ["code"],           # Code generation
    "voice":      ["chat"],           # Chat + talk extras
    "3d":         ["blender"],        # Blender automation
    "jira":       ["jira"],           # Jira management
    "docker":     ["docker"],         # Container management
    "images":     ["sd"],             # Stable Diffusion
    "browser":    ["chat"],           # Chat + browser tools
    "desktop":    ["chat"],           # Chat + CUA tools
    "exploring":  ["chat"],           # Start with chat
}

# System-aware additions:
# Docker installed → auto-suggest docker agent
# Jira env vars set → auto-suggest jira agent
# Blender found → auto-suggest blender agent
# NPU detected → suggest larger models

Smart Model Deduplication

Multiple agents share models. The recommendation engine deduplicates:

• ChatAgent needs: Qwen3-Coder-30B + nomic-embed + Qwen3-VL-4B
• CodeAgent needs: Qwen3-Coder-30B
• JiraAgent needs: Qwen3-Coder-30B
• Total: Just Qwen3-Coder-30B + nomic-embed + Qwen3-VL-4B (not 3× Qwen3-Coder)

UserProfile Output

@dataclass
class UserProfile:
    use_cases: List[str]
    technical_level: str          # beginner, intermediate, advanced
    selected_agents: List[str]
    scan_permitted: bool
    system_profile: Optional[SystemProfile]
    install_plan: InstallPlan
    
    def save(self, path: str = "~/.gaia/user_profile.json"): ...
    
    @classmethod
    def load(cls, path: str = "~/.gaia/user_profile.json"): ...

Implementation Notes

• Pre-LLM operation: The interview must work BEFORE any models are downloaded. Use structured prompts (multiple choice), not free-form LLM conversation.
• Post-LLM enhancement: Once a model is available, offer richer interaction.
• CLI mode: Rich console with colored panels, progress indicators
• Chat UI mode: Send structured data to frontend for card-based selection (Issue NPU Linux support #9)
• Idempotent: Running `gaia setup` again should detect existing state and offer to modify

Files to Create

• `src/gaia/agents/onboarding/agent.py` (NEW, ~600 lines)
• `src/gaia/agents/onboarding/agent.yml` (NEW) — manifest for the onboarding agent itself
• `src/gaia/agents/onboarding/interview.py` (NEW, ~300 lines) — persona interview logic
• `src/gaia/agents/onboarding/recommendations.py` (NEW, ~200 lines) — plan generation
• `tests/unit/agents/test_onboarding.py` (NEW)

Acceptance Criteria

• Works without any models installed (structured prompts, not LLM)
• System scan produces accurate SystemProfile
• Persona interview identifies correct agents for each use case
• Install plan deduplicates shared models
• Plan shows accurate disk/time estimates
• User can customize plan before execution
• UserProfile saved and loadable for re-runs
• CLI and headless modes both work
• Unit tests for persona mapping and plan generation

Depends On

• Issue Update installer and workflows/actions for CI/CD #1 (Manifest), Use public Lemonade hybrid installer #2 (Registry), Documentation update from v0.7.2 tag. #4 (Lifecycle), Update Documentation #5 (System Scanner)

Enables

• Issue Installer Fails on Some Systems #7 (Executor), v0.7.4 #8 (First-Run Detection), NPU Linux support #9 (UI Wizard)

[kovtcharov]

Update: MCP server auto-installation is now tracked in #474. The onboarding agent's recommendation engine should include MCP servers alongside agents — e.g., 'Docker detected → recommend Docker agent + Docker MCP server'.