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.
@@ -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,30 @@
1
+ tools.json,sha256=H_QNevftqZ7h-xhfDQoApyEHGWgSR9gPS9SjOVOwxKQ,16198
2
+ ladok_vakt/__init__.py,sha256=zXYUMkTpZ9Z6yyNbEb3QG6fHaSiVgpJBuXFlMWUzah0,261
3
+ ladok_vakt/__main__.py,sha256=rNi2GS925FBaePsNF4r3Ustt9DWyep3dgQrQQcIOTi8,1651
4
+ ladok_vakt/core.py,sha256=4KKAsg5rwmplsBpdqZWAH_rhDBOqEk94mg11DaL0vwE,20957
5
+ ladok_vakt/login.py,sha256=9XE4lwDA3Wgp2fW-8JZPBR9_eyhiueq9-QJwXmf9P50,12443
6
+ unitoolkit/__init__.py,sha256=RaANGbRu5e-vehwXI1-Qe2ggPPfs1TQaZj072JdbLk4,22
7
+ unitoolkit/__main__.py,sha256=iDZymWuk1gelNKRp5bncgbumrQc-YpCGIoQ1h-yJI-Q,1788
8
+ unitoolkit/agent.py,sha256=Ie02cE1XKCJzeyw-rO54_-vdrldfX7hJ5n4qWb92FuQ,11796
9
+ unitoolkit/browser.py,sha256=TMh5JqQN2_Ambvye2m4g7alrn-bO8lcYfP4U2yGtchI,5402
10
+ unitoolkit/canvas.py,sha256=biC1ZMcpMWbrMsenWnEfaVSF8TqImcte1SOOOL9lzRw,8096
11
+ unitoolkit/chainproxy.py,sha256=jujJDhfSZzO4lC7t1mjG0v5rr5_5pS8G7cFOCvwbKtg,4140
12
+ unitoolkit/citation.py,sha256=8cH2r3D7QT3CoIz3jIDTe7rk2u3zt56eh3GQnGQ6b1U,7456
13
+ unitoolkit/databases.py,sha256=WYpBkSP2UIH7JFPxSCToR0iJonqxejG-IyHbUE2MU4k,21893
14
+ unitoolkit/docs.py,sha256=OUMT47miAENYPwFZd-86bsFAZblO2TmzSTdsV4WxNCU,15767
15
+ unitoolkit/fulltext.py,sha256=JuccCIMitN3oAnjZf8drWiDpifia6qs7B3syH7ye8Uc,11665
16
+ unitoolkit/koha.py,sha256=JFY_oGEzugYDmM54LvkOrnapH7andmpOPP6fIQBBpd8,31605
17
+ unitoolkit/mcp.py,sha256=VmT5GsPcyLH0vdeojccqaNZPaP6S3y0F2xQRRlWkTH4,3397
18
+ unitoolkit/programme.py,sha256=naD27VepgbB7YGTUypqdFnY_14MkWN3QGGNaUEVXRsY,5824
19
+ unitoolkit/search.py,sha256=5SpDUxNZFdbtqqr0__jdv4KZPKtfoww0fJpJpa_jd5g,20892
20
+ unitoolkit/serve.py,sha256=L9fQ3j5BYYBu00cCWbK9kEe-9wwcW8aiWCsUz7VREcM,6460
21
+ unitoolkit/sharepoint.py,sha256=mpwc9c3zqNELwBv3AOAWVhulDIi6Pvo6dxlj8aUHj5A,3183
22
+ unitoolkit/surface.py,sha256=l-8WWgPriFuKyvaRpI-KpeYyl09DQt70bHCJkmC_hTE,4458
23
+ unitoolkit/timeedit.py,sha256=A2nYA1uGabBznXHZk5-HEoVA3-bIJEjcSAw86iYBRRA,10169
24
+ unitoolkit/tools.py,sha256=pCG7rbSdRqrvLmeKtweaPCf7EIoXg3FXcCgVbtNF0Qo,24808
25
+ unitoolkit-0.7.0.dist-info/licenses/LICENSE,sha256=YmWyvGq5O6PaiQ-XCyHtASY10wZHTI-c3MfWduX4QiU,1065
26
+ unitoolkit-0.7.0.dist-info/METADATA,sha256=YbN20TxObEIeaBT80I0pzJOP0nheC3DGPN7_6_yfO0c,9569
27
+ unitoolkit-0.7.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
28
+ unitoolkit-0.7.0.dist-info/entry_points.txt,sha256=yrhPCj3fPY4hyEQdoJFfg3pgQwduL_4Q0CMa7Fcf1zc,143
29
+ unitoolkit-0.7.0.dist-info/top_level.txt,sha256=wEvI5VqVPcIDkbT_EKPhK_THAmRicTbVA14y_Y3Kuts,22
30
+ unitoolkit-0.7.0.dist-info/RECORD,,
@@ -0,0 +1,5 @@
1
+ Wheel-Version: 1.0
2
+ Generator: setuptools (84.2.1)
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
5
+
@@ -0,0 +1,4 @@
1
+ [console_scripts]
2
+ unitoolkit = unitoolkit.__main__:cli
3
+ unitoolkit-chainproxy = unitoolkit.chainproxy:main
4
+ unitoolkit-mcp = unitoolkit.mcp:main
@@ -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,2 @@
1
+ ladok_vakt
2
+ unitoolkit