aluminatiai 0.2.0__tar.gz

aluminatiai-0.2.0/GETTING_STARTED.md

@@ -0,0 +1,284 @@
+# Getting Started with GPU Energy Agent
+
+## Prerequisites
+
+1. **NVIDIA GPU** with driver 450.80.02 or newer
+2. **Python 3.8+**
+3. **Linux OS** (Ubuntu, CentOS, etc.)
+
+## Quick Start
+
+### 1. Install Dependencies
+
+```bash
+cd agent
+pip install -r requirements.txt
+```
+
+Expected output:
+```
+Successfully installed nvidia-ml-py3-7.352.0 psutil-5.9.6 rich-13.7.0 ...
+```
+
+### 2. Test GPU Detection
+
+Run a quick test to verify the collector can access your GPUs:
+
+```bash
+python collector.py
+```
+
+Expected output:
+```
+Testing GPU Collector...
+Found 4 GPUs:
+  GPU 0: NVIDIA A100-SXM4-40GB (GPU-abc123...)
+  GPU 1: NVIDIA A100-SXM4-40GB (GPU-def456...)
+  ...
+
+Collecting 3 samples (2s intervals)...
+  GPU 0: 287.4W, 98% util, 76°C, 1437.0J
+  ...
+
+✅ Collector test passed!
+```
+
+### 3. Run the Agent
+
+Start monitoring all GPUs:
+
+```bash
+python main.py
+```
+
+You should see real-time metrics updating every 5 seconds:
+
+```
+GPU Energy Agent v0.1.0
+📊 Monitoring 4 GPUs
+⏱️  Sampling interval: 5.0s
+
+┏━━━━━┳━━━━━━━━┳━━━━━━┳━━━━━━┳━━━━━━━━━┳━━━━━━━━━━┓
+┃ GPU ┃  Power ┃ Util ┃ Temp ┃ Energy Δ┃ Total kWh┃
+┡━━━━━╇━━━━━━━━╇━━━━━━╇━━━━━━╇━━━━━━━━━╇━━━━━━━━━━┩
+│ GPU 0│ 287.4W │  98% │  76°C│   1437J │  0.0012  │
+│ GPU 1│ 289.1W │  97% │  77°C│   1446J │  0.0012  │
+...
+```
+
+Press `Ctrl+C` to stop.
+
+### 4. Export to CSV
+
+Run for 5 minutes and save metrics to CSV:
+
+```bash
+python main.py --duration 300 --output data/test_run.csv
+```
+
+This creates `data/test_run.csv` with timestamped metrics for analysis.
+
+### 5. Run Tests
+
+#### Test 1: Unit Tests
+
+```bash
+python tests/test_collector.py
+```
+
+Expected: All tests pass ✅
+
+#### Test 2: Overhead Benchmark
+
+Measure agent CPU/memory impact:
+
+```bash
+python tests/benchmark_overhead.py
+```
+
+Expected results:
+- CPU overhead: <0.1%
+- Memory overhead: <50 MB
+- Collection latency: <1ms per GPU
+
+#### Test 3: Energy Validation
+
+Validate energy calculations:
+
+```bash
+python tests/validate_energy.py --duration 60
+```
+
+Expected: Energy error <5% ✅
+
+## Common Issues
+
+### Issue: "No NVIDIA GPUs found"
+
+**Cause**: NVIDIA driver not installed or not working
+
+**Fix**:
+```bash
+# Check driver
+nvidia-smi
+
+# If not working, install driver:
+# Ubuntu:
+sudo apt install nvidia-driver-535
+
+# Then reboot
+sudo reboot
+```
+
+### Issue: "Failed to initialize NVML"
+
+**Cause**: Permission issue or driver mismatch
+
+**Fix**:
+```bash
+# Check driver version
+nvidia-smi
+
+# Ensure you're in the right groups
+groups
+
+# Add to video group if needed
+sudo usermod -a -G video $USER
+# Then log out and back in
+```
+
+### Issue: "Module 'pynvml' not found"
+
+**Cause**: Dependencies not installed
+
+**Fix**:
+```bash
+pip install -r requirements.txt
+```
+
+## Next Steps
+
+### Week 1-2: Current Focus
+
+- [x] Metrics collection working
+- [x] Energy calculations validated
+- [x] Overhead benchmarked
+- [ ] Run 24-hour stability test
+- [ ] Compare against external power meter
+
+### Week 3-4: Attribution
+
+- [ ] Add process tracking (PID → GPU mapping)
+- [ ] Parse command lines for model names
+- [ ] Implement job start/stop detection
+
+### Week 5-6: Backend Integration
+
+- [ ] Connect to FastAPI backend
+- [ ] Upload metrics to database
+- [ ] Real-time dashboard
+
+## Testing Checklist
+
+Use this checklist to verify your MVP agent:
+
+```
+□ GPU detection works (python collector.py)
+□ Agent runs without errors (python main.py)
+□ CPU overhead <0.1% (python tests/benchmark_overhead.py)
+□ Energy error <5% (python tests/validate_energy.py)
+□ CSV export works (python main.py --output data/test.csv)
+□ Can run for 1+ hours without crash
+□ Energy totals match expectations
+```
+
+## Getting Help
+
+If you encounter issues:
+
+1. Check `logs/` directory for error messages
+2. Run with verbose logging: `python main.py -v`
+3. Review [troubleshooting guide](README.md#troubleshooting)
+4. Open issue in main repository
+
+## Performance Tuning
+
+### Reduce Overhead
+
+If CPU usage is too high:
+
+```bash
+# Increase sampling interval
+python main.py --interval 10
+
+# Disable clock monitoring (edit collector.py):
+collector = GPUCollector(collect_clocks=False)
+```
+
+### Increase Accuracy
+
+For better energy accuracy:
+
+```bash
+# Use faster sampling (1s interval)
+python main.py --interval 1
+
+# Trade-off: Slightly higher overhead (~0.05% CPU)
+```
+
+## Example Workflows
+
+### Workflow 1: Validate Against Power Meter
+
+```bash
+# 1. Start a GPU workload (e.g., training)
+python your_training_script.py &
+
+# 2. Run agent for 10 minutes
+python main.py --duration 600 --output data/validation.csv
+
+# 3. Compare total kWh with power meter reading
+# Note: Meter shows whole system, agent shows GPU only
+```
+
+### Workflow 2: Daily Monitoring
+
+```bash
+# Run as background service
+nohup python main.py --output data/daily_$(date +%Y%m%d).csv > logs/agent.log 2>&1 &
+
+# Check status
+tail -f logs/agent.log
+
+# Stop
+pkill -f "python main.py"
+```
+
+### Workflow 3: Job Energy Profiling
+
+```bash
+# Start agent
+python main.py --output data/job_profile.csv &
+AGENT_PID=$!
+
+# Run your ML job
+python train_resnet.py
+
+# Stop agent
+kill $AGENT_PID
+
+# Analyze CSV to see energy consumption during job
+```
+
+## Success Criteria (Week 1-2)
+
+Your MVP agent is ready when:
+
+- ✅ Runs with <0.1% CPU overhead
+- ✅ Collects accurate power metrics (validated against NVML)
+- ✅ Energy calculations within 5% of theoretical
+- ✅ Can run continuously for 24+ hours
+- ✅ CSV export works correctly
+- ✅ All unit tests pass
+
+Once these are met, move to Week 3-4 (attribution)!

aluminatiai-0.2.0/PKG-INFO

@@ -0,0 +1,393 @@
+Metadata-Version: 2.4
+Name: aluminatiai
+Version: 0.2.0
+Summary: GPU energy monitoring agent — per-job cost attribution for AI teams
+License: MIT
+Project-URL: Homepage, https://aluminatiai.com
+Project-URL: Documentation, https://aluminatiai.com/docs/agent
+Project-URL: Repository, https://github.com/AgentMulder404/AluminatAI
+Project-URL: Bug Tracker, https://github.com/AgentMulder404/AluminatAI/issues
+Keywords: gpu,monitoring,energy,mlops,cost,nvidia
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: pynvml>=11.5.0
+Requires-Dist: requests>=2.28
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: rich>=13.0
+Provides-Extra: prometheus
+Requires-Dist: prometheus-client>=0.19; extra == "prometheus"
+
+# AluminatAI - GPU Energy Intelligence Platform
+
+**Know exactly what your GPUs cost. Every watt, every dollar, every job.**
+
+AluminatAI is an open-source GPU energy monitoring platform that gives AI teams real-time visibility into power consumption, energy costs, and utilization across their GPU fleet. A lightweight Python agent runs on your GPU machines and streams metrics to a cloud dashboard where you can track spending, compare jobs, and optimize workloads.
+
+**Live:** [https://www.aluminatiai.com/](https://aluminatiai-landing.vercel.app)
+
+---
+
+## How It Works
+
+```
+┌──────────────────┐     HTTPS/JSON      ┌──────────────────────────┐
+│   GPU Machine     │ ─────────────────► │   AluminatAI Platform     │
+│                    │   every 60s        │                            │
+│  ┌──────────────┐ │                     │  ┌──────────┐             │
+│  │  Python Agent │ │                     │  │ Next.js  │  Vercel     │
+│  │  (pynvml)    │ │                     │  │ API      │             │
+│  └──────────────┘ │                     │  └────┬─────┘             │
+│                    │                     │       │                    │
+│  NVIDIA A100/H100  │                     │  ┌────▼─────┐             │
+│  RTX 3090/4090     │                     │  │ Supabase │  PostgreSQL │
+│  Any NVIDIA GPU    │                     │  │ Database │  + RLS      │
+└──────────────────┘                     │  └────┬─────┘             │
+                                          │       │                    │
+                                          │  ┌────▼─────┐             │
+                                          │  │Dashboard │  React      │
+                                          │  │ UI       │  + Recharts │
+                                          │  └──────────┘             │
+                                          └──────────────────────────┘
+```
+
+## Features
+
+- **Real-Time GPU Monitoring** - Power draw, utilization, temperature, memory, and clock speeds sampled every 5 seconds
+- **Energy Cost Tracking** - Calculates energy consumption in kWh and converts to dollar costs at your electricity rate
+- **Job Attribution** - Track which training jobs consumed how much energy and what they cost
+- **Dashboard** - Three views: Today's Cost, Jobs Table, and Utilization vs Power chart
+- **Free Trial** - 30-day free trial with auto-generated API keys on signup
+- **Lightweight Agent** - <1% CPU, ~50MB RAM overhead on GPU machines
+- **Secure** - Row-Level Security, API key auth with `pgcrypto`, rate limiting, server-side validation
+- **Minimax Scheduler** - Bonus hackathon project: AI-powered job scheduling that balances speed vs. energy cost
+
+---
+
+## Project Structure
+
+```
+AluminatAI/
+├── aluminatai-landing/          # Next.js web platform (deployed to Vercel)
+│   ├── app/
+│   │   ├── api/
+│   │   │   ├── metrics/ingest/  # GPU metrics ingestion endpoint
+│   │   │   ├── dashboard/       # today-cost, jobs, utilization-chart
+│   │   │   ├── user/profile/    # User profile + API key rotation
+│   │   │   └── cron/            # Materialized view refresh
+│   │   ├── dashboard/           # Protected dashboard UI
+│   │   ├── login/               # Auth pages
+│   │   └── page.tsx             # Landing page
+│   ├── components/              # React components
+│   ├── lib/                     # Auth, rate limiting, Supabase clients
+│   └── database/migrations/     # SQL migrations (001-005)
+│
+├── agent/                       # Python GPU monitoring agent
+│   ├── main.py                  # Agent entry point
+│   ├── collector.py             # NVML-based GPU metrics collector
+│   ├── uploader.py              # API upload with retry + local backup
+│   ├── config.py                # Environment-based configuration
+│   ├── install.sh               # One-line install script
+│   └── tests/                   # Test suite + Colab notebook
+│
+├── minimax-scheduler/           # Hackathon: Minimax GPU job scheduler
+│   └── backend/                 # FastAPI + minimax algorithm
+│
+├── backend/                     # Legacy FastAPI backend (reference)
+├── frontend/                    # Legacy React frontend (reference)
+├── docker/                      # Docker configs for agent + backend
+├── docs/                        # Architecture docs, metrics schema
+└── assets/                      # Logo and diagrams
+```
+
+---
+
+## Quick Start
+
+### Prerequisites
+
+- Node.js 18+ and npm
+- Python 3.8+
+- A Supabase account ([supabase.com](https://supabase.com))
+- An NVIDIA GPU (for the agent) or Google Colab with GPU runtime
+
+### 1. Clone the Repository
+
+```bash
+git clone https://github.com/AgentMulder404/aluminatai-landing.git
+cd aluminatai-landing
+```
+
+### 2. Set Up the Database (Supabase)
+
+1. Create a new project at [supabase.com](https://supabase.com)
+2. Go to **SQL Editor** and run the migrations in order:
+
+```bash
+# Run these SQL files in the Supabase SQL Editor:
+database/migrations/002_gpu_monitoring_schema_postgres.sql
+database/migrations/003_fix_materialized_view.sql
+database/migrations/004_fix_trigger_permissions.sql
+database/migrations/005_secure_api_keys_and_constraints.sql
+```
+
+This creates:
+- `users` table with auto-generated API keys (using `pgcrypto`)
+- `gpu_metrics` time-series table with CHECK constraints
+- `gpu_jobs` table for job tracking
+- `gpu_metrics_hourly` materialized view for fast dashboard queries
+- Row-Level Security policies on all tables
+- Triggers for user profile auto-creation on signup
+
+### 3. Set Up the Web Platform
+
+```bash
+cd aluminatai-landing
+npm install
+```
+
+Create a `.env.local` file:
+
+```bash
+# Supabase (from your project settings > API)
+NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
+NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key
+SUPABASE_SERVICE_ROLE_KEY=your-service-role-key
+
+# Cron secret (generate with: openssl rand -base64 32)
+CRON_SECRET=your-cron-secret
+```
+
+Run the development server:
+
+```bash
+npm run dev
+```
+
+Visit `http://localhost:3000` - you should see the landing page.
+
+### 4. Create an Account
+
+1. Click **"Start Free Trial"** on the landing page
+2. Enter your name, email, and password
+3. You'll be redirected to the dashboard setup page
+4. Copy your API key (starts with `alum_`)
+
+### 5. Install the GPU Agent
+
+On your GPU machine (or Google Colab):
+
+```bash
+# Install dependencies
+pip install pynvml requests python-dotenv rich
+
+# Set environment variables
+export ALUMINATAI_API_KEY="alum_your_key_here"
+export ALUMINATAI_API_ENDPOINT="http://localhost:3000/api/metrics/ingest"
+
+# Run the agent
+python agent/main.py
+```
+
+Options:
+
+```bash
+# Custom sampling interval (1 second)
+python agent/main.py --interval 1
+
+# Save to CSV + upload
+python agent/main.py --output data/metrics.csv
+
+# Run for 5 minutes
+python agent/main.py --duration 300
+
+# Quiet mode (no console output)
+python agent/main.py --quiet --output data/metrics.csv
+```
+
+For production, use the systemd service:
+
+```bash
+cd agent
+chmod +x install.sh
+sudo ./install.sh
+```
+
+### 6. Test on Google Colab (A100)
+
+Upload `agent/tests/AluminatAI_A100_Test.ipynb` to Google Colab:
+
+1. Go to [colab.research.google.com](https://colab.research.google.com)
+2. **File > Upload notebook** and select the `.ipynb` file
+3. **Runtime > Change runtime type** > select **A100 GPU**
+4. Paste your API key in Cell 2
+5. **Runtime > Run all**
+
+The notebook runs 7 test suites:
+- NVML hardware access
+- Collector class + energy calculation
+- API authentication validation
+- End-to-end collect + upload
+- Stress test under GPU load (8192x8192 matmul)
+- API key security audit
+- 60-second continuous monitoring demo
+
+---
+
+## API Reference
+
+### Metrics Ingestion
+
+```
+POST /api/metrics/ingest
+Header: X-API-Key: alum_your_key_here
+```
+
+**Request body** (single metric or array):
+
+```json
+[
+  {
+    "timestamp": "2026-02-06T12:00:00Z",
+    "gpu_index": 0,
+    "gpu_uuid": "GPU-abc123",
+    "gpu_name": "NVIDIA A100-SXM4-40GB",
+    "power_draw_w": 285.5,
+    "power_limit_w": 400.0,
+    "energy_delta_j": 571.0,
+    "utilization_gpu_pct": 95,
+    "utilization_memory_pct": 60,
+    "temperature_c": 72,
+    "memory_used_mb": 32000,
+    "memory_total_mb": 40960
+  }
+]
+```
+
+**Validation rules:**
+- `power_draw_w`: 0-1500W
+- `temperature_c`: 0-120C
+- `utilization_*_pct`: 0-100
+- `timestamp`: valid ISO 8601, not more than 5 minutes in the future
+- Max 1000 metrics per request
+
+**Rate limit:** 100 requests/minute per user
+
+### Dashboard APIs
+
+| Endpoint | Method | Auth | Rate Limit | Description |
+|---|---|---|---|---|
+| `/api/dashboard/today-cost` | GET | Session | 60/min | Today's energy cost |
+| `/api/dashboard/jobs` | GET | Session | 60/min | Job history with pagination |
+| `/api/dashboard/utilization-chart` | GET | Session | 60/min | Time-series chart data |
+| `/api/user/profile` | GET | Session | - | User profile + API key |
+| `/api/user/profile` | PATCH | Session | - | Update profile settings |
+| `/api/user/profile` | POST | Session | 5/hr | Rotate API key |
+
+### API Key Rotation
+
+```bash
+curl -X POST https://aluminatiai-landing.vercel.app/api/user/profile \
+  -H "Content-Type: application/json" \
+  -H "Cookie: your-session-cookie" \
+  -d '{"action": "rotate_api_key"}'
+```
+
+---
+
+## Security
+
+- **API Keys**: Generated with `pgcrypto gen_random_bytes()` - 340 bits of entropy
+- **Row-Level Security**: Users can only access their own data
+- **Rate Limiting**: Per-user limits on all endpoints
+- **Input Validation**: Server-side + database CHECK constraints
+- **HTTPS**: Enforced by Vercel
+- **No ambiguous characters**: API keys exclude `0, O, I, l, 1` to prevent copy errors
+
+---
+
+## Deployment
+
+### Vercel (Web Platform)
+
+```bash
+# Install Vercel CLI
+npm i -g vercel
+
+# Deploy
+cd aluminatai-landing
+vercel
+
+# Set environment variables in Vercel dashboard
+```
+
+### Cron Job (Materialized View Refresh)
+
+Set up a cron job to refresh the hourly metrics view:
+
+- **URL**: `https://your-app.vercel.app/api/cron/refresh-metrics`
+- **Method**: POST
+- **Header**: `Authorization: Bearer your-cron-secret`
+- **Schedule**: Every hour (`0 * * * *`)
+
+You can use [cron-job.org](https://cron-job.org) (free) or Vercel Cron.
+
+---
+
+## Tech Stack
+
+| Component | Technology |
+|---|---|
+| Web Framework | Next.js 16 |
+| UI | React 19 + Tailwind CSS 4 |
+| Charts | Recharts |
+| Database | Supabase PostgreSQL |
+| Auth | Supabase Auth |
+| GPU Agent | Python + pynvml (NVML) |
+| Deployment | Vercel |
+| Scheduler | Minimax with alpha-beta pruning |
+
+---
+
+## Minimax GPU Scheduler
+
+A bonus hackathon project in `minimax-scheduler/` that uses game theory to optimize GPU job scheduling:
+
+- **Speed Player (Maximizer)**: Wants to complete jobs ASAP
+- **Cost Player (Minimizer)**: Wants to minimize energy costs
+- **Alpha-Beta Pruning**: Efficiently explores the decision tree
+- **Result**: 15-30% cost savings vs. naive FIFO scheduling
+
+```bash
+cd minimax-scheduler/backend
+pip install -r requirements.txt
+python demo.py
+```
+
+---
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/my-feature`)
+3. Commit your changes
+4. Push to the branch (`git push origin feature/my-feature`)
+5. Open a Pull Request
+
+---
+
+## License
+
+This project is open source. See [LICENSE](LICENSE) for details.
+
+---
+
+Built by [@AgentMulder404](https://github.com/AgentMulder404)