diff --git a/README.en.md b/README.en.md index e548868..da58853 100644 --- a/README.en.md +++ b/README.en.md @@ -38,6 +38,11 @@ it stands on itself. ## How it works, in short +resh is an **analysis tool, not an agent**: you invoke it (CLI, library, or MCP server), it +computes, it returns a report — no conversational loop, no goal pursued on its own. The agentic +form (a system that evaluates and re-evaluates its own representations over time) is the +direction of the theoretical model, not a present capability. + resh looks at every text with **two independent instruments, on equal footing** — they are never merged into a single verdict: @@ -125,13 +130,17 @@ medium, ≥0.40 low, below that critical. **Components.** Each between 0 and 1, and **high is always good** — including the negatively-named ones: "Absence of fallacies" or "Absence of rhetorical bias" at 1.0 mean a -clean text. The *Genesis* section reorders components by erosion (how much each one lowers -ε) and attaches the pathologies causing it: start there to understand *why* ε is what it is. +clean text. "Absence of rhetorical bias" penalizes **absolutism** (boosters: "obviously", +"undoubtedly"), **not** hedging: "perhaps", "seems", "might" are fallibilism, and resh does not +count them as a defect — that would punish the very doubt it claims to serve. The *Genesis* +section reorders components by erosion (how much each one lowers ε) and attaches the pathologies +causing it: start there to understand *why* ε is what it is. **Pathologies.** Every finding carries `sev` (severity), `conf` (confidence) and the source that produced it (`regex`, `nli_zeroshot`, structural entailment...). Mind the `confermata` field: only pathologies confirmed by multiple independent signals are verdicts; the rest are -**candidates** — flags to check by eye, not convictions. +**candidates** — flags to check by eye, not convictions. A regex match, for example, becomes a +verdict only if NLI confirms the same fallacy in the same sentence. **Implicit-premise density.** How many undeclared premises per token. A descriptive metric (it does not enter ε): "low" on a long text is a good sign, not a flaw. @@ -156,7 +165,9 @@ its error: a report declaring 14 errors is an honest report, not a broken one. ## Open questions resh is an evolving project, and a tool that diagnoses hidden dogmas cannot afford to hide -its own: the deliberately provisional choices live here. +its own: the deliberately provisional choices live here. The full analysis of resh's known +biases — in the code and in the agent's self-coherence — together with the fixes applied is in +[`docs/analisi_bias.md`](docs/analisi_bias.md). - **The inventory of argumentative units is noisy.** Clause segmentation breaks up long periods — classical prose suffers more than contemporary writing — and fragments or @@ -164,9 +175,11 @@ its own: the deliberately provisional choices live here. every line shows the classifier's `conf`: below ~0.7, treat it as a weak flag. Under evaluation: collapsing units with no recognizable connectives into a count, keeping the detail in the JSON. -- **`struttura_argomentativa` is sensitive to period style.** On long-period texts the low - value is partly a segmentation artifact, not a defect of the text: read it together with - the other components, never alone. +- **`struttura_argomentativa` and `qualità_sintattica` are sensitive to period style.** On + long-period texts the low value is partly a segmentation artifact, and partly the effect of + stylistic optima tuned on a contemporary register — not a defect of the text: read them + together with the other components, never alone. Gulpease (an Italian readability formula) is + excluded from the score on EN texts; the optima still need recalibration on a gold set. - **LLM judgments can smuggle in an undeclared philosophical frame** — for instance reading an idealist by the yardstick of an implicit realism. Current mitigation: the deterministic pre-detect candidates must be adjudicated one by one, and rejecting one must be motivated @@ -225,6 +238,7 @@ resh/ ├── dataset/trilemma/, dataset/astratti/ annotated gold sets for calibration and eval ├── tests/ non-regression batteries and evals ├── examples/ sample texts and the real reports they produce +├── docs/analisi_bias.md bias analysis (code + self-coherence) and fixes └── curate_dataset.py manual run curation → dataset for future calibration ``` diff --git a/README.md b/README.md index 083d8f4..126e47c 100644 --- a/README.md +++ b/README.md @@ -39,6 +39,11 @@ cosa si regge lui. ## Come funziona, in breve +resh è uno **strumento di analisi, non un agente**: lo invochi (CLI, libreria o server MCP), +calcola, restituisce un report — nessun loop conversazionale, nessun obiettivo perseguito da +solo. La forma agentiva (un sistema che nel tempo valuta e ri-valuta le proprie +rappresentazioni) è la direzione del modello teorico, non una capacità presente. + resh guarda ogni testo con **due strumenti indipendenti, a pari dignità** — non si fondono mai in un unico verdetto: @@ -125,14 +130,18 @@ logici, premesse occultate, coerenza), **non la verità**: un testo falso può r vero può reggere male. Fasce indicative: ≥0.85 alta, ≥0.65 media, ≥0.40 bassa, sotto critica. **Componenti.** Ognuno tra 0 e 1, e **alto è sempre buono** — anche per i componenti nominati -in negativo: "Assenza fallacie" o "Assenza bias retorico" a 1.0 significano testo pulito. La -*Genesi* riordina i componenti per erosione (quanto ciascuno abbassa ε) e vi allega le -patologie che li causano: è il punto da cui partire per capire *perché* ε è quello che è. +in negativo: "Assenza fallacie" o "Assenza bias retorico" a 1.0 significano testo pulito. +«Assenza bias retorico» penalizza l'**assolutismo** (booster: «ovviamente», «indubbiamente»), +**non** l'hedging: «forse», «sembra», «potrebbe» sono fallibilismo, e resh non li conta come +difetto — sarebbe punire proprio il dubbio che dichiara di voler servire. La *Genesi* riordina +i componenti per erosione (quanto ciascuno abbassa ε) e vi allega le patologie che li causano: +è il punto da cui partire per capire *perché* ε è quello che è. **Patologie.** Ogni rilievo porta `sev` (gravità) e `conf` (fiducia) e la fonte che l'ha prodotto (`regex`, `nli_zeroshot`, `entailment strutturale`...). Attenzione al campo `confermata`: solo le patologie confermate da più segnali indipendenti sono verdetti; le -altre sono **candidate** — segnalazioni da verificare a occhio, non condanne. +altre sono **candidate** — segnalazioni da verificare a occhio, non condanne. Un match regex, +per esempio, diventa verdetto solo se l'NLI conferma la stessa fallacia nella stessa frase. **Densità premesse implicite.** Quante premesse non dichiarate per token. Metrica descrittiva (non entra in ε): "bassa" per un testo lungo è un buon segno, non un difetto. @@ -157,6 +166,8 @@ l'errore: un report con 14 errori dichiarati è un report onesto, non un report resh è un progetto in evoluzione, e un tool che diagnostica dogmi nascosti non può permettersi di nasconderne di propri: le scelte dichiaratamente provvisorie stanno qui. +L'analisi completa dei bias noti — nel codice e nell'auto-coerenza dell'agente con se stesso — +con le correzioni applicate è in [`docs/analisi_bias.md`](docs/analisi_bias.md). - **L'inventario delle unità argomentative è rumoroso.** La segmentazione in clausole spezza i periodi lunghi — la prosa classica ne soffre più di quella contemporanea — e frammenti o @@ -164,9 +175,11 @@ permettersi di nasconderne di propri: le scelte dichiaratamente provvisorie stan riga mostra la `conf` del classificatore: sotto ~0.7 va presa come segnalazione debole. In valutazione: compattare le unità senza connettivi riconosciuti in un conteggio, lasciando il dettaglio nel JSON. -- **`struttura_argomentativa` risente dello stile d'epoca.** Su testi a periodi lunghi il - valore basso è in parte un artefatto della segmentazione, non un difetto del testo: va - letto insieme agli altri componenti, non da solo. +- **`struttura_argomentativa` e `qualità_sintattica` risentono dello stile d'epoca.** Su testi + a periodi lunghi il valore basso è in parte un artefatto della segmentazione e di ottimi + stilistici tarati su un registro contemporaneo, non un difetto del testo: vanno letti insieme + agli altri componenti, non da soli. Il Gulpease (formula di leggibilità italiana) è escluso + dal punteggio sui testi EN; gli ottimi restano da ricalibrare su un gold set. - **I giudizi LLM possono importare un quadro filosofico non dichiarato** — per esempio leggere un idealista dal metro di un realismo implicito. Mitigazione attuale: i candidati del pre-detect deterministico vanno giudicati uno per uno e il rigetto va motivato con @@ -225,6 +238,7 @@ resh/ ├── dataset/trilemma/, dataset/astratti/ gold set annotati per calibrazione ed eval ├── tests/ batterie di non-regressione ed eval ├── examples/ testi ed esempi di report reali +├── docs/analisi_bias.md analisi dei bias (codice + auto-coerenza) e correzioni └── curate_dataset.py curazione manuale run → dataset per calibrazione futura ```