AlvGolf-Identity-EngineV3

AlvGolf - Multi-Agent Golf Analytics System

Version: v4.9.3 - Historial Styled + PDF Universal + Marina Golf Enrichment Estado: Production Ready Ultima actualizacion: 2026-03-29

Dashboard Backend Agentic Agents Endpoints Users Islands Social Tests Cost

Descripcion del Proyecto

AlvGolf es un sistema completo de analisis de rendimiento de golf potenciado por IA que combina:

  1. Dashboard Dinamico v5.4.0 - 36 visualizaciones interactivas con Chart.js + contenido AI + ~326 valores dinamicos + campanita notificaciones
  2. Backend Generator v5.3.0 - 59 funciones de procesamiento de datos + scoring engine + player level system
  3. Multi-Agent System v4.9.1 - 7 agentes especializados + identity generator con arquitectura optimizada (asyncio.to_thread)
  4. Identity System - Scoring Engine (8 dimensiones) + 6 Levels (PlayerLevel) + AI-Generated Identity + Identity Timeline
  5. Social Comparisons - Comparativas bilaterales entre amigos (max 2 activas, cross-isla) + 15 tipos de notificaciones + 9 benchmarks estaticos (PGA + HCP 0-35)
  6. Radar Redesign + Comparison Overlays - Radar Tab 1 con selectores strip+bar para benchmarks/amigos + 5 chart overlays comparativos (evolucion HCP, scoring por campo, distancias, dispersion, strokes gained)
  7. Strokes Gained V2 - Motor informativo basado en benchmarks Golfissimo/Broadie, API en metros, comparacion multi-nivel
  8. Template vs Data - Dashboard reutilizable: ~326 IDs dinamicos + 12 containers + 7 funciones de inyeccion (extendidas)
  9. Course Guide Portal - Personalized hole-by-hole strategy guides with AI
  10. Island Branding - White-label per club/resort/academy (B2B2C)

Datos Analizados

Arquitectura del Sistema - Multi-Agent v3.0.5

graph TB
    subgraph "Frontend Layer"
        A[dashboard_dynamic.html<br/>36 Charts + ~216 IDs dinamicos v5.3.0]
        B[dashboard_agentic.html<br/>Course Guide Portal]
    end

    subgraph "Multi-Agent System v4.9.1 (Orchestrator v4.3)"
        C[FastAPI Server :8000]
        D[Data Loader<br/>273 KB, 0 RAG]

        subgraph "Team 2 - Analytics ~89s"
            E1[AgentAnalista<br/>Performance]
            E2[AgentTecnico<br/>Biomechanics]
            E3[AgentEstratega<br/>Practice]
        end

        subgraph "Team 3 - Content ~112s"
            F1[AgentUXWriter<br/>Dashboard Content]
            F2[AgentCoach<br/>Coaching Reports]
        end

        F3[AgentCourseStrategist<br/>Course Guides]
    end

    subgraph "Backend v5.3.0 - Generator"
        H[generate_dashboard_data.py<br/>59 functions]
        H2[scoring_engine.py<br/>8 dimensions 0-10]
        H3[player_level.py<br/>6 levels + identity IA]
        H4[temporal_analysis.py<br/>Identity Timeline]
    end

    subgraph "Data Layer"
        I[dashboard_data.json<br/>273 KB, 62 keys]
        J[Raw Data<br/>FlightScope + Tarjetas]
    end

    subgraph "External APIs"
        K[Anthropic Claude Sonnet 4.6<br/>LLM + Prompt Caching]
    end

    A -->|Link| B
    B -->|POST /analyze| C
    C -->|Load JSON| D
    D -->|100% Data| E1 & E2 & E3
    E1 & E2 & E3 -->|Analysis| F1 & F2
    F1 & F2 -->|Response| B

    J -->|Process| H
    H -->|Score| H2 & H3 & H4
    H -->|Generate| I
    I -->|Load + Inject| A
    I -->|Load| D

    E1 & E2 & E3 & F1 & F2 -->|LLM Calls| K

Flujo Optimizado v4.2 (~2.1 minutos):

  1. Data Loader (0.05s) -> Load dashboard_data.json (273 KB)
  2. Scoring Engine (< 10ms) -> 8 dimensiones 0-10 (determinista)
  3. Player Level (< 1ms) -> Nivel 1-6 (determinista)
  4. Team 2 Parallel (~49s) -> 3 agents simultaneos (asyncio.to_thread)
  5. Team 3 Parallel (~86s) -> 2 agents simultaneos -> END

What’s New

v4.7.1 - Orchestrator v4.2 + Enrichment + Social Benchmarks Design (2026-03-24)

v4.4.0 - CourseStrategist + Course Guide Portal (2026-03-18)

v4.3.0 - Archetype Redesign (2026-03-17)

v4.7.0 - 6 Levels + AI Identity + Server-Side Auth (2026-03-22)

v4.2.0 - Demo Comercial 30 Marzo (2026-03-16/17)

v3.3.0 - AI History + Selective Agents (2026-03-15)

Persistencia, comparacion y regeneracion selectiva de analisis IA:

v3.2.0 - Full Glassmorphism Redesign Tabs 1-6 (2026-03-07)

Rediseno visual completo de los 6 tabs con glassmorphism consistente, quick menus con sub-grupos logicos, y reorganizacion de secciones:

v3.1.3 - Tab 2 Redesign + AI Conclusions + Quick Menu Audit (2026-03-05)

v3.0.9 - Radar Deduplication + Section Reorg (2026-03-03)

Eliminacion de radar duplicado en Tab 1 y unificacion de fuente de datos en Tab 5:

v3.0.8 - Card System v3.1 + Typography Fix (2026-03-03)

Card System v3.1 — sistema CSS unificado de 4 niveles de jerarquia visual:

v3.0.7 - 100% Dynamic Dashboard (2026-03-02)

~176 hardcodes editoriales migrados a JSON (LOTES 1-9), completando la dinamizacion al 100%:

LOTE Tab Contenido Hardcodes
1 Tab 1 Archetype/Form narratives ~15
2 Meta PDF filename dinamico ~5
3 Tab 3 Course dates, insights, patterns ~15
4 Tab 4 Dispersion stats per club (11 clubs) ~33
5 Tab 4 Dispersion summary + conclusion ~18
6 Tab 5 Diagnostic prose + player profile ~20
7 Tab 1 Coaching recommendations ~15
8 Tab 4 Bubble analysis (4 zones) ~25
9 Tab 6 28-day improvement plan ~30

v3.0.6 - Template vs Data Phase 2 (2026-03-01)

~110 hardcodes numericos de alta prioridad migrados a JSON (LOTES 0-5):

Funcion Prefijo IDs Tab
injectPlayerStats() ps- 22 + DNA(21) + form/last5(23) + zones(25) Tab 1
injectHeaderStats() hd- 12 Header
injectEvolutionStats() ev- 24 Tab 2
injectCourseStats() cs- 17 + narratives(22) + goals + 3 containers Tab 3
injectClubStats() cl- 14 + 4 containers Tab 4
injectAnalysisStats() an- 4 + metrics(14) Tab 5
injectStrategyStats() st- 9 Tab 6

Template vs Data Phase 1 (2026-02-28)

v3.0.5 - Identity Timeline (2026-02-25)

Feature: Timeline visual mostrando evolucion del arquetipo golfistico a lo largo de 18 meses con ventanas deslizantes (90d window, 60d step). 11 periodos generados.

Nuevos modulos:

Claves JSON nuevas: flightscope_shots_timeline (497 shots), identity_timeline (11 periodos), scoring_profile, golf_identity

v3.0.4 - Orchestrator asyncio Optimization (2026-02-24)

v3.0.3 - Static AI Content Cache (2026-02-22)

v3.0.2 - Prompt Caching + Model Update (2026-02-21)

v3.0.1 - UXWriter Dashboard Integration (2026-02-17)

v3.0.0 - Multi-Agent System Complete (2026-02-16)

Caracteristicas Principales

Dashboard v5.3.0 (Estatico + Dinamico)

Backend Generator v5.3.0

Multi-Agent System v4.9.1

Course Guide Portal

API Endpoints (v4.9.2 — 43 endpoints)

Core AI & Analysis (19)

Metodo Path Proposito Tiempo
GET / Health check <100ms
POST /ingest Ingesta de datos a Pinecone ~2s
POST /query RAG query 10-15s
POST /analyze Workflow completo (6 agentes) + deteccion de eventos ~3.6 min
POST /analyze-smart Regeneracion condicional + deteccion de eventos variable
POST /generate-content UXWriter content only ~60-70s
POST /generate-coach Coach report only ~60-70s
POST /generate-agent Agente individual selectivo ~40-70s
POST /generate-course-guide Course strategy guide ~40-50s
POST /chat AI Caddie conversacional (auth server-side) ~2-5s
POST /generate-identity Identidad unica IA por jugador ~5s
POST /record-ingesta Record data source update <100ms
POST /batch-analyze Batch analysis (Batches API) variable
GET /batch-status/{batch_id} Check batch status <100ms
POST /batch-collect/{batch_id} Collect batch results <100ms
GET /history Listado analisis guardados <100ms
GET /history/{id} Cargar analisis especifico <100ms
GET /history/compare/{id1}/{id2} Comparar dos analisis <100ms
POST /history/summarize/{id1}/{id2} Resumen IA de cambios entre analisis ~3-5s

Social Comparisons (7)

Metodo Path Proposito Tiempo
GET /compare?users=a,b Perfiles de comparacion (valida activas) <200ms
POST /compare/request Enviar solicitud de comparativa <100ms
POST /compare/accept Aceptar solicitud pendiente <100ms
POST /compare/reject Rechazar solicitud pendiente <100ms
POST /compare/revoke Revocar comparativa activa (unilateral) <100ms
GET /compare/active/{user_id} Listar activas + pendientes + codigo <100ms
GET /compare/search?q= Buscar usuarios por nombre/codigo <100ms

Notifications (4)

Metodo Path Proposito Tiempo
GET /notifications/{user_id} Notificaciones paginadas con filtros <100ms
POST /notifications/{user_id}/read Marcar como leidas <100ms
GET /notifications/{user_id}/unread-count Contador para badge campanita <100ms
PUT /notifications/{user_id}/preferences Preferencias frecuencia + tipos <100ms

Benchmarks, Users & Islands (13)

Metodo Path Proposito Tiempo
GET /benchmarks Lista 9 niveles de benchmark <100ms
GET /benchmarks/{level} Benchmark completo (dims+clubs+SG) <100ms
GET /users Listar usuarios (filtro por isla) <100ms
POST /users Crear usuario <100ms
GET /users/{user_id} Perfil completo de usuario <100ms
PUT /users/{user_id} Actualizar campos usuario <100ms
DELETE /users/{user_id} Desactivar usuario <100ms
GET /islands Listar islas con conteo usuarios <100ms
POST /islands Crear configuracion de isla <100ms
GET /islands/{slug} Config de isla <100ms
PUT /islands/{slug} Actualizar config de isla <100ms
GET /api-costs Resumen costes API <100ms
GET /api-costs/detail Desglose costes detallado <100ms

Instalacion y Configuracion

Requisitos Previos

Paso 1: Clonar Repositorio

git clone https://github.com/AlvGolf/AlvGolf-Identity-EngineV3.git
cd AlvGolf-Identity-EngineV3

Paso 2: Configurar Environment

cp .env.example .env
# Editar .env con tus API keys

Contenido de .env:

ANTHROPIC_API_KEY=sk-ant-api03-...
PINECONE_API_KEY=pcsk_...
PINECONE_INDEX_NAME=alvgolf-rag
ENV=local
API_HOST=0.0.0.0
API_PORT=8000
LOG_LEVEL=INFO

Paso 3: Instalar Dependencies

pip install -r requirements.txt

Paso 4: Generar Datos del Dashboard

python generate_dashboard_data.py
cp output/dashboard_data.json dashboard_data.json

Paso 5: Iniciar Backend (opcional, para agentes IA)

python -m app.main

Paso 6: Iniciar Frontend Server

python -m http.server 8001

Paso 7: Acceder

Estructura del Proyecto

AlvGolf/
├── app/                              # Backend Agentic Analytics Engine
│   ├── __init__.py
│   ├── main.py                       # FastAPI app (43 endpoints)
│   ├── history.py                    # AI analysis persistence & comparison
│   ├── history_summarize.py          # AI summary for history comparisons (Claude)
│   ├── config.py                     # Settings management (.env)
│   ├── models.py                     # Pydantic models (21 models)
│   ├── rag.py                        # RAG Core (Pinecone + Claude)
│   ├── scoring_engine.py             # Deterministic scoring (0-10, 8 dims)
│   ├── player_level.py               # 6 deterministic levels (replaces archetype_classifier)
│   ├── archetype_classifier.py       # DEPRECATED — replaced by player_level.py
│   ├── scoring_integration.py        # Scoring + levels + identity + timeline
│   ├── temporal_analysis.py          # Sliding window identity analysis
│   ├── strokes_gained_v2.py          # SG V2 motor (Golfissimo/Broadie benchmarks, meters)
│   └── agents/                       # Multi-Agent System
│       ├── __init__.py
│       ├── orchestrator.py           # LangGraph workflow orchestrator
│       ├── analytics_pro.py          # Legacy Analytics Agent (TIER 1)
│       ├── analista.py               # Team 2: Performance (650 lines)
│       ├── tecnico.py                # Team 2: Biomechanics (550 lines)
│       ├── estratega.py              # Team 2: Practice design (600 lines)
│       ├── ux_writer.py              # Team 3: Dashboard content (752 lines)
│       ├── coach.py                  # Team 3: Coaching reports (807 lines)
│       └── course_strategist.py      # Course strategy guides (~320 lines)
│
├── scripts/                          # Scripts and utilities
│   ├── create_user.py                # User creation CLI (--name, --hcp, --island)
│   ├── generate_demo_data.py         # Fictional player data generator
│   ├── generate_course_guide.py      # Course strategy guide generator (offline HTML)
│   ├── test_team3_complete.py        # Team 3 test suite (6 tests)
│   ├── test_optimized_architecture.py
│   ├── test_dashboard_integration.py # E2E tests (4/4)
│   └── ingest_full_data.py           # Data ingestion (120 vectors)
│
├── output/
│   ├── dashboard_data.json           # Generated data (273 KB, 62 keys)
│   ├── ai_content.json              # Pre-generated AI content (20 sections)
│   ├── ai_history/                  # Timestamped AI analysis history
│   ├── course_guides/               # Pre-generated course strategy guides
│   └── users/{user_id}/             # Multi-user data isolation
│
├── data/                             # Raw data
│   ├── flightscope/                  # 497 shots, 11 clubs
│   ├── tarjetas/                     # 85 rounds, 11 courses
│   └── enrichment/
│       └── course_holes.json         # Real hole data (11 courses)
│
├── config/
│   ├── users.json                    # User registry
│   └── islands/                      # Club branding configs
│       ├── valle_del_este.json
│       ├── desert_spring.json
│       └── academia_miki.json
│
├── docs/                             # Corporate documentation
│   ├── brand_guidelines.html         # Brand Guidelines
│   ├── guia_funcionalidades.html     # Feature Guide
│   ├── guia_rapida.html              # Quick Guide for directors
│   ├── one_pager.html                # One-page commercial PDF
│   └── demo_script_30_abril.html     # Internal demo script
│
├── dashboard_dynamic.html            # Main dashboard (v5.3.0, ~20,800 lines)
├── dashboard_agentic.html            # Course Guide Portal
├── admin.html                        # Island Admin Suite (11 blocks)
├── index.html                        # Landing page
├── generate_dashboard_data.py        # Backend generator (59 functions)
│
├── .env                              # API keys (NOT committed)
├── .env.example                      # Template
├── requirements.txt                  # Python dependencies
├── ARCHITECTURE_DIAGRAMS.md          # 8 Mermaid architecture diagrams
└── README.md                         # This file

Metricas del Sistema

Performance

| Metrica | Valor | |———|——-| | Dashboard Load | <1s (static HTML) | | AI Content Load | <100ms (pre-generated) | | JSON Generation | ~3.1s (59 functions) | | Full Agent Workflow | ~3.6 min (6 agents) | | UXWriter Only | ~60-70s |

Costos (25 analisis/mes)

| Concepto | Costo | |———-|——-| | Per-call (sin cache) | $0.185 | | Per-call (con cache) | $0.110 | | Pinecone Serverless | ~$0.40/mes | | Total Estimado | ~$0.52/mes |

Dataset

| Metrica | Valor | |———|——-| | Rondas Historicas | 85 (Mar 2024 - Dic 2025) | | Shots FlightScope | 497 (11 clubs) | | Campos | 11 | | JSON Keys | 62 | | JSON Size | 273 KB | | Dynamic IDs | ~326 (spans + containers) | | Injection Functions | 7 (extended) |

Roadmap

Completado

v5.0.0 - v5.1.1 (Feb 2026)

TIER 1 Agentic (2026-02-15)

v3.0.0 - v3.0.5 (Feb 2026)

v3.0.3 (2026-02-22) - Performance + Coach PDF

Template vs Data Phase 1 (2026-02-28)

v3.0.6 - Template vs Data Phase 2 (2026-03-01)

v3.0.9 - Radar Deduplication + Section Reorg (2026-03-03)

v3.0.8 - Card System v3.1 + Typography Fix (2026-03-03)

v3.0.7 - 100% Dynamic Dashboard (2026-03-02)

v3.2.0 - Full Glassmorphism Redesign (2026-03-07)

v3.3.0 - AI History + Selective Agents (2026-03-15)

Pendiente

Changelog

v4.9.3 (2026-03-29) - Historial Styled + PDF Universal + Marina Golf

v4.9.2 (2026-03-29) - Hub IA Comparador con Resumen IA

v4.9.1 (2026-03-26) - Radar Redesign + Comparison Overlays + Strokes Gained V2

v4.9.0 (2026-03-26) - Social Comparisons + Notifications

v4.8.0 (2026-03-26) - Islas Funcionales

v3.3.0 (2026-03-15) - AI History + Selective Agents

v3.2.0 (2026-03-07) - Full Glassmorphism Redesign Tabs 1-6

v3.1.3 (2026-03-05) - Tab 2 Redesign + CSS Paso 0 + Tab 3-4 Glassmorphism

v3.0.9 (2026-03-03) - Radar Deduplication + Section Reorg

v3.0.8 (2026-03-03) - Card System v3.1 + Typography Fix

v3.0.7 (2026-03-02) - 100% Dynamic Dashboard

v3.0.6 (2026-03-01) - Template vs Data Phase 2

Template vs Data Phase 1 (2026-02-28)

v3.0.5 (2026-02-25) - Identity Timeline

v3.0.4 (2026-02-24) - Async Optimization

v3.0.3 (2026-02-22) - Lazy Loading + Coach PDF + Static AI Cache

v3.0.2 (2026-02-21) - Prompt Caching

v3.0.1 (2026-02-17) - UXWriter Integration

v3.0.0 (2026-02-16) - Multi-Agent System

v5.1.1 (2026-02-13) - Heatmap + Mobile

v5.1.0 (2026-02-12) - 10D Radar

v5.0.0 (2026-02-09) - 36 Charts (100%)

TIER 1 (2026-02-15) - FastAPI + RAG + Agent

Seguridad

Contacto & Links

Proyecto: AlvGolf Multi-Agent Golf Analytics System Developer: Alvaro Peralta Asistido por: Claude Sonnet 4.6 / Claude Opus 4.6 (Anthropic) GitHub: https://github.com/AlvGolf/AlvGolf-Identity-EngineV3 GitHub Pages: https://alvgolf.github.io/AlvGolf-Identity-EngineV3/

Licencia

Proyecto personal - Todos los derechos reservados Alvaro Peralta 2026

Ultima actualizacion: 18 de marzo de 2026 Estado: Production Ready Version: v4.4.0 - CourseStrategist + Course Guide Portal