auraagent 0.1.1

Aura — Carbon tracking and monitoring toolkit

auraagent

Carbon tracking and monitoring toolkit for AI engineers.

Track CO2 emissions from your Python scripts and AI training jobs, and visualize them on your AURA dashboard — with a single line of code.

---

Installation

# Package de base (tracking uniquement)
pip install auraagent

# Avec l'interface web locale
pip install "auraagent[web]"

Requires Python 3.9+

---

Premiers pas

1. Lancer l'interface de configuration

aura-web

Ouvre automatiquement http://localhost:8765 dans votre navigateur.

Connectez-vous avec votre email et votre clé API générée depuis votre dashboard AURA → Profil → Clés API.

2. Tracker des émissions dans votre code

Context manager :

from aura.carbon import AuraCarbon
import time

with AuraCarbon(project_name="mon-projet") as tracker:
    # Votre code ici
    time.sleep(5)

# Les émissions sont automatiquement envoyées au dashboard

Décorateur :

from aura.carbon import track_emissions

@track_emissions(project_name="fine-tuning-bert")
def train_model():
    # Votre entraînement
    pass

train_model()

Gestion manuelle :

from aura.carbon import AuraCarbon

tracker = AuraCarbon(project_name="inference")
tracker.start()

# ... votre code ...

emissions = tracker.stop()
print(f"Émissions : {emissions:.6f} kg CO₂")

---

CLI

# Lancer l'interface web
aura-web

# Voir le statut de la configuration locale
aura status

# Se déconnecter (supprime ~/.aura.config)
aura logout

---

Configuration avancée

La configuration est stockée dans ~/.aura.config après la première connexion :

[aura]
api_endpoint    = https://cevia.ai/api
api_key         = votre_cle_api
user_id         = 42
machine_id      = uuid-de-votre-machine
organization    = CEVIA
default_project = mon-projet

Tester en local / réseau privé

Pour pointer vers un serveur Django local au lieu de cevia.ai :

# Serveur local
export AURA_SERVER_URL=http://127.0.0.1:8000
aura-web

# Réseau local (autre machine)
export AURA_SERVER_URL=http://192.168.1.42:8000
aura-web

Ou de façon permanente dans votre ~/.zshrc / ~/.bashrc :

export AURA_SERVER_URL=http://127.0.0.1:8000

---

Architecture

auraagent/
├── aura/
│   ├── carbon/
│   │   ├── tracker.py      # AuraCarbon — wrapper CodeCarbon
│   │   ├── output.py       # AuraOutput — envoi HTTP vers le serveur
│   │   └── decorators.py   # @track_emissions
│   ├── web/
│   │   ├── main.py         # Lance FastAPI + ouvre le navigateur
│   │   ├── app.py          # Application FastAPI
│   │   ├── routers/        # auth, tracker, config
│   │   ├── services/       # Logique métier (singleton tracker)
│   │   └── templates/      # Pages HTML (login, dashboard, settings)
│   └── core/
│       ├── constants.py    # AURA_SERVER_URL (surchargeable via env)
│       ├── config.py       # Lecture/écriture ~/.aura.config
│       ├── auth.py         # Vérification email + clé API
│       ├── models.py       # Modèles Pydantic
│       └── exceptions.py   # AuraError, AuraAuthError, etc.
├── installer/
│   ├── install.py          # Script d'installation (crée icône bureau)
│   └── build.py            # Compilation PyInstaller
└── tests/

Flux de données

Votre code Python
      │
      ▼
AuraCarbon (wrapper CodeCarbon)
      │  mesure CPU/GPU/RAM
      ▼
AuraOutput (BaseOutput)
      │  POST /api/emissions/
      │  Authorization: Token <api_key>
      ▼
Serveur Django AURA
      │
      ▼
Dashboard cevia.ai

Flux d'authentification (première connexion)

aura-web (localhost:8765)
      │  email + api_key
      ▼
POST /api/auth/verify/       → retourne api_endpoint, user_id, organization
      │
      ▼
POST /api/machines/register/ → retourne machine_id
      │
      ▼
~/.aura.config               ← écrit la configuration locale

---

Dépendances

Dépendance	Rôle
codecarbon	Mesure de la consommation électrique
requests	Envoi HTTP des émissions
pydantic	Validation des modèles de données
click	Interface CLI
rich	Affichage terminal
fastapi (web)	Interface web locale
uvicorn (web)	Serveur ASGI
jinja2 (web)	Templates HTML

---

Licence

MIT — CEVIA