commit 671bd9d46023cd3b481c483a2216473ad169dc8b Author: Davide Grilli Date: Wed Jul 15 18:06:21 2026 +0200 Commit iniziale diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..7fdea24 --- /dev/null +++ b/.gitignore @@ -0,0 +1,23 @@ +# stato locale dell'app llm-wiki (hash/timestamp di sync, non contenuto) +# la cartella resta nel repo (.gitkeep) cosi' un clone fresco la ritrova gia' pronta +.llm-wiki/* +!.llm-wiki/.gitkeep + +# preferenze Obsidian locali (workspace, plugin UI, non contenuto della wiki) +.obsidian/* +!.obsidian/.gitkeep + +# scarti tipici di un output MinerU non ancora ripulito prima dell'ingest +# (vedi CLAUDE.md: da non copiare in raw/sources/, ma per sicurezza li ignoriamo +# nel caso finiscano nel repo prima della pulizia) +*_layout.pdf +*_span.pdf +*_middle.json +*_model.json +**/auto/ + +# OS / editor +.DS_Store +Thumbs.db +*.tmp +~$* diff --git a/.llm-wiki/.gitkeep b/.llm-wiki/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/.obsidian/.gitkeep b/.obsidian/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..d818416 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,5 @@ +# AGENTS.md + +Le istruzioni operative per questo repository sono in [CLAUDE.md](./CLAUDE.md) — leggilo prima di lavorare qui. + +Questo file esiste solo perché alcuni agent (es. Codex CLI) cercano `AGENTS.md` invece di `CLAUDE.md`; il contenuto è identico, tenuto in un solo posto per evitare che i due file divergano. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..c03d0a1 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,84 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## Cos'è questo repository + +Non è un progetto software: è un vault Obsidian gestito con il pattern **llm-wiki** (raw → wiki, sorgenti immutabili → pagine sintetizzate), applicato a un dominio di ingegneria meccanica. Non ci sono build/lint/test: l'unico "lavoro" è ingest di documenti grezzi e mantenimento delle pagine wiki. + +Il layer `.llm-wiki/` (project.json, file-snapshot.json, file-change-queue.json, history/) è gestito da un'app esterna che traccia le modifiche a `purpose.md`, `schema.md` e `wiki/*.md`. Non modificare questi file JSON a mano: si aggiornano da soli quando l'app rileva un cambiamento. + +## I tre livelli + +1. **`raw/`** — sorgenti immutabili. Non modificare mai un file dentro `raw/` dopo l'ingest: se un dato è sbagliato o mal estratto, la correzione va fatta nella pagina wiki (con nota sul problema), non nel raw. + - `raw/sources/` — un sottocartella per documento sorgente (vedi convenzione sotto) + - `raw/assets/` — immagini/scan/figure autonome non legate a un output MinerU +2. **`wiki/`** — pagine generate/curate da Claude, organizzate per tipo secondo `schema.md` (`entities/`, `concepts/`, `sources/`, `queries/`, `comparisons/`, `synthesis/`, più `index.md`, `log.md`, `overview.md`). +3. **`purpose.md` / `schema.md`** — regole. `purpose.md` definisce l'ambito e le domande guida del progetto; `schema.md` definisce come sono strutturate le pagine e le convenzioni di naming/frontmatter. Leggi entrambi prima di ogni sessione di ingest. + +## Convenzione per `raw/sources/` + +Ogni documento sorgente vive in `raw/sources//`, dove `` è un kebab-case descrittivo (es. `iso-6336-gear-rating`, `catalogo-skf-cuscinetti-2024`). Dentro: + +- l'output originale così com'è (markdown + eventuali `images/`, `*_content_list.json`, ecc.) — **non spostare o rinominare i file interni** prodotti dal parser, altrimenti si rompono i link relativi alle immagini +- se il documento arriva come PDF puro senza markdown, il PDF stesso + +Questa cartella è la unità minima di provenienza: ogni claim scritto in `wiki/` deve poter essere ricondotto a uno slug in `raw/sources/`. + +## Ingest di un nuovo documento in `raw/` + +Quando trovi materiale nuovo (o non ancora processato) in `raw/sources/`: + +1. **Identifica il tipo di documento**: norma/standard (ISO, UNI, DIN...), datasheet/catalogo produttore, paper/articolo tecnico, capitolo di libro, report interno, manuale. Il tipo guida quali pagine wiki creare (uno standard e un datasheet produttore, per esempio, diventano entity diverse con campi diversi). +2. **Valuta la qualità dell'estrazione** prima di fidarti del testo (vedi sezione MinerU sotto). Se il documento è scansionato o processato in modalità pipeline, non trattare l'OCR come verità assoluta senza controllo. +3. **Estrai entità e concetti**: componenti/materiali/norme/produttori → `wiki/entities/`; fenomeni, metodi di calcolo, teorie → `wiki/concepts/`; il documento stesso → una pagina in `wiki/sources/`. +4. **Segui `schema.md`** per frontmatter, naming e wikilink `[[slug]]`. Non inventare tipi di pagina o convenzioni diverse. +5. **Aggiorna `wiki/index.md`** (nuove voci) e **`wiki/log.md`** (una riga sotto la data odierna che descrive cosa hai ingerito e le pagine toccate). Questi due si aggiornano **ad ogni ingest**, senza bisogno che l'utente lo chieda. +6. Se il documento contraddice materiale già presente, segui la sezione "Contradiction Handling" di `schema.md` (nota sulla pagina concept/entity coinvolta, crea/aggiorna una query page, risolvi con una synthesis solo quando hai abbastanza evidenza). + +**`wiki/overview.md` non si aggiorna ad ogni ingest** (diventerebbe rumoroso e incoerente riscritto un documento alla volta). Aggiornalo solo a checkpoint più ampi: +- l'utente lo chiede esplicitamente ("aggiorna l'overview"), +- dopo un batch di più documenti correlati appena ingeriti, +- quando emerge un cambiamento reale nella thesis/scope del progetto (vedi `purpose.md`). + +In quei casi riscrivi `overview.md` come sintesi corrente dello stato della wiki (cosa copre, cosa manca, thesis aggiornata), non come changelog — quello è il ruolo di `log.md`. + +## Note su MinerU (backend "pipeline") + +Molti documenti in `raw/sources/` arrivano pre-processati con **MinerU in modalità pipeline** (parsing layout+OCR tradizionale, non VLM). Questo backend è più leggero ma ha limiti noti di cui tenere conto durante l'ingest: + +- **Ordine di lettura**: su layout multi-colonna o tabelle complesse l'ordine dei blocchi estratti può essere sbagliato. Se un paragrafo non ha senso nel punto in cui compare, verifica se appartiene a una colonna/sezione diversa prima di citarlo. +- **Formule**: convertite in LaTeX via OCR, possono contenere simboli sbagliati (es. confusione tra `l`/`1`/`I`, apici/pedici persi, segni persi). Non riportare una formula tecnica in una pagina wiki senza controllo visivo minimo di plausibilità (unità di misura coerenti, termini noti). +- **Tabelle**: rese come markdown/HTML, possono avere celle disallineate o merge di celle perse. Trattare i valori numerici tabellari come "da verificare" se la tabella sembra irregolare. +- **Header/footer/note a piè di pagina**: a volte finiscono interfogliati nel corpo del testo. Non trattarli come parte del discorso principale. +- **Immagini**: estratte come crop in `images/` e referenziate con path relativi nel `.md` — non toccare i path. + +Regola pratica: quando una pagina wiki riporta un dato numerico, una formula o una specifica tecnica presa da un documento in pipeline mode, se il punto è dubbio aggiungi una nota inline tipo `(da verificare: OCR pipeline mode, layout tabellare irregolare)` invece di ometterla silenziosamente o presentarla come certa. + +### Checklist import da output MinerU grezzo + +Un output MinerU tipico (cartella `/auto/`) contiene molti file: solo una parte va copiata in `raw/sources//`. + +**Tenere:** +- `.md` — testo +- `_content_list.json` (o `_v2`, sceglierne **uno solo**) — blocchi strutturati con `page_idx`/`img_path`, utile per citare pagine +- `images/` — cartella intera, referenziata dal `.md` con path relativi tipo `images/.jpg` +- `_origin.pdf` — opzionale, solo se vuoi poter riaprire il PDF originale per verificare formule/tabelle dubbie (spesso decine di MB: valuta se vale lo spazio) + +**Scartare** (debug/intermedi della pipeline, senza valore per la wiki, spesso centinaia di MB in totale): +- `_layout.pdf`, `_span.pdf` — PDF di debug con overlay dei bounding box +- `_middle.json` — struttura intermedia pre-assemblaggio, ridondante rispetto a `content_list.json` +- `_model.json` — output grezzo dei modelli di detection + +**Passaggi:** +1. Crea `raw/sources//` (lo slug identifica il documento, es. `costruzioni-di-macchine-9` — non serve rispecchiare il nome file originale) +2. Copia dentro solo i file "da tenere", eliminando il livello intermedio `auto/` +3. **Non rinominare** `images/` né i file interni copiati: i path relativi (`images/.jpg`) non dipendono dal nome della cartella padre, quindi rinominare la cartella-slug è sicuro, rinominare i singoli file è inutile e rischioso se non si aggiornano anche i riferimenti nel `.md`/`.json`. + +## Regole generali + +- Non modificare mai i file dentro `raw/`. +- Non modificare i file JSON dentro `.llm-wiki/`. +- Ogni pagina wiki nuova va aggiunta a `wiki/index.md`; ogni sessione di lavoro va loggata in `wiki/log.md`. +- Usa `[[wikilink]]` per collegare le pagine tra loro, non link markdown relativi. +- Lingua di default per le pagine wiki: italiano (i nomi di tipo/frontmatter restano in inglese come da `schema.md`, es. `type: entity`). diff --git a/purpose.md b/purpose.md new file mode 100644 index 0000000..a1a788f --- /dev/null +++ b/purpose.md @@ -0,0 +1,33 @@ +# Project Purpose + +## Goal + + + +## Key Questions + + + +1. +2. +3. + +## Scope + +**In scope:** +- + +**Out of scope:** +- + +## Domain conventions + +- **Lingua pagine wiki:** italiano (default, vedi CLAUDE.md) +- **Fonti tipiche:** norme (ISO/UNI/DIN...), datasheet/cataloghi produttore, paper, manuali — spesso pre-processate con MinerU in modalità pipeline (vedi CLAUDE.md per i limiti di questo backend) +- **Unità di misura:** + +## Thesis + + + +> TBD diff --git a/raw/assets/.gitkeep b/raw/assets/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/raw/sources/.gitkeep b/raw/sources/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/schema.md b/schema.md new file mode 100644 index 0000000..3767a45 --- /dev/null +++ b/schema.md @@ -0,0 +1,91 @@ +# Wiki Schema + +## Raw Layer + +- `raw/sources//` — one subfolder per source document, kebab-case slug (e.g. `iso-6336-gear-rating`, `catalogo-skf-cuscinetti-2024`). Contains the document as produced by ingestion (MinerU markdown output + `images/` + json sidecars, or a bare PDF). Never rename or move files inside a source folder — relative image links depend on the original layout. +- `raw/assets/` — standalone images/scans/figures not tied to a specific ingested document. +- Files under `raw/` are immutable once ingested. If extracted content is wrong (OCR error, bad table), fix it in the wiki page with a note — never edit the raw file. +- Every claim in `wiki/` must be traceable to a slug in `raw/sources/`. + +## Page Types + +| Type | Directory | Purpose | +|------|-----------|---------| +| entity | wiki/entities/ | Named things (people, tools, organizations, datasets) | +| concept | wiki/concepts/ | Ideas, techniques, phenomena, frameworks | +| source | wiki/sources/ | Papers, articles, talks, books, blog posts | +| query | wiki/queries/ | Open questions under active investigation | +| comparison | wiki/comparisons/ | Side-by-side analysis of related entities | +| synthesis | wiki/synthesis/ | Cross-cutting summaries and conclusions | +| overview | wiki/ | High-level project summary (one per project) | + +## Naming Conventions + +- Files: `kebab-case.md` +- Entities: match official name where possible (e.g., `openai.md`, `gpt-4.md`) +- Concepts: descriptive noun phrases (e.g., `chain-of-thought.md`) +- Sources: `author-year-slug.md` (e.g., `wei-2022-cot.md`) +- Queries: question as slug (e.g., `does-scale-improve-reasoning.md`) + +## Frontmatter + +All pages must include YAML frontmatter: + +```yaml +--- +type: entity | concept | source | query | comparison | synthesis | overview +title: Human-readable title +tags: [] +related: [] +created: YYYY-MM-DD +updated: YYYY-MM-DD +--- +``` + +Source pages also include: +```yaml +authors: [] +year: YYYY +url: "" +venue: "" +``` + +Any page that draws on a source processed via OCR/layout extraction (e.g. MinerU pipeline mode) should reference it and, where a specific fact is uncertain (garbled formula, misaligned table, ambiguous reading order), mark it inline rather than presenting it as verified: + +```yaml +raw_source: raw-slug # slug in raw/sources/ this page is derived from +confidence: high | medium | low +``` + +Use `confidence: low` or `medium` for any numeric value, formula, or spec pulled from a document with known extraction issues, until it's been cross-checked. + +## Index Format + +`wiki/index.md` lists all pages grouped by type. Each entry: +``` +- [[page-slug]] — one-line description +``` + +## Log Format + +`wiki/log.md` records activity in reverse chronological order: +``` +## YYYY-MM-DD + +- Action taken / finding noted +``` + +## Cross-referencing Rules + +- Use `[[page-slug]]` syntax to link between wiki pages +- Every entity and concept should appear in `wiki/index.md` +- Queries link to the sources and concepts they draw on +- Synthesis pages cite all contributing sources via `related:` + +## Contradiction Handling + +When sources contradict each other: +1. Note the contradiction in the relevant concept or entity page +2. Create or update a query page to track the open question +3. Link both sources from the query page +4. Resolve in a synthesis page once sufficient evidence exists diff --git a/wiki/comparisons/.gitkeep b/wiki/comparisons/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/wiki/concepts/.gitkeep b/wiki/concepts/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/wiki/entities/.gitkeep b/wiki/entities/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/wiki/index.md b/wiki/index.md new file mode 100644 index 0000000..0617fac --- /dev/null +++ b/wiki/index.md @@ -0,0 +1,13 @@ +# Wiki Index + +## Entities + +## Concepts + +## Sources + +## Queries + +## Comparisons + +## Synthesis diff --git a/wiki/log.md b/wiki/log.md new file mode 100644 index 0000000..dddc37a --- /dev/null +++ b/wiki/log.md @@ -0,0 +1,5 @@ +# Research Log + +## 2026-07-15 + +- Project created diff --git a/wiki/overview.md b/wiki/overview.md new file mode 100644 index 0000000..1c4ae02 --- /dev/null +++ b/wiki/overview.md @@ -0,0 +1,10 @@ +--- +type: overview +title: Project Overview +tags: [] +related: [] +--- + +# Overview + + diff --git a/wiki/queries/.gitkeep b/wiki/queries/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/wiki/sources/.gitkeep b/wiki/sources/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/wiki/synthesis/.gitkeep b/wiki/synthesis/.gitkeep new file mode 100644 index 0000000..e69de29