📖 Manual de Usuario · SkyWeave Alpha

Guía completa del demo platform — 60-day plan · Mode B
🇬🇧 English

Introducción

SkyWeave Alpha es un substrate continuo de integración de datos para decisiones de aerolíneas. Reemplaza al ejército de 60 analistas + las consultoras (McKinsey, BCG, Bain, Simon-Kucher, Alton, Oliver Wyman, Seabury, ICF) que hoy cobran $5–15M por aerolínea por año.

Este demo es la implementación funcional del plan de 60 días de Luis (Rev 5) en Mode B (synthetic data, sin DP-1 carrier firmado). Demuestra el wedge end-to-end: ingesta con provenance → coordinator pipeline → audit chain → 6 surfaces → What-If → RAG scaffold → conectores nombrados → schemas publicados.

El destino final del proyecto: 30 agentes IA operando una aerolínea por Diciembre 2026, una aerolínea de 10 personas para 2030. Este demo muestra la base sobre la que ese destino se construye.

El menú superior tiene dos zonas:

Cada surface tiene su propio dashboard con KPI cards arriba y cards expandibles abajo. Cliqueá cualquier card para ver el detalle completo de la Decision: PAL+ decomposition, levers recomendados, audit info, raw JSON artifact.

Las 6 superficies productivas

📊

S1 · Daily Margin Watch

CadenciaDiaria · publicación 06:00 local BuyerCFO + VP Finance + VP Commercial + VP Revenue DesplazaMcKinsey margin-diagnostic engagements ($500K-2M)

Qué hace

Atribuye el P&L de cada vuelo del día anterior contra forecast + budget + last-year. Detecta desviaciones de margen ≥1σ y emite un Decision Artifact por cada vuelo flagged con la descomposición PAL+ completa (revenue + ancillary + cargo - 6 líneas de costo).

Cómo leer el dashboard

  • KPI superior: total flights, total margin actual vs forecast (delta en rojo/verde), número de anomalías flagged, integridad de la audit chain.
  • Sección Anomalías: cards rojos con flight_number, ruta, margen actual, deviation_sigma. Cliqueá para expandir y ver el narrative + breakdown PAL+ línea por línea + drill-down al Sense record.
  • Sección All flights: primeros 50 vuelos on-baseline. Cliqueá cualquiera para ver su decomposition completa.
  • view artifact: cada card linkea a su JSON artifact (deep-linkeable, replayable).
💰

S2 · Daily Cost Control

CadenciaDiaria 06:00 + scenario triggers on-demand BuyerCFO + VP Operations + cost owners funcionales (Fuel, Crew, MX, Airport, Distribution) DesplazaMcKinsey cost-out programs / Bain cost-PMO ($500K-3M)

Qué hace

Detecta anomalías en CADA línea de costo (fuel, crew, MX, airport, distribution) con z-score per-population. Para cada anomalía emite un Decision con narrative + lever propuesto (ej: 'reduce reserve crew at hub by 2 pilots') con USD estimado del impacto.

Cómo leer el dashboard

  • KPI superior: cantidad de cost-line anomalies, total impact, top opportunity (mejor single lever).
  • Cards estratégicas: cada anomalía muestra qué línea está desviada (ej. 'fuel cost 50% of revenue'), el delta vs baseline, y los levers recomendados — acciones específicas con USD impact estimado.
  • Constitution gate: el write-back a Hyperion-Sim requiere CFO + COO sign-off via audit chain.
🎯

S3 · Daily RM Strategic

CadenciaDiaria + scenario triggers BuyerVP RM + Director Pricing + pirámide de RM analysts + VP Commercial Strategy DesplazaSimon-Kucher / BCG / McKinsey RM strategy engagements ($300K-1M)

Qué hace

Detecta oportunidades de redesign de fences (reglas que separan corporate de leisure). Calcula corporate-vs-leisure yield ratio por ruta y flag-ea las rutas con ratio bajo el median — donde el fence se colapsó. Cada Decision propone fence redesign + cluster reassignment con +X bp yield estimado.

Cómo leer el dashboard

  • NO compite con PROS / AirVision / FLYR — esos manejan el bid-price tactical day-of-departure. SkyWeave provee el strategic envelope.
  • Cards estratégicas: cada una muestra la ruta, el yield corporate vs leisure observado, el ratio, y la propuesta de redesign.
  • Write-back: strategic params (no bid-prices) van a PROS-Sim strategic-params API.
📦

S4 · Daily Cargo Strategic

CadenciaDiaria + scenario triggers BuyerVP Cargo + Director Cargo + VP Commercial Strategy DesplazaBoutique cargo consultants + ICF cargo studies + Seabury ($200K-600K)

Qué hace

Recalibra yield curves por O&D × commodity. Detecta rutas con cargo yield bajo el network mean (bottom 25%) y propone recalibration: lift floor rate + rebalance belly capacity vs pax-capacity coupling. NO compite con IBS iCargo tactical booking layer.

Cómo leer el dashboard

  • Yield-per-ton-mile: la métrica clave que se compara al network mean por O&D.
  • Levers: cada Decision incluye opciones específicas (yield curve recalibration, commodity mix shift) con USD impact anual estimado.
  • Write-back: a iCargo-Sim strategic API (no tactical bookings).
✈️

S5 · P11 Fleet Strategy

CadenciaProyecto · trimestral + event-driven rerun BuyerCFO + Treasury + VP Fleet Planning + Corporate Development Desplaza3-4 meses de Alton / Oliver Wyman / ICF fleet review ($1-5M)

Qué hace

Analiza rotation multi-año por tipo de flota. Identifica candidatos de retirement (under-performers) y expansion (out-performers) con cálculo de NPV a 5 años. Cada Decision incluye levers concretos (retire over 24mo + redeploy crew, OEM bid evaluation, lessor renegotiation).

Cómo leer el dashboard

  • Horizon: 5 años (NPV calculado a discount rate ~8%).
  • Por fleet type: A320-200, A321neo, B737-800, B737-MAX8, B787-9. Compara avg margin/cycle vs network mean.
  • Levers: retire (con timeline de 24 meses), OEM bid evaluation, lessor early-return clauses.
🌐

S6 · P10 Network Strategy

CadenciaProyecto · trimestral + event-driven on competitive shifts BuyerVP Commercial Planning + VP Network + CFO Desplaza2-3 meses de Oliver Wyman / Seabury / Alton network engagement ($5-15M)

Qué hace

Identifica rutas a abrir (top performers de la red) y rutas a cerrar (bottom performers). NPV 5-año por ruta. Cada Decision incluye levers concretos: closure + slot redeployment via auction primitive, o frequency add con RM coordination.

Cómo leer el dashboard

  • Bottom-3 + Top-2: el stub muestra hasta 5 candidatos (3 cierres + 2 expansions).
  • NPV: calculado sobre 5 años, base discount rate ~8%.
  • Levers: route closure con slot auction, frequency add con bid-price ceiling coordination.

Las 8 primitivas (F1–F8)

F1

💎 PAL+ Profit Attribution

Descompone cada Decision en líneas USD: revenue + ancillary + cargo - 6 cost lines. Cada línea tiene formula_hash + evidence_ref (apunta al content-hash del Sense record fuente). En el demo son 9 líneas; en producción son 36 calibration constants tuned contra multi-year override telemetry, con cross-cadence dedup graph que bloquea double-counting. El demo tiene la estructura completa pero no la calibración.

F2

🔐 Audit-chained Ledger

Append-only Merkle chain per-tenant. Cada decision/override/kill-switch/scenario commit se hashea linkeando al hash anterior. En producción: blake3 + AWS KMS Sign (RSA-PSS) + hourly Merkle root pin a S3 Object Lock (compliance mode 7 años). En el demo: SHA-256 + verify_chain() returns OK. Independientemente verificable sin trust en SkyWeave.

F3

⚙️ Coordinator Runtime + Constitution + Kill-Switch

Coordinator base class (ABC) + 6 implementaciones concretas (Margin, Cost, RM, Cargo, Fleet, Network). Pipeline no-bypasseable: run() → constitution → PAL+ → audit → profit_queue. Constitution chequea FAR 117 + EU OPS 965 + per-tenant CBA antes de que cualquier Decision llegue al audit. Kill-switch halt ≤60s p99 a todos los coordinators. Plug-in interface para que Roberto inyecte su optimization engine sin tocar coordinators.

F4

👁️ Sense Ledger + Inference Cache + Replay Manifest

Append-only log de cada fetch externo + interno. Cada record content-hashed con SHA-256 (production: blake3). En producción: 18+ MCP/computer-use connectors (Altea, SabreSonic, AMOS, NetLine, PROS, etc.) bajo entitlement-grant. LLM Inference Cache: cada LLM call (prompt, model_dated_id, response, sampling_params, KMS signature) → WORM S3. Replay Manifest indexa cada decision a sus Sense records exactos. 3-month replay byte-equivalent en el demo.

F5

🧰 Skill SDK

Deferred del demo — En producción: skyweave-cli init / validate / deploy / publish con cosign signing pipeline. Cada Skill es un YAML manifest (declared coordinator bindings, data dependencies, constitution rules, PAL+ extensions, renderer template). Marketplace post-Series A. En el demo las surfaces shipean como módulos internos.

F6

📐 Open Ontology + Schemas

5 JSON Schemas (Draft 2020-12) publicados Apache 2.0: Decision, PALDecomposition, PALLine, SenseRecord, AuditEntry. Vocabulario de la industria — habilita que un regulador, un lender, o un paper académico citen nuestras estructuras. El costo de publicar es cero; el moat compone por años.

F7

🔮 Analyst What-If Engine

Runtime multi-tenant que permite que analistas corran scenarios replayables sobre cualquier surface. En producción: 50-200 concurrent analyst seats. En el demo: single-user runner con replay + fork. Cada scenario aplica una mutación (fuel ±%, demand ±%, crew premium ±%, etc.) y re-corre el coordinator con los datos mutados. El delta vs baseline se muestra en la página What-If.

F8

🔍 RAG Pipeline (scaffold)

Per-tenant RAG sobre docs del carrier (contracts, JCBA, MELs, ATPCO, AMOS work-order history, NetLine schedules, regulatory environment per-jurisdiction). En producción: BGE-large-en embeddings + pgvector HNSW + LoRA fine-tune en RunPod GPU + federated learning. En el demo: scaffold solo — ingestion structure + hash-bow embedding + cosine retrieval. SIN model training. La interface es la misma que producción para que el swap sea drop-in.

Herramientas

Las 6 páginas de herramientas del menú superior, una por una:

📋

Decision Artifacts

→ Abrir artifacts.html

Viewer unificado de TODOS los Decision Artifacts emitidos en la última corrida del demo (S1-S6). Cada card muestra el JSON crudo expandible (replayable), la PAL+ decomposition con formula hashes, los levers recomendados, y el evidence reference (content-hash al Sense record fuente). Cliqueá cualquier card para drill-down completo.

🔮

What-If Engine

→ Abrir whatif.html

6 scenarios pre-ejecutados sobre S1 y S2 con mutaciones: fuel +20%, fuel -15%, demand -10%, cargo +25%, crew premium +15%. Cada scenario corre el coordinator con datos mutados y muestra delta-vs-baseline en flagged count + impact USD. Permalink + fork: cualquier analyst puede branchear de un scenario y aplicar más mutations.

🔍

RAG Index Studio

→ Abrir rag.html

Muestra el índice RAG con 5 doc classes ingestadas: regulatory (FAR 117 summary), contracts (Pilot CBA 2024), manuals (AMOS engine MX), jcba (route constraints), amos_work_orders. Y 5 sample queries con los top-3 chunks recuperados. Embedding hash-bow para demo (producción: BGE-large-en).

🔌

Connectors

→ Abrir connectors.html

8 vendor stubs scaffolded con sample records en wire-format real de cada vendor: Sabre (SabreSonic XML), Amadeus (Altea NDC + Nevio REST), PROS (strategic-params API), AMOS (work-order XML), NetLine (SSIM-X), IBS iCargo (AWB EDIFACT), Hyperion (staging mart), Anaplan (REST v2). En producción: MCP + computer-use bindings + entitlement-grant.

🔐

Audit Chain

→ Abrir audit.html

Muestra el estado del audit chain: integrity check (verify_chain), entry count total, kill-switch events drilled, Merkle root actual. La tabla de últimas entries muestra seq, kind, entry_hash, previous_hash, decision_id, timestamp. Una sola byte tampered rompe el chain a partir de ahí.

📐

Open Ontology · Schemas

→ Abrir schemas.html

Los 5 JSON Schemas (Draft 2020-12, Apache 2.0) publicados Day 1 con la URL conceptual github.com/skyweave/ontology. Cada uno con properties count, descripción, y el schema crudo expandible. Estos son el contrato público — el motor de Roberto y cualquier Skill futura tienen que conformar a estas shapes.

Conceptos clave

Decision
La unidad atómica de output de SkyWeave. Cada coordinator emite Decisions; el pipeline (Constitution → PAL+ → Audit → Queue) NO se puede bypassear. Contiene id, surface_id, coordinator_name, flight_date, narrative, levers, impact_usd, PAL+ decomposition. Es replayable byte-equivalent.
PAL+ (Profit Attribution Library)
La biblioteca de descomposición de profit en líneas USD. Cada PAL+ line es atribuída a un underlying_record_key (tail, ESN, route, O&D), con formula_hash + evidence_ref. El cross-cadence dedup graph (NetworkX) bloquea que dos decisions reclamen la misma línea.
Constitution
El conjunto de reglas que toda Decision debe cumplir antes de llegar al audit. En producción incluye FAR 117 + FAR 121 + EU OPS 965 + IATA 735a + per-tenant CBA. En el demo: 4 reglas — R-DISCLOSURE (flagged needs narrative), R-SANITY (sigma plausible), R-SURFACE (valid surface_id), R-MATERIALITY (>$1M loss must flag). Violación → ConstitutionViolation → la decisión NUNCA aterriza.
Audit Chain (Merkle)
Append-only per-tenant. Cada entry hashea (previous_hash + payload_hash + timestamp + tenant_id). Una byte tampered rompe la chain. En producción: hourly Merkle root + KMS Sign + S3 Object Lock 7-año. En demo: in-memory verify_chain() returns OK.
Coordinator
Una instancia de la Coordinator base class. Cada surface (S1-S6) tiene la suya: MarginCoordinator, CostCoordinator, RMCoordinator, CargoCoordinator, FleetCoordinator, NetworkCoordinator. Cada uno implementa run() que devuelve Decisions; el emit() del base class corre el pipeline no-bypasseable.
Sense Ledger
Append-only log de TODO record que entra al sistema (CSV ingestion, MCP fetch, computer-use binding). Content-hash (SHA-256/blake3) por record. Entitlement-grant scoped. Cada PAL+ line linkea a su record fuente via evidence_ref.
Content-hash provenance
Cada record en el Sense ledger tiene un content_hash deterministic. Ese hash aparece como evidence_ref en cada PAL+ line, y en el source_record_hash de cada RAG chunk. Trazabilidad end-to-end: USD value → PAL+ line → Sense record → source connector. Esto es lo que un consultor no puede dar.
Replay
La capacidad de re-derivar una decisión dada los inputs exactos al momento del cálculo. El Replay Manifest indexa cada decision a sus Sense records + Inference Cache entries. Demo: 3-month replay byte-equivalent en 100% de decisions sampled.
Mode A vs Mode B
Mode A: DP-1 carrier firmado, S1-S6 corren contra la data real del carrier. Attestation signer es el CFO + VP RM + VP Cargo + VP Fleet del carrier. Mode B: sin DP-1, S1-S6 corren contra synthetic data (BTS T-100 + DB1B + OAG public + 10-K filings). Este demo es Mode B.
Mythos timeline / 30-agent destination
El roadmap post-alpha asume que un modelo frontier-class de tool-use lands ≥99.9% reliable + coherent 60-90min reasoning por Dec 2026. Bajo esa asunción: 6 agentes al alpha (D45) → 30 agentes al M6 (Dec 2026). Si Mythos slipea: 30 agentes lands M9 con human-in-loop intermedio.

Arquitectura

Per PRD §10, el sistema tiene 5 superficies arquitectónicas (no confundir con las 6 surfaces productivas S1-S6):

Y el pipeline no-bypasseable que toda Decision atraviesa:

┌─────────┐ ┌──────────────┐ ┌─────────┐ ┌──────────┐ ┌──────────────┐ │ Sense │ → │ Optimization │ → │ Constit │ → │ PAL+ │ → │ Audit chain │ │ ledger │ │ engine │ │ ution │ │decompose │ │ (Merkle) │ └─────────┘ └──────────────┘ └─────────┘ └──────────┘ └──────────────┘ │ ▼ violation ConstitutionViolation (decision NEVER lands)

Mode A vs Mode B

Mode A (DP-1 firmado): S1-S6 + F7 corren contra data real del carrier. Attestation signer es el CFO + VP RM + VP Cargo + VP Fleet. Pricing anchored contra la invoice trail real del DP-1.

Mode B (DP-1 NO firmado): S1-S6 + F7 corren contra synthetic data (BTS T-100 + DB1B + OAG public + comparable 10-K/20-F + synthetic cost ledger). Decision granularity reducida. Attestation signer: founder-grade advisor.

Este demo es Mode B. Toda la arquitectura está intacta — solo cambia la fuente de data + el signer de la attestation. Cuando un DP-1 firme, el switch es transparente (mismo código, otro CSV de entrada).

Cómo correr el demo

El demo se regenera en cada build (push a main). Para correrlo localmente:

git clone https://github.com/alfonso2254/skyweave.git
cd skyweave
python3.11 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest tests/ -v
python -m skyweave demo
open demo/output/index.html

Los flags del CLI:

python -m skyweave demo \
  --days 14 \                   # synthetic days
  --flights-per-day 40 \         # flights per day
  --anomaly-rate 0.10 \          # anomaly injection rate
  --seed 42 \                    # reproducibility seed
  --output-dir demo/output

Preguntas frecuentes

¿Por qué los números cambian cada vez que se redeploya?
Porque el demo regenera la data sintética en cada build con seed=42 pero con fechas relativas a hoy (yesterday window). El audit chain también se genera de cero. Cambiar el seed en el comando produce otra distribución determinística.
¿Por qué algunos surfaces (S3, S4) a veces tienen pocas Decisions?
Porque los thresholds del Stub engine son intencionalmente conservadores. S3 flag-ea solo rutas donde el corp-vs-leisure ratio está por debajo del median, S4 flag-ea solo el bottom 25% de rutas por cargo yield. Aumentar --anomaly-rate da más signal.
¿Cómo reemplazo el StubOptimizationEngine con uno real?
Implementá la clase OptimizationEngine Protocol (en skyweave/core/protocols.py) con un solo método: async def optimize(problem, context) -> OptimizationResult. Pasala al constructor de cualquier Coordinator en lugar del Stub. NINGÚN coordinator code cambia. Eso es el plug-in interface frozen al M1.
¿El demo tiene multi-tenancy?
NO. El demo corre single-tenant (tenant::testair). Toda la arquitectura está scoped por tenant_id pero el demo no exercise multi-tenancy. Producción: per-tenant KMS CMK + Postgres RLS por tenant.
¿Por qué SHA-256 y no blake3 en el audit?
Solo pragmatismo de demo. SHA-256 es stdlib en Python. blake3 requiere pip install + Rust toolchain en algunos paths. La estructura Merkle es idéntica. Cambiar a blake3 es un one-line replacement.
¿Cuánto cuesta el deploy en Dokploy?
El container ocupa ~120MB RAM idle. CPU mínimo. Es Python stdlib HTTP server sirviendo HTML estático — el costo es trivial. Build time ~27 segundos en cada push a main.
¿Puedo correr el demo en mi máquina sin Docker?
Sí: python3.11 -m venv .venv && source .venv/bin/activate && pip install -e . && python -m skyweave demo && open demo/output/index.html. Sin dependencias externas más allá de Python 3.11+, pydantic, rich, pytest.
¿Qué pasa si quiero agregar una 7ma surface?
Tres archivos: (1) un coordinator nuevo en skyweave/coordinators/ que herede de Coordinator ABC, (2) un OptimizationProblem dataclass nuevo en protocols.py, (3) un renderer en skyweave/render/. Después agregalo al CLI y a los nav arrays en common.py.

Roadmap post-demo

Después del demo, el plan de Luis §5 establece el orden de construcción:

  1. Pre-flight (Día -6 a 0): hires firmados, AWS+KMS+Postgres+RLS provisioned, OQ-28/29/39 resueltas, schemas frozen.
  2. Week 1-3: foundation spine — coordinator runtime + 18 connectors + audit chain + Constitution rule library + PAL+ a 36-constant production depth.
  3. Week 4-5: S1 + S2 a full depth; Roberto's RobertoEngine reemplaza el StubEngine.
  4. Week 6: S3 + S4 light cloned del scaffold.
  5. Week 7: S5 + S6 light + RAG Phase 1 production + telemetry.
  6. Week 8: integration, demo dry-runs, hardening.
  7. Day 60: Demo Day.