gridos 0.1.0__tar.gz

gridos-0.1.0/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+All notable changes to GridOS will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2025-03-06
+
+### Added
+
+- **Core Models**: Pydantic v2 data models for DER telemetry, device info, and control commands
+- **Protocol Adapters**: Base adapter framework with Modbus TCP, MQTT, DNP3, IEC 61850, and OPC-UA implementations
+- **Storage Backends**: InfluxDB 2.x and TimescaleDB storage backends with async interfaces
+- **Digital Twin Engine**: Physics-based models for Bus, Line, Transformer, Load, PV, Battery, and EV Charger
+- **Power Flow Solver**: Simplified backward/forward sweep for radial distribution networks
+- **ML Forecasting**: LSTM-based time-series forecaster with PyTorch (persistence fallback)
+- **Anomaly Detection**: Isolation Forest detector with scikit-learn (threshold fallback)
+- **MILP Optimiser**: PuLP-based energy management scheduler with greedy heuristic fallback
+- **Real-time Dispatch**: Schedule-to-device dispatch engine via adapter layer
+- **REST API**: FastAPI-based API with device, telemetry, control, forecast, and optimisation endpoints
+- **WebSocket**: Live telemetry streaming with per-device subscriptions
+- **Edge Support**: SQLite store-and-forward cache with cloud sync
+- **Security**: API key and JWT authentication with role-based access control
+- **Utilities**: Structured JSON logging, Prometheus metrics, helper functions
+- **Docker**: Multi-stage Dockerfile and Docker Compose with InfluxDB
+- **Kubernetes**: Deployment manifests with HPA auto-scaling
+- **CI/CD**: GitHub Actions workflows for linting, testing, security scanning, and Docker builds
+- **Documentation**: Architecture guide, API reference, deployment guide
+- **Sample Data**: Load profile and solar irradiance CSV datasets
+- **Quick Start**: Demo script showcasing all major features

gridos-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,106 @@
+# Contributing to GridOS
+
+Thank you for your interest in contributing to GridOS! This document provides guidelines and instructions for contributing to the project.
+
+## Code of Conduct
+
+By participating in this project, you agree to abide by our [Code of Conduct](CODE_OF_CONDUCT.md).
+
+## How to Contribute
+
+### Reporting Issues
+
+- Use [GitHub Issues](https://github.com/your-org/GridOS/issues) to report bugs or request features
+- Search existing issues before creating a new one
+- Include steps to reproduce, expected behaviour, and actual behaviour for bugs
+- Include your environment details (OS, Python version, GridOS version)
+
+### Submitting Changes
+
+1. **Fork** the repository
+2. **Create a branch** from `develop`:
+   ```bash
+   git checkout -b feature/your-feature-name develop
+   ```
+3. **Make your changes** following the coding standards below
+4. **Write tests** for new functionality
+5. **Run the test suite**:
+   ```bash
+   pytest tests/ -v --cov=gridos
+   ```
+6. **Run linting**:
+   ```bash
+   ruff check src/ tests/
+   ruff format src/ tests/
+   ```
+7. **Commit** with a clear message:
+   ```bash
+   git commit -m "feat: add support for SunSpec protocol adapter"
+   ```
+8. **Push** and create a **Pull Request** against `develop`
+
+### Commit Message Format
+
+We follow [Conventional Commits](https://www.conventionalcommits.org/):
+
+| Prefix | Description |
+|--------|-------------|
+| `feat:` | New feature |
+| `fix:` | Bug fix |
+| `docs:` | Documentation changes |
+| `test:` | Adding or updating tests |
+| `refactor:` | Code refactoring |
+| `perf:` | Performance improvement |
+| `ci:` | CI/CD changes |
+| `chore:` | Maintenance tasks |
+
+### Coding Standards
+
+- **Python 3.10+** with type hints on all public functions
+- **Pydantic v2** for data models
+- **async/await** for all I/O operations
+- **Ruff** for linting and formatting
+- **pytest** for testing with >80% coverage target
+- **Docstrings** in NumPy style for all public classes and functions
+- **Logging** via `logging.getLogger(__name__)` — no `print()` statements
+
+### Adding a New Protocol Adapter
+
+1. Create `src/gridos/adapters/your_protocol.py`
+2. Inherit from `BaseAdapter`
+3. Implement `connect()`, `disconnect()`, `read_telemetry()`, `write_command()`
+4. Add tests in `tests/test_adapters.py`
+5. Update `src/gridos/adapters/__init__.py`
+6. Document in `docs/architecture.md`
+
+### Adding a New Physics Model
+
+1. Create `src/gridos/digital_twin/models/your_component.py`
+2. Implement `update(dt, grid_state)` method
+3. Register in `GridModel` class
+4. Add tests in `tests/test_digital_twin.py`
+
+## Development Setup
+
+```bash
+# Clone your fork
+git clone https://github.com/your-username/GridOS.git
+cd GridOS
+
+# Create virtual environment
+python -m venv .venv
+source .venv/bin/activate
+
+# Install in development mode
+pip install -e ".[dev]"
+
+# Run tests
+pytest tests/ -v
+
+# Run linting
+ruff check src/ tests/
+```
+
+## Questions?
+
+Open a [Discussion](https://github.com/your-org/GridOS/discussions) or reach out to the maintainers.

gridos-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 GridOS Contributors
+
+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.

gridos-0.1.0/MANIFEST.in

@@ -0,0 +1,16 @@
+include LICENSE
+include README.md
+include CHANGELOG.md
+include CONTRIBUTING.md
+include pyproject.toml
+include requirements/*.txt
+
+recursive-include src/gridos *.py *.pyi
+recursive-include data *.csv *.json
+
+prune tests
+prune notebooks
+prune k8s
+prune docker
+prune scripts
+prune .github

gridos-0.1.0/PKG-INFO

@@ -0,0 +1,270 @@
+Metadata-Version: 2.4
+Name: gridos
+Version: 0.1.0
+Summary: GridOS — Open Energy Operating System: vendor-neutral middleware for Distributed Energy Resources.
+Author: GridOS Contributors
+License: MIT
+Project-URL: Homepage, https://github.com/iceccarelli/GridOS
+Project-URL: Documentation, https://github.com/iceccarelli/GridOS/tree/main/docs
+Project-URL: Repository, https://github.com/iceccarelli/GridOS
+Project-URL: Issues, https://github.com/iceccarelli/GridOS/issues
+Project-URL: Changelog, https://github.com/iceccarelli/GridOS/blob/main/CHANGELOG.md
+Keywords: energy,smart-grid,DER,digital-twin,microgrid,SCADA,IoT,IEC61850,Modbus,MQTT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+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: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastapi>=0.110.0
+Requires-Dist: uvicorn[standard]>=0.27.0
+Requires-Dist: pydantic>=2.6.0
+Requires-Dist: pydantic-settings>=2.1.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: structlog>=24.1.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: numpy>=1.26.0
+Requires-Dist: pandas>=2.2.0
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: ml
+Requires-Dist: scikit-learn>=1.4.0; extra == "ml"
+Requires-Dist: torch>=2.2.0; extra == "ml"
+Requires-Dist: pulp>=2.8.0; extra == "ml"
+Requires-Dist: matplotlib>=3.8.0; extra == "ml"
+Requires-Dist: joblib>=1.3.0; extra == "ml"
+Provides-Extra: adapters
+Requires-Dist: pymodbus>=3.6.0; extra == "adapters"
+Requires-Dist: paho-mqtt>=2.0.0; extra == "adapters"
+Requires-Dist: asyncua>=1.1.0; extra == "adapters"
+Provides-Extra: storage
+Requires-Dist: influxdb-client[async]>=1.40.0; extra == "storage"
+Requires-Dist: asyncpg>=0.29.0; extra == "storage"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
+Requires-Dist: black>=24.1.0; extra == "dev"
+Requires-Dist: ruff>=0.2.0; extra == "dev"
+Requires-Dist: mypy>=1.8.0; extra == "dev"
+Requires-Dist: pre-commit>=3.6.0; extra == "dev"
+Requires-Dist: jupyter>=1.0.0; extra == "dev"
+Dynamic: license-file
+
+# GridOS — Open Energy Operating System
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
+[![PyPI version](https://img.shields.io/pypi/v/gridos.svg)](https://pypi.org/project/gridos/)
+[![PyPI downloads](https://img.shields.io/pypi/dm/gridos.svg)](https://pypi.org/project/gridos/)
+[![Docker Image](https://img.shields.io/badge/docker-ghcr.io%2Ficeccarelli%2Fgridos-blue?logo=docker)](https://github.com/iceccarelli/GridOS/pkgs/container/gridos)
+[![CI](https://github.com/iceccarelli/GridOS/actions/workflows/ci.yml/badge.svg)](https://github.com/iceccarelli/GridOS/actions/workflows/ci.yml)
+[![FastAPI](https://img.shields.io/badge/FastAPI-0.110+-teal.svg)](https://fastapi.tiangolo.com/)
+[![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)
+
+**GridOS** is a vendor-neutral, open-source middleware platform that unifies **Distributed Energy Resources (DERs)** — solar inverters, batteries, EV chargers, smart loads — behind a single, standards-based API. It provides real-time telemetry ingestion, digital-twin simulation, ML-driven forecasting, and optimal energy dispatch, enabling utilities, aggregators, and microgrid operators to accelerate the energy transition.
+
+---
+
+## Key Features
+
+| Capability | Description |
+|---|---|
+| **Multi-Protocol Adapters** | Modbus TCP/RTU, MQTT, DNP3, IEC 61850, OPC-UA — connect any DER out of the box. |
+| **Common Information Model** | Pydantic models aligned with IEC 61968/61850 for interoperable data exchange. |
+| **Time-Series Storage** | Pluggable backends for InfluxDB 2.x and TimescaleDB with async I/O. |
+| **Digital Twin Engine** | Physics-based component models (bus, line, transformer, PV, battery, EV charger) with simplified power-flow simulation. |
+| **ML Forecasting** | LSTM-based load and solar forecasting plus Isolation Forest anomaly detection. |
+| **MILP Optimization** | Mixed-Integer Linear Programming scheduler for optimal battery dispatch and demand response. |
+| **REST + WebSocket API** | FastAPI-powered endpoints with live telemetry streaming via WebSockets. |
+| **Edge Support** | SQLite-based store-and-forward cache for intermittent connectivity. |
+| **Cloud-Native Deployment** | Docker Compose, Kubernetes manifests, and GitHub Actions CI/CD included. |
+
+---
+
+## Architecture Overview
+
+```
+┌──────────────────────────────────────────────────────────┐
+│                      GridOS Platform                     │
+│                                                          │
+│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌─────────┐ │
+│  │ Modbus   │  │  MQTT    │  │  DNP3    │  │ IEC61850│ │
+│  │ Adapter  │  │ Adapter  │  │ Adapter  │  │ Adapter │ │
+│  └────┬─────┘  └────┬─────┘  └────┬─────┘  └────┬────┘ │
+│       │              │              │              │      │
+│       └──────────────┼──────────────┼──────────────┘      │
+│                      ▼                                    │
+│              ┌───────────────┐                            │
+│              │  CIM Models   │                            │
+│              │  (Pydantic)   │                            │
+│              └───────┬───────┘                            │
+│                      │                                    │
+│         ┌────────────┼────────────┐                       │
+│         ▼            ▼            ▼                       │
+│  ┌────────────┐ ┌──────────┐ ┌──────────────┐            │
+│  │ Time-Series│ │ Digital  │ │ Optimization │            │
+│  │  Storage   │ │  Twin    │ │  (MILP)      │            │
+│  └────────────┘ │  Engine  │ └──────────────┘            │
+│                 └──────────┘                              │
+│                      │                                    │
+│              ┌───────┴───────┐                            │
+│              │  FastAPI +    │                            │
+│              │  WebSocket    │                            │
+│              └───────────────┘                            │
+└──────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Installation
+
+### Option 1: Install from PyPI (Recommended)
+
+```bash
+pip install gridos
+```
+
+With optional dependencies:
+
+```bash
+# Machine learning (LSTM forecasting, anomaly detection)
+pip install gridos[ml]
+
+# Protocol adapters (Modbus, MQTT, OPC-UA)
+pip install gridos[adapters]
+
+# Storage backends (InfluxDB, TimescaleDB)
+pip install gridos[storage]
+
+# Everything
+pip install gridos[ml,adapters,storage]
+```
+
+### Option 2: Run with Docker
+
+```bash
+docker pull ghcr.io/iceccarelli/gridos:latest
+docker run -p 8000:8000 ghcr.io/iceccarelli/gridos:latest
+```
+
+The API is now available at `http://localhost:8000/docs`.
+
+### Option 3: Run with Docker Compose (Full Stack)
+
+```bash
+git clone https://github.com/iceccarelli/GridOS.git
+cd GridOS
+docker-compose up -d
+```
+
+This starts GridOS alongside InfluxDB, TimescaleDB, and Grafana.
+
+### Option 4: Install from Source
+
+```bash
+git clone https://github.com/iceccarelli/GridOS.git
+cd GridOS
+
+python -m venv .venv
+source .venv/bin/activate
+
+# Install with dev dependencies
+pip install -e ".[dev]"
+```
+
+---
+
+## Quick Start
+
+### Configuration
+
+```bash
+# Copy the example environment file
+cp .env.example .env
+
+# Edit .env with your settings (storage URLs, broker addresses, etc.)
+```
+
+### Run the API Server
+
+```bash
+uvicorn gridos.main:app --host 0.0.0.0 --port 8000 --reload
+```
+
+The interactive API documentation is available at `http://localhost:8000/docs`.
+
+---
+
+## Project Structure
+
+```
+GridOS/
+├── src/gridos/           # Core Python package
+│   ├── models/           # Pydantic CIM models
+│   ├── adapters/         # Protocol adapters (Modbus, MQTT, DNP3, …)
+│   ├── storage/          # Time-series backends (InfluxDB, TimescaleDB)
+│   ├── digital_twin/     # Simulation engine + ML modules
+│   ├── optimization/     # MILP scheduler and dispatch
+│   ├── api/              # FastAPI routes and WebSocket manager
+│   ├── edge/             # Edge caching (SQLite store-and-forward)
+│   ├── security/         # API key + JWT authentication
+│   └── utils/            # Logging, metrics, and shared utilities
+├── tests/                # Pytest test suite (70 tests)
+├── notebooks/            # Jupyter demo notebooks
+├── data/                 # Sample datasets
+├── docs/                 # Architecture, API reference, developer guide
+├── k8s/                  # Kubernetes manifests
+├── scripts/              # Utility and demo scripts
+└── requirements/         # Dependency files (base, ml, dev, prod)
+```
+
+---
+
+## Running Tests
+
+```bash
+pytest tests/ -v --cov=gridos --cov-report=term-missing
+```
+
+---
+
+## Notebooks
+
+Explore the interactive Jupyter notebooks in `notebooks/`:
+
+1. **Data Ingestion Demo** — Connect adapters and ingest telemetry.
+2. **Digital Twin Simulation** — Build a grid model and run power-flow.
+3. **Forecasting with ML** — Train an LSTM on solar generation data.
+4. **Optimization Scheduler** — Solve optimal battery dispatch with MILP.
+5. **API Client** — Interact with the REST API programmatically.
+
+---
+
+## Contributing
+
+We welcome contributions from the community. Please read [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on how to get started.
+
+---
+
+## Security
+
+If you discover a security vulnerability, please follow the responsible disclosure process described in [SECURITY.md](SECURITY.md).
+
+---
+
+## License
+
+GridOS is released under the [MIT License](LICENSE).
+
+---
+
+## Acknowledgements
+
+GridOS builds on the shoulders of outstanding open-source projects including FastAPI, Pydantic, PuLP, scikit-learn, InfluxDB, TimescaleDB, and many others. We are grateful to the energy systems research community for the standards and models that inform this work.

gridos-0.1.0/README.md

@@ -0,0 +1,211 @@
+# GridOS — Open Energy Operating System
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
+[![PyPI version](https://img.shields.io/pypi/v/gridos.svg)](https://pypi.org/project/gridos/)
+[![PyPI downloads](https://img.shields.io/pypi/dm/gridos.svg)](https://pypi.org/project/gridos/)
+[![Docker Image](https://img.shields.io/badge/docker-ghcr.io%2Ficeccarelli%2Fgridos-blue?logo=docker)](https://github.com/iceccarelli/GridOS/pkgs/container/gridos)
+[![CI](https://github.com/iceccarelli/GridOS/actions/workflows/ci.yml/badge.svg)](https://github.com/iceccarelli/GridOS/actions/workflows/ci.yml)
+[![FastAPI](https://img.shields.io/badge/FastAPI-0.110+-teal.svg)](https://fastapi.tiangolo.com/)
+[![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)
+
+**GridOS** is a vendor-neutral, open-source middleware platform that unifies **Distributed Energy Resources (DERs)** — solar inverters, batteries, EV chargers, smart loads — behind a single, standards-based API. It provides real-time telemetry ingestion, digital-twin simulation, ML-driven forecasting, and optimal energy dispatch, enabling utilities, aggregators, and microgrid operators to accelerate the energy transition.
+
+---
+
+## Key Features
+
+| Capability | Description |
+|---|---|
+| **Multi-Protocol Adapters** | Modbus TCP/RTU, MQTT, DNP3, IEC 61850, OPC-UA — connect any DER out of the box. |
+| **Common Information Model** | Pydantic models aligned with IEC 61968/61850 for interoperable data exchange. |
+| **Time-Series Storage** | Pluggable backends for InfluxDB 2.x and TimescaleDB with async I/O. |
+| **Digital Twin Engine** | Physics-based component models (bus, line, transformer, PV, battery, EV charger) with simplified power-flow simulation. |
+| **ML Forecasting** | LSTM-based load and solar forecasting plus Isolation Forest anomaly detection. |
+| **MILP Optimization** | Mixed-Integer Linear Programming scheduler for optimal battery dispatch and demand response. |
+| **REST + WebSocket API** | FastAPI-powered endpoints with live telemetry streaming via WebSockets. |
+| **Edge Support** | SQLite-based store-and-forward cache for intermittent connectivity. |
+| **Cloud-Native Deployment** | Docker Compose, Kubernetes manifests, and GitHub Actions CI/CD included. |
+
+---
+
+## Architecture Overview
+
+```
+┌──────────────────────────────────────────────────────────┐
+│                      GridOS Platform                     │
+│                                                          │
+│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌─────────┐ │
+│  │ Modbus   │  │  MQTT    │  │  DNP3    │  │ IEC61850│ │
+│  │ Adapter  │  │ Adapter  │  │ Adapter  │  │ Adapter │ │
+│  └────┬─────┘  └────┬─────┘  └────┬─────┘  └────┬────┘ │
+│       │              │              │              │      │
+│       └──────────────┼──────────────┼──────────────┘      │
+│                      ▼                                    │
+│              ┌───────────────┐                            │
+│              │  CIM Models   │                            │
+│              │  (Pydantic)   │                            │
+│              └───────┬───────┘                            │
+│                      │                                    │
+│         ┌────────────┼────────────┐                       │
+│         ▼            ▼            ▼                       │
+│  ┌────────────┐ ┌──────────┐ ┌──────────────┐            │
+│  │ Time-Series│ │ Digital  │ │ Optimization │            │
+│  │  Storage   │ │  Twin    │ │  (MILP)      │            │
+│  └────────────┘ │  Engine  │ └──────────────┘            │
+│                 └──────────┘                              │
+│                      │                                    │
+│              ┌───────┴───────┐                            │
+│              │  FastAPI +    │                            │
+│              │  WebSocket    │                            │
+│              └───────────────┘                            │
+└──────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Installation
+
+### Option 1: Install from PyPI (Recommended)
+
+```bash
+pip install gridos
+```
+
+With optional dependencies:
+
+```bash
+# Machine learning (LSTM forecasting, anomaly detection)
+pip install gridos[ml]
+
+# Protocol adapters (Modbus, MQTT, OPC-UA)
+pip install gridos[adapters]
+
+# Storage backends (InfluxDB, TimescaleDB)
+pip install gridos[storage]
+
+# Everything
+pip install gridos[ml,adapters,storage]
+```
+
+### Option 2: Run with Docker
+
+```bash
+docker pull ghcr.io/iceccarelli/gridos:latest
+docker run -p 8000:8000 ghcr.io/iceccarelli/gridos:latest
+```
+
+The API is now available at `http://localhost:8000/docs`.
+
+### Option 3: Run with Docker Compose (Full Stack)
+
+```bash
+git clone https://github.com/iceccarelli/GridOS.git
+cd GridOS
+docker-compose up -d
+```
+
+This starts GridOS alongside InfluxDB, TimescaleDB, and Grafana.
+
+### Option 4: Install from Source
+
+```bash
+git clone https://github.com/iceccarelli/GridOS.git
+cd GridOS
+
+python -m venv .venv
+source .venv/bin/activate
+
+# Install with dev dependencies
+pip install -e ".[dev]"
+```
+
+---
+
+## Quick Start
+
+### Configuration
+
+```bash
+# Copy the example environment file
+cp .env.example .env
+
+# Edit .env with your settings (storage URLs, broker addresses, etc.)
+```
+
+### Run the API Server
+
+```bash
+uvicorn gridos.main:app --host 0.0.0.0 --port 8000 --reload
+```
+
+The interactive API documentation is available at `http://localhost:8000/docs`.
+
+---
+
+## Project Structure
+
+```
+GridOS/
+├── src/gridos/           # Core Python package
+│   ├── models/           # Pydantic CIM models
+│   ├── adapters/         # Protocol adapters (Modbus, MQTT, DNP3, …)
+│   ├── storage/          # Time-series backends (InfluxDB, TimescaleDB)
+│   ├── digital_twin/     # Simulation engine + ML modules
+│   ├── optimization/     # MILP scheduler and dispatch
+│   ├── api/              # FastAPI routes and WebSocket manager
+│   ├── edge/             # Edge caching (SQLite store-and-forward)
+│   ├── security/         # API key + JWT authentication
+│   └── utils/            # Logging, metrics, and shared utilities
+├── tests/                # Pytest test suite (70 tests)
+├── notebooks/            # Jupyter demo notebooks
+├── data/                 # Sample datasets
+├── docs/                 # Architecture, API reference, developer guide
+├── k8s/                  # Kubernetes manifests
+├── scripts/              # Utility and demo scripts
+└── requirements/         # Dependency files (base, ml, dev, prod)
+```
+
+---
+
+## Running Tests
+
+```bash
+pytest tests/ -v --cov=gridos --cov-report=term-missing
+```
+
+---
+
+## Notebooks
+
+Explore the interactive Jupyter notebooks in `notebooks/`:
+
+1. **Data Ingestion Demo** — Connect adapters and ingest telemetry.
+2. **Digital Twin Simulation** — Build a grid model and run power-flow.
+3. **Forecasting with ML** — Train an LSTM on solar generation data.
+4. **Optimization Scheduler** — Solve optimal battery dispatch with MILP.
+5. **API Client** — Interact with the REST API programmatically.
+
+---
+
+## Contributing
+
+We welcome contributions from the community. Please read [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on how to get started.
+
+---
+
+## Security
+
+If you discover a security vulnerability, please follow the responsible disclosure process described in [SECURITY.md](SECURITY.md).
+
+---
+
+## License
+
+GridOS is released under the [MIT License](LICENSE).
+
+---
+
+## Acknowledgements
+
+GridOS builds on the shoulders of outstanding open-source projects including FastAPI, Pydantic, PuLP, scikit-learn, InfluxDB, TimescaleDB, and many others. We are grateful to the energy systems research community for the standards and models that inform this work.