🐝 BeeWatch AI
Monitoraggio intelligente dell'apiario per apicoltori amatoriali
Registra apiari, alveari, ispezioni e raccolti. Stima la resa attesa con un
modello di regressione. Riassume le note di campo con un assistente
conversazionale che può girare interamente sul tuo computer.
Documentazione ·
Schema del database ·
I dati ·
Backlog
In breve
Progetto in corso. Fondamenta, livello dati e accesso ai dati con l'ETL
sono chiusi; modello di previsione, assistente AI e interfaccia Streamlit sono
ancora da costruire. Quello che segue
descrive il progetto completo, e la tabella di marcia dice a che punto e.
| |
|---|
| Problema | Un apicoltore amatoriale annota apiari, ispezioni e raccolti su carta o su un foglio: i dati esistono, ma non dicono niente sulla resa attesa |
| Il mio ruolo | Progetto personale. Finora: configurazione e gestione dei segreti, gerarchia delle eccezioni, logging, CI, schema del database e dati di partenza, accesso ai dati (transazioni, repository) ed ETL del dataset USDA |
| Risultato finora | 3 milestone su 8 chiuse, 1223 test automatici (1081 rapidi + 142 con MySQL in Docker), CI verde |
| Stack | Python · MySQL · Docker · scikit-learn · Streamlit · pandas |
| Demo | Non ancora: lo scheletro dell'interfaccia c'è (streamlit run app/Home.py), le pagine sono M6. Case study |
| Avvio | pip install -e ".[dev]" e Docker per MySQL — istruzioni |
| Stato | In corso, iniziato ad agosto 2026 — roadmap · backlog |
Indice
Cosa fa
| Funzionalità | Consegnata in |
|---|
| 📋 | Gestione dell'apiario — apiari, alveari, ispezioni e raccolti, con storico completo | M6 |
| 📊 | Dashboard — alveari attivi, ispezioni recenti, produzione della stagione, avvisi sugli alveari trascurati | M6 |
| 📈 | Stima della resa — previsione con banda di incertezza, basata su quindici anni di rilevazioni USDA | M4 · M6 |
| 🤖 | Assistente conversazionale — riassume le note di ispezione e risponde a domande, in locale con Ollama o via OpenRouter | M5 · M6 |
| 📄 | Report — esportazione dei dati della stagione | M6 |
| 🔍 | Trasparenza — una pagina che dichiara da dove vengono i dati, cosa il modello non può sapere, e come vengono trattati i dati personali | M6 · M7 |
Le funzionalità sono elencate in ordine di priorità del backlog. Lo stato di
avanzamento è nella roadmap.
Tecnologie
| Ambito | Scelta | Perché |
|---|
| Linguaggio | Python 3.11+ | requisito di progetto |
| Interfaccia | Streamlit | interfaccia dati in Python puro, senza frontend separato |
| Database | MySQL 8 in Docker | nessuna installazione locale, stesso ambiente per tutto il gruppo |
| Machine Learning | scikit-learn + joblib | pipeline, metriche e serializzazione del modello |
| Assistente | Ollama (locale) o OpenRouter (remoto) | in locale le note non lasciano il computer |
| Qualità | pytest · ruff · GitHub Actions | test e lint automatici a ogni pull request |
Avvio rapido
Requisiti
| |
|---|
| Python 3.11+ | python.org |
| Docker Desktop | MySQL gira in un contenitore: non serve installarlo |
| Ollama (facoltativo) | solo per l'assistente in locale invece che via OpenRouter |
Installazione
git clone https://github.com/imadelmir/beewatch-ai.git
cd beewatch-ai
python -m venv .venv
.venv\Scripts\activate # Windows
source .venv/bin/activate # macOS e Linux
pip install -e ".[dev]"
Configurazione
copy .env.example .env # Windows
cp .env.example .env # macOS e Linux
Le variabili sono documentate una per una dentro .env.example. Le obbligatorie
sono tre: DB_NAME, DB_USER, DB_PASSWORD.
L'applicazione valida la configurazione all'avvio e si ferma con un
messaggio che elenca tutti i problemi insieme, invece di farteli scoprire uno
alla volta.
L'interfaccia
Con il database acceso (docker compose up -d mysql) e il file .env compilato, dalla radice del
progetto (Streamlit legge da lì il tema di .streamlit/config.toml):
streamlit run app/Home.py
Si apre su http://localhost:8501. La Home mostra la panoramica; le sei pagine (Alveari, Ispezioni,
Previsione, Assistente AI, Dashboard, Trasparenza) sono nel menu a sinistra, nell'ordine del prefisso
numerico dei file in app/pages/. Per ora sono scheletri: il contenuto arriva con le task di M6. Senza
database, o senza .env, l'app parte e lo dice in chiaro invece di rompersi. Con docker compose up -d
parte anche l'interfaccia, nel contenitore.
Il dataset
Il dataset USDA è già nel repository, in data/honeyproduction.csv: la
licenza (CC0, pubblico dominio) lo permette. Provenienza, versione e checksum
sono in data/README.md.
Per caricarlo nel database (si può rilanciare: non duplica nulla):
docker compose up -d mysql
python scripts/run_etl.py
Oppure, senza Python sul computer, dentro il contenitore dell'app:
docker compose run --rm app python scripts/run_etl.py
Come è fatto, cosa dice e cosa non può dire: docs/markdown/M2-dati/dati.md.
Il modello
Il modello di previsione è già nel repository, addestrato e documentato:
models/produzione_v1.joblib e, accanto, models/produzione_v1.json (versione, dati usati,
metriche, intervallo, versioni delle librerie). L'applicazione lo carica, non lo addestra mai
da sola. Per rifarlo da zero, dopo aver caricato il dataset (si usa sempre il database, mai il CSV):
python scripts/train_model.py
Stessi dati, stesso seme e stesse librerie danno le stesse previsioni. Cosa sa fare, quanto
sbaglia e quando non usarlo: docs/model_card.md.
Il modello di linguaggio
L'assistente AI usa Ollama in locale (predefinito: gratis, le note non escono dal computer) oppure
OpenRouter nel cloud. Si sceglie con una variabile in .env (LLM_PROVIDER, più LLM_API_KEY per
OpenRouter e OLLAMA_BASE_URL se Ollama non è su localhost; dal contenitore usa
http://host.docker.internal:11434). Per provare che il provider risponde davvero:
python scripts/verifica_llm.py
Aggiornare un database che esiste già
Gli script di sql/ girano da soli solo alla creazione del database (volume vuoto). Chi ha già
un volume e riceve una modifica dello schema la applica a mano, come root (l'utente
dell'applicazione non può modificare lo schema, ed è voluto). Ogni file sql/schema_*.sql è
ripetibile e non tocca i dati; il comando è scritto in testa a ciascuno. Per esempio, per la
colonna previsioni.feature_json (M4-T8):
docker compose exec -T mysql sh -c \
'mysql -uroot -p"$MYSQL_ROOT_PASSWORD" --database="$MYSQL_DATABASE"' \
< sql/schema_02_previsioni_feature_json.sql
e, per la tabella dei riepiloghi AI delle ispezioni (M5-T5), lo stesso comando con
sql/schema_03_riepiloghi_ispezione.sql.
Se manca una modifica, l'applicazione lo dice con un messaggio che rimanda a questo comando.
Struttura del progetto
beewatch-ai/
├── app/ interfaccia Streamlit — nessuna logica applicativa
├── beewatch/ il pacchetto: configurazione, database, ML, AI
├── data/ dataset locali (ignorata da git)
├── docs/ documentazione: markdown/, diagrams/, images/
├── models/ modelli addestrati (.joblib)
├── notebooks/ analisi esplorativa (M2) e confronto fra modelli (M4)
├── scripts/ utilità eseguibili
├── sql/ schema e seed del database
└── tests/ test automatici
La separazione fra app/ e beewatch/ è deliberata. L'interfaccia chiama
il pacchetto; il pacchetto non sa che Streamlit esiste. I test girano senza
avviare l'interfaccia, e se un giorno l'interfaccia cambiasse tecnologia la
logica resterebbe intatta.
Sviluppo
pytest -m "not integration" # suite rapida, senza Docker (è quella del controllo obbligatorio)
pytest -m integration # test con MySQL vero: richiede Docker in esecuzione
ruff check . # lint e ordine degli import
ruff check . --fix # correzione automatica di ciò che è correggibile
I test integration avviano da soli uno stack Docker temporaneo e lo smontano
alla fine: il database di sviluppo non viene mai toccato. pytest senza
opzioni li esegue tutti, quindi senza Docker va in errore.
Ogni pull request installa il progetto su una macchina pulita ed esegue lint
e test rapidi: se il controllo Lint e test è rosso, il merge è bloccato. Un
secondo job esegue i test integration con MySQL in Docker. È anche la
sola prova che il progetto si installa davvero da zero — sul computer di chi
sviluppa funziona sempre.
Convenzioni di ramo, messaggi di commit e flusso di lavoro:
CONTRIBUTING.md.
Documentazione
Ogni task completata ha il proprio documento, nella cartella della sua
milestone. L'indice è in docs/README.md.
Stato e roadmap
| Milestone | Contenuto | Stato |
|---|
| M1 | Fondamenta e setup | ✅ completata |
| M2 | Dati e database | ✅ completata |
| M3 | Accesso ai dati ed ETL | ✅ completata |
| M4 | Machine Learning | ⬜ |
| M5 | Componente AI generativa | ⬜ |
| M6 | Interfaccia Streamlit | ⬜ |
| M7 | Qualità, Docker, etica | ⬜ |
| M8 | Documentazione, demo e consegna | ⬜ |
Il backlog completo — 55 task su 9 milestone, ciascuna con la propria
Definition of Done — è nelle issue e nella board Projects.
Limiti dichiarati
Le stime prodotte da questo sistema sono indicative e si basano su
rilevazioni di apicoltura commerciale statunitense del periodo 1998-2012,
aggregate per stato.
Non descrivono un apiario amatoriale italiano: vanno lette come ordine di
grandezza, mai come previsione puntuale. Per questo ogni stima è mostrata come
intervallo e mai come numero singolo.
Questo software non è uno strumento diagnostico. Non sostituisce un
veterinario né un tecnico apistico.
L'analisi completa dei limiti — bias dei dati, privacy e GDPR, trasparenza, EU
AI Act, usi impropri — è in
docs/markdown/M2-dati/dati.md.
Licenza
MIT — Imad El Mir , progetto finale ITS.
