AI & Energy Balancing Engine

The AI & Energy Balancing Engine combines conversational artificial intelligence, multimodal computer vision, and grid optimization algorithms to automate energy cooperative operations.

---

Functions Matrix

Function Name	Inbound Trigger	AI Model / Integration	Core Output
jarvis	User Voice / Text Query	LLM + Voice Processing Pipeline	Conversational JSON, Tool Execution, Synthesized Audio
ai-energy-balancer	Periodic Cron / Dispatch Trigger	Dynamic Balancing Algorithm	Battery Charge/Discharge Schedule, Surplus Sharing Matrix
process-declaration-ocr	Document Upload Event	Google Gemini Vision (Multimodal)	Structured JSON Form Data (PESEL, kWp, Meter IDs)
fetch-energy-news	Daily Scheduled Cron	LLM Summarization Pipeline	Curated Polish Energy Market Briefings (TGE / URE)

---

1. jarvis (Conversational Voice Assistant)

Architecture & Pipeline

jarvis acts as the multimodal AI engine communicating directly with the Planovi Flutter App.

sequenceDiagram
    autonumber
    actor User as Member / Manager
    participant App as Flutter Client
    participant Jarvis as jarvis Edge Function
    participant DB as PostgreSQL
    participant AI as LLM Provider

    User->>App: Speaks command ("Show today's solar generation")
    App->>Jarvis: POST /functions/v1/jarvis (Audio Base64 / Text + JWT)
    Jarvis->>Jarvis: Bulletproof Base64 Decoding & JWT Validation
    Jarvis->>DB: Fetch Caller Tenant Context (coop_id, role, live telemetry)
    Jarvis->>AI: Send Prompt + System Schema + Context + User Audio
    AI-->>Jarvis: Intent: "QUERY_TELEMETRY", Parameters: { timeframe: "today" }
    Jarvis->>DB: Execute Query: SELECT SUM(solar_kwh) FROM telemetry_hourly WHERE ...
    DB-->>Jarvis: Result: 42.8 kWh
    Jarvis->>AI: Synthesize conversational Polish response
    AI-->>Jarvis: "Dzisiaj Twoja spółdzielnia wyprodukowała 42,8 kWh."
    Jarvis-->>App: 200 OK { response_text, action_type, audio_payload }
    App->>User: Audio Playback & Screen Navigation

Request Contract

interface JarvisRequest {
  query?: string;              // Text prompt
  audio_base64?: string;       // Recorded audio blob (AAC / WAV)
  conversation_id?: string;   // Thread continuity
  context?: {
    current_screen?: string;   // E.g., "energy_dashboard"
    device_id?: string;
  };
}

Response Contract

interface JarvisResponse {
  success: boolean;
  response_text: string;
  intent: 'NAVIGATE' | 'QUERY_METRICS' | 'TRIGGER_ACTION' | 'INFO';
  action_payload?: {
    route?: string;
    params?: Record<string, unknown>;
  };
  audio_url?: string;
}

---

2. ai-energy-balancer

Algorithmic Purpose

Energy cooperatives under Polish OZE regulations achieve maximum economic benefit when internal generation is consumed instantaneously by members before being fed into the national distribution grid (minimizing grid distribution fees and maximizing self-consumption ratios).

Operational Workflow

1. Inputs:
   • Weather forecasts (Solar irradiance $W/m^2$, cloud cover percentage).
   • Historical consumption patterns (member load curves aggregated over the past 30 days).
   • Current Battery Energy Storage System (BESS) State-of-Charge (SoC %).
   • Dynamic spot electricity prices on Towarowa Giełda Energii (TGE).
2. Optimization Model:
   • Determines battery charging windows during peak solar generation or negative TGE prices.
   • Schedules battery discharging during peak tariff hours (e.g., 18:00–21:00).
   • Allocates virtual energy credits across members according to cooperative share allocations.

---

3. process-declaration-ocr

Gemini AI Multimodal Vision Integration

Processes scanned or photographed energy declaration documents (PDF, JPEG, PNG) uploaded by prospective or existing cooperative members.

flowchart LR
    Doc[Scanned Document] --> S3["Supabase Storage: declarations"]
    S3 --> OCR[process-declaration-ocr]
    OCR --> Gemini[Google Gemini Multimodal API]
    Gemini --> Extractor[Structured Entity Extractor]
    Extractor --> Validate["Regex & Checksum Validator"]
    Validate --> DB[Upsert member_declarations]

Extracted Field Schemas

• Personal / Entity Identifiers: Full Name, PESEL (with checksum verification), NIP, REGON.
• Point of Delivery (PPE): 18-character Polish Distribution System Operator identifier.
• Installation Parameters: Total PV capacity ($kW_p$), Inverter manufacturer/model, Phase count (1-phase / 3-phase), Storage capacity ($kWh$).
• Confidence Scoring: Each extracted field returns a confidence score (0.0–1.0). If any required field is below 0.85, the status is flagged as NEEDS_HUMAN_REVIEW.

---

4. fetch-energy-news

Daily Automated Workflow

1. Runs at 06:00 UTC via Supabase Cron.
2. Pulls recent regulatory announcements from Urząd Regulacji Energetyki (URE) and Polish energy exchange reports.
3. Uses LLM summarization to synthesize 3-bullet executive takeaways in Polish.
4. Stores items in coop_news_feed table and broadcasts real-time alerts to cooperative managers.