Translate repository documentation to English

Author: sudoantonio

.github/ISSUE_TEMPLATE/bug.yml

@@ -1,25 +1,24 @@
 name: Bug
-description: Segnala un errore riproducibile nel prototipo
+description: Report a reproducible error in the prototype
 title: "[Bug]: "
 labels: [bug]
 body:
   - type: textarea
     id: observed
     attributes:
-      label: Comportamento osservato
+      label: Observed behavior
     validations:
       required: true
   - type: textarea
     id: expected
     attributes:
-      label: Comportamento atteso
+      label: Expected behavior
     validations:
       required: true
   - type: textarea
     id: reproduction
     attributes:
-      label: Riproduzione minima
-      description: Usa dati pubblici o sintetici e non includere credenziali.
+      label: Minimal reproduction
+      description: Use public or synthetic data and do not include credentials.
     validations:
       required: true
-

.github/ISSUE_TEMPLATE/config.yml

@@ -1,5 +1,5 @@
 blank_issues_enabled: false
 contact_links:
-  - name: Vulnerabilità
+  - name: Security vulnerability
     url: https://github.com/sudoantonio/welfaregraph/security/advisories/new
-    about: Usa una segnalazione privata per problemi di sicurezza.
+    about: Use a private report for security issues.

.github/ISSUE_TEMPLATE/research.yml

@@ -1,29 +1,29 @@
-name: Sviluppo metodologico
-description: Propone un'estensione di algoritmo, questionario o valutazione
+name: Methodological development
+description: Propose an extension to an algorithm, questionnaire, or evaluation
 title: "[Research]: "
 labels: [enhancement]
 body:
   - type: textarea
     id: question
     attributes:
-      label: Domanda di ricerca o esigenza
+      label: Research question or need
     validations:
       required: true
   - type: textarea
     id: method
     attributes:
-      label: Metodo proposto
+      label: Proposed method
     validations:
       required: true
   - type: textarea
     id: validation
     attributes:
-      label: Criteri di validazione
+      label: Validation criteria
     validations:
       required: true
   - type: textarea
     id: risks
     attributes:
-      label: Limiti, dati e supervisione umana
+      label: Limitations, data, and human oversight
     validations:
       required: false

CONTRIBUTING.md

@@ -1,10 +1,9 @@
-# Contribuire
+# Contributing
 
-1. Aprire una issue con il problema, l'artefatto coinvolto e il risultato atteso.
-2. Usare soltanto dati pubblici o campioni sintetici; non aggiungere dati personali.
-3. Accompagnare le modifiche agli algoritmi con test deterministici.
-4. Eseguire `pytest` prima di proporre la modifica.
-5. Documentare ogni modifica a questionari, prompt, fallback o criteri di associazione.
-
-Le modifiche metodologiche devono distinguere chiaramente comportamento implementato, ipotesi e sviluppo futuro.
+1. Open an issue describing the problem, the affected artifact, and the expected result.
+2. Use only public data or synthetic samples; do not add personal data.
+3. Accompany algorithm changes with deterministic tests.
+4. Run `pytest` before proposing a change.
+5. Document every change to questionnaires, prompts, fallbacks, or association criteria.
 
+Methodological changes must clearly distinguish implemented behavior, assumptions, and future work.

README.md

@@ -1,6 +1,5 @@
-# Sicurezza
+# Security
 
-Il progetto è un prototipo di ricerca. Segnalare vulnerabilità tramite una security advisory privata di GitHub, senza includere credenziali, documenti riservati o dati personali.
-
-Prima di un uso operativo sono necessari almeno: isolamento dei parser, scansione degli allegati, controllo degli URL, autenticazione, autorizzazioni per ruolo, gestione sicura dei segreti, limiti di richiesta, audit e politiche di conservazione.
+This project is a research prototype. Report vulnerabilities through a private GitHub security advisory, without including credentials, confidential documents, or personal data.
 
+Operational use requires, at minimum: parser isolation, attachment scanning, URL validation, authentication, role-based authorization, secure secret management, request limits, audit logging, and retention policies.

SECURITY.md

@@ -1,21 +1,20 @@
-# Corpus D1
+# D1 corpus
 
-Questa directory contiene 219 rappresentazioni testuali di bandi, avvisi e procedure raccolti da portali pubblici durante la sperimentazione della tesi.
+This directory contains 219 textual representations of calls, notices, and procedures collected from public portals during the thesis experiment.
 
-## Uso previsto
+## Intended use
 
-- riprodurre la costruzione del grafo D1;
-- calcolare e confrontare firme operative;
-- sviluppare test di classificazione ed estrazione;
-- costruire in futuro un sottoinsieme annotato da esperti.
+- reproduce construction of the D1 graph;
+- compute and compare operational signatures;
+- develop classification and extraction tests;
+- build a future expert-annotated subset.
 
-## Avvertenze
+## Cautions
 
-- I nomi dei file derivano dalle fonti e non costituiscono una tassonomia validata.
-- Il contenuto può essere obsoleto, incompleto o sostituito da versioni successive.
-- Per qualunque decisione amministrativa occorre consultare il portale e il documento ufficiale vigente.
-- La licenza del codice non modifica i diritti applicabili ai documenti di terzi.
-- Il corpus non contiene intenzionalmente dati individuali di beneficiari.
-
-Gli stati di acquisizione e gli URL delle fonti sono conservati in `tools/scraper/state/`.
+- Filenames come from the sources and do not constitute a validated taxonomy.
+- Content may be outdated, incomplete, or superseded by later versions.
+- Consult the current official portal and document before making any administrative decision.
+- The code license does not alter rights applicable to third-party documents.
+- The corpus intentionally contains no individual beneficiary data.
 
+Acquisition states and source URLs are stored in `tools/scraper/state/`.

data/corpus/README.md

@@ -1,10 +1,10 @@
-# Corpus minimo
+# Minimal corpus
 
-Quattro esempi ridotti per prove rapide della pipeline:
+Four reduced examples for quick pipeline tests:
 
-- microimpresa turistica;
-- PMI manifatturiera;
-- ente del Terzo Settore sociale;
-- cooperativa agricola.
+- tourism microenterprise;
+- manufacturing SME;
+- social third-sector entity;
+- agricultural cooperative.
 
-Questi campioni sono adatti allo sviluppo e non sostituiscono il corpus sperimentale completo.
+These samples support development and do not replace the complete experimental corpus.

data/mini/README.md

@@ -1,58 +1,58 @@
-# Architettura
+# Architecture
 
-## Componenti reali
+## Implemented components
 
-### Raccolta documentale
+### Document collection
 
-`tools/scraper/` contiene i parser per:
+`tools/scraper/` contains parsers for:
 
-- Ambito Territoriale di Mesagne, basato su WordPress;
-- Sistema Puglia, basato su Oracle APEX;
-- portale incentivi MIMIT;
-- catalogo bandi della Regione Puglia.
+- the Mesagne Territorial Area WordPress portal;
+- the Oracle APEX-based Sistema Puglia portal;
+- the MIMIT incentives portal;
+- the Regione Puglia call catalog.
 
-Lo scraper mantiene stato incrementale per fonte, limita i PDF a 50 MB, controlla il tipo di contenuto e separa download, selezione del documento ed estrazione testuale.
+The scraper maintains incremental state for each source, limits PDFs to 50 MB, validates content types, and separates downloading, document selection, and text extraction.
 
-### Modello e runtime DS4
+### Model and DS4 runtime
 
-Il prototipo usa DeepSeek V4 Flash servito localmente tramite [DS4 / DwarfStar](https://github.com/antirez/ds4), sviluppato da Salvatore Sanfilippo. Il confine applicativo è un endpoint OpenAI-compatible configurabile tramite variabili d'ambiente. DS4 è il runtime di inferenza; DeepSeek V4 Flash è il modello utilizzato.
+The prototype uses DeepSeek V4 Flash served locally through [DS4 / DwarfStar](https://github.com/antirez/ds4), developed by Salvatore Sanfilippo. The application boundary is an OpenAI-compatible endpoint configured through environment variables. DS4 is the inference runtime; DeepSeek V4 Flash is the model.
 
-### Dominio D1 e grafo G1
+### D1 domain and G1 graph
 
-Il questionario D1 definisce domande, risposte, metadata e grafo iniziale. Il loader valida unicità degli identificatori, coerenza domanda-risposta, radici e archi. `build_g1` estende il grafo quando due campioni non sono ancora distinguibili, preservando aciclicità e assenza di domande ripetute sul percorso.
+The D1 questionnaire defines questions, answers, metadata, and the initial graph. The loader validates identifier uniqueness, question-answer consistency, roots, and edges. `build_g1` extends the graph when two samples are not yet distinguishable, while preserving acyclicity and preventing repeated questions along a path.
 
-### Inferenza sul bando
+### Call inference
 
-`infer_g1` percorre il grafo per un documento e produce una `OperationalQASignature`. La firma include le coppie operative raggiunte e consente di confrontare o differenziare i bandi.
+`infer_g1` traverses the graph for one document and produces an `OperationalQASignature`. The signature contains the operational pairs reached and supports call comparison and differentiation.
 
-### Induzione trans-dominio
+### Cross-domain induction
 
-`build_induction_objects` e `associate_legal_subject` predispongono a livello prototipale domande D2, insiemi minimi di premesse e inferenza guidata verso G1. La sperimentazione non ha però completato il questionario semplificato degli enti né validato queste componenti su profili organizzativi reali.
+`build_induction_objects` and `associate_legal_subject` provide prototype D2 questions, minimal premise sets, and guided inference toward G1. The experiment has not yet completed the simplified entity questionnaire or validated these components on real organizational profiles.
 
-### Persistenza
+### Persistence
 
-`persistence.py` serializza domini, grafi, firme, sistemi di induzione e sessioni in JSON. La CLI usa checkpoint per riprendere elaborazioni lunghe senza ricominciare da zero.
+`persistence.py` serializes domains, graphs, signatures, induction systems, and sessions as JSON. The CLI uses checkpoints to resume long-running processes without starting over.
 
-## Corrispondenza Lean-Python
+## Lean-Python mapping
 
-| Specifica | Python |
+| Specification | Python |
 |---|---|
 | `SemanticDomain` | `domain.SemanticDomain` |
 | `QA` | `types.QA` |
 | `OperationalGraph` | `types.OperationalGraph` |
 | `OperationalQASignature` | `FrozenSet[OperationalQA]` |
 | `TransDomainRule` | `types.TransDomainRule` |
 | `TargetInductionObject` | `types.TargetInductionObject` |
-| costruzione G1 | `algorithms.build_g1` |
-| inferenza G1 | `algorithms.infer_g1` |
-| oggetti di induzione | `algorithms.build_induction_objects` |
-| inferenza guidata | `algorithms.associate_legal_subject` |
-
-## Confini di affidabilità
-
-- I documenti e le pagine web sono input non attendibili.
-- L'output LLM viene validato strutturalmente e ritentato, ma resta fallibile.
-- Alcuni errori del modello attivano fallback deterministici; i log devono renderli visibili.
-- Il risultato è compatibilità semantica rispetto alla configurazione, non ammissibilità giuridica.
-- Gli artefatti empirici disponibili riguardano D1; D2 e ranking restano una fase successiva.
-- Il prototipo non tratta dati individuali dei beneficiari.
+| G1 construction | `algorithms.build_g1` |
+| G1 inference | `algorithms.infer_g1` |
+| induction objects | `algorithms.build_induction_objects` |
+| guided inference | `algorithms.associate_legal_subject` |
+
+## Trust boundaries
+
+- Documents and web pages are untrusted inputs.
+- LLM output is structurally validated and retried, but remains fallible.
+- Some model errors trigger deterministic fallbacks; logs must make them visible.
+- The result expresses semantic compatibility under the configured rules, not legal eligibility.
+- Available empirical artifacts cover D1; D2 and ranking remain future work.
+- The prototype does not process individual beneficiary data.