Metadata-Version: 2.4
Name: auraagent
Version: 0.2.0
Summary: Aura — Carbon tracking and AI bias analysis toolkit
Project-URL: Homepage, https://cevia.ai
Author-email: CEVIA <info@cevia.ai>
License: MIT License
        
        Copyright (c) 2025 CEVIA
        
        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.
License-File: LICENSE
Keywords: ai,bias,carbon,emissions,fairness,sustainability,tracking
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.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.9
Requires-Dist: click>=8.1.0
Requires-Dist: codecarbon>=2.4.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: requests>=2.31.0
Requires-Dist: rich>=13.0.0
Provides-Extra: dev
Requires-Dist: mypy>=1.9.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.3.0; extra == 'dev'
Description-Content-Type: text/markdown

# 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

```bash
# 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

```bash
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 :**
```python
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 :**
```python
from aura.carbon import track_emissions

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

train_model()
```

**Gestion manuelle :**
```python
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

```bash
# 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 :

```ini
[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` :

```bash
# 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` :
```bash
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](https://cevia.ai)
