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

480 lines
14 KiB
Markdown
Raw Blame History

---
title: Vapora - START HERE
date: 2025-11-10
status: READY
version: 1.0
type: 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`](./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`](./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`](./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`](./.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
```bash
# 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
```bash
# 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`](./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
- [QUICKSTART.md](./QUICKSTART.md) - 15-minute setup
- [SETUP.md](./SETUP.md) - Complete setup guide
- [README.md](./README.md) - Project overview
### Documentation
- [QUICKSTART_TRACKING.md](./QUICKSTART_TRACKING.md) - Tracking system quick start
- [SETUP_TRACKING.md](./SETUP_TRACKING.md) - Tracking system detailed setup
- [.coder/TRACKING_DOCUMENTATION_INDEX.md](./.coder/TRACKING_DOCUMENTATION_INDEX.md) - Master guide
### Code & Architecture
- [Source code](./crates/) - Implementation
- [API endpoints](./crates/vapora-backend/README.md) - REST API
- [Tracking system](./crates/vapora-tracking/README.md) - Tracking crate
- [Integration guide](./crates/vapora-tracking/INTEGRATION.md) - System integration
### Project Management
- [Roadmap](./README.md#-roadmap) - Future features
- [Contributing](./README.md#-contributing) - How to contribute
- [Issues](https://github.com/vapora/vapora/issues) - Bug reports & features
---
## 🆘 Quick Help
### "I'm stuck on installation"
→ See [SETUP.md Troubleshooting](./SETUP.md#troubleshooting)
### "I don't know how to use the tracking system"
→ See [QUICKSTART_TRACKING.md Usage](./QUICKSTART_TRACKING.md#-first-time-usage)
### "I need to understand the architecture"
→ See [.coder/TRACKING_DOCUMENTATION_INDEX.md](./CODER/TRACKING_DOCUMENTATION_INDEX.md)
### "I want to deploy to production"
→ See [INTEGRATION.md Deployment](./crates/vapora-tracking/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)
```bash
# Read and follow
# QUICKSTART.md
# Expected outcome: Project running, first tracking entry created
```
### 2. Complete Setup (45 minutes)
```bash
# Read and follow:
# SETUP.md (complete with configuration and IDE setup)
# Expected outcome: Full development environment ready
```
### 3. Understanding First (1-2 hours)
```bash
# 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)
```bash
# 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
Reference in New Issue View Git Blame Copy Permalink