gavvahar-access-kit 1.0.1__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 (35) hide show
  1. gavvahar_access_kit-1.0.1/.gitignore +27 -0
  2. gavvahar_access_kit-1.0.1/LICENSE +21 -0
  3. gavvahar_access_kit-1.0.1/PKG-INFO +308 -0
  4. gavvahar_access_kit-1.0.1/README.md +274 -0
  5. gavvahar_access_kit-1.0.1/pyproject.toml +47 -0
  6. gavvahar_access_kit-1.0.1/src/access_kit/__init__.py +0 -0
  7. gavvahar_access_kit-1.0.1/src/access_kit/_http.py +54 -0
  8. gavvahar_access_kit-1.0.1/src/access_kit/_redis.py +43 -0
  9. gavvahar_access_kit-1.0.1/src/access_kit/budget.py +167 -0
  10. gavvahar_access_kit-1.0.1/src/access_kit/errors.py +9 -0
  11. gavvahar_access_kit-1.0.1/src/access_kit/health.py +42 -0
  12. gavvahar_access_kit-1.0.1/src/access_kit/http.py +62 -0
  13. gavvahar_access_kit-1.0.1/src/access_kit/jobs.py +206 -0
  14. gavvahar_access_kit-1.0.1/src/access_kit/llm/__init__.py +0 -0
  15. gavvahar_access_kit-1.0.1/src/access_kit/llm/core.py +77 -0
  16. gavvahar_access_kit-1.0.1/src/access_kit/llm/factory.py +23 -0
  17. gavvahar_access_kit-1.0.1/src/access_kit/llm/http.py +68 -0
  18. gavvahar_access_kit-1.0.1/src/access_kit/llm/providers.py +95 -0
  19. gavvahar_access_kit-1.0.1/src/access_kit/llm/types.py +56 -0
  20. gavvahar_access_kit-1.0.1/src/access_kit/logging.py +97 -0
  21. gavvahar_access_kit-1.0.1/src/access_kit/notify.py +110 -0
  22. gavvahar_access_kit-1.0.1/src/access_kit/privacy.py +45 -0
  23. gavvahar_access_kit-1.0.1/src/access_kit/py.typed +0 -0
  24. gavvahar_access_kit-1.0.1/src/access_kit/ratelimit.py +94 -0
  25. gavvahar_access_kit-1.0.1/src/access_kit/safe_fetch/__init__.py +0 -0
  26. gavvahar_access_kit-1.0.1/src/access_kit/safe_fetch/errors.py +25 -0
  27. gavvahar_access_kit-1.0.1/src/access_kit/safe_fetch/fetcher.py +147 -0
  28. gavvahar_access_kit-1.0.1/src/access_kit/safe_fetch/ipcheck.py +59 -0
  29. gavvahar_access_kit-1.0.1/src/access_kit/session.py +124 -0
  30. gavvahar_access_kit-1.0.1/src/access_kit/settings.py +30 -0
  31. gavvahar_access_kit-1.0.1/src/access_kit/testing/__init__.py +0 -0
  32. gavvahar_access_kit-1.0.1/src/access_kit/testing/fakes.py +35 -0
  33. gavvahar_access_kit-1.0.1/src/access_kit/testing/fixtures.py +18 -0
  34. gavvahar_access_kit-1.0.1/src/access_kit/testing/ssrf_cases.py +59 -0
  35. gavvahar_access_kit-1.0.1/src/access_kit/turnstile.py +61 -0
@@ -0,0 +1,27 @@
1
+ .lh
2
+ .env
3
+ .vscode
4
+ .giga
5
+ .cursor
6
+ .cursorrules
7
+ AGENTS.md
8
+ copilot-instructions.md
9
+ CLAUDE.md
10
+ node_modules
11
+ .venv
12
+ .claude
13
+
14
+ __pycache__/
15
+ *.py[cod]
16
+ .pytest_cache/
17
+ .mypy_cache/
18
+ .ruff_cache/
19
+ .coverage
20
+ htmlcov/
21
+ .tox/
22
+ **/dist/
23
+ *.egg-info/
24
+ *.tgz
25
+
26
+ web/test-results/
27
+ web/playwright-report/
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Nihar Gavva
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,308 @@
1
+ Metadata-Version: 2.5
2
+ Name: gavvahar-access-kit
3
+ Version: 1.0.1
4
+ Summary: Shared backend toolkit for ClearRead and SoundSight
5
+ Project-URL: Documentation, https://github.com/gavvahar/access-kit/blob/main/docs/api.md
6
+ Project-URL: Issues, https://github.com/gavvahar/access-kit/issues
7
+ Project-URL: Repository, https://github.com/gavvahar/access-kit
8
+ Author: Nihar Gavva
9
+ License-Expression: MIT
10
+ License-File: LICENSE
11
+ Keywords: accessibility,fastapi,redis,ssrf
12
+ Requires-Python: >=3.15
13
+ Requires-Dist: fastapi<1,>=0.115
14
+ Requires-Dist: httpx<1,>=0.28
15
+ Requires-Dist: pydantic-settings<3,>=2.7
16
+ Requires-Dist: pydantic<3,>=2.9
17
+ Requires-Dist: redis<9,>=5
18
+ Provides-Extra: dev
19
+ Requires-Dist: build>=1.2; extra == 'dev'
20
+ Requires-Dist: fakeredis[lua]>=2.26; extra == 'dev'
21
+ Requires-Dist: httpx<1,>=0.28; extra == 'dev'
22
+ Requires-Dist: mypy>=1.14; extra == 'dev'
23
+ Requires-Dist: pre-commit>=4; extra == 'dev'
24
+ Requires-Dist: pytest-asyncio>=0.25; extra == 'dev'
25
+ Requires-Dist: pytest-cov>=6; extra == 'dev'
26
+ Requires-Dist: pytest>=8; extra == 'dev'
27
+ Requires-Dist: ruff>=0.9; extra == 'dev'
28
+ Requires-Dist: tox>=4.24; extra == 'dev'
29
+ Provides-Extra: testing
30
+ Requires-Dist: fakeredis[lua]>=2.26; extra == 'testing'
31
+ Requires-Dist: pytest-asyncio>=0.25; extra == 'testing'
32
+ Requires-Dist: pytest>=8; extra == 'testing'
33
+ Description-Content-Type: text/markdown
34
+
35
+ # access-kit Python
36
+
37
+ Typed backend primitives for ClearRead and SoundSight. Use the latest stable Python 3 release.
38
+
39
+ ## Install
40
+
41
+ The PyPI distribution is `gavvahar-access-kit`; Python imports use `access_kit`.
42
+ The prepared Python release is `1.0.1` (publication status is in the roadmap).
43
+
44
+ ```bash
45
+ python -m pip install 'gavvahar-access-kit==1.0.1'
46
+ ```
47
+
48
+ From the repository root:
49
+
50
+ ```bash
51
+ python -m pip install -e './python[dev]'
52
+ pytest
53
+ mypy
54
+ python -m build python
55
+ ```
56
+
57
+ ## Settings
58
+
59
+ Subclass `access_kit.settings.AccessKitSettings` for application-specific fields.
60
+ Process environment is loaded case-insensitively. Required fields:
61
+
62
+ | Variable | Validation |
63
+ | ----------------- | ------------------------------ |
64
+ | `APP_NAME` | Nonempty string |
65
+ | `PUBLIC_BASE_URL` | HTTP or HTTPS URL |
66
+ | `REDIS_URL` | Redis DSN |
67
+ | `SESSION_SECRET` | Secret, at least 32 characters |
68
+ | `IP_HASH_SALT` | Secret, at least 32 characters |
69
+
70
+ `ENV` is `dev`, `test`, or `prod` (default `dev`).
71
+ `TRUST_CLOUDFLARE_HEADERS` defaults to false. Enable it only when the origin
72
+ accepts verified Cloudflare connections and configure trusted proxy networks in
73
+ `client_ip`; a header alone never establishes proxy trust.
74
+
75
+ Dotenv loading is opt-in: `Settings(_env_file=".env")`.
76
+ Secret fields are redacted in representations; do not log full settings objects,
77
+ validation error dictionaries, connection URLs, or raw input.
78
+
79
+ The configuration uses [Pydantic Settings](https://docs.pydantic.dev/latest/concepts/pydantic_settings/).
80
+
81
+ ## Health
82
+
83
+ ```python
84
+ from fastapi import FastAPI
85
+ from access_kit.health import health_router
86
+
87
+ app = FastAPI()
88
+
89
+
90
+ async def database_ready() -> bool:
91
+ # Replace with the app's asynchronous database ping.
92
+ return True
93
+
94
+
95
+ app.include_router(health_router({"database": database_ready}, timeout=2.0))
96
+ ```
97
+
98
+ Checks run concurrently. Any exception, timeout, or return value other than
99
+ `True` yields HTTP 503. A healthy response is:
100
+
101
+ ```json
102
+ { "status": "ok", "checks": { "database": "ok" } }
103
+ ```
104
+
105
+ Responses use `Cache-Control: no-store` and never contain exception messages.
106
+ Check names are public: use names such as `database`, not connection strings.
107
+ Checks must use asynchronous I/O and cooperate with cancellation. Timeouts cannot
108
+ interrupt blocking code. Without checks, `/healthz` is a liveness endpoint.
109
+
110
+ HTTP status handling follows [FastAPI's response API](https://fastapi.tiangolo.com/advanced/additional-status-codes/).
111
+
112
+ ## Logging and request IDs
113
+
114
+ ```python
115
+ import logging
116
+ from access_kit.logging import request_id_middleware, setup_logging
117
+
118
+ setup_logging(settings)
119
+ app = request_id_middleware(app)
120
+ logging.info("request_done", extra={"status_code": 200, "duration_ms": 12})
121
+ ```
122
+
123
+ Wrap the complete ASGI app so error responses also receive `X-Request-ID`.
124
+ IDs are generated on the server and isolated between concurrent requests.
125
+ `get_request_id()` returns the current ID and resets after the request.
126
+
127
+ The default JSON handler keeps constant event names, safe numeric fields, known
128
+ HTTP methods/provider names, and validated request IDs. It drops bodies, headers,
129
+ URLs, IPs, arbitrary metadata, formatted arguments, exception text, and tracebacks.
130
+ Use constant event names: never put user text in an event name. Configure logging
131
+ at process startup, before installing additional handlers. Separate log handlers
132
+ installed by an app must apply their own equivalent redaction.
133
+
134
+ ## Privacy and anonymous sessions
135
+
136
+ ```python
137
+ from access_kit.privacy import client_ip, hash_ip
138
+ from access_kit.session import session_middleware
139
+
140
+ app = session_middleware(app, secret=settings.session_secret.get_secret_value())
141
+ # Inside a request handler:
142
+ # peer = client_ip(request)
143
+ # identifier = hash_ip(peer, settings.ip_hash_salt.get_secret_value()) if peer else None
144
+ ```
145
+
146
+ `client_ip` ignores forwarding headers by default. Cloudflare extraction requires
147
+ both `trust_cloudflare=True` and explicit `trusted_proxies` CIDRs. The ASGI client
148
+ address must be the actual socket peer; unconditional upstream proxy-header
149
+ rewriting would undermine that check. Keep proxy networks current in the app.
150
+ Malformed or duplicate Cloudflare headers fall back to the verified peer.
151
+
152
+ `hash_ip` uses HMAC-SHA256 and a 32-byte minimum salt, normalizing equivalent IPv6
153
+ and mapped IPv4 literals. The application owns retention/deletion; there is no
154
+ generic SQL deletion helper. Rotating the salt changes identifiers.
155
+
156
+ Use `Depends(get_session_id)` from `access_kit.session` to read the anonymous ID.
157
+ Cookies are HMAC-signed, expire after one year, and use HttpOnly, Secure,
158
+ SameSite=Lax, and Path=/. Pass `secure=False` only for local HTTP development.
159
+ Tampered or expired cookies are replaced without raising a request error.
160
+
161
+ `rotate_session(request)` changes the current ID before response headers are sent.
162
+ Stateless rotation does not revoke old signed cookies. Apps that need revocation
163
+ must reject the old ID in their data store. The cookie is not authentication or
164
+ CSRF protection.
165
+
166
+ ## Safe fetching
167
+
168
+ ```python
169
+ from pathlib import Path
170
+ from access_kit.safe_fetch.fetcher import make_fetcher
171
+
172
+ fetch, download = make_fetcher(max_bytes=5_000_000, total_timeout=15)
173
+ result = await fetch("https://example.com/document")
174
+ # result.url, result.content, result.content_type, result.status_code
175
+ await download("https://example.com/document", Path("document.html"))
176
+ ```
177
+
178
+ HTTP(S) URLs may use only ports 80 or 443, with no credentials or local names.
179
+ Every DNS answer must be public; mixed public/private answers are rejected.
180
+ The validated numeric IP is used as the socket target, with the original Host
181
+ and TLS verification hostname preserved. Each redirect gets a new client and
182
+ fresh validation, including rejection of HTTPS-to-HTTP downgrades. Proxy settings,
183
+ ambient cookies, automatic redirects, and HTTP retries are disabled.
184
+
185
+ The default media types are HTML, XHTML, plain text, and JSON. Supply an explicit
186
+ `allowed_content_types=frozenset({...})` for other content. Content encoding must
187
+ be identity to avoid decompression bombs. Announced and streamed byte counts are
188
+ bounded, and the total timeout includes DNS, redirects, and body reads.
189
+
190
+ Downloads write to a temporary file and publish atomically after success. Existing
191
+ paths are never overwritten. Failures and cancellation remove temporary files.
192
+ Disk writes are synchronous in bounded chunks; network deadlines cannot interrupt
193
+ blocking filesystem operations. File types and fetched HTML remain untrusted:
194
+ apps must sanitize content and enforce suitable rendering/download policies.
195
+
196
+ Errors live in `access_kit.safe_fetch.errors`: `BlockedDestination`, `TooLarge`,
197
+ `BadContentType`, `TooManyRedirects`, `FetchTimeout`, and their base `FetchError`.
198
+ Error messages omit submitted URLs and response bodies.
199
+
200
+ IP pinning uses HTTPX's documented
201
+ [`sni_hostname` extension](https://www.python-httpx.org/advanced/extensions/).
202
+ The regression suite tests actual HTTPX/httpcore socket arguments and TLS names,
203
+ not only mocked responses. Reusable attack URLs live in
204
+ `access_kit.testing.ssrf_cases.SSRF_CASES`; redirect, rebinding, cancellation,
205
+ streaming-limit, and TLS tests are maintained in `python/tests/test_safe_fetch.py`.
206
+
207
+ ## LLM providers and strict JSON
208
+
209
+ ```python
210
+ from typing import TypedDict
211
+ from access_kit.llm.factory import provider_from_settings
212
+
213
+ Summary = TypedDict("Summary", {"summary": str})
214
+ provider = provider_from_settings(settings)
215
+ result, tokens = await provider["complete_json"]("Summarize the document.", "Document content", Summary)
216
+ ```
217
+
218
+ Configure `LLM_PROVIDER` (`anthropic`, `ollama`, or `omniroute`) and `LLM_MODEL`
219
+ explicitly. Remote models and credentials are never selected implicitly.
220
+ `LLM_API_KEY` is a redacted secret. `LLM_BASE_URL` overrides the trusted provider
221
+ endpoint. Ollama defaults to `http://localhost:11434/v1`; OmniRoute requires an
222
+ explicit base URL and API key. Remote endpoints must use HTTPS; HTTP is allowed
223
+ only on loopback. Provider endpoint configuration is trusted app configuration,
224
+ not a place to pass user-submitted URLs.
225
+
226
+ Direct factories live in `access_kit.llm.providers`. Both adapters expose a dict
227
+ with `complete_text`, `complete_json`, provider name, model, and an input limit.
228
+ They use the [Anthropic Messages API](https://platform.claude.com/docs/en/api/messages/create)
229
+ and [Ollama's OpenAI-compatible Chat Completions API](https://docs.ollama.com/api/openai-compatibility).
230
+ Models are always caller-selected. The input limit is enforced as a conservative
231
+ UTF-8 byte cap plus 1,024 bytes of framing allowance, not a tokenizer or a billing
232
+ estimate. The provider remains responsible for its actual model context limit.
233
+
234
+ `complete_json` validates with a Pydantic TypeAdapter in strict mode. It retries
235
+ invalid JSON/schema responses twice by default; fences and string-to-integer
236
+ coercion are not accepted. Retry limits are configurable from zero to five.
237
+ Transport failures, refusals, truncation, and tool calls fail explicitly.
238
+ HTTP responses are bounded to one MB and have a total timeout; HTTP retries and
239
+ redirect following are disabled. Injected HTTPX clients remain caller-owned.
240
+
241
+ `Usage` contains `input_tokens`, `output_tokens`, `total_tokens`, and `complete`.
242
+ Anthropic cached input tokens are included. JSON retries and explicit provider
243
+ fallbacks accumulate usage across failed attempts. Errors also carry `.usage`.
244
+ `complete=False` means some usage could not be established, for example after a
245
+ connection reset. Do not interpret unknown usage as zero spending.
246
+
247
+ `with_fallback([...])` in `access_kit.llm.core` is opt-in: it sends the prompt to
248
+ each configured provider in order until one succeeds. If every provider fails,
249
+ `LLMFallbackError` retains sanitized errors and accumulated known usage.
250
+ Weighted rate limiting and daily budgets are available as explicit protection
251
+ modules. Provider factories do not silently apply a cap: reserve a verified upper
252
+ bound before dispatch, including every possible retry and fallback attempt.
253
+
254
+ ## Consumer test helpers
255
+
256
+ Install `gavvahar-access-kit[testing]` for pytest/fakeredis support. Fixtures are opt-in:
257
+
258
+ ```python
259
+ # conftest.py
260
+ pytest_plugins = ["access_kit.testing.fixtures"]
261
+ ```
262
+
263
+ The async `fake_redis` fixture closes its in-memory client after each test.
264
+ `fake_llm` in `access_kit.testing.fakes` returns `(provider, calls)` and runs the
265
+ same JSON validation and retry logic as real providers. Supply strings or
266
+ `LLMError` instances as deterministic responses; exhausted responses fail clearly.
267
+ The call records retain prompts in test memory and must not be used in production.
268
+
269
+ All Python `__init__.py` files are empty. Import from named modules rather than
270
+ package-level re-exports. Read the installed version with
271
+ `importlib.metadata.version("access-kit")`.
272
+
273
+ ## Release acceptance
274
+
275
+ The library core and a consumer-style FastAPI integration test are implemented.
276
+ ClearRead's Phase 1 pipeline is not present in its current template repository,
277
+ so the planned `py-v0.1.0` consuming-app acceptance check is still pending.
278
+ The protection and progress modules are implemented and tested locally; real
279
+ consuming-app acceptance and authenticated registry uploads remain pending.
280
+ See [the roadmap](https://github.com/gavvahar/access-kit/blob/main/docs/roadmap.md).
281
+
282
+ ## Protection, delivery, and job progress
283
+
284
+ `ratelimit`, `turnstile`, `budget`, and `notify` are documented with configuration,
285
+ error handling and operating constraints in [the protection guide](https://github.com/gavvahar/access-kit/blob/main/docs/protection.md).
286
+ `jobs` provides owner-scoped worker progress and a FastAPI SSE response helper;
287
+ see [job integration](https://github.com/gavvahar/access-kit/blob/main/docs/jobs.md). Public infrastructure exceptions live in
288
+ `access_kit.errors`. Storage failure must deny protected work.
289
+
290
+ Install `[testing]` or `[dev]` to run Redis Lua scripts with fakeredis. On the
291
+ latest Python, a native Lua wheel may need the compiler toolchain supplied by
292
+ `environment.yml`; no sudo is required. The real Redis CI check independently
293
+ exercises concurrent budget admission, weighted limits and job event replay.
294
+ The [API inventory](https://github.com/gavvahar/access-kit/blob/main/docs/api.md) covers every supported module; the
295
+ [architecture decisions](https://github.com/gavvahar/access-kit/blob/main/docs/decisions.md) explain ownership and lifecycle.
296
+
297
+ ## Bounded HTTP requests
298
+
299
+ Wrap an ASGI app with `access_kit.http.body_limit(app, max_bytes=1_000_000,
300
+ read_timeout=15)` before exposing JSON/document endpoints. Oversized declared or
301
+ streamed bodies receive 413 before framework parsing. Duplicate/invalid/mismatched
302
+ Content-Length receives 400; body-read timeout receives 408. Non-HTTP scopes pass
303
+ through. Valid bodies replay once, then preserve the original disconnect stream.
304
+ This buffers bounded requests; use a separate design for streaming uploads.
305
+
306
+ `provider_from_settings` accepts explicit `max_tokens`, `max_input_tokens`,
307
+ `timeout` and `json_retries` overrides. Consumer budgets can reserve the true
308
+ upper bound across those bounded attempts instead of guessing factory defaults.
@@ -0,0 +1,274 @@
1
+ # access-kit Python
2
+
3
+ Typed backend primitives for ClearRead and SoundSight. Use the latest stable Python 3 release.
4
+
5
+ ## Install
6
+
7
+ The PyPI distribution is `gavvahar-access-kit`; Python imports use `access_kit`.
8
+ The prepared Python release is `1.0.1` (publication status is in the roadmap).
9
+
10
+ ```bash
11
+ python -m pip install 'gavvahar-access-kit==1.0.1'
12
+ ```
13
+
14
+ From the repository root:
15
+
16
+ ```bash
17
+ python -m pip install -e './python[dev]'
18
+ pytest
19
+ mypy
20
+ python -m build python
21
+ ```
22
+
23
+ ## Settings
24
+
25
+ Subclass `access_kit.settings.AccessKitSettings` for application-specific fields.
26
+ Process environment is loaded case-insensitively. Required fields:
27
+
28
+ | Variable | Validation |
29
+ | ----------------- | ------------------------------ |
30
+ | `APP_NAME` | Nonempty string |
31
+ | `PUBLIC_BASE_URL` | HTTP or HTTPS URL |
32
+ | `REDIS_URL` | Redis DSN |
33
+ | `SESSION_SECRET` | Secret, at least 32 characters |
34
+ | `IP_HASH_SALT` | Secret, at least 32 characters |
35
+
36
+ `ENV` is `dev`, `test`, or `prod` (default `dev`).
37
+ `TRUST_CLOUDFLARE_HEADERS` defaults to false. Enable it only when the origin
38
+ accepts verified Cloudflare connections and configure trusted proxy networks in
39
+ `client_ip`; a header alone never establishes proxy trust.
40
+
41
+ Dotenv loading is opt-in: `Settings(_env_file=".env")`.
42
+ Secret fields are redacted in representations; do not log full settings objects,
43
+ validation error dictionaries, connection URLs, or raw input.
44
+
45
+ The configuration uses [Pydantic Settings](https://docs.pydantic.dev/latest/concepts/pydantic_settings/).
46
+
47
+ ## Health
48
+
49
+ ```python
50
+ from fastapi import FastAPI
51
+ from access_kit.health import health_router
52
+
53
+ app = FastAPI()
54
+
55
+
56
+ async def database_ready() -> bool:
57
+ # Replace with the app's asynchronous database ping.
58
+ return True
59
+
60
+
61
+ app.include_router(health_router({"database": database_ready}, timeout=2.0))
62
+ ```
63
+
64
+ Checks run concurrently. Any exception, timeout, or return value other than
65
+ `True` yields HTTP 503. A healthy response is:
66
+
67
+ ```json
68
+ { "status": "ok", "checks": { "database": "ok" } }
69
+ ```
70
+
71
+ Responses use `Cache-Control: no-store` and never contain exception messages.
72
+ Check names are public: use names such as `database`, not connection strings.
73
+ Checks must use asynchronous I/O and cooperate with cancellation. Timeouts cannot
74
+ interrupt blocking code. Without checks, `/healthz` is a liveness endpoint.
75
+
76
+ HTTP status handling follows [FastAPI's response API](https://fastapi.tiangolo.com/advanced/additional-status-codes/).
77
+
78
+ ## Logging and request IDs
79
+
80
+ ```python
81
+ import logging
82
+ from access_kit.logging import request_id_middleware, setup_logging
83
+
84
+ setup_logging(settings)
85
+ app = request_id_middleware(app)
86
+ logging.info("request_done", extra={"status_code": 200, "duration_ms": 12})
87
+ ```
88
+
89
+ Wrap the complete ASGI app so error responses also receive `X-Request-ID`.
90
+ IDs are generated on the server and isolated between concurrent requests.
91
+ `get_request_id()` returns the current ID and resets after the request.
92
+
93
+ The default JSON handler keeps constant event names, safe numeric fields, known
94
+ HTTP methods/provider names, and validated request IDs. It drops bodies, headers,
95
+ URLs, IPs, arbitrary metadata, formatted arguments, exception text, and tracebacks.
96
+ Use constant event names: never put user text in an event name. Configure logging
97
+ at process startup, before installing additional handlers. Separate log handlers
98
+ installed by an app must apply their own equivalent redaction.
99
+
100
+ ## Privacy and anonymous sessions
101
+
102
+ ```python
103
+ from access_kit.privacy import client_ip, hash_ip
104
+ from access_kit.session import session_middleware
105
+
106
+ app = session_middleware(app, secret=settings.session_secret.get_secret_value())
107
+ # Inside a request handler:
108
+ # peer = client_ip(request)
109
+ # identifier = hash_ip(peer, settings.ip_hash_salt.get_secret_value()) if peer else None
110
+ ```
111
+
112
+ `client_ip` ignores forwarding headers by default. Cloudflare extraction requires
113
+ both `trust_cloudflare=True` and explicit `trusted_proxies` CIDRs. The ASGI client
114
+ address must be the actual socket peer; unconditional upstream proxy-header
115
+ rewriting would undermine that check. Keep proxy networks current in the app.
116
+ Malformed or duplicate Cloudflare headers fall back to the verified peer.
117
+
118
+ `hash_ip` uses HMAC-SHA256 and a 32-byte minimum salt, normalizing equivalent IPv6
119
+ and mapped IPv4 literals. The application owns retention/deletion; there is no
120
+ generic SQL deletion helper. Rotating the salt changes identifiers.
121
+
122
+ Use `Depends(get_session_id)` from `access_kit.session` to read the anonymous ID.
123
+ Cookies are HMAC-signed, expire after one year, and use HttpOnly, Secure,
124
+ SameSite=Lax, and Path=/. Pass `secure=False` only for local HTTP development.
125
+ Tampered or expired cookies are replaced without raising a request error.
126
+
127
+ `rotate_session(request)` changes the current ID before response headers are sent.
128
+ Stateless rotation does not revoke old signed cookies. Apps that need revocation
129
+ must reject the old ID in their data store. The cookie is not authentication or
130
+ CSRF protection.
131
+
132
+ ## Safe fetching
133
+
134
+ ```python
135
+ from pathlib import Path
136
+ from access_kit.safe_fetch.fetcher import make_fetcher
137
+
138
+ fetch, download = make_fetcher(max_bytes=5_000_000, total_timeout=15)
139
+ result = await fetch("https://example.com/document")
140
+ # result.url, result.content, result.content_type, result.status_code
141
+ await download("https://example.com/document", Path("document.html"))
142
+ ```
143
+
144
+ HTTP(S) URLs may use only ports 80 or 443, with no credentials or local names.
145
+ Every DNS answer must be public; mixed public/private answers are rejected.
146
+ The validated numeric IP is used as the socket target, with the original Host
147
+ and TLS verification hostname preserved. Each redirect gets a new client and
148
+ fresh validation, including rejection of HTTPS-to-HTTP downgrades. Proxy settings,
149
+ ambient cookies, automatic redirects, and HTTP retries are disabled.
150
+
151
+ The default media types are HTML, XHTML, plain text, and JSON. Supply an explicit
152
+ `allowed_content_types=frozenset({...})` for other content. Content encoding must
153
+ be identity to avoid decompression bombs. Announced and streamed byte counts are
154
+ bounded, and the total timeout includes DNS, redirects, and body reads.
155
+
156
+ Downloads write to a temporary file and publish atomically after success. Existing
157
+ paths are never overwritten. Failures and cancellation remove temporary files.
158
+ Disk writes are synchronous in bounded chunks; network deadlines cannot interrupt
159
+ blocking filesystem operations. File types and fetched HTML remain untrusted:
160
+ apps must sanitize content and enforce suitable rendering/download policies.
161
+
162
+ Errors live in `access_kit.safe_fetch.errors`: `BlockedDestination`, `TooLarge`,
163
+ `BadContentType`, `TooManyRedirects`, `FetchTimeout`, and their base `FetchError`.
164
+ Error messages omit submitted URLs and response bodies.
165
+
166
+ IP pinning uses HTTPX's documented
167
+ [`sni_hostname` extension](https://www.python-httpx.org/advanced/extensions/).
168
+ The regression suite tests actual HTTPX/httpcore socket arguments and TLS names,
169
+ not only mocked responses. Reusable attack URLs live in
170
+ `access_kit.testing.ssrf_cases.SSRF_CASES`; redirect, rebinding, cancellation,
171
+ streaming-limit, and TLS tests are maintained in `python/tests/test_safe_fetch.py`.
172
+
173
+ ## LLM providers and strict JSON
174
+
175
+ ```python
176
+ from typing import TypedDict
177
+ from access_kit.llm.factory import provider_from_settings
178
+
179
+ Summary = TypedDict("Summary", {"summary": str})
180
+ provider = provider_from_settings(settings)
181
+ result, tokens = await provider["complete_json"]("Summarize the document.", "Document content", Summary)
182
+ ```
183
+
184
+ Configure `LLM_PROVIDER` (`anthropic`, `ollama`, or `omniroute`) and `LLM_MODEL`
185
+ explicitly. Remote models and credentials are never selected implicitly.
186
+ `LLM_API_KEY` is a redacted secret. `LLM_BASE_URL` overrides the trusted provider
187
+ endpoint. Ollama defaults to `http://localhost:11434/v1`; OmniRoute requires an
188
+ explicit base URL and API key. Remote endpoints must use HTTPS; HTTP is allowed
189
+ only on loopback. Provider endpoint configuration is trusted app configuration,
190
+ not a place to pass user-submitted URLs.
191
+
192
+ Direct factories live in `access_kit.llm.providers`. Both adapters expose a dict
193
+ with `complete_text`, `complete_json`, provider name, model, and an input limit.
194
+ They use the [Anthropic Messages API](https://platform.claude.com/docs/en/api/messages/create)
195
+ and [Ollama's OpenAI-compatible Chat Completions API](https://docs.ollama.com/api/openai-compatibility).
196
+ Models are always caller-selected. The input limit is enforced as a conservative
197
+ UTF-8 byte cap plus 1,024 bytes of framing allowance, not a tokenizer or a billing
198
+ estimate. The provider remains responsible for its actual model context limit.
199
+
200
+ `complete_json` validates with a Pydantic TypeAdapter in strict mode. It retries
201
+ invalid JSON/schema responses twice by default; fences and string-to-integer
202
+ coercion are not accepted. Retry limits are configurable from zero to five.
203
+ Transport failures, refusals, truncation, and tool calls fail explicitly.
204
+ HTTP responses are bounded to one MB and have a total timeout; HTTP retries and
205
+ redirect following are disabled. Injected HTTPX clients remain caller-owned.
206
+
207
+ `Usage` contains `input_tokens`, `output_tokens`, `total_tokens`, and `complete`.
208
+ Anthropic cached input tokens are included. JSON retries and explicit provider
209
+ fallbacks accumulate usage across failed attempts. Errors also carry `.usage`.
210
+ `complete=False` means some usage could not be established, for example after a
211
+ connection reset. Do not interpret unknown usage as zero spending.
212
+
213
+ `with_fallback([...])` in `access_kit.llm.core` is opt-in: it sends the prompt to
214
+ each configured provider in order until one succeeds. If every provider fails,
215
+ `LLMFallbackError` retains sanitized errors and accumulated known usage.
216
+ Weighted rate limiting and daily budgets are available as explicit protection
217
+ modules. Provider factories do not silently apply a cap: reserve a verified upper
218
+ bound before dispatch, including every possible retry and fallback attempt.
219
+
220
+ ## Consumer test helpers
221
+
222
+ Install `gavvahar-access-kit[testing]` for pytest/fakeredis support. Fixtures are opt-in:
223
+
224
+ ```python
225
+ # conftest.py
226
+ pytest_plugins = ["access_kit.testing.fixtures"]
227
+ ```
228
+
229
+ The async `fake_redis` fixture closes its in-memory client after each test.
230
+ `fake_llm` in `access_kit.testing.fakes` returns `(provider, calls)` and runs the
231
+ same JSON validation and retry logic as real providers. Supply strings or
232
+ `LLMError` instances as deterministic responses; exhausted responses fail clearly.
233
+ The call records retain prompts in test memory and must not be used in production.
234
+
235
+ All Python `__init__.py` files are empty. Import from named modules rather than
236
+ package-level re-exports. Read the installed version with
237
+ `importlib.metadata.version("access-kit")`.
238
+
239
+ ## Release acceptance
240
+
241
+ The library core and a consumer-style FastAPI integration test are implemented.
242
+ ClearRead's Phase 1 pipeline is not present in its current template repository,
243
+ so the planned `py-v0.1.0` consuming-app acceptance check is still pending.
244
+ The protection and progress modules are implemented and tested locally; real
245
+ consuming-app acceptance and authenticated registry uploads remain pending.
246
+ See [the roadmap](https://github.com/gavvahar/access-kit/blob/main/docs/roadmap.md).
247
+
248
+ ## Protection, delivery, and job progress
249
+
250
+ `ratelimit`, `turnstile`, `budget`, and `notify` are documented with configuration,
251
+ error handling and operating constraints in [the protection guide](https://github.com/gavvahar/access-kit/blob/main/docs/protection.md).
252
+ `jobs` provides owner-scoped worker progress and a FastAPI SSE response helper;
253
+ see [job integration](https://github.com/gavvahar/access-kit/blob/main/docs/jobs.md). Public infrastructure exceptions live in
254
+ `access_kit.errors`. Storage failure must deny protected work.
255
+
256
+ Install `[testing]` or `[dev]` to run Redis Lua scripts with fakeredis. On the
257
+ latest Python, a native Lua wheel may need the compiler toolchain supplied by
258
+ `environment.yml`; no sudo is required. The real Redis CI check independently
259
+ exercises concurrent budget admission, weighted limits and job event replay.
260
+ The [API inventory](https://github.com/gavvahar/access-kit/blob/main/docs/api.md) covers every supported module; the
261
+ [architecture decisions](https://github.com/gavvahar/access-kit/blob/main/docs/decisions.md) explain ownership and lifecycle.
262
+
263
+ ## Bounded HTTP requests
264
+
265
+ Wrap an ASGI app with `access_kit.http.body_limit(app, max_bytes=1_000_000,
266
+ read_timeout=15)` before exposing JSON/document endpoints. Oversized declared or
267
+ streamed bodies receive 413 before framework parsing. Duplicate/invalid/mismatched
268
+ Content-Length receives 400; body-read timeout receives 408. Non-HTTP scopes pass
269
+ through. Valid bodies replay once, then preserve the original disconnect stream.
270
+ This buffers bounded requests; use a separate design for streaming uploads.
271
+
272
+ `provider_from_settings` accepts explicit `max_tokens`, `max_input_tokens`,
273
+ `timeout` and `json_retries` overrides. Consumer budgets can reserve the true
274
+ upper bound across those bounded attempts instead of guessing factory defaults.
@@ -0,0 +1,47 @@
1
+ [build-system]
2
+ requires = ["hatchling>=1.27"]
3
+ build-backend = "hatchling.build"
4
+
5
+ [project]
6
+ name = "gavvahar-access-kit"
7
+ version = "1.0.1"
8
+ description = "Shared backend toolkit for ClearRead and SoundSight"
9
+ keywords = ["accessibility", "fastapi", "ssrf", "redis"]
10
+ readme = "README.md"
11
+ requires-python = ">=3.15"
12
+ license = "MIT"
13
+ license-files = ["LICENSE"]
14
+ authors = [{ name = "Nihar Gavva" }]
15
+ dependencies = [
16
+ "fastapi>=0.115,<1",
17
+ "pydantic-settings>=2.7,<3",
18
+ "pydantic>=2.9,<3",
19
+ "httpx>=0.28,<1",
20
+ "redis>=5,<9",
21
+ ]
22
+
23
+ [project.optional-dependencies]
24
+ testing = ["fakeredis[lua]>=2.26", "pytest>=8", "pytest-asyncio>=0.25"]
25
+ dev = [
26
+ "build>=1.2",
27
+ "fakeredis[lua]>=2.26",
28
+ "httpx>=0.28,<1",
29
+ "mypy>=1.14",
30
+ "pytest>=8",
31
+ "pytest-asyncio>=0.25",
32
+ "pytest-cov>=6",
33
+ "ruff>=0.9",
34
+ "tox>=4.24",
35
+ "pre-commit>=4",
36
+ ]
37
+
38
+ [project.urls]
39
+ Documentation = "https://github.com/gavvahar/access-kit/blob/main/docs/api.md"
40
+ Issues = "https://github.com/gavvahar/access-kit/issues"
41
+ Repository = "https://github.com/gavvahar/access-kit"
42
+
43
+ [tool.hatch.build.targets.wheel]
44
+ packages = ["src/access_kit"]
45
+
46
+ [tool.hatch.build.targets.sdist]
47
+ include = ["src", "README.md", "LICENSE", "pyproject.toml"]
File without changes