style/chore: fix, update linters, fix lingering static type bugs

Author: tazlin

.github/workflows/maintests.yml

@@ -41,4 +41,4 @@ jobs:
 
 
       - name: Run tests
-        run: uv run pytest tests --ignore-glob='**/*api_calls*' -m "not api_side_ci"
+        run: uv run pytest tests --ignore-glob='**/*api_calls*' -m "not api_side_ci"

.pre-commit-config.yaml

@@ -1,21 +1,18 @@
 repos:
 -   repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v5.0.0
+    rev: v6.0.0
     hooks:
     -   id: check-yaml
         exclude: ^mkdocs\.yml$
     -   id: end-of-file-fixer
     -   id: trailing-whitespace
--   repo: https://github.com/psf/black
-    rev: 24.10.0
-    hooks:
-    -   id: black
 -   repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.7.2
+    rev: v0.14.10
     hooks:
-    -    id: ruff
+    -    id: ruff-check
+    -    id: ruff-format
 -   repo: https://github.com/pre-commit/mirrors-mypy
-    rev: 'v1.13.0'
+    rev: v1.19.1
     hooks:
     -   id: mypy
         args: [., --strict, --ignore-missing-imports, --exclude=^codegen]
@@ -30,10 +27,11 @@ repos:
             types-setuptools,
             types-urllib3,
             types-aiofiles,
+            types-PyYAML,
             StrEnum,
             horde_model_reference>=2.0.0,
         ]
 - repo: https://github.com/gauge-sh/tach-pre-commit
-  rev: v0.27.0
+  rev: v0.29.0
   hooks:
     - id: tach

docs/.pages

@@ -21,7 +21,7 @@ nav:
         - SDK Client Design: concepts/client_design
         - Backend Values Mappers: concepts/backend_values_mappers
     - horde_sdk
-       
+
     - GitHub Repo: 'https://github.com/Haidra-Org/horde-sdk'
 
 order: desc

docs/concepts/backend_values_mappers.md

@@ -131,7 +131,7 @@ def map_to_example_backend_sampler(self, sdk_sampler: KNOWN_IMAGE_SAMPLERS) -> K
     """Maps an SDK sampler to a backend sampler."""
     ...
 
-... 
+...
 ```
 
 #### Understanding `_map_value` and `_is_valid_value`

docs/concepts/client_design.md

@@ -12,9 +12,9 @@ classDiagram
     class GenericHordeAPIManualClient
 
     class GenericAsyncHordeAPIManualClient
-    class GenericHordeAPISession 
+    class GenericHordeAPISession
 
-    class GenericAsyncHordeAPISession 
+    class GenericAsyncHordeAPISession
 
     BaseHordeAPIClient <|-- GenericHordeAPIManualClient
     BaseHordeAPIClient <|-- GenericAsyncHordeAPIManualClient

docs/concepts/style_guide.md

@@ -162,7 +162,7 @@ Many classes contain standardized prefixes, suffixes, or identifiers within thei
         - For example, methods which are known to rely on external resources (e.g., network calls, file I/O) should document the exceptions that may be raised in the event of a failure.
         - It is **not** expected that every conceivable exception raised from a particular call hierarchy is documented, but rather those that are most likely to occur and can be reasonably anticipated.
             - A method that opens a file should document `FileNotFoundError` and `IOError` in its `Raises` section, while network-related methods should document `ConnectionError`, `TimeoutError`, and other relevant exceptions.
-  
+
 ### API Model Specific Documentation
 
 Many docstrings in the SDK have additional requirements when they are related to API models or requests/responses. While these rules would be difficult to remember, they are luckily enforced by CI and the `horde_sdk.meta` module has helper functions to assist in generating the required docstrings. The correct docstrings will also be emitted by the `object_verify` tests. Be sure to run the tests with `-s` to see the output.

docs/worker/generation_states_flow.md

@@ -14,7 +14,7 @@ flowchart TD
 
     NOT_STARTED@{shape: subproc}
     PRELOADING@{shape: subproc}
-    PRELOADING_COMPLETE@{shape: subproc} 
+    PRELOADING_COMPLETE@{shape: subproc}
     PENDING_POST_PROCESSING@{ shape: subproc}
     POST_PROCESSING@{ shape: subproc}
     GENERATING@{ shape: subproc}
@@ -119,7 +119,7 @@ Good:
     - Here, the worker encountered an error during preloading, attempted to recover, but failed again and then aborted the job. Note that you can set the intended number of retries in worker job configuration. See the `HordeWorkerJobConfig` class and the  `state_error_limits` arg in a generation class constructor for more details.
 - `NOT_STARTED` -> `PRELOADING` -> `USER_REQUESTED_ABORT` -> `USER_ABORT_COMPLETE`
     - In this case, the user who created the job requested an abort, and the worker was able to complete the abort process successfully.
-  
+
 Bad:
 
 - `NOT_STARTED` -> `PRELOADING` -> `ERROR` -> `GENERATING`

docs/worker/generations.md

@@ -85,7 +85,7 @@ These functions return the transitioned to state.
 #### Important Notes on State Transitions
 
 - **Strict Order:** You must call state transition methods in the correct sequence. For example, you cannot call `on_generating()` before `on_preloading_complete()`. This strictness helps catch workflow errors early. Out-of-order calls almost always indicate a problem in your logic or resource handling.
-- **Error Handling:** If an error occurs at any step, use `on_error(failed_message="...")` to move the generation into the `ERROR` state. This lets you handle errors gracefully and, if needed, recover. To continue after an error, you must return to the most recent valid state before proceeding.  
+- **Error Handling:** If an error occurs at any step, use `on_error(failed_message="...")` to move the generation into the `ERROR` state. This lets you handle errors gracefully and, if needed, recover. To continue after an error, you must return to the most recent valid state before proceeding.
     - For example, if you are in the `GENERATING` state and an error occurs, call `on_error()` to enter `ERROR`, then call `on_generating()` again to retry.
 - **Dynamic States:** Some transition methods, such as `on_generation_work_complete()`, may lead to different next states depending on context (e.g., whether post-processing is required). The class handles these decisions internally, so you don’t need to manually select the next state.
 - **Manual States:** You can use the generic `step(state)` or `on_state(state)` methods to transition to a specific state. However, you are responsible for ensuring the transition is valid—these methods bypass some of the built-in checks.
@@ -346,7 +346,7 @@ flowchart TD
 
     NOT_STARTED@{shape: subproc}
     PRELOADING@{shape: subproc}
-    PRELOADING_COMPLETE@{shape: subproc} 
+    PRELOADING_COMPLETE@{shape: subproc}
     PENDING_POST_PROCESSING@{ shape: subproc}
     POST_PROCESSING@{ shape: subproc}
     GENERATING@{ shape: subproc}
@@ -451,7 +451,7 @@ Good:
     - Here, the worker encountered an error during preloading, attempted to recover, but failed again and then aborted the job. Note that you can set the intended number of retries in worker job configuration. See the `HordeWorkerJobConfig` class and the  `state_error_limits` arg in a generation class constructor for more details.
 - `NOT_STARTED` -> `PRELOADING` -> `USER_REQUESTED_ABORT` -> `USER_ABORT_COMPLETE`
     - In this case, the user who created the job requested an abort, and the worker was able to complete the abort process successfully.
-  
+
 Bad:
 
 - `NOT_STARTED` -> `PRELOADING` -> `ERROR` -> `GENERATING`

horde_sdk/ai_horde_api/apimodels/documents.py

@@ -14,6 +14,8 @@
 
 
 class DocumentFormat(StrEnum):
+    """The supported formats for a document."""
+
     html = "html"
     markdown = "markdown"
 
@@ -25,7 +27,7 @@ class HordeDocument(HordeResponseBaseModel):
         - /v2/documents/privacy | AIHordeGetPrivacyPolicyRequest [GET] -> 200
 
     v2 API Model: `HordeDocument`
-    """
+    """  # noqa: D205, D415
 
     html: str | None = None
     """The HTML content of the document, if requested."""
@@ -39,6 +41,8 @@ def get_api_model_name(cls) -> str:
 
 
 class AIHordeDocumentRequestMixin(HordeAPIObjectBaseModel):
+    """Mixin for requests that retrieve a document from the AI Horde API."""
+
     format: DocumentFormat | str = DocumentFormat.html
 
     """The format of the document to return. Default is markdown."""

horde_sdk/ai_horde_api/apimodels/generate/text/async_.py

@@ -188,6 +188,8 @@ class _BasePayloadKoboldMixin(HordeAPIData):
 
 @Unhashable
 class ModelPayloadRootKobold(_BasePayloadKoboldMixin):
+    """Base model for KoboldAI generation payloads."""
+
     n: int | None = Field(default=None, examples=[1], ge=1, le=20)
     """The number of generations to produce."""
 
@@ -204,7 +206,7 @@ class ModelPayloadRootKobold(_BasePayloadKoboldMixin):
 
 @Unhashable
 class ModelGenerationInputKobold(ModelPayloadRootKobold):
-    pass
+    """API Parity intermediate model for generation input."""
 
 
 class TextGenerateAsyncDryRunResponse(HordeResponseBaseModel):