mockupAWS/.opencode/AGENTS.md

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

# 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

# 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