@biolibs/bionet-agent 0.1.4 → 0.1.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/src/index.ts CHANGED
@@ -8,7 +8,9 @@
8
8
  * merges the lab's logs holds it to that.
9
9
  *
10
10
  * - `tools.ts` — what an adviser is given: the lab to read, the engines, and three things to write
11
- * - `lookup.ts` — the two that reach outside it, to NCBI's public databases
11
+ * - `lookup.ts` — the ones that reach outside it, to NCBI's public databases
12
+ * - `papers.ts` — the ones that read the literature, at Europe PMC
13
+ * - `known.ts` — and the ones that say what is known about a protein, at UniProt
12
14
  * - `serve.ts` — those tools served over the Model Context Protocol, on this machine only
13
15
  *
14
16
  * The device that hosts the adviser keeps its key (`hostAdviser` in `@biolibs/bionet-client`), and
@@ -17,4 +19,6 @@
17
19
  */
18
20
  export * from "./tools.js";
19
21
  export * from "./lookup.js";
22
+ export * from "./papers.js";
23
+ export * from "./known.js";
20
24
  export * from "./serve.js";
package/src/known.ts ADDED
@@ -0,0 +1,241 @@
1
+ /**
2
+ * What is known about a protein, and what would be done to it: UniProt, and the motif rules.
3
+ *
4
+ * These two belong together because neither is worth much alone, and together they answer the
5
+ * question a project like making casein in yeast actually turns on.
6
+ *
7
+ * UniProt alone gives a record: here are the five phosphoserines somebody read out of a paper.
8
+ * That is true of the cow's protein and says nothing about a variant, or about a gene that has
9
+ * been rewritten in another host's codons. The motif rules alone give a prediction, and a
10
+ * prediction over a few residues is a thing to be sceptical of. Put together, the comparison is
11
+ * the useful object: the rule reproduces the record on the protein somebody has studied, so it can
12
+ * be believed on the one nobody has.
13
+ *
14
+ * The other thing these answer is the one a lab finds out too late. A host will happily make a
15
+ * protein of the right mass that is the wrong thing, because the modification that makes it work is
16
+ * put on by an enzyme the host does not have. An adviser that can say that before the month is
17
+ * spent is worth more than one that can design the construct.
18
+ */
19
+ import { UniProtError, lookUpProtein, onTheChain, readProtein, searchProteins, settings,
20
+ type Protein } from "@biolibs/uniprot";
21
+ import { HOST_KINASES, PHOSPHO_MOTIFS, comparedWithKnown, hostPhosphorylation, phosphoSites, phosphoWorking } from "@biolibs/bionet-tools";
22
+ import type { AgentTool } from "./tools.js";
23
+
24
+ /** The most results one protein search gives back. */
25
+ export const MOST_PROTEINS = 25;
26
+
27
+ /** How an adviser reaches UniProt. */
28
+ export interface KnownOptions {
29
+ /** Whether to offer these tools at all. On unless a host says otherwise. */
30
+ known?: boolean;
31
+ /** What to call this software to UniProt. Never a person's name. */
32
+ tool?: string;
33
+ /** An address UniProt could use about heavy use, if somebody has set one on purpose. */
34
+ email?: string | null;
35
+ }
36
+
37
+ const text = (value: unknown, what: string): string => {
38
+ if (typeof value !== "string" || value.trim() === "") throw new Error(`${what} has to be given, as text.`);
39
+ return value.trim();
40
+ };
41
+ const whole = (value: unknown, what: string): number => {
42
+ if (typeof value !== "number" || !Number.isSafeInteger(value)) throw new Error(`${what} has to be a whole number.`);
43
+ return value;
44
+ };
45
+
46
+ /** What UniProt said went wrong, in words the agent can do something about. */
47
+ const asTrouble = (cause: unknown): Error => {
48
+ if (cause instanceof UniProtError) {
49
+ if (cause.status === 429) return new Error("UniProt is being asked too often just now. Wait a little and ask again.");
50
+ if (cause.offline) return new Error("UniProt could not be reached. This device may be offline.");
51
+ return new Error(cause.message);
52
+ }
53
+ return cause instanceof Error ? cause : new Error(String(cause));
54
+ };
55
+
56
+ /** A protein said the way the rest of these tools say things. */
57
+ const proteinView = (protein: Protein): Record<string, unknown> => ({
58
+ accession: protein.accession, entry: protein.entryName, name: protein.name,
59
+ gene: protein.gene, organism: protein.organism,
60
+ // The first thing to look at, and the thing an agent is most likely to skip past.
61
+ reviewed_by_a_curator: protein.reviewed,
62
+ ...(protein.reviewed ? {} : { unreviewed_note: "This entry was made by machine from similarity, not read out of papers by anybody. What it says is marked on the protein is a guess, and a guess of a different kind from a curator's reading." }),
63
+ precursor_length: protein.length,
64
+ ...(protein.mass === null ? {} : { precursor_mass_daltons: protein.mass }),
65
+ ...(protein.signal === null ? {} : { signal_peptide: `${protein.signal.from}-${protein.signal.to}` }),
66
+ ...(protein.chain === null ? { mature_chain: null } : { mature_chain: {
67
+ name: protein.chain.name, lies: `${protein.chain.from}-${protein.chain.to}`, residues: protein.chain.length,
68
+ note: "This is what a lab ends up holding, and what its band on a gel is. The entry's own sequence is the precursor and is longer.",
69
+ } }),
70
+ keywords: protein.keywords.slice(0, 12),
71
+ look_at: protein.lookAt,
72
+ });
73
+
74
+ /**
75
+ * The tools that say what is known about a protein.
76
+ *
77
+ * @param options - Whether to offer them, and what to tell UniProt about who is asking.
78
+ * @returns The tools, or none if a host asked for none.
79
+ *
80
+ * @example
81
+ * ```ts
82
+ * import { knownTools } from "@biolibs/bionet-agent";
83
+ *
84
+ * knownTools().map((one) => one.name);
85
+ * // ["search_proteins", "look_up_protein", "work_out_phosphorylation"]
86
+ * ```
87
+ */
88
+ export function knownTools(options: KnownOptions = {}): AgentTool[] {
89
+ if (options.known === false) return [];
90
+ settings.tool = options.tool ?? "bionet-adviser";
91
+ if (options.email !== undefined) settings.email = options.email;
92
+
93
+ /** Fetch and read one entry. */
94
+ const entry = async (accession: string): Promise<Protein> => {
95
+ try { return readProtein(await lookUpProtein(accession)); } catch (cause) { throw asTrouble(cause); }
96
+ };
97
+
98
+ return [
99
+ {
100
+ name: "search_proteins", title: "Find a protein in UniProt", readOnly: true,
101
+ description: [
102
+ "Search UniProt for a protein, to get the accession that look_up_protein needs.",
103
+ "The query takes plain words and UniProt's fields: `gene:CSN2`, `organism_id:9913`, `taxonomy_name:\"Bos taurus\"`, `reviewed:true`, `length:[200 TO 300]`. For example: `casein AND organism_id:9913`.",
104
+ "Each result says whether a curator has been over it. A reviewed entry (Swiss-Prot) has been read out of papers by somebody; an unreviewed one (TrEMBL) was made by machine from similarity. Prefer a reviewed entry, and say which kind you used.",
105
+ "This reaches the internet. Only the query is sent.",
106
+ ].join(" "),
107
+ input: { type: "object", required: ["query"], additionalProperties: false, properties: {
108
+ query: { type: "string", description: "What to look for, in UniProt's syntax." },
109
+ reviewed_only: { type: "boolean", description: "Only entries a curator has been over. Usually what you want." },
110
+ limit: { type: "integer", description: `How many, up to ${MOST_PROTEINS}. 10 if not given.` },
111
+ } },
112
+ run: async (args) => {
113
+ const query = text(args["query"], "The query");
114
+ if (query.length > 300) throw new Error("A query is at most 300 characters. This searches by words; a sequence is not something to put in one.");
115
+ try {
116
+ const found = await searchProteins(query, {
117
+ ...(args["reviewed_only"] === true ? { reviewedOnly: true } : {}),
118
+ ...(args["limit"] === undefined ? {} : { limit: Math.min(MOST_PROTEINS, whole(args["limit"], "The limit")) }),
119
+ });
120
+ return {
121
+ query: found.query,
122
+ results: found.results.map((one) => ({
123
+ accession: one.accession, entry: one.entryName, name: one.name, gene: one.gene,
124
+ organism: one.organism, precursor_length: one.length, reviewed_by_a_curator: one.reviewed, look_at: one.lookAt,
125
+ })),
126
+ ...(found.results.length === 0 ? { note: "Nothing matched. Try fewer words, or an organism as organism_id:9913." } : {}),
127
+ from_outside: "This came from UniProt and is what is known outside this lab.",
128
+ };
129
+ } catch (cause) { throw asTrouble(cause); }
130
+ },
131
+ },
132
+ {
133
+ name: "look_up_protein", title: "What UniProt knows about a protein", readOnly: true,
134
+ description: [
135
+ "Read one UniProt entry: what the protein is, where its signal peptide and its mature chain lie, every residue that is modified after it is made, where it varies between individuals or breeds, and its named parts.",
136
+ "Two things here are worth more than the rest.",
137
+ "The mature chain is what a lab actually ends up holding. A UniProt entry's own sequence is usually the precursor, signal peptide and all, and the two are different lengths and so different masses on a gel. Use the chain when you are saying what band to look for.",
138
+ "The modified residues are what a sequence cannot tell you. For a protein like casein the phosphoserines are the whole point — they are what lets it build a micelle — and whether the host will put them on is a different question from whether it will make the protein. work_out_phosphorylation asks that one.",
139
+ "Positions are given both ways: on the entry, which is how UniProt counts and how a paper will cite it, and on the mature chain, which is how a lab holding the protein counts. They differ by the length of the signal peptide, and confusing them is the easiest mistake here to make.",
140
+ "This reaches the internet. Only the accession is sent, and nothing is added to the lab.",
141
+ ].join(" "),
142
+ input: { type: "object", required: ["accession"], additionalProperties: false, properties: {
143
+ accession: { type: "string", description: "The UniProt accession, such as P02666." },
144
+ include: { type: "string", enum: ["all", "variants", "regions"], description: "Bring the sequence variants or the named parts too; both are long. Left out if not given." },
145
+ } },
146
+ run: async (args) => {
147
+ const protein = await entry(text(args["accession"], "The accession"));
148
+ const wanted = args["include"] === undefined ? "" : text(args["include"], "What to include");
149
+ const both = (at: number): Record<string, unknown> => {
150
+ const on = onTheChain(protein, at);
151
+ return { on_the_entry: at, ...(on === null ? { on_the_mature_chain: null } : { on_the_mature_chain: on }) };
152
+ };
153
+ return {
154
+ ...proteinView(protein),
155
+ sequence: protein.sequence,
156
+ ...(protein.chain === null ? {} : { mature_sequence: protein.chain.sequence }),
157
+ modified_residues: protein.modifications.map((one) => ({
158
+ ...both(one.at), residue: one.residue, what: one.what,
159
+ evidence_cited: one.evidenced,
160
+ })),
161
+ ...(protein.modifications.length === 0 ? { modified_residues_note: "This entry records none. For an unreviewed entry that usually means nobody has looked, not that there are none." } : {}),
162
+ ...(wanted === "all" || wanted === "variants"
163
+ ? { variants: protein.variants.map((one) => ({ ...both(one.from), was: one.was, now: one.now, note: one.note })) }
164
+ : protein.variants.length === 0 ? {} : { variants_not_shown: `${protein.variants.length} sequence variants are recorded. Ask with include "variants" to see them; for a protein like beta-casein they are the difference between one milk and another.` }),
165
+ ...(wanted === "all" || wanted === "regions"
166
+ ? { named_parts: protein.regions.map((one) => ({ lies: `${one.from}-${one.to}`, kind: one.kind, name: one.name })) }
167
+ : protein.regions.length === 0 ? {} : { named_parts_not_shown: protein.regions.length }),
168
+ from_outside: "This came from UniProt. A reviewed entry is a curator's reading of the papers; it is not something this lab has seen.",
169
+ };
170
+ },
171
+ },
172
+ {
173
+ name: "work_out_phosphorylation", title: "Which residues would be phosphorylated, and whether the host would do it", readOnly: true,
174
+ description: [
175
+ "Work out which serines and threonines of a protein carry a phosphorylation motif, and say whether the host it is being expressed in has the enzyme that would act on them.",
176
+ "This is the question a project to make a milk protein turns on, and it is not the same question as whether the protein gets made. Casein builds a micelle — which is what makes it behave like cheese rather than like dissolved protein — through clusters of phosphorylated serines binding calcium. A host can make casein of exactly the right mass, giving exactly the right band, that will not do the job because it was never phosphorylated.",
177
+ "Two things come back, and they are different in kind. The sites are a rule over the sequence: the secretory-pathway kinase reads Ser-x-Glu, and a serine that is already phosphorylated acts like a glutamate for the one two residues before it, so the sites march backwards along a cluster. That is arithmetic and the working shows it. Whether the host has the kinase is not arithmetic; it is what is generally held, it says how firmly, and it says to check the literature — which search_papers can now do.",
178
+ "Give `uniprot` as well, and the rule is compared against what a curator recorded. That comparison is worth more than either on its own: a rule that reproduces the record on a protein somebody studied can be believed on a variant nobody has.",
179
+ "Give the protein as a sequence, or as a part in this lab, or as a UniProt accession.",
180
+ ].join(" "),
181
+ input: { type: "object", additionalProperties: false, properties: {
182
+ sequence: { type: "string", description: "The amino acids, if you have them in hand." },
183
+ uniprot: { type: "string", description: "A UniProt accession, such as P02666. Its recorded sites are compared against the rule." },
184
+ on_the_mature_chain: { type: "boolean", description: "With a UniProt accession: work on the mature chain rather than the precursor. The precursor if not given, since that is how UniProt and a paper number things." },
185
+ host: { type: "string", description: "What it would be expressed in, such as \"Komagataella phaffii\" or \"Saccharomyces cerevisiae\"." },
186
+ } },
187
+ run: async (args) => {
188
+ const accession = args["uniprot"] === undefined ? null : text(args["uniprot"], "The accession");
189
+ const given = args["sequence"] === undefined ? null : text(args["sequence"], "The sequence");
190
+ if (accession === null && given === null) throw new Error("Give a sequence, or a UniProt accession to read one from.");
191
+ const protein = accession === null ? null : await entry(accession);
192
+ const mature = args["on_the_mature_chain"] === true;
193
+ if (mature && protein?.chain == null) throw new Error("That entry marks no mature chain, so there is no chain to count on.");
194
+ const chain = given ?? (mature ? protein!.chain!.sequence : protein!.sequence);
195
+ const found = phosphoSites(chain);
196
+ if (found.problem !== null) throw new Error(found.problem);
197
+ const named = args["host"] === undefined ? null : text(args["host"], "The host");
198
+ const host = named === null ? null : hostPhosphorylation(named);
199
+
200
+ // UniProt counts on the precursor; if the chain is what is being looked at, so must this.
201
+ const recorded = protein === null ? null : protein.modifications
202
+ .filter((one) => /phospho/i.test(one.what))
203
+ .map((one) => (mature ? onTheChain(protein, one.at) : one.at))
204
+ .filter((one): one is number => one !== null);
205
+ const against = recorded === null ? null : comparedWithKnown(found.sites.map((one) => one.at), recorded);
206
+
207
+ return {
208
+ ...(protein === null ? {} : { protein: protein.name, accession: protein.accession, reviewed_by_a_curator: protein.reviewed }),
209
+ counted_on: mature ? "the mature chain" : protein === null ? "the sequence given" : "the whole entry, precursor included",
210
+ residues: chain.length,
211
+ motifs: PHOSPHO_MOTIFS.map((one) => ({ name: one.name, pattern: one.pattern, kinase: one.kinase, about: one.about })),
212
+ sites: found.sites.map((one) => ({
213
+ at: one.at, residue: one.residue, by: one.by, kinase: one.kinase, context: one.context, round: one.round, because: one.because,
214
+ // A residue can carry more than one motif, and which is named first is only the order
215
+ // the rules are tried in. The others are said so that is not read as a finding.
216
+ ...(one.alsoBy.length === 0 ? {} : { also_matches: one.alsoBy.map((other) => ({ by: other.name, kinase: other.kinase, because: other.because })) }),
217
+ })),
218
+ rounds: found.rounds,
219
+ ...(against === null ? {} : { against_what_is_recorded: {
220
+ recorded, confirmed: against.confirmed, the_rule_missed: against.missed, predicted_only: against.onlyPredicted,
221
+ caught: `${Math.round(against.caught * 100)}% of the recorded sites`,
222
+ note: against.missed.length === 0 && against.confirmed.length > 0
223
+ ? "The rule reproduces every site a curator recorded, which is the reason to believe it on a sequence nobody has studied — a variant, or this gene rewritten in another host's codons."
224
+ : "The rule and the record do not agree. Believe the record for this protein, and be careful using the rule on another.",
225
+ } }),
226
+ ...(host === null ? (named === null ? {} : { host: named, host_not_known: `Nothing here says what ${named} does. That is not the same as its doing nothing: search_papers is the way to find out.` })
227
+ : { host: {
228
+ host: host.host,
229
+ has_the_secretory_kinase: host.secretoryKinase,
230
+ has_casein_kinase_2: host.casein2,
231
+ says: host.says,
232
+ how_firmly: host.standing,
233
+ check_it: `This is not worked out from anything; it is what is generally held. Search the literature for this host and this protein before spending a month on it.`,
234
+ } }),
235
+ working: phosphoWorking(found, host).map((one) => ({ of: one.of, comes: one.comes, kind: one.kind, steps: one.steps, ...(one.rests === undefined ? {} : { rests: one.rests }) })),
236
+ hosts_this_knows_of: HOST_KINASES.map((one) => one.host),
237
+ };
238
+ },
239
+ },
240
+ ];
241
+ }
package/src/papers.ts ADDED
@@ -0,0 +1,271 @@
1
+ /**
2
+ * Reading the literature: Europe PMC, through `@biolibs/europepmc`.
3
+ *
4
+ * Every other thing an adviser has either reads the lab or works something out from a sequence.
5
+ * These read what other people have published, and that is a different kind of knowing, so they
6
+ * are kept apart and say so in their own descriptions.
7
+ *
8
+ * It is worth being clear about why this exists at all. An adviser without it answers a question
9
+ * like "which host should we express casein in?" out of whatever it happens to know, and what it
10
+ * happens to know has no date on it and cannot be checked. With it, the answer can be a paper: this
11
+ * group used this host with this promoter and got this much, here is the section that says so, and
12
+ * here is where to read it. That is a different thing to hand a lab member, and the difference is
13
+ * the whole point.
14
+ *
15
+ * Three things follow from reaching outside, and all three are decided here rather than left to the
16
+ * agent:
17
+ *
18
+ * - **Nothing of the lab's goes out.** A query is words the agent writes, capped short enough that
19
+ * a sequence cannot be pasted into one. Nothing reads the freezer.
20
+ * - **A paper is somebody's claim.** What comes back is what a group reported, not something this
21
+ * lab has seen, and every answer says so rather than leaving it to be assumed.
22
+ * - **Only the open ones can be read.** Most papers are not open access, and for those there is the
23
+ * abstract and a link. Saying that plainly is better than an agent trying four ways to get at a
24
+ * full text that was never going to be there.
25
+ */
26
+ import { EuropePmcError, citationsOf, findSection, fullTextOf, readArticle, referencesOf, searchArticles, settings,
27
+ MOST_FOUND, SECTION_KINDS, type Article, type Corpus } from "@biolibs/europepmc";
28
+ import type { AgentTool } from "./tools.js";
29
+
30
+ /** The longest a query may be. Short enough that a sequence cannot be put in one. */
31
+ export const LONGEST_QUERY = 400;
32
+
33
+ /** The most characters of a paper handed back in one go. A section, not a book. */
34
+ export const MOST_READ = 24_000;
35
+
36
+ /** How an adviser reaches Europe PMC. */
37
+ export interface PaperOptions {
38
+ /** Whether to offer these tools at all. On unless a host says otherwise. */
39
+ papers?: boolean;
40
+ /** What to call this software to Europe PMC. Never a person's name. */
41
+ tool?: string;
42
+ /**
43
+ * An address Europe PMC could use to get in touch about heavy use, if somebody has given one for
44
+ * that. It is never taken from the lab or from the device.
45
+ */
46
+ email?: string | null;
47
+ }
48
+
49
+ const text = (value: unknown, what: string): string => {
50
+ if (typeof value !== "string" || value.trim() === "") throw new Error(`${what} has to be given, as text.`);
51
+ return value.trim();
52
+ };
53
+ const whole = (value: unknown, what: string): number => {
54
+ if (typeof value !== "number" || !Number.isSafeInteger(value)) throw new Error(`${what} has to be a whole number.`);
55
+ return value;
56
+ };
57
+
58
+ /** What Europe PMC said went wrong, in words the agent can do something about. */
59
+ const asTrouble = (cause: unknown): Error => {
60
+ if (cause instanceof EuropePmcError) {
61
+ if (cause.status === 429) return new Error("Europe PMC is being asked too often just now. Wait a little and ask again.");
62
+ // Only a request that was actually sent and got no answer means the device may be offline. An
63
+ // ID of the wrong shape never leaves this machine, and saying "offline" would send somebody to
64
+ // check their network when what is wrong is what they typed.
65
+ if (cause.offline) return new Error("Europe PMC could not be reached. This device may be offline.");
66
+ return new Error(cause.message);
67
+ }
68
+ return cause instanceof Error ? cause : new Error(String(cause));
69
+ };
70
+
71
+ /** As much of a section as fits, with what was left said rather than quietly dropped. */
72
+ function asMuchAs(pieces: { heading: string; text: string }[], room: number): { parts: { heading: string; text: string }[]; cut: number } {
73
+ const parts: { heading: string; text: string }[] = [];
74
+ let left = room;
75
+ let cut = 0;
76
+ for (const piece of pieces) {
77
+ if (left <= 0) { cut += 1; continue; }
78
+ if (piece.text.length <= left) { parts.push(piece); left -= piece.text.length; continue; }
79
+ parts.push({ heading: piece.heading, text: `${piece.text.slice(0, left)}…` });
80
+ left = 0;
81
+ }
82
+ return { parts, cut };
83
+ }
84
+
85
+ /** The most headings listed at once. A review nests forty of them, which as one sentence is a wall. */
86
+ const MOST_HEADINGS = 40;
87
+
88
+ /**
89
+ * What a paper's shape says it is worth asking for next.
90
+ *
91
+ * The headings go back as a list and not as a sentence. A review has forty of them nested four
92
+ * deep, and run together with semicolons they are unreadable by anything, which is the opposite of
93
+ * what this is for.
94
+ */
95
+ function whatElse(article: Article): Record<string, unknown> {
96
+ const headings = article.sections.filter((one) => one.heading !== "");
97
+ const shown = headings.slice(0, MOST_HEADINGS);
98
+ return {
99
+ ...(shown.length === 0 ? {} : { sections: shown.map((one) => ({ heading: one.heading, under: one.depth, characters: one.text.length })) }),
100
+ ...(headings.length > shown.length ? { more_sections: headings.length - shown.length } : {}),
101
+ ...(article.tables.length === 0 ? {} : { tables: article.tables.length, tables_note: "A yield is as often in a table as in a sentence. Ask for \"tables\"." }),
102
+ ask_for: "Any heading above, by name, or one of: " + [...SECTION_KINDS, "tables", "figures", "all"].join(", "),
103
+ };
104
+ }
105
+
106
+ /**
107
+ * The tools that read the literature.
108
+ *
109
+ * @param options - Whether to offer them, and what to tell Europe PMC about who is asking.
110
+ * @returns The tools, or none if a host asked for none.
111
+ *
112
+ * @example
113
+ * ```ts
114
+ * import { paperTools } from "@biolibs/bionet-agent";
115
+ *
116
+ * paperTools({ tool: "bionet-adviser" }).map((one) => one.name);
117
+ * // ["search_papers", "read_paper", "papers_around"]
118
+ * ```
119
+ */
120
+ export function paperTools(options: PaperOptions = {}): AgentTool[] {
121
+ if (options.papers === false) return [];
122
+ // Said once, before anything is asked. Europe PMC wants a client to name itself; it is told the
123
+ // software's name and nothing about the lab or the person at it.
124
+ settings.tool = options.tool ?? "bionet-adviser";
125
+ if (options.email !== undefined) settings.email = options.email;
126
+
127
+ const query = (value: unknown): string => {
128
+ const asked = text(value, "The query");
129
+ if (asked.length > LONGEST_QUERY) throw new Error(`A query is at most ${LONGEST_QUERY} characters. This searches by words; a sequence is not something to put in one.`);
130
+ return asked;
131
+ };
132
+
133
+ return [
134
+ {
135
+ name: "search_papers", title: "Search the literature", readOnly: true,
136
+ description: [
137
+ "Search Europe PMC, which indexes PubMed, PubMed Central, preprints and patents together, for what has been published about something.",
138
+ "Use it when the question is what is known rather than what this lab holds: which host somebody expressed a protein in and what they got, whether a promoter works in a given organism, what a sensible yield looks like, whether an approach has already failed for somebody.",
139
+ "The query takes plain words, phrases in quotes, and fields: `TITLE:`, `ABSTRACT:`, `METHODS:` (which searches the methods sections of open papers and is the one to use for a technique), `AUTH:`, `JOURNAL:`, `PUB_YEAR:`. `AND`, `OR` and `NOT` join them. For example: `\"kappa-casein\" AND \"Pichia pastoris\"` or `METHODS:\"Gibson assembly\" AND casein`.",
140
+ "Each result says whether its full text can actually be read, which is what read_paper needs; most papers are not open, and for those there is the abstract and a link.",
141
+ "This reaches the internet. Only the query is sent, so write it yourself and do not put the lab's own sequences, part names or notes in it; nothing is read from the freezer.",
142
+ ].join(" "),
143
+ input: { type: "object", required: ["query"], additionalProperties: false, properties: {
144
+ query: { type: "string", description: `What to look for, at most ${LONGEST_QUERY} characters.` },
145
+ corpus: { type: "string", enum: ["all", "open-access", "preprints", "reviews"],
146
+ description: "Narrow it: open-access for papers that can be read in full, preprints for the newest work, reviews for a way into a field. All of it if not given." },
147
+ sort: { type: "string", enum: ["relevance", "cited", "date"], description: "cited brings the papers others built on, which for a broad query means the famous rather than the fitting; date brings the newest. Relevance if not given, and usually what you want." },
148
+ abstracts: { type: "boolean", description: "Bring the abstracts too. Worth it for a few results, not for many." },
149
+ limit: { type: "integer", description: `How many, up to ${MOST_FOUND}. 10 if not given.` },
150
+ } },
151
+ run: async (args) => {
152
+ const asked = query(args["query"]);
153
+ try {
154
+ const found = await searchArticles(asked, {
155
+ ...(args["corpus"] === undefined ? {} : { corpus: text(args["corpus"], "The corpus") as Corpus }),
156
+ ...(args["sort"] === undefined ? {} : { sort: text(args["sort"], "The sort") as "cited" | "date" | "relevance" }),
157
+ ...(args["abstracts"] === true ? { abstracts: true } : {}),
158
+ ...(args["limit"] === undefined ? {} : { limit: whole(args["limit"], "The limit") }),
159
+ });
160
+ if (found.results.length === 0) {
161
+ return { query: found.query, matched: 0, results: [],
162
+ note: "Nothing matched. Try fewer words, or drop a quoted phrase: a phrase has to appear exactly as written." };
163
+ }
164
+ return {
165
+ query: found.query, matched: found.matched, showing: found.results.length,
166
+ results: found.results.map((one) => ({
167
+ id: one.id, source: one.source, title: one.title, authors: one.authors.slice(0, 6),
168
+ journal: one.journal, year: one.year, cited_by: one.citedBy,
169
+ ...(one.pmcid === null ? {} : { pmcid: one.pmcid }), ...(one.doi === null ? {} : { doi: one.doi }),
170
+ can_read_in_full: one.fullText,
171
+ ...(one.hasSupplement ? { has_supplementary_data: true } : {}),
172
+ look_at: one.lookAt,
173
+ ...(one.abstract === null ? {} : { abstract: one.abstract }),
174
+ })),
175
+ ...(found.matched > found.results.length
176
+ ? { note: `${found.matched.toLocaleString("en-US")} matched in all; these are the first ${found.results.length}. Narrow the query rather than asking for many more.` }
177
+ : {}),
178
+ from_outside: "These are what other groups have published. Nothing here has been checked by this lab. Use read_paper on one whose full text can be read.",
179
+ };
180
+ } catch (cause) { throw asTrouble(cause); }
181
+ },
182
+ },
183
+ {
184
+ name: "read_paper", title: "Read an open-access paper", readOnly: true,
185
+ description: [
186
+ "Read one open-access paper from Europe PMC: its abstract, a named section of it, or its tables.",
187
+ "This is the one that answers a real question. A paper's methods are where the recipe is — which strain, which plasmid, what the medium was, what it was induced with and for how long — and `section: \"methods\"` gives that section and everything under it. `section: \"results\"` gives what came of it. `section: \"tables\"` gives the tables as rows, which is where a yield usually is.",
188
+ "Ask for it by the PubMed Central ID that search_papers gives as `pmcid`, for a result whose `can_read_in_full` is true. A paper that is not open access cannot be read here however it is asked for; there is its abstract from search_papers, and its link.",
189
+ "Without a section it gives the abstract and the list of headings, which is the cheap way to see what is worth asking for. A section longer than what one read brings back is cut, and says it was.",
190
+ "What a paper says is what that group reported. It is not something this lab has seen, and a method that worked for them may not work here; say whose result it is when you use it.",
191
+ "This reaches the internet. Only the paper's ID is sent.",
192
+ ].join(" "),
193
+ input: { type: "object", required: ["pmcid"], additionalProperties: false, properties: {
194
+ pmcid: { type: "string", description: "The PubMed Central ID, such as PMC11767299." },
195
+ section: { type: "string", description: `Which part: ${SECTION_KINDS.join(", ")}, "tables", "figures", "all", or any words to match a heading with, such as "yeast".` },
196
+ } },
197
+ run: async (args) => {
198
+ const pmcid = text(args["pmcid"], "The paper's ID");
199
+ const wanted = args["section"] === undefined ? null : text(args["section"], "The section").toLowerCase();
200
+ let paper: Article;
201
+ try { paper = readArticle(await fullTextOf(pmcid)); } catch (cause) { throw asTrouble(cause); }
202
+ const about = {
203
+ pmcid: pmcid.toUpperCase(), title: paper.title, journal: paper.journal, year: paper.year,
204
+ authors: paper.authors.slice(0, 8), ...(paper.licence === null ? {} : { licence: paper.licence }),
205
+ from_outside: "This is what this group reported. It is not something this lab has seen.",
206
+ };
207
+ if (wanted === "tables") {
208
+ const { parts, cut } = asMuchAs(paper.tables.map((one) => ({ heading: `${one.label} ${one.caption}`.trim(), text: JSON.stringify({ headings: one.headings, rows: one.rows }) })), MOST_READ);
209
+ return { ...about, tables: paper.tables.slice(0, parts.length).map((one) => ({ label: one.label, caption: one.caption, headings: one.headings, rows: one.rows })),
210
+ ...(cut === 0 ? {} : { note: `${cut} more ${cut === 1 ? "table is" : "tables are"} not shown: they would not fit in one read.` }) };
211
+ }
212
+ if (wanted === "figures") return { ...about, figures: paper.figures };
213
+ if (wanted === null) {
214
+ return { ...about, abstract: paper.abstract, keywords: paper.keywords,
215
+ table_captions: paper.tables.map((one) => `${one.label}: ${one.caption}`),
216
+ what_else: whatElse(paper) };
217
+ }
218
+ const whole = wanted === "all";
219
+ const match = whole ? { sections: paper.sections.filter((one) => one.text !== ""), exact: true } : findSection(paper, wanted);
220
+ const sections = match.sections;
221
+ if (sections.length === 0) {
222
+ return { ...about, found_nothing: `This paper has no section matching ${JSON.stringify(wanted)}.`, what_else: whatElse(paper) };
223
+ }
224
+ const { parts, cut } = asMuchAs(sections.map((one) => ({ heading: one.heading, text: one.text })), MOST_READ);
225
+ return {
226
+ ...about, section: wanted,
227
+ // A paper with no methods section still has headings with the word in them. Saying the
228
+ // match was loose is the difference between an answer and a wrong answer confidently given.
229
+ ...(match.exact ? {} : { not_an_exact_match: `No heading of this paper is ${JSON.stringify(wanted)}. These merely contain the word, so they may not be what you are after. The headings are in what_else.`,
230
+ what_else: whatElse(paper) }),
231
+ parts: parts.filter((one) => one.text !== "" || one.heading !== ""),
232
+ ...(cut === 0 ? {} : { note: `${cut} further ${cut === 1 ? "part" : "parts"} of this section would not fit in one read. Ask for one of them by its heading.` }),
233
+ };
234
+ },
235
+ },
236
+ {
237
+ name: "papers_around", title: "What a paper cited, and who cited it", readOnly: true,
238
+ description: [
239
+ "Walk a paper's reference list, or the papers that have cited it since.",
240
+ "This is how you get to a method that is not written down where you found it. A paper says it expressed the gene \"as described previously\" and gives a number; the number is the paper with the actual recipe, and `direction: \"back\"` finds it. Going the other way says whether anybody managed to repeat the work, and what they changed.",
241
+ "Ask by the `id` and `source` that search_papers gives for a result, not by the PMC ID.",
242
+ "This reaches the internet. Only the paper's ID is sent.",
243
+ ].join(" "),
244
+ input: { type: "object", required: ["id", "source", "direction"], additionalProperties: false, properties: {
245
+ id: { type: "string", description: "The paper's ID, from search_papers." },
246
+ source: { type: "string", description: "Which index it is in, from search_papers: MED, PMC or PPR." },
247
+ direction: { type: "string", enum: ["back", "forward"], description: "back for what it cited; forward for what has cited it." },
248
+ page: { type: "integer", description: "Which page, counting from 1. The first if not given." },
249
+ limit: { type: "integer", description: "How many on a page. 25 if not given." },
250
+ } },
251
+ run: async (args) => {
252
+ const id = text(args["id"], "The paper's ID");
253
+ const source = text(args["source"], "The index");
254
+ const back = text(args["direction"], "The direction") === "back";
255
+ const page = args["page"] === undefined ? undefined : whole(args["page"], "The page");
256
+ const limit = args["limit"] === undefined ? undefined : whole(args["limit"], "The limit");
257
+ try {
258
+ const trail = await (back ? referencesOf : citationsOf)(source, id, {
259
+ ...(page === undefined ? {} : { page }), ...(limit === undefined ? {} : { limit }),
260
+ });
261
+ return {
262
+ of: `${source}/${id}`, direction: back ? "what it cited" : "what has cited it",
263
+ count: trail.count, page: trail.page, more: trail.more,
264
+ papers: trail.papers.map((one) => ({ id: one.id, source: one.source, title: one.title, authors: one.authors, journal: one.journal, year: one.year, look_at: one.lookAt })),
265
+ ...(trail.count === 0 ? { note: back ? "Europe PMC has no reference list for this one." : "Nothing has cited it yet, or Europe PMC does not know of it." } : {}),
266
+ };
267
+ } catch (cause) { throw asTrouble(cause); }
268
+ },
269
+ },
270
+ ];
271
+ }