@iflow-mcp/kitfunso-luminus 0.2.0

package/dist/tools/rte-france.js

@@ -0,0 +1,147 @@
+import { z } from "zod";
+import { TtlCache, TTL } from "../lib/cache.js";
+const ECO2MIX_API = "https://odre.opendatasoft.com/api/explore/v2.1/catalog/datasets";
+const cache = new TtlCache();
+export const rteFranceSchema = z.object({
+    dataset: z
+        .enum(["generation", "consumption", "exchanges", "outages"])
+        .describe('"generation" = French real-time generation by source (nuclear, wind, solar, hydro, gas, etc.). ' +
+        '"consumption" = French electricity consumption (MW). ' +
+        '"exchanges" = Cross-border commercial exchanges with neighbours. ' +
+        '"outages" = French generation unavailability (nuclear outages drive EU prices).'),
+    date: z
+        .string()
+        .optional()
+        .describe("Date in YYYY-MM-DD format. Defaults to today."),
+});
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+async function fetchOdre(datasetId, where, limit = 24) {
+    const url = `${ECO2MIX_API}/${datasetId}/records?` +
+        `where=${encodeURIComponent(where)}&limit=${limit}&order_by=date_heure%20DESC`;
+    const cached = cache.get(url);
+    if (cached)
+        return cached.results;
+    const response = await fetch(url, {
+        headers: { Accept: "application/json", "User-Agent": "luminus-mcp/0.2" },
+    });
+    if (!response.ok) {
+        const body = await response.text();
+        throw new Error(`RTE/ODRE API returned ${response.status}: ${body.slice(0, 300)}`);
+    }
+    const json = await response.json();
+    cache.set(url, json, TTL.REALTIME);
+    return json.results ?? [];
+}
+async function fetchGeneration(date) {
+    const records = await fetchOdre("eco2mix-national-tr", `date_heure >= '${date}T00:00:00' AND date_heure <= '${date}T23:59:59'`, 48);
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const parsed = records.map((r) => {
+        const f = r.fields ?? r;
+        return {
+            timestamp: f.date_heure ?? "",
+            nuclear_mw: Math.round(Number(f.nucleaire ?? 0)),
+            wind_mw: Math.round(Number(f.eolien ?? 0)),
+            solar_mw: Math.round(Number(f.solaire ?? 0)),
+            hydro_mw: Math.round(Number(f.hydraulique ?? 0)),
+            gas_mw: Math.round(Number(f.gaz ?? 0)),
+            coal_mw: Math.round(Number(f.charbon ?? 0)),
+            bioenergy_mw: Math.round(Number(f.bioenergies ?? 0)),
+            total_mw: Math.round(Number(f.nucleaire ?? 0) +
+                Number(f.eolien ?? 0) +
+                Number(f.solaire ?? 0) +
+                Number(f.hydraulique ?? 0) +
+                Number(f.gaz ?? 0) +
+                Number(f.charbon ?? 0) +
+                Number(f.bioenergies ?? 0)),
+        };
+    });
+    return {
+        dataset: "generation",
+        source: "RTE France (eco2mix via ODRE)",
+        date,
+        records: parsed.slice(0, 24),
+        latest: parsed.length > 0 ? parsed[0] : null,
+    };
+}
+async function fetchConsumption(date) {
+    const records = await fetchOdre("eco2mix-national-tr", `date_heure >= '${date}T00:00:00' AND date_heure <= '${date}T23:59:59'`, 48);
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const parsed = records.map((r) => {
+        const f = r.fields ?? r;
+        return {
+            timestamp: f.date_heure ?? "",
+            consumption_mw: Math.round(Number(f.consommation ?? 0)),
+            forecast_mw: Math.round(Number(f.prevision_j ?? f.prevision_j1 ?? 0)),
+        };
+    });
+    return {
+        dataset: "consumption",
+        source: "RTE France (eco2mix via ODRE)",
+        date,
+        records: parsed.slice(0, 24),
+    };
+}
+async function fetchExchanges(date) {
+    const records = await fetchOdre("eco2mix-national-tr", `date_heure >= '${date}T00:00:00' AND date_heure <= '${date}T23:59:59'`, 48);
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const parsed = records.map((r) => {
+        const f = r.fields ?? r;
+        const gb = Number(f.ech_comm_angleterre ?? 0);
+        const es = Number(f.ech_comm_espagne ?? 0);
+        const it = Number(f.ech_comm_italie ?? 0);
+        const ch = Number(f.ech_comm_suisse ?? 0);
+        const de = Number(f.ech_comm_allemagne_belgique ?? 0);
+        return {
+            timestamp: f.date_heure ?? "",
+            gb_mw: Math.round(gb),
+            spain_mw: Math.round(es),
+            italy_mw: Math.round(it),
+            switzerland_mw: Math.round(ch),
+            germany_belgium_mw: Math.round(de),
+            net_mw: Math.round(gb + es + it + ch + de),
+        };
+    });
+    return {
+        dataset: "exchanges",
+        source: "RTE France (eco2mix via ODRE)",
+        date,
+        records: parsed.slice(0, 24),
+    };
+}
+async function fetchOutages(date) {
+    // Use REMIT-style outage data from ODRE if available
+    const records = await fetchOdre("registre-national-installation-production-stockage-electricite-agrege", `commune IS NOT NULL`, 30).catch(() => []);
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const parsed = records.slice(0, 20).map((r) => {
+        const f = r.fields ?? r;
+        return {
+            unit_name: f.nominstallation ?? f.nom ?? "Unknown",
+            fuel_type: f.filiere ?? f.combustible ?? "Unknown",
+            unavailable_mw: Math.round(Number(f.puismaxcharge ?? 0) - Number(f.puismaxrac ?? 0)),
+            available_mw: Math.round(Number(f.puismaxrac ?? 0)),
+            start_date: f.datamiseenservice ?? date,
+            end_date: "",
+            reason: f.regime ?? "",
+        };
+    });
+    return {
+        dataset: "outages",
+        source: "RTE France (ODRE)",
+        description: "French generation availability. For detailed REMIT outage data, " +
+            "see ENTSO-E get_outages with country=FR or REMIT UMM platforms.",
+        records: parsed,
+    };
+}
+export async function getRteFrance(params) {
+    const date = params.date ?? new Date().toISOString().slice(0, 10);
+    switch (params.dataset) {
+        case "generation":
+            return fetchGeneration(date);
+        case "consumption":
+            return fetchConsumption(date);
+        case "exchanges":
+            return fetchExchanges(date);
+        case "outages":
+            return fetchOutages(date);
+    }
+}

package/dist/tools/screen-site.d.ts

@@ -0,0 +1,50 @@
+import { z } from "zod";
+import { type GisSourceMetadata } from "../lib/gis-sources.js";
+/** EU member-state country codes supported for reduced screening. */
+export declare const EU_COUNTRY_CODES: Set<string>;
+export declare const screenSiteSchema: z.ZodObject<{
+    lat: z.ZodNumber;
+    lon: z.ZodNumber;
+    radius_km: z.ZodOptional<z.ZodNumber>;
+    country: z.ZodString;
+}, z.core.$strip>;
+type Verdict = "pass" | "warn" | "fail";
+interface VerdictFlag {
+    category: "terrain" | "grid" | "solar" | "constraints" | "agricultural_land" | "flood_risk" | "land_cover";
+    level: "warn" | "fail";
+    reason: string;
+}
+interface ScreenSiteVerdict {
+    overall: Verdict;
+    flags: VerdictFlag[];
+}
+interface ScreenSiteSourceMetadata {
+    terrain: GisSourceMetadata;
+    grid: GisSourceMetadata;
+    solar: GisSourceMetadata;
+    constraints: GisSourceMetadata;
+    agricultural_land?: GisSourceMetadata;
+    flood_risk?: GisSourceMetadata;
+    land_cover?: GisSourceMetadata;
+}
+interface ScreenSiteResult {
+    lat: number;
+    lon: number;
+    radius_km: number;
+    country: string;
+    terrain: any | null;
+    grid: any | null;
+    solar: any | null;
+    constraints: any | null;
+    agricultural_land: any | null;
+    flood_risk: any | null;
+    land_cover?: any | null;
+    verdict: ScreenSiteVerdict;
+    layers_available: string[];
+    layers_unavailable: Record<string, string>;
+    source_metadata: ScreenSiteSourceMetadata;
+    warnings?: string[];
+    disclaimer: string;
+}
+export declare function screenSite(params: z.infer<typeof screenSiteSchema>): Promise<ScreenSiteResult>;
+export {};

package/dist/tools/screen-site.js

@@ -0,0 +1,288 @@
+import { z } from "zod";
+import { getTerrainAnalysis } from "./terrain-analysis.js";
+import { getGridProximity } from "./grid-proximity.js";
+import { getSolarIrradiance } from "./solar.js";
+import { getLandConstraints } from "./land-constraints.js";
+import { getAgriculturalLand } from "./agricultural-land.js";
+import { getFloodRisk } from "./flood-risk.js";
+import { getLandCover } from "./land-cover.js";
+import { GIS_SOURCES } from "../lib/gis-sources.js";
+/** EU member-state country codes supported for reduced screening. */
+export const EU_COUNTRY_CODES = new Set([
+    "AT", "BE", "BG", "CY", "CZ", "DE", "DK", "EE", "ES", "FI",
+    "FR", "GR", "HR", "HU", "IE", "IT", "LT", "LU", "LV", "MT",
+    "NL", "PL", "PT", "RO", "SE", "SI", "SK",
+]);
+export const screenSiteSchema = z.object({
+    lat: z.number().describe("Latitude (-90 to 90). WGS84."),
+    lon: z.number().describe("Longitude (-180 to 180). WGS84."),
+    radius_km: z
+        .number()
+        .optional()
+        .describe("Search radius in km for grid and constraints (default 2, max 10)."),
+    country: z
+        .string()
+        .describe('ISO 3166-1 alpha-2 country code. "GB" and EU member states are supported.'),
+});
+// --- Heuristic thresholds ---
+/** Slope above this is flagged as a terrain warning (degrees). */
+const SLOPE_WARN_DEG = 10;
+/** Annual irradiance below this is flagged as a solar warning (kWh/m2). */
+const IRRADIANCE_WARN_KWH = 900;
+const DISCLAIMER = "This is an automated screening summary using public data. " +
+    "It is not investment advice, planning consent, or a final site feasibility assessment. " +
+    "Professional due diligence is required before any development decision.";
+// --- Heuristic evaluation ---
+function evaluateVerdict(terrain, grid, solar, constraints, agriculturalLand, floodRisk, landCover) {
+    const flags = [];
+    // Constraints: hard constraint = fail
+    if (constraints?.summary?.has_hard_constraint) {
+        flags.push({
+            category: "constraints",
+            level: "fail",
+            reason: `${constraints.summary.constraint_count} protected area(s) found within search radius`,
+        });
+    }
+    // Terrain: steep slope = warn
+    if (terrain && terrain.slope_deg > SLOPE_WARN_DEG) {
+        flags.push({
+            category: "terrain",
+            level: "warn",
+            reason: `Slope is ${terrain.slope_deg} deg (threshold: ${SLOPE_WARN_DEG} deg)`,
+        });
+    }
+    // Grid: no substations and no lines = warn
+    if (grid && grid.summary.nearest_substation_km === null && grid.summary.nearest_line_km === null) {
+        flags.push({
+            category: "grid",
+            level: "warn",
+            reason: "No substations or HV lines found within search radius",
+        });
+    }
+    // Solar: low irradiance = warn
+    if (solar && solar.annual_irradiance_kwh_m2 < IRRADIANCE_WARN_KWH) {
+        flags.push({
+            category: "solar",
+            level: "warn",
+            reason: `Annual irradiance is ${solar.annual_irradiance_kwh_m2} kWh/m2 (threshold: ${IRRADIANCE_WARN_KWH} kWh/m2)`,
+        });
+    }
+    // Agricultural land: BMV is a planning-risk warning, not a hard exclusion.
+    if (agriculturalLand?.bmv_status === "yes") {
+        flags.push({
+            category: "agricultural_land",
+            level: "warn",
+            reason: `Best and Most Versatile agricultural land flagged (${agriculturalLand.effective_grade ?? "unknown grade"})`,
+        });
+    }
+    else if (agriculturalLand?.bmv_status === "uncertain") {
+        flags.push({
+            category: "agricultural_land",
+            level: "warn",
+            reason: `Agricultural land classification is uncertain (${agriculturalLand.effective_grade ?? "unknown grade"}); Grade 3 may split into 3a or 3b`,
+        });
+    }
+    // Flood risk: Flood Zone 3 and flood storage areas are treated as fail,
+    // Flood Zone 2 as warn. This is a screening heuristic, not a legal rule.
+    if (floodRisk?.flood_storage_area) {
+        flags.push({
+            category: "flood_risk",
+            level: "fail",
+            reason: "Point intersects an Environment Agency flood storage area",
+        });
+    }
+    else if (floodRisk?.flood_zone === "3") {
+        flags.push({
+            category: "flood_risk",
+            level: "fail",
+            reason: "Point is in Flood Zone 3 (high probability floodplain)",
+        });
+    }
+    else if (floodRisk?.flood_zone === "2") {
+        flags.push({
+            category: "flood_risk",
+            level: "warn",
+            reason: "Point is in Flood Zone 2 (medium probability floodplain)",
+        });
+    }
+    // Land cover: CORINE planning exclusion = warn (EU only)
+    if (landCover?.land_cover?.is_planning_exclusion) {
+        flags.push({
+            category: "land_cover",
+            level: "warn",
+            reason: `Land cover type "${landCover.land_cover.label}" is typically excluded from PV/BESS development`,
+        });
+    }
+    // Overall: fail > warn > pass
+    let overall = "pass";
+    if (flags.some((f) => f.level === "warn"))
+        overall = "warn";
+    if (flags.some((f) => f.level === "fail"))
+        overall = "fail";
+    return { flags, overall };
+}
+// --- Main tool function ---
+export async function screenSite(params) {
+    const { lat, lon } = params;
+    const country = params.country.toUpperCase();
+    const radiusKm = params.radius_km ?? 2;
+    // Validation
+    const isEu = EU_COUNTRY_CODES.has(country);
+    if (country !== "GB" && !isEu) {
+        throw new Error(`Country "${params.country}" is not supported. "GB" and EU member states are available.`);
+    }
+    if (lat < -90 || lat > 90) {
+        throw new Error("Latitude must be between -90 and 90.");
+    }
+    if (lon < -180 || lon > 180) {
+        throw new Error("Longitude must be between -180 and 180.");
+    }
+    if (radiusKm <= 0 || radiusKm > 10) {
+        throw new Error("radius_km must be between 0 and 10.");
+    }
+    if (isEu) {
+        return screenSiteEu(lat, lon, radiusKm, country);
+    }
+    return screenSiteGb(lat, lon, radiusKm);
+}
+// --- GB flow (unchanged logic) ---
+async function screenSiteGb(lat, lon, radiusKm) {
+    // Run all sub-tools in parallel with allSettled for resilience
+    const [terrainResult, gridResult, solarResult, constraintsResult, agriculturalLandResult, floodRiskResult] = await Promise.allSettled([
+        getTerrainAnalysis({ lat, lon }),
+        getGridProximity({ lat, lon, radius_km: radiusKm }),
+        getSolarIrradiance({ lat, lon }),
+        getLandConstraints({ lat, lon, radius_km: radiusKm, country: "GB" }),
+        getAgriculturalLand({ lat, lon, country: "GB" }),
+        getFloodRisk({ lat, lon, country: "GB" }),
+    ]);
+    const warnings = [];
+    const terrain = terrainResult.status === "fulfilled" ? terrainResult.value : null;
+    if (terrainResult.status === "rejected") {
+        warnings.push(`terrain: ${terrainResult.reason instanceof Error ? terrainResult.reason.message : String(terrainResult.reason)}`);
+    }
+    const grid = gridResult.status === "fulfilled" ? gridResult.value : null;
+    if (gridResult.status === "rejected") {
+        warnings.push(`grid: ${gridResult.reason instanceof Error ? gridResult.reason.message : String(gridResult.reason)}`);
+    }
+    const solar = solarResult.status === "fulfilled" ? solarResult.value : null;
+    if (solarResult.status === "rejected") {
+        warnings.push(`solar: ${solarResult.reason instanceof Error ? solarResult.reason.message : String(solarResult.reason)}`);
+    }
+    const constraints = constraintsResult.status === "fulfilled" ? constraintsResult.value : null;
+    if (constraintsResult.status === "rejected") {
+        warnings.push(`constraints: ${constraintsResult.reason instanceof Error ? constraintsResult.reason.message : String(constraintsResult.reason)}`);
+    }
+    const agriculturalLand = agriculturalLandResult.status === "fulfilled" ? agriculturalLandResult.value : null;
+    if (agriculturalLandResult.status === "rejected") {
+        warnings.push(`agricultural_land: ${agriculturalLandResult.reason instanceof Error ? agriculturalLandResult.reason.message : String(agriculturalLandResult.reason)}`);
+    }
+    const floodRisk = floodRiskResult.status === "fulfilled" ? floodRiskResult.value : null;
+    if (floodRiskResult.status === "rejected") {
+        warnings.push(`flood_risk: ${floodRiskResult.reason instanceof Error ? floodRiskResult.reason.message : String(floodRiskResult.reason)}`);
+    }
+    // If all sub-queries failed, throw
+    if (terrain === null && grid === null && solar === null && constraints === null && agriculturalLand === null && floodRisk === null) {
+        throw new Error(`All sub-queries failed for screen_site: ${warnings.join("; ")}`);
+    }
+    const { flags, overall } = evaluateVerdict(terrain, grid, solar, constraints, agriculturalLand, floodRisk);
+    const result = {
+        lat,
+        lon,
+        radius_km: radiusKm,
+        country: "GB",
+        terrain,
+        grid,
+        solar,
+        constraints,
+        agricultural_land: agriculturalLand,
+        flood_risk: floodRisk,
+        verdict: { overall, flags },
+        layers_available: ["terrain", "grid", "solar", "constraints", "agricultural_land", "flood_risk"],
+        layers_unavailable: {
+            land_cover: "CORINE 2018 does not cover Great Britain. " +
+                "Agricultural land classification (agricultural_land layer) provides partial land-use context for England. " +
+                "A future integration with the UKCEH Land Cover Map could fill this gap.",
+        },
+        source_metadata: {
+            terrain: GIS_SOURCES["open-meteo-elevation"],
+            grid: GIS_SOURCES["overpass-osm"],
+            solar: GIS_SOURCES["pvgis"],
+            constraints: GIS_SOURCES["natural-england"],
+            agricultural_land: GIS_SOURCES["natural-england-alc"],
+            flood_risk: GIS_SOURCES["ea-flood-map"],
+        },
+        disclaimer: DISCLAIMER,
+    };
+    if (warnings.length > 0) {
+        result.warnings = warnings;
+    }
+    return result;
+}
+// --- EU flow (reduced layer set) ---
+async function screenSiteEu(lat, lon, radiusKm, country) {
+    const [terrainResult, gridResult, solarResult, constraintsResult, landCoverResult] = await Promise.allSettled([
+        getTerrainAnalysis({ lat, lon }),
+        getGridProximity({ lat, lon, radius_km: radiusKm }),
+        getSolarIrradiance({ lat, lon }),
+        getLandConstraints({ lat, lon, radius_km: radiusKm, country }),
+        getLandCover({ lat, lon, country }),
+    ]);
+    const warnings = [];
+    const terrain = terrainResult.status === "fulfilled" ? terrainResult.value : null;
+    if (terrainResult.status === "rejected") {
+        warnings.push(`terrain: ${terrainResult.reason instanceof Error ? terrainResult.reason.message : String(terrainResult.reason)}`);
+    }
+    const grid = gridResult.status === "fulfilled" ? gridResult.value : null;
+    if (gridResult.status === "rejected") {
+        warnings.push(`grid: ${gridResult.reason instanceof Error ? gridResult.reason.message : String(gridResult.reason)}`);
+    }
+    const solar = solarResult.status === "fulfilled" ? solarResult.value : null;
+    if (solarResult.status === "rejected") {
+        warnings.push(`solar: ${solarResult.reason instanceof Error ? solarResult.reason.message : String(solarResult.reason)}`);
+    }
+    const constraints = constraintsResult.status === "fulfilled" ? constraintsResult.value : null;
+    if (constraintsResult.status === "rejected") {
+        warnings.push(`constraints: ${constraintsResult.reason instanceof Error ? constraintsResult.reason.message : String(constraintsResult.reason)}`);
+    }
+    const landCover = landCoverResult.status === "fulfilled" ? landCoverResult.value : null;
+    if (landCoverResult.status === "rejected") {
+        warnings.push(`land_cover: ${landCoverResult.reason instanceof Error ? landCoverResult.reason.message : String(landCoverResult.reason)}`);
+    }
+    // If all sub-queries failed, throw
+    if (terrain === null && grid === null && solar === null && constraints === null && landCover === null) {
+        throw new Error(`All sub-queries failed for screen_site: ${warnings.join("; ")}`);
+    }
+    const { flags, overall } = evaluateVerdict(terrain, grid, solar, constraints, null, null, landCover);
+    const result = {
+        lat,
+        lon,
+        radius_km: radiusKm,
+        country,
+        terrain,
+        grid,
+        solar,
+        constraints,
+        agricultural_land: null,
+        flood_risk: null,
+        land_cover: landCover,
+        verdict: { overall, flags },
+        layers_available: ["terrain", "grid", "solar", "constraints", "land_cover"],
+        layers_unavailable: {
+            agricultural_land: "England only — no equivalent EU source",
+            flood_risk: "England only — no equivalent EU source",
+        },
+        source_metadata: {
+            terrain: GIS_SOURCES["open-meteo-elevation"],
+            grid: GIS_SOURCES["overpass-osm"],
+            solar: GIS_SOURCES["pvgis"],
+            constraints: GIS_SOURCES["eea-natura2000"],
+            land_cover: GIS_SOURCES["corine-land-cover"],
+        },
+        disclaimer: DISCLAIMER,
+    };
+    if (warnings.length > 0) {
+        result.warnings = warnings;
+    }
+    return result;
+}

package/dist/tools/site-revenue.d.ts

@@ -0,0 +1,50 @@
+import { z } from "zod";
+export declare const siteRevenueSchema: z.ZodObject<{
+    lat: z.ZodNumber;
+    lon: z.ZodNumber;
+    zone: z.ZodString;
+    technology: z.ZodEnum<{
+        bess: "bess";
+        pv: "pv";
+    }>;
+    capacity_mw: z.ZodOptional<z.ZodNumber>;
+    date: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+interface TerrainSnapshot {
+    elevation_m: number;
+    slope_deg: number;
+    aspect_cardinal: string;
+}
+interface PriceSnapshot {
+    date: string;
+    peak_eur_mwh: number;
+    off_peak_eur_mwh: number;
+    mean_eur_mwh: number;
+}
+interface SiteRevenueResult {
+    lat: number;
+    lon: number;
+    zone: string;
+    technology: "pv" | "bess";
+    capacity_mw: number;
+    terrain: TerrainSnapshot | null;
+    revenue: {
+        annual_generation_mwh?: number;
+        capacity_factor?: number;
+        capture_price_eur_mwh?: number;
+        daily_spread_eur_mwh?: number;
+        daily_revenue_eur?: number;
+        arb_signal?: string;
+        estimated_annual_revenue_eur: number;
+    };
+    price_snapshot: PriceSnapshot | null;
+    caveats: string[];
+    disclaimer: string;
+}
+/**
+ * Estimate annual PV generation revenue or BESS arbitrage revenue for a
+ * candidate site. Combines GIS data (solar resource, terrain) with market
+ * data (day-ahead prices, spread analysis).
+ */
+export declare function estimateSiteRevenue(params: z.infer<typeof siteRevenueSchema>): Promise<SiteRevenueResult>;
+export {};

package/dist/tools/site-revenue.js

@@ -0,0 +1,147 @@
+import { z } from "zod";
+import { getSolarIrradiance } from "./solar.js";
+import { getDayAheadPrices } from "./prices.js";
+import { getPriceSpreadAnalysis } from "./price-spread-analysis.js";
+import { getTerrainAnalysis } from "./terrain-analysis.js";
+export const siteRevenueSchema = z.object({
+    lat: z.number().describe("Latitude (-90 to 90). WGS84."),
+    lon: z.number().describe("Longitude (-180 to 180). WGS84."),
+    zone: z.string().describe("Bidding zone for price data (e.g. GB, DE, FR)."),
+    technology: z.enum(["pv", "bess"]).describe("PV (solar) or BESS (battery storage)."),
+    capacity_mw: z
+        .number()
+        .optional()
+        .describe("Installed capacity in MW (default 10)."),
+    date: z
+        .string()
+        .optional()
+        .describe("Price date for BESS arbitrage (YYYY-MM-DD, default today)."),
+});
+const DISCLAIMER = "This is a screening-level estimate only. It is not a financial model, investment advice, or a substitute for a bankable feasibility study.";
+const COMMON_CAVEATS = [
+    "Revenue estimate uses a single day's price curve, not historical averages",
+    "No degradation, curtailment, or network losses modeled",
+    "Grid connection costs are not included",
+];
+const PV_CAVEATS = [
+    "Capture price uses daylight hours (07:00-19:00) as a simple proxy",
+];
+const BESS_CAVEATS = [
+    "Arbitrage assumes optimal dispatch with perfect foresight",
+];
+/** Round to 2 decimal places. */
+function round2(n) {
+    return Math.round(n * 100) / 100;
+}
+/**
+ * Estimate annual PV generation revenue or BESS arbitrage revenue for a
+ * candidate site. Combines GIS data (solar resource, terrain) with market
+ * data (day-ahead prices, spread analysis).
+ */
+export async function estimateSiteRevenue(params) {
+    const { lat, lon, zone, technology } = params;
+    const capacity_mw = params.capacity_mw ?? 10;
+    const date = params.date ?? new Date().toISOString().slice(0, 10);
+    if (technology === "pv") {
+        return estimatePvRevenue({ lat, lon, zone, capacity_mw, date });
+    }
+    return estimateBessRevenue({ lat, lon, zone, capacity_mw, date });
+}
+async function estimatePvRevenue(p) {
+    // Fire all three requests in parallel; terrain is non-critical.
+    const [solarResult, pricesResult, terrainResult] = await Promise.allSettled([
+        getSolarIrradiance({ lat: p.lat, lon: p.lon }),
+        getDayAheadPrices({ zone: p.zone, start_date: p.date }),
+        getTerrainAnalysis({ lat: p.lat, lon: p.lon }),
+    ]);
+    // Solar is required.
+    if (solarResult.status === "rejected") {
+        throw new Error(`Solar irradiance lookup failed: ${solarResult.reason instanceof Error ? solarResult.reason.message : String(solarResult.reason)}`);
+    }
+    // Price data is required.
+    if (pricesResult.status === "rejected") {
+        throw new Error(`Day-ahead price lookup failed: ${pricesResult.reason instanceof Error ? pricesResult.reason.message : String(pricesResult.reason)}`);
+    }
+    const solar = solarResult.value;
+    const prices = pricesResult.value;
+    const terrain = terrainResult.status === "fulfilled" ? terrainResult.value : null;
+    // annual_generation_mwh = capacity_mw * 1000 * (annual_yield_kwh / 1000)
+    // annual_yield_kwh is per 1 kWp, so for capacity_mw MW:
+    const annual_generation_mwh = round2(p.capacity_mw * 1000 * (solar.annual_yield_kwh / 1000));
+    // Capacity factor: actual generation / (capacity * 8760 hours)
+    const capacity_factor = round2(annual_generation_mwh / (p.capacity_mw * 8760));
+    // Capture price: weighted average of daylight hours (7-19)
+    const daylightPrices = prices.prices.filter((pp) => pp.hour >= 7 && pp.hour <= 19);
+    const capture_price_eur_mwh = daylightPrices.length > 0
+        ? round2(daylightPrices.reduce((s, pp) => s + pp.price_eur_mwh, 0) / daylightPrices.length)
+        : prices.stats.mean;
+    // Annual revenue in EUR. annual_generation_mwh is already in MWh.
+    const estimated_annual_revenue_eur = round2(annual_generation_mwh * capture_price_eur_mwh);
+    const price_snapshot = {
+        date: prices.start_date,
+        peak_eur_mwh: prices.stats.max,
+        off_peak_eur_mwh: prices.stats.min,
+        mean_eur_mwh: prices.stats.mean,
+    };
+    return {
+        lat: p.lat,
+        lon: p.lon,
+        zone: p.zone.toUpperCase(),
+        technology: "pv",
+        capacity_mw: p.capacity_mw,
+        terrain: terrain
+            ? { elevation_m: terrain.elevation_m, slope_deg: terrain.slope_deg, aspect_cardinal: terrain.aspect_cardinal }
+            : null,
+        revenue: {
+            annual_generation_mwh,
+            capacity_factor,
+            capture_price_eur_mwh,
+            estimated_annual_revenue_eur,
+        },
+        price_snapshot,
+        caveats: [...COMMON_CAVEATS, ...PV_CAVEATS],
+        disclaimer: DISCLAIMER,
+    };
+}
+// ---------------------------------------------------------------------------
+// BESS revenue
+// ---------------------------------------------------------------------------
+async function estimateBessRevenue(p) {
+    const [spreadResult, terrainResult] = await Promise.allSettled([
+        getPriceSpreadAnalysis({ zone: p.zone, date: p.date, efficiency: 0.88, cycles: 2 }),
+        getTerrainAnalysis({ lat: p.lat, lon: p.lon }),
+    ]);
+    // Spread is required.
+    if (spreadResult.status === "rejected") {
+        throw new Error(`Price spread analysis failed: ${spreadResult.reason instanceof Error ? spreadResult.reason.message : String(spreadResult.reason)}`);
+    }
+    const spread = spreadResult.value;
+    const terrain = terrainResult.status === "fulfilled" ? terrainResult.value : null;
+    const daily_revenue_eur = round2(spread.revenuePerMwDay * p.capacity_mw);
+    const estimated_annual_revenue_eur = round2(daily_revenue_eur * 365);
+    const price_snapshot = {
+        date: spread.date,
+        peak_eur_mwh: spread.peakPrice,
+        off_peak_eur_mwh: spread.offPeakPrice,
+        mean_eur_mwh: round2((spread.peakPrice + spread.offPeakPrice) / 2),
+    };
+    return {
+        lat: p.lat,
+        lon: p.lon,
+        zone: p.zone.toUpperCase(),
+        technology: "bess",
+        capacity_mw: p.capacity_mw,
+        terrain: terrain
+            ? { elevation_m: terrain.elevation_m, slope_deg: terrain.slope_deg, aspect_cardinal: terrain.aspect_cardinal }
+            : null,
+        revenue: {
+            daily_spread_eur_mwh: spread.netSpread,
+            daily_revenue_eur,
+            arb_signal: spread.signal,
+            estimated_annual_revenue_eur,
+        },
+        price_snapshot,
+        caveats: [...COMMON_CAVEATS, ...BESS_CAVEATS],
+        disclaimer: DISCLAIMER,
+    };
+}