unitoolkit 0.7.0__tar.gz

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.
Files changed (45) hide show
  1. unitoolkit-0.7.0/LICENSE +21 -0
  2. unitoolkit-0.7.0/PKG-INFO +177 -0
  3. unitoolkit-0.7.0/README.md +149 -0
  4. unitoolkit-0.7.0/pyproject.toml +49 -0
  5. unitoolkit-0.7.0/setup.cfg +4 -0
  6. unitoolkit-0.7.0/tests/test_agent.py +56 -0
  7. unitoolkit-0.7.0/tests/test_announcements.py +49 -0
  8. unitoolkit-0.7.0/tests/test_citation.py +33 -0
  9. unitoolkit-0.7.0/tests/test_databases.py +62 -0
  10. unitoolkit-0.7.0/tests/test_docs.py +110 -0
  11. unitoolkit-0.7.0/tests/test_fulltext.py +59 -0
  12. unitoolkit-0.7.0/tests/test_koha.py +94 -0
  13. unitoolkit-0.7.0/tests/test_search.py +205 -0
  14. unitoolkit-0.7.0/tests/test_sharepoint.py +64 -0
  15. unitoolkit-0.7.0/tests/test_timeedit.py +42 -0
  16. unitoolkit-0.7.0/tools.json +623 -0
  17. unitoolkit-0.7.0/unitoolkit/__init__.py +1 -0
  18. unitoolkit-0.7.0/unitoolkit/__main__.py +63 -0
  19. unitoolkit-0.7.0/unitoolkit/agent.py +270 -0
  20. unitoolkit-0.7.0/unitoolkit/browser.py +147 -0
  21. unitoolkit-0.7.0/unitoolkit/canvas.py +189 -0
  22. unitoolkit-0.7.0/unitoolkit/chainproxy.py +113 -0
  23. unitoolkit-0.7.0/unitoolkit/citation.py +165 -0
  24. unitoolkit-0.7.0/unitoolkit/databases.py +497 -0
  25. unitoolkit-0.7.0/unitoolkit/docs.py +394 -0
  26. unitoolkit-0.7.0/unitoolkit/fulltext.py +260 -0
  27. unitoolkit-0.7.0/unitoolkit/koha.py +729 -0
  28. unitoolkit-0.7.0/unitoolkit/mcp.py +85 -0
  29. unitoolkit-0.7.0/unitoolkit/programme.py +147 -0
  30. unitoolkit-0.7.0/unitoolkit/search.py +507 -0
  31. unitoolkit-0.7.0/unitoolkit/serve.py +153 -0
  32. unitoolkit-0.7.0/unitoolkit/sharepoint.py +86 -0
  33. unitoolkit-0.7.0/unitoolkit/surface.py +86 -0
  34. unitoolkit-0.7.0/unitoolkit/timeedit.py +209 -0
  35. unitoolkit-0.7.0/unitoolkit/tools.py +555 -0
  36. unitoolkit-0.7.0/unitoolkit.egg-info/PKG-INFO +177 -0
  37. unitoolkit-0.7.0/unitoolkit.egg-info/SOURCES.txt +43 -0
  38. unitoolkit-0.7.0/unitoolkit.egg-info/dependency_links.txt +1 -0
  39. unitoolkit-0.7.0/unitoolkit.egg-info/entry_points.txt +4 -0
  40. unitoolkit-0.7.0/unitoolkit.egg-info/requires.txt +9 -0
  41. unitoolkit-0.7.0/unitoolkit.egg-info/top_level.txt +2 -0
  42. unitoolkit-0.7.0/vendor/ladok-vakt/ladok_vakt/__init__.py +7 -0
  43. unitoolkit-0.7.0/vendor/ladok-vakt/ladok_vakt/__main__.py +51 -0
  44. unitoolkit-0.7.0/vendor/ladok-vakt/ladok_vakt/core.py +553 -0
  45. unitoolkit-0.7.0/vendor/ladok-vakt/ladok_vakt/login.py +232 -0
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 vhsgreed
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,177 @@
1
+ Metadata-Version: 2.4
2
+ Name: unitoolkit
3
+ Version: 0.7.0
4
+ Summary: Read-only tools an agent needs to run a Swedish university student's week: Canvas, Ladok, TimeEdit, the library, and the subscribed research databases, with APA citations
5
+ Author: vhsgreed
6
+ License: MIT
7
+ Project-URL: Homepage, https://github.com/vhsgreed/shh-study-kit
8
+ Project-URL: Issues, https://github.com/vhsgreed/shh-study-kit/issues
9
+ Project-URL: Source, https://github.com/vhsgreed/shh-study-kit
10
+ Keywords: canvas,ladok,timeedit,koha,library,cinahl,cochrane,pubmed,apa,citations,student,university,sweden,nursing,mcp,agent
11
+ Classifier: Programming Language :: Python :: 3
12
+ Classifier: License :: OSI Approved :: MIT License
13
+ Classifier: Operating System :: OS Independent
14
+ Classifier: Topic :: Education
15
+ Classifier: Environment :: Console
16
+ Classifier: Intended Audience :: Education
17
+ Requires-Python: >=3.9
18
+ Description-Content-Type: text/markdown
19
+ License-File: LICENSE
20
+ Requires-Dist: websockets>=10
21
+ Provides-Extra: docs
22
+ Requires-Dist: pdftotext; extra == "docs"
23
+ Provides-Extra: dev
24
+ Requires-Dist: pytest>=7; extra == "dev"
25
+ Requires-Dist: build; extra == "dev"
26
+ Requires-Dist: twine; extra == "dev"
27
+ Dynamic: license-file
28
+
29
+ # unitoolkit
30
+
31
+ **Your agent, inside your university.** Canvas, Ladok, the timetable, the library and the
32
+ subscribed research databases, behind one MCP server, with APA references built from the
33
+ publisher's own metadata. Read-only. Built for a nursing student at Sophiahemmet Högskola in
34
+ Stockholm; the Canvas, Ladok and TimeEdit parts fit any Swedish university.
35
+
36
+ [![PyPI](https://img.shields.io/pypi/v/unitoolkit.svg)](https://pypi.org/project/unitoolkit/)
37
+ [![Python](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://pypi.org/project/unitoolkit/)
38
+ [![Tests](https://img.shields.io/badge/tests-89%20offline-brightgreen.svg)](#tests)
39
+ [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
40
+
41
+ The point is one endpoint. A student should be able to say *"what do I need to do this week"*,
42
+ *"find me three peer-reviewed sources on delirium prevention, in APA"*, or *"get me that
43
+ article"*, and have the agent work it out, without the student learning which of six systems
44
+ holds what answer.
45
+
46
+ ## Install
47
+
48
+ ```bash
49
+ pip install unitoolkit # library, CLI and MCP server
50
+ uvx --from unitoolkit unitoolkit-mcp # or run the server without installing
51
+
52
+ claude mcp add unitoolkit -- unitoolkit-mcp # Claude Code
53
+ codex mcp add unitoolkit -- unitoolkit-mcp # Codex
54
+ ```
55
+
56
+ For Hermes, Cursor or any other MCP client the command is `unitoolkit-mcp` (stdio). The server
57
+ lists **eleven question-shaped tools** by default; `UNITOOLKIT_TOOLS=all` lists all 38, and every
58
+ tool stays callable by name either way.
59
+
60
+ ## Ask it this
61
+
62
+ | You say | The agent calls | The answer comes from |
63
+ |---|---|---|
64
+ | "What do I need to do?" | `today` | Canvas deadlines not yet submitted, Ladok registration windows open or opening, this week's timetable |
65
+ | "Find me sources on X, APA" | `find_sources` | CINAHL + PubMed + Cochrane (+ PsycInfo, Web of Science), deduplicated by DOI |
66
+ | "Get me that article" | `db_fulltext doi=` | the PDF, through the school's subscription |
67
+ | "What does the assignment ask?" | `assignment`, `search` | Canvas description and rubric |
68
+ | "Did a teacher post anything?" | `announcements`, `discussions` | announcements with body text, and unread discussion threads |
69
+ | "When is the seminar?" | `schedule query=1SPRY2` | TimeEdit, any course or student group, any period |
70
+ | "Is a room free tomorrow?" | `free_rooms` | the TimeEdit booking guide, within the booking rules |
71
+ | "Is the book in?" / "When are my books due?" | `library query=` / `library` | the catalogue, and the student's own account |
72
+ | "Something is broken" | `doctor` | every session and credential, each failing row with the human fix |
73
+
74
+ ## What it covers
75
+
76
+ | System | Read | Notes |
77
+ |---|---|---|
78
+ | **Canvas** | courses, assignments with rubrics, modules, pages, discussions, files, everything due, full-text search across a course and its documents | Any Canvas school (`CANVAS_BASE`). SHH disables the pages index; pages are read through module items. |
79
+ | **Ladok** | course and exam registration windows, with days to open and close | Studentwebb has no API for students, so this reads the same endpoints the page does, on the student's own session. |
80
+ | **TimeEdit** | any course code's or student group's schedule for any period; the student-bookable rooms and their free gaps | The public guide needs no login. The room list needs the school SSO once, then it is cached. |
81
+ | **Library (Koha)** | catalogue search, availability per copy, own loans with due dates, holds, fines | Needs a browser; where the library drops your IP, also a proxy (below). |
82
+ | **Databases** | CINAHL and PsycInfo (EBSCOhost), Cochrane, Web of Science, plus PubMed and Libris | Everything subscription sits behind the school's OCLC EZproxy: one sign-in covers all of them. |
83
+ | **Citations** | APA 7 from a DOI, a DOI from a title | APA comes from the DOI registry, not from scraped search cards. |
84
+
85
+ ## What it refuses
86
+
87
+ - **Nothing is written.** No submissions, no registrations, no bookings, no renewals, no
88
+ messages. Every call is a read.
89
+ - **No passwords.** The tools never type, store, print or log one. They use a browser session a
90
+ human signed in to, once, and `doctor` says when that session needs renewing.
91
+ - **No bulk downloading.** `db_fulltext` stops at 20 articles an hour. Publishers detect
92
+ systematic downloading and block the institution's whole proxy, which would cut off every
93
+ student at the school. The cap is a licence rule, not a tuning knob.
94
+ - **No telemetry.** Nothing about your data leaves the machine.
95
+
96
+ ## Setup (once, by the human)
97
+
98
+ 1. **Canvas token**: Account → Settings → New access token → `~/.secrets/CANVAS_TOKEN` (0600).
99
+ Tokens expire silently; `doctor` reads the real expiry date from Canvas and warns at 14 days.
100
+ 2. **Agent browser**, its own profile, never the everyday one:
101
+ ```bash
102
+ google-chrome --user-data-dir="$HOME/.cache/unitoolkit-chrome" --remote-debugging-port=9233
103
+ ```
104
+ 3. **Sign in once** in that window to Canvas, Ladok, the school SSO and the library. The session
105
+ cookies then carry every tool; `doctor` says which one has lapsed.
106
+ 4. **Optional**: `UNITOOLKIT_GROUP=H26SK` (your student group) so `today` can show the cohort's
107
+ timetable. `KOHA_PROXY=0` if your network reaches the library directly.
108
+
109
+ The library is the one system that may need more than a login: it drops some home IPs on port
110
+ 443 and answers plain HTTP clients with a Cloudflare 429, so the only reader is a real browser,
111
+ and where the IP is dropped, a proxy. `python -m unitoolkit.chainproxy` starts a local chaining
112
+ proxy (upstream from `CHAIN_UPSTREAM_*`, password from `CHAIN_UPSTREAM_PASSWORD_FILE`); Chrome
113
+ then runs with `--proxy-server=http://127.0.0.1:8118`. The proxy exit must be **sticky**: Koha
114
+ binds a session to the client IP.
115
+
116
+ ## Health
117
+
118
+ - `unitoolkit doctor`: every session and credential, each failing row with the human fix.
119
+ - `python scripts/smoke.py`: one real query per reader, silent when all pass. Run it weekly.
120
+
121
+ Readers are scrapers, so they break when a site redesigns. A silent break is worse than a loud
122
+ one, which is why the smoke test speaks only when something is wrong.
123
+
124
+ ## Tests
125
+
126
+ 89 offline tests, no network: `python -m pytest tests -q`.
127
+
128
+ ## Extend it
129
+
130
+ One decorated function in [`unitoolkit/tools.py`](unitoolkit/tools.py) appears in the CLI, the
131
+ MCP server and `tools.json` at once. [`skill/SKILL.md`](skill/SKILL.md) is written for an agent:
132
+ the tool table and every gotcha found while building this, from Canvas rubric quirks to the Koha
133
+ login that binds a session to your IP.
134
+
135
+ ## Subrepo: ladok-vakt
136
+
137
+ [`vendor/ladok-vakt`](vendor/ladok-vakt) is a git subtree of
138
+ [ladok-vakt](https://github.com/vhsgreed/ladok-vakt): mejl när Ladok-anmälan öppnar (email
139
+ alerts for registration windows). It is here because Canvas answers "what is due" and Ladok
140
+ answers "what can I still register for", and a student needs both. Sync it with:
141
+
142
+ ```bash
143
+ git subtree pull --prefix=vendor/ladok-vakt https://github.com/vhsgreed/ladok-vakt main --squash
144
+ ```
145
+
146
+ `ladok_windows` is a thin read-only wrapper around it. Run the watcher itself (mail, cron) from
147
+ the standalone repo.
148
+
149
+ ## Status
150
+
151
+ In daily use against live systems by one nursing student, 2026. Honest limits:
152
+
153
+ - **Sweden, not the world.** Canvas is generic, Ladok is Swedish, and the school-specific hosts
154
+ (library, EZproxy, TimeEdit guide ids) are constants you change for your own school.
155
+ - **Readers are scrapers.** CINAHL, Cochrane, Web of Science and Koha are read through their
156
+ pages, not APIs, so a redesign breaks them. Hence the smoke test.
157
+ - **APA keeps the publisher's title case**; APA 7 wants sentence case for article titles. The
158
+ tool flags this rather than lowercasing by rule, because acronyms and proper nouns break.
159
+ - **Not verified at another school.** If it works for you elsewhere, say so.
160
+
161
+ ## License
162
+
163
+ MIT, for the software only. Course material, articles and library data stay under their own
164
+ licences and belong to whoever owns them.
165
+
166
+ ---
167
+
168
+ <sub>
169
+
170
+ **In honour of Xom**, god of chaos, who answers prayers with teleport traps and grants
171
+ wishes nobody made. This kit was written in that spirit: a student asked for a deadline
172
+ list and an agent mapped six terms of a nursing programme. Xom finds the whole arrangement
173
+ very funny. Xom is not done with you.
174
+
175
+ *Xom is interested. Point your agent at the repo and see what happens.*
176
+
177
+ </sub>
@@ -0,0 +1,149 @@
1
+ # unitoolkit
2
+
3
+ **Your agent, inside your university.** Canvas, Ladok, the timetable, the library and the
4
+ subscribed research databases, behind one MCP server, with APA references built from the
5
+ publisher's own metadata. Read-only. Built for a nursing student at Sophiahemmet Högskola in
6
+ Stockholm; the Canvas, Ladok and TimeEdit parts fit any Swedish university.
7
+
8
+ [![PyPI](https://img.shields.io/pypi/v/unitoolkit.svg)](https://pypi.org/project/unitoolkit/)
9
+ [![Python](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://pypi.org/project/unitoolkit/)
10
+ [![Tests](https://img.shields.io/badge/tests-89%20offline-brightgreen.svg)](#tests)
11
+ [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
12
+
13
+ The point is one endpoint. A student should be able to say *"what do I need to do this week"*,
14
+ *"find me three peer-reviewed sources on delirium prevention, in APA"*, or *"get me that
15
+ article"*, and have the agent work it out, without the student learning which of six systems
16
+ holds what answer.
17
+
18
+ ## Install
19
+
20
+ ```bash
21
+ pip install unitoolkit # library, CLI and MCP server
22
+ uvx --from unitoolkit unitoolkit-mcp # or run the server without installing
23
+
24
+ claude mcp add unitoolkit -- unitoolkit-mcp # Claude Code
25
+ codex mcp add unitoolkit -- unitoolkit-mcp # Codex
26
+ ```
27
+
28
+ For Hermes, Cursor or any other MCP client the command is `unitoolkit-mcp` (stdio). The server
29
+ lists **eleven question-shaped tools** by default; `UNITOOLKIT_TOOLS=all` lists all 38, and every
30
+ tool stays callable by name either way.
31
+
32
+ ## Ask it this
33
+
34
+ | You say | The agent calls | The answer comes from |
35
+ |---|---|---|
36
+ | "What do I need to do?" | `today` | Canvas deadlines not yet submitted, Ladok registration windows open or opening, this week's timetable |
37
+ | "Find me sources on X, APA" | `find_sources` | CINAHL + PubMed + Cochrane (+ PsycInfo, Web of Science), deduplicated by DOI |
38
+ | "Get me that article" | `db_fulltext doi=` | the PDF, through the school's subscription |
39
+ | "What does the assignment ask?" | `assignment`, `search` | Canvas description and rubric |
40
+ | "Did a teacher post anything?" | `announcements`, `discussions` | announcements with body text, and unread discussion threads |
41
+ | "When is the seminar?" | `schedule query=1SPRY2` | TimeEdit, any course or student group, any period |
42
+ | "Is a room free tomorrow?" | `free_rooms` | the TimeEdit booking guide, within the booking rules |
43
+ | "Is the book in?" / "When are my books due?" | `library query=` / `library` | the catalogue, and the student's own account |
44
+ | "Something is broken" | `doctor` | every session and credential, each failing row with the human fix |
45
+
46
+ ## What it covers
47
+
48
+ | System | Read | Notes |
49
+ |---|---|---|
50
+ | **Canvas** | courses, assignments with rubrics, modules, pages, discussions, files, everything due, full-text search across a course and its documents | Any Canvas school (`CANVAS_BASE`). SHH disables the pages index; pages are read through module items. |
51
+ | **Ladok** | course and exam registration windows, with days to open and close | Studentwebb has no API for students, so this reads the same endpoints the page does, on the student's own session. |
52
+ | **TimeEdit** | any course code's or student group's schedule for any period; the student-bookable rooms and their free gaps | The public guide needs no login. The room list needs the school SSO once, then it is cached. |
53
+ | **Library (Koha)** | catalogue search, availability per copy, own loans with due dates, holds, fines | Needs a browser; where the library drops your IP, also a proxy (below). |
54
+ | **Databases** | CINAHL and PsycInfo (EBSCOhost), Cochrane, Web of Science, plus PubMed and Libris | Everything subscription sits behind the school's OCLC EZproxy: one sign-in covers all of them. |
55
+ | **Citations** | APA 7 from a DOI, a DOI from a title | APA comes from the DOI registry, not from scraped search cards. |
56
+
57
+ ## What it refuses
58
+
59
+ - **Nothing is written.** No submissions, no registrations, no bookings, no renewals, no
60
+ messages. Every call is a read.
61
+ - **No passwords.** The tools never type, store, print or log one. They use a browser session a
62
+ human signed in to, once, and `doctor` says when that session needs renewing.
63
+ - **No bulk downloading.** `db_fulltext` stops at 20 articles an hour. Publishers detect
64
+ systematic downloading and block the institution's whole proxy, which would cut off every
65
+ student at the school. The cap is a licence rule, not a tuning knob.
66
+ - **No telemetry.** Nothing about your data leaves the machine.
67
+
68
+ ## Setup (once, by the human)
69
+
70
+ 1. **Canvas token**: Account → Settings → New access token → `~/.secrets/CANVAS_TOKEN` (0600).
71
+ Tokens expire silently; `doctor` reads the real expiry date from Canvas and warns at 14 days.
72
+ 2. **Agent browser**, its own profile, never the everyday one:
73
+ ```bash
74
+ google-chrome --user-data-dir="$HOME/.cache/unitoolkit-chrome" --remote-debugging-port=9233
75
+ ```
76
+ 3. **Sign in once** in that window to Canvas, Ladok, the school SSO and the library. The session
77
+ cookies then carry every tool; `doctor` says which one has lapsed.
78
+ 4. **Optional**: `UNITOOLKIT_GROUP=H26SK` (your student group) so `today` can show the cohort's
79
+ timetable. `KOHA_PROXY=0` if your network reaches the library directly.
80
+
81
+ The library is the one system that may need more than a login: it drops some home IPs on port
82
+ 443 and answers plain HTTP clients with a Cloudflare 429, so the only reader is a real browser,
83
+ and where the IP is dropped, a proxy. `python -m unitoolkit.chainproxy` starts a local chaining
84
+ proxy (upstream from `CHAIN_UPSTREAM_*`, password from `CHAIN_UPSTREAM_PASSWORD_FILE`); Chrome
85
+ then runs with `--proxy-server=http://127.0.0.1:8118`. The proxy exit must be **sticky**: Koha
86
+ binds a session to the client IP.
87
+
88
+ ## Health
89
+
90
+ - `unitoolkit doctor`: every session and credential, each failing row with the human fix.
91
+ - `python scripts/smoke.py`: one real query per reader, silent when all pass. Run it weekly.
92
+
93
+ Readers are scrapers, so they break when a site redesigns. A silent break is worse than a loud
94
+ one, which is why the smoke test speaks only when something is wrong.
95
+
96
+ ## Tests
97
+
98
+ 89 offline tests, no network: `python -m pytest tests -q`.
99
+
100
+ ## Extend it
101
+
102
+ One decorated function in [`unitoolkit/tools.py`](unitoolkit/tools.py) appears in the CLI, the
103
+ MCP server and `tools.json` at once. [`skill/SKILL.md`](skill/SKILL.md) is written for an agent:
104
+ the tool table and every gotcha found while building this, from Canvas rubric quirks to the Koha
105
+ login that binds a session to your IP.
106
+
107
+ ## Subrepo: ladok-vakt
108
+
109
+ [`vendor/ladok-vakt`](vendor/ladok-vakt) is a git subtree of
110
+ [ladok-vakt](https://github.com/vhsgreed/ladok-vakt): mejl när Ladok-anmälan öppnar (email
111
+ alerts for registration windows). It is here because Canvas answers "what is due" and Ladok
112
+ answers "what can I still register for", and a student needs both. Sync it with:
113
+
114
+ ```bash
115
+ git subtree pull --prefix=vendor/ladok-vakt https://github.com/vhsgreed/ladok-vakt main --squash
116
+ ```
117
+
118
+ `ladok_windows` is a thin read-only wrapper around it. Run the watcher itself (mail, cron) from
119
+ the standalone repo.
120
+
121
+ ## Status
122
+
123
+ In daily use against live systems by one nursing student, 2026. Honest limits:
124
+
125
+ - **Sweden, not the world.** Canvas is generic, Ladok is Swedish, and the school-specific hosts
126
+ (library, EZproxy, TimeEdit guide ids) are constants you change for your own school.
127
+ - **Readers are scrapers.** CINAHL, Cochrane, Web of Science and Koha are read through their
128
+ pages, not APIs, so a redesign breaks them. Hence the smoke test.
129
+ - **APA keeps the publisher's title case**; APA 7 wants sentence case for article titles. The
130
+ tool flags this rather than lowercasing by rule, because acronyms and proper nouns break.
131
+ - **Not verified at another school.** If it works for you elsewhere, say so.
132
+
133
+ ## License
134
+
135
+ MIT, for the software only. Course material, articles and library data stay under their own
136
+ licences and belong to whoever owns them.
137
+
138
+ ---
139
+
140
+ <sub>
141
+
142
+ **In honour of Xom**, god of chaos, who answers prayers with teleport traps and grants
143
+ wishes nobody made. This kit was written in that spirit: a student asked for a deadline
144
+ list and an agent mapped six terms of a nursing programme. Xom finds the whole arrangement
145
+ very funny. Xom is not done with you.
146
+
147
+ *Xom is interested. Point your agent at the repo and see what happens.*
148
+
149
+ </sub>
@@ -0,0 +1,49 @@
1
+ [build-system]
2
+ requires = ["setuptools>=61"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "unitoolkit"
7
+ version = "0.7.0"
8
+ description = "Read-only tools an agent needs to run a Swedish university student's week: Canvas, Ladok, TimeEdit, the library, and the subscribed research databases, with APA citations"
9
+ readme = "README.md"
10
+ requires-python = ">=3.9"
11
+ license = {text = "MIT"}
12
+ authors = [{name = "vhsgreed"}]
13
+ keywords = ["canvas", "ladok", "timeedit", "koha", "library", "cinahl", "cochrane", "pubmed",
14
+ "apa", "citations", "student", "university", "sweden", "nursing", "mcp", "agent"]
15
+ classifiers = [
16
+ "Programming Language :: Python :: 3",
17
+ "License :: OSI Approved :: MIT License",
18
+ "Operating System :: OS Independent",
19
+ "Topic :: Education",
20
+ "Environment :: Console",
21
+ "Intended Audience :: Education",
22
+ ]
23
+ # Every dependency is stdlib only, except the Chrome DevTools client: connecting to a modern
24
+ # Chrome needs a websocket client, and reimplementing one would be worse than this one line.
25
+ dependencies = ["websockets>=10"]
26
+
27
+ [project.optional-dependencies]
28
+ docs = ["pdftotext"] # optional: `docs` extracts PDF text via the pdftotext binary
29
+ dev = ["pytest>=7", "build", "twine"]
30
+
31
+ [project.urls]
32
+ Homepage = "https://github.com/vhsgreed/shh-study-kit"
33
+ Issues = "https://github.com/vhsgreed/shh-study-kit/issues"
34
+ Source = "https://github.com/vhsgreed/shh-study-kit"
35
+
36
+ [project.scripts]
37
+ unitoolkit = "unitoolkit.__main__:cli"
38
+ unitoolkit-mcp = "unitoolkit.mcp:main"
39
+ unitoolkit-chainproxy = "unitoolkit.chainproxy:main"
40
+
41
+ [tool.setuptools]
42
+ packages = ["unitoolkit", "ladok_vakt"]
43
+
44
+ [tool.setuptools.package-dir]
45
+ unitoolkit = "unitoolkit"
46
+ ladok_vakt = "vendor/ladok-vakt/ladok_vakt"
47
+
48
+ [tool.setuptools.package-data]
49
+ unitoolkit = ["../tools.json"]
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1,56 @@
1
+ """Offline tests for the agent surface: listing modes, date maths, partial failure."""
2
+
3
+ import sys
4
+ from pathlib import Path
5
+
6
+ sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
7
+
8
+ from unitoolkit import agent, mcp # noqa: E402
9
+ from unitoolkit.tools import TOOLS # noqa: E402
10
+
11
+
12
+ def test_core_tools_all_exist():
13
+ missing = [n for n in agent.CORE if n not in TOOLS]
14
+ assert not missing, missing
15
+
16
+
17
+ def test_listing_modes(monkeypatch):
18
+ monkeypatch.delenv('UNITOOLKIT_TOOLS', raising=False)
19
+ assert agent.listed(list(TOOLS)) == list(agent.CORE)
20
+ monkeypatch.setenv('UNITOOLKIT_TOOLS', 'all')
21
+ assert len(agent.listed(list(TOOLS))) == len(TOOLS)
22
+ monkeypatch.setenv('UNITOOLKIT_TOOLS', 'pubmed, apa, nope')
23
+ assert agent.listed(list(TOOLS)) == ['pubmed', 'apa']
24
+
25
+
26
+ def test_mcp_lists_core_but_calls_anything(monkeypatch):
27
+ monkeypatch.delenv('UNITOOLKIT_TOOLS', raising=False)
28
+ names = [t['name'] for t in mcp.handle({'method': 'tools/list', 'id': 1})['tools']]
29
+ assert names == list(agent.CORE)
30
+ # an unlisted tool is still callable by name (offline: apa with a bad DOI errors cleanly)
31
+ r = mcp.handle({'method': 'tools/call', 'id': 2, 'params': {'name': 'apa', 'arguments': {'doi': 'x'}}})
32
+ assert r['isError'] and 'not a DOI' in r['content'][0]['text']
33
+
34
+
35
+ def test_days():
36
+ import datetime as dt
37
+ base = dt.date(2026, 11, 17)
38
+ assert agent._days('2026-11-26T15:00:00Z', base) == 9
39
+ assert agent._days('', base) is None and agent._days('garbage', base) is None
40
+
41
+
42
+ def test_guard_keeps_going_after_a_failure():
43
+ ok = agent._guard(lambda: [1])
44
+ bad = agent._guard(lambda: (_ for _ in ()).throw(SystemExit(2)))
45
+ assert ok['ok'] and ok['data'] == [1]
46
+ assert bad['ok'] is False and 'SystemExit' in bad['error']
47
+
48
+
49
+ def test_doctor_reports_every_check_even_when_they_crash(monkeypatch):
50
+ def boom():
51
+ raise RuntimeError('down')
52
+ monkeypatch.setattr(agent, 'CHECKS', [('a', boom), ('b', lambda: ('ok', 'fine', ''))])
53
+ r = agent.doctor()
54
+ assert r['overall'] == 'fail'
55
+ assert [c['check'] for c in r['checks']] == ['a', 'b']
56
+ assert r['checks'][1]['status'] == 'ok'
@@ -0,0 +1,49 @@
1
+ """Announcements: the plain discussion list hides them, so the reader must ask explicitly."""
2
+ import time
3
+
4
+ from unitoolkit import canvas
5
+
6
+
7
+ def _row(i, posted, title='t'):
8
+ return {'id': i, 'title': title, 'posted_at': posted, 'author': {'display_name': 'A'},
9
+ 'html_url': 'u', 'message': 'body'}
10
+
11
+
12
+ def test_asks_for_announcements_only(monkeypatch):
13
+ seen = {}
14
+
15
+ def fake_try_get(path, **params):
16
+ seen['path'], seen['params'] = path, params
17
+ return [_row(1, time.strftime('%Y-%m-%dT%H:%M:%SZ', time.gmtime()))]
18
+
19
+ monkeypatch.setattr(canvas, 'try_get', fake_try_get)
20
+ out = canvas.announcements(course=2416, days=30)
21
+ assert seen['params']['only_announcements'] is True
22
+ assert '/courses/2416/discussion_topics' in seen['path']
23
+ assert len(out) == 1 and out[0]['author'] == 'A'
24
+
25
+
26
+ def test_newest_first_and_day_window(monkeypatch):
27
+ now = time.time()
28
+ rows = [_row(1, time.strftime('%Y-%m-%dT%H:%M:%SZ', time.gmtime(now - 40 * 86400)), 'old'),
29
+ _row(2, time.strftime('%Y-%m-%dT%H:%M:%SZ', time.gmtime(now - 86400)), 'new')]
30
+ monkeypatch.setattr(canvas, 'try_get', lambda *a, **k: rows)
31
+ out = canvas.announcements(course=2416, days=7)
32
+ assert [a['title'] for a in out] == ['new']
33
+
34
+
35
+ def test_empty_when_canvas_hides_them(monkeypatch):
36
+ monkeypatch.setattr(canvas, 'try_get', lambda *a, **k: [])
37
+ assert canvas.announcements(course=2416, days=30) == []
38
+
39
+
40
+ def test_discussions_skip_announcements_and_filter_read(monkeypatch):
41
+ rows = [{'id': 1, 'title': 'group discussion', 'read_state': 'unread',
42
+ 'discussion_subentry_count': 15, 'posted_at': '2026-11-10T10:00:00Z'},
43
+ {'id': 2, 'title': 'an announcement', 'is_announcement': True, 'read_state': 'read'},
44
+ {'id': 3, 'title': 'already read', 'read_state': 'read',
45
+ 'discussion_subentry_count': 2}]
46
+ monkeypatch.setattr(canvas, 'try_get', lambda *a, **k: rows)
47
+ got = canvas.discussions(course=2415, unread_only=True)
48
+ assert [d['title'] for d in got] == ['group discussion']
49
+ assert got[0]['entries'] == 15 and got[0]['read_state'] == 'unread'
@@ -0,0 +1,33 @@
1
+ """Offline tests for citation helpers."""
2
+
3
+ import sys
4
+ from pathlib import Path
5
+
6
+ sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
7
+
8
+ from unitoolkit import citation as c # noqa: E402
9
+
10
+
11
+ def test_clean_doi_strips_prefixes():
12
+ for raw in ('https://doi.org/10.1111/inr.13079', 'doi: 10.1111/inr.13079', '10.1111/inr.13079'):
13
+ assert c.clean_doi(raw) == '10.1111/inr.13079'
14
+
15
+
16
+ def test_relevance_prefers_on_topic_titles():
17
+ q = 'delirium prevention nursing'
18
+ on = {'title': 'Interventions for preventing delirium in older people'}
19
+ off = {'title': 'Neuraminidase inhibitors for preventing and treating influenza'}
20
+ assert c.relevance(q, on) > c.relevance(q, off)
21
+
22
+
23
+ def test_relevance_ignores_stopwords():
24
+ assert c.relevance('the and of', {'title': 'anything'}) == 0.0
25
+
26
+
27
+ def test_total_parses_non_breaking_space():
28
+ assert c._total('1\xa0012') == 1012
29
+ assert c._total('') is None
30
+
31
+
32
+ def test_dedupe_key_is_doi_case_insensitive():
33
+ assert c._key({'doi': '10.1002/14651858.CD005563'}) == c._key({'doi': '10.1002/14651858.cd005563'})
@@ -0,0 +1,62 @@
1
+ """Offline tests for the database layer: query normalisation and citation parsing."""
2
+
3
+ import sys
4
+ from pathlib import Path
5
+
6
+ sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
7
+
8
+ from unitoolkit import databases as db # noqa: E402
9
+
10
+
11
+ def test_bare_multiword_query_gets_and():
12
+ assert db._normalise_query('delirium older adults') == 'delirium AND older AND adults'
13
+
14
+
15
+ def test_explicit_operators_are_left_alone():
16
+ for q in ('delirium AND older', '"person-centred care" delirium', 'delirium OR confusion',
17
+ 'delirium NOT child', 'delirium N3 older'):
18
+ assert db._normalise_query(q) == q
19
+
20
+
21
+ def test_single_word_untouched():
22
+ assert db._normalise_query('delirium') == 'delirium'
23
+
24
+
25
+ def test_parse_source_reads_volume_issue_pages():
26
+ src = db.parse_source('In:Perfusion, Nov2026, volume 41, issue 8, pages 1492-1501 (10p)CINAHL')
27
+ assert src['journal'] == 'Perfusion'
28
+ assert src['year'] == '2026'
29
+ assert src['volume'] == '41'
30
+ assert src['issue'] == '8'
31
+ assert src['pages'] == '1492-1501'
32
+
33
+
34
+ def test_parse_source_handles_singular_page():
35
+ src = db.parse_source('In:Psychiatry International, Oct2026, volume 7, issue 5, page 235CINAHL')
36
+ assert (src['journal'], src['pages']) == ('Psychiatry International', '235')
37
+
38
+
39
+ def test_parse_source_drops_an_issn_so_it_is_not_read_as_a_year():
40
+ src = db.parse_source('Dementia (14713012), 2026, volume 25, issue 8, pages 2000-2019')
41
+ assert (src['journal'], src['year'], src['volume'], src['pages']) == (
42
+ 'Dementia', '2026', '25', '2000-2019')
43
+
44
+
45
+ def test_split_authors_strips_by_and_count():
46
+ got = db._split_authors('By:Güdel, Marion⁠;Grunt, Sebastian⁠; +1 more')
47
+ assert got == ['Güdel, Marion', 'Grunt, Sebastian']
48
+
49
+
50
+ def test_unknown_database_is_refused():
51
+ try:
52
+ db.search('upToDate', 'delirium')
53
+ except db.DatabaseError as exc:
54
+ assert 'unknown database' in str(exc)
55
+ else:
56
+ raise AssertionError('should have raised')
57
+
58
+
59
+ def test_catalogue_lists_the_nursing_databases():
60
+ keys = {d['key'] for d in db.catalogue()}
61
+ assert {'cinahl', 'psycinfo', 'cochrane', 'wos'} <= keys
62
+ assert db.catalogue()[0]['behind_ezproxy'] is True