Adds the simulations

Author: ribalba

.github/workflows/tests.yml

@@ -0,0 +1,29 @@
+name: Tests
+
+on:
+  push:
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -r requirements.txt -r requirements-dev.txt
+      - name: Run tests
+        run: pytest
+      - name: Lint code
+        run: pylint --recursive=y elephant/

README.md

@@ -4,6 +4,8 @@
 
 Its main purpose is the integration into the Green Metrics Tool (GMT) to provide dynamic carbon intensity values.
 
+![Elephant UI](Screenshot.png)
+
 ## Installation
 
 ```bash
@@ -25,11 +27,13 @@ Before running Elephant, you need to configure your data providers:
 ```bash
 # Copy the example configuration
 cp config.example.yml config.yml
-
-# Edit config.yml and add your API tokens
-# For ElectricityMaps: Replace "your-electricitymaps-api-token-here" with your actual token
 ```
 
+Edit config.yml and add your API tokens
+
+For ElectricityMaps: Replace "your-electricitymaps-api-token-here" with your actual token. You don't need to modify anything to start collection. We use free endpoints per default.
+
+
 ## Running
 
 You should just be able to do
@@ -49,7 +53,7 @@ You should be able to
 
 ```
 pip install -r requirements-dev.txt
-pylint elephant/**.py
+pylint pylint --recursive=y elephant/
 pytest tests
 ```
 
@@ -66,3 +70,50 @@ python3 -m elephant.database
 python3 -m elephant.cron
 python3 -m elephant --host 0.0.0.0 --port 8000
 ```
+
+## API
+
+Once Elephant is running (for example with `docker compose up --build`), the generated docs are available at:
+
+- Swagger UI: `http://localhost:8000/docs`
+- ReDoc: `http://localhost:8000/redoc`
+
+### Core endpoints
+
+- `GET /carbon-intensity/current` — Latest carbon intensities for a region. Query params: `region` (ISO 3166-1 alpha-2), optional `update` (force refresh) and `simulation_id` (serve simulated data).
+- `GET /carbon-intensity/current/primary` — Latest carbon intensity from the configured primary provider for `region`; also accepts `update` and `simulation_id`.
+- `GET /carbon-intensity/history` — Historical values between `startTime` and `endTime` (ISO 8601) for `region`.
+- `GET /regions` — List of regions with stored data.
+- `GET /health` — Service health, providers, DB record count, and regions.
+
+### Simulation endpoints
+
+Elephant includes a lightweight simulator so you can drive client integrations or demos without live provider data.
+
+- `POST /simulation` with a JSON body `{"carbon_values": [120, [140, 2], [100, null]]}` registers a run and returns a `simulation_id`. Each entry is either a float or a `[value, calls]` pair; `calls` is how often that value is returned before automatically advancing (use `null` to disable auto-advance).
+- `GET /simulation/get_carbon?simulation_id=...` returns the current simulated carbon intensity and will auto-advance when call thresholds are met.
+- `POST /simulation/next?simulation_id=...` forces the next value.
+- `GET /simulation/stats?simulation_id=...` shows the current index and call history for debugging.
+
+You can plug a simulation into the core responses by passing `simulation_id`:
+
+```bash
+curl "http://localhost:8000/carbon-intensity/current?region=DE&simulation_id=<simulation_id>"
+curl "http://localhost:8000/carbon-intensity/current/primary?region=DE&simulation_id=<simulation_id>"
+```
+
+### Electricity Maps compatible endpoints
+
+For Electricity Maps compatible payloads, use the v3 endpoints:
+
+```bash
+curl "http://localhost:8000/v3/carbon-intensity/current?zone=DE"
+curl "http://localhost:8000/v3/carbon-intensity/history?zone=DE"
+```
+
+They mirror the Electricity Maps API schema. To serve simulated data to an Electricity Maps client, send the simulation id as `auth-token`:
+
+```bash
+curl -H "auth-token: <simulation_id>" "http://localhost:8000/v3/carbon-intensity/current?zone=DE"
+curl -H "auth-token: <simulation_id>" "http://localhost:8000/v3/carbon-intensity/history?zone=DE"
+```

Screenshot.png

@@ -8,26 +8,24 @@ database:
 # Provider configuration
 providers:
   electricitymaps:
-    enabled: false
     api_token: "YOUR TOKEN HERE"
-  energycharts:
-    enabled: true
-  bundesnetzagentur:
-    enabled: true
 
 # Cron job for fetching data
 cron:
   interval_seconds: 300  # Default: 5 minutes
   sources:
     - region: "DE"
       provider: "bundesnetzagentur"
-    - region: "DE"
-      provider: "electricitymaps"
-      primary: true
+      primary: true # If you have multiple sources for the same region, one should be marked as primary so the api knows which to return by default
     - region: "DE"
       provider: "energycharts"
-    - region: "FR"
-      provider: "electricitymaps"
+    # - region: "DE"
+    #   provider: "bundesnetzagentur_all"
+    # - region: "DE"
+    #   provider: "electricitymaps"
+    #   primary: true
+    # - region: "FR"
+    #   provider: "electricitymaps"
 
 # Logging
 logging: