jesus/Vapora
1
0
Fork 0
Code Issues Pull Requests Actions 3 Packages Projects Releases Wiki Activity
Vapora/docs/getting-started.md
Jesús Pérez d14150da75 feat: Phase 5.3 - Multi-Agent Learning Infrastructure 
Implement intelligent agent learning from Knowledge Graph execution history
with per-task-type expertise tracking, recency bias, and learning curves.

## Phase 5.3 Implementation

### Learning Infrastructure (✅ Complete)
- LearningProfileService with per-task-type expertise metrics
- TaskTypeExpertise model tracking success_rate, confidence, learning curves
- Recency bias weighting: recent 7 days weighted 3x higher (exponential decay)
- Confidence scoring prevents overfitting: min(1.0, executions / 20)
- Learning curves computed from daily execution windows

### Agent Scoring Service (✅ Complete)
- Unified AgentScore combining SwarmCoordinator + learning profiles
- Scoring formula: 0.3*base + 0.5*expertise + 0.2*confidence
- Rank agents by combined score for intelligent assignment
- Support for recency-biased scoring (recent_success_rate)
- Methods: rank_agents, select_best, rank_agents_with_recency

### KG Integration (✅ Complete)
- KGPersistence::get_executions_for_task_type() - query by agent + task type
- KGPersistence::get_agent_executions() - all executions for agent
- Coordinator::load_learning_profile_from_kg() - core KG→Learning integration
- Coordinator::load_all_learning_profiles() - batch load for multiple agents
- Convert PersistedExecution → ExecutionData for learning calculations

### Agent Assignment Integration (✅ Complete)
- AgentCoordinator uses learning profiles for task assignment
- extract_task_type() infers task type from title/description
- assign_task() scores candidates using AgentScoringService
- Fallback to load-based selection if no learning data available
- Learning profiles stored in coordinator.learning_profiles RwLock

### Profile Adapter Enhancements (✅ Complete)
- create_learning_profile() - initialize empty profiles
- add_task_type_expertise() - set task-type expertise
- update_profile_with_learning() - update swarm profiles from learning

## Files Modified

### vapora-knowledge-graph/src/persistence.rs (+30 lines)
- get_executions_for_task_type(agent_id, task_type, limit)
- get_agent_executions(agent_id, limit)

### vapora-agents/src/coordinator.rs (+100 lines)
- load_learning_profile_from_kg() - core KG integration method
- load_all_learning_profiles() - batch loading for agents
- assign_task() already uses learning-based scoring via AgentScoringService

### Existing Complete Implementation
- vapora-knowledge-graph/src/learning.rs - calculation functions
- vapora-agents/src/learning_profile.rs - data structures and expertise
- vapora-agents/src/scoring.rs - unified scoring service
- vapora-agents/src/profile_adapter.rs - adapter methods

## Tests Passing
- learning_profile: 7 tests ✅
- scoring: 5 tests ✅
- profile_adapter: 6 tests ✅
- coordinator: learning-specific tests ✅

## Data Flow
1. Task arrives → AgentCoordinator::assign_task()
2. Extract task_type from description
3. Query KG for task-type executions (load_learning_profile_from_kg)
4. Calculate expertise with recency bias
5. Score candidates (SwarmCoordinator + learning)
6. Assign to top-scored agent
7. Execution result → KG → Update learning profiles

## Key Design Decisions
✅ Recency bias: 7-day half-life with 3x weight for recent performance
✅ Confidence scoring: min(1.0, total_executions / 20) prevents overfitting
✅ Hierarchical scoring: 30% base load, 50% expertise, 20% confidence
✅ KG query limit: 100 recent executions per task-type for performance
✅ Async loading: load_learning_profile_from_kg supports concurrent loads

## Next: Phase 5.4 - Cost Optimization
Ready to implement budget enforcement and cost-aware provider selection.
2026-01-11 13:03:53 +00:00

14 KiB
Raw Blame History

title, date, status, version, type
title date status version type
Vapora - START HERE 2025-11-10 READY 1.0 entry-point

🌊 Vapora - START HERE

Welcome to Vapora! This is your entry point to the intelligent development orchestration platform.

Choose your path below based on what you want to do:

⚡ I Want to Get Started NOW (15 minutes)

👉 Read: QUICKSTART.md

This is the fastest way to get up and running:

  • Prerequisites check (2 min)
  • Build complete project (5 min)
  • Run backend & frontend (3 min)
  • Verify everything works (2 min)
  • Create first tracking entry (3 min)

Then: Try using the tracking system: /log-change, /add-todo, /track-status

🛠️ I Want Complete Setup Instructions

👉 Read: SETUP.md

Complete step-by-step guide covering:

  • Prerequisites verification & installation
  • Workspace configuration (3 options)
  • Building all 8 crates
  • Running full test suite
  • IDE setup (VS Code, CLion)
  • Development workflow
  • Troubleshooting guide

Time: 30-45 minutes for complete setup with configuration

🚀 I Want to Understand the Project

👉 Read: README.md

Project overview covering:

  • What is Vapora (intelligent development orchestration)
  • Key features (agents, LLM routing, tracking, K8s, RAG)
  • Architecture overview
  • Technology stack
  • Getting started links
  • Contributing guidelines

Time: 15-20 minutes to understand the vision

📚 I Want Deep Technical Understanding

👉 Read: .coder/TRACKING_DOCUMENTATION_INDEX.md

Master documentation index covering:

  • All documentation files (8+ docs)
  • Reading paths by role (PM, Dev, DevOps, Architect, User)
  • Complete architecture and design decisions
  • API reference and integration details
  • Performance characteristics
  • Troubleshooting strategies

Time: 1-2 hours for comprehensive understanding

🎯 Quick Navigation by Role

Role Start with Then read Time
New Developer QUICKSTART.md SETUP.md 45 min
Backend Dev SETUP.md crates/vapora-backend/ 1 hour
Frontend Dev SETUP.md crates/vapora-frontend/ 1 hour
DevOps / Ops SETUP.md INTEGRATION.md 1 hour
Project Lead README.md .coder/ docs 2 hours
Architect .coder/TRACKING_DOCUMENTATION_INDEX.md All docs 2+ hours
Tracking System User QUICKSTART_TRACKING.md SETUP_TRACKING.md 30 min

📋 Projects and Components

Main Components

Vapora is built from 8 integrated crates:

Crate Purpose Status
vapora-shared Shared types, utilities, errors ✅ Core
vapora-agents Agent orchestration framework ✅ Complete
vapora-llm-router Multi-LLM routing (Claude, GPT, Gemini, Ollama) ✅ Complete
vapora-tracking Change & TODO tracking system (NEW) ✅ Production
vapora-backend REST API server (Axum) ✅ Complete
vapora-frontend Web UI (Leptos + WASM) ✅ Complete
vapora-mcp-server MCP protocol support ✅ Complete
vapora-doc-lifecycle Document lifecycle management ✅ Complete

System Architecture

┌─────────────────────────────────────────────────┐
│           Vapora Platform (You are here)        │
├─────────────────────────────────────────────────┤
│                                                 │
│  Frontend (Leptos WASM)                         │
│  └─ http://localhost:8080                       │
│                                                 │
│  Backend (Axum REST API)                        │
│  └─ http://localhost:3000/api/v1/*              │
│                                                 │
│  ┌─────────────────────────────────────────┐   │
│  │  Core Services                          │   │
│  │  • Tracking System (vapora-tracking)    │   │
│  │  • Agent Orchestration (vapora-agents)  │   │
│  │  • LLM Router (vapora-llm-router)       │   │
│  │  • Document Lifecycle Manager           │   │
│  └─────────────────────────────────────────┘   │
│                                                 │
│  ┌─────────────────────────────────────────┐   │
│  │  Infrastructure                         │   │
│  │  • SQLite Database (local dev)          │   │
│  │  • SurrealDB (production)               │   │
│  │  • NATS JetStream (messaging)           │   │
│  │  • Kubernetes Ready                     │   │
│  └─────────────────────────────────────────┘   │
│                                                 │
└─────────────────────────────────────────────────┘

🚀 Quick Start Options

Option 1: 15-Minute Build & Run

# Build entire project
cargo build

# Run backend (Terminal 1)
cargo run -p vapora-backend

# Run frontend (Terminal 2, optional)
cd crates/vapora-frontend && trunk serve

# Visit http://localhost:3000 and http://localhost:8080

Option 2: Test Everything First

# Build
cargo build

# Run all tests
cargo test --lib

# Check code quality
cargo clippy --all -- -W clippy::all

# Format code
cargo fmt

# Then run: cargo run -p vapora-backend

Option 3: Step-by-Step Complete Setup

See SETUP.md for:

  • Detailed prerequisites
  • Configuration options
  • IDE setup
  • Development workflow
  • Comprehensive troubleshooting

📖 Documentation Structure

In Vapora Root

File Purpose Time
START_HERE.md This file - entry point 5 min
QUICKSTART.md 15-minute full project setup 15 min
SETUP.md Complete setup guide 30 min
README.md Project overview & features 15 min

In .coder/ (Project Analysis)

File Purpose Time
TRACKING_SYSTEM_STATUS.md Implementation status & API reference 30 min
TRACKING_DOCUMENTATION_INDEX.md Master navigation guide 15 min
OPTIMIZATION_SUMMARY.md Code improvements & architecture 20 min

In Crate Directories

Crate README Integration Other
vapora-tracking Feature overview Full guide Benchmarks
vapora-backend API reference Deployment Tests
vapora-frontend Component docs WASM build Examples
vapora-shared Type definitions Utilities Tests
vapora-agents Framework Examples Agents
vapora-llm-router Router logic Config Examples

Tools Directory (~/.Tools/.coder/)

File Purpose Language
BITACORA_TRACKING_DONE.md Implementation summary Spanish

✨ Key Features at a Glance

🎯 Project Management

  • Kanban board (Todo → Doing → Review → Done)
  • Change tracking with impact analysis
  • TODO system with priority & estimation
  • Real-time collaboration

🤖 AI Agent Orchestration

  • 12+ specialized agents (Architect, Developer, Reviewer, Tester, etc.)
  • Parallel pipeline execution with approval gates
  • Multi-LLM routing (Claude, OpenAI, Gemini, Ollama)
  • Customizable & extensible agent system

🧠 Intelligent Routing

  • Automatic LLM selection per task
  • Manual override capability
  • Fallback chains
  • Cost tracking & budget alerts

📚 Knowledge Management

  • RAG integration for semantic search
  • Document lifecycle management
  • Team decisions & docs discoverable
  • Code & guide integration

☁️ Infrastructure Ready

  • Kubernetes native (K3s, RKE2, vanilla)
  • Istio service mesh
  • Self-hosted (no SaaS)
  • Horizontal scaling

🎬 What You Can Do After Getting Started

✅ Build & Run

  • Build complete project: cargo build
  • Run backend: cargo run -p vapora-backend
  • Run frontend: trunk serve (in frontend dir)
  • Run tests: cargo test --lib

✅ Use Tracking System

  • Log changes: /log-change "description" --impact backend
  • Create TODOs: /add-todo "task" --priority H --estimate M
  • Check status: /track-status --limit 10
  • Export reports: ./scripts/export-tracking.nu json

✅ Use Agent Framework

  • Orchestrate AI agents for tasks
  • Multi-LLM routing for optimal model selection
  • Pipeline execution with approval gates

✅ Integrate & Extend

  • Add custom agents
  • Integrate with external services
  • Deploy to Kubernetes
  • Customize LLM routing

✅ Develop & Contribute

  • Understand codebase architecture
  • Modify agents and services
  • Add new features
  • Submit pull requests

🛠️ System Requirements

Minimum:

  • macOS 10.15+ / Linux / Windows
  • Rust 1.75+
  • 4GB RAM
  • 2GB disk space
  • Internet connection

Recommended:

  • macOS 12+ (M1/M2) / Linux
  • Rust 1.75+
  • 8GB+ RAM
  • 5GB+ disk space
  • NuShell 0.95+ (for scripts)

📚 Learning Paths

Path 1: Quick User (30 minutes)

  1. Read: QUICKSTART.md (15 min)
  2. Build: cargo build (8 min)
  3. Run: Backend & frontend (5 min)
  4. Try: /log-change, /track-status (2 min)

Path 2: Developer (2 hours)

  1. Read: README.md (15 min)
  2. Read: SETUP.md (30 min)
  3. Setup: Development environment (20 min)
  4. Build: Full project (5 min)
  5. Explore: Crate documentation (30 min)
  6. Code: Try modifying something (20 min)

Path 3: Architect (3+ hours)

  1. Read: README.md (15 min)
  2. Read: .coder/TRACKING_DOCUMENTATION_INDEX.md (30 min)
  3. Deep dive: All architecture docs (1+ hour)
  4. Review: Source code (1+ hour)
  5. Plan: Extensions and modifications

Path 4: Tracking System Focus (1 hour)

  1. Read: QUICKSTART_TRACKING.md (15 min)
  2. Build: cargo build -p vapora-tracking (5 min)
  3. Setup: Tracking system (10 min)
  4. Explore: Tracking features (20 min)
  5. Try: /log-change, /track-status, exports (10 min)

🔗 Quick Links

Getting Started

Documentation

Code & Architecture

Project Management

🆘 Quick Help

"I'm stuck on installation"

→ See SETUP.md Troubleshooting

"I don't know how to use the tracking system"

→ See QUICKSTART_TRACKING.md Usage

"I need to understand the architecture"

→ See .coder/TRACKING_DOCUMENTATION_INDEX.md

"I want to deploy to production"

→ See INTEGRATION.md Deployment

"I'm not sure where to start"

→ Choose your role from the table above and follow the reading path

🎯 Next Steps

Choose one:

1. Fast Track (15 minutes)

# Read and follow
# QUICKSTART.md

# Expected outcome: Project running, first tracking entry created

2. Complete Setup (45 minutes)

# Read and follow:
# SETUP.md (complete with configuration and IDE setup)

# Expected outcome: Full development environment ready

3. Understanding First (1-2 hours)

# Read in order:
# 1. README.md (project overview)
# 2. .coder/TRACKING_DOCUMENTATION_INDEX.md (architecture)
# 3. SETUP.md (setup with full understanding)

# Expected outcome: Deep understanding of system design

4. Tracking System Only (30 minutes)

# Read and follow:
# QUICKSTART_TRACKING.md

# Expected outcome: Tracking system running and in use

✅ Installation Checklist

Before you start:

  • Rust 1.75+ installed
  • Cargo available
  • Git installed
  • 2GB+ disk space available
  • Internet connection working

After quick start:

  • cargo build succeeds
  • cargo test --lib passes
  • Backend runs on port 3000
  • Frontend loads on port 8080 (optional)
  • Can create tracking entries
  • Code formats correctly

All checked? ✅ You're ready to develop with Vapora!

💡 Pro Tips

  • Start simple: Begin with QUICKSTART.md, expand later
  • Use the docs: Every crate has README.md with examples
  • Check status: Run /track-status frequently
  • IDE matters: Set up VS Code or CLion properly
  • Ask questions: Check documentation first, then ask the community
  • Contribute: Once comfortable, consider contributing improvements

🌟 Welcome to Vapora!

You're about to join a platform that's changing how development teams work together. Whether you're here to build, contribute, or just explore, you've come to the right place.

Choose your starting point above and begin your Vapora journey! 🚀

Quick decision guide:

  • ⏱️ Have 15 min? → QUICKSTART.md
  • ⏱️ Have 45 min? → SETUP.md
  • ⏱️ Have 2 hours? → README.md + Deep dive
  • ⏱️ Just tracking? → QUICKSTART_TRACKING.md

Last updated: 2025-11-10 | Status: ✅ Production Ready | Version: 1.0