Refactor tinygrid/ercot.py into modular subpackage

README.md

@@ -54,6 +54,50 @@ as_prices = ercot.get_as_prices(start="2024-01-15")
 as_plan = ercot.get_as_plan(start="2024-01-15")
 ```
 
+### Real-Time Grid Data
+
+Access real-time grid data using the unified API:
+
+```python
+from tinygrid import ERCOT
+
+ercot = ERCOT()
+
+# Get actual system load by weather zone
+load = ercot.get_load(start="today", by="weather_zone")
+
+# Get wind generation forecast
+wind = ercot.get_wind_forecast(start="today")
+
+# Get solar generation forecast  
+solar = ercot.get_solar_forecast(start="today")
+
+# Get load forecast
+load_forecast = ercot.get_load_forecast_by_weather_zone(
+    start_date="2024-12-28",
+    end_date="2024-12-29",
+)
+```
+
+### Historical Yearly Data
+
+Access complete yearly historical data from ERCOT's MIS document system:
+
+```python
+from tinygrid import ERCOT
+
+ercot = ERCOT()
+
+# Get full year of RTM settlement point prices
+rtm_2023 = ercot.get_rtm_spp_historical(2023)
+
+# Get full year of DAM settlement point prices
+dam_2023 = ercot.get_dam_spp_historical(2023)
+
+# Get settlement point mapping
+mapping = ercot.get_settlement_point_mapping()
+```
+
 ### Direct Endpoint Access
 
 For full control, call any of the 100+ ERCOT endpoints directly:
@@ -84,20 +128,47 @@ forecast = ercot.get_load_forecast_by_weather_zone(
 )
 ```
 
-See [`examples/ercot_example.py`](examples/ercot_example.py) for complete examples.
+See [`examples/ercot_demo.ipynb`](examples/ercot_demo.ipynb) for complete examples.
 
 ## Unified API Methods
 
 These methods provide a simpler interface with automatic routing, date parsing, and historical data access:
 
+### Pricing Methods
+
 | Method | Description | Markets |
 |--------|-------------|---------|
 | `get_spp()` | Settlement Point Prices | Real-time 15-min, Day-ahead hourly |
 | `get_lmp()` | Locational Marginal Prices | Real-time SCED, Day-ahead hourly |
 | `get_as_prices()` | Ancillary Services MCPC prices | Day-ahead |
 | `get_as_plan()` | Ancillary Services plan | Day-ahead |
-| `get_wind_forecast()` | Wind power forecast | System-wide or by region |
-| `get_solar_forecast()` | Solar power forecast | System-wide or by region |
+| `get_shadow_prices()` | Transmission constraint shadow prices | Real-time SCED, Day-ahead |
+
+### Forecast Methods
+
+| Method | Description |
+|--------|-------------|
+| `get_wind_forecast()` | Wind power forecast (system-wide or by region) |
+| `get_solar_forecast()` | Solar power forecast (system-wide or by region) |
+| `get_load()` | Actual system load by weather or forecast zone |
+
+### Direct Endpoint Methods
+
+For full control, 100+ low-level endpoint methods are available:
+
+| Category | Example Methods |
+|----------|----------------|
+| Load | `get_actual_system_load_by_weather_zone()`, `get_load_forecast_by_weather_zone()` |
+| Generation | `get_generation_by_resource_type()`, `get_wpp_hourly_average_actual_forecast()` |
+| Pricing | `get_dam_settlement_point_prices()`, `get_spp_node_zone_hub()` |
+
+### Historical Yearly Methods
+
+| Method | Description |
+|--------|-------------|
+| `get_rtm_spp_historical(year)` | Full year RTM settlement point prices |
+| `get_dam_spp_historical(year)` | Full year DAM settlement point prices |
+| `get_settlement_point_mapping()` | Settlement point to bus mapping |
 
 ### Features
 
@@ -115,6 +186,8 @@ Authentication is required for some endpoints. To get credentials:
 2. Subscribe to the API products you need
 3. Use your email, password, and subscription key
 
+**Note:** Dashboard methods (`get_status()`, `get_fuel_mix()`, etc.) do not require authentication.
+
 ## Available ERCOT Endpoints
 
 Direct access to 100+ ERCOT endpoints organized by category:
@@ -171,15 +244,23 @@ except GridTimeoutError as e:
 
 ```
 tinygrid/
-├── tinygrid/           # SDK layer
-│   ├── ercot.py        # ERCOT client with unified and direct API methods
-│   ├── auth/           # Authentication handling
-│   ├── constants/      # Market types, location enums, endpoint mappings
-│   ├── utils/          # Date parsing, timezone handling, decorators
-│   └── errors.py       # Error types
-├── pyercot/            # Auto-generated ERCOT API client (from OpenAPI spec)
-├── examples/           # Usage examples
-└── tests/              # Test suite (258 tests)
+├── tinygrid/              # SDK layer
+│   ├── ercot/             # ERCOT client package
+│   │   ├── __init__.py    # Main ERCOT class (combining mixins)
+│   │   ├── client.py      # ERCOTBase with auth, retry, pagination
+│   │   ├── endpoints.py   # Low-level pyercot wrappers (~100 methods)
+│   │   ├── api.py         # High-level unified API methods
+│   │   ├── archive.py     # Historical archive access
+│   │   ├── dashboard.py   # Public dashboard methods (no auth)
+│   │   ├── documents.py   # MIS document fetching
+│   │   └── transforms.py  # Data filtering/transformation utilities
+│   ├── auth/              # Authentication handling
+│   ├── constants/         # Market types, location enums, endpoint mappings
+│   ├── utils/             # Date parsing, timezone handling, decorators
+│   └── errors.py          # Error types
+├── pyercot/               # Auto-generated ERCOT API client (from OpenAPI spec)
+├── examples/              # Usage examples
+└── tests/                 # Test suite (505 tests)
 ```
 
 ## Development

examples/README.md

@@ -32,32 +32,26 @@ ERCOT_SUBSCRIPTION_KEY=your-key
 
 ## Examples
 
-### Unified API Demo (Notebook)
+### Demo Notebook
 
-The `unified_api_demo.ipynb` notebook demonstrates the new unified API with:
+The `ercot_demo.ipynb` notebook demonstrates the full tinygrid API with:
 
-- **Type-safe enums** (`Market`, `LocationType`) for IDE autocomplete
-- **Date parsing** with "today", "yesterday", "latest" keywords
-- **Unified methods** like `get_spp()`, `get_lmp()`, `get_as_prices()`
-- **Location filtering** by Load Zone, Trading Hub, or Resource Node
+- **Unified API** - `get_spp()`, `get_lmp()`, `get_as_prices()` with automatic routing
+- **Dashboard API** - No-auth methods like `get_status()`, `get_fuel_mix()`
+- **Historical Yearly Data** - `get_rtm_spp_historical(year)`, `get_dam_spp_historical(year)`
+- **Type-safe enums** - `Market`, `LocationType` for IDE autocomplete
+- **Date parsing** - "today", "yesterday", "latest" keywords
+- **Location filtering** - Filter by Load Zone, Trading Hub, or Resource Node
 
 ```bash
 # Run with Jupyter
-uv run jupyter notebook examples/unified_api_demo.ipynb
-```
-
-### Python Scripts
-
-```bash
-# Basic ERCOT demo
-uv run python examples/ercot_demo.py
-
-# Validate all endpoints
-uv run python examples/validate_all_endpoints.py
+uv run jupyter notebook examples/ercot_demo.ipynb
 ```
 
 ## Quick Start
 
+### Unified API
+
 ```python
 from tinygrid import ERCOT, Market, LocationType
 
@@ -78,4 +72,106 @@ df = ercot.get_lmp(
 
 # Get ancillary service prices
 df = ercot.get_as_prices(start="yesterday")
+
+# Get wind and solar forecasts
+wind = ercot.get_wind_forecast(start="today")
+solar = ercot.get_solar_forecast(by_region=True)
+```
+
+### Load and Forecast Data
+
+```python
+from tinygrid import ERCOT
+
+ercot = ERCOT()
+
+# Get actual system load
+load = ercot.get_load(start="today", by="weather_zone")
+
+# Get wind forecast
+wind = ercot.get_wind_forecast(start="today")
+
+# Get solar forecast
+solar = ercot.get_solar_forecast(start="today")
+
+# Get load forecast (direct endpoint)
+forecast = ercot.get_load_forecast_by_weather_zone(
+    start_date="2024-12-28",
+    end_date="2024-12-29",
+)
 ```
+
+### Historical Yearly Data
+
+Access complete yearly historical data from ERCOT's MIS document system:
+
+```python
+from tinygrid import ERCOT
+
+ercot = ERCOT()
+
+# Get full year of RTM settlement point prices
+rtm_2023 = ercot.get_rtm_spp_historical(2023)
+
+# Get full year of DAM settlement point prices
+dam_2023 = ercot.get_dam_spp_historical(2023)
+
+# Get settlement point mapping
+mapping = ercot.get_settlement_point_mapping()
+```
+
+### Direct Endpoint Access
+
+For full control over API parameters:
+
+```python
+from tinygrid import ERCOT, ERCOTAuth, ERCOTAuthConfig
+
+# Set up authentication
+auth = ERCOTAuth(ERCOTAuthConfig(
+    username="your-email@example.com",
+    password="your-password",
+    subscription_key="your-key",
+))
+
+ercot = ERCOT(auth=auth)
+
+# Call endpoints directly
+load_data = ercot.get_actual_system_load_by_weather_zone(
+    operating_day_from="2024-12-20",
+    operating_day_to="2024-12-20",
+    size=24,
+)
+```
+
+## API Reference
+
+### Unified Methods
+
+| Method | Description |
+|--------|-------------|
+| `get_spp()` | Settlement Point Prices |
+| `get_lmp()` | Locational Marginal Prices |
+| `get_as_prices()` | Ancillary Services MCPC prices |
+| `get_as_plan()` | Ancillary Services plan |
+| `get_wind_forecast()` | Wind power forecast |
+| `get_solar_forecast()` | Solar power forecast |
+| `get_load()` | Actual system load |
+| `get_shadow_prices()` | Transmission constraint shadow prices |
+
+### Load and Forecast Methods
+
+| Method | Description |
+|--------|-------------|
+| `get_load()` | Actual system load by zone |
+| `get_wind_forecast()` | Wind power forecast |
+| `get_solar_forecast()` | Solar power forecast |
+| `get_load_forecast_by_weather_zone()` | Load forecast |
+
+### Historical Methods
+
+| Method | Description |
+|--------|-------------|
+| `get_rtm_spp_historical(year)` | Full year RTM SPP |
+| `get_dam_spp_historical(year)` | Full year DAM SPP |
+| `get_settlement_point_mapping()` | Settlement point mapping |