enerlytics-ai 0.1.0__tar.gz

enerlytics_ai-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Huseyin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

enerlytics_ai-0.1.0/PKG-INFO

@@ -0,0 +1,142 @@
+Metadata-Version: 2.4
+Name: enerlytics-ai
+Version: 0.1.0
+Summary: AI platform for predicting renewable energy investment opportunities using meteorological data, machine learning and financial analytics.
+Author-email: Huseyin Kucukogul <huseyinkucukogulcontact@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2026 Huseyin
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/Kucukogul/enerlytics.ai
+Project-URL: Repository, https://github.com/Kucukogul/enerlytics.ai
+Keywords: energy,AI,machine learning,renewable energy,solar,analytics
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastapi>=0.110.0
+Requires-Dist: uvicorn>=0.27.0
+Requires-Dist: pandas>=2.1.0
+Requires-Dist: numpy>=1.26.0
+Requires-Dist: requests>=2.31.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: pyyaml>=6.0.0
+Requires-Dist: pyarrow>=14.0.0
+Requires-Dist: shapely>=2.0.0
+Requires-Dist: tqdm>=4.66.0
+Requires-Dist: tenacity>=8.2.0
+Dynamic: license-file
+
+# Enerlytics.ai
+
+AI platform for predicting renewable energy investment opportunities in Turkiye.
+
+Combines meteorological data, machine learning and financial analytics to estimate solar energy potential and evaluate project feasibility at any location in Turkiye.
+
+---
+
+## Setup
+
+```bash
+python -m venv .venv && source .venv/bin/activate
+pip install -r requirements.txt
+cp .env.example .env
+uvicorn enerlytics_ai.app.main:app --app-dir src --reload
+```
+
+API → `http://127.0.0.1:8000` · Docs → `http://127.0.0.1:8000/docs`
+
+---
+
+## Quick Start
+
+```bash
+# Site analysis
+curl -X POST "http://127.0.0.1:8000/api/v1/analyze-site" \
+  -H "Content-Type: application/json" \
+  -d '{"latitude": 39.9208, "longitude": 32.8541}'
+
+# Historical solar data
+curl -X POST "http://127.0.0.1:8000/api/v1/historical-solar" \
+  -H "Content-Type: application/json" \
+  -d '{"latitude": 39.9208, "longitude": 32.8541, "start_year": 2015, "end_year": 2024}'
+```
+
+---
+
+## Structure
+
+```
+enerlytics.ai/
+│
+├── src/enerlytics_ai/
+│   ├── api/
+│   │   └── routes.py                        # API route definitions
+│   ├── app/
+│   │   ├── main.py                          # FastAPI app entry point
+│   │   └── config.py                        # app configuration
+│   ├── models/
+│   │   ├── energy_model.py                  # solar energy estimation model
+│   │   └── lcoe_model.py                    # LCOE financial model
+│   ├── services/
+│   │   ├── pvgis_data_service.py            # PVGIS API integration
+│   │   ├── solar_data_service.py            # solar data fetching & caching
+│   │   └── solar_model_service.py           # model inference service
+│   └── utils/
+│       ├── constants.py                     # shared constants
+│       └── helpers.py                       # utility functions
+│
+├── pipelines/
+│   ├── province_scan.py                     # scans all 81 TR provinces
+│   └── scoring.py                           # investment scoring logic
+│
+├── analysis/
+│   ├── notebooks/
+│   │   ├── 01_eda.ipynb                     # exploratory data analysis
+│   │   └── 02_turkiye_geneli_eda.ipynb      # Turkiye-wide solar EDA
+│   └── outputs/
+│       ├── monthly_stats.csv
+│       ├── tr81_monthly_risk_band.csv
+│       └── tr81_province_ranking.csv        # province investment ranking
+│
+├── data/
+│   ├── raw/pvgis/                           # raw PVGIS API responses
+│   └── processed/                           # cleaned province datasets
+│
+├── scripts/
+│   └── fetch_pvgis_81_seriescalc.py         # data collection script
+│
+└── tests/
+    ├── unit/
+    │   └── test_scoring.py
+    └── integration/
+        └── test_province_pipeline.py
+```
+
+---
+
+**Author:** Huseyin Kucukogul · MIT License

enerlytics_ai-0.1.0/README.md

@@ -0,0 +1,89 @@
+# Enerlytics.ai
+
+AI platform for predicting renewable energy investment opportunities in Turkiye.
+
+Combines meteorological data, machine learning and financial analytics to estimate solar energy potential and evaluate project feasibility at any location in Turkiye.
+
+---
+
+## Setup
+
+```bash
+python -m venv .venv && source .venv/bin/activate
+pip install -r requirements.txt
+cp .env.example .env
+uvicorn enerlytics_ai.app.main:app --app-dir src --reload
+```
+
+API → `http://127.0.0.1:8000` · Docs → `http://127.0.0.1:8000/docs`
+
+---
+
+## Quick Start
+
+```bash
+# Site analysis
+curl -X POST "http://127.0.0.1:8000/api/v1/analyze-site" \
+  -H "Content-Type: application/json" \
+  -d '{"latitude": 39.9208, "longitude": 32.8541}'
+
+# Historical solar data
+curl -X POST "http://127.0.0.1:8000/api/v1/historical-solar" \
+  -H "Content-Type: application/json" \
+  -d '{"latitude": 39.9208, "longitude": 32.8541, "start_year": 2015, "end_year": 2024}'
+```
+
+---
+
+## Structure
+
+```
+enerlytics.ai/
+│
+├── src/enerlytics_ai/
+│   ├── api/
+│   │   └── routes.py                        # API route definitions
+│   ├── app/
+│   │   ├── main.py                          # FastAPI app entry point
+│   │   └── config.py                        # app configuration
+│   ├── models/
+│   │   ├── energy_model.py                  # solar energy estimation model
+│   │   └── lcoe_model.py                    # LCOE financial model
+│   ├── services/
+│   │   ├── pvgis_data_service.py            # PVGIS API integration
+│   │   ├── solar_data_service.py            # solar data fetching & caching
+│   │   └── solar_model_service.py           # model inference service
+│   └── utils/
+│       ├── constants.py                     # shared constants
+│       └── helpers.py                       # utility functions
+│
+├── pipelines/
+│   ├── province_scan.py                     # scans all 81 TR provinces
+│   └── scoring.py                           # investment scoring logic
+│
+├── analysis/
+│   ├── notebooks/
+│   │   ├── 01_eda.ipynb                     # exploratory data analysis
+│   │   └── 02_turkiye_geneli_eda.ipynb      # Turkiye-wide solar EDA
+│   └── outputs/
+│       ├── monthly_stats.csv
+│       ├── tr81_monthly_risk_band.csv
+│       └── tr81_province_ranking.csv        # province investment ranking
+│
+├── data/
+│   ├── raw/pvgis/                           # raw PVGIS API responses
+│   └── processed/                           # cleaned province datasets
+│
+├── scripts/
+│   └── fetch_pvgis_81_seriescalc.py         # data collection script
+│
+└── tests/
+    ├── unit/
+    │   └── test_scoring.py
+    └── integration/
+        └── test_province_pipeline.py
+```
+
+---
+
+**Author:** Huseyin Kucukogul · MIT License

enerlytics_ai-0.1.0/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "enerlytics-ai"
+version = "0.1.0"
+description = "AI platform for predicting renewable energy investment opportunities using meteorological data, machine learning and financial analytics."
+readme = "README.md"
+license = { file = "LICENSE" }
+authors = [{ name = "Huseyin Kucukogul", email = "huseyinkucukogulcontact@gmail.com" }]
+requires-python = ">=3.10"
+keywords = ["energy", "AI", "machine learning", "renewable energy", "solar", "analytics"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+    "fastapi>=0.110.0",
+    "uvicorn>=0.27.0",
+    "pandas>=2.1.0",
+    "numpy>=1.26.0",
+    "requests>=2.31.0",
+    "python-dotenv>=1.0.0",
+    "pyyaml>=6.0.0",
+    "pyarrow>=14.0.0",
+    "shapely>=2.0.0",
+    "tqdm>=4.66.0",
+    "tenacity>=8.2.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/Kucukogul/enerlytics.ai"
+Repository = "https://github.com/Kucukogul/enerlytics.ai"
+
+[tool.setuptools.packages.find]
+where = ["src"]

enerlytics_ai-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

enerlytics_ai-0.1.0/src/enerlytics_ai/api/__init__.py

@@ -0,0 +1 @@
+

enerlytics_ai-0.1.0/src/enerlytics_ai/api/routes.py

@@ -0,0 +1,105 @@
+from fastapi import APIRouter, HTTPException
+from pydantic import BaseModel, Field
+from requests import exceptions as requests_exceptions
+
+from enerlytics_ai.services.solar_data_service import fetch_historical_monthly_ghi_kwh_m2
+from enerlytics_ai.services.solar_model_service import analyze_site
+
+router = APIRouter()
+
+
+class AnalyzeRequest(BaseModel):
+    latitude: float = Field(..., ge=-90, le=90)
+    longitude: float = Field(..., ge=-180, le=180)
+
+
+class AnalyzeResponse(BaseModel):
+    data_source: str
+    annual_energy_kwh: float
+    estimated_lcoe: float
+    lcoe_try_kwh: float
+    simple_payback_years: float | None
+    summary: str
+
+
+class HistoricalSolarRequest(BaseModel):
+    latitude: float = Field(..., ge=35.0, le=43.0)
+    longitude: float = Field(..., ge=25.0, le=46.0)
+    start_year: int = Field(..., ge=1984, le=2100)
+    end_year: int = Field(..., ge=1984, le=2100)
+
+
+class HistoricalMonthlyPoint(BaseModel):
+    year: int
+    month: int
+    ghi_kwh_m2_day: float
+
+
+class HistoricalAnnualSummaryPoint(BaseModel):
+    year: int
+    total_ghi_kwh_m2_day: float
+    average_ghi_kwh_m2_day: float
+
+
+class HistoricalSolarResponse(BaseModel):
+    data_source: str
+    parameter: str
+    latitude: float
+    longitude: float
+    start_year: int
+    end_year: int
+    monthly_series: list[HistoricalMonthlyPoint]
+    annual_summary: list[HistoricalAnnualSummaryPoint]
+
+
+@router.post("/api/v1/analyze-site", response_model=AnalyzeResponse)
+def analyze(payload: AnalyzeRequest) -> AnalyzeResponse:
+    try:
+        result = analyze_site(payload.latitude, payload.longitude)
+    except requests_exceptions.Timeout as exc:
+        raise HTTPException(status_code=504, detail="Upstream solar data request timed out.") from exc
+    except requests_exceptions.ConnectionError as exc:
+        raise HTTPException(status_code=503, detail="Could not connect to upstream solar data provider.") from exc
+    except requests_exceptions.HTTPError as exc:
+        raise HTTPException(status_code=502, detail="Upstream solar data provider returned an error.") from exc
+    except requests_exceptions.RequestException as exc:
+        raise HTTPException(status_code=502, detail="Unexpected upstream request error during analysis.") from exc
+    except ValueError as exc:
+        raise HTTPException(status_code=422, detail=f"Analysis validation failed: {exc}") from exc
+    return AnalyzeResponse(**result)
+
+
+@router.post("/api/v1/historical-solar", response_model=HistoricalSolarResponse)
+def historical_solar(payload: HistoricalSolarRequest) -> HistoricalSolarResponse:
+    try:
+        result = fetch_historical_monthly_ghi_kwh_m2(
+            latitude=payload.latitude,
+            longitude=payload.longitude,
+            start_year=payload.start_year,
+            end_year=payload.end_year,
+        )
+    except requests_exceptions.Timeout as exc:
+        raise HTTPException(status_code=504, detail="Upstream solar data request timed out.") from exc
+    except requests_exceptions.ConnectionError as exc:
+        raise HTTPException(status_code=503, detail="Could not connect to upstream solar data provider.") from exc
+    except requests_exceptions.HTTPError as exc:
+        status_code = exc.response.status_code if exc.response is not None else "unknown"
+        raise HTTPException(
+            status_code=502,
+            detail=f"Upstream solar data provider returned an error (status: {status_code}).",
+        ) from exc
+    except requests_exceptions.RequestException as exc:
+        raise HTTPException(status_code=502, detail="Unexpected upstream request error during historical fetch.") from exc
+    except ValueError as exc:
+        raise HTTPException(status_code=422, detail=f"Historical solar validation failed: {exc}") from exc
+
+    return HistoricalSolarResponse(
+        data_source=result["source"],
+        parameter=result["parameter"],
+        latitude=result["latitude"],
+        longitude=result["longitude"],
+        start_year=result["start_year"],
+        end_year=result["end_year"],
+        monthly_series=result["monthly_series"],
+        annual_summary=result["annual_summary"],
+    )

enerlytics_ai-0.1.0/src/enerlytics_ai/app/__init__.py

@@ -0,0 +1 @@
+

enerlytics_ai-0.1.0/src/enerlytics_ai/app/config.py

@@ -0,0 +1,47 @@
+import os
+from dataclasses import dataclass
+
+from dotenv import load_dotenv
+
+load_dotenv()
+
+
+@dataclass(frozen=True)
+class Settings:
+    solar_data_provider: str = os.getenv("SOLAR_DATA_PROVIDER", "nasa").lower()
+    nasa_power_base_url: str = os.getenv(
+        "NASA_POWER_BASE_URL",
+        "https://power.larc.nasa.gov/api/temporal/climatology/point",
+    )
+    nasa_power_monthly_base_url: str = os.getenv(
+        "NASA_POWER_MONTHLY_BASE_URL",
+        "https://power.larc.nasa.gov/api/temporal/monthly/point",
+    )
+    nasa_power_parameter: str = os.getenv("NASA_POWER_PARAMETER", "ALLSKY_SFC_SW_DWN")
+    nasa_power_community: str = os.getenv("NASA_POWER_COMMUNITY", "RE")
+    nasa_power_format: str = os.getenv("NASA_POWER_FORMAT", "JSON")
+    request_timeout_seconds: int = int(os.getenv("REQUEST_TIMEOUT_SECONDS", "15"))
+    enable_nasa_cache: bool = os.getenv("ENABLE_NASA_CACHE", "true").lower() == "true"
+    nasa_cache_dir: str = os.getenv("NASA_CACHE_DIR", "data/raw/nasa_power")
+    nasa_cache_ttl_hours: int = int(os.getenv("NASA_CACHE_TTL_HOURS", "720"))
+    pvgis_base_url: str = os.getenv("PVGIS_BASE_URL", "https://re.jrc.ec.europa.eu/api/v5_2/MRcalc")
+    pvgis_start_year: int = int(os.getenv("PVGIS_START_YEAR", "2015"))
+    pvgis_end_year: int = int(os.getenv("PVGIS_END_YEAR", "2020"))
+    enable_pvgis_cache: bool = os.getenv("ENABLE_PVGIS_CACHE", "true").lower() == "true"
+    pvgis_cache_dir: str = os.getenv("PVGIS_CACHE_DIR", "data/raw/pvgis")
+    pvgis_cache_ttl_hours: int = int(os.getenv("PVGIS_CACHE_TTL_HOURS", "720"))
+
+    panel_efficiency: float = float(os.getenv("PANEL_EFFICIENCY", "0.20"))
+    system_losses: float = float(os.getenv("SYSTEM_LOSSES", "0.14"))
+    default_system_area_m2: float = float(os.getenv("DEFAULT_SYSTEM_AREA_M2", "25"))
+    project_lifetime_years: int = int(os.getenv("PROJECT_LIFETIME_YEARS", "25"))
+
+    capex_usd: float = float(os.getenv("CAPEX_USD", "12000"))
+    opex_annual_usd: float = float(os.getenv("OPEX_ANNUAL_USD", "180"))
+    usd_try: float = float(os.getenv("USD_TRY", "32.0"))
+    discount_rate_tr: float = float(os.getenv("DISCOUNT_RATE_TR", "0.30"))
+    land_cost_try: float = float(os.getenv("LAND_COST_TRY", "0"))
+    electricity_sale_price_try_kwh: float = float(os.getenv("ELECTRICITY_SALE_PRICE_TRY_KWH", "2.5"))
+
+
+settings = Settings()

enerlytics_ai-0.1.0/src/enerlytics_ai/app/main.py

@@ -0,0 +1,11 @@
+from fastapi import FastAPI
+
+from enerlytics_ai.api.routes import router as api_router
+
+app = FastAPI(title="Enerlytics.ai", version="0.1.0")
+app.include_router(api_router)
+
+
+@app.get("/health")
+def health() -> dict:
+    return {"status": "ok"}

enerlytics_ai-0.1.0/src/enerlytics_ai/models/__init__.py

@@ -0,0 +1 @@
+

enerlytics_ai-0.1.0/src/enerlytics_ai/models/energy_model.py

@@ -0,0 +1,7 @@
+from enerlytics_ai.app.config import settings
+
+
+def estimate_annual_energy_kwh(annual_irradiance_kwh_m2: float) -> float:
+    raw_output = annual_irradiance_kwh_m2 * settings.default_system_area_m2 * settings.panel_efficiency
+    net_output = raw_output * (1 - settings.system_losses)
+    return round(net_output, 2)

enerlytics_ai-0.1.0/src/enerlytics_ai/models/lcoe_model.py

@@ -0,0 +1,15 @@
+from enerlytics_ai.app.config import settings
+
+
+def estimate_lcoe_usd_per_kwh(annual_energy_kwh: float) -> float:
+    if annual_energy_kwh <= 0:
+        raise ValueError("Annual energy must be greater than zero.")
+    if settings.project_lifetime_years <= 0:
+        raise ValueError("Project lifetime must be greater than zero years.")
+    if settings.capex_usd < 0 or settings.opex_annual_usd < 0:
+        raise ValueError("CAPEX and annual OPEX cannot be negative.")
+
+    total_cost = settings.capex_usd + (settings.opex_annual_usd * settings.project_lifetime_years)
+    total_energy_output = annual_energy_kwh * settings.project_lifetime_years
+    lcoe = total_cost / total_energy_output
+    return round(lcoe, 4)

enerlytics_ai-0.1.0/src/enerlytics_ai/services/__init__.py

@@ -0,0 +1 @@
+

enerlytics_ai-0.1.0/src/enerlytics_ai/services/pvgis_data_service.py

@@ -0,0 +1,148 @@
+import json
+import os
+import time
+from collections import defaultdict
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+import requests
+
+from enerlytics_ai.app.config import settings
+
+
+def _cache_file_path(latitude: float, longitude: float, start_year: int, end_year: int) -> Path:
+    cache_key = (
+        f"{latitude:.4f}_{longitude:.4f}_{start_year}_{end_year}".replace("-", "m")
+    )
+    return Path(settings.pvgis_cache_dir) / f"{cache_key}.json"
+
+
+def _read_cached_payload(
+    latitude: float, longitude: float, start_year: int, end_year: int
+) -> Optional[Dict[str, Any]]:
+    if not settings.enable_pvgis_cache:
+        return None
+
+    cache_path = _cache_file_path(latitude, longitude, start_year, end_year)
+    if not cache_path.exists():
+        return None
+
+    try:
+        with cache_path.open("r", encoding="utf-8") as cache_file:
+            payload = json.load(cache_file)
+    except (OSError, json.JSONDecodeError, TypeError, ValueError):
+        try:
+            cache_path.unlink(missing_ok=True)
+        except OSError:
+            pass
+        return None
+
+    fetched_at = float(payload.get("fetched_at_unix", 0))
+    ttl_seconds = settings.pvgis_cache_ttl_hours * 3600
+    if ttl_seconds <= 0 or (time.time() - fetched_at) > ttl_seconds:
+        return None
+
+    monthly_entries = payload.get("monthly_entries")
+    if not isinstance(monthly_entries, list) or not monthly_entries:
+        return None
+    return monthly_entries
+
+
+def _write_cache_payload(
+    latitude: float,
+    longitude: float,
+    start_year: int,
+    end_year: int,
+    monthly_entries: List[Dict[str, Any]],
+) -> None:
+    if not settings.enable_pvgis_cache:
+        return
+
+    cache_path = _cache_file_path(latitude, longitude, start_year, end_year)
+    os.makedirs(cache_path.parent, exist_ok=True)
+
+    with cache_path.open("w", encoding="utf-8") as cache_file:
+        json.dump(
+            {
+                "fetched_at_unix": int(time.time()),
+                "monthly_entries": monthly_entries,
+            },
+            cache_file,
+        )
+
+
+def _request_monthly_entries(
+    latitude: float, longitude: float, start_year: int, end_year: int
+) -> List[Dict[str, Any]]:
+    params = {
+        "lat": latitude,
+        "lon": longitude,
+        "horirrad": 1,
+        "outputformat": "json",
+        "startyear": start_year,
+        "endyear": end_year,
+    }
+
+    response = requests.get(
+        settings.pvgis_base_url,
+        params=params,
+        timeout=settings.request_timeout_seconds,
+    )
+    response.raise_for_status()
+    payload = response.json()
+
+    monthly_entries = payload.get("outputs", {}).get("monthly", [])
+    if not isinstance(monthly_entries, list) or not monthly_entries:
+        raise ValueError("PVGIS MRcalc response missing monthly entries.")
+    return monthly_entries
+
+
+def _annual_irradiance_from_monthly_entries(monthly_entries: List[Dict[str, Any]]) -> float:
+    yearly_totals: Dict[int, float] = defaultdict(float)
+    yearly_month_counts: Dict[int, int] = defaultdict(int)
+
+    for entry in monthly_entries:
+        try:
+            year = int(entry["year"])
+            value = float(entry["H(h)_m"])
+        except (KeyError, TypeError, ValueError) as exc:
+            raise ValueError("PVGIS monthly entry has invalid format.") from exc
+        yearly_totals[year] += value
+        yearly_month_counts[year] += 1
+
+    complete_years = [y for y, count in yearly_month_counts.items() if count == 12]
+    if not complete_years:
+        raise ValueError("PVGIS response has no complete-year monthly coverage.")
+
+    yearly_sums = [yearly_totals[year] for year in complete_years]
+    return sum(yearly_sums) / len(yearly_sums)
+
+
+def fetch_annual_ghi_kwh_m2(latitude: float, longitude: float) -> Dict[str, Any]:
+    start_year = settings.pvgis_start_year
+    end_year = settings.pvgis_end_year
+    if start_year > end_year:
+        raise ValueError("PVGIS_START_YEAR must be less than or equal to PVGIS_END_YEAR.")
+
+    cached_entries = _read_cached_payload(latitude, longitude, start_year, end_year)
+    if cached_entries is not None:
+        annual_ghi = _annual_irradiance_from_monthly_entries(cached_entries)
+        return {
+            "source": "PVGIS (cache)",
+            "annual_irradiance_kwh_m2": round(annual_ghi, 2),
+            "monthly_entries": cached_entries,
+            "start_year": start_year,
+            "end_year": end_year,
+        }
+
+    monthly_entries = _request_monthly_entries(latitude, longitude, start_year, end_year)
+    _write_cache_payload(latitude, longitude, start_year, end_year, monthly_entries)
+    annual_ghi = _annual_irradiance_from_monthly_entries(monthly_entries)
+
+    return {
+        "source": "PVGIS",
+        "annual_irradiance_kwh_m2": round(annual_ghi, 2),
+        "monthly_entries": monthly_entries,
+        "start_year": start_year,
+        "end_year": end_year,
+    }

enerlytics_ai-0.1.0/src/enerlytics_ai/services/solar_data_service.py

@@ -0,0 +1,188 @@
+import json
+import os
+import time
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+import requests
+
+from enerlytics_ai.app.config import settings
+from enerlytics_ai.utils.helpers import monthly_to_annual_irradiance
+
+
+def _cache_file_path(latitude: float, longitude: float) -> Path:
+    cache_key = f"{latitude:.4f}_{longitude:.4f}_{settings.nasa_power_parameter}".replace("-", "m")
+    return Path(settings.nasa_cache_dir) / f"{cache_key}.json"
+
+
+def _read_cached_monthly_data(latitude: float, longitude: float) -> Optional[Dict[str, Any]]:
+    if not settings.enable_nasa_cache:
+        return None
+
+    cache_path = _cache_file_path(latitude, longitude)
+    if not cache_path.exists():
+        return None
+
+    try:
+        with cache_path.open("r", encoding="utf-8") as cache_file:
+            payload = json.load(cache_file)
+    except (OSError, json.JSONDecodeError, TypeError, ValueError):
+        try:
+            cache_path.unlink(missing_ok=True)
+        except OSError:
+            pass
+        return None
+
+    fetched_at = float(payload.get("fetched_at_unix", 0))
+    ttl_seconds = settings.nasa_cache_ttl_hours * 3600
+    if ttl_seconds <= 0 or (time.time() - fetched_at) > ttl_seconds:
+        return None
+
+    monthly_daily_ghi = payload.get("monthly_daily_ghi")
+    if not isinstance(monthly_daily_ghi, dict):
+        return None
+    return monthly_daily_ghi
+
+
+def _write_cache_payload(latitude: float, longitude: float, monthly_daily_ghi: Dict[str, Any]) -> None:
+    if not settings.enable_nasa_cache:
+        return
+
+    cache_path = _cache_file_path(latitude, longitude)
+    os.makedirs(cache_path.parent, exist_ok=True)
+
+    with cache_path.open("w", encoding="utf-8") as cache_file:
+        json.dump(
+            {
+                "fetched_at_unix": int(time.time()),
+                "monthly_daily_ghi": monthly_daily_ghi,
+            },
+            cache_file,
+        )
+
+
+def fetch_annual_ghi_kwh_m2(latitude: float, longitude: float) -> Dict[str, Any]:
+    cached_monthly_data = _read_cached_monthly_data(latitude=latitude, longitude=longitude)
+    if cached_monthly_data is not None:
+        annual_ghi = monthly_to_annual_irradiance(cached_monthly_data)
+        return {
+            "source": "NASA POWER (cache)",
+            "annual_irradiance_kwh_m2": round(annual_ghi, 2),
+            "monthly_daily_ghi": cached_monthly_data,
+        }
+
+    params = {
+        "parameters": settings.nasa_power_parameter,
+        "community": settings.nasa_power_community,
+        "longitude": longitude,
+        "latitude": latitude,
+        "format": settings.nasa_power_format,
+    }
+
+    response = requests.get(
+        settings.nasa_power_base_url,
+        params=params,
+        timeout=settings.request_timeout_seconds,
+    )
+    response.raise_for_status()
+    payload = response.json()
+
+    monthly_data = (
+        payload.get("properties", {})
+        .get("parameter", {})
+        .get(settings.nasa_power_parameter, {})
+    )
+    _write_cache_payload(latitude=latitude, longitude=longitude, monthly_daily_ghi=monthly_data)
+    annual_ghi = monthly_to_annual_irradiance(monthly_data)
+
+    return {
+        "source": "NASA POWER",
+        "annual_irradiance_kwh_m2": round(annual_ghi, 2),
+        "monthly_daily_ghi": monthly_data,
+    }
+
+
+def fetch_historical_monthly_ghi_kwh_m2(
+    latitude: float,
+    longitude: float,
+    start_year: int,
+    end_year: int,
+) -> Dict[str, Any]:
+    if start_year > end_year:
+        raise ValueError("start_year must be less than or equal to end_year.")
+
+    params = {
+        "parameters": settings.nasa_power_parameter,
+        "community": settings.nasa_power_community,
+        "longitude": longitude,
+        "latitude": latitude,
+        "format": settings.nasa_power_format,
+        "start": str(start_year),
+        "end": str(end_year),
+    }
+
+    response = requests.get(
+        settings.nasa_power_monthly_base_url,
+        params=params,
+        timeout=settings.request_timeout_seconds,
+    )
+    response.raise_for_status()
+    payload = response.json()
+
+    monthly_data = (
+        payload.get("properties", {})
+        .get("parameter", {})
+        .get(settings.nasa_power_parameter, {})
+    )
+    if not isinstance(monthly_data, dict):
+        raise ValueError("Historical solar data format is invalid.")
+
+    monthly_series = []
+    for key, value in monthly_data.items():
+        if not (isinstance(key, str) and len(key) == 6 and key.isdigit()):
+            continue
+        year = int(key[:4])
+        month = int(key[4:])
+        if year < start_year or year > end_year or month < 1 or month > 12:
+            continue
+        monthly_series.append(
+            {
+                "year": year,
+                "month": month,
+                "ghi_kwh_m2_day": float(value),
+            }
+        )
+
+    monthly_series.sort(key=lambda item: (item["year"], item["month"]))
+    if not monthly_series:
+        raise ValueError("No historical monthly solar data returned for requested range.")
+
+    annual_summary_map: Dict[int, Dict[str, float]] = {}
+    for point in monthly_series:
+        year = point["year"]
+        annual_summary_map.setdefault(year, {"sum_ghi_kwh_m2_day": 0.0, "month_count": 0})
+        annual_summary_map[year]["sum_ghi_kwh_m2_day"] += point["ghi_kwh_m2_day"]
+        annual_summary_map[year]["month_count"] += 1
+
+    annual_summary = []
+    for year in sorted(annual_summary_map):
+        year_total = annual_summary_map[year]["sum_ghi_kwh_m2_day"]
+        month_count = annual_summary_map[year]["month_count"]
+        annual_summary.append(
+            {
+                "year": year,
+                "total_ghi_kwh_m2_day": round(year_total, 4),
+                "average_ghi_kwh_m2_day": round(year_total / month_count, 4),
+            }
+        )
+
+    return {
+        "source": "NASA POWER",
+        "parameter": settings.nasa_power_parameter,
+        "latitude": latitude,
+        "longitude": longitude,
+        "start_year": start_year,
+        "end_year": end_year,
+        "monthly_series": monthly_series,
+        "annual_summary": annual_summary,
+    }

enerlytics_ai-0.1.0/src/enerlytics_ai/services/solar_model_service.py

@@ -0,0 +1,35 @@
+from enerlytics_ai.models.energy_model import estimate_annual_energy_kwh
+from enerlytics_ai.models.lcoe_model import estimate_lcoe_usd_per_kwh
+from enerlytics_ai.app.config import settings
+from enerlytics_ai.services import pvgis_data_service, solar_data_service
+
+
+def _fetch_solar_data(latitude: float, longitude: float, provider: str | None = None) -> dict:
+    selected = (provider or settings.solar_data_provider).lower()
+    if selected == "nasa":
+        return solar_data_service.fetch_annual_ghi_kwh_m2(latitude=latitude, longitude=longitude)
+    if selected == "pvgis":
+        return pvgis_data_service.fetch_annual_ghi_kwh_m2(latitude=latitude, longitude=longitude)
+    raise ValueError("Invalid solar data provider. Supported values: nasa, pvgis.")
+
+
+def analyze_site(latitude: float, longitude: float, provider: str | None = None) -> dict:
+    solar_data = _fetch_solar_data(latitude=latitude, longitude=longitude, provider=provider)
+    annual_energy_kwh = estimate_annual_energy_kwh(solar_data["annual_irradiance_kwh_m2"])
+    estimated_lcoe_usd = estimate_lcoe_usd_per_kwh(annual_energy_kwh)
+    lcoe_try_kwh = round(estimated_lcoe_usd * settings.usd_try, 4)
+    annual_revenue_try = annual_energy_kwh * settings.electricity_sale_price_try_kwh
+    total_investment_try = (settings.capex_usd * settings.usd_try) + settings.land_cost_try
+    simple_payback_years = round(total_investment_try / annual_revenue_try, 2) if annual_revenue_try > 0 else None
+
+    return {
+        "data_source": solar_data["source"],
+        "annual_energy_kwh": annual_energy_kwh,
+        "estimated_lcoe": estimated_lcoe_usd,
+        "lcoe_try_kwh": lcoe_try_kwh,
+        "simple_payback_years": simple_payback_years,
+        "summary": (
+            f"Estimated annual production is {annual_energy_kwh} kWh with "
+            f"an LCOE of {estimated_lcoe_usd} USD/kWh ({lcoe_try_kwh} TRY/kWh)."
+        ),
+    }

enerlytics_ai-0.1.0/src/enerlytics_ai/utils/__init__.py

@@ -0,0 +1 @@
+

enerlytics_ai-0.1.0/src/enerlytics_ai/utils/constants.py

@@ -0,0 +1,17 @@
+MONTHS_IN_YEAR = 12
+DAYS_IN_YEAR = 365
+
+NASA_MONTH_KEYS = (
+    "JAN",
+    "FEB",
+    "MAR",
+    "APR",
+    "MAY",
+    "JUN",
+    "JUL",
+    "AUG",
+    "SEP",
+    "OCT",
+    "NOV",
+    "DEC",
+)

enerlytics_ai-0.1.0/src/enerlytics_ai/utils/helpers.py

@@ -0,0 +1,11 @@
+from typing import Dict
+
+from enerlytics_ai.utils.constants import DAYS_IN_YEAR, MONTHS_IN_YEAR, NASA_MONTH_KEYS
+
+
+def monthly_to_annual_irradiance(monthly_daily_ghi: Dict[str, float]) -> float:
+    values = [float(monthly_daily_ghi[m]) for m in NASA_MONTH_KEYS if m in monthly_daily_ghi]
+    if len(values) != MONTHS_IN_YEAR:
+        raise ValueError("Incomplete monthly GHI data from NASA POWER.")
+    average_daily_ghi = sum(values) / MONTHS_IN_YEAR
+    return average_daily_ghi * DAYS_IN_YEAR

enerlytics_ai-0.1.0/src/enerlytics_ai.egg-info/PKG-INFO

@@ -0,0 +1,142 @@
+Metadata-Version: 2.4
+Name: enerlytics-ai
+Version: 0.1.0
+Summary: AI platform for predicting renewable energy investment opportunities using meteorological data, machine learning and financial analytics.
+Author-email: Huseyin Kucukogul <huseyinkucukogulcontact@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2026 Huseyin
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/Kucukogul/enerlytics.ai
+Project-URL: Repository, https://github.com/Kucukogul/enerlytics.ai
+Keywords: energy,AI,machine learning,renewable energy,solar,analytics
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastapi>=0.110.0
+Requires-Dist: uvicorn>=0.27.0
+Requires-Dist: pandas>=2.1.0
+Requires-Dist: numpy>=1.26.0
+Requires-Dist: requests>=2.31.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: pyyaml>=6.0.0
+Requires-Dist: pyarrow>=14.0.0
+Requires-Dist: shapely>=2.0.0
+Requires-Dist: tqdm>=4.66.0
+Requires-Dist: tenacity>=8.2.0
+Dynamic: license-file
+
+# Enerlytics.ai
+
+AI platform for predicting renewable energy investment opportunities in Turkiye.
+
+Combines meteorological data, machine learning and financial analytics to estimate solar energy potential and evaluate project feasibility at any location in Turkiye.
+
+---
+
+## Setup
+
+```bash
+python -m venv .venv && source .venv/bin/activate
+pip install -r requirements.txt
+cp .env.example .env
+uvicorn enerlytics_ai.app.main:app --app-dir src --reload
+```
+
+API → `http://127.0.0.1:8000` · Docs → `http://127.0.0.1:8000/docs`
+
+---
+
+## Quick Start
+
+```bash
+# Site analysis
+curl -X POST "http://127.0.0.1:8000/api/v1/analyze-site" \
+  -H "Content-Type: application/json" \
+  -d '{"latitude": 39.9208, "longitude": 32.8541}'
+
+# Historical solar data
+curl -X POST "http://127.0.0.1:8000/api/v1/historical-solar" \
+  -H "Content-Type: application/json" \
+  -d '{"latitude": 39.9208, "longitude": 32.8541, "start_year": 2015, "end_year": 2024}'
+```
+
+---
+
+## Structure
+
+```
+enerlytics.ai/
+│
+├── src/enerlytics_ai/
+│   ├── api/
+│   │   └── routes.py                        # API route definitions
+│   ├── app/
+│   │   ├── main.py                          # FastAPI app entry point
+│   │   └── config.py                        # app configuration
+│   ├── models/
+│   │   ├── energy_model.py                  # solar energy estimation model
+│   │   └── lcoe_model.py                    # LCOE financial model
+│   ├── services/
+│   │   ├── pvgis_data_service.py            # PVGIS API integration
+│   │   ├── solar_data_service.py            # solar data fetching & caching
+│   │   └── solar_model_service.py           # model inference service
+│   └── utils/
+│       ├── constants.py                     # shared constants
+│       └── helpers.py                       # utility functions
+│
+├── pipelines/
+│   ├── province_scan.py                     # scans all 81 TR provinces
+│   └── scoring.py                           # investment scoring logic
+│
+├── analysis/
+│   ├── notebooks/
+│   │   ├── 01_eda.ipynb                     # exploratory data analysis
+│   │   └── 02_turkiye_geneli_eda.ipynb      # Turkiye-wide solar EDA
+│   └── outputs/
+│       ├── monthly_stats.csv
+│       ├── tr81_monthly_risk_band.csv
+│       └── tr81_province_ranking.csv        # province investment ranking
+│
+├── data/
+│   ├── raw/pvgis/                           # raw PVGIS API responses
+│   └── processed/                           # cleaned province datasets
+│
+├── scripts/
+│   └── fetch_pvgis_81_seriescalc.py         # data collection script
+│
+└── tests/
+    ├── unit/
+    │   └── test_scoring.py
+    └── integration/
+        └── test_province_pipeline.py
+```
+
+---
+
+**Author:** Huseyin Kucukogul · MIT License

enerlytics_ai-0.1.0/src/enerlytics_ai.egg-info/SOURCES.txt

@@ -0,0 +1,24 @@
+LICENSE
+README.md
+pyproject.toml
+src/enerlytics_ai/__init__.py
+src/enerlytics_ai.egg-info/PKG-INFO
+src/enerlytics_ai.egg-info/SOURCES.txt
+src/enerlytics_ai.egg-info/dependency_links.txt
+src/enerlytics_ai.egg-info/requires.txt
+src/enerlytics_ai.egg-info/top_level.txt
+src/enerlytics_ai/api/__init__.py
+src/enerlytics_ai/api/routes.py
+src/enerlytics_ai/app/__init__.py
+src/enerlytics_ai/app/config.py
+src/enerlytics_ai/app/main.py
+src/enerlytics_ai/models/__init__.py
+src/enerlytics_ai/models/energy_model.py
+src/enerlytics_ai/models/lcoe_model.py
+src/enerlytics_ai/services/__init__.py
+src/enerlytics_ai/services/pvgis_data_service.py
+src/enerlytics_ai/services/solar_data_service.py
+src/enerlytics_ai/services/solar_model_service.py
+src/enerlytics_ai/utils/__init__.py
+src/enerlytics_ai/utils/constants.py
+src/enerlytics_ai/utils/helpers.py

enerlytics_ai-0.1.0/src/enerlytics_ai.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

enerlytics_ai-0.1.0/src/enerlytics_ai.egg-info/requires.txt

@@ -0,0 +1,11 @@
+fastapi>=0.110.0
+uvicorn>=0.27.0
+pandas>=2.1.0
+numpy>=1.26.0
+requests>=2.31.0
+python-dotenv>=1.0.0
+pyyaml>=6.0.0
+pyarrow>=14.0.0
+shapely>=2.0.0
+tqdm>=4.66.0
+tenacity>=8.2.0

enerlytics_ai-0.1.0/src/enerlytics_ai.egg-info/top_level.txt

@@ -0,0 +1 @@
+enerlytics_ai