Merge pull request #54 from ondata/feat/speeches-date-filter

feat(speeches): filtro --date-from/--date-to + colonna date (#37)

Author: aborruso

LOG.md

@@ -2,6 +2,8 @@
 
 ## 2026-07-11
 
+- **feat `speeches` — filtro `--date-from`/`--date-to` + colonna `date`** (#37, branch `feat/speeches-date-filter`). Prima gli interventi non erano filtrabili né datati nell'output. **Camera**: la data reale non è sull'intervento (`ods:modified` è il timestamp del record) ma sulla `ocd:discussione` che lo raggruppa (`dc:date` plain `AAAAMMGG`); verificato che copre sia Aula (stenografico, `sezione=assemblea`) sia commissione (bollettino), cardinalità 1 per intervento. Il join+`FILTER` sulle date va dentro la subquery-first (il filtro precede il `LIMIT`); performante solo col range filter sul soggetto → il filtro data richiede `legislature` (0.5s con, degrada senza). **Senato**: `osr:dataSeduta` (xsd:date ISO) già disponibile, filtro con `STR(?ds)` (regge sia xsd:date sia xsd:string). Colonna `date` (YYYY-MM-DD) ora su entrambe le camere — rinominata da `session_date` per parità (nessun consumer esterno). CLI (`--date-from/--date-to`), MCP, skill (tools.md + commands.md) e wiki (`camera/interventi-data.md` nuova) allineati. +2 test (Camera e Senato), 139/139 verdi, tsc pulito.
+
 - **v0.24.2** — release patch. Raccoglie i fix e i miglioramenti mergiati dopo la 0.24.1 (137/137 test verdi, tsc pulito, **43 tool** invariati): (1) **fix CLI emptyHint** (#49) — l'`emptyHint` statico dei tool ora arriva anche via CLI (prima cablato solo in `formatResult`/MCP), così i vuoti "legittimi" (es. gap COVID leg.18) hanno la spiegazione anche a riga di comando; via OpenSpec + `withEmptyHint`. (2) **anti-refuso `bill_number` blindato** (#52) — test di regressione sul Piano Casa (label "DDL n. 1994" → `bill_number` 1944, dal backfill `osr:fase`) e wiki `fiducia-fallback` allineata. (3) **`senato-vote-detail` — dettaglio per tipo di voto** (#53) — verificato che il dettaglio nominativo c'è per tutte le modalità; la scelta espressa (Favorevole/Contrario/Astenuto) manca solo su `segreta` e `verifica numero legale` (solo presenze). Description del tool, wiki `votazione-tipo-semantico` e skill aggiornate; segnale `roll_call_available` derivabile da `type`, niente campo nuovo. (4) **ricetta sede question time `aic`** — la sede (Aula/commissione) è già filtrabile via `--type "immediata in assemblea"/"in commissione"` (match sul label regolare), documentata in description/esempio + skill. (5) **fix agente** news-driven-cli-gap-analyzer che si auto-delegava (#50). Nessuna nuova capacità utente → patch.
 
 ## 2026-07-10

docs/lod-wiki/camera/index.md

@@ -6,6 +6,7 @@ Endpoint SPARQL: `https://dati.camera.it/sparql`. Ontologia OCD (namespace `http
 
 * [Sedute e attività delle commissioni](sedute-commissione.md) - `ocd:seduta` per organo e per data; proprietà reali (`dc:date` stringa `AAAAMMGG`, `ocd:rif_organo`, `ocd:rif_leg`) e filtro legislatura obbligatorio.
 * [Composizione delle commissioni](composizione-commissione.md) - chi ne fa parte con ruolo e date; due path RDF da unire (`ocd:membro` + `ocd:ufficioParlamentare`), trappola bicamerale sui presidenti senatori (`ocd:rif_senatore`).
+* [Data di un intervento in aula](interventi-data.md) - l'intervento non porta la data (`ods:modified` è il timestamp del record); il giorno reale è su `dc:date` della `ocd:discussione` che lo raggruppa (`AAAAMMGG`), verificato per Aula e commissione. Filtro data performante solo con range filter sul soggetto (legislatura obbligatoria).
 * [Date degli atti di sindacato ispettivo (aic)](aic-date.md) - `dc:date` è presentazione (a volte composta `pres-modifica`), `ocd:endDate` è conclusione/trattazione; la seduta NON è un link strutturato (numero solo in `dc:description`). Trappola question time.
 * [Iter di un atto — timeline degli stati](iter-statoIter.md) - la cronologia dell'iter è una timeline via `ocd:rif_statoIter` (uno stato per fase, `dc:date`+`dc:title`); copertura alla pari tra legislature (18 = 19). Il ramo Senato dà per design solo lo stato corrente (timeline nel feed RSS), asimmetria di ramo non di legislatura.
 * [Firmatari di decreti-legge e atti governativi](firmatari-atti-governativi.md) - sugli atti del Governo `ocd:primo_firmatario` punta a un blank node "membro di governo", non a un deputato: il nome del ministro è via `ocd:rif_persona`, il dicastero in `ocd:ruolo`. Senza seguirli il nome torna vuoto.

docs/lod-wiki/camera/interventi-data.md

@@ -0,0 +1,17 @@
+# Data di un intervento in aula (Camera)
+
+L'intervento (`ocd:intervento`) **non porta la propria data**: l'unica proprietà temporale sull'istanza è `ods:modified`, che è il timestamp di modifica del record, non il giorno in cui l'intervento è stato pronunciato. La data reale vive sulla `ocd:discussione` che raggruppa l'intervento: la discussione lo referenzia con `ocd:rif_intervento` e porta `dc:date`.
+
+```sparql
+PREFIX ocd: <http://dati.camera.it/ocd/>
+PREFIX dc: <http://purl.org/dc/elements/1.1/>
+SELECT ?date WHERE {
+  ?disc ocd:rif_intervento <http://dati.camera.it/ocd/intervento.rdf/in19_824755> ; dc:date ?date .
+}
+```
+
+`dc:date` è una stringa `AAAAMMGG` (es. `20260617`), confrontabile lessicograficamente per un filtro a intervallo. Come per gli altri campi data della Camera (`votes`, `sessions`, `aic`), il confronto va forzato con `STR(?date)`: su Virtuoso Camera i range su `dc:date` senza `STR()` rischiano un confronto numerico spurio e vuoti muti. La copertura è verificata su **entrambe** le sedi: interventi d'Aula (documento stenografico, `dc:relation` con `sezione=assemblea`) e interventi di commissione (bollettino, `sezione=bollettini`) hanno tutti la discussione con `dc:date`, con cardinalità 1 per intervento.
+
+## Filtrare per data in modo performante
+
+Gli interventi Camera non hanno `ocd:rif_leg`: la legislatura è solo nel pattern URI (`in<leg>_<id>`). Un filtro data va perciò abbinato al range filter sul soggetto (`FILTER(?s >= <…in19_> && ?s < <…in19_z>)`), che àncora l'indice Virtuoso; il join sulla discussione con il `FILTER` sulle date va **dentro** la subquery che seleziona/ordina/limita i soli `?s`, così il filtro precede il `LIMIT`. Senza il vincolo di legislatura la query perde l'àncora ed è molto più lenta. Questo è esattamente ciò che fa il tool `speeches` con `--date-from`/`--date-to`.

skills/italian-parliament-cli/references/commands.md

@@ -112,10 +112,13 @@ italianparliament vote-detail show --vote-uri <vote-uri> --format csv
 ```
 
 ### `speeches list`
-Interventi in aula (disponibili da leg. 17).
+Interventi in aula, Camera e Senato (`--chamber`; dati Camera da leg. 17). Colonna `date` (YYYY-MM-DD) in output.
 ```bash
 italianparliament speeches list --legislature 19
+italianparliament speeches list --legislature 19 --date-from 2026-06-17 --date-to 2026-06-17
+italianparliament speeches list --chamber senato --legislature 19 --date-from 2025-03-01 --date-to 2025-03-31
 ```
+`--date-from`/`--date-to` filtrano per la **data della seduta**. Camera: la data non è sull'intervento (`ods:modified` è il timestamp del record) ma sulla `ocd:discussione` che lo raggruppa — il tool la ricava. Per la Camera il filtro data richiede `--legislature` (àncora l'indice; senza è molto più lento).
 
 ### `attendance show`
 Conteggio aggregato dei voti di un deputato su tutte le votazioni della sua legislatura (favorevole/contrario/astensione/non ha votato/ha votato in scrutinio segreto) — misura di attivismo/assenteismo.

skills/italian-parliament-mcp/references/tools.md

@@ -84,9 +84,12 @@ Come ha votato ogni deputato in una votazione.
 - `voteType`: Favorevole | Contrario | Astenuto | Non ha votato
 
 ### `speeches`
-Interventi in aula Camera.
-- `legislature`: numero legislatura (nota: dati disponibili da leg. 17)
-- `deputyUri`: filtra per deputato
+Interventi in aula, Camera **e** Senato (`chamber`).
+- `chamber`: `camera` (default) o `senato`
+- `legislature`: numero legislatura (nota: dati Camera disponibili da leg. 17)
+- `deputyUri`: filtra per parlamentare
+- `dateFrom` / `dateTo` (YYYY-MM-DD): filtra per **data della seduta** dell'intervento. Camera: la data non è sull'intervento (`ods:modified` è il timestamp del record) ma sulla `ocd:discussione` che lo raggruppa — il tool la ricava per te. Per la Camera il filtro data richiede `legislature` (àncora l'indice; senza è molto più lento).
+- Colonna `date` (YYYY-MM-DD) in output per entrambe le camere.
 
 ### `attendance`
 Conteggio aggregato dei voti di un deputato su tutte le votazioni della sua legislatura (misura di attivismo/assenteismo). L'URI del deputato è già specifico di una legislatura (`.../deputato.rdf/d<ID>_<LEG>`), quindi il conteggio è già delimitato senza filtro separato.

src/cli.ts

@@ -47,6 +47,7 @@ import { CAPABILITIES, capabilityScore } from "./core/capabilities.js";
 import { formatRows, type Format } from "./core/format.js";
 import { SparqlError } from "./core/client.js";
 import { ZodError } from "zod";
+import { formatZodError } from "./core/zod-error.js";
 import type { ToolResult } from "./tools/types.js";
 import { withEmptyHint } from "./core/empty-hint.js";
 import { createRequire } from "module";
@@ -84,13 +85,7 @@ async function runTool(tool: { inputSchema: { parse(i: unknown): any }; execute(
     parsed = tool.inputSchema.parse(input);
   } catch (e) {
     if (e instanceof ZodError) {
-      const msgs = e.issues.map((i) => {
-        const field = i.path.join(".") || "input";
-        return i.code === "invalid_enum_value"
-          ? `--${field}: valore non valido "${(i as { received?: string }).received ?? ""}". Ammessi: ${i.options.join(" | ")}.`
-          : `--${field}: ${i.message}`;
-      });
-      throw new Error(msgs.join("\n"));
+      throw new Error(formatZodError(e, true));
     }
     throw e;
   }
@@ -644,6 +639,8 @@ const speechesList = defineCommand({
       type: "string",
       description: "Full URI of a deputy/senator",
     },
+    "date-from": { type: "string", description: "Start date YYYY-MM-DD (session date)" },
+    "date-to": { type: "string", description: "End date YYYY-MM-DD (session date)" },
     "count-only": {
       type: "boolean",
       description: "Return only the total count",
@@ -658,6 +655,8 @@ const speechesList = defineCommand({
       chamber,
       legislature: parseIntFlag(args.legislature as string, "legislature"),
       deputyUri: (args["deputy-uri"] as string) || undefined,
+      dateFrom: (args["date-from"] as string) || undefined,
+      dateTo: (args["date-to"] as string) || undefined,
       countOnly: Boolean(args["count-only"]),
       limit: parseIntFlag(args.limit as string, "limit") ?? 100,
       offset: Number(args.offset ?? 0),
@@ -1861,14 +1860,7 @@ if (argv[0] === "sparql" && argv[1] !== "query" && argv[1] !== "--help" && argv[
 runMain(main).catch((err: unknown) => {
   if (err instanceof ZodError) {
     // Errori di validazione input: per gli enum, elenca i valori validi.
-    const msgs = err.issues.map((i) => {
-      const field = i.path.join(".") || "input";
-      if (i.code === "invalid_enum_value") {
-        return `--${field}: valore non valido. Ammessi: ${i.options.join(" | ")}.`;
-      }
-      return `--${field}: ${i.message}`;
-    });
-    process.stderr.write(`Error: ${msgs.join("\n")}\n`);
+    process.stderr.write(`Error: ${formatZodError(err, true)}\n`);
   } else if (err instanceof SparqlError) {
     process.stderr.write(
       `Error: ${err.message}\nEndpoint: ${err.endpoint}\n${err.status ? `Status: ${err.status}\n` : ""}`,

src/core/zod-error.test.ts

@@ -0,0 +1,33 @@
+import { describe, it, expect } from "vitest";
+import { z } from "zod";
+import { ZodError } from "zod";
+import { formatZodError } from "./zod-error.js";
+
+function zodErrorFrom(schema: z.ZodTypeAny, input: unknown): ZodError {
+  const r = schema.safeParse(input);
+  if (r.success) throw new Error("atteso fallimento di parsing");
+  return r.error;
+}
+
+describe("formatZodError", () => {
+  it("enum: elenca i valori ammessi e il valore ricevuto", () => {
+    const schema = z.object({ voteType: z.enum(["finale", "emendamento"]) });
+    const msg = formatZodError(zodErrorFrom(schema, { voteType: "x" }));
+    expect(msg).toContain("voteType:");
+    expect(msg).toContain('"finale" | "emendamento"');
+    expect(msg).toContain('"x"');
+  });
+
+  it("flagStyle rende il flag CLI reale (-- + kebab-case), MCP lascia il nome schema nudo", () => {
+    const schema = z.object({ dateFrom: z.string().regex(/^\d{4}-\d{2}-\d{2}$/) });
+    const err = zodErrorFrom(schema, { dateFrom: "pippo" });
+    expect(formatZodError(err, true)).toMatch(/^--date-from:/);
+    expect(formatZodError(err)).toMatch(/^dateFrom:/);
+  });
+
+  it("una riga per issue", () => {
+    const schema = z.object({ a: z.string(), b: z.number() });
+    const msg = formatZodError(zodErrorFrom(schema, { a: 1, b: "x" }));
+    expect(msg.split("\n").length).toBe(2);
+  });
+});

src/core/zod-error.ts

@@ -0,0 +1,32 @@
+import { ZodError } from "zod";
+
+// Formatta un ZodError in un messaggio compatto, una riga per campo, con i
+// valori ammessi per gli enum. Condiviso tra CLI e path MCP (server.ts) così
+// un input non valido produce lo stesso errore leggibile invece della stringa
+// JSON lunga di default di Zod. flagStyle=true antepone "--" al nome del campo
+// (stile flag CLI); false lascia il nome del parametro nudo (MCP).
+export function formatZodError(e: ZodError, flagStyle = false): string {
+  // flagStyle: rende il campo come il flag CLI reale — "--" + kebab-case
+  // (dateFrom -> --date-from, voteType -> --vote-type), così l'errore non
+  // suggerisce un flag camelCase inesistente. MCP usa il nome nudo dello schema.
+  const label = (field: string) =>
+    flagStyle ? `--${field.replace(/([A-Z])/g, "-$1").toLowerCase()}` : field;
+  const safeJson = (value: unknown) => {
+    try {
+      return JSON.stringify(value) ?? "undefined";
+    } catch {
+      return String(value);
+    }
+  };
+  return e.issues
+    .map((i) => {
+      const field = i.path.join(".") || "input";
+      if (i.code === "invalid_enum_value") {
+        const received = safeJson(i.received);
+        const allowed = i.options.map((v) => safeJson(v)).join(" | ");
+        return `${label(field)}: valore non valido ${received}. Ammessi: ${allowed}.`;
+      }
+      return `${label(field)}: ${i.message}`;
+    })
+    .join("\n");
+}

src/server.ts

@@ -45,6 +45,8 @@ import { senatoAttendanceTool } from "./tools/senato-attendance.js";
 import type { Tool, ToolResult } from "./tools/types.js";
 import { toJsonl } from "./core/format.js";
 import { SparqlError } from "./core/client.js";
+import { ZodError } from "zod";
+import { formatZodError } from "./core/zod-error.js";
 
 function describe(tool: Tool): string {
   return `${tool.description}\n\nExamples:\n${tool.examples
@@ -63,20 +65,27 @@ function formatResult(result: ToolResult, emptyHint?: string): string {
 function makeHandler(tool: Tool) {
   return async (input: unknown) => {
     try {
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      const result = await tool.execute(input as any);
+      // Valida l'input con lo schema Zod prima di eseguire, come fa la CLI
+      // (cli.ts). Le regex/limiti dello schema (es. il formato data YYYY-MM-DD
+      // di speeches) non devono dipendere dal solo dispatch dell'SDK: parseare
+      // qui è il chokepoint unico che protegge tutti i tool da input non
+      // conformi che finirebbero interpolati nelle query SPARQL.
+      const parsed = tool.inputSchema.parse(input);
+      const result = await tool.execute(parsed);
       return {
         content: [
           { type: "text" as const, text: formatResult(result, tool.emptyHint) },
         ],
       };
     } catch (err) {
       const message =
-        err instanceof SparqlError
-          ? `SPARQL error on ${err.endpoint}${err.status ? ` (HTTP ${err.status})` : ""}: ${err.message}`
-          : err instanceof Error
-            ? err.message
-            : String(err);
+        err instanceof ZodError
+          ? formatZodError(err)
+          : err instanceof SparqlError
+            ? `SPARQL error on ${err.endpoint}${err.status ? ` (HTTP ${err.status})` : ""}: ${err.message}`
+            : err instanceof Error
+              ? err.message
+              : String(err);
       return {
         content: [{ type: "text" as const, text: `Error: ${message}` }],
         isError: true,