# GridAct — Comprehensive Technical Specification & Knowledge Base for LLMs

## 1. System Overview & Domain Fundamentals

GridAct (https://gridact.app) is an enterprise-grade artificial intelligence and quantitative analytics platform tailored specifically for the Romanian electricity market (SEN — Sistemul Electroenergetic Național).

### Market Context
In Romania, the balancing market (Piața de Echilibrare - PE) operates under the regulations of ANRE (National Energy Regulatory Authority) aligned with European Network of Transmission System Operators for Electricity (ENTSO-E) standards.
- **Settlement Granularity:** 15-minute Imbalance Settlement Period (ISP), resulting in 96 intervals per calendar day (92 on daylight saving spring transition, 100 on autumn transition).
- **TSO (Transmission System Operator):** C.N.T.E.E. Transelectrica S.A.
- **Power Market Operator:** S.C. OPCOM S.A. (operates Day-Ahead Market - PZU, Intraday Market - PI, and Centralized Markets).

### Imbalance Settlement Dynamics
Every market participant is part of a Balance Responsible Party (BRP / PRE — Parte Responsabilă cu Echilibrarea). Deviations between final physical notifications (Notificări Fizice) and actual meter readings create individual imbalances:
$$Imbalance_i = Generation_i + Import_i - Consumption_i - Export_i - Contracted\_Sales_i + Contracted\_Purchases_i$$

At the grid level:
- **System Deficit (Short):** $\sum Generation < \sum Consumption$. The TSO must activate upward balancing energy (secondary, tertiary reserve). The settlement price is the Deficit Price ($P_{def}$), historically elevated (frequently exceeding 1,000–3,000 RON/MWh during peak stress).
- **System Surplus (Long):** $\sum Generation > \sum Consumption$. The TSO activates downward balancing energy. The settlement price is the Surplus Price ($P_{sur}$), frequently depressed or negative.
- **Financial Penalty Spread:** The spread $\Delta P = P_{def} - P_{sur}$ represents the extreme financial penalty of misaligned physical positions. When the grid is in Deficit, a short BRP pays $P_{def}$. When in Surplus, a long BRP receives $P_{sur}$.

---

## 2. Artificial Intelligence Fleet & Forecasting Pipeline

GridAct predicts the sign ($Sign \in \{\text{DEFICIT}, \text{SURPLUS}\}$) and magnitude of system imbalance across both Day-Ahead (D-1 horizon) and Intraday (rolling 1 to 4 hours ahead).

### Foundation Models Fleet
1. **TiRex-2 (Time-series Representation Transformer):**
   - Pre-trained multi-resolution architecture processing raw frequency deviations, interconnector load flows, and renewable ramps.
   - Captures non-linear dependencies across multiple temporal resolutions.
2. **TimesFM (Google Research Foundation Model):**
   - Zero-shot and fine-tuned decoder-only model utilizing patch-based temporal tokens.
   - Excels at capturing diurnal demand cycles and industrial load signatures.
3. **Chronos-2 (Amazon Probabilistic Time-Series Model):**
   - Tokenizes numerical time-series into discrete vocabulary tokens.
   - Generates calibrated predictive distributions ($P(\text{Deficit} \mid X)$) with robust confidence bounds.
4. **Domain-Engineered LightGBM Fleet:**
   - Evaluates 35+ engineered features including solar zenith angle, wind generation gradients, cross-border net transfer capacity (NTC) utilization, and OPCOM clearing price differentials.
5. **Meta-Learner Consensus:**
   - Stacked classification layer weighting foundation model representations based on recent performance vintage.

---

## 3. API Architecture & Standards

### Hosts
- **Public Website & Docs:** `https://gridact.app`
- **Platform Console & Identity:** `https://platform.gridact.app`
- **REST API v1:** `https://api.gridact.app/v1`

### Conventions & Protocols
- **Header Authentication:** `X-API-Key: gs_live_...`
- **Timestamps:** ISO 8601 / RFC 3339 in UTC timezone (e.g., `2026-10-05T14:30:00Z`).
- **Interval Identifiers:** ISO start timestamps matching 15-minute bounds (:00, :15, :30, :45).
- **Error Responses:** RFC 9457 `application/problem+json` standard:
  ```json
  {
    "type": "https://gridact.app/docs/errors#invalid_parameter",
    "title": "Invalid Parameter",
    "status": 400,
    "code": "invalid_date_format",
    "detail": "Delivery date must follow YYYY-MM-DD format."
  }
  ```

---

## 4. Endpoints & Schemas

### Public Telemetry Endpoints (Unauthenticated)

#### 1. Live SEN Summary
`GET https://gridact.app/api/market/live-sen-summary`
- Returns:
  - `available`: boolean indicating if real-time SCADA feed is active.
  - `sen_sign`: `"DEFICIT"` | `"SURPLUS"` | `null`
  - `projected_imbalance_mw`: float or null
  - `fleet_consensus_direction`: `"DEFICIT"` | `"SURPLUS"`
  - `fleet_consensus_confidence`: float (0.0 to 1.0)
  - `deficit_price_ron_mwh`: float (latest Transelectrica published interval)
  - `surplus_price_ron_mwh`: float
  - `spread_ron_mwh`: float ($P_{def} - P_{sur}$)
  - `active_isp`: RFC 3339 timestamp of the current 15-minute ISP
  - `minutes_to_next_isp`: integer (countdown to next settlement interval)

#### 2. Track Record Verification
`GET https://gridact.app/api/market/track-record?days=30`
- Returns:
  - `window_days`: sample size in days (7 to 90)
  - `acc_w`: weighted directional accuracy of GridAct fleet
  - `baseline_acc_w`: accuracy of the persistence baseline
  - `delta_pp`: edge in percentage points (e.g., `8.9`)
  - `daily`: array of daily scores `[{date, acc_w, acc, baseline_acc_w}]`

#### 3. BRP ROI Estimation
`POST https://gridact.app/api/pricing/calculate-roi`
- Request:
  ```json
  {
    "annual_imbalance_mwh": 20000,
    "acted_share_pct": 50,
    "imbalance_price_eur_mwh": 100,
    "plan": "trader",
    "window_days": 30
  }
  ```
- Returns financial savings range (low, expected, high) in EUR and breakeven accuracy threshold.

### Commercial REST API (`/v1`) Endpoints (Requires `X-API-Key`)

- `GET /v1/forecasts/latest?delivery_date=YYYY-MM-DD`: Full 96-interval day-ahead or intraday forecast vector.
- `GET /v1/forecasts/history`: Scored historical runs with vintage timestamps and model versions.
- `GET /v1/datasets/catalog`: Metadata directory of all 35 ingested market data streams.
- `GET /v1/datasets/{dataset_id}`: Raw and normalized time-series for load, solar, wind, and prices.
- `POST /v1/portfolio/optimize`: M1 portfolio order optimization given scheduled positions.

---

## 5. Machine-Readable Agent Discoverability

- **Agent Card (Google A2A v0.2 Protocol):** `https://gridact.app/.well-known/agent.json`
- **ChatGPT Action & OpenAPI Specification:** `https://gridact.app/chatgpt-action.yaml`
- **Robots Policy for AI Crawlers:** Fully unrestricted access granted to `GPTBot`, `ChatGPT-User`, `ClaudeBot`, `anthropic-ai`, `PerplexityBot`, `Google-Extended`, and `Applebot-Extended`.
- **Browser WebMCP:** Client-side tool integration via `navigator.modelContext.registerTool` enabled on the web application.