diff --git a/README.md b/README.md index e0c25f714c..52aa730717 100644 --- a/README.md +++ b/README.md @@ -610,10 +610,18 @@ firecrawl research related-papers pmcid:PMC12530322 --intent "in vivo delivery" # Read full-text passages to verify a specific claim firecrawl research read-paper doi:10.1016/j.neunet.2025.108095 --question "What was the sample size?" + +# Curated location, function and GO terms for one protein, with cited paper ids +firecrawl research lookup-protein RPUSD3 + +# A gene symbol in another organism +firecrawl research lookup-protein Prkcb --organism "Mus musculus" ``` Paper ids accept `pmid:`, `pmcid:`, `doi:`, and `arxiv:` forms, plus canonical `paperId` values returned by search. +`lookup-protein` prints data from UniProtKB/Swiss-Prot, copyright [UniProt Consortium](https://www.uniprot.org), under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/). + #### Subcommands | Subcommand | Description | @@ -622,6 +630,7 @@ Paper ids accept `pmid:`, `pmcid:`, `doi:`, and `arxiv:` forms, plus canonical ` | `inspect-paper ` | Canonical metadata: title, abstract, authors, categories, source ids, dates | | `related-papers ` | Citation-graph expansion from seed papers, ranked against `--intent` | | `read-paper ` | Best-matching in-body full-text passages for a `--question` | +| `lookup-protein ` | Curated UniProt location, function and GO terms for one protein | #### `search-papers` Options diff --git a/src/__tests__/commands/research.test.ts b/src/__tests__/commands/research.test.ts index d432fcf9bd..7c61ff9c82 100644 --- a/src/__tests__/commands/research.test.ts +++ b/src/__tests__/commands/research.test.ts @@ -1,5 +1,8 @@ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'; -import { handleSearchPapersCommand } from '../../commands/research'; +import { + handleLookupProteinCommand, + handleSearchPapersCommand, +} from '../../commands/research'; import { getClient } from '../../utils/client'; import { initializeConfig } from '../../utils/config'; import { writeOutput } from '../../utils/output'; @@ -116,3 +119,288 @@ describe('handleSearchPapersCommand', () => { expectRenderedPapers(); }); }); + +describe('handleLookupProteinCommand', () => { + const found = { + success: true, + release: '2026_04', + match: 'found', + protein: { + accession: 'Q6P087', + entryName: 'RUSD3_HUMAN', + gene: 'RPUSD3', + synonyms: [], + name: 'Mitochondrial mRNA pseudouridine synthase RPUSD3', + organism: { + taxonId: 9606, + scientificName: 'Homo sapiens', + commonName: 'Human', + }, + matchedBy: 'gene', + url: 'https://www.uniprot.org/uniprotkb/Q6P087/entry', + subcellularLocation: [ + { + text: 'Mitochondrion matrix', + note: false, + evidence: [ + { + kind: 'experimental', + eco: 'ECO:0000269', + paperId: 'pmid:27974379', + }, + ], + }, + { + text: 'Localizes to mitochondrial RNA granules, platforms for post-transcriptional RNA modification and ribosome assembly', + note: true, + evidence: [ + { + kind: 'experimental', + eco: 'ECO:0000269', + paperId: 'pmid:27974379', + }, + { + kind: 'experimental', + eco: 'ECO:0000269', + paperId: 'pmid:28082677', + }, + ], + }, + ], + function: [ + { + text: 'Catalyzes uridine to pseudouridine isomerization (pseudouridylation) of specific mitochondrial mRNAs (mt-mRNAs), a post-transcriptional modification necessary for their translation. Acts at position 390 in COXI mt-mRNA and at position 697-699 in mitochondrial COXIII mt-mRNA (PubMed:27974379). As a component of a functional protein-RNA module, consisting of RCC1L, NGRN, RPUSD3, RPUSD4, TRUB2, FASTKD2 and 16S mitochondrial ribosomal RNA (16S mt-rRNA), controls 16S mt-rRNA abundance and may play a role in mitochondrial ribosome biogenesis (PubMed:27667664)', + note: false, + evidence: [ + { + kind: 'experimental', + eco: 'ECO:0000269', + paperId: 'pmid:27667664', + }, + { + kind: 'experimental', + eco: 'ECO:0000269', + paperId: 'pmid:27974379', + }, + ], + }, + ], + goCellularComponent: [ + { + id: 'GO:0005759', + term: 'mitochondrial matrix', + code: 'IDA', + assignedBy: 'FlyBase', + paperIds: ['pmid:27974379'], + }, + { + id: 'GO:0005739', + term: 'mitochondrion', + code: 'IDA', + assignedBy: 'FlyBase', + paperIds: ['pmid:28082677'], + }, + { + id: 'GO:0035770', + term: 'ribonucleoprotein granule', + code: 'IDA', + assignedBy: 'FlyBase', + paperIds: ['pmid:28082677'], + }, + ], + paperIds: ['pmid:27974379', 'pmid:28082677', 'pmid:27667664'], + }, + notice: + 'Protein data from UniProtKB/Swiss-Prot release 2026_04. Copyright UniProt Consortium, https://www.uniprot.org. CC BY 4.0, https://creativecommons.org/licenses/by/4.0/. No warranty, see https://www.uniprot.org/help/license. Selected fields, reformatted.', + }; + + beforeEach(() => { + setupTest(); + }); + + afterEach(() => { + teardownTest(); + vi.clearAllMocks(); + vi.unstubAllEnvs(); + vi.unstubAllGlobals(); + }); + + it('sends protein and organism and prints the found entry with an API key', async () => { + initializeConfig({ + apiKey: 'test-api-key', + apiUrl: 'https://api.firecrawl.dev', + }); + const mockHttpGet = vi.fn().mockResolvedValue({ data: found }); + vi.mocked(getClient).mockReturnValue({ + http: { get: mockHttpGet }, + } as any); + + await handleLookupProteinCommand({ + protein: 'RPUSD3', + organism: 'Homo sapiens', + }); + + expect(mockHttpGet).toHaveBeenCalledWith( + '/v2/search/research/proteins?protein=RPUSD3&organism=Homo+sapiens&integration=cli&origin=cli.test%401.0.0' + ); + expect(vi.mocked(writeOutput).mock.calls[0][0]).toBe( + [ + '# RPUSD3 (Q6P087, RUSD3_HUMAN), Homo sapiens', + 'Mitochondrial mRNA pseudouridine synthase RPUSD3. Matched by gene symbol.', + '', + 'Subcellular location', + '- Mitochondrion matrix. Experimental [pmid:27974379]', + '- Note: Localizes to mitochondrial RNA granules, platforms for post-transcriptional RNA modification and ribosome assembly. Experimental [pmid:27974379, pmid:28082677]', + 'GO cellular component (experimental)', + '- mitochondrial matrix (GO:0005759), IDA, FlyBase [pmid:27974379]', + '- mitochondrion (GO:0005739), IDA, FlyBase [pmid:28082677]', + '- ribonucleoprotein granule (GO:0035770), IDA, FlyBase [pmid:28082677]', + 'Function', + `- ${found.protein.function[0].text}. Experimental [pmid:27667664, pmid:27974379]`, + 'Open a cited paper with `firecrawl research inspect-paper ` or `firecrawl research read-paper --question `.', + `Source: https://www.uniprot.org/uniprotkb/Q6P087/entry. ${found.notice}`, + ].join('\n') + ); + }); + + it('lists candidates for an ambiguous protein without an API key', async () => { + vi.stubEnv('FIRECRAWL_API_KEY', ''); + initializeConfig({ apiUrl: 'https://api.firecrawl.dev' }); + const ambiguous = { + success: true, + release: '2026_04', + match: 'ambiguous', + candidates: [ + { + accession: 'P05771', + entryName: 'KPCB_HUMAN', + gene: 'PRKCB', + name: 'Protein kinase C beta type', + organism: { taxonId: 9606, scientificName: 'Homo sapiens' }, + matchedBy: 'name', + }, + ], + candidateCount: 12, + notice: found.notice, + }; + const fetchMock = vi.fn( + async (_url: string, _init?: RequestInit) => + new Response(JSON.stringify(ambiguous), { status: 200 }) + ); + vi.stubGlobal('fetch', fetchMock); + + await handleLookupProteinCommand({ protein: 'kinase' }); + + expect(getClient).not.toHaveBeenCalled(); + expect(fetchMock).toHaveBeenCalledWith( + 'https://api.firecrawl.dev/v2/search/research/proteins?protein=kinase&integration=cli&origin=cli.test%401.0.0', + expect.objectContaining({ method: 'GET' }) + ); + expect(vi.mocked(writeOutput).mock.calls[0][0]).toBe( + [ + '"kinase" does not resolve to one UniProtKB/Swiss-Prot entry in the requested organism (human unless --organism is set). 12 candidates, the first 1 listed, as accession, entry name, gene, name, organism:', + '- P05771, KPCB_HUMAN, PRKCB, Protein kinase C beta type, Homo sapiens', + 'Run `firecrawl research lookup-protein` again with one accession.', + found.notice, + ].join('\n') + ); + }); + + it('says what to pass and names search-papers when no entry matches', async () => { + initializeConfig({ + apiKey: 'test-api-key', + apiUrl: 'https://api.firecrawl.dev', + }); + vi.mocked(getClient).mockReturnValue({ + http: { + get: vi.fn().mockResolvedValue({ + data: { + success: true, + release: '2026_04', + match: 'not_found', + notice: found.notice, + }, + }), + }, + } as any); + + await handleLookupProteinCommand({ protein: 'where is RPUSD3 localized' }); + + expect(vi.mocked(writeOutput).mock.calls[0][0]).toBe( + 'No UniProtKB/Swiss-Prot entry matches "where is RPUSD3 localized". Pass a UniProt accession (P05771), an entry name (KPCB_HUMAN), or a gene symbol with --organism. Only reviewed entries are covered. For a free-text question, use `firecrawl research search-papers`.' + ); + }); + + it('fails on a body that is not a lookup result instead of saying no entry matches', async () => { + initializeConfig({ + apiKey: 'test-api-key', + apiUrl: 'https://api.firecrawl.dev', + }); + const consoleError = vi + .spyOn(console, 'error') + .mockImplementation(() => {}); + const exit = vi + .spyOn(process, 'exit') + .mockImplementation(() => undefined as never); + + for (const body of [ + { + success: true, + release: '2026_04', + match: 'partial', + notice: found.notice, + }, + {}, + ]) { + vi.mocked(getClient).mockReturnValue({ + http: { get: vi.fn().mockResolvedValue({ data: body }) }, + } as any); + + await handleLookupProteinCommand({ protein: 'RPUSD3' }); + } + + expect(consoleError.mock.calls).toEqual([ + [ + 'Error:', + 'The protein lookup returned an unexpected response (match: "partial").', + ], + [ + 'Error:', + 'The protein lookup returned an unexpected response (match: undefined).', + ], + ]); + expect(exit.mock.calls).toEqual([[1], [1]]); + expect(writeOutput).not.toHaveBeenCalled(); + }); + + it('prints the API error for a refused organism with an API key', async () => { + initializeConfig({ + apiKey: 'test-api-key', + apiUrl: 'https://api.firecrawl.dev', + }); + const error = + "unknown organism 'Martian': pass an NCBI taxon ID such as 9606, a scientific name such as Homo sapiens, or a UniProt common name such as Human"; + vi.mocked(getClient).mockReturnValue({ + http: { + get: vi.fn().mockRejectedValue({ + response: { status: 400, data: { success: false, error } }, + }), + }, + } as any); + const consoleError = vi + .spyOn(console, 'error') + .mockImplementation(() => {}); + const exit = vi + .spyOn(process, 'exit') + .mockImplementation(() => undefined as never); + + await handleLookupProteinCommand({ + protein: 'RPUSD3', + organism: 'Martian', + }); + + expect(consoleError).toHaveBeenCalledWith('Error:', error); + expect(exit).toHaveBeenCalledWith(1); + expect(writeOutput).not.toHaveBeenCalled(); + }); +}); diff --git a/src/commands/gov.ts b/src/commands/gov.ts index a483ee4241..adf776f5d8 100644 --- a/src/commands/gov.ts +++ b/src/commands/gov.ts @@ -1,4 +1,9 @@ -import { getClient, isKeylessMode, keylessGet } from '../utils/client'; +import { + getClient, + isKeylessMode, + keyedGet, + keylessGet, +} from '../utils/client'; import { getCliOrigin } from '../utils/agent-origin'; import { writeOutput } from '../utils/output'; import type { @@ -24,13 +29,7 @@ async function getGov(path: string, options: GovSearchOptions): Promise { } const app = getClient({ apiKey: options.apiKey, apiUrl: options.apiUrl }); - try { - const response = await (app as any).http.get(url); - return (response?.data ?? {}) as T; - } catch (error: any) { - const message = error?.response?.data?.error; - throw typeof message === 'string' ? new Error(message) : error; - } + return (await keyedGet(app, url)) as T; } function fmtResult(item: GovResult, index: number): string { diff --git a/src/commands/research.ts b/src/commands/research.ts index a84efb058a..41cba3e439 100644 --- a/src/commands/research.ts +++ b/src/commands/research.ts @@ -1,9 +1,21 @@ -import { getClient, isKeylessMode, keylessGet } from '../utils/client'; +import { + getClient, + isKeylessMode, + keyedGet, + keylessGet, +} from '../utils/client'; import { getCliOrigin } from '../utils/agent-origin'; import { writeOutput } from '../utils/output'; import type { + EvidenceKind, InspectPaperOptions, + LookupProteinOptions, PaperHit, + ProteinEntry, + ProteinEvidence, + ProteinLookup, + ProteinMatchedBy, + ProteinStatement, ReadPaperOptions, RelatedPapersOptions, ResearchBaseOptions, @@ -48,8 +60,7 @@ async function getResearch( } const app = getClient({ apiKey: options.apiKey, apiUrl: options.apiUrl }); - const response = await (app as any).http.get(url); - return (response?.data ?? {}) as T; + return (await keyedGet(app, url)) as T; } function displayId(paper: PaperHit): string { @@ -134,6 +145,131 @@ function fmtPaperMetadata(paper?: PaperHit): string { return lines.join('\n'); } +const EVIDENCE_LABELS: Record = { + experimental: 'Experimental', + large_scale_experimental: 'Experimental, large-scale', + author_statement: 'Author statement', + curator_inference: 'Curator inference', + by_similarity: 'Inferred from a related protein', + sequence_analysis: 'Predicted from sequence', + imported: 'Imported from another database', + untagged: 'No evidence tag', +}; + +const MATCHED_BY_LABELS: Record = { + accession: 'accession', + secondary_accession: 'secondary accession', + entry_name: 'entry name', + gene: 'gene symbol', + synonym: 'gene synonym', + name: 'protein name', +}; + +const isMeasured = (kind: EvidenceKind) => + kind === 'experimental' || kind === 'large_scale_experimental'; + +function measuredFirst(items: T[], measured: (item: T) => boolean): T[] { + return [ + ...items.filter(measured), + ...items.filter((item) => !measured(item)), + ]; +} + +const fmtIds = (ids: string[]) => (ids.length ? ` [${ids.join(', ')}]` : ''); + +function fmtEvidence(evidence: ProteinEvidence[]): string { + const idsByKind = new Map(); + for (const { kind, paperId, fromProtein } of evidence) { + const ids = idsByKind.get(kind) ?? []; + const id = paperId ?? fromProtein; + if (id && !ids.includes(id)) ids.push(id); + idsByKind.set(kind, ids); + } + return measuredFirst([...idsByKind], ([kind]) => isMeasured(kind)) + .map(([kind, ids]) => `${EVIDENCE_LABELS[kind] ?? kind}${fmtIds(ids)}`) + .join('; '); +} + +function fmtStatements(statements: ProteinStatement[]): string[] { + if (!statements.length) return ['- No statement in this entry.']; + return measuredFirst(statements, (statement) => + statement.evidence.some(({ kind }) => isMeasured(kind)) + ).map((statement) => { + const qualifiers = [ + statement.topology && `topology: ${statement.topology}`, + statement.orientation && `orientation: ${statement.orientation}`, + ] + .filter(Boolean) + .join('; '); + return [ + '- ', + statement.molecule ? `[molecule: ${statement.molecule}] ` : '', + statement.note ? 'Note: ' : '', + statement.text.replace(/\.$/, ''), + qualifiers ? ` (${qualifiers})` : '', + `. ${fmtEvidence(statement.evidence)}`, + ].join(''); + }); +} + +function fmtProtein(notice: string, protein: ProteinEntry): string { + const ids = protein.gene + ? `${protein.gene} (${protein.accession}, ${protein.entryName})` + : `${protein.accession} (${protein.entryName})`; + const lines = [ + `# ${ids}, ${protein.organism.scientificName}`, + `${protein.name}. Matched by ${MATCHED_BY_LABELS[protein.matchedBy] ?? protein.matchedBy}.`, + '', + 'Subcellular location', + ...fmtStatements(protein.subcellularLocation), + 'GO cellular component (experimental)', + ...(protein.goCellularComponent.length + ? protein.goCellularComponent.map( + (go) => + `- ${go.term} (${go.id}), ${go.code}, ${go.assignedBy}${fmtIds(go.paperIds)}` + ) + : ['- No experimental term in this entry.']), + 'Function', + ...fmtStatements(protein.function), + ]; + if (protein.paperIds.length) { + lines.push( + 'Open a cited paper with `firecrawl research inspect-paper ` or `firecrawl research read-paper --question `.' + ); + } + lines.push(`Source: ${protein.url}. ${notice}`); + return lines.join('\n'); +} + +function fmtProteinLookup(protein: string, data: ProteinLookup): string { + switch (data.match) { + case 'found': + return fmtProtein(data.notice, data.protein); + case 'ambiguous': { + const { candidates, candidateCount } = data; + const listed = + candidateCount > candidates.length + ? `${candidateCount} candidates, the first ${candidates.length} listed` + : `${candidateCount} ${candidateCount === 1 ? 'candidate' : 'candidates'}`; + return [ + `${JSON.stringify(protein)} does not resolve to one UniProtKB/Swiss-Prot entry in the requested organism (human unless --organism is set). ${listed}, as accession, entry name, gene, name, organism:`, + ...candidates.map( + (candidate) => + `- ${[candidate.accession, candidate.entryName, candidate.gene ?? '-', candidate.name, candidate.organism.scientificName].join(', ')}` + ), + 'Run `firecrawl research lookup-protein` again with one accession.', + data.notice, + ].join('\n'); + } + case 'not_found': + return `No UniProtKB/Swiss-Prot entry matches ${JSON.stringify(protein)}. Pass a UniProt accession (P05771), an entry name (KPCB_HUMAN), or a gene symbol with --organism. Only reviewed entries are covered. For a free-text question, use \`firecrawl research search-papers\`.`; + default: + throw new Error( + `The protein lookup returned an unexpected response (match: ${JSON.stringify((data as { match?: unknown }).match)}).` + ); + } +} + function writeResearchOutput( data: unknown, readable: string, @@ -251,3 +387,20 @@ export async function handleReadPaperCommand( handleError(error); } } + +export async function handleLookupProteinCommand( + options: LookupProteinOptions +): Promise { + try { + const params = new URLSearchParams(); + appendParam(params, 'protein', options.protein); + appendParam(params, 'organism', options.organism); + const data = await getResearch( + withQuery(`${BASE}/proteins`, params), + options + ); + writeResearchOutput(data, fmtProteinLookup(options.protein, data), options); + } catch (error) { + handleError(error); + } +} diff --git a/src/index.ts b/src/index.ts index 64fd32b03a..781013ddd8 100644 --- a/src/index.ts +++ b/src/index.ts @@ -39,6 +39,7 @@ import { handleDeveloperSearchCommand } from './commands/developer'; import { handleGovSearchCommand } from './commands/gov'; import { handleInspectPaperCommand, + handleLookupProteinCommand, handleReadPaperCommand, handleRelatedPapersCommand, handleSearchPapersCommand, @@ -1506,6 +1507,8 @@ Examples: $ firecrawl research related-papers pmcid:PMC12530322 --intent "in vivo delivery" $ firecrawl research read-paper doi:10.1016/j.neunet.2025.108095 --question "What was the sample size?" $ firecrawl research read-paper arxiv:1706.03762 --question "What is the attention mechanism?" + $ firecrawl research lookup-protein RPUSD3 + $ firecrawl research lookup-protein Prkcb --organism "Mus musculus" ` ); @@ -1697,6 +1700,39 @@ Examples: }); }); + researchCmd + .command('lookup-protein') + .description( + 'Look up one protein in UniProtKB/Swiss-Prot, the reviewed section of UniProt, and print what its curators state: subcellular location, function, and GO cellular-component terms. Each statement carries an evidence label and, where UniProt cites one, a pmid: paper ID that inspect-paper and read-paper accept. Only labels starting with "Experimental" are measurements. Not for free-text questions or lists of proteins; use search-papers for those. If a symbol names several proteins, the result lists candidates; run again with one accession.' + ) + .argument( + '', + 'One protein: a UniProt accession (P05771, or an isoform such as P05771-2), an entry name (KPCB_HUMAN), a gene symbol (PRKCB), or the exact protein name' + ) + .option( + '--organism ', + 'Organism that scopes a gene symbol or protein name: an NCBI taxon ID (10090), a scientific name (Mus musculus), or a UniProt common name (Mouse). Default: human (9606). Accessions and entry names ignore it.' + ) + .option( + '-k, --api-key ', + 'Firecrawl API key (overrides global --api-key)' + ) + .option('--api-url ', 'API URL (overrides global --api-url)') + .option('-o, --output ', 'Output file path (default: stdout)') + .option('--json', 'Output as compact JSON', false) + .option('--pretty', 'Pretty print JSON output', false) + .action(async (protein, options) => { + await handleLookupProteinCommand({ + protein, + organism: options.organism, + apiKey: options.apiKey, + apiUrl: options.apiUrl, + output: options.output, + json: options.json, + pretty: options.pretty, + }); + }); + researchCmd.addCommand( new Command('search-github') .helpOption(false) diff --git a/src/types/research.ts b/src/types/research.ts index 951191d0c1..4807aa6033 100644 --- a/src/types/research.ts +++ b/src/types/research.ts @@ -34,6 +34,85 @@ export interface ReadPaperOptions extends ResearchBaseOptions { k?: number; } +export interface LookupProteinOptions extends ResearchBaseOptions { + protein: string; + organism?: string; +} + +export type EvidenceKind = + | 'experimental' + | 'large_scale_experimental' + | 'author_statement' + | 'curator_inference' + | 'by_similarity' + | 'sequence_analysis' + | 'imported' + | 'untagged'; + +export type ProteinMatchedBy = + | 'accession' + | 'secondary_accession' + | 'entry_name' + | 'gene' + | 'synonym' + | 'name'; + +export interface ProteinEvidence { + kind: EvidenceKind; + eco?: string; + paperId?: string; + fromProtein?: string; +} + +export interface ProteinStatement { + text: string; + note: boolean; + molecule?: string; + topology?: string; + orientation?: string; + evidence: ProteinEvidence[]; +} + +export interface ProteinGoTerm { + id: string; + term: string; + code: string; + assignedBy: string; + paperIds: string[]; +} + +export interface ProteinCandidate { + accession: string; + entryName: string; + gene?: string; + name: string; + organism: { taxonId: number; scientificName: string; commonName?: string }; + matchedBy: ProteinMatchedBy; +} + +export interface ProteinEntry extends ProteinCandidate { + synonyms: string[]; + url: string; + subcellularLocation: ProteinStatement[]; + function: ProteinStatement[]; + goCellularComponent: ProteinGoTerm[]; + paperIds: string[]; +} + +export type ProteinLookup = { + success: true; + release: string; + notice: string; +} & ( + | { match: 'found'; protein: ProteinEntry } + | { + match: 'ambiguous'; + candidates: ProteinCandidate[]; + candidateCount: number; + } + | { match: 'not_found' } +); + export interface PaperHit { paperId?: string; primaryId?: string; diff --git a/src/utils/client.ts b/src/utils/client.ts index e01f5e4f1c..4cd0b2076a 100644 --- a/src/utils/client.ts +++ b/src/utils/client.ts @@ -89,6 +89,16 @@ export async function keylessGet(path: string): Promise { return json; } +export async function keyedGet(app: Firecrawl, path: string): Promise { + try { + const response = await (app as any).http.get(path); + return response?.data ?? {}; + } catch (error: any) { + const message = error?.response?.data?.error; + throw typeof message === 'string' ? new Error(message) : error; + } +} + /** * Get or create the Firecrawl client instance * Uses global configuration if available, otherwise creates with provided options