studygraph 1.2.2

Build, search and ask questions on your study materials — locally.

StudyGraph

Carica i tuoi PDF, fai domande, ricevi risposte con citazioni — tutto in locale.

StudyGraph trasforma appunti, dispense e slide in una knowledge base interrogabile con ricerca testuale e semantica. L'interfaccia web ti mostra una mappa visuale dei tuoi materiali e ti permette di fare domande con risposte citate. Funziona offline con --dry-run, senza API key.

Requisiti

• Python >= 3.10
• Windows, macOS o Linux

Quickstart

# 1. Installa da PyPI
pip install studygraph

# 2. (Opzionale) Crea i file di configurazione
studygraph init

# 3. Avvia l'interfaccia web (apre automaticamente il browser)
studygraph start

# 4. Carica i tuoi PDF dalla pagina Upload, oppure clicca "Prova la demo"

PDF di esempio: la cartella studygraph/demo_pdfs/ contiene 5 PDF sintetici per testare la pipeline completa. Per provare: carica analisi1_good.pdf dalla pagina Upload.

Tutto parte dalla pagina Esplora che mostra la tua knowledge base con un grafo visuale. Se non hai ancora documenti, StudyGraph carica automaticamente una demo (Fourier, Limiti, Derivate).

Windows

Su Windows, dopo l'installazione puoi:

• Usare il terminale: apri PowerShell o CMD e digita studygraph start
• Usare il launcher: fai doppio clic su start_studygraph.bat (apre automaticamente il browser su http://localhost:8111)

Comandi principali

Comando	Cosa fa
studygraph start	Avvia tutto: web UI + apre il browser. Il punto di partenza.
studygraph init	Crea config.yaml e .env.example nella cartella corrente
studygraph web	Avvia l'interfaccia web locale (Esplora, Upload, Dashboard, Cerca, Chiedi)
studygraph ask "domanda"	Risponde a una domanda con citazioni
studygraph search-kb "query"	Cerca nella knowledge base (mode: lexical/semantic/hybrid)
studygraph build DIR	Pipeline completa: audit -> export -> KB -> indice -> embedding
studygraph demo	Demo end-to-end da terminale
studygraph audit DIR	Analizza e valuta documenti
studygraph evaluate-retrieval KB DATASET	Confronta modalita di retrieval
studygraph evaluate-qa KB DATASET	Valuta qualita delle risposte

studygraph start

Il comando principale per iniziare:

studygraph start                  # avvia su http://localhost:8111 e apre il browser
studygraph start --port 8112      # porta custom

studygraph web

Interfaccia web locale con 6 pagine — Esplora, Upload, Dashboard, Cerca, Chiedi:

studygraph web                    # avvia su http://localhost:8111
studygraph web --port 8112        # porta custom
studygraph web --host 0.0.0.0     # accessibile da altri dispositivi nella rete

Design "Warm Academic": palette calda, font serif, layout editoriale. CSS inline, zero dipendenze frontend.

Pagina Esplora: mappa visuale della knowledge base (grafo corsi → argomenti → documenti), card esplorabili, statistiche. Se la KB e vuota, trovi un welcome con guida in 3 step e pulsante per la demo.

studygraph build

Pipeline completa in un comando:

studygraph build ./data/input --course "Analisi 1" --dry-run

Opzioni: --dry-run (nessuna API key), --course, --output-dir, --skip-export, --with-embed-real.

studygraph ask

studygraph ask "Che cos'è il limite di una funzione?" --mode hybrid --dry-run
studygraph ask "formule di derivazione" --mode lexical --dry-run --json

Opzioni: --mode lexical|semantic|hybrid, --course, --top-k, --json.

studygraph search-kb

studygraph search-kb "serie di Fourier" --mode lexical
studygraph search-kb "funzioni periodiche" --mode semantic --dry-run
studygraph search-kb "0/0" --mode hybrid --dry-run

studygraph audit (comando base)

studygraph audit ./examples/demo_documents --course "Analisi 1" --dry-run

Processo: ingest -> estrazione testo -> qualita -> dedup -> scoring -> decisione -> dashboard CSV+HTML.

Configurazione

Per usare LLM ed embedding reali, crea .env.local:

STUDYGRAPH_API_KEY=la_tua_chiave
STUDYGRAPH_LLM_BASE_URL=https://generativelanguage.googleapis.com/v1beta/openai/
STUDYGRAPH_LLM_MODEL=gemini-2.0-flash

Oppure modifica config.yaml. I default puntano a OpenAI (api.openai.com/v1, modello gpt-4o-mini).

Output

Tutto in data/output/:

• dashboard.csv / .html — report con score e decisioni
• dashboard_<corso>.csv / .html — per corso
• documents.jsonl — record completi di scoring
• knowledge_base/ — KB canonica con catalog + per-course indici
• search_index/ — indice invertito per ricerca BM25
• vector_index/ — embedding vettoriali (se generati)
• eval/ — report di valutazione retrieval e QA
• demo/ — output del comando demo

Troubleshooting

pkg_resources o pip errori durante l'installazione

Assicurati di avere Python >= 3.10 e pip aggiornato:

python --version
pip install --upgrade pip

studygraph: command not found (Windows)

Assicurati che Python Scripts sia nel PATH:

python -m studygraph web

Oppure reinstalla con pip install -e . e riavvia il terminale.

Porta 8111 gia in uso

studygraph web --port 8112      # usa una porta diversa

PyMuPDF (libreria PDF) non si installa

Su Windows, PyMuPDF ha wheel precompilati. Se l'installazione fallisce, installa prima:

pip install --upgrade pip setuptools wheel
pip install pymupdf

API key non valida o errore LLM

Usa --dry-run per evitare chiamate API:

studygraph build ./data/input --dry-run

Oppure verifica la configurazione in .env.local.

Altri problemi

Apri una issue su GitHub Issues.

Test

pytest          # 237 test

Licenza

MIT — vedi LICENSE.