jesus/Vapora
1
0
Fork 0
Code Issues Pull Requests Actions 3 Packages Projects Releases Wiki Activity
Vapora/CHANGELOG.md
Jesús Pérez 4cbbf3f864
Some checks failed
Rust CI / Security Audit (push) Has been cancelled
Details
Rust CI / Check + Test + Lint (nightly) (push) Has been cancelled
Details
Rust CI / Check + Test + Lint (stable) (push) Has been cancelled
Details
chore: add setup md files
2026-01-12 03:17:04 +00:00

13 KiB
Raw Blame History

Changelog

All notable changes to VAPORA will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

Unreleased

Added

  • Comprehensive Examples System: 26+ executable examples demonstrating all VAPORA capabilities

    • Basic Examples (6): Foundation for each core crate
      • crates/vapora-agents/examples/01-simple-agent.rs - Agent registry & metadata
      • crates/vapora-llm-router/examples/01-provider-selection.rs - Multi-provider routing
      • crates/vapora-swarm/examples/01-agent-registration.rs - Swarm coordination basics
      • crates/vapora-knowledge-graph/examples/01-execution-tracking.rs - Temporal KG persistence
      • crates/vapora-backend/examples/01-health-check.rs - Backend verification
      • crates/vapora-shared/examples/01-error-handling.rs - Error type patterns
    • Intermediate Examples (9): System integration scenarios
      • Learning profiles with recency bias weighting
      • Budget enforcement with 3-tier fallback strategy
      • Cost tracking and ROI analysis per provider/task type
      • Swarm load distribution and capability-based filtering
      • Knowledge graph learning curves and similarity search
      • Full-stack agent + routing integration
      • Multi-agent swarm with expertise-based assignment
    • Advanced Examples (2): Complete end-to-end workflows
      • Full system integration (API → Swarm → Agents → Router → KG)
      • REST API integration with real-time WebSocket updates
    • Real-World Use Cases (3): Production scenarios with business value
      • Code review workflow: 3-stage pipeline with cost optimization ($488/month savings)
      • Documentation generation: Automated sync with quality checks ($989/month savings)
      • Issue triage: Intelligent classification with selective escalation ($997/month savings)
    • Interactive Notebooks (4): Marimo-based exploration
      • Agent basics with role configuration
      • Budget playground with cost projections
      • Learning curves visualization with confidence intervals
      • Cost analysis with provider comparison charts

  • Examples Documentation: 600+ line comprehensive guide

    • docs/examples-guide.md - Master reference for all examples
    • Example-by-example breakdown with learning objectives and run instructions
    • Three learning paths: Quick Overview (30min), System Integration (90min), Production Ready (2-3hrs)
    • Common tasks mapped to relevant examples
    • Business value analysis for real-world scenarios
    • Troubleshooting section and quick reference commands

  • Examples Organization:

    • Per-crate examples following crates/*/examples/ Cargo convention
    • Root-level examples in examples/full-stack/ and examples/real-world/
    • Master README catalog at examples/README.md with navigation
    • Python requirements for Marimo notebooks: examples/notebooks/requirements.txt

  • Web Assets Optimization: Restructured landing page with minification pipeline

    • Separated source (assets/web/src/index.html) from minified production version
    • Automated minification script (assets/web/minify.sh) for version synchronization
    • 32% compression achieved (26KB → 18KB)
    • Bilingual content (English/Spanish) preserved with localStorage persistence
    • Complete documentation in assets/web/README.md

  • Infrastructure & Build System

    • Just recipes for CI/CD automation (50+ recipes organized by category)
    • Parametrized help system for command discovery
    • Integration with development workflows

Changed

  • Code Quality Improvements

    • Removed unused imports from API and workflow modules (5+ files)
    • Fixed 6 unnecessary mut keyword warnings in provider analytics
    • Improved code patterns: converted verbose match to matches! macro (workflow/state.rs)
    • Applied automatic clippy fixes for idiomatic Rust

  • Documentation & Linting

    • Fixed markdown linting compliance in assets/web/README.md
    • Proper code fence language specifications (MD040)
    • Blank lines around code blocks (MD031)
    • Table formatting with compact style (MD060)

Fixed

  • Compilation & Testing
    • Eliminated all unused import warnings in vapora-backend
    • Suppressed architectural dead code with appropriate attributes
    • All 55 tests passing in vapora-backend
    • 0 compilation errors, clean build output

Technical Details

  • Architecture: Refactored unused imports from workflow and API modules

    • Tests moved to test-only scope for AgentConfig/RegistryConfig types
    • Intentional suppression for components not yet integrated
    • Future-proof markers for architectural patterns

  • Build Status: Clean compilation pipeline

    • cargo build -p vapora-backend ✅
    • cargo clippy -p vapora-backend ✅ (5 nesting suggestions only)
    • cargo test -p vapora-backend ✅ (55/55 passing)

1.2.0 - 2026-01-11

Added - Phase 5.3: Multi-Agent Learning

  • Learning Profiles: Per-task-type expertise tracking for each agent

    • LearningProfile struct with task-type expertise mapping
    • Success rate calculation with recency bias (7-day window weighted 3x)
    • Confidence scoring based on execution count (prevents small-sample overfitting)
    • Learning curve computation with exponential decay

  • Agent Scoring Service: Unified agent selection combining swarm metrics + learning

    • Formula: final_score = 0.3*base + 0.5*expertise + 0.2*confidence
    • Base score from SwarmCoordinator (load balancing)
    • Expertise score from learning profiles (historical success)
    • Confidence weighting dampens low-execution-count agents

  • Knowledge Graph Integration: Learning curve calculator

    • calculate_learning_curve() with time-series expertise evolution
    • apply_recency_bias() with exponential weighting formula
    • Aggregate by time windows (daily/weekly) for trend analysis

  • Coordinator Enhancement: Learning-based agent selection

    • Extract task type from description/role
    • Query learning profiles for task-specific expertise
    • Replace simple load balancing with learning-aware scoring
    • Background profile synchronization (30s interval)

Added - Phase 5.4: Cost Optimization

  • Budget Manager: Per-role cost enforcement

    • BudgetConfig with TOML serialization/deserialization
    • Role-specific monthly and weekly limits (in cents)
    • Automatic fallback provider when budget exceeded
    • Alert thresholds (default 80% utilization)
    • Weekly/monthly automatic resets

  • Configuration Loading: Graceful budget initialization

    • BudgetConfig::load() with strict validation
    • BudgetConfig::load_or_default() with fallback to empty config
    • Environment variable override: BUDGET_CONFIG_PATH
    • Validation: limits > 0, thresholds in [0.0, 1.0]

  • Cost-Aware Routing: Provider selection with budget constraints

    • Three-tier enforcement:
      1. Budget exceeded → force fallback provider
      2. Near threshold (>80%) → prefer cost-efficient providers
      3. Normal → rule-based routing with cost as tiebreaker
    • Cost efficiency ranking: (quality * 100) / (cost + 1)
    • Fallback chain ordering by cost (Ollama → Gemini → OpenAI → Claude)

  • Prometheus Metrics: Real-time cost and budget monitoring

    • vapora_llm_budget_remaining_cents{role} - Monthly budget remaining
    • vapora_llm_budget_utilization{role} - Budget usage fraction (0.0-1.0)
    • vapora_llm_fallback_triggered_total{role,reason} - Fallback event counter
    • vapora_llm_cost_per_provider_cents{provider} - Cumulative cost per provider
    • vapora_llm_tokens_per_provider{provider,type} - Token usage tracking

  • Grafana Dashboards: Visual monitoring

    • Budget utilization gauge (color thresholds: 70%, 90%, 100%)
    • Cost distribution pie chart (percentage per provider)
    • Fallback trigger time series (rate of fallback activations)
    • Agent assignment latency histogram (P50, P95, P99)

  • Alert Rules: Prometheus alerting

    • BudgetThresholdExceeded: Utilization > 80% for 5 minutes
    • HighFallbackRate: Rate > 0.1 for 10 minutes
    • CostAnomaly: Cost spike > 2x historical average
    • LearningProfilesInactive: No updates for 5 minutes

Added - Integration & Testing

  • End-to-End Integration Tests: Validate learning + budget interaction

    • test_end_to_end_learning_with_budget_enforcement() - Full system test
    • test_learning_selection_with_budget_constraints() - Budget pressure scenarios
    • test_learning_profile_improvement_with_budget_tracking() - Learning evolution

  • Agent Server Integration: Budget initialization at startup

    • Load budget configuration from config/agent-budgets.toml
    • Initialize BudgetManager with Arc for thread-safe sharing
    • Attach to coordinator via with_budget_manager() builder pattern
    • Graceful fallback if no configuration exists

  • Coordinator Builder Pattern: Budget manager attachment

    • Added budget_manager: Option<Arc<BudgetManager>> field
    • with_budget_manager() method for fluent API
    • Updated all constructors (new(), with_registry())
    • Backward compatible (works without budget configuration)

Added - Documentation

  • Implementation Summary: .coder/2026-01-11-phase-5-completion.done.md

    • Complete architecture overview (3-layer integration)
    • All files created/modified with line counts
    • Prometheus metrics reference
    • Quality metrics (120 tests passing)
    • Educational insights

  • Gradual Deployment Guide: guides/gradual-deployment-guide.md

    • Week 1: Staging validation (24 hours)
    • Week 2-3: Canary deployment (incremental traffic shift)
    • Week 4+: Production rollout (100% traffic)
    • Automated rollback procedures (< 5 minutes)
    • Success criteria per phase
    • Emergency procedures and checklists

Changed

  • LLMRouter: Enhanced with budget awareness

    • select_provider_with_budget() method for budget-aware routing
    • Fixed incomplete fallback implementation (lines 227-246)
    • Cost-ordered fallback chain (cheapest first)

  • ProfileAdapter: Learning integration

    • update_from_kg_learning() method for learning profile sync
    • Query KG for task-specific executions with recency filter
    • Calculate success rate with 7-day exponential decay

  • AgentCoordinator: Learning-based assignment

    • Replaced min-load selection with AgentScoringService
    • Extract task type from task description
    • Combine swarm metrics + learning profiles for final score

Fixed

  • Clippy Warnings: All resolved (0 warnings)

    • redundant_guards in BudgetConfig
    • needless_borrow in registry defaults
    • or_insert_with → or_default() conversions
    • map_clone → cloned() conversions
    • manual_div_ceil → div_ceil() method

  • Test Warnings: Unused variables marked with underscore prefix

Technical Details

New Files Created (13):

  • vapora-agents/src/learning_profile.rs (250 lines)
  • vapora-agents/src/scoring.rs (200 lines)
  • vapora-knowledge-graph/src/learning.rs (150 lines)
  • vapora-llm-router/src/budget.rs (300 lines)
  • vapora-llm-router/src/cost_ranker.rs (180 lines)
  • vapora-llm-router/src/cost_metrics.rs (120 lines)
  • config/agent-budgets.toml (50 lines)
  • vapora-agents/tests/end_to_end_learning_budget_test.rs (NEW)
  • 4+ integration test files (700+ lines total)

Modified Files (10):

  • vapora-agents/src/coordinator.rs - Learning integration
  • vapora-agents/src/profile_adapter.rs - KG sync
  • vapora-agents/src/bin/server.rs - Budget initialization
  • vapora-llm-router/src/router.rs - Cost-aware routing
  • vapora-llm-router/src/lib.rs - Budget exports
  • Plus 5 more lib.rs and config updates

Test Suite:

  • Total: 120 tests passing
  • Unit tests: 71 (vapora-agents: 41, vapora-llm-router: 30)
  • Integration tests: 42 (learning: 7, coordinator: 9, budget: 11, cost: 12, end-to-end: 3)
  • Quality checks: Zero warnings, clippy -D warnings passing

Deployment Readiness:

  • Staging validation checklist complete
  • Canary deployment Istio VirtualService configured
  • Grafana dashboards deployed
  • Alert rules created
  • Rollback automation ready (< 5 minutes)

0.1.0 - 2026-01-10

Added

  • Initial release with core platform features
  • Multi-agent orchestration with 12 specialized roles
  • Multi-IA router (Claude, OpenAI, Gemini, Ollama)
  • Kanban board UI with glassmorphism design
  • SurrealDB multi-tenant data layer
  • NATS JetStream agent coordination
  • Kubernetes-native deployment
  • Istio service mesh integration
  • MCP plugin system
  • RAG integration for semantic search
  • Cedar policy engine RBAC
  • Full-stack Rust implementation (Axum + Leptos)