CLI di ricerca — OpenCaseLaw

Installazione

Python 3.10 o più recente. Installatelo da PyPI come strumento con pipx o uv; entrambi creano l’ambiente isolato richiesto dalle installazioni Python attuali. ocl doctor verifica connessione, server e client.

pipx install opencaselaw-cli        # or: uv tool install opencaselaw-cli
ocl --help

Senza pipx o uv, usate un ambiente virtuale: python3 -m venv .venv && .venv/bin/pip install opencaselaw-cli, poi eseguite .venv/bin/ocl. Aggiornamento con pipx upgrade opencaselaw-cli (o uv tool upgrade opencaselaw-cli).

1. Verificare le citazioni di una bozza

Mettete i riferimenti della bozza in un file, uno per riga, oppure come righe JSON quando un riferimento indica un considerando. Ognuno torna come resolved, missing o ambiguous con la decisione trovata; un considerando conta come resolved solo se esiste nell’indice.

cat > references.jsonl <<'JSONL'
{"reference":"BGE 136 III 513","pinpoint":"2.3"}
{"reference":"4A_747/2012"}
{"reference":"BGE 999 III 1"}
{"reference":"BGE 140 III 86","pinpoint":"2.3"}
JSONL
ocl citations resolve --input references.jsonl

Al terminale compare:

resolved              BGE 136 III 513  bge_BGE_136_III_513  E. 2.3 retrieved
resolved              4A_747/2012      bger_4A_747_2012     BGer 4A_747/2012 vom 5. April 2013
missing               BGE 999 III 1                         not in the corpus
pinpoint_unavailable  BGE 140 III 86   bge_BGE_140_III_86   E. 2.3 not in the index

partial: 2 resolved, 1 missing, 1 pinpoint_unavailable.
Existence and pinpoints only; no assessment of legal support.

Il codice di uscita è 4 perché non tutto è stato risolto. Ciò che la verifica non fa: non dice mai che una decisione sostiene la vostra tesi, che è ancora valida o che si adatta ai vostri fatti. Quella lettura spetta a voi.

2. Conservare le prove dietro un memo

Un comando esegue la ricerca e salva le decisioni selezionate, i considerandi e gli articoli di legge che indicate in una cartella: testi integrali come serviti, un INDEX.md leggibile e un manifest.json con ogni richiesta, marca temporale, link alla fonte e hash del file. I file salvati non vengono mai sovrascritti; --resume completa un’esecuzione interrotta.

ocl bundle create 'Rachekündigung Art. 336 OR' --max-results 10 --passage 2 \
  --law OR:336 --out rachekuendigung-2026-09

La cartella si legge senza alcuno strumento:

rachekuendigung-2026-09/
  INDEX.md                                    what was saved, in plain language
  manifest.json                               every request, timestamp, hash, source link
  decisions/bge_BGE_136_III_513-5b3e22ef.txt  full text as served (+ .json metadata)
  passages/bge_BGE_136_III_513_2-ff487655.txt E. 2, verbatim
  laws/OR_336-812a5382.json                   Art. 336 OR, consolidation date, Fedlex link
  search/page-0000-1850ce82.json              the search page the selection came from

Una raccolta è complete quando ogni elemento richiesto è stato salvato, altrimenti partial con ogni elemento mancato, per esempio una decisione cantonale senza considerandi numerati. Conserva ciò che il servizio ha restituito quel giorno; il corpus viene ricostruito ogni notte, e la stessa ricerca il mese dopo può selezionare altre decisioni.

Che cosa significano i risultati

resolved: la decisione esiste nel corpus. Con un considerando, quello indicato esiste e il suo testo è nella riga.
pinpoint_unavailable: la decisione esiste; il considerando numerato non è nell’indice strutturale. Per un sotto-considerando con lettera (consid. 2a, 3c/aa) viene fornito il numero superiore (parent_retrieved); cercarvi la lettera.
missing: nessuna decisione con quella citazione o quel numero di procedura. Una citazione errata o una lacuna di copertura, mai la prova che una citazione sia stata inventata.
ambiguous: più di una decisione porta quell’etichetta (i numeri di procedura si ripetono tra tribunali). Scegliete un decision_id.
unrecognized: la decisione proposta dal servizio non porta alcuna etichetta scritta nel riferimento; la proposta sta in service_candidate, mai in decision_id. resolution_incomplete, error: identità non stabilita o richiesta fallita. Nulla viene indovinato.
total_is_lower_bound: true significa «almeno tanti». Una ricerca testuale è ordinata su un insieme limitato di candidati; has_more: false non prova mai che ogni decisione rilevante sia stata vista.
Codici di uscita: 0 completo, 2 input non valido, 3 servizio o rete falliti, 4 parziale o non risolto (anche una decisione o un considerando che il servizio non ha). Gli script si diramano su di essi senza analizzare prosa.
discrepancy: la decisione è identificata, ma la data o il numero di procedura scritto accanto alla citazione DTF contraddice il record; discrepancies elenca ogni divergenza.

Ricette

Cercare, poi recuperare le decisioni complete, in un’unica pipeline:

ocl decisions search 'Rachekündigung Art. 336 OR' --max-results 5 --format jsonl |
  ocl decisions get --stdin --format jsonl > decisions.jsonl

Tutto ciò che un tribunale ha deciso in un periodo. Senza testo di ricerca i filtri enumerano un insieme esatto, pagina per pagina:

ocl decisions search --court bge --date-from 2026-01-01 --date-to 2026-06-30 \
  --sort date_desc --max-results 500 --format jsonl > bge-2026-h1.jsonl

Citare un considerando alla lettera, con la citazione che lo accompagna:

ocl decisions passage bge_BGE_136_III_513 2.3
ocl cite 'BGE 136 III 513' --pinpoint 2.3 --language fr

Una legge com’era in vigore a una data:

ocl laws get OR --article 41 --as-of 2015-01-01

Chi cita una decisione di principio:

ocl citations list bge_BGE_140_III_86 --direction incoming --limit 50

Gli agenti di codice come Claude Code o Codex eseguono gli stessi comandi da una shell e leggono il JSON; le prove restano in file che potete controllare, non nella memoria del modello.

Per gli agenti

Un agente ha bisogno di quattro cose: un’installazione senza domande, un output che possa analizzare, verdetti su cui diramarsi e regole che non possa aggirare. ocl fornisce tutte e quattro: JSON appena l’output va in una pipe; codici di uscita che portano il verdetto (0 tutto risolto, 2 input non valido, 3 servizio o rete, 4 qualcosa non si è risolto); --cache perché le ripetizioni entro una generazione della banca dati non costino nulla; e tre skill inclusi (controllo delle citazioni, ricerca, cartella delle prove). ocl tool call raggiunge ogni strumento di ricerca del servizio.

ocl agent-guide                  # the contract on one page: JSON, exit codes, statuses, rules
ocl skills install --claude      # citation-check, research, evidence-bundle into ~/.claude/skills
ocl tool list                    # every research tool of the service
ocl tool call find_leading_cases query='Rachekündigung Art. 336 OR' limit=5
ocl quotes check --input quotes.jsonl --format jsonl
ocl citations resolve --input refs.jsonl --format jsonl --cache ~/.cache/ocl

Le regole non si negoziano: le stringhe di citazione e le citazioni arrivano dal servizio così come sono; un close_match o un service_candidate è un’informazione per l’autore, mai un sostituto; lo strumento accerta esistenza e testo, non la portata giuridica. opencaselaw_cli.api offre lo stesso come libreria.

Dove si colloca

Conversazione: collegate Claude, ChatGPT o un altro client MCP a mcp.opencaselaw.ch (configurazione per client).
Script, notebook e agenti: ocl, oppure direttamente l’API REST. Stessi record, stessi limiti.
Analisi sull’intero corpus: il dataset Parquet.

Limiti

Una ricerca testuale è inviata come un’unica richiesta ordinata di al massimo 800 risultati; le ricerche con soli filtri sono paginate. Le ricerche ampie possono superare il timeout e vengono segnalate come errore, non come risultato vuoto. Le leggi cantonali si indicano come --law ZH/StG:1. Le richieste vanno al servizio ospitato e sono soggette all’informativa sulla privacy; --base-url indica un server gestito separatamente.

La guida completa con le sezioni di riferimento (ricerca e recupero, raccolte, risoluzione delle citazioni, contratto dell’API) è su GitHub: docs/research-cli.md.

Verificare le citazioni e conservare le prove dal terminale