feat: initial project setup with scenarios, database and web ui
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/)
This commit is contained in:
Luca Sacchi Ricciardi
165
.opencode/AGENTS.md
Normal file
165
.opencode/AGENTS.md
Normal file
@@ -0,0 +1,165 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user