pubmed-search-agent: Instructions file for Claude Code

PubMed NL Search Agent — CLAUDE.md

1. Obiettivo del progetto

Costruire un motore di ricerca che permetta di interrogare PubMed (via API E-utilities di NCBI) formulando query in linguaggio naturale, che vengono tradotte automaticamente nella sintassi di ricerca avanzata di PubMed (tag di campo, operatori booleani, filtri MeSH, date, ecc.), eseguite contro le API reali, e i cui risultati vengono poi filtrati per rilevanza semantica rispetto all'intento originale dell'utente — non per semplice matching di parole chiave.

Esempio di flusso:

Utente: "Trovami gli studi degli ultimi 3 anni su immunoterapia nel melanoma metastatico,
         solo trial clinici randomizzati, escludendo case report"
   ↓
Traduzione NL → query PubMed:
("melanoma"[MeSH Terms] OR "melanoma"[tiab]) AND
("immunotherapy"[MeSH Terms] OR "immunotherapy"[tiab]) AND
"metastatic"[tiab] AND
"randomized controlled trial"[pt] AND
("2023"[dp] : "2026"[dp])
NOT "case reports"[pt]
   ↓
Esecuzione su ESearch/EFetch (NCBI E-utilities, con api_key)
   ↓
Filtro di rilevanza semantica sui risultati (Claude)
   ↓
Output: elenco ordinato per pertinenza, con motivazione della rilevanza

2. Stato del progetto

• API key NCBI già generata (E-utilities, non Datasets API — parametro api_key, non api-key).
• Sviluppo previsto interamente in Claude Code (serve accesso di rete live verso eutils.ncbi.nlm.nih.gov per testare le chiamate reali, non disponibile in ambiente chat).
• Questo file è il documento guida iniziale: va raffinato in modalità di pianificazione (plan mode) mano a mano che l'architettura si consolida.

3. Architettura

pubmed-search-agent/
├── CLAUDE.md
├── .env
├── .env.example
├── pytest.ini
├── requirements.txt
├── docs/superpowers/
│   ├── specs/                 # design approvati in brainstorming
│   └── plans/                 # piani di implementazione
├── src/
│   ├── pubmed_errors.py       # gerarchia di eccezioni condivisa
│   ├── pubmed_models.py       # dataclass + parsing XML puro (nessuna rete)
│   ├── pubmed_client.py       # wrapper E-utilities, rate limiting, retry
│   ├── run_search.py          # entry-point CLI: query -> esearch/efetch -> JSON
│   ├── nl_query_translator.py # NL → sintassi PubMed
│   ├── mesh_resolver.py       # termini liberi → MeSH controllati
│   └── mcp_server.py          # tool MCP `search_pubmed_papers`
├── tests/
│   ├── test_pubmed_errors.py
│   ├── test_pubmed_models.py
│   ├── test_pubmed_client.py
│   ├── test_pubmed_live.py
│   ├── test_nl_query_translator.py
│   ├── test_run_search.py
│   ├── record_fixtures.py     # registra risposte NCBI reali
│   └── fixtures/              # XML NCBI salvati, senza api_key
└── examples/
    └── sample_queries.md