# 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
