luminus-py 0.2.1__py3-none-any.whl

luminus/__init__.py

@@ -0,0 +1,29 @@
+from .client import Luminus
+from .exceptions import (
+    LuminusConfigurationError,
+    LuminusError,
+    LuminusProtocolError,
+    LuminusStartupError,
+    LuminusToolError,
+    LuminusTransportError,
+    LuminusUpstreamError,
+)
+from .models import GridConnectionQueueSnapshot, GridProximitySnapshot, SiteRevenueEstimate
+from .result import LuminusResult
+
+__all__ = [
+    "Luminus",
+    "GridConnectionQueueSnapshot",
+    "GridProximitySnapshot",
+    "LuminusError",
+    "LuminusConfigurationError",
+    "LuminusProtocolError",
+    "LuminusStartupError",
+    "LuminusToolError",
+    "LuminusTransportError",
+    "LuminusUpstreamError",
+    "LuminusResult",
+    "SiteRevenueEstimate",
+]
+
+__version__ = "0.2.1"

luminus/client.py

@@ -0,0 +1,512 @@
+from __future__ import annotations
+
+import atexit
+import json
+import os
+import queue
+import shutil
+import subprocess
+import threading
+import time
+import weakref
+from concurrent.futures import ThreadPoolExecutor
+from itertools import count
+from pathlib import Path
+from typing import Any, Iterable, Mapping, Sequence
+
+from .exceptions import (
+    LuminusConfigurationError,
+    LuminusError,
+    LuminusProtocolError,
+    LuminusStartupError,
+    LuminusToolError,
+    LuminusTransportError,
+    LuminusUpstreamError,
+)
+from .models import GridConnectionQueueSnapshot, GridProximitySnapshot, SiteRevenueEstimate
+from .result import LuminusResult
+
+DEFAULT_PROTOCOL_VERSION = "2025-03-26"
+DEFAULT_CLIENT_NAME = "luminus-py"
+DEFAULT_CLIENT_VERSION = "0.2.1"
+
+_ACTIVE_CLIENTS: "weakref.WeakSet[Luminus]" = weakref.WeakSet()
+
+
+def _close_active_clients() -> None:  # pragma: no cover - process-exit behaviour
+    for client in list(_ACTIVE_CLIENTS):
+        try:
+            client.close()
+        except Exception:
+            pass
+
+
+atexit.register(_close_active_clients)
+
+
+class _PipePump(threading.Thread):
+    def __init__(self, pipe, sink: "queue.Queue[str]"):
+        super().__init__(daemon=True)
+        self._pipe = pipe
+        self._sink = sink
+
+    def run(self) -> None:  # pragma: no cover - exercised indirectly
+        try:
+            for line in self._pipe:
+                self._sink.put(line.rstrip("\r\n"))
+        finally:
+            self._sink.put("")
+
+
+class Luminus:
+    def __init__(
+        self,
+        command: Sequence[str] | str | None = None,
+        *,
+        profile: str = "full",
+        cwd: str | Path | None = None,
+        env: Mapping[str, str] | None = None,
+        request_timeout: float = 30.0,
+        startup_timeout: float = 10.0,
+    ) -> None:
+        self.profile = profile
+        self.cwd = str(cwd) if cwd is not None else None
+        self.request_timeout = request_timeout
+        self._request_ids = count(1)
+        self._stdout_queue: queue.Queue[str] = queue.Queue()
+        self._stderr_queue: queue.Queue[str] = queue.Queue()
+        self._noise_lines: list[str] = []
+        self._lock = threading.Lock()
+        self._closed = False
+        self._tool_cache: dict[str, dict[str, Any]] = {}
+
+        resolved_command = self._resolve_command(command, profile)
+        self._spawn_command = list(resolved_command)
+        self._user_env = {key: str(value) for key, value in (env or {}).items()}
+        self._startup_timeout = startup_timeout
+
+        merged_env = os.environ.copy()
+        merged_env.setdefault("DOTENV_CONFIG_QUIET", "true")
+        if self._user_env:
+            merged_env.update(self._user_env)
+
+        try:
+            self._process = subprocess.Popen(
+                resolved_command,
+                cwd=self.cwd,
+                env=merged_env,
+                stdin=subprocess.PIPE,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+                text=True,
+                encoding="utf-8",
+                bufsize=1,
+            )
+        except FileNotFoundError as exc:
+            raise LuminusStartupError(
+                "Could not start luminus-mcp. Install it on PATH or pass an explicit command=[...]."
+            ) from exc
+
+        if self._process.stdin is None or self._process.stdout is None or self._process.stderr is None:
+            raise LuminusStartupError("Failed to open stdio pipes to luminus-mcp.")
+
+        self._stdout_pump = _PipePump(self._process.stdout, self._stdout_queue)
+        self._stderr_pump = _PipePump(self._process.stderr, self._stderr_queue)
+        self._stdout_pump.start()
+        self._stderr_pump.start()
+
+        try:
+            init_result = self._request(
+                "initialize",
+                {
+                    "protocolVersion": DEFAULT_PROTOCOL_VERSION,
+                    "capabilities": {},
+                    "clientInfo": {"name": DEFAULT_CLIENT_NAME, "version": DEFAULT_CLIENT_VERSION},
+                },
+                timeout=startup_timeout,
+            )
+        except LuminusTransportError as exc:
+            self.close()
+            raise LuminusStartupError(str(exc)) from exc
+        self.protocol_version = init_result.get("protocolVersion", DEFAULT_PROTOCOL_VERSION)
+        self.server_info = init_result.get("serverInfo", {})
+        self._send({"jsonrpc": "2.0", "method": "notifications/initialized", "params": {}})
+        _ACTIVE_CLIENTS.add(self)
+
+    def __enter__(self) -> "Luminus":
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> None:
+        self.close()
+
+    def __del__(self) -> None:  # pragma: no cover - best-effort cleanup
+        try:
+            self.close()
+        except Exception:
+            pass
+
+    def close(self) -> None:
+        if self._closed:
+            return
+        self._closed = True
+        _ACTIVE_CLIENTS.discard(self)
+
+        if self._process.poll() is None:
+            self._process.terminate()
+            try:
+                self._process.wait(timeout=5)
+            except subprocess.TimeoutExpired:  # pragma: no cover
+                self._process.kill()
+                self._process.wait(timeout=5)
+
+    def refresh_tools(self) -> dict[str, dict[str, Any]]:
+        result = self._request("tools/list", {})
+        self._tool_cache = {
+            tool["name"]: tool
+            for tool in result.get("tools", [])
+            if isinstance(tool, dict) and "name" in tool
+        }
+        return dict(self._tool_cache)
+
+    def list_tools(self) -> list[str]:
+        return list(self.refresh_tools().keys())
+
+    def tool_specs(self) -> dict[str, dict[str, Any]]:
+        if not self._tool_cache:
+            self.refresh_tools()
+        return dict(self._tool_cache)
+
+    def describe_tool(self, name: str) -> dict[str, Any]:
+        specs = self.tool_specs()
+        if name not in specs:
+            raise KeyError(f"Tool {name!r} is not available from this Luminus server")
+        return dict(specs[name])
+
+    def call_tool(self, name: str, arguments: Mapping[str, Any] | None = None) -> LuminusResult:
+        result = self._request(
+            "tools/call",
+            {"name": name, "arguments": dict(arguments or {})},
+            timeout=self.request_timeout,
+        )
+        parsed = self._parse_tool_result(result)
+        if result.get("isError"):
+            self._raise_tool_error(name, parsed)
+        return LuminusResult(tool_name=name, raw=parsed, raw_response=result)
+
+    def get_day_ahead_prices(self, **arguments: Any) -> LuminusResult:
+        return self.call_tool("get_day_ahead_prices", arguments)
+
+    def get_generation_mix(self, **arguments: Any) -> LuminusResult:
+        return self.call_tool("get_generation_mix", arguments)
+
+    def get_outages_frame(self, **arguments: Any):
+        return self.call_tool_to_pandas("get_outages", arguments, data_key="outages")
+
+    def screen_site(self, **arguments: Any) -> LuminusResult:
+        return self.call_tool("screen_site", arguments)
+
+    def get_server_status(self) -> LuminusResult:
+        return self.call_tool("get_server_status", {})
+
+    def get_cross_border_flows_many(
+        self,
+        corridors: Iterable[tuple[str, str]],
+        *,
+        parallel: bool = False,
+        max_workers: int | None = None,
+        **arguments: Any,
+    ):
+        return self.call_many_to_pandas(
+            "get_cross_border_flows",
+            [
+                {**arguments, "from_zone": from_zone, "to_zone": to_zone}
+                for from_zone, to_zone in corridors
+            ],
+            data_key="flows",
+            request_prefix="request_",
+            parallel=parallel,
+            max_workers=max_workers,
+        )
+
+    def get_grid_proximity_substations(self, **arguments: Any):
+        return self.call_tool_to_pandas("get_grid_proximity", arguments, data_key="substations")
+
+    def get_grid_proximity_lines(self, **arguments: Any):
+        return self.call_tool_to_pandas("get_grid_proximity", arguments, data_key="lines")
+
+    def get_grid_proximity_snapshot(self, **arguments: Any) -> GridProximitySnapshot:
+        return self.call_tool("get_grid_proximity", arguments).to_model(GridProximitySnapshot)
+
+    def get_grid_connection_queue_projects(self, **arguments: Any):
+        return self.call_tool_to_pandas("get_grid_connection_queue", arguments, data_key="projects")
+
+    def get_grid_connection_queue_sites(self, **arguments: Any):
+        return self.call_tool_to_pandas("get_grid_connection_queue", arguments, data_key="connection_sites")
+
+    def get_grid_connection_queue_snapshot(self, **arguments: Any) -> GridConnectionQueueSnapshot:
+        return self.call_tool("get_grid_connection_queue", arguments).to_model(GridConnectionQueueSnapshot)
+
+    def estimate_site_revenue_frame(self, **arguments: Any):
+        return self.call_tool("estimate_site_revenue", arguments).to_flat_pandas()
+
+    def estimate_site_revenue_estimate(self, **arguments: Any) -> SiteRevenueEstimate:
+        return self.call_tool("estimate_site_revenue", arguments).to_model(SiteRevenueEstimate)
+
+    def call_tool_to_pandas(
+        self,
+        name: str,
+        arguments: Mapping[str, Any] | None = None,
+        *,
+        data_key: str | None = None,
+    ):
+        return self.call_tool(name, arguments).to_pandas(data_key=data_key)
+
+    def call_tool_to_geojson(
+        self,
+        name: str,
+        arguments: Mapping[str, Any] | None = None,
+        *,
+        data_key: str | None = None,
+    ) -> dict[str, Any]:
+        return self.call_tool(name, arguments).to_geojson(data_key=data_key)
+
+    def call_tool_to_geodataframe(
+        self,
+        name: str,
+        arguments: Mapping[str, Any] | None = None,
+        *,
+        data_key: str | None = None,
+        crs: str = "EPSG:4326",
+    ):
+        return self.call_tool(name, arguments).to_geodataframe(data_key=data_key, crs=crs)
+
+    def call_many(
+        self,
+        name: str,
+        argument_sets: Iterable[Mapping[str, Any]],
+        *,
+        parallel: bool = False,
+        max_workers: int | None = None,
+    ) -> list[LuminusResult]:
+        jobs = [dict(arguments) for arguments in argument_sets]
+        if not parallel or len(jobs) <= 1:
+            return [self.call_tool(name, arguments) for arguments in jobs]
+
+        worker_count = max_workers or min(4, len(jobs))
+
+        def _run(arguments: Mapping[str, Any]) -> LuminusResult:
+            child = self._spawn_child_client()
+            try:
+                return child.call_tool(name, arguments)
+            finally:
+                child.close()
+
+        with ThreadPoolExecutor(max_workers=worker_count) as executor:
+            return list(executor.map(_run, jobs))
+
+    def call_many_to_pandas(
+        self,
+        name: str,
+        argument_sets: Iterable[Mapping[str, Any]],
+        *,
+        data_key: str | None = None,
+        include_request_args: bool = True,
+        request_prefix: str = "request_",
+        parallel: bool = False,
+        max_workers: int | None = None,
+    ):
+        try:
+            import pandas as pd
+        except ImportError as exc:  # pragma: no cover
+            raise RuntimeError(
+                "pandas is not installed. Install luminus-py[notebook] or add pandas manually."
+            ) from exc
+
+        frames = []
+        jobs = [dict(arguments) for arguments in argument_sets]
+        results = self.call_many(name, jobs, parallel=parallel, max_workers=max_workers)
+        for args, result in zip(jobs, results, strict=False):
+            frame = result.to_pandas(data_key=data_key)
+            if include_request_args:
+                for key, value in args.items():
+                    frame[f"{request_prefix}{key}"] = value
+            frames.append(frame)
+
+        if not frames:
+            return pd.DataFrame()
+        return pd.concat(frames, ignore_index=True)
+
+    def get_day_ahead_prices_many(
+        self,
+        zones: Iterable[str],
+        *,
+        parallel: bool = False,
+        max_workers: int | None = None,
+        **arguments: Any,
+    ):
+        return self.call_many_to_pandas(
+            "get_day_ahead_prices",
+            [{**arguments, "zone": zone} for zone in zones],
+            request_prefix="request_",
+            parallel=parallel,
+            max_workers=max_workers,
+        )
+
+    def get_generation_mix_many(
+        self,
+        zones: Iterable[str],
+        *,
+        parallel: bool = False,
+        max_workers: int | None = None,
+        **arguments: Any,
+    ):
+        return self.call_many_to_pandas(
+            "get_generation_mix",
+            [{**arguments, "zone": zone} for zone in zones],
+            data_key="generation",
+            request_prefix="request_",
+            parallel=parallel,
+            max_workers=max_workers,
+        )
+
+    def compare_sites_rankings(self, **arguments: Any):
+        return self.call_tool_to_pandas("compare_sites", arguments, data_key="rankings")
+
+    def compare_sites_rankings_geojson(self, **arguments: Any) -> dict[str, Any]:
+        return self.call_tool_to_geojson("compare_sites", arguments, data_key="rankings")
+
+    def compare_sites_rankings_geodataframe(self, **arguments: Any):
+        return self.call_tool_to_geodataframe("compare_sites", arguments, data_key="rankings")
+
+    def __getattr__(self, name: str):
+        if name.startswith("_"):
+            raise AttributeError(name)
+
+        try:
+            tool = self.describe_tool(name)
+        except (KeyError, LuminusError) as exc:
+            raise AttributeError(name) from exc
+
+        def _dynamic_tool(**arguments: Any) -> LuminusResult:
+            return self.call_tool(name, arguments)
+
+        _dynamic_tool.__name__ = name
+        _dynamic_tool.__qualname__ = f"{self.__class__.__name__}.{name}"
+        _dynamic_tool.__doc__ = tool.get("description") or f"Call the {name} MCP tool."
+        return _dynamic_tool
+
+    def __dir__(self) -> list[str]:
+        names = set(super().__dir__())
+        try:
+            names.update(self.tool_specs().keys())
+        except LuminusError:
+            pass
+        return sorted(names)
+
+    def _spawn_child_client(self) -> "Luminus":
+        return Luminus(
+            command=list(self._spawn_command),
+            profile=self.profile,
+            cwd=self.cwd,
+            env=self._user_env,
+            request_timeout=self.request_timeout,
+            startup_timeout=self._startup_timeout,
+        )
+
+    def _resolve_command(self, command: Sequence[str] | str | None, profile: str) -> list[str]:
+        if command is None:
+            executable = shutil.which("luminus-mcp")
+            if executable is None:
+                raise LuminusStartupError(
+                    "luminus-mcp was not found on PATH. Install it first or pass command=[...]."
+                )
+            return [executable, "--profile", profile]
+
+        parts = [command] if isinstance(command, str) else list(command)
+        if "--profile" not in parts:
+            parts.extend(["--profile", profile])
+        return [str(part) for part in parts]
+
+    def _send(self, message: Mapping[str, Any]) -> None:
+        if self._process.poll() is not None:
+            raise LuminusTransportError(self._crash_message("luminus-mcp exited before the request completed."))
+        assert self._process.stdin is not None
+        self._process.stdin.write(json.dumps(message) + "\n")
+        self._process.stdin.flush()
+
+    def _request(self, method: str, params: Mapping[str, Any], timeout: float | None = None) -> dict[str, Any]:
+        with self._lock:
+            request_id = next(self._request_ids)
+            self._send({"jsonrpc": "2.0", "id": request_id, "method": method, "params": params})
+            return self._wait_for_response(request_id, timeout or self.request_timeout)
+
+    def _wait_for_response(self, request_id: int, timeout: float) -> dict[str, Any]:
+        deadline = time.monotonic() + timeout
+        while True:
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                raise LuminusTransportError(
+                    self._crash_message(f"Timed out waiting for response to request {request_id}.")
+                )
+
+            if self._process.poll() is not None and self._stdout_queue.empty():
+                raise LuminusTransportError(self._crash_message("luminus-mcp exited unexpectedly."))
+
+            try:
+                line = self._stdout_queue.get(timeout=remaining)
+            except queue.Empty as exc:
+                raise LuminusTransportError(
+                    self._crash_message(f"Timed out waiting for response to request {request_id}.")
+                ) from exc
+
+            if not line:
+                continue
+            if not line.startswith("{"):
+                self._noise_lines.append(line)
+                continue
+
+            try:
+                message = json.loads(line)
+            except json.JSONDecodeError:
+                self._noise_lines.append(line)
+                continue
+
+            if "id" not in message:
+                continue
+            if message.get("id") != request_id:
+                continue
+            if "error" in message:
+                error = message["error"]
+                raise LuminusProtocolError(f"{error.get('message', 'Unknown MCP error')} (code={error.get('code')})")
+            return message.get("result", {})
+
+    def _parse_tool_result(self, result: Mapping[str, Any]) -> Any:
+        content = result.get("content", [])
+        if len(content) == 1 and isinstance(content[0], dict) and content[0].get("type") == "text":
+            text = content[0].get("text", "")
+            try:
+                return json.loads(text)
+            except json.JSONDecodeError:
+                return text
+        return dict(result)
+
+    def _raise_tool_error(self, tool_name: str, payload: Any) -> None:
+        message = payload if isinstance(payload, str) else json.dumps(payload)
+        lower = message.lower()
+        if "configuration error" in lower or "api key" in lower:
+            raise LuminusConfigurationError(f"{tool_name} failed: {message}")
+        if "upstream" in lower or "timed out" in lower or "no data" in lower:
+            raise LuminusUpstreamError(f"{tool_name} failed: {message}")
+        raise LuminusToolError(f"{tool_name} failed: {message}")
+
+    def _crash_message(self, prefix: str) -> str:
+        stderr_lines: list[str] = []
+        while not self._stderr_queue.empty():
+            line = self._stderr_queue.get_nowait()
+            if line:
+                stderr_lines.append(line)
+
+        details = stderr_lines[-5:] or self._noise_lines[-5:]
+        if not details:
+            return prefix
+        return prefix + " Last output: " + " | ".join(details)

luminus/exceptions.py

@@ -0,0 +1,26 @@
+class LuminusError(Exception):
+    """Base exception for luminus-py."""
+
+
+class LuminusTransportError(LuminusError):
+    """Process, pipe, or timeout failure while talking to luminus-mcp."""
+
+
+class LuminusStartupError(LuminusTransportError):
+    """The luminus-mcp subprocess could not be started or initialized."""
+
+
+class LuminusProtocolError(LuminusError):
+    """The server returned an MCP/JSON-RPC level error."""
+
+
+class LuminusToolError(LuminusError):
+    """The MCP server returned a tool-level error payload."""
+
+
+class LuminusConfigurationError(LuminusToolError):
+    """The requested tool failed because required configuration is missing."""
+
+
+class LuminusUpstreamError(LuminusToolError):
+    """The requested tool failed because an upstream source errored or timed out."""

luminus/models.py

@@ -0,0 +1,206 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Mapping
+
+
+@dataclass(slots=True)
+class GridProximitySubstation:
+    name: str | None
+    voltage_kv: int | None
+    operator: str | None
+    distance_km: float
+    lat: float
+    lon: float
+
+
+@dataclass(slots=True)
+class GridProximityLine:
+    voltage_kv: int
+    operator: str | None
+    distance_km: float
+    cables: int | None
+
+
+@dataclass(slots=True)
+class GridProximitySummary:
+    nearest_substation_km: float | None
+    nearest_line_km: float | None
+    max_nearby_voltage_kv: int | None
+
+
+@dataclass(slots=True)
+class GridProximitySnapshot:
+    lat: float
+    lon: float
+    radius_km: float
+    substations: list[GridProximitySubstation]
+    lines: list[GridProximityLine]
+    summary: GridProximitySummary
+    source_metadata: dict[str, Any]
+
+    @classmethod
+    def from_dict(cls, payload: Mapping[str, Any]) -> "GridProximitySnapshot":
+        return cls(
+            lat=float(payload["lat"]),
+            lon=float(payload["lon"]),
+            radius_km=float(payload["radius_km"]),
+            substations=[
+                GridProximitySubstation(
+                    name=item.get("name"),
+                    voltage_kv=item.get("voltage_kv"),
+                    operator=item.get("operator"),
+                    distance_km=float(item["distance_km"]),
+                    lat=float(item["lat"]),
+                    lon=float(item["lon"]),
+                )
+                for item in payload.get("substations", [])
+            ],
+            lines=[
+                GridProximityLine(
+                    voltage_kv=int(item.get("voltage_kv", 0)),
+                    operator=item.get("operator"),
+                    distance_km=float(item["distance_km"]),
+                    cables=item.get("cables"),
+                )
+                for item in payload.get("lines", [])
+            ],
+            summary=GridProximitySummary(**dict(payload.get("summary", {}))),
+            source_metadata=dict(payload.get("source_metadata", {})),
+        )
+
+
+@dataclass(slots=True)
+class GridConnectionQueueFilters:
+    connection_site_query: str | None
+    project_name_query: str | None
+    host_to: str | None
+    plant_type: str | None
+    project_status: str | None
+    agreement_type: str | None
+
+
+@dataclass(slots=True)
+class GridConnectionQueueSummary:
+    matched_projects: int
+    returned_projects: int
+    total_connected_mw: float
+    total_net_change_mw: float
+    total_cumulative_capacity_mw: float
+    earliest_effective_from: str | None
+    latest_effective_from: str | None
+
+
+@dataclass(slots=True)
+class GridConnectionSiteSummary:
+    connection_site: str
+    project_count: int
+    total_net_change_mw: float
+    total_connected_mw: float
+    total_cumulative_capacity_mw: float
+    plant_types: list[str]
+    project_statuses: list[str]
+    earliest_effective_from: str | None
+
+
+@dataclass(slots=True)
+class GridConnectionProject:
+    project_name: str
+    customer_name: str | None
+    connection_site: str
+    stage: int | None
+    mw_connected: float
+    mw_increase_decrease: float
+    cumulative_total_capacity_mw: float
+    mw_effective_from: str | None
+    project_status: str | None
+    agreement_type: str | None
+    host_to: str | None
+    plant_type: str | None
+    project_id: str | None
+    project_number: str | None
+    gate: int | None
+
+
+@dataclass(slots=True)
+class GridConnectionQueueSnapshot:
+    filters: GridConnectionQueueFilters
+    summary: GridConnectionQueueSummary
+    connection_sites: list[GridConnectionSiteSummary]
+    projects: list[GridConnectionProject]
+    source_metadata: dict[str, Any]
+    disclaimer: str
+
+    @classmethod
+    def from_dict(cls, payload: Mapping[str, Any]) -> "GridConnectionQueueSnapshot":
+        return cls(
+            filters=GridConnectionQueueFilters(**dict(payload.get("filters", {}))),
+            summary=GridConnectionQueueSummary(**dict(payload.get("summary", {}))),
+            connection_sites=[
+                GridConnectionSiteSummary(**dict(item))
+                for item in payload.get("connection_sites", [])
+            ],
+            projects=[
+                GridConnectionProject(**dict(item))
+                for item in payload.get("projects", [])
+            ],
+            source_metadata=dict(payload.get("source_metadata", {})),
+            disclaimer=str(payload.get("disclaimer", "")),
+        )
+
+
+@dataclass(slots=True)
+class SiteRevenueTerrain:
+    elevation_m: float
+    slope_deg: float
+    aspect_cardinal: str
+
+
+@dataclass(slots=True)
+class SiteRevenueMetrics:
+    estimated_annual_revenue_eur: float
+    annual_generation_mwh: float | None = None
+    capacity_factor: float | None = None
+    capture_price_eur_mwh: float | None = None
+    daily_spread_eur_mwh: float | None = None
+    daily_revenue_eur: float | None = None
+    arb_signal: str | None = None
+
+
+@dataclass(slots=True)
+class PriceSnapshot:
+    date: str
+    peak_eur_mwh: float
+    off_peak_eur_mwh: float
+    mean_eur_mwh: float
+
+
+@dataclass(slots=True)
+class SiteRevenueEstimate:
+    lat: float
+    lon: float
+    zone: str
+    technology: str
+    capacity_mw: float
+    terrain: SiteRevenueTerrain | None
+    revenue: SiteRevenueMetrics
+    price_snapshot: PriceSnapshot | None
+    caveats: list[str]
+    disclaimer: str
+
+    @classmethod
+    def from_dict(cls, payload: Mapping[str, Any]) -> "SiteRevenueEstimate":
+        terrain_payload = payload.get("terrain")
+        price_payload = payload.get("price_snapshot")
+        return cls(
+            lat=float(payload["lat"]),
+            lon=float(payload["lon"]),
+            zone=str(payload["zone"]),
+            technology=str(payload["technology"]),
+            capacity_mw=float(payload["capacity_mw"]),
+            terrain=SiteRevenueTerrain(**dict(terrain_payload)) if isinstance(terrain_payload, Mapping) else None,
+            revenue=SiteRevenueMetrics(**dict(payload.get("revenue", {}))),
+            price_snapshot=PriceSnapshot(**dict(price_payload)) if isinstance(price_payload, Mapping) else None,
+            caveats=[str(item) for item in payload.get("caveats", [])],
+            disclaimer=str(payload.get("disclaimer", "")),
+        )

luminus/result.py

@@ -0,0 +1,171 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Mapping, Protocol, TypeVar
+
+
+T = TypeVar("T")
+
+
+class SupportsFromDict(Protocol[T]):
+    @classmethod
+    def from_dict(cls, payload: Mapping[str, Any]) -> T: ...
+
+
+@dataclass(slots=True)
+class LuminusResult:
+    tool_name: str
+    raw: Any
+    raw_response: Mapping[str, Any] | None = field(default=None)
+
+    @property
+    def data(self) -> Any:
+        return self.raw
+
+    def to_dict(self) -> Any:
+        return self.raw
+
+    def _resolve_value(self, data_key: str | None = None) -> Any:
+        value = self.raw
+        if data_key is not None:
+            if not isinstance(value, dict) or data_key not in value:
+                raise KeyError(f"{data_key!r} not found in {self.tool_name} result")
+            value = value[data_key]
+        return value
+
+    def _frame_rows(self, data_key: str | None = None) -> list[dict[str, Any]]:
+        value = self._resolve_value(data_key=data_key)
+
+        if isinstance(value, list):
+            if all(isinstance(item, dict) for item in value):
+                return value
+            return [{"value": item} for item in value]
+
+        if isinstance(value, dict):
+            list_keys = [key for key, item in value.items() if isinstance(item, list)]
+            if len(list_keys) == 1:
+                list_key = list_keys[0]
+                rows = value[list_key]
+                meta = {
+                    key: item
+                    for key, item in value.items()
+                    if key != list_key and not isinstance(item, (dict, list))
+                }
+                if all(isinstance(item, dict) for item in rows):
+                    return [{**meta, **row} for row in rows]
+                return [{**meta, "value": item} for item in rows]
+            return [value]
+
+        return [{"value": value}]
+
+    def _extract_lon_lat(self, row: Mapping[str, Any]) -> tuple[float, float] | None:
+        if "lon" in row and "lat" in row:
+            lon = row.get("lon")
+            lat = row.get("lat")
+            if isinstance(lon, (int, float)) and isinstance(lat, (int, float)):
+                return float(lon), float(lat)
+
+        if "longitude" in row and "latitude" in row:
+            lon = row.get("longitude")
+            lat = row.get("latitude")
+            if isinstance(lon, (int, float)) and isinstance(lat, (int, float)):
+                return float(lon), float(lat)
+
+        coords = row.get("coordinates")
+        if isinstance(coords, (list, tuple)) and len(coords) >= 2:
+            lon, lat = coords[0], coords[1]
+            if isinstance(lon, (int, float)) and isinstance(lat, (int, float)):
+                return float(lon), float(lat)
+
+        return None
+
+    def to_pandas(self, data_key: str | None = None):
+        try:
+            import pandas as pd
+        except ImportError as exc:  # pragma: no cover
+            raise RuntimeError(
+                "pandas is not installed. Install luminus-py[notebook] or add pandas manually."
+            ) from exc
+
+        return pd.DataFrame(self._frame_rows(data_key=data_key))
+
+    def to_flat_pandas(self, data_key: str | None = None, *, sep: str = "."):
+        try:
+            import pandas as pd
+        except ImportError as exc:  # pragma: no cover
+            raise RuntimeError(
+                "pandas is not installed. Install luminus-py[notebook] or add pandas manually."
+            ) from exc
+
+        value = self._resolve_value(data_key=data_key)
+        if isinstance(value, list):
+            return pd.json_normalize(value, sep=sep)
+        return pd.json_normalize(value, sep=sep)
+
+    def to_model(self, model_type: type[SupportsFromDict[T]], data_key: str | None = None) -> T:
+        value = self._resolve_value(data_key=data_key)
+        if not isinstance(value, Mapping):
+            raise TypeError(f"{self.tool_name} result is not a mapping and cannot be converted to {model_type.__name__}")
+        return model_type.from_dict(value)
+
+    def to_geojson(self, data_key: str | None = None) -> dict[str, Any]:
+        features: list[dict[str, Any]] = []
+        for row in self._frame_rows(data_key=data_key):
+            lon_lat = self._extract_lon_lat(row)
+            if lon_lat is None:
+                continue
+            lon, lat = lon_lat
+            properties = {
+                key: value
+                for key, value in row.items()
+                if key not in {"lon", "lat", "longitude", "latitude", "coordinates"}
+            }
+            features.append(
+                {
+                    "type": "Feature",
+                    "geometry": {"type": "Point", "coordinates": [lon, lat]},
+                    "properties": properties,
+                }
+            )
+
+        if not features:
+            raise ValueError(
+                f"{self.tool_name} does not contain any rows with lat/lon-style coordinates. "
+                "Pass data_key=... if the geospatial rows live under a nested list."
+            )
+
+        return {"type": "FeatureCollection", "features": features}
+
+    def to_geodataframe(self, data_key: str | None = None, *, crs: str = "EPSG:4326"):
+        try:
+            import geopandas as gpd
+        except ImportError as exc:  # pragma: no cover
+            raise RuntimeError(
+                "geopandas is not installed. Install luminus-py[gis] or luminus-py[all]."
+            ) from exc
+
+        rows: list[dict[str, Any]] = []
+        for row in self._frame_rows(data_key=data_key):
+            lon_lat = self._extract_lon_lat(row)
+            if lon_lat is None:
+                continue
+            lon, lat = lon_lat
+            cleaned = {
+                key: value
+                for key, value in row.items()
+                if key not in {"lon", "lat", "longitude", "latitude", "coordinates"}
+            }
+            cleaned["lon"] = lon
+            cleaned["lat"] = lat
+            rows.append(cleaned)
+
+        if not rows:
+            raise ValueError(
+                f"{self.tool_name} does not contain any rows with lat/lon-style coordinates. "
+                "Pass data_key=... if the geospatial rows live under a nested list."
+            )
+
+        frame = gpd.GeoDataFrame(rows)
+        frame["geometry"] = gpd.points_from_xy(frame["lon"], frame["lat"])
+        frame.set_crs(crs, inplace=True)
+        return frame

luminus_py-0.2.1.dist-info/METADATA

@@ -0,0 +1,196 @@
+Metadata-Version: 2.4
+Name: luminus-py
+Version: 0.2.1
+Summary: Notebook-friendly Python client for luminus-mcp
+Author: Keith So
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/kitfunso/luminus
+Project-URL: Repository, https://github.com/kitfunso/luminus
+Project-URL: Issues, https://github.com/kitfunso/luminus/issues
+Project-URL: Changelog, https://github.com/kitfunso/luminus/blob/master/CHANGELOG.md
+Keywords: mcp,jupyter,notebook,energy,electricity,gis
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Provides-Extra: notebook
+Requires-Dist: pandas>=2.0; extra == "notebook"
+Provides-Extra: gis
+Requires-Dist: geopandas>=0.14; extra == "gis"
+Provides-Extra: all
+Requires-Dist: pandas>=2.0; extra == "all"
+Requires-Dist: geopandas>=0.14; extra == "all"
+
+# luminus-py
+
+A notebook-friendly Python client for `luminus-mcp`.
+
+This package starts the existing Node MCP server under the hood, calls tools over stdio, and returns Python-native result objects with optional pandas helpers.
+
+Any MCP tool exposed by `luminus-mcp` is callable directly as a Python method, so the SDK does not need a hand-written wrapper for every tool.
+
+The SDK also includes geospatial helpers for notebook workflows: `to_geojson()` for lightweight mapping and `to_geodataframe()` for GeoPandas users.
+
+Roadmap: see [`../docs/python-sdk-roadmap.md`](../docs/python-sdk-roadmap.md).
+
+## Install
+
+```bash
+pip install luminus-py[notebook]
+```
+
+For GIS notebook work:
+
+```bash
+pip install luminus-py[all]
+```
+
+You also need `luminus-mcp` itself available on your machine, because the Python SDK starts the existing Node MCP server under the hood.
+
+```bash
+npm install -g luminus-mcp@0.2.0
+```
+
+## API keys
+
+Keyed tools use the same auth model as the Node server. Resolution order is:
+1. environment variables like `ENTSOE_API_KEY`
+2. `~/.luminus/keys.json`
+
+Example `~/.luminus/keys.json`:
+
+```json
+{
+  "ENTSOE_API_KEY": "...",
+  "GIE_API_KEY": "...",
+  "FINGRID_API_KEY": "..."
+}
+```
+
+Per-notebook overrides are also supported:
+
+```python
+lum = Luminus(profile="trader", env={"ENTSOE_API_KEY": "..."})
+```
+
+## Quick start
+
+```python
+from luminus import Luminus
+
+with Luminus(profile="trader") as lum:
+    prices = lum.get_day_ahead_prices(zone="DE")
+    df = prices.to_pandas()
+
+    # Any MCP tool can be called directly
+    flows = lum.get_cross_border_flows(from_zone="DE", to_zone="NL")
+    site = lum.compare_sites(sites=[
+        {"name": "A", "lat": 52.1, "lon": 0.1},
+        {"name": "B", "lat": 52.2, "lon": 0.2},
+    ], country="GB")
+
+    # GIS-friendly exports
+    geojson = site.to_geojson(data_key="rankings")
+
+    # Batch several calls into one DataFrame
+    multi_zone = lum.call_many_to_pandas(
+        "get_day_ahead_prices",
+        [{"zone": "DE"}, {"zone": "FR"}, {"zone": "NL"}],
+        parallel=True,
+    )
+
+    # One-shot export helpers
+    prices_df = lum.call_tool_to_pandas("get_day_ahead_prices", {"zone": "DE"})
+    rankings_geojson = lum.call_tool_to_geojson("compare_sites", {
+        "country": "GB",
+        "sites": [
+            {"label": "A", "lat": 52.1, "lon": 0.1},
+            {"label": "B", "lat": 52.2, "lon": 0.2},
+        ],
+    }, data_key="rankings")
+```
+
+## Notebook demos
+
+Polished notebook demos live in [`examples/`](examples/):
+
+- [Trader workflow](examples/trader_workflow.ipynb)
+- [GIS siting workflow](examples/gis_siting_workflow.ipynb)
+- [BESS shortlist workflow](examples/bess_shortlist_workflow.ipynb)
+
+## Notebook-first helpers
+
+The Python SDK now ships a few opinionated helpers for high-usage analyst flows:
+
+- `lum.get_outages_frame(...)`
+- `lum.get_cross_border_flows_many([...])`
+- `lum.get_grid_proximity_substations(...)`
+- `lum.get_grid_proximity_lines(...)`
+- `lum.get_grid_proximity_snapshot(...)`
+- `lum.get_grid_connection_queue_projects(...)`
+- `lum.get_grid_connection_queue_sites(...)`
+- `lum.get_grid_connection_queue_snapshot(...)`
+- `lum.estimate_site_revenue_frame(...)`
+- `lum.estimate_site_revenue_estimate(...)`
+
+Example:
+
+```python
+from luminus import GridProximitySnapshot, Luminus, SiteRevenueEstimate
+
+with Luminus(profile="gis") as lum:
+    outages = lum.get_outages_frame(zone="DE", type="generation")
+    flows = lum.get_cross_border_flows_many([("DE", "NL"), ("FR", "DE")])
+    substations = lum.get_grid_proximity_substations(lat=52.0, lon=0.1)
+    queue = lum.get_grid_connection_queue_projects(connection_site_query="Berkswell")
+    revenue = lum.estimate_site_revenue_frame(
+        lat=52.0,
+        lon=0.1,
+        zone="GB",
+        technology="bess",
+        capacity_mw=20,
+    )
+
+    proximity: GridProximitySnapshot = lum.get_grid_proximity_snapshot(lat=52.0, lon=0.1)
+    estimate: SiteRevenueEstimate = lum.estimate_site_revenue_estimate(
+        lat=52.0,
+        lon=0.1,
+        zone="GB",
+        technology="bess",
+    )
+```
+
+## Errors and typed models
+
+- Startup failures now raise `LuminusStartupError`.
+- Tool-side configuration failures raise `LuminusConfigurationError`.
+- Tool-side upstream/data-source failures raise `LuminusUpstreamError`.
+- Dynamic whole-surface access still works through `LuminusResult`, and common GIS/revenue flows also expose opt-in typed models.
+
+## Notes
+
+- Use `lum.list_tools()` to see the live tool surface for the active profile.
+- Use `lum.describe_tool("tool_name")` to inspect the MCP description/schema metadata.
+- Use `lum.call_many()` / `lum.call_many_to_pandas()` for generic multi-zone or multi-site notebook pulls.
+- Use `parallel=True` on batch helpers when you want the SDK to fan out across multiple MCP subprocesses.
+- Use `lum.get_day_ahead_prices_many()` and `lum.get_generation_mix_many()` for common analyst workflows.
+- Use `lum.compare_sites_rankings()` together with `lum.compare_sites_rankings_geojson()` and `lum.compare_sites_rankings_geodataframe()` for ranked siting output.
+- Use the typed snapshots only when they help notebook readability; the raw dynamic MCP surface is still available.
+- Notebook demos live in [`examples/`](examples/).
+- Use `to_geojson()` for lightweight mapping and `to_geodataframe()` when GeoPandas is installed.
+
+- Requires `luminus-mcp` to be available on `PATH`, unless you pass an explicit command.
+- By default the client starts `luminus-mcp --profile <profile>`.
+- For local repo development you can point it at the built server directly:
+
+```python
+lum = Luminus(command=["node", r"C:\Users\skf_s\luminus\dist\index.js"], profile="gis")
+```

luminus_py-0.2.1.dist-info/RECORD

@@ -0,0 +1,9 @@
+luminus/__init__.py,sha256=_VkqfBKd9s11gOl8l7o06nRk_k3gzvEdGLQg2pBmuWY,711
+luminus/client.py,sha256=tkP6e82_vu7uxOtHqJseamSgYP55gGd4rfh0wWRI6aw,18759
+luminus/exceptions.py,sha256=-L6budfNM4KIPrpBM6if3eeYDvNvazAZ2xKDCScisVc,787
+luminus/models.py,sha256=3E-FGHpXs5o45DdRRPugUi3SfbFAlnGg1udw9r_9g8M,6205
+luminus/result.py,sha256=h-W1MzkjXSv5G4J5ODbTuiTdNa6ZEJLflQhJfRmOqAA,6371
+luminus_py-0.2.1.dist-info/METADATA,sha256=r9n5k48SiAT-IoV462IGMDspevIkvZ2Vs9okLpuwPdE,6974
+luminus_py-0.2.1.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+luminus_py-0.2.1.dist-info/top_level.txt,sha256=QZbm58e06XmpdHCp0wmvC8pVwEXD6rFSgZzwbt50IaM,8
+luminus_py-0.2.1.dist-info/RECORD,,

luminus_py-0.2.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

luminus_py-0.2.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+luminus