pubmed-search-agent
CLAUDE.md2 starsChanged 4 months agoMITView on GitHub
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: Principio guida: ogni modulo deve essere testabile in isolamento. pubmed_client.py…
- Reads credentials
1 other project uses a version of this.
Adopted by
Most recently taken up by
- Dariolex/pubmed-search-agentword for word, first seen Jul 27, 2026
Other versions1 project uses a version of this.
Word for word · 1
- Dariolex/pubmed-search-agent★ 2100% same
Edited · 0
None found.
Wrote their own version · 0
None found.
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repositoryOne other file it gives its agents.
- pubmed-searchSkill
The file
Files
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 rilevanza2. Stato del progetto
- API key NCBI già generata (E-utilities, non Datasets API — parametro
api_key, nonapi-key). - Sviluppo previsto interamente in Claude Code (serve accesso di rete live verso
eutils.ncbi.nlm.nih.govper 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.mdPrincipio guida: ogni modulo deve essere testabile in isolamento. pubmed_client.py non deve mai contenere logica di interpretazione NL; nl_query_translator.py non deve mai fare chiamate HTTP dirette a NCBI.
Il parsing XML vive in pubmed_models.py, che non ha alcuna dipendenza da rete ed è
testabile passandogli stringhe. pubmed_errors.py esiste in un modulo proprio perché
sia il parser sia il client devono sollevare eccezioni della stessa gerarchia, e
definirle nel client creerebbe un import circolare.
La skill /pubmed-search (.claude/skills/pubmed-search/SKILL.md) è l'interfaccia utente:
guida Claude nella fase 1 (estrazione NL → JSON intermedio) e nel filtro di rilevanza
inline, invocando nl_query_translator (fase 2, serializzazione deterministica) e
run_search (esecuzione). Nessuna API key oltre a quella NCBI.
4. API PubMed (NCBI E-utilities) — riferimento tecnico
Base URL: https://eutils.ncbi.nlm.nih.gov/entrez/eutils/
Parametri obbligatori su ogni chiamata:
tool— nome applicazione (stringa senza spazi)email— email di contattoapi_key— la chiave NCBI generata dall'utente
Endpoint principali usati dal progetto:
| Endpoint | Funzione | Note |
esearch.fcgi?db=pubmed&term=... | Esegue la query, restituisce PMID | Usare usehistory=y per query con molti risultati; supporta retmax, datetype, mindate/maxdate |
esummary.fcgi?db=pubmed&id=... | Metadati sintetici (titolo, autori, journal, data) | Fase successiva, non nel MVP: efetch restituisce già titolo, autori, journal e data insieme all'abstract |
efetch.fcgi?db=pubmed&id=...&rettype=abstract&retmode=xml | Abstract completo | Necessario per il filtro di rilevanza semantica |
elink.fcgi?dbfrom=pubmed&db=pubmed&id=...&linkname=... | Articoli correlati / citazioni | Implementato in related_search.py (PubMedClient.elink); linkname sempre esplicito (pubmed_pubmed o pubmed_pubmed_citedin), il PMID sorgente va sempre escluso dal risultato |
Rate limiting: 3 richieste/secondo senza api_key, 10 richieste/secondo con api_key valida. pubmed_client.py deve implementare un limitatore esplicito (es. token bucket) e gestire i retry su HTTP 429, non affidarsi solo alla libreria HTTP.
Attenzione — <ErrorList> non è un errore fatale. ESearch restituisce
<ErrorList><PhraseNotFound>…</PhraseNotFound></ErrorList> quando un termine non trova
corrispondenze, ma la ricerca è comunque riuscita: quei figli finiscono in
SearchResult.warnings e dicono quale termine non ha matchato. Solo l'elemento
<ERROR> indica un fallimento vero e produce un PubMedAPIError.
Attenzione — un errore può arrivare con HTTP 200. Una query malformata non produce un
400 ma un <ERROR> dentro XML valido con status 200. Controllare solo status_code
darebbe una lista vuota indistinguibile da «nessun match».
Sintassi di ricerca PubMed rilevante da generare in traduzione:
- Tag di campo:
[tiab](title/abstract),[MeSH Terms],[au](autore),[ta](rivista),[dp](data pubblicazione),[pt](tipo di pubblicazione, es."randomized controlled trial"[pt]),[la](lingua),[cois](conflict of interest statement) - Operatori booleani:
AND,OR,NOT(maiuscoli, obbligatori) - Intervalli di date:
("2023"[dp] : "2026"[dp]) - Esplosione MeSH automatica: PubMed la applica di default sui termini
[MeSH Terms]; non serve gestirla manualmente - Frasi esatte tra virgolette per evitare tokenizzazione indesiderata
- Brevetti: PubMed non li indicizza (nessun campo
[si]o subset dedicato, verificato dal vivo). L'unico proxy è il Conflict of Interest Statement:"patent*"[cois]. È testo libero, quindi cattura anche le dichiarazioni negative;Article.coi_statementespone il testo così che il filtro semantico possa scartarle.
5. Traduzione linguaggio naturale → query PubMed
Componente core (nl_query_translator.py). Approccio a due fasi:
- Estrazione strutturata — Claude analizza la query NL e produce un JSON intermedio con: concetti chiave, sinonimi/varianti, filtri (data, tipo di studio, lingua, età/popolazione), esclusioni esplicite, operatori logici impliciti tra i concetti.
- Serializzazione in sintassi PubMed — dal JSON intermedio si genera la stringa
term=finale, con tag di campo corretti e parentesi per la precedenza booleana.
Separare le due fasi permette di:
- testare la serializzazione senza dover richiamare Claude ogni volta (usando JSON fissi come fixture)
- validare/loggare il JSON intermedio per il debug quando la query risultante non produce i risultati attesi
- riusare
mesh_resolver.pyper mappare i concetti estratti a termini MeSH controllati quando possibile, invece di affidarsi solo a[tiab]
Nota importante: la traduzione va sempre mostrata all'utente insieme ai risultati (query PubMed generata + link diretto alla ricerca su pubmed.ncbi.nlm.nih.gov), così l'utente può verificare che l'interpretazione sia corretta e, se necessario, correggerla manualmente.
6. Filtro di rilevanza semantica
Il filtro di rilevanza vive inline nella skill /pubmed-search
(.claude/skills/pubmed-search/SKILL.md, fase 5), non in un modulo Python dedicato:
dopo aver recuperato PMID + abstract via run_search/related_search, Claude legge
titolo e abstract di ogni articolo insieme all'intento originale dell'utente e:
- scarta o declassa gli articoli non pertinenti, anche se hanno matchato la query booleana
- segnala eventuali falsi negativi (articoli che sembrano rilevanti ma che la query booleana potrebbe aver escluso, per una restrizione troppo aggressiva)
- quando il filtro brevetti è attivo, legge anche
coi_statementper scartare le dichiarazioni negative (vedi sezione 4, tag[cois])
Questo filtro è ciò che distingue il progetto da una semplice interfaccia a ESearch: la query booleana serve a restringere lo spazio di ricerca in modo efficiente, il filtro semantico serve a ordinare/scartare per pertinenza reale.
7. Setup ambiente
.env:
NCBI_API_KEY=...
NCBI_TOOL_NAME=pubmed-nl-search-agent
NCBI_EMAIL=...Nessuna chiave va mai committata o loggata in chiaro; pubmed_client.py deve leggerla solo da variabili d'ambiente.
8. Roadmap di sviluppo (MVP → oltre)
(completato)pubmed_errors.py+pubmed_models.py+pubmed_client.py— wrapper ESearch + EFetch con rate limiting e parsing tipizzato, testato offline su fixture reali e in modalità live(completato)nl_query_translator.py— traduzione NL → sintassi PubMed (solo[tiab]+ MeSH a giudizio di Claude), come modulo deterministico testabileIntegrazione end-to-end: query NL → query PubMed → PMID → abstract, tramite(completato)run_search.pye la skill/pubmed-searchFiltro di rilevanza: implementato inline nella skill(completato, inline)/pubmed-search(Claude legge gli abstract e ordina per pertinenza rispetto all'intento originale)(completato)mesh_resolver.py— risoluzione autoritativa verso il vocabolario MeSH controllato di NCBI (PubMedClient.resolve_mesh,db=mesh), invocata dalla skill/pubmed-searchprima della serializzazione(completato)mcp_server.py— esposizione come tool MCPsearch_pubmed_papers(FastMCP, transport stdio), tool a grana fine che prende una query in sintassi PubMed e restituisce gli articoli con abstract; riusarun_search.eseguie un'unica istanza diPubMedClient(rate limiter preservato). La traduzione NL e il filtro di rilevanza restano compito del modello client che chiama il tool.(completato)related_search.py— supporto aelink.fcgiper articoli correlati (pubmed_pubmed) e articoli che citano un PMID (pubmed_pubmed_citedin), invocato dalla skill a partire da un PMID noto.pubmed_pubmed_refs(riferimenti citati) escluso: dati assenti nella maggioranza dei casi testati dal vivo.
Configurazione del server MCP in Claude Desktop/Code
Aggiungere a claude_desktop_config.json:
{
"mcpServers": {
"pubmed-search": {
"command": "python",
"args": ["C:\\percorso\\assoluto\\src\\mcp_server.py"]
}
}
}Il .env (NCBI_API_KEY, NCBI_TOOL_NAME, NCBI_EMAIL) deve essere raggiungibile dal
processo, oppure le variabili vanno passate in un blocco "env" nella stessa config.
Nuova dipendenza: mcp[cli] (vedi requirements.txt).
9. Testing
- I test su
pubmed_client.pydevono poter girare sia in modalità "live" (vera chiamata a NCBI, marcata ed eseguita separatamente per non consumare rate limit nei test automatici) sia in modalità offline usando le fixture XML salvate intests/fixtures/. examples/sample_queries.mdraccoglie query NL reali con la query PubMed attesa e un giudizio manuale sui primi risultati: serve da suite di regressione qualitativa quando si modifica il prompt di traduzione.
I test live sono marcati @pytest.mark.live ed esclusi di default da pytest.ini
(addopts = -m "not live"): pytest gira interamente offline, pytest -m live esegue le
chiamate reali. Le fixture non si scrivono a mano — python tests/record_fixtures.py
registra risposte NCBI autentiche in tests/fixtures/, rimuovendo la api_key prima di
scrivere su disco.
10. Convenzioni di lavoro con Claude Code
- Ogni modifica architetturale rilevante va prima discussa in plan mode e poi riportata in questo file.
- Preferire commit piccoli e mirati per modulo (
pubmed_client, poinl_query_translator, ecc.) piuttosto che un'unica implementazione monolitica. - Le chiamate reali verso NCBI vanno sempre testate con query semplici prima di query complesse con molti operatori annidati.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

