Metadata-Version: 2.4
Name: studygraph
Version: 1.4.2
Summary: Build, search and ask questions on your study materials — locally.
Author-email: Antonio Cioffi <cioffiantonio.2004@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/cioffiAI/StudyGraph
Project-URL: Repository, https://github.com/cioffiAI/StudyGraph
Project-URL: Bug Tracker, https://github.com/cioffiAI/StudyGraph/issues
Keywords: study,education,rag,pdf,knowledge-base,search,qa
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Education
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Text Processing :: Indexing
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: pymupdf>=1.23
Requires-Dist: langdetect>=1.0
Requires-Dist: python-dotenv>=1.0
Requires-Dist: fastapi>=0.100
Requires-Dist: uvicorn>=0.20
Requires-Dist: python-multipart>=0.0.6
Requires-Dist: jinja2>=3.0.0
Requires-Dist: pywebview>=5.0
Requires-Dist: pyinstaller>=6.3.0
Requires-Dist: keyring>=24.0
Dynamic: license-file

# StudyGraph · v1.4.2

**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, ti permette di chattare con i tuoi documenti in un canvas split-screen e ricevere risposte citate. Funziona offline con `--dry-run`, senza API key.

> ![StudyGraph Web UI](docs/screenshot.png)

## Requisiti

- **Python >= 3.10**
- Windows, macOS o Linux

## Quickstart

```bash
# 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.

> **Guida per beta tester**: vedi [BETA_SETUP.md](BETA_SETUP.md) con istruzioni dettagliate di installazione e primo utilizzo.

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, Documenti, Chat) |
| `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:

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

### `studygraph web`

Interfaccia web locale con 8 pagine — **Esplora**, Carica PDF, Documenti, Chat, Dashboard, Impostazioni, Progresso:

```bash
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" aggiornato: palette calda, mini design system Jinja/CSS, navigazione chiara e 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:

```bash
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`

```bash
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`

```bash
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)

```bash
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`:

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

Configurazione completa incluso QA generativo:

```env
STUDYGRAPH_QA_PROVIDER=openai_compatible
STUDYGRAPH_QA_API_KEY=la_tua_chiave
STUDYGRAPH_QA_BASE_URL=https://api.openai.com/v1
STUDYGRAPH_QA_MODEL=gpt-4o-mini
```

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:
```bash
python --version
pip install --upgrade pip
```

### `studygraph: command not found` (Windows)
Assicurati che Python Scripts sia nel PATH:
```cmd
python -m studygraph web
```
Oppure reinstalla con `pip install -e .` e riavvia il terminale.

### Porta 8111 gia in uso
```bash
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:
```bash
pip install --upgrade pip setuptools wheel
pip install pymupdf
```

### API key non valida o errore LLM
Usa `--dry-run` per evitare chiamate API:
```bash
studygraph build ./data/input --dry-run
```
Oppure verifica la configurazione in `.env.local`.

### Altri problemi
Apri una issue su [GitHub Issues](https://github.com/cioffiAI/StudyGraph/issues).

## Test

```bash
pytest          # 247 tests, ~20s
```

## Licenza

MIT — vedi [LICENSE](LICENSE).
