Relevant source files

The following files were used as context for generating this wiki page: - [frontend/src/app/api/zl/brief/route.ts](https://github.com/zincdigitalofmiami/ZINC-Fusion-V15/blob/main/frontend/src/app/api/zl/brief/route.ts) - [frontend/src/lib/services/narrative-service.ts](https://github.com/zincdigitalofmiami/ZINC-Fusion-V15/blob/main/frontend/src/lib/services/narrative-service.ts) - [frontend/src/lib/ai-intelligence.ts](https://github.com/zincdigitalofmiami/ZINC-Fusion-V15/blob/main/frontend/src/lib/ai-intelligence.ts) - [AGENTS.md](https://github.com/zincdigitalofmiami/ZINC-Fusion-V15/blob/main/AGENTS.md) - [Docs/zinc-fusion-v15-preview.html](https://github.com/zincdigitalofmiami/ZINC-Fusion-V15/blob/main/Docs/zinc-fusion-v15-preview.html) - [README.md](https://github.com/zincdigitalofmiami/ZINC-Fusion-V15/blob/main/README.md)

# Vegas Intel & Procurement The **Vegas Intel & Procurement** module is a specialized decision-support layer within the ZINC-Fusion-V15 system, tailored for US Oil Solutions (Las Vegas, NV). Its primary purpose is to translate complex quantitative soybean oil (ZL) futures forecasts into actionable intelligence for bulk procurement timing and hedging decisions. The system provides probabilistic multi-horizon forecasts (1W/1M/3M/6M) to determine when to lock in futures and how much to purchase. Sources: [AGENTS.md:5-7](), [README.md:32-37](), [frontend/src/app/api/zl/brief/route.ts:5-10]() The module serves as a "Sales Command Center" and "Procurement Posture" engine, utilizing 11 specialist models (the "Big-11") and a core AutoGluon ensemble to generate a unified market outlook. It specifically addresses regional demand spikes (e.g., CES, UFC events) and translates technical indicators like crush margins and trade policy into plain-English recommendations such as "BUY NOW" or "WAIT". Sources: [README.md:20-25](), [Docs/zinc-fusion-v15-preview.html:1208-1212](), [frontend/src/lib/services/narrative-service.ts:40-60]() ## System Architecture and Data Flow The Vegas Intel system operates as an L5-level synthesis engine that aggregates data from multiple underlying schemas (`mkt`, `econ`, `alt`, `forecasts`, and `analytics`) to produce a "Vegas Brief." ```mermaid flowchart TD subgraph Data_Layer [Data Schemas] A[mkt.futures_1d] B[econ.vol_indices_1d] C[analytics.board_crush_1d] D[forecasts.production_1d] end subgraph Logic_Layer [Processing Services] E[VixService] F[CrushService] G[NarrativeService] H[AI Intelligence] end subgraph Output_Layer [Vegas Interfaces] I[Procurement Brief API] J[Vegas Intel Dashboard] end A & B & C --> E & F E & F & D --> G & H G & H --> I I --> J ``` The diagram above shows the flow from raw market/economic data through specialized services to the final Vegas Intel dashboard. Sources: [frontend/src/app/api/zl/brief/route.ts:13-16](), [AGENTS.md:22-25](), [frontend/src/lib/ai-intelligence.ts:10-18]() ### Key Data Structures The system relies on a consolidated `VegasBrief` interface to provide a single source of truth for the frontend dashboard. | Component | Type | Description | | :--- | :--- | :--- | | `recommendation` | Enum | Actionable advice: `BUY NOW`, `WAIT`, `NORMAL SCHEDULE`, `LOCK IN COVERAGE`, or `CHECK DATA`. | | `price` | Object | Includes current price, previous close, change percentages, and weekly high/low. | | `forecasts` | Array | 1W, 1M, 1Q, and 6M horizons with target P30/P50/P70 bands. | | `drivers` | Array | Scores for Markets (VIX), Crush, China, and Trade (Tariff). | | `dataQuality` | String | Indicator of data freshness and availability: `good`, `partial`, or `poor`. | Sources: [frontend/src/app/api/zl/brief/route.ts:54-94]() ## Procurement Posture Logic The "Procurement Posture" is determined through a scoring algorithm that weighs four primary market drivers. These scores (0-100) are averaged to produce an overall market pressure rating. ### Scoring Thresholds and Recommendations The `NarrativeService` and `brief` API route use the following logic to generate recommendations: * **WAIT / BEARISH (Score >= 65-70):** Multiple red flags; markets are in panic or trade policy uncertainty is high. * **CAUTION (Score 55-65):** Mixed signals; recommendation is to "Keep Powder Dry." * **NORMAL SCHEDULE (Score 40-55):** Balanced market; buy on schedule. * **LOCK IN COVERAGE / BULLISH (Score < 40):** Favorable window; conditions suggest covering needs. Sources: [frontend/src/lib/services/narrative-service.ts:40-60](), [frontend/src/app/api/zl/brief/route.ts:328-340](), [frontend/src/lib/ai-intelligence.ts:80-95]() ### Specialist Driver Integration The system tracks "The Big-11" specialist buckets, with four key drivers highlighted in the Vegas Intel view: | Driver | Metric Source | Impact Logic | | :--- | :--- | :--- | | **Markets** | VIX (Fear Index) | High VIX (>25-30) triggers "Panic" status and fund liquidation risks. | | **Crush** | Board Crush Margin | Tight margins (<$1.25/bu) signal potential supply tightening as processors slow down. | | **China** | CNY/USD Rate | Weak Yuan (>7.30) makes Brazilian soy more competitive, hurting US export demand. | | **Trade** | TPU (Trade Policy Uncertainty) | High TPU (>200) indicates trade war risks and export demand cliffs. | Sources: [frontend/src/lib/ai-intelligence.ts:65-75](), [frontend/src/lib/services/narrative-service.ts:120-155](), [frontend/src/app/api/zl/brief/route.ts:175-210]() ## Multi-Horizon Forecasting The module consumes probabilistic multi-step forecasts from the `forecasts.production_1d` table, representing horizons of 5, 21, 63, and 126 days. ```mermaid sequenceDiagram participant API as Brief API Route participant DB as Production Forecasts participant Logic as Narrative Engine API->>DB: SELECT p30, p50, p70 FROM forecasts.production_1d DB-->>API: Returns probabilistic bands API->>Logic: Calculate expected change % vs current price Logic-->>API: Map change % to Direction (UP/DOWN/FLAT) API-->>API: Enforce Quantile Monotonicity (P10 < P30 < P50 < P70 < P90) ``` The sequence above illustrates how the API retrieves and processes model outputs to determine price direction for different time horizons. Sources: [frontend/src/app/api/zl/brief/route.ts:133-155](), [README.md:70-80](), [cubic.yaml:126-135]() ## Event-Driven Intelligence (Vegas Specific) Unique to the Vegas Intel module is the integration of local event data to forecast demand spikes. This is visible in the "Sales Command Center" view, which tracks: * **Major Conventions:** CES (Consumer Electronics Show) with ~140K attendees is modeled with a 2.4x demand impact. * **Sporting Events:** UFC events (e.g., UFC 305) and F1 Grand Prix are tracked for their specific impact on hotel/casino fryer oil consumption. * **Upsell Targets:** Customer cards (e.g., MGM Grand, Resorts World) are prioritized based on their alignment with these upcoming events. Sources: [Docs/zinc-fusion-v15-preview.html:1213-1250](), [Docs/zinc-fusion-v15-preview.html:1410-1440]() ## Data Quality and Freshness Gate To prevent "silent data corruption," the module implements an "anti-bullshit gate." The API route checks the `as_of_date` of all incoming drivers. If data is more than 3 days old, it is flagged as `stale`, and the system generates a warning in the `dataIssues` array. If more than 3 drivers are missing or stale, the recommendation is force-overridden to `CHECK DATA`. Sources: [frontend/src/app/api/zl/brief/route.ts:15-18](), [frontend/src/app/api/zl/brief/route.ts:182-192](), [frontend/src/app/api/zl/brief/route.ts:328-332]() The system also monitors **Quantile Monotonicity**. Uncertainty ranges (P10-P90) must widen with longer horizons; if a 5-day range is wider than a 3-month range, the model is considered broken and the data is flagged. Sources: [cubic.yaml:126-132]() ## Summary The Vegas Intel & Procurement system bridge the gap between complex quantitative ML models and real-world commodity purchasing. By aggregating specialist signals—ranging from global macro volatility to specific Las Vegas event schedules—the system provides a centralized "Brief" that guides US Oil Solutions in navigating the volatile soybean oil futures market. Its focus on data integrity, through staleness checks and monotonicity guards, ensures that the resulting procurement recommendations are both mathematically defensible and actionable. Sources: [frontend/src/app/api/zl/brief/route.ts:390-410](), [README.md:12-18](), [AGENTS.md:5-10]()