unitoolkit 0.7.0__py3-none-any.whl

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.
unitoolkit/tools.py ADDED
@@ -0,0 +1,555 @@
1
+ """One tool registry for every surface: CLI, MCP server, tools.json manifest.
2
+
3
+ Each tool is a plain function with a JSON-schema'd signature. Add a tool here and it
4
+ appears in `python -m unitoolkit <name>`, in the MCP server, and in `tools.json`.
5
+ All tools are read-only toward the school's systems; the only writes are local files.
6
+ """
7
+ import json
8
+ import pathlib
9
+ import urllib.parse
10
+ import urllib.request
11
+
12
+ TOOLS = {}
13
+
14
+
15
+ def tool(name, description, properties=None, required=()):
16
+ def wrap(fn):
17
+ TOOLS[name] = {
18
+ "name": name,
19
+ "description": description,
20
+ "inputSchema": {"type": "object", "properties": properties or {},
21
+ "required": list(required), "additionalProperties": False},
22
+ "fn": fn,
23
+ }
24
+ return fn
25
+ return wrap
26
+
27
+
28
+ S = {"type": "string"}
29
+ I = {"type": "integer"}
30
+ B = {"type": "boolean"}
31
+
32
+
33
+ # ------------------------------------------------------------- Agent surface
34
+ # Question-shaped tools. The MCP server lists these by default (unitoolkit/agent.py: CORE);
35
+ # UNITOOLKIT_TOOLS=all lists everything. All tools stay callable by name.
36
+
37
+ @tool("today",
38
+ "START HERE for 'what do I need to do?'. Everything due in the next N days (default 14) "
39
+ "from every system at once: Canvas deadlines not yet submitted, Ladok registration "
40
+ "windows open now or opening soon, this week's timetable, and (library=true) library "
41
+ "loans due back. "
42
+ "Each section reports its own error, so one dead session never hides the rest.",
43
+ {"days": I, "library": B})
44
+ def today(days=14, library=False):
45
+ from . import agent
46
+ return agent.today(days or 14, library=bool(library))
47
+
48
+
49
+ @tool("doctor",
50
+ "Health check of every session the toolkit depends on (Canvas token and its expiry date, "
51
+ "agent browser, Ladok, database proxy, library, timetable link). Each row has the fix, "
52
+ "which is always a human action. Run it when another tool fails. only='canvas,ladok' "
53
+ "limits the checks.",
54
+ {"only": S})
55
+ def doctor(only=None):
56
+ from . import agent
57
+ return agent.doctor(only)
58
+
59
+
60
+ @tool("schedule",
61
+ "Timetable for any course code (1SPRY2), student group (H26SK) or room, for any period, "
62
+ "from TimeEdit without a login. kind=code|group|room|subject. start/end as YYYY-MM-DD or "
63
+ "TimeEdit relative form (0.d = today, 4.w = four weeks). Course NAMES are not indexed: "
64
+ "search the code or the group.",
65
+ {"query": S, "kind": S, "start": S, "end": S}, ["query"])
66
+ def schedule(query, kind="code", start="0.d", end="14.d"):
67
+ from . import timeedit
68
+ return timeedit.schedule(query, kind or "code", start or "0.d", end or "14.d")
69
+
70
+
71
+ @tool("free_rooms",
72
+ "Which student-bookable rooms are free on a date (default today), as gaps between "
73
+ "bookings within the booking rules (Mon-Fri 08-20, up to 3 days ahead, max 4 h). "
74
+ "Read-only: booking itself is done by the student in TimeEdit.",
75
+ {"date": S, "min_minutes": I})
76
+ def free_rooms(date=None, min_minutes=60):
77
+ from . import timeedit
78
+ return timeedit.free_rooms(date or None, min_minutes or 60)
79
+
80
+
81
+ @tool("library",
82
+ "The school library (Koha). With query: catalogue search with availability per copy. "
83
+ "Without: the student's own loans with due dates and days left, holds and fines.",
84
+ {"query": S, "limit": I})
85
+ def library(query=None, limit=10):
86
+ from . import agent
87
+ return agent.library(query, limit or 10)
88
+
89
+
90
+ # ------------------------------------------------------------------- Ladok
91
+
92
+ @tool("ladok_windows",
93
+ "Ladok registration windows (kursregistrering + tentamensanmälan): what opens when, "
94
+ "what closes within N days, with course period. Needs the agent Chrome logged in to "
95
+ "Ladok (CDP :9233); read-only, never registers anything. Subrepo: ladok_vakt/.",
96
+ {"close_days": I})
97
+ def ladok_windows(close_days=None):
98
+ """Structured rows, not the watcher's text lines.
99
+
100
+ core.run() is the cron path: it returns human lines and turns a missing session into a
101
+ "VARNING" line, which an agent would read as data. Here a fault is an error field, and
102
+ LADOK_AUTOLOGIN=1 (with LADOK_IDP_ENTITY) lets it restore the session once first.
103
+ """
104
+ import sys
105
+ try:
106
+ from ladok_vakt import core # installed wheel ships it as a package
107
+ except ImportError: # source checkout: the vendored subtree
108
+ _vendor = pathlib.Path(__file__).resolve().parents[1] / 'vendor' / 'ladok-vakt'
109
+ sys.path.insert(0, str(_vendor))
110
+ from ladok_vakt import core
111
+ cfg = core.Config()
112
+ if close_days is not None:
113
+ cfg.close_days = int(close_days)
114
+ try:
115
+ try:
116
+ uid, reg_xml, exam_xml = core.fetch(cfg)
117
+ except core.Fault:
118
+ if not cfg.autologin:
119
+ raise
120
+ from ladok_vakt.login import login
121
+ login(cfg)
122
+ uid, reg_xml, exam_xml = core.fetch(cfg)
123
+ except core.Fault as exc:
124
+ return {"error": str(exc),
125
+ "hint": "sign in to Ladok once in the agent browser (CDP :9233), or set "
126
+ "LADOK_AUTOLOGIN=1 and LADOK_IDP_ENTITY for the opt-in re-login"}
127
+ rows = core.pending_actions(core.parse_registrations(reg_xml) + core.parse_exams(exam_xml))
128
+ for r in rows:
129
+ r["days_to_open"] = core.days_until(r.get("reg_opens"))
130
+ r["days_to_close"] = core.days_until(r.get("reg_closes"))
131
+ return {"windows": rows, "urgent": core.urgent(rows, cfg.close_days)}
132
+
133
+
134
+ # ---------------------------------------------------------------- Canvas (token)
135
+
136
+ @tool("courses", "List the student's Canvas courses: id, code, name, term.")
137
+ def courses():
138
+ from . import canvas
139
+ return [{"id": c["id"], "code": c.get("course_code"), "name": c.get("name"),
140
+ "term": (c.get("term") or {}).get("name")} for c in canvas.courses()]
141
+
142
+
143
+ @tool("discussions",
144
+ "Discussion topics across courses with read state and reply count, so a group discussion "
145
+ "that is waiting for an answer does not go unnoticed. Announcements are separate.",
146
+ {"course": {**I, "description": "Canvas course id; omitted: every active course"},
147
+ "days": {**I, "description": "Only topics replied to in the last N days; omitted: all"},
148
+ "unread_only": {**B, "description": "Skip topics already read"}})
149
+ def discussions(course=None, days=None, unread_only=False):
150
+ from . import canvas
151
+ return canvas.discussions(course=course, days=days, unread_only=unread_only)
152
+
153
+
154
+ @tool("announcements",
155
+ "Course announcements, newest first, with body text. Canvas hides these from the plain "
156
+ "discussion list, so this is the only way to see what a teacher posted.",
157
+ {"course": {**I, "description": "Canvas course id; omitted: every active course"},
158
+ "days": {**I, "description": "How far back, default 30"}})
159
+ def announcements(course=None, days=30):
160
+ from . import canvas
161
+ return canvas.announcements(course=course, days=days)
162
+
163
+
164
+ @tool("upcoming", "Everything due from today across all Canvas courses: title, course, "
165
+ "due (UTC), submitted. Start here for 'what is due?'.")
166
+ def upcoming():
167
+ from . import canvas
168
+ out = []
169
+ for i in canvas.upcoming():
170
+ sub = i.get("submissions")
171
+ out.append({"course": i.get("context_name"), "type": i.get("plannable_type"),
172
+ "title": ((i.get("plannable") or {}).get("title") or "").strip(),
173
+ "due_utc": i.get("plannable_date"),
174
+ "submitted": sub.get("submitted") if isinstance(sub, dict) else None})
175
+ return out
176
+
177
+
178
+ @tool("mirror", "Download a whole Canvas course (modules, pages, assignments with rubrics, "
179
+ "announcements, discussions, files) to disk. course='all' mirrors every course.",
180
+ {"course": S, "out": S, "files": B}, ["course"])
181
+ def mirror(course, out="~/courses/canvas", files=True):
182
+ from . import canvas
183
+ base = pathlib.Path(out).expanduser()
184
+ ids = [c["id"] for c in canvas.courses()] if str(course) == "all" else [int(course)]
185
+ return [canvas.mirror(i, base / str(i), files=files) for i in ids]
186
+
187
+
188
+ @tool("canvas_get", "Raw Canvas REST GET with pagination, e.g. path='courses/123/assignments'. "
189
+ "params is a JSON object of query parameters.", {"path": S, "params": {"type": "object"}}, ["path"])
190
+ def canvas_get(path, params=None):
191
+ from . import canvas
192
+ return canvas.get(path, **(params or {}))
193
+
194
+
195
+ @tool("assignment", "One Canvas assignment with description and rubric as plain text.",
196
+ {"course": I, "assignment": I}, ["course", "assignment"])
197
+ def assignment(course, assignment):
198
+ import html
199
+ import re
200
+ from . import canvas
201
+ a = canvas.get(f"courses/{course}/assignments/{assignment}")
202
+ desc = html.unescape(re.sub(r"<[^>]+>", " ", a.get("description") or ""))
203
+ return {"name": a.get("name"), "due_utc": a.get("due_at"), "points": a.get("points_possible"),
204
+ "description": re.sub(r"\s+", " ", desc).strip(),
205
+ "rubric": [{"criterion": r.get("description"), "long": r.get("long_description"),
206
+ "ratings": [x.get("description") for x in r.get("ratings", [])]}
207
+ for r in a.get("rubric") or []]}
208
+
209
+
210
+ # ------------------------------------------------------- SSO browser (CDP)
211
+
212
+ @tool("login_check", "Which SSO sites (Canvas, SharePoint, Ladok) the agent browser is logged in to.")
213
+ def login_check():
214
+ from . import browser
215
+ sites = ("https://shh.instructure.com/", "https://shh365.sharepoint.com/",
216
+ "https://www.student.ladok.se/student/app/studentwebb/")
217
+ out = {}
218
+ for u in sites:
219
+ ok, landed = browser.logged_in(u)
220
+ out[u] = {"logged_in": ok, "landed": landed[:120]}
221
+ return out
222
+
223
+
224
+ @tool("page", "Rendered text of any page, read through the student's logged-in browser "
225
+ "(SharePoint, Ladok, Inspera, intranet).", {"url": S}, ["url"])
226
+ def page(url):
227
+ from . import browser
228
+ return browser.page(url)
229
+
230
+
231
+ @tool("fetch", "JSON/text fetch executed inside `origin` so the site's own cookies apply. "
232
+ "Use for internal APIs (Ladok student API, SharePoint REST).", {"url": S, "origin": S}, ["url", "origin"])
233
+ def fetch(url, origin):
234
+ from . import browser
235
+ return browser.fetch(url, origin)
236
+
237
+
238
+ @tool("sharepoint_download", "Download a SharePoint share link (/:b:/ or /:u:/ style) to a "
239
+ "local file; returns path, size, type.", {"share_url": S, "out": S}, ["share_url"])
240
+ def sharepoint_download(share_url, out="~/courses/downloads"):
241
+ from . import sharepoint
242
+ return sharepoint.save_share(share_url, out)
243
+
244
+
245
+ # ---------------------------------------------------------- Course search
246
+
247
+ @tool("search", "Full-text search inside one course: pages, assignments with rubrics, "
248
+ "modules, discussions, files. Operators: \"phrase\", -exclude, +required, OR, "
249
+ "type:sida|uppgift|fil|modul|diskussion, filetype:pdf, intitle:word, before:YYYY-MM-DD, "
250
+ "after:YYYY-MM-DD, plus regex/fuzzy toggles. source='mirror' searches a local mirror "
251
+ "(fast, may be stale), 'api' fetches live from Canvas, 'auto' prefers the mirror. "
252
+ "include_docs=true also searches the document text built by the docs tool.",
253
+ {"course": S, "query": S, "source": S, "regex": B, "fuzzy": B, "whole_word": B,
254
+ "case_sensitive": B, "include_docs": B, "limit": I}, ["course", "query"])
255
+ def search(course, query, source="auto", regex=False, fuzzy=False, whole_word=False,
256
+ case_sensitive=False, include_docs=False, limit=25):
257
+ import pathlib as _p
258
+ from . import docs as docs_mod
259
+ from . import search as s
260
+ mirror = _p.Path("~/courses/canvas").expanduser() / str(course)
261
+ use_mirror = source == "mirror" or (source == "auto" and (mirror / "pages").exists())
262
+ idx = s.index_from_mirror(mirror) if use_mirror else s.build_index(course)
263
+ if include_docs:
264
+ extra = docs_mod.load(course)
265
+ # a file with extracted text should appear once, as the text hit, not also as a name
266
+ with_text = {(d.get("title") or "").lower() for d in extra}
267
+ idx = {**idx, "docs": [d for d in idx["docs"]
268
+ if not (d["type"] == "fil" and (d.get("title") or "").lower() in with_text)]
269
+ + extra}
270
+ res = s.run(idx, query, case_sensitive=case_sensitive, regex=regex, fuzzy=fuzzy,
271
+ whole_word=whole_word, limit=limit)
272
+ hits = []
273
+ for h in res.get("hits", []):
274
+ row = {"type": h["type"], "title": h["title"], "score": h["score"],
275
+ "anchor": h.get("anchor", ""), "snippet": h["snippet"], "url": h["url"]}
276
+ if h["type"] == "fildok":
277
+ # page numbers matter for citations, and pdftotext keeps them as \f
278
+ row["page"] = docs_mod.page_of(h.get("body") or "", h.get("at") or 0)
279
+ row["ocr_pages"] = h.get("ocr_pages") or 0
280
+ hits.append(row)
281
+ out = {"source": idx["source"], "documents": len(idx["docs"]),
282
+ "total": res.get("total", 0), "hits": hits}
283
+ if res.get("error"):
284
+ out["error"] = res["error"]
285
+ if not out["total"] and not regex:
286
+ alt = s.suggest(idx, query)
287
+ if alt:
288
+ out["did_you_mean"] = alt
289
+ return out
290
+
291
+
292
+ # ---------------------------------------------------------- Document text
293
+
294
+ @tool("docs", "Download a course's files once, extract their text (pdf, docx, pptx, xlsx, html, "
295
+ "images) and cache it keyed by file id + updated_at. Bytes are discarded, text is kept. "
296
+ "ocr=true adds tesseract for documents with no usable text layer; it is slow, so it is "
297
+ "not part of a normal index run.",
298
+ {"course": S, "ocr": B, "force": B, "max_files": I, "ocr_max_pages": I,
299
+ "only_contains": S, "links": B}, ["course"])
300
+ def docs(course, ocr=False, force=False, max_files=None, ocr_max_pages=60, only_contains=None,
301
+ links=False):
302
+ from . import docs as d
303
+ out = {"files": d.build(course, ocr=ocr, force=force, max_files=max_files,
304
+ ocr_max_pages=ocr_max_pages, only_contains=only_contains)}
305
+ if links:
306
+ # shares are not in /files at all; they live only as links inside pages
307
+ out["links"] = d.resolve_links(course, allow_ocr=ocr)
308
+ return out
309
+
310
+
311
+ # ---------------------------------------------------------- Session surface
312
+
313
+ @tool("surface", "Probe which Canvas endpoints a student session can reach, before building "
314
+ "anything on assumptions. Returns per-endpoint status, item count and payload size, "
315
+ "plus a summary of what is blocked (pages index, quizzes and rubrics are commonly off).",
316
+ {"course": S}, ["course"])
317
+ def surface(course):
318
+ from . import surface as s
319
+ rows = s.probe_course(course)
320
+ return {"course": course, "summary": s.summary(rows),
321
+ "endpoints": [{"label": r["label"], "status": r["status"], "count": r["count"],
322
+ "bytes": r["bytes"], "note": r["note"]} for r in rows]}
323
+
324
+
325
+ # ---------------------------------------------------------- Programme map
326
+
327
+ @tool("programme", "Map the whole SHH nursing programme: every course with its kursplan and "
328
+ "kurslitteraturlista downloaded and verified by the course code inside each file.",
329
+ {"out": S})
330
+ def programme(out="~/courses/programme"):
331
+ from . import programme as pr
332
+ cs, docs = pr.build(out)
333
+ md = pr.report(cs)
334
+ (pathlib.Path(out).expanduser() / "KURSKARTA.md").write_text(md)
335
+ return {"courses": [{"code": c["code"], "name": c["name"], "kursplan": c.get("kursplan_file"),
336
+ "litteratur": c.get("litteratur_file")} for c in cs],
337
+ "errors": [d for d in docs if d.get("error")]}
338
+
339
+
340
+ # ---------------------------------------------------------- TimeEdit (public)
341
+
342
+ @tool("timeedit", "Bookings from a TimeEdit schedule link (the .html URL the student copies "
343
+ "from TimeEdit). Returns date, start, end and the booking columns. Note: a link covers "
344
+ "only the period it was created for.", {"url": S}, ["url"])
345
+ def timeedit(url):
346
+ j = url.split("?")[0].rsplit(".", 1)[0] + ".json"
347
+ with urllib.request.urlopen(j, timeout=30) as r:
348
+ d = json.load(r)
349
+ head = d.get("columnheaders", [])
350
+ return [{"date": x["startdate"], "start": x["starttime"], "end": x["endtime"],
351
+ **{(head[k] if k < len(head) else f"col{k}") or f"col{k}": v
352
+ for k, v in enumerate(x.get("columns", []))}}
353
+ for x in d.get("reservations", [])]
354
+
355
+
356
+ # -------------------------------------------------------------------- Koha
357
+
358
+ @tool("koha_search",
359
+ "Search the SHH library catalogue (Koha, biblioteket.shh.se) for course books and "
360
+ "literature: title, biblionumber and availability per hit. Read-only. Goes through the "
361
+ "proxied agent browser because the library's Cloudflare refuses plain HTTP clients.",
362
+ {"q": S, "limit": I}, ("q",))
363
+ def koha_search(q, limit=10):
364
+ from . import koha
365
+ rows = koha.search(q, limit=limit or 10)
366
+ return {"query": q, "hits": len(rows), "results": rows}
367
+
368
+
369
+ @tool("koha_item",
370
+ "One catalogue record by biblionumber: item table (placering, status, item type) and the "
371
+ "record summary (publisher, edition, language). Read-only.",
372
+ {"biblionumber": S}, ("biblionumber",))
373
+ def koha_item(biblionumber):
374
+ from . import koha
375
+ return koha.availability(biblionumber)
376
+
377
+
378
+ @tool("koha_loans",
379
+ "Your own Koha account: loans with due dates and reservations with queue position. Needs "
380
+ "~/.secrets/KOHA_USER and ~/.secrets/KOHA_PIN (you create them; never printed). Read-only: "
381
+ "no renewal, no reservation changes.",
382
+ {})
383
+ def koha_loans():
384
+ from . import koha
385
+ return koha.loans()
386
+
387
+
388
+ @tool("koha_open_login",
389
+ "Open the library account page in the proxied Chrome window and report whether the "
390
+ "session is signed in. For the one-time manual sign-in; after that koha_loans reads "
391
+ "the account from the session cookie.",
392
+ {})
393
+ def koha_open_login():
394
+ from . import koha
395
+ return koha.open_login()
396
+
397
+
398
+ @tool("koha_wait_login",
399
+ "Wait until the library account page shows a signed-in session, for the one-time manual "
400
+ "sign-in in the proxied Chrome window. After that koha_loans needs no credentials.",
401
+ {"timeout": I})
402
+ def koha_wait_login(timeout=300):
403
+ from . import koha
404
+ return {"result": koha.wait_for_login(timeout=timeout or 300)}
405
+
406
+
407
+ @tool("koha_status",
408
+ "Diagnostics for the Koha path: whether the proxied browser and the local chain proxy are "
409
+ "up, and whether library credentials are on file.",
410
+ {})
411
+ def koha_status():
412
+ from . import koha
413
+ return koha.status()
414
+
415
+
416
+ # ---------------------------------------------------------- Open research APIs
417
+
418
+ @tool("db_list",
419
+ "List the subscription databases Sophiahemmet gives access to (CINAHL, PsycInfo, "
420
+ "Cochrane, Web of Science, JCR, Sage Research Methods, NE, PubMed) and whether each "
421
+ "one can be searched from here.",
422
+ {})
423
+ def db_list():
424
+ from . import databases
425
+ return {"databases": databases.catalogue()}
426
+
427
+
428
+ @tool("db_status",
429
+ "Check whether the school sign-in still works for a database (default cinahl). "
430
+ "authenticated=false means the Entra session expired and someone has to sign in once "
431
+ "in the school browser.",
432
+ {"database": S})
433
+ def db_status(database="cinahl"):
434
+ from . import databases
435
+ return databases.status(database or "cinahl")
436
+
437
+
438
+ @tool("db_search",
439
+ "Search a subscription database (cinahl, psycinfo) and return citations: title, "
440
+ "authors, journal, year, volume, issue, pages, subjects, peer-reviewed, full-text, "
441
+ "record URL. A bare multi-word query is joined with AND; quotes keep a phrase.",
442
+ {"database": S, "query": S, "limit": I})
443
+ def db_search(database, query, limit=10):
444
+ from . import databases
445
+ if not query:
446
+ raise ValueError("query is required")
447
+ return databases.search(database or "cinahl", query, limit=limit or 10)
448
+
449
+
450
+ @tool("db_detail",
451
+ "Open one database record and return its abstract, DOI, authors and source line. "
452
+ "Pass the record URL from db_search.",
453
+ {"url": S})
454
+ def db_detail(url):
455
+ from . import databases
456
+ if not url:
457
+ raise ValueError("url is required")
458
+ return databases.detail(url)
459
+
460
+
461
+ @tool("db_open",
462
+ "Open one database in the school browser and report where it landed. For the "
463
+ "databases that have no structured search here (Cochrane, Web of Science, JCR, Sage, "
464
+ "NE) and for signing in when the session has expired.",
465
+ {"database": S})
466
+ def db_open(database):
467
+ from . import databases
468
+ return databases.open_database(database)
469
+
470
+
471
+ @tool("db_fulltext",
472
+ "Full text of one article, by DOI, through the school's subscription (EZproxy). Saves "
473
+ "the PDF under ~/.local/share/unitoolkit/fulltext and returns path, pages and the "
474
+ "extracted text. Says why when there is no route (publisher outside the proxy: order "
475
+ "it via fjärrlån; or an open-access copy exists). Capped at 20 downloads an hour: the "
476
+ "licences allow reading for study, not bulk downloading.",
477
+ {"doi": S, "text": B})
478
+ def db_fulltext(doi, text=True):
479
+ from . import fulltext
480
+ if not doi:
481
+ raise ValueError("doi is required")
482
+ return fulltext.fetch(doi, text=True if text is None else bool(text))
483
+
484
+
485
+ @tool("find_sources",
486
+ "THE citation tool: one query across several databases (default cinahl, pubmed, "
487
+ "cochrane; also psycinfo, wos), deduplicated by DOI, each hit with an APA 7 reference "
488
+ "built from the publisher's own DOI metadata. Use this for 'find me sources on X'.",
489
+ {"query": S, "databases": {"type": "array", "items": S}, "limit": I}, ["query"])
490
+ def find_sources(query, databases=None, limit=5):
491
+ from . import citation
492
+ return citation.find_sources(query, tuple(databases or ("cinahl", "pubmed", "cochrane")),
493
+ limit=limit or 5)
494
+
495
+
496
+ @tool("apa",
497
+ "APA 7 reference for a DOI, from the DOI registry (not from scraped pages). lang='sv' "
498
+ "for svensk APA wording.",
499
+ {"doi": S, "lang": S}, ["doi"])
500
+ def apa(doi, lang="en"):
501
+ from . import citation
502
+ return {"doi": citation.clean_doi(doi), "apa": citation.apa(doi, lang or "en")}
503
+
504
+
505
+ @tool("pubmed", "Search PubMed. Returns PMID, title, journal, year, authors, DOI.",
506
+ {"query": S, "max": I}, ["query"])
507
+ def pubmed(query, max=10):
508
+ import urllib.parse
509
+ E = "https://eutils.ncbi.nlm.nih.gov/entrez/eutils/"
510
+ q = urllib.parse.urlencode({"db": "pubmed", "term": query, "retmax": max, "retmode": "json",
511
+ "sort": "relevance"}) # E-utilities default is newest first
512
+ with urllib.request.urlopen(E + "esearch.fcgi?" + q, timeout=30) as r:
513
+ ids = json.load(r)["esearchresult"]["idlist"]
514
+ if not ids:
515
+ return []
516
+ q = urllib.parse.urlencode({"db": "pubmed", "id": ",".join(ids), "retmode": "json"})
517
+ with urllib.request.urlopen(E + "esummary.fcgi?" + q, timeout=30) as r:
518
+ res = json.load(r)["result"]
519
+ out = []
520
+ for i in ids:
521
+ x = res.get(i, {})
522
+ doi = next((a["value"] for a in x.get("articleids", []) if a.get("idtype") == "doi"), None)
523
+ out.append({"pmid": i, "title": x.get("title"), "journal": x.get("fulljournalname"),
524
+ "year": (x.get("pubdate") or "")[:4], "doi": doi,
525
+ "authors": [a.get("name") for a in x.get("authors", [])]})
526
+ return out
527
+
528
+
529
+ @tool("libris", "Search Libris (Swedish union catalogue) for books: title, author, year, "
530
+ "publisher, ISBN. Use to verify a course-book reference.", {"query": S, "max": I}, ["query"])
531
+ def libris(query, max=10):
532
+ import urllib.parse
533
+ q = urllib.parse.urlencode({"query": query, "format": "json", "n": max})
534
+ with urllib.request.urlopen("https://libris.kb.se/xsearch?" + q, timeout=30) as r:
535
+ d = json.load(r)
536
+ out = []
537
+ for x in d.get("xsearch", {}).get("list", []):
538
+ out.append({"title": x.get("title"), "creator": x.get("creator"), "date": x.get("date"),
539
+ "publisher": x.get("publisher"), "isbn": x.get("isbn"),
540
+ "type": x.get("type"), "url": x.get("identifier")})
541
+ return out
542
+
543
+
544
+ # ---------------------------------------------------------- dispatch
545
+
546
+ def call(name, args=None):
547
+ if name not in TOOLS:
548
+ raise KeyError(f"unknown tool {name!r}; have {sorted(TOOLS)}")
549
+ return TOOLS[name]["fn"](**(args or {}))
550
+
551
+
552
+ def manifest(names=None):
553
+ """Tool schemas. names=None: every tool (tools.json); a list: only those, in that order."""
554
+ pick = TOOLS.values() if names is None else [TOOLS[n] for n in names if n in TOOLS]
555
+ return [{k: v for k, v in t.items() if k != "fn"} for t in pick]