feat: Add gas support (v0.3.0)

- Add GasConsumption, GasTariff, GasMeterPoint models
- Add get_gas_consumption(), get_daily_gas_usage(), get_gas_tariff() methods
- Add gas tools to Claude agent (get_gas_usage, get_gas_tariff)
- Auto-convert m³ to kWh for SMETS2 meters
- Clean up README with better structure
- Update .env.example with gas environment variables

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: solboy

.env.example

@@ -2,9 +2,13 @@
 OCTOPUS_API_KEY=sk_live_xxx
 OCTOPUS_ACCOUNT=A-XXXXXXXX
 
-# Optional: for consumption data
+# Electricity meter (optional, for consumption data)
 OCTOPUS_MPAN=1234567890123
 OCTOPUS_METER_SERIAL=12A3456789
 
-# Optional: for Claude AI agent (octopus-ask)
+# Gas meter (optional, for gas consumption)
+OCTOPUS_GAS_MPRN=1234567890
+OCTOPUS_GAS_METER_SERIAL=G4A12345
+
+# Claude AI agent (optional, for octopus-ask)
 ANTHROPIC_API_KEY=sk-ant-xxx

README.md

@@ -1,30 +1,19 @@
 # Open Octopus 🐙
 
-Modern async Python client for the **Octopus Energy GraphQL API**.
-
-Supports features not available in the REST API:
-- ⚡ **Live power consumption** (requires Home Mini)
-- 🔌 **Intelligent Octopus dispatch slots**
-- 🎁 **Saving Sessions** / Free Electricity events
-- 💰 **Account balance** and tariff info
-- 🖥️ **macOS menu bar app** for live monitoring
-- 🤖 **Claude AI agent** for natural language queries
-
-## Installation
+Modern async Python client for the **Octopus Energy API**.
 
 ```bash
-# Core library
 pip install open-octopus
+```
 
-# With macOS menu bar app
-pip install 'open-octopus[menubar]'
-
-# With Claude AI agent
-pip install 'open-octopus[agent]'
+## Features
 
-# Everything
-pip install 'open-octopus[all]'
-```
+- ⚡ **Live power** - Real-time consumption (Home Mini)
+- 🔌 **Smart charging** - Intelligent Octopus dispatch slots
+- 🎁 **Saving Sessions** - Free electricity events
+- 🔥 **Dual fuel** - Electricity + gas support
+- 🤖 **AI agent** - Natural language queries
+- 🖥️ **Menu bar** - macOS status bar app
 
 ## Quick Start
 
@@ -37,245 +26,117 @@ async def main():
         api_key="sk_live_xxx",
         account="A-XXXXXXXX"
     ) as client:
-        # Get account balance
+        # Account
         account = await client.get_account()
         print(f"Balance: £{account.balance:.2f}")
 
-        # Get current rate
+        # Current rate
         tariff = await client.get_tariff()
         rate = client.get_current_rate(tariff)
-        print(f"Rate: {rate.rate}p/kWh ({'off-peak' if rate.is_off_peak else 'peak'})")
+        print(f"Rate: {rate.rate}p ({'off-peak' if rate.is_off_peak else 'peak'})")
 
-        # Get live power (requires Home Mini)
+        # Live power (requires Home Mini)
         power = await client.get_live_power()
         if power:
-            print(f"Current draw: {power.demand_kw:.2f} kW")
+            print(f"Power: {power.demand_kw:.2f} kW")
 
 asyncio.run(main())
 ```
 
-## CLI Usage
+## Environment Variables
 
 ```bash
-# Set environment variables
+# Required
 export OCTOPUS_API_KEY="sk_live_xxx"
 export OCTOPUS_ACCOUNT="A-XXXXXXXX"
-export OCTOPUS_MPAN="1234567890123"  # Optional, for consumption data
-export OCTOPUS_METER_SERIAL="12A3456789"  # Optional
-
-# Show account info
-octopus account
-
-# Show current rate
-octopus rate
-
-# Show dispatch status (Intelligent Octopus)
-octopus dispatch
-
-# Show live power consumption
-octopus power
-
-# Show upcoming saving sessions
-octopus sessions
-
-# Show daily usage
-octopus usage --days 7
-
-# Full status overview
-octopus status
-
-# Watch live power (updates every 30s)
-octopus watch
-```
-
-## Features
-
-### Account & Billing
-
-```python
-account = await client.get_account()
-print(f"Name: {account.name}")
-print(f"Balance: £{account.balance:.2f}")
-print(f"Status: {account.status}")
-```
-
-### Tariff & Rates
-
-```python
-tariff = await client.get_tariff()
-print(f"Tariff: {tariff.name}")
-print(f"Standing charge: {tariff.standing_charge}p/day")
-
-# Get current rate with time-of-use info
-rate = client.get_current_rate(tariff)
-print(f"Current: {rate.rate}p/kWh")
-print(f"Off-peak: {rate.is_off_peak}")
-print(f"Changes at: {rate.period_end}")
-```
-
-### Consumption Data
-
-```python
-# Get last 48 half-hourly readings
-consumption = await client.get_consumption(periods=48)
-for c in consumption:
-    print(f"{c.start}: {c.kwh:.3f} kWh")
-
-# Get daily totals
-daily = await client.get_daily_usage(days=7)
-for date, kwh in daily.items():
-    print(f"{date}: {kwh:.1f} kWh")
-```
-
-### Intelligent Octopus Dispatches
-
-```python
-# Check if currently charging
-status = await client.get_dispatch_status()
-if status.is_dispatching:
-    print(f"Charging until {status.current_dispatch.end}")
-elif status.next_dispatch:
-    print(f"Next charge: {status.next_dispatch.start}")
-
-# Get all scheduled dispatches
-dispatches = await client.get_dispatches()
-for d in dispatches:
-    print(f"{d.start} - {d.end} ({d.duration_minutes}min)")
-```
-
-### Saving Sessions
 
-```python
-sessions = await client.get_saving_sessions()
-for s in sessions:
-    if s.is_active:
-        print(f"FREE POWER until {s.end}!")
-    else:
-        print(f"Upcoming: {s.start} - {s.end}")
-        print(f"  Reward: {s.reward_per_kwh} Octopoints/kWh")
-```
+# Electricity meter (optional)
+export OCTOPUS_MPAN="1234567890123"
+export OCTOPUS_METER_SERIAL="12A3456789"
 
-### Live Power (Home Mini)
+# Gas meter (optional)
+export OCTOPUS_GAS_MPRN="1234567890"
+export OCTOPUS_GAS_METER_SERIAL="G4A12345"
 
-Requires a [Home Mini](https://octopus.energy/blog/home-mini/) paired with your smart meter.
-
-```python
-power = await client.get_live_power()
-if power:
-    print(f"Demand: {power.demand_watts}W")
-    print(f"Read at: {power.read_at}")
-
-    # Calculate cost per hour
-    tariff = await client.get_tariff()
-    rate = client.get_current_rate(tariff)
-    cost_per_hour = (power.demand_watts / 1000) * rate.rate
-    print(f"Cost: {cost_per_hour:.1f}p/hour")
+# AI agent (optional)
+export ANTHROPIC_API_KEY="sk-ant-xxx"
 ```
 
-## macOS Menu Bar App
-
-Live energy monitoring in your menu bar:
+## CLI
 
 ```bash
-# Install with menubar support
-pip install 'open-octopus[menubar]'
-
-# Run
-octopus-menubar
+octopus status      # Full overview
+octopus rate        # Current rate
+octopus power       # Live consumption
+octopus dispatch    # Charging status
+octopus usage       # Daily usage
+octopus gas         # Gas usage
 ```
 
-Shows:
-- ⚡ Live power consumption (with Home Mini)
-- 🌙/☀️ Current rate (off-peak/peak)
-- 🔌 Charging status (Intelligent Octopus)
-- 🎁 Saving Sessions alerts
-- 💰 Account balance
-
-## Claude AI Agent
+## AI Agent
 
-Ask questions about your energy in plain English:
+Ask questions in plain English:
 
 ```bash
-# Install with agent support
 pip install 'open-octopus[agent]'
 
-# Set your Anthropic API key
-export ANTHROPIC_API_KEY="sk-ant-xxx"
-
-# Ask questions
-octopus-ask "What's my current power usage?"
+octopus-ask "What's my current rate?"
+octopus-ask "How much gas did I use yesterday?"
 octopus-ask "When is my next charging window?"
-octopus-ask "How much did I use yesterday?"
-octopus-ask "Am I on off-peak rates right now?"
 ```
 
-Or use in Python:
+## Gas Support
 
 ```python
-from open_octopus import OctopusAgent
-import asyncio
-
-async def main():
-    agent = OctopusAgent()
-    response = await agent.ask("What's my current rate?")
-    print(response)
-
-asyncio.run(main())
+async with OctopusClient(
+    api_key="sk_live_xxx",
+    account="A-XXXXXXXX",
+    gas_mprn="1234567890",
+    gas_meter_serial="G4A12345"
+) as client:
+    # Gas consumption
+    gas = await client.get_gas_consumption(periods=48)
+    for reading in gas:
+        print(f"{reading.start}: {reading.kwh:.2f} kWh")
+
+    # Gas tariff
+    tariff = await client.get_gas_tariff()
+    print(f"Rate: {tariff.unit_rate}p/kWh")
+
+    # Daily gas usage
+    daily = await client.get_daily_gas_usage(days=7)
+    for date, kwh in daily.items():
+        print(f"{date}: {kwh:.1f} kWh")
 ```
 
-## Configuration
-
-### Environment Variables
-
-| Variable | Required | Description |
-|----------|----------|-------------|
-| `OCTOPUS_API_KEY` | Yes | API key from Octopus dashboard |
-| `OCTOPUS_ACCOUNT` | Yes | Account number (e.g., A-FB05ED6C) |
-| `OCTOPUS_MPAN` | No | Meter Point Admin Number (for consumption) |
-| `OCTOPUS_METER_SERIAL` | No | Electricity meter serial number |
-| `ANTHROPIC_API_KEY` | For agent | Anthropic API key (for octopus-ask) |
-
-### Getting Your API Key
-
-1. Log in to [Octopus Energy](https://octopus.energy/dashboard/)
-2. Go to **Developer Settings**
-3. Copy your API key (starts with `sk_live_`)
-
-### Finding Your MPAN
+## Menu Bar (macOS)
 
-Your MPAN is on your electricity bill, or run:
-
-```python
-# The API can discover your meter points
-account = await client.get_account()
-print(account)  # Includes property info
+```bash
+pip install 'open-octopus[menubar]'
+octopus-menubar
 ```
 
-## Comparison with Other Libraries
-
-| Feature | open-octopus | octopus-energy | Home Assistant |
-|---------|--------------|----------------|----------------|
-| REST API | ✅ | ✅ | ✅ |
-| GraphQL API | ✅ | ❌ | ✅ |
-| Live power (Home Mini) | ✅ | ❌ | ✅ |
-| Intelligent dispatches | ✅ | ❌ | ✅ |
-| Saving sessions | ✅ | ❌ | ✅ |
-| Account balance | ✅ | ❌ | ✅ |
-| Standalone library | ✅ | ✅ | ❌ |
-| CLI tool | ✅ | ❌ | ❌ |
-| Async/await | ✅ | ✅ | ❌ |
-| Typed models | ✅ | ❌ | ❌ |
-
-## License
+Shows live power, current rate, charging status, and balance.
 
-MIT License - see [LICENSE](LICENSE) for details.
+## API Reference
 
-## Contributing
+### Client Methods
 
-Contributions welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) first.
+| Method | Description |
+|--------|-------------|
+| `get_account()` | Account info and balance |
+| `get_tariff()` | Electricity tariff details |
+| `get_current_rate(tariff)` | Current rate with off-peak status |
+| `get_consumption()` | Half-hourly electricity readings |
+| `get_daily_usage()` | Daily electricity totals |
+| `get_live_power()` | Real-time power (Home Mini) |
+| `get_dispatches()` | Intelligent Octopus charge slots |
+| `get_dispatch_status()` | Current charging status |
+| `get_saving_sessions()` | Free electricity events |
+| `get_gas_consumption()` | Half-hourly gas readings |
+| `get_daily_gas_usage()` | Daily gas totals |
+| `get_gas_tariff()` | Gas tariff details |
 
-## Links
+## License
 
-- [Octopus Energy Developer API](https://developer.octopus.energy/)
-- [GraphQL API Documentation](https://developer.octopus.energy/graphql/)
-- [Report Issues](https://github.com/abracadabra50/open-octopus/issues)
+MIT

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "open-octopus"
-version = "0.2.0"
+version = "0.3.0"
 description = "Modern async Python client for the Octopus Energy GraphQL API"
 readme = "README.md"
 license = "MIT"