docket-client 0.3.2__py3-none-any.whl

docket_client-0.3.2.dist-info/METADATA

@@ -0,0 +1,233 @@
+Metadata-Version: 2.5
+Name: docket-client
+Version: 0.3.2
+Summary: Typed Python client for the docket scheduling API
+Project-URL: Homepage, https://github.com/AllenNeuralDynamics/docket
+Project-URL: Repository, https://github.com/AllenNeuralDynamics/docket
+Project-URL: Bug Tracker, https://github.com/AllenNeuralDynamics/docket/issues
+Project-URL: Changelog, https://github.com/AllenNeuralDynamics/docket/releases
+Author: Allen Institute for Neural Dynamics
+License-Expression: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.11
+Requires-Dist: attrs>=22.2.0
+Requires-Dist: httpx<0.29.0,>=0.23.1
+Provides-Extra: auth
+Requires-Dist: msal<2,>=1.31; extra == 'auth'
+Provides-Extra: mcp
+Requires-Dist: mcp<2,>=1.30; extra == 'mcp'
+Requires-Dist: msal<2,>=1.31; extra == 'mcp'
+Requires-Dist: tzdata>=2024.1; (sys_platform == 'win32') and extra == 'mcp'
+Requires-Dist: tzlocal<6,>=5; extra == 'mcp'
+Description-Content-Type: text/markdown
+
+# docket
+
+A typed Python client for the **docket** scheduling API.
+
+## Installation
+
+```bash
+pip install docket-client
+# the unreleased version, from the repository:
+pip install "docket-client @ git+https://github.com/AllenNeuralDynamics/docket#subdirectory=client"
+# or, from the repo root during development:
+pip install ./client
+```
+
+## Usage
+
+```python
+from docket import Client
+
+client = Client(base_url="http://localhost:8001")
+```
+
+For authenticated endpoints use `AuthenticatedClient`:
+
+```python
+from docket import AuthenticatedClient
+
+client = AuthenticatedClient(base_url="https://api.example.com", token="SuperSecretToken")
+```
+
+Call any endpoint:
+
+```python
+from docket.api.scheduled_acquisitions import list_active_acquisitions
+
+sessions = list_active_acquisitions.sync(
+    client=client,
+    instrument_id="BEH.B-Box1",
+    before_minutes=15,
+    effective_status=["scheduled", "ongoing"],
+)
+```
+
+Every endpoint module exposes four variants:
+
+| Function | Behaviour |
+| --- | --- |
+| `sync` | Blocking — returns the parsed response body or `None` |
+| `sync_detailed` | Blocking — always returns a `Response` object with status code, headers, and `parsed` |
+| `asyncio` | Async equivalent of `sync` |
+| `asyncio_detailed` | Async equivalent of `sync_detailed` |
+
+See [examples/downstream_usage.py](examples/downstream_usage.py) for a
+full end-to-end walkthrough.
+
+## MCP server (`docket-mcp`)
+
+`docket-mcp` lets an AI assistant (Claude Code, Claude Desktop, any MCP client) look at the
+schedule and change it, through the same API as everyone else. It runs **locally over stdio**:
+the client starts it on your machine, so it reaches Docket over your own network or VPN and
+nothing new is hosted. It is the `docket_mcp` package here, next to `docket_auth`.
+
+### Install
+
+```bash
+pip install "docket-client[mcp]"
+# or as an isolated tool (puts `docket-mcp` on your PATH):
+uv tool install "docket-client[mcp]"
+# from a checkout:
+uv tool install "./client[mcp]"
+```
+
+### Add it to your assistant
+
+Claude Code:
+
+```bash
+claude mcp add docket -e DOCKET_API_URL=http://localhost:8001 -e DOCKET_TIME_ZONE=America/Los_Angeles -- docket-mcp
+# with an API token (see "Sign-in"):
+claude mcp add docket -e DOCKET_API_URL=https://docket.example.org -e DOCKET_API_TOKEN=dkt_... -- docket-mcp
+# straight from a checkout, without installing:
+claude mcp add docket -e DOCKET_API_URL=http://localhost:8001 -- uv run --project ./client --extra mcp docket-mcp
+```
+
+Claude Desktop (`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "docket": {
+      "command": "docket-mcp",
+      "env": {
+        "DOCKET_API_URL": "http://localhost:8001",
+        "DOCKET_TIME_ZONE": "America/Los_Angeles",
+        "DOCKET_API_TOKEN": "dkt_..."
+      }
+    }
+  }
+}
+```
+
+If `docket-mcp` is not on the app's `PATH`, give its full path as `command`.
+
+### Configuration
+
+All through environment variables:
+
+| Variable | Meaning |
+| --- | --- |
+| `DOCKET_API_URL` | The API's address. Default `http://localhost:8001`. A frontend origin works too (`https://docket.example.org` or `…/api`), with its URL prefix if it has one (`https://host/docket`). |
+| `DOCKET_TIME_ZONE` | IANA zone for the local times you give and get back. Default: this machine's zone. A tool's `time_zone` argument overrides it. |
+| `DOCKET_API_TOKEN` | A Docket API token (`dkt_…`). Checked **first**; works in Tokens and Entra mode. |
+| `DOCKET_AUTH_CLIENT_ID`, `DOCKET_AUTH_SCOPE`, `DOCKET_AUTH_TENANT_ID` (or `DOCKET_AUTH_AUTHORITY`) | Entra sign-in when there is no API token: the SPA's public client id, `api://…/access_as_user`, and the tenant (or another OIDC authority, such as the mock provider). |
+| `DOCKET_AUTH_CLIENT_SECRET` | With the three above: sign in as an application (client credentials) instead of as a person. |
+| `DOCKET_AUTH_CACHE_PATH` | Where the person's token cache lives. Default `~/.docket/mcp-token-cache.json` (holds refresh tokens: protect it). |
+
+### Sign-in
+
+Reads are anonymous. The server asks `/api/v1/me` once for `auth_mode`, and only **writes** carry a token.
+
+- `auth_mode: disabled` (the default Docket): nothing to set up and you are never asked to sign in.
+- `auth_mode: tokens`: set `DOCKET_API_TOKEN`. Ask an admin for a token from **Settings > Access**. Without one, write tools say so.
+- `auth_mode: entra`: set `DOCKET_API_TOKEN` too (simplest), or sign in as yourself. The first write prints a URL and a code to stderr **and** returns them as the tool's error text (some clients hide stderr); open the URL, enter the code, then run the tool again. The token is cached afterwards. Set `DOCKET_AUTH_CLIENT_SECRET` for an unattended application.
+
+Tokens are never logged or returned by a tool. `whoami` shows your auth mode, caller, roles (and where each came from) and grants: as yourself when a credential is available without interaction (an API token, client credentials or a cached sign-in), otherwise as anonymous (`signed_in: false`). It never starts a sign-in.
+
+The device-code token cache holds refresh tokens. It is created owner-only (`chmod 600`) on Linux and macOS; on Windows `chmod` is a no-op and the file relies on your user profile's ACL, so keep it there (the default is `~/.docket/`).
+
+### Tools
+
+| Read | |
+| --- | --- |
+| `list_rigs`, `list_projects` | what you can book, with optional `search` |
+| `lookup_subject`, `lookup_person` | check an id or username exists |
+| `get_schedule` | sessions between two dates (rig, subject, person, archived filters) |
+| `get_acquisition` | one session in full: people, notes, resolved settings, runs |
+| `find_free_slots` | gaps on a rig long enough for a session, within daily bounds |
+| `list_series`, `get_series` | recurring series and their rules |
+| `list_templates`, `list_settings`, `list_runs`, `whoami` | |
+
+| Write (all take `dry_run`, default **true**) | |
+| --- | --- |
+| `schedule_acquisition` | book one session (optionally from a template) |
+| `move_acquisition` | change start, length or rig |
+| `archive_acquisition` | archive a session (nothing is ever hard-deleted) |
+| `create_series` | a finite daily/weekly series |
+| `edit_series_from` | change a series from a date on (the old one ends, a new one starts) |
+| `archive_series` | archive a series, keeping or archiving its upcoming sessions |
+| `mark_outcome` | record succeeded / failed / cancelled by hand |
+
+Not in v1: pushing settings, syncing vocabulary, managing templates and roles.
+
+### Dry runs
+
+Every write tool previews by default and changes nothing: it returns what would happen,
+including overlap warnings, skipped (daylight-saving) dates and which sessions a series edit
+would replace or keep. The tool descriptions tell the assistant to show you the preview and
+repeat the call with `dry_run=false` only once you agree. Series and moves use the server's own
+preview endpoints; for a single session the API has none, so the preview checks the schedule
+itself with the server's overlap rule (same rig only; the same subject on another rig is listed
+as `advisory`) and the server checks again when it creates it.
+
+Each preview returns what the confirmation needs, under `confirm_with`: the `expected_version`
+of what it looked at (moves, archives, outcomes, series edits and archives) and an
+`idempotency_key` (new sessions, series and series edits). Repeat the call with
+`dry_run=false` and those values. If the session or series changed in between, the call is
+refused with "changed since your preview; preview again" and nothing is written. A retry
+after a timeout with the same key cannot book or create twice.
+
+### Times
+
+Give local wall-clock times such as `2026-03-08T09:30`, never offsets. Results show the local
+time (with its offset) and UTC. A time that does not exist (a spring-forward gap) is refused;
+a repeated one (fall back) takes the first occurrence and says so.
+
+### Example prompts
+
+- "What is on rig `BEH.A` next week, and which afternoons are free for a 90-minute session?"
+- "Book subject 812345 on `BEH.A` under project `Vision` tomorrow at 10:00 for an hour, with me as experimenter." (it previews first)
+- "Move session 412 to Thursday at 14:00."
+- "Set up a weekly series, Mondays and Thursdays at 09:00 for eight sessions, for subject 812345."
+- "From 2026-11-02, shift that series to 10:30." / "Cancel the rest of series 17 but keep what already ran."
+- "Did anything fail on the FIP rigs this week?"
+
+### Developing
+
+```bash
+uv sync --group dev
+uv run pytest client/tests                       # unit tests + the stdio smoke test
+uv run pytest client/tests -m integration        # schedule -> move -> archive on a real server
+```
+
+The integration test builds the server image and starts its own Compose project
+(`docket-mcp-it`, API on port 8020, static vocabulary, nothing from the institute) and removes
+it afterwards; set `DOCKET_IT_URL` to use a server that is already running instead.
+
+## Building / publishing
+
+```bash
+# from the repo root
+uv build --package docket-client   # → dist/docket_client-*.whl
+```

docket_client-0.3.2.dist-info/RECORD

@@ -0,0 +1,188 @@
+docket/__init__.py,sha256=mXHDX36eM0PU_Xd8Z4QOu5uIMU_QOLVChHkMzeMXAH8,153
+docket/client.py,sha256=RNOlUXJyXojGoTe70XQ7Ua3F6vL9VEVZrcyuN4a559I,12448
+docket/errors.py,sha256=gO8GBmKqmSNgAg-E5oT-oOyxztvp7V_6XG7OUTT15q0,546
+docket/types.py,sha256=Hs1kUAG3WouD0popBN5bf1TsZiJ73ARUAKs4UOJG_Lo,1343
+docket/api/__init__.py,sha256=zTSiG_ujSjAqWPyc435YXaX9XTlpMjiJWBbV-f-YtdA,45
+docket/api/access/__init__.py,sha256=5vd9uJWAjRqa9xzxzYkLD1yoZ12Ld_bAaNB5WX4fbE8,56
+docket/api/access/add_principal.py,sha256=0V2QI_d_xmSOoOhIu2FOwbw6fS8LTprrR7z8ja1r1J4,5956
+docket/api/access/archive_role_assignment.py,sha256=BD39Ur9el4_JFGFrlNEMn3s9oB9UbKcFWFOAc7dYfB0,4936
+docket/api/access/create_api_token.py,sha256=f-s8Pcnx5kJVtZVN4Eu-RqgjnWJAyopgrEUX4NjieI8,6254
+docket/api/access/create_application_principal.py,sha256=6xxqWrOuzKphkDnRxYvMWzetUd8JKdpdhq0wYBRz9I8,6269
+docket/api/access/create_role_assignment.py,sha256=JaZaejO2jMhVYA0ucmcZKmWnKgGvy3ih0Lwj7yAc6aQ,5867
+docket/api/access/list_api_tokens.py,sha256=F0Eptt9fOnSS8irVVC7gZtO1tJNYlaiZM4RIUOkTWN8,5058
+docket/api/access/list_principals.py,sha256=F2oLioAk7-VTIqs8NKurRrSqGXw2GWhMhZo1yEJSPN0,5061
+docket/api/access/list_role_assignments.py,sha256=kPrAR5C6T5ebxYZ-xaCEcV1djpkFxKV9tUmQ_45nFxY,5820
+docket/api/access/revoke_api_token.py,sha256=SIHQfjJLPp-n9x3T6VKyOKT8I3OmZlImiKO3dGab79o,4421
+docket/api/identity/__init__.py,sha256=5vd9uJWAjRqa9xzxzYkLD1yoZ12Ld_bAaNB5WX4fbE8,56
+docket/api/identity/create_my_api_token.py,sha256=dWdLfR-nEYRn1xxtEY8fUwbt5Ii1O2-xBtpmXuYNgU8,6847
+docket/api/identity/get_me.py,sha256=qItA6ZkXxfILbvko32T58WqdRhWyRm5PN7IbRRu8aDs,3104
+docket/api/identity/list_my_api_tokens.py,sha256=B8j8joE6grTSPAADxYxHvgxSsdE0Z-ZBOwkVfC6qaOc,4390
+docket/api/identity/revoke_my_api_token.py,sha256=3s0G6EWu7jiNoGZbQQfr2roncH6kmuyfY0m09SqwT-4,4504
+docket/api/recurring_acquisitions/__init__.py,sha256=5vd9uJWAjRqa9xzxzYkLD1yoZ12Ld_bAaNB5WX4fbE8,56
+docket/api/recurring_acquisitions/archive_recurring_acquisition.py,sha256=t8bbswk6iRhrqovmPw4cAZrER5ohmjYk83ZYXulQNhQ,6428
+docket/api/recurring_acquisitions/create_recurring_acquisition.py,sha256=lKcQj1jBJ3oVPQLOMP5MVXk74awamfys4XlzY1_WTOM,7331
+docket/api/recurring_acquisitions/get_recurring_acquisition.py,sha256=nMoV8muigj6nDCtVk-GiuUtz-aJKrCJog6w4_htny3w,4399
+docket/api/recurring_acquisitions/list_recurring_acquisitions.py,sha256=wmUPvLjGSnYGH0HqSuRB8dmM4ygqHEWJZbYlk76iP3Y,7725
+docket/api/recurring_acquisitions/preview_recurring_acquisition.py,sha256=sQlMa1vhbOs1A-UpoZrkseqoaoXOvRNq9otIiVPrKLE,6203
+docket/api/recurring_acquisitions/preview_split_recurring_acquisition.py,sha256=GIOJVOxnE820Nl4p5VZDxbvKx70UKzWydnXA5992ahE,8139
+docket/api/recurring_acquisitions/split_recurring_acquisition.py,sha256=CfBlD_gKhZ3LgcTEc5og5V7e-qUTFl0er7EY_AE1lcs,9495
+docket/api/runs/__init__.py,sha256=5vd9uJWAjRqa9xzxzYkLD1yoZ12Ld_bAaNB5WX4fbE8,56
+docket/api/runs/get_run.py,sha256=53faiXYr8tilRQJFKoP5rywTaAWCt8eIqWdTfLpbwAM,3883
+docket/api/runs/list_runs.py,sha256=nn5mSzYzaw0NFlH5Z2V7oEM4rgG8fmetrBchzLAPXDY,4816
+docket/api/runs/report_run_outcome.py,sha256=sT5FbEfgty0XCBpryJ6rAiZQafn4laS7nZWYivDzE-A,5924
+docket/api/scheduled_acquisitions/__init__.py,sha256=5vd9uJWAjRqa9xzxzYkLD1yoZ12Ld_bAaNB5WX4fbE8,56
+docket/api/scheduled_acquisitions/archive_scheduled_acquisition.py,sha256=QnXScKVPI-QyyjdcJfmSZK7P17pQRVYO0I1KgnySHkE,5980
+docket/api/scheduled_acquisitions/create_scheduled_acquisition.py,sha256=Xx1l4UQ7pmTGBRrC8pyXz6dZcONyLoF-iBU14NBSb9s,5768
+docket/api/scheduled_acquisitions/get_resolved_settings.py,sha256=m-8iO5kMagbBLvaIWbXnk8ASTd13n-1mfwOZFkTK7zE,4916
+docket/api/scheduled_acquisitions/get_scheduled_acquisition.py,sha256=RT9Eh8rD9nVcbo1ryiMYgY8FBJG1LPs0E_Gl8QFrzas,4032
+docket/api/scheduled_acquisitions/list_active_acquisitions.py,sha256=kZaqYp3qWTV5-wdQSbpwH96iRg43L20iTedx4FaOL90,10278
+docket/api/scheduled_acquisitions/list_runs_for_scheduled_acquisition.py,sha256=tg737gKCQtylQoHom-cR3IOtG9FbiLfDi2kR1MHOqEU,4839
+docket/api/scheduled_acquisitions/list_scheduled_acquisitions.py,sha256=lZjNxLV5x9VWoah-cv6U8KjhzwXoL3reYnbKDyJNDrk,11573
+docket/api/scheduled_acquisitions/preview_scheduled_acquisition_edit.py,sha256=3f8eDve9jAR96Tn759RdShVn0r6_G5lhsmBOuUYZD_c,7461
+docket/api/scheduled_acquisitions/set_planning_status.py,sha256=27ttxqH1zw7AR7mHuos182uhoLQkmThMOhBxGqtlDsQ,5662
+docket/api/scheduled_acquisitions/start_run.py,sha256=RR56dJJaob-CXGbZTv5Sj_jxCUp-crRwP3o3wJQkrrU,6573
+docket/api/scheduled_acquisitions/update_scheduled_acquisition.py,sha256=ZWwpi-nCZ6a0VRV1-lCHx9JpMElNGzbqBn6g6KDKxyI,7271
+docket/api/settings/__init__.py,sha256=5vd9uJWAjRqa9xzxzYkLD1yoZ12Ld_bAaNB5WX4fbE8,56
+docket/api/settings/list_behavior_curriculum_discriminator_values.py,sha256=1oXG-R-s4AbXmmqs9SKeYta3kzdw-AMA4xmDBbmVuw0,5089
+docket/api/settings/list_behavior_curriculum_settings.py,sha256=MWJJaIH09ID2qpfPm7onqCfAaiujdhCbbB9BDpfo_ks,5992
+docket/api/settings/list_fip_discriminator_values.py,sha256=5ZGay9NnXHu_CmpkYFwXY3oeSfDO1jr7felcsYhrtSY,4993
+docket/api/settings/list_fip_settings.py,sha256=1vZ2EDjLzmGklblCwcg0GLkKjZOa6jpbN8plpHMUSBg,5677
+docket/api/settings/list_live_behavior_curriculum_settings.py,sha256=_NwGd0awOeQtaNOu9LeV0Qrw5EWf4_poHFwg227ms0Q,7435
+docket/api/settings/list_live_fip_settings.py,sha256=A20CWkO8zh8dChyr8wTksKot2E8u9m_si2BUYJrhl54,7104
+docket/api/settings/preview_behavior_curriculum_settings.py,sha256=22x4WsaYcRDF7vh346lrFi7Y88ko-mA2V80IiSaNLx8,6424
+docket/api/settings/preview_fip_settings.py,sha256=zbUhqijlSXdc8yoZoeIvVDkd7HuWzrHFf4SXojtbMA8,5253
+docket/api/settings/push_behavior_curriculum_settings.py,sha256=hBTaRR9o0d0QEj4fYUFjV4-oZgiOarEu79OJ-bGsjUc,6965
+docket/api/settings/push_fip_settings.py,sha256=rgy9xQAchdkBp66akJcaPe7zO_bD7wQUM7rNOxdhiyY,6463
+docket/api/templates/__init__.py,sha256=5vd9uJWAjRqa9xzxzYkLD1yoZ12Ld_bAaNB5WX4fbE8,56
+docket/api/templates/archive_template.py,sha256=U5MbBg3YFMQ2hSgx54oLAnYd7K7UG4A7jV8iYaqwbjs,5737
+docket/api/templates/create_template.py,sha256=TTNOk1xqhYyT53v3C2KTBQIXBpdVP0lmTkyy9GyMnvw,6788
+docket/api/templates/get_template.py,sha256=R8yirbGaixhv8XyEh65hkRARwffHMSqlKxvJKMN65HE,3862
+docket/api/templates/list_templates.py,sha256=3ly9Sj04b1iDhDORQKcOXObvDKhSv4OXyYvjj_m_zqk,4618
+docket/api/templates/update_template.py,sha256=2_oo3e8c6-1cfEkJ4Df-nOlUfauFkwKFBPr19tT3SI4,7908
+docket/api/vocabulary/__init__.py,sha256=5vd9uJWAjRqa9xzxzYkLD1yoZ12Ld_bAaNB5WX4fbE8,56
+docket/api/vocabulary/list_instruments.py,sha256=yfan5XkiWFlg86y6KjbGgTL5JHo67JryusCC3ZevN7c,4115
+docket/api/vocabulary/list_persons.py,sha256=5UrgYqJQbjmk9GS-tIhxjlzzipyDL1PJIHcmaSANNko,3408
+docket/api/vocabulary/list_projects.py,sha256=etbT6RJGCQXvB1HVBNWjDzHROkTI3ZjE8UGAQxPCKmU,3422
+docket/api/vocabulary/list_subjects.py,sha256=eyC1SjKYcFrz5Fs4pM55Tldmu2lX9C0KicL9J8lP1MI,3422
+docket/api/vocabulary/lookup_person.py,sha256=MrV6jb4JCR6HtdVUPCyI9LrfSthyQGQhVBE5cZfd0to,4290
+docket/api/vocabulary/lookup_subject.py,sha256=dexBxL65qaJ8JjLa5KbD7B710ZrZGHYhMq72rwt3Njc,4342
+docket/api/vocabulary/sync_vocabulary.py,sha256=-1QdTclGJyYnkZuTre83Y6G2jKAQCc-VtHVijW3Ms5w,3891
+docket/models/__init__.py,sha256=ikA3t_CDFT88dYDA6xTyR5UOPe-ggO0pQE0Diu3w3Kk,9478
+docket/models/access_role.py,sha256=qWKVQ2cb3GbZFqLHv8LY9aRHp6SMZzGNmIni_G4JV0E,297
+docket/models/access_role_nullable_type_1.py,sha256=aT8uRQANzPRRVyuwKKioVMWCY_quqkdtb3a9OiSDSfA,310
+docket/models/access_role_nullable_type_2_type_1.py,sha256=KitsG4ftAYt-Zlo2HenR4qBryd8oVARrEer75JNN8bI,315
+docket/models/access_role_nullable_type_3_type_1.py,sha256=T-ygFj-sizAjJaEUYIaGqWZJ1-61_oO7vnCwAJ8YMNo,315
+docket/models/acquisition_variable.py,sha256=98P7L5RmvVC8ZFTJ1hvVNpW-2eKpbHIfzPlozHbjHvY,1783
+docket/models/acquisition_warning.py,sha256=7GStpBEyFvcwMTyP-nmVxvxjIMvB4jbMyGOl62ltIkU,3931
+docket/models/add_principal_request.py,sha256=jqHX5h3ZwycVSNx__D1lmHjRxFz3cLCqFQX1JR6I5lQ,2340
+docket/models/api_token_response.py,sha256=u_cYyJ6OFRMr5vP66dCL4yXRXk98qF1pcAPRmzLUekA,9542
+docket/models/api_token_status.py,sha256=3TPFDd6-dx4trrj_MXT0wndji5ZSBb6NLxCZHqErzVc,189
+docket/models/archive_recurring_acquisition_request.py,sha256=du7-4MOkHjL29fHUNwIsKLJVIOcB3UC191mWG5zEYJQ,2455
+docket/models/archive_recurring_acquisition_response.py,sha256=WyJqHwxM29sQq2Etp7ShKJQJ6ZOGSMgYExXTS7mtGRM,2702
+docket/models/archive_scheduled_acquisition_request.py,sha256=8M86ZgewdA7yw8nIkzjDc4Q07XEx4mhyNTPZeFtDV8c,2497
+docket/models/archive_template_request.py,sha256=ffEGatgrHqHVfQDDy4Bp68avubZ0k-0-vVu7xaTzOwc,1934
+docket/models/auth_mode.py,sha256=aZgoSip5S0Ahnxt7sph2Yb3VPrF4EWfEGr0VdSin2NA,181
+docket/models/behavior_curriculum_push_settings_request.py,sha256=vLp3nUKR7r7diBz_NGJm-fFZncKduZpsrTEpuJDLYMo,2698
+docket/models/behavior_curriculum_settings.py,sha256=Muq0ge13FhD1O7hlApyQB2p3GGmYF_PU1JU8FLRqONA,1633
+docket/models/behavior_curriculum_settings_preview_response.py,sha256=26l3Ir4IhTKBawoFmUEJBuCZ0DRA9yIS2A-tem2ih94,3552
+docket/models/behavior_curriculum_settings_preview_response_promoted.py,sha256=gkhtsWxC_XWowP0z-z6uO6zMsQGQ5Y00u_74hkq3whc,1557
+docket/models/behavior_curriculum_settings_version_response.py,sha256=3acFoeKKPUZj7tQvg8R25lUCtHlNowEBSVU4kUXUq4g,5603
+docket/models/behavior_curriculum_settings_version_response_promoted.py,sha256=nd0IASNNwsUD-MZrezzK_NIeKEAJd2rjHQIGn2ui7r8,1557
+docket/models/caller_kind.py,sha256=QJI--8_BxjmzKINVOuKr0Ev-XfpmuUpL0oplw_Poo7s,217
+docket/models/create_api_token_request.py,sha256=OMYnr0mssMh2QTbnvLsul3C5f9Yyqy2ka-qeziG3E1I,2912
+docket/models/create_application_principal_request.py,sha256=6iANl-qR7G3z9oq9-073CRkUv4oXBx2ouy9i8SGWvEg,1870
+docket/models/create_personal_api_token_request.py,sha256=FLUyDfkXMFWnp6ipTeHyUfoBtQmegKHELSbZ0X8angc,5699
+docket/models/create_recurring_acquisition_request.py,sha256=o7TMCMJLT-l5IarfJU4ivLCgRgK0sFLNIA9SxBX_k4I,10867
+docket/models/create_role_assignment_request.py,sha256=DY2tfrE-aqKXTgRZCBoHUYVi8Jwuv42aOXf1C4WPPjo,3042
+docket/models/create_scheduled_acquisition_request.py,sha256=M-0gaUxEaS8sj3jVCIEQDSY-zUoF3OvMw0gwe63u-a4,9976
+docket/models/create_template_request.py,sha256=BP7APCY9I-7LeBU3UxVWStcnqqjMNfXq5qcFrzdEOi4,12311
+docket/models/created_api_token_response.py,sha256=qhP14Mq_jjTrW1RXObQtHWsisF8ewicPRruHl4d8p9Q,2363
+docket/models/effective_status.py,sha256=LCY7nDShbxcLx8tFXTEuNKnCWx9I1mfBQYVN1URV0EM,330
+docket/models/fip_color.py,sha256=v5TziP1WWvSzKk_2LCWnpajJgcf358lTwQgLqnacKqo,233
+docket/models/fip_fiber.py,sha256=bdOUByJdJXVq6wQnvD2c86vjZZE0UWXHFSkRMILmqGs,2662
+docket/models/fip_mode.py,sha256=b2u56KhLkIQDwD4DYMLZ1UtGEsvKvzlj-NCXBy_iqTQ,158
+docket/models/fip_push_settings_request.py,sha256=Q-3Ii8IOquRvhKnw80hkWBSMzP-bOjCoi2YulDMdNbk,2302
+docket/models/fip_settings.py,sha256=KF6xTkgRrC_r25AdofwczmXgfD51iIggFTMpULbki90,2413
+docket/models/fip_settings_preview_response.py,sha256=UnxT6Cad4kDRkXXbcoZuGkFBk6XIuHz80gSpSpWLhr8,3001
+docket/models/fip_settings_preview_response_promoted.py,sha256=Mc3fNZmF3d1Ogzs-2LsJ0q9P1v5kGn_RYDSbA4xiMEc,1479
+docket/models/fip_settings_version_response.py,sha256=gIsDkTmVj25yM6HtfiR6dO5b1TMj9KuuWRFVgGwP9Ok,5052
+docket/models/fip_settings_version_response_promoted.py,sha256=V-HtGVdxV75wkmNa0O9NzT90_OufZh-pPT3A_z7s9BE,1479
+docket/models/future_occurrences.py,sha256=p4Y_QH32uvZ9V_0ttao6PsCb0IBFZOyr-0bnvyy-pSs,164
+docket/models/get_resolved_settings_response_200.py,sha256=HyRstSONqyLneSdRdTKl0vBkUvhm9RdHbr_atlH_MhA,1999
+docket/models/held_role_response.py,sha256=uCYqsiFfdXovuvznLSXMUkhfnGLgbqtza3gttoi8D_g,3408
+docket/models/http_validation_problem_details.py,sha256=g4rZwOvp8pa-jT5ebo6_XHbI_Z7b2MLHyVDFlw_eOwg,6260
+docket/models/http_validation_problem_details_errors.py,sha256=gqdYs_dHGp2V4RTkmfrXaqHYXJWkDDaL7GfjH-8LOl4,1769
+docket/models/instrument_response.py,sha256=qLRqPvnDbZNSsuC-NnHEhWJv_qAa9S_P5BQK-kx1clQ,2282
+docket/models/kept_occurrence.py,sha256=1z1J_A9zsdsJ66nRtNrni_jwXWztXpd99akl_e-C6q4,2669
+docket/models/kept_occurrence_reason.py,sha256=DcIT5qbnanx0mKdzH5WHNCg0M4Gq3qN1W6SIoxIJnvQ,195
+docket/models/list_active_acquisitions_effective_status_item.py,sha256=NLWnHJHcXjc0WqmOrD4FZPxGaIlkQDbuQIeIzzfQW28,356
+docket/models/list_scheduled_acquisitions_planning_status.py,sha256=Rk1gkFHn3fYJnXjY1OmgnJXifQod_pciDjQOFMiBF68,250
+docket/models/me_caller.py,sha256=CqzynuWxH7ki4hYVK9eZRddMsIxo39bK5x3063dmh5E,3509
+docket/models/me_permission.py,sha256=r2jCTdEY34BS_iEO8x72Y0a3ZaRdK4ZsDZ1fpuF7Vs8,2701
+docket/models/me_response.py,sha256=DTWgekrV0e4-CnKhN2Ar8a9akQoElj4rJ8ICOK-GNAA,5449
+docket/models/me_role.py,sha256=UFfRzzVjFP4jkFrGzj5gZSq8xrF-ppdXjyUOl7RJDvA,1924
+docket/models/occurrence_preview.py,sha256=VQn-aAx_mvmnGR-MEm5bGetBFXe0qPxNuWicIYLf37o,4175
+docket/models/occurrence_summary.py,sha256=cuA0i3EiMnD5Is-uspzGWJ8Y2e_yZPSQQxk8qeUayfY,4203
+docket/models/occurrence_warnings.py,sha256=C02Rf66Q6riToYlEJuNaqpMUhPewGybOwudHcbuzkTk,2715
+docket/models/permission_action.py,sha256=aJliPOYJpeVhjQ_10AwnLUw34KMhxIdWnmphQFUGm3A,231
+docket/models/person_assignment.py,sha256=_ME39Pb4YiolHyhursEqY01BYjKRPGcYLccXyY6mSAc,1889
+docket/models/person_lookup_response.py,sha256=YDTbbL2sTI8LCc-TGb_g_3RC2D14fjx0oo71BvvLHoY,3779
+docket/models/person_response.py,sha256=s15QvZD3wiJ8Qpf1X5cU4pF7108qvOxLrE-oK_-m-Co,2720
+docket/models/person_role.py,sha256=NEWl-WLFLd7-BmQ9XBYi12Ng_zEDZXslYv2z4moUZ00,195
+docket/models/personal_token_limits.py,sha256=HxNh_CInW5HHR8tJ6CekYBzwPnnmxckLrltYhhIVa0k,3012
+docket/models/planning_status.py,sha256=K7dMJZYMcermMfWv8EljW_HUt4_j6eAWWaT1zQBIA4w,225
+docket/models/principal_kind.py,sha256=x9X2HbMcpso8N3eW-BF2TXhT7bgVj3ynAAwPhPABCBs,172
+docket/models/principal_response.py,sha256=MprsDZxFltiC8-4WTsxjdBtxD77ifUfuNTJ6cZ8yk_M,7789
+docket/models/problem_details.py,sha256=anILAvUU2JQl-0CxqRH1TN_uAXO-FUC-WRFArJuNi9Y,5189
+docket/models/project_response.py,sha256=0U-MWzYYOkm9Eu6q46949IW3rWKKdancep9d55pfOP8,1921
+docket/models/recurrence_exception_kind.py,sha256=-TG6BR8dFtsR1juQlCeKCNnXM3wZENXIJaCZsJ1jh9U,362
+docket/models/recurrence_exception_response.py,sha256=jkhSTHjOM9-zgdfV5bwvvlcMWWPfhjnGMxBpt5zMTmM,3456
+docket/models/recurrence_frequency.py,sha256=EJd18ujrVqlb3IsHFQr9Q961yj1frw0dZcOpV-Tzp5E,166
+docket/models/recurrence_preview_response.py,sha256=Jm-2oAsmMB8_8Lzto_3HCX-_VvRSMcReVbiH2ol34rI,3204
+docket/models/recurrence_rule.py,sha256=yAJCN9w7ecdshyoZ_G2M3ksj5xLvs5ZO6qSiejOiJ1s,7148
+docket/models/recurring_acquisition_created_response.py,sha256=ZnduO3MXjs3ZO_52fPLb2XpizD6RgUNgYR6f1k_n6-I,4309
+docket/models/recurring_acquisition_detail_response.py,sha256=NuN4q--s_5LbVQQdir79TdL4DYxTvD3WVDDpQJN77Q0,3701
+docket/models/recurring_acquisition_response.py,sha256=_ELOHRgOtvb0N5ke4yPGiX9MvuC64F-WrBM9DfDVdyU,11562
+docket/models/report_run_outcome_request.py,sha256=4Ge2y05BbiI4Os_9rrWHlszBt24zvt9GqhzapH4DecE,2569
+docket/models/resolution_mode.py,sha256=UnI3saqdfq65xsxxT6ytVG6vGLYpRPuaYTXTFA9AbcA,209
+docket/models/resolved_settings.py,sha256=YHfHzcMfVKQ0Nn_40iCSGyJlYYDTPfa-A24RYJiBKco,1875
+docket/models/role_assignment_response.py,sha256=GSruhGF7gkX--pdXUGInlXF36x0X7SK80PwujdSe4bY,5147
+docket/models/role_origin.py,sha256=VCtrRpLcewjY1D1Gt-iUjBaAFz_bVPCkF58sWbvOSgs,197
+docket/models/role_source_kind.py,sha256=9Bh6S1oIkOJj7kUXef0kBTBFI3YmKk3jvVioidHanSM,201
+docket/models/run_origin.py,sha256=ABR3EFipFwRyHHcZ2ZXzmUvpsPKQ9J3AKEXrh5tJk2E,156
+docket/models/run_outcome.py,sha256=S8Sxa4vCtTulOJuNeZNE6vyBW-Qz3W3fWr1wEky8HWI,167
+docket/models/run_response.py,sha256=69X3Rh6Oy6GOBxDFoGQ9Irvg2MBlhzBTOZGVndxYpfY,5595
+docket/models/run_settings_snapshot.py,sha256=v1PBssFrIXv2gXLXjr_0jmkn1N3dcA6GxBkjjYQ-9T8,1985
+docket/models/run_start_response.py,sha256=BIe3EuTozc589o4z7uikV_yNljeBARHvVhpTcpMv2k4,2520
+docket/models/run_start_response_settings.py,sha256=rYYsMBeQDO85xBvAlW9qw9-FwIm5kq4lP1-lYN02MZE,2028
+docket/models/run_status.py,sha256=idt5-R9CD0jZg0ho-VyE0z_6grXjBbno9ZSR4PjPGRE,218
+docket/models/scheduled_acquisition_edit_preview_response.py,sha256=srSR1v4tIyzOZQUgruh80sGrq1tB2tVvTkB8F-QipVk,5323
+docket/models/scheduled_acquisition_response.py,sha256=u4gCN_0BA-FGHEbzbKRG-Aq6hoARAHKQwE1AJaFDPTk,13568
+docket/models/set_planning_status_request.py,sha256=vj30lagVdhJVs_pupaG36QfVHKQwHpEh-Kb4G4otomM,2963
+docket/models/settings_selector.py,sha256=bqX5Vxra5RUfGQXU-8dpHKBnb_caaYeIfknwu5x6aQ0,4900
+docket/models/skipped_occurrence.py,sha256=RgP4qGkytpONsppYkQYGRleAuvJ9-BOK-NwnLKBmUfk,2538
+docket/models/split_preview_response.py,sha256=YSyvPbD_kI1xZSas3o5OBY0r7mTZ_VgBRL8eaRQpk7o,4229
+docket/models/split_recurring_acquisition_request.py,sha256=4jS_pfXJCeui7nXg7KLHpTMTf6VoSrESu14zmr6c-ho,10045
+docket/models/split_recurring_acquisition_response.py,sha256=1FzZmqRQSC5-PkDZPBdRY_0zqLMLQpC2PSTxGcyCtqg,5640
+docket/models/start_run_request.py,sha256=3lwwvlENoZp0o-U4QwEA2JfPTUxn5o0qwm03HisS1sE,2078
+docket/models/subject_lookup_response.py,sha256=FMVOdZMIaCo55YpsWHpbb5c7UyUo8ObvTClyD8pN-QA,4494
+docket/models/subject_response.py,sha256=iExW1E7fgMzigEinUFoaSvIxRiQCNXEbRfCHhRJsvKk,3684
+docket/models/sync_counts.py,sha256=MYD5dQyyTeBc0Dwv-99pM3My_aDVqGF1NfIj8c22Au0,1943
+docket/models/sync_response.py,sha256=Ocn-RWEIJwfnFiPnE2MN-q0YmHKAN3BSfAJtxy38w04,2100
+docket/models/template_response.py,sha256=9rxRqK44AXY9NeSTDy8EGw8djJL0jWmhrGK5Un-WuFw,9966
+docket/models/update_scheduled_acquisition_request.py,sha256=IUgkJOeP5nKDsOcfQj7ZW5wQyJMeOf-g4m9T-OSIpcI,9333
+docket/models/update_template_request.py,sha256=kgUYLx_rUVss9OyAgcKenehi-PRIcQ_a7ZeygraFr-s,10653
+docket/models/weekday.py,sha256=ynDKgQZbEeeJU3f6AAzURIxz4ILkuebmq6UFD9R68ms,282
+docket_auth/__init__.py,sha256=T28BUSFiljQsQR8oOK2UxLJHCirg5D9zK6zCCdhT4R8,9166
+docket_mcp/__init__.py,sha256=pOSC3KZ_hkFb0VW4QDDpkGa7lpUPGEMlUUmDd8HCwsg,368
+docket_mcp/api.py,sha256=5eDiTC_lJJGKI02PQ_J1RytdltfllVSN9R93dXK3RE0,8483
+docket_mcp/config.py,sha256=aKS_dc5-r9AeMzbgjHtYiFzBtH8ZTEb-7QsXqhXXpuw,2005
+docket_mcp/server.py,sha256=nqgvV_mWkuDBwe8ORH54PxyHZhLjGtAqpA3yJgHCfh8,2563
+docket_mcp/signin.py,sha256=lwFZ4lodUnaqOWg6ivsWeZVpzdHQD1mr8dwnDIZYb6c,5684
+docket_mcp/slots.py,sha256=SUzQ6vXdgDH_6lwX9T6SMvRV-xo3i62X-oU76MDPNp0,2779
+docket_mcp/times.py,sha256=HpoIaJ3uihwfY0oo3OBk5CJJzuRzCioDULJcXB9fl1E,5820
+docket_mcp/tools.py,sha256=Z4L6WbTS5FlJYFvWVK3IrOXAgADeYqdwtHV4aKnIT60,52360
+docket_client-0.3.2.dist-info/METADATA,sha256=xfL1wU9NPHXyUTYJFfCyoInY2IUBoHEbDdUdMKdbPoQ,10352
+docket_client-0.3.2.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+docket_client-0.3.2.dist-info/entry_points.txt,sha256=Wh6bZ_A_jc7MClLXlPaufhYtoYMGMLmTMC7ynpolbxk,54
+docket_client-0.3.2.dist-info/RECORD,,

docket_client-0.3.2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

docket_client-0.3.2.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+docket-mcp = docket_mcp.server:main

docket_mcp/__init__.py

@@ -0,0 +1,6 @@
+"""A local MCP server for Docket (console script ``docket-mcp``, install ``docket-client[mcp]``).
+
+Hand-written, a sibling of ``docket_auth``; ``client/docket/`` is generated and never edited.
+It speaks MCP over stdio and calls the Docket API through the generated client, so nothing new
+is hosted and the institute network is reached from the user's own machine.
+"""

docket_mcp/api.py

@@ -0,0 +1,207 @@
+"""The HTTP layer: the generated client's connections, token handling and error mapping.
+
+Reads go through an anonymous `docket.Client`; only writes use the token-carrying
+[`docket.AuthenticatedClient`][docket.client.AuthenticatedClient] (from ``docket_auth``), mirroring the frontend. ``/api/v1/me``
+is read once to learn ``auth_mode``: when it is ``disabled`` no token is ever requested and
+sign-in is never prompted. Responses stay plain JSON so tools can reshape them for a model.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+from docket import Client
+from docket_auth import AuthenticationError, TokenProvider, authenticated_client
+
+from .config import Settings
+from .signin import SignInRequired, build_provider, non_interactive_token
+
+__all__ = ["DocketApi", "DocketToolError"]
+
+TOKEN_HELP = "Set DOCKET_API_TOKEN (ask an admin for a token from Settings > Access)."
+
+
+class DocketToolError(Exception):
+    """A failure to report to the model as the tool's error text (never carries a token)."""
+
+
+class DocketApi:
+    def __init__(
+        self,
+        settings: Settings,
+        *,
+        transport: httpx.BaseTransport | None = None,
+        token_provider: TokenProvider | None = None,
+    ) -> None:
+        self.settings = settings
+        extra: dict[str, Any] = {"transport": transport} if transport else {}
+        timeout = httpx.Timeout(30.0)
+        self._anonymous = Client(base_url=settings.api_url, timeout=timeout, httpx_args=extra)
+        self._provider = token_provider or build_provider(settings)
+        self._authed = (
+            authenticated_client(
+                settings.api_url, self._provider, timeout=timeout, httpx_args=dict(extra)
+            )
+            if self._provider
+            else None
+        )
+        self._me: dict[str, Any] | None = None
+
+    # -- reads (never carry a token) -------------------------------------------------------------
+
+    def get(self, path: str, *, what: str = "this", **params: Any) -> Any:
+        query = {k: v for k, v in params.items() if v is not None}
+        return self._send(self._anonymous, "GET", path, what, "read", params=query)
+
+    def me(self) -> dict[str, Any]:
+        if self._me is None:
+            self._me = self.get("/api/v1/me", what="the caller")
+        assert self._me is not None
+        return self._me
+
+    def me_as_caller(self) -> tuple[dict[str, Any], bool]:
+        """``/me`` with the caller's own credential when one is available without interaction.
+
+        Returns ``(me, signed_in)``. An API token, client credentials or a warm msal cache are
+        used; a device-code sign-in is never started here. Falls back to the anonymous view.
+        """
+        anonymous = self.me()
+        if (
+            anonymous.get("auth_mode") == "disabled"
+            or self._provider is None
+            or self._authed is None
+        ):
+            return anonymous, False
+        if non_interactive_token(self._provider) is None:
+            return anonymous, False
+        try:
+            return self._send(self._authed, "GET", "/api/v1/me", "the caller", "read"), True
+        except DocketToolError:
+            return anonymous, False  # rejected or unreachable: show the anonymous view
+
+    @property
+    def auth_mode(self) -> str:
+        return str(self.me().get("auth_mode", "disabled"))
+
+    # -- writes (carry a token unless the server has auth disabled) ------------------------------
+
+    def post(
+        self,
+        path: str,
+        body: Any = None,
+        *,
+        action: str,
+        idempotency_key: str | None = None,
+        **params: Any,
+    ) -> Any:
+        headers = {"Idempotency-Key": idempotency_key} if idempotency_key else None
+        return self._write("POST", path, body, action, headers, params)
+
+    def patch(self, path: str, body: Any, *, action: str) -> Any:
+        return self._write("PATCH", path, body, action, None, {})
+
+    def preview(self, path: str, body: Any = None) -> Any:
+        """A server preview endpoint: it writes nothing, so it carries no token."""
+        return self._send(self._anonymous, "POST", path, "this", "preview", json=body)
+
+    def _write(
+        self,
+        method: str,
+        path: str,
+        body: Any,
+        action: str,
+        headers: dict[str, str] | None,
+        params: dict[str, Any],
+    ) -> Any:
+        client = self._anonymous if self.auth_mode == "disabled" else self._credentialed()
+        query = {k: v for k, v in params.items() if v is not None}
+        return self._send(
+            client, method, path, "this", action, json=body, headers=headers, params=query
+        )
+
+    def _credentialed(self) -> Client:
+        if self._authed is None or self._provider is None:
+            if self.auth_mode == "tokens":
+                raise DocketToolError(TOKEN_HELP)
+            raise DocketToolError(
+                "This Docket needs a signed-in caller for changes. "
+                f"{TOKEN_HELP} Or sign in as yourself: set DOCKET_AUTH_CLIENT_ID, DOCKET_AUTH_SCOPE "
+                "and DOCKET_AUTH_TENANT_ID (or DOCKET_AUTH_AUTHORITY)."
+            )
+        return self._authed  # type: ignore[return-value]
+
+    # -- plumbing --------------------------------------------------------------------------------
+
+    def _send(
+        self, client: Any, method: str, path: str, what: str, action: str, **kwargs: Any
+    ) -> Any:
+        try:
+            response = client.get_httpx_client().request(method, path, **kwargs)
+        except SignInRequired as error:
+            raise DocketToolError(str(error)) from None
+        except AuthenticationError as error:
+            raise DocketToolError(f"Could not get a token: {error}") from None
+        except httpx.TimeoutException:
+            raise DocketToolError(
+                f"Docket at {self.settings.api_url} did not answer in time."
+            ) from None
+        except httpx.HTTPError as error:
+            raise DocketToolError(
+                f"Cannot reach Docket at {self.settings.api_url} ({type(error).__name__}). "
+                "Is the server running, and are you on the VPN? Check DOCKET_API_URL."
+            ) from None
+        if response.status_code >= 400:
+            raise _problem(response, action)
+        if not response.content:
+            return None
+        return response.json()
+
+
+def _problem(response: httpx.Response, action: str) -> DocketToolError:
+    """Map an RFC 9457 problem response to a message the model can act on."""
+    detail = ""
+    code = ""
+    errors: Any = None
+    try:
+        body = response.json()
+        detail = str(body.get("detail") or body.get("title") or "")
+        code = str(body.get("code") or "")
+        errors = body.get("errors")
+    except ValueError:
+        detail = response.text[:200]
+    status = response.status_code
+    suffix = f" ({detail})" if detail else ""
+    if status == 401:
+        return DocketToolError(
+            f"Not signed in, or the credential was rejected{suffix}. "
+            "If you use an API token it may be revoked or expired: "
+            "ask an admin for a new one from Settings > Access."
+        )
+    if status == 403:
+        return DocketToolError(
+            f"You are not allowed to {action}{suffix}. "
+            "Sessions can usually only be changed by their creator, a schedule maintainer or an admin."
+        )
+    if status == 404:
+        return DocketToolError(f"Not found{suffix}. Check the id and try again.")
+    if status == 409:
+        return DocketToolError(
+            f"This changed since your preview, or conflicts with another change{suffix}. "
+            "Preview again (dry_run=true), show the user, and confirm that one."
+        )
+    if status in (400, 422):
+        fields = ""
+        if isinstance(errors, dict) and errors:
+            fields = " Fields: " + "; ".join(
+                f"{key}: {', '.join(map(str, value)) if isinstance(value, list) else value}"
+                for key, value in errors.items()
+            )
+        return DocketToolError(f"The server rejected the request{suffix}.{fields}")
+    if status == 429:
+        return DocketToolError(f"Too many requests{suffix}; wait a moment and retry.")
+    if status == 502 or status == 503 or code == "upstream_unavailable":
+        return DocketToolError(
+            f"Docket could not reach an upstream service{suffix}. Try again later."
+        )
+    return DocketToolError(f"Docket returned an unexpected error {status}{suffix}.")