python-sdk-roadmap.md

Python SDK roadmap

Status tracker for the notebook-friendly Python client that wraps luminus-mcp.

Shipped baseline

• Initial luminus-py package scaffold under python/
• Stdio client that starts luminus-mcp and speaks MCP over subprocess pipes
• Dynamic tool binding so any live MCP tool can be called as a Python method
• to_pandas() result export
• to_geojson() and to_geodataframe() helpers for GIS workflows
• Batch helpers: call_many() and call_many_to_pandas()
• Parallel batch fan-out via multiple MCP subprocesses
• Higher-level notebook helpers for common flows like multi-zone prices, generation mix, and ranked site comparison
• Notebook examples for quickstart, GIS screening, BESS ranked screening, map exports, multi-zone prices, and auth setup
• Analyst-ready notebook demos for trader workflow, GIS siting workflow, and BESS shortlist workflow
• More opinionated notebook helpers for outages, cross-border flows, grid proximity, grid connection queue, and site revenue
• CI coverage for Python tests and packaging checks on push / PR
• Clearer Python-side error translation for startup failures, missing API keys, and upstream tool errors
• Lightweight typed result models for common GIS and site-revenue flows
• Python packaging metadata, buildable wheel/sdist, and local packaging checks

Current status

• Publish luminus-py to PyPI via GitHub Trusted Publishing (v0.3.0)
• Revisit async execution or smarter client/process pooling if heavy notebook fan-out becomes a bottleneck

Prioritised next actions

1. Revisit async execution or smarter client/process pooling if heavy notebook fan-out becomes a bottleneck

Guardrails

• Keep the Python SDK notebook-first: DataFrames, GeoJSON, GeoDataFrames, and simple methods beat exposing raw MCP details
• Do not fork business logic into a full Python reimplementation unless there is a strong reason to stop reusing the Node MCP server
• Prefer a thin wrapper over the live MCP surface before adding heavyweight notebook UI integrations