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.
- unitoolkit-0.7.0/LICENSE +21 -0
- unitoolkit-0.7.0/PKG-INFO +177 -0
- unitoolkit-0.7.0/README.md +149 -0
- unitoolkit-0.7.0/pyproject.toml +49 -0
- unitoolkit-0.7.0/setup.cfg +4 -0
- unitoolkit-0.7.0/tests/test_agent.py +56 -0
- unitoolkit-0.7.0/tests/test_announcements.py +49 -0
- unitoolkit-0.7.0/tests/test_citation.py +33 -0
- unitoolkit-0.7.0/tests/test_databases.py +62 -0
- unitoolkit-0.7.0/tests/test_docs.py +110 -0
- unitoolkit-0.7.0/tests/test_fulltext.py +59 -0
- unitoolkit-0.7.0/tests/test_koha.py +94 -0
- unitoolkit-0.7.0/tests/test_search.py +205 -0
- unitoolkit-0.7.0/tests/test_sharepoint.py +64 -0
- unitoolkit-0.7.0/tests/test_timeedit.py +42 -0
- unitoolkit-0.7.0/tools.json +623 -0
- unitoolkit-0.7.0/unitoolkit/__init__.py +1 -0
- unitoolkit-0.7.0/unitoolkit/__main__.py +63 -0
- unitoolkit-0.7.0/unitoolkit/agent.py +270 -0
- unitoolkit-0.7.0/unitoolkit/browser.py +147 -0
- unitoolkit-0.7.0/unitoolkit/canvas.py +189 -0
- unitoolkit-0.7.0/unitoolkit/chainproxy.py +113 -0
- unitoolkit-0.7.0/unitoolkit/citation.py +165 -0
- unitoolkit-0.7.0/unitoolkit/databases.py +497 -0
- unitoolkit-0.7.0/unitoolkit/docs.py +394 -0
- unitoolkit-0.7.0/unitoolkit/fulltext.py +260 -0
- unitoolkit-0.7.0/unitoolkit/koha.py +729 -0
- unitoolkit-0.7.0/unitoolkit/mcp.py +85 -0
- unitoolkit-0.7.0/unitoolkit/programme.py +147 -0
- unitoolkit-0.7.0/unitoolkit/search.py +507 -0
- unitoolkit-0.7.0/unitoolkit/serve.py +153 -0
- unitoolkit-0.7.0/unitoolkit/sharepoint.py +86 -0
- unitoolkit-0.7.0/unitoolkit/surface.py +86 -0
- unitoolkit-0.7.0/unitoolkit/timeedit.py +209 -0
- unitoolkit-0.7.0/unitoolkit/tools.py +555 -0
- unitoolkit-0.7.0/unitoolkit.egg-info/PKG-INFO +177 -0
- unitoolkit-0.7.0/unitoolkit.egg-info/SOURCES.txt +43 -0
- unitoolkit-0.7.0/unitoolkit.egg-info/dependency_links.txt +1 -0
- unitoolkit-0.7.0/unitoolkit.egg-info/entry_points.txt +4 -0
- unitoolkit-0.7.0/unitoolkit.egg-info/requires.txt +9 -0
- unitoolkit-0.7.0/unitoolkit.egg-info/top_level.txt +2 -0
- unitoolkit-0.7.0/vendor/ladok-vakt/ladok_vakt/__init__.py +7 -0
- unitoolkit-0.7.0/vendor/ladok-vakt/ladok_vakt/__main__.py +51 -0
- unitoolkit-0.7.0/vendor/ladok-vakt/ladok_vakt/core.py +553 -0
- unitoolkit-0.7.0/vendor/ladok-vakt/ladok_vakt/login.py +232 -0
unitoolkit-0.7.0/LICENSE
ADDED
|
@@ -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
|
+
[](https://pypi.org/project/unitoolkit/)
|
|
37
|
+
[](https://pypi.org/project/unitoolkit/)
|
|
38
|
+
[](#tests)
|
|
39
|
+
[](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
|
+
[](https://pypi.org/project/unitoolkit/)
|
|
9
|
+
[](https://pypi.org/project/unitoolkit/)
|
|
10
|
+
[](#tests)
|
|
11
|
+
[](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,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
|