Website and auto pypi deployment

.github/workflows/docs.yml

@@ -0,0 +1,55 @@
+name: docs
+
+on:
+  push:
+    branches: [main, polish-ecal-package]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+          cache: pip
+
+      - name: Install package with docs extras
+        run: pip install -e ".[docs]"
+
+      - name: Build Sphinx docs
+        run: sphinx-build -b html -W --keep-going docs docs/_build/html
+
+      - name: Assemble combined site (website at /, docs at /docs/)
+        run: |
+          rm -rf site
+          mkdir -p site
+          cp -r website/. site/
+          mkdir -p site/docs
+          cp -r docs/_build/html/. site/docs/
+
+      - name: Upload site artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  deploy:
+    if: github.event_name == 'workflow_dispatch' || (github.event_name == 'push' && (github.ref == 'refs/heads/main' || github.ref == 'refs/heads/polish-ecal-package'))
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/publish.yml

@@ -0,0 +1,57 @@
+name: publish
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Check release tag matches pyproject.toml version
+        run: |
+          TAG="${GITHUB_REF_NAME#v}"
+          PKG_VERSION=$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          if [ "$TAG" != "$PKG_VERSION" ]; then
+            echo "Release tag '$GITHUB_REF_NAME' (version '$TAG') does not match pyproject.toml version '$PKG_VERSION'"
+            exit 1
+          fi
+
+      - name: Install build
+        run: pip install build
+
+      - name: Build sdist and wheel
+        run: python -m build
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/ecal-energy/
+    permissions:
+      id-token: write
+    steps:
+      - name: Download build artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

.gitignore

@@ -1,3 +1,9 @@
+# macOS
+.DS_Store
+
+# Paper PDF (large binary)
+paper.pdf
+
 # Byte-compiled / optimized / DLL files
 __pycache__/
 *.py[cod]
@@ -70,6 +76,10 @@ instance/
 
 # Sphinx documentation
 docs/_build/
+docs/api/generated/
+
+# Combined GitHub Pages assembly (website + docs)
+/site/
 
 # PyBuilder
 .pybuilder/

.readthedocs.yaml

@@ -0,0 +1,17 @@
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+
+sphinx:
+  configuration: docs/conf.py
+  fail_on_warning: true
+
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs

MANIFEST.in

@@ -0,0 +1,2 @@
+recursive-include tests *.py
+recursive-include src/ecal/hardware/data *.yaml

README.md

@@ -1,33 +1,141 @@
 # eCAL
-Simulator for the eCAL metric
 
+Analytical estimation of the energy cost of the AI lifecycle (J/bit).
+
+eCAL computes the total energy consumed across the full AI model lifecycle — data transmission, preprocessing, training, evaluation, and inference — using closed-form FLOP formulas and hardware power profiles.
+
+Published in **IEEE Journal on Selected Areas in Communications (JSAC), 2026**.
+
+[Documentation](https://sensorlab.github.io/eCAL/docs/)
 
 ## Installation
-To install the required dependencies, run the following command:
+
+### From source (recommended for development)
+
+```bash
+git clone https://github.com/sensorlab/eCAL.git
+cd eCAL
+pip install -e ".[dev]"
+```
+
+### From PyPI
+
+```bash
+pip install ecal-energy
+```
+
+### Dependencies only (legacy)
+
 ```bash
 pip install -r requirements.txt
 ```
 
-in case if you want to run LLMs you might need additional dependencies, you can install them by running the following command:
+## Quickstart
+
+### Python API
+
+```python
+import ecal
+
+result = ecal.estimate(
+    model_type="MLP",
+    model_params={"num_layers": 3, "din": 10, "dout": 2},
+    num_samples=1000,
+    num_epochs=50,
+    hardware="apple_m2",
+)
+
+print(f"Total energy: {result['total']:.4f} J")
+print(f"eCAL: {result['ecal_j_per_bit']:.2e} J/bit")
+```
+
+### CLI
+
 ```bash
-pip install transformers sentencepiece tiktoken
+# Estimate energy for an MLP
+ecal estimate --model MLP --layers 3 --epochs 50 --hardware apple_m2
+
+# JSON output
+ecal estimate --model Transformer --layers 6 --hardware nvidia_h100_sxm --json
+
+# List available hardware profiles
+ecal profiles
+
+# Version
+ecal --version
 ```
-## Usage
-To run the calculator, use the following command:
+
+### Legacy (RunCalculator.py)
+
 ```bash
+# Edit configs/CalculatorConfig.py, then:
 python RunCalculator.py
 ```
+
+## Supported Models
+
+| Model       | FLOP Calculator        | Key Parameters                                      |
+|-------------|------------------------|-----------------------------------------------------|
+| MLP         | `MLPCalculator`        | `num_layers`, `din`, `dout`                         |
+| CNN         | `CNNCalculator`        | `num_cnv_layers`, `num_pool_layers`, `i_r`, `k_r`   |
+| KAN         | `KANCalculator`        | `num_layers`, `grid_size`, `din`, `dout`            |
+| Transformer | `TransformerCalculator`| `context_length`, `embedding_size`, `num_heads`, `num_decoder_blocks` |
+
+## Hardware Profiles
+
+| Profile            | FP32 FLOPS   | TDP (W) | Device |
+|--------------------|-------------|---------|--------|
+| `apple_m2`         | 3.6 TFLOPS  | 22      | mps    |
+| `nvidia_a100_80gb` | 19.5 TFLOPS | 400     | cuda   |
+| `nvidia_h100_sxm`  | 67 TFLOPS   | 700     | cuda   |
+| `generic_cpu`      | 1 TFLOPS    | 100     | cpu    |
+| `generic_edge`     | 0.01 TFLOPS | 15      | cpu    |
+
+## Architecture
+
+```
+                    ecal.estimate()
+                         |
+        +--------+-------+-------+--------+
+        |        |       |       |        |
+  Transmission  Preproc  Training  Eval  Inference
+        |        |       |       |        |
+        v        v       v       v        v
+   Protocol   FLOP    FLOP     FLOP    FLOP
+   Configs   Calcs   Calcs    Calcs   Calcs
+                     (per model type)
+                         |
+                    Hardware Profile
+                   (FLOPS, power, TDP)
+                         |
+                   Energy = time * power
+                         |
+                  eCAL = total_E / total_bits
+```
+
 ## Configuration
-The configuration is done in the `CalculatorConfig.py` file. What specific configuration options are available can be found in the file itself.
-To change the Control and Data plane overheads of the transmission layer or implement new protocols you can change the values  in the `configs/ProtocolConfigs.py` file.
+
+Protocol configs are in `configs/ProtocolConfigs.py` — supports 7 OSI layers with multiple protocol options (HTTP, TCP, IPv4, WiFi, Bluetooth, etc.).
+
+Calculator parameters are in `configs/CalculatorConfig.py` for the legacy `RunCalculator.py` interface.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest                    # run tests
+ruff check src/ tests/    # lint
+mypy src/ecal/            # type check
+```
 
 ## Citation
-If you use this tool please cite our [paper](https://ieeexplore.ieee.org/abstract/document/11298182): 
+
+If you use this tool please cite our [paper](https://ieeexplore.ieee.org/abstract/document/11298182):
 ```
 @ARTICLE{11298182,
   author={Chou, Shih-Kai and Hribar, Jernej and Hanžel, Vid and Mohorčič, Mihael and Fortuna, Carolina},
-  journal={IEEE Journal on Selected Areas in Communications}, 
-  title={The Energy Cost of Artificial Intelligence Lifecycle in Communication Networks}, 
+  journal={IEEE Journal on Selected Areas in Communications},
+  title={The Energy Cost of Artificial Intelligence Lifecycle in Communication Networks},
   year={2026},
   volume={44},
   number={},
@@ -40,8 +148,8 @@ Other related work:
 ```
 @INPROCEEDINGS{11349371,
   author={Chou, Shih-Kai and Hribar, Jernej and Bertalanič, Blaž and Mohorčič, Mihael and Lagkas, Thomas and Sarigiannidis, Panagiotis and Fortuna, Carolina},
-  booktitle={2025 IEEE Conference on Network Function Virtualization and Software-Defined Networking (NFV-SDN)}, 
-  title={Energy Cost of the AI/ML Workflow in O-RAN}, 
+  booktitle={2025 IEEE Conference on Network Function Virtualization and Software-Defined Networking (NFV-SDN)},
+  title={Energy Cost of the AI/ML Workflow in O-RAN},
   year={2025},
   volume={},
   number={},
@@ -53,12 +161,16 @@ Other related work:
 ```
 @INPROCEEDINGS{10849732,
   author={Chou, Shih-Kai and Hribar, Jernej and Mohorčič, Mihael and Fortuna, Carolina},
-  booktitle={2024 IEEE Conference on Standards for Communications and Networking (CSCN)}, 
-  title={Towards the Standardization of Energy Efficiency Metrics of the AI Lifecycle in 6G and Beyond}, 
+  booktitle={2024 IEEE Conference on Standards for Communications and Networking (CSCN)},
+  title={Towards the Standardization of Energy Efficiency Metrics of the AI Lifecycle in 6G and Beyond},
   year={2024},
   volume={},
   number={},
   pages={187-190},
   keywords={Measurement;6G mobile communication;Energy consumption;Costs;Energy measurement;Energy efficiency;Computational efficiency;Quality of experience;Artificial intelligence;Standards;6G;AI-native network;energy efficiency},
   doi={10.1109/CSCN63874.2024.10849732}}
 ```
+
+## License
+
+BSD 3-Clause License. See [LICENSE](LICENSE).