59e5cf48f0
Add complete mockupAWS platform for AWS cost estimation: - FastAPI backend with scenario management - PostgreSQL database schema for scenarios, metrics, logs - AWS pricing table with real pricing data - React frontend dashboard (planned) - PII detection and token counting - Report generation (PDF/CSV) - Complete test suite with pytest - Docker Compose setup - Documentation: README, PRD, Architecture - OpenCode configuration (.opencode/)
166 lines
4.5 KiB
Markdown
166 lines
4.5 KiB
Markdown
# AGENTS.md - Istruzioni per OpenCode
|
|
|
|
## Contesto Progetto
|
|
|
|
**mockupAWS** è un simulatore FastAPI per profilare traffico di log e calcolare costi AWS prima del deploy in produzione. Fa parte dell'ecosistema LogWhispererAI.
|
|
|
|
### Scopo Principale
|
|
- Non analizzare i log, ma **profilare il traffico e calcolare i driver di costo** AWS
|
|
- Simulare comportamento di SQS, Lambda e Bedrock/LLM
|
|
- Fornire stime di fatturazione basate su traffico simulato o reale
|
|
|
|
## Principi Guida (DA RISPETTARE SEMPRE)
|
|
|
|
### 1. Safety First
|
|
- Validare sempre l'integrità del payload in ingresso
|
|
- Verificare la sanitizzazione dei dati (assenza di PII/Secreti)
|
|
- Controllare presenza di email (@ + .com) come indicatore di data leak
|
|
|
|
### 2. Little Often
|
|
- Processamento a piccoli batch per simulare lettura ottimizzata dalle code
|
|
- Task piccole e verificabili in <2 ore
|
|
- Progresso incrementale
|
|
|
|
### 3. Double Check
|
|
- Validazione finale del prompt generato prima del calcolo costi
|
|
- Conteggio token esatto con tokenizer cl100k_base
|
|
- Verificare sempre i risultati delle stime
|
|
|
|
## Workflow di Sviluppo
|
|
|
|
### TDD (Test-Driven Development)
|
|
1. **Scrivere il test PRIMA** della logica di implementazione
|
|
2. Il test deve fallire inizialmente (Red)
|
|
3. Implementare la logica minima per far passare il test (Green)
|
|
4. Refactoring (Refactor)
|
|
|
|
### Convenzioni Git
|
|
- **Conventional Commits**: `feat:`, `fix:`, `chore:`, `test:`, `docs:`
|
|
- Commit atomici e mirati
|
|
- Un concetto = un commit
|
|
|
|
### Struttura Messaggi Commit
|
|
```
|
|
<type>: <descrizione breve>
|
|
|
|
[opzionale: corpo con dettagli]
|
|
|
|
[opzionale: footer con riferimenti]
|
|
```
|
|
|
|
Esempi:
|
|
- `feat: add token counting for Bedrock cost estimation`
|
|
- `test: add SQS billing block calculation tests`
|
|
- `fix: correct payload size calculation in profiler`
|
|
|
|
## Metriche AWS Simulate
|
|
|
|
### SQS (Simple Queue Service)
|
|
- Blocco fatturazione: 64KB (65536 bytes)
|
|
- Formula: `(payload_size_bytes // 65536) + 1`
|
|
- Metrica: `sqs_billing_blocks`
|
|
|
|
### Lambda
|
|
- Simulazione invocazioni batch
|
|
- Metrica: `lambda_simulated_invocations`
|
|
|
|
### Bedrock/LLM
|
|
- Tokenizer: `cl100k_base` (tiktoken)
|
|
- Conteggio: `len(encoder.encode(text))`
|
|
- Metrica: `llm_estimated_input_tokens`
|
|
|
|
## Struttura File
|
|
|
|
```
|
|
mockupAWS/
|
|
├── src/
|
|
│ ├── main.py # FastAPI app con endpoint /ingest, /metrics
|
|
│ └── profiler.py # Logica conteggio token e blocchi SQS
|
|
├── test/
|
|
│ └── test_ingest.py # Test TDD per tutte le metriche
|
|
├── export/ # File gestiti da agente @spec-architect
|
|
│ ├── prd.md
|
|
│ ├── architecture.md
|
|
│ ├── kanban.md
|
|
│ ├── progress.md
|
|
│ └── githistory.md
|
|
├── docs/
|
|
│ ├── architecture.md # Decisioni architetturali (ADR)
|
|
│ └── bug_ledger.md
|
|
└── pyproject.toml # Dipendenze e configurazione uv
|
|
```
|
|
|
|
## Comandi Principali
|
|
|
|
```bash
|
|
# Installazione dipendenze
|
|
uv sync
|
|
|
|
# Avvio server di sviluppo
|
|
uv run uvicorn src.main:app --reload
|
|
|
|
# Esecuzione test
|
|
uv run pytest
|
|
|
|
# Test specifico
|
|
uv run pytest test/test_ingest.py::test_sqs_billing_block_calculation -v
|
|
```
|
|
|
|
## Linee Guida Codice
|
|
|
|
### Import
|
|
```python
|
|
# 1. Standard library
|
|
import sys
|
|
import time
|
|
|
|
# 2. Third party
|
|
import tiktoken
|
|
from fastapi import FastAPI
|
|
from pydantic import BaseModel
|
|
|
|
# 3. Local modules
|
|
from src.profiler import count_tokens, calculate_sqs_blocks
|
|
```
|
|
|
|
### Naming
|
|
- Funzioni: `snake_case` (es. `count_tokens`, `calculate_sqs_blocks`)
|
|
- Classi: `PascalCase` (es. `LogPayload`, `Metrics`)
|
|
- Costanti: `UPPER_CASE`
|
|
|
|
### Type Hints
|
|
- Usare sempre type hints per parametri e return type
|
|
- Usare Pydantic BaseModel per i payload
|
|
|
|
## Gestione Errori
|
|
|
|
- Validazione input con Pydantic
|
|
- Non esporre dettagli interni negli errori HTTP
|
|
- Loggare errori per debug in ambiente sviluppo
|
|
|
|
## Testing
|
|
|
|
### Fixture Disponibili
|
|
- `reset_metrics`: Resetta i contatori prima di ogni test
|
|
|
|
### Test Obbligatori per Nuove Feature
|
|
1. Test endpoint risponde correttamente (200)
|
|
2. Test calcolo metriche specifiche
|
|
3. Test edge cases (payload vuoto, payload molto grande)
|
|
4. Test validazione sicurezza (PII detection)
|
|
|
|
## Domande da Porsi Prima di Modificare
|
|
|
|
1. "Ho scritto il test prima dell'implementazione?"
|
|
2. "Il mio codice rispetta il principio Safety First?"
|
|
3. "Ho fatto Double Check sulle stime costi?"
|
|
4. "Il commit segue le convenzioni?"
|
|
5. "Ho verificato che non esponiamo PII nei log?"
|
|
|
|
## Riferimenti
|
|
|
|
- FastAPI Docs: https://fastapi.tiangolo.com
|
|
- Tiktoken: https://github.com/openai/tiktoken
|
|
- AWS SQS Pricing: https://aws.amazon.com/sqs/pricing/
|
|
- Conventional Commits: https://www.conventionalcommits.org
|