refactor: rethink of states, result types, adds batch_ids, gen/job thread safety

refactor: dynamic params via `additional_params` for image gen

This allows extendibility, allowing parameter types or categories either unknown the SDK or as implemented by third parties.

style: catch up

fix/style: missing import, lingering style issues

[pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

fix: remove `type` syntax for now

I am unclear how to guard it from raising an exception right now and its not terribly important as it just helps my IDE color it a certain way

fix: use compat version of horde_model_reference

fix: using `typing_extensions` for `override`

This namespace migration is only effective as of python 3.12 and later, and the old namespace appears to still be valid in 3.12 and 3.13 at this time.

Author: tazlin

.pre-commit-config.yaml

@@ -31,7 +31,7 @@ repos:
             types-urllib3,
             types-aiofiles,
             StrEnum,
-            horde_model_reference==0.9.2,
+            horde_model_reference==0.10.0,
         ]
 - repo: https://github.com/gauge-sh/tach-pre-commit
   rev: v0.27.0

CONTRIBUTING.md

@@ -51,7 +51,7 @@
   - See all rules (but not necessarily used in the project) availible in rust [here](https://beta.ruff.rs/docs/rules/).
   - Run with `ruff check .`
     - Note: When using autofixing (`ruff check . --fix`), changes may be made that require running black, which can then result in needing to run `ruff check . --fix` again.
-    - Consider running `black . && ruff check . --fix && black . && ruff check . --fix` to avoid this. 
+    - Consider running `black . && ruff check . --fix && black . && ruff check . --fix` to avoid this.
 - [**mypy**](https://mypy-lang.org/)
   - Static type safety
   - I recommending using the [mypy daemon](https://mypy.readthedocs.io/en/stable/mypy_daemon.html) instead of periodically running `pre-commit` (or `mypy` directly.).
@@ -65,7 +65,7 @@
     - `"python.analysis.languageServerMode": "full"`
     - `"python.testing.pytestEnabled": true`
 - [**tach**](https://github.com/gauge-sh/tach)
-  - Enforces internal namespace dependency constraints. This helps avoid circular dependencies and helps ensure implementations are in a logical place.  
+  - Enforces internal namespace dependency constraints. This helps avoid circular dependencies and helps ensure implementations are in a logical place.
 
 ## Code Style and System Design
 
@@ -120,7 +120,7 @@ The Horde ecosystem is a collaborative effort made possible through volunteer ef
 - Update documentation for new features or changes to existing functionality
 - Use descriptive commit messages consistent with the project commit history, especially for medium-to-large changesets.
   - While it is possible we will squash commits before merging, it is still helpful to have descriptive commit messages for review and opens the possibility of rebasing instead.
-  
+
 #### Don't
 
 - Make large sweeping changes unrelated to your primary goal

docs/concepts/package_structure.md

@@ -18,7 +18,7 @@ API support packages do the following:
 - Constants for API endpoints and other configurations
   - Some examples include the valid values for parameters which accept only certain strings.
   - This also includes consts for default timeout values, default anonymous API keys, etc.
-  
+
 ```bash
 ai_horde_api/
 ├── apimodels/

docs/concepts/style_guide.md

@@ -71,7 +71,7 @@ Many classes contain standardized prefixes, suffixes, or identifiers within thei
 - **Base** (Always a Prefix): Indicates a foundational class that provides core functionality and may be abstract or partially implemented. It is intended to be extended by more specific classes.
   - Examples: `BaseAIHordeClient`, `BaseAIHordeSimpleClient`
 
-#### API/Client Specific  
+#### API/Client Specific
 
 - **Manual**: Refers to classes that do not have context management or automatic session handling. These classes require the user to clean up server resources manually.
   - Examples: `AIHordeAPIManualClient`, `GenericHordeAPIManualClient`
@@ -134,7 +134,7 @@ Many docstrings in the SDK have additional requirements when they are related to
     ```
 
   - Children classes of `HordeResponse` must have additional information, for example:
-  
+
     ```python
     class HordePerformanceResponse(HordeResponseBaseModel):
     """Information about the performance of the horde, such as worker counts and queue sizes.
@@ -146,7 +146,7 @@ Many docstrings in the SDK have additional requirements when they are related to
     ```
 
   - Children classes of `HordeRequest` must have additional information, for example:
-  
+
     ```python
     class HordePerformanceRequest(BaseAIHordeRequest):
         """Request performance information about the horde, such as worker counts and queue sizes.
@@ -160,14 +160,14 @@ Many docstrings in the SDK have additional requirements when they are related to
 - Class and method signatures should prefer keyword-only arguments especially when there are multiple arguments of the same type
   - This improves readability and reduces the chance of passing arguments in the wrong order. Additionally, it improves the ability to add new arguments in the future without breaking existing code.
   - For example, instead of:
-  
+
     ```python
     def create_user(name: str, age: int, email: str):
         ...
     ```
-  
+
     Prefer:
-  
+
     ```python
     def create_user(*, name: str, age: int, email: str):
         ...
@@ -189,23 +189,23 @@ Many docstrings in the SDK have additional requirements when they are related to
   - This is technically enforced by type hints, but it is still important to consider the implications of returning different types, especially as a consumer.
   - Generally, for methods which mutate or return a different type based on input, it should be clear from the method name and documentation that this is the case and which types can be expected based on different inputs.
     - For example, the following method signature should be considered bad practice:
-  
+
       ```python
       def get_items(self, as_list: bool = True) -> list[Item] | set[Item]:
           ...
       ```
 
   - Methods which *can* return a list or a container should *always* return a list or container, even if it is a single item.
     - For example, the following method signature should be considered bad practice:
-  
+
       ```python
       def get_items(self) -> list[Item] | Item:
           ...
       ```
 
   - Methods should avoid returning different container types *unless that is the purpose of the method*.
     - For example, the following method signatures should be considered bad practice:
-  
+
       ```python
       def get_items(self) -> list[Item] | set[Item]:
           ...
@@ -221,7 +221,7 @@ Many docstrings in the SDK have additional requirements when they are related to
 
 - Prefer guard clauses over deeply nested if statements.
   - For example, instead of:
-  
+
     ```python
     def process_item(item: Item):
         if item is not None:
@@ -231,7 +231,7 @@ Many docstrings in the SDK have additional requirements when they are related to
     ```
 
     Prefer:
-  
+
     ```python
     def process_item(item: Item):
         if item is None or not item.is_valid():
@@ -242,18 +242,18 @@ Many docstrings in the SDK have additional requirements when they are related to
 
 - Prefer meaningfully named composite `bool` conditionals over complex multi-line `if` statements.
   - For example, instead of:
-  
+
     ```python
     def is_valid_item(item: Item) -> bool:
-        if (item.has_name() and item.has_value()) or 
+        if (item.has_name() and item.has_value()) or
             (item.has_description() and item.description_valid()):
               if item.is_active():
                   return True
         return False
     ```
 
     Prefer:
-  
+
     ```python
     def is_valid_item(item: Item) -> bool:
         has_name_and_value = item.has_name() and item.has_value()
@@ -299,15 +299,15 @@ Many docstrings in the SDK have additional requirements when they are related to
   - `Enum`s should be used to represent numbers with a specific set of valid values and regular constants can be used for isolated (unconnected) values.
   - If many constants relate to each other, they should be grouped into a class.
     - For example, instead of:
-  
+
       ```python
       MAX_RETRIES = 5
       TIMEOUT = 30
       ...
       ```
 
     Prefer:
-  
+
       ```python
       class APIConfig:
           MAX_RETRIES = 5
@@ -317,7 +317,7 @@ Many docstrings in the SDK have additional requirements when they are related to
 
 ### "KNOWN" Constants
 
-- For consumer convenience, parameters which have a fixed set of known values should be defined as constants in an appropriate `consts.py` file. These constants should be named with the `KNOWN_` prefix and should be defined as `StrEnum`s or `Enum`s as appropriate. 
+- For consumer convenience, parameters which have a fixed set of known values should be defined as constants in an appropriate `consts.py` file. These constants should be named with the `KNOWN_` prefix and should be defined as `StrEnum`s or `Enum`s as appropriate.
 - However, these values should **always be considered optional**. Consumers of the SDK should be able to use any valid value for the parameter as long as its type is correct. It would be ideal, but not required, that classes or functions which require these parameters validate them against the live API at runtime.
   - **_Rationale_**: This prevents the SDK from needing to be updated every time a new value is added to an API, and allows consumers to use any valid value without needing to wait for an SDK update.
 

horde_sdk/consts.py

@@ -1,6 +1,5 @@
 """Constants used by the SDK."""
 
-import sys
 import os
 from enum import IntEnum
 from uuid import UUID
@@ -14,12 +13,8 @@
 _OVERLOADED_MODEL = "_MODEL_OVERLOADED"
 """The model is used incorrectly on the API."""
 
-if sys.version_info <= (3, 12):
-    GENERATION_ID_TYPES = str | UUID
-    """The types that can be used as generation IDs."""
-else:
-    type GENERATION_ID_TYPES = str | UUID
-    """The types that can be used as generation IDs."""
+GENERATION_ID_TYPES = str | UUID
+"""The types that can be used as generation IDs."""
 
 
 def get_default_frozen_model_config_dict() -> ConfigDict:

horde_sdk/generation_parameters/__init__.py

@@ -27,6 +27,7 @@
 from horde_sdk.generation_parameters.generic import BasicModelGenerationParameters, ComposedParameterSetBase
 from horde_sdk.generation_parameters.generic.consts import KNOWN_AUX_MODEL_SOURCE
 from horde_sdk.generation_parameters.image.consts import (
+    CLIP_SKIP_REPRESENTATION,
     KNOWN_IMAGE_CONTROLNETS,
     KNOWN_IMAGE_SAMPLERS,
     KNOWN_IMAGE_SCHEDULERS,
@@ -35,8 +36,18 @@
     LORA_TRIGGER_INJECT_CHOICE,
     TI_TRIGGER_INJECT_CHOICE,
 )
-from horde_sdk.generation_parameters.image.object_models import ImageGenerationParameters
-from horde_sdk.generation_parameters.text.object_models import TextGenerationParameters
+from horde_sdk.generation_parameters.image.object_models import (
+    BasicImageGenerationParameters,
+    BasicImageGenerationParametersTemplate,
+    ImageGenerationParameters,
+    ImageGenerationParametersTemplate,
+)
+from horde_sdk.generation_parameters.text.object_models import (
+    BasicTextGenerationFormatParameters,
+    BasicTextGenerationParameters,
+    KoboldAITextGenerationParameters,
+    TextGenerationParameters,
+)
 
 __all__ = [
     "AlchemyParameters",
@@ -65,6 +76,13 @@
     "KNOWN_IMAGE_WORKFLOWS",
     "LORA_TRIGGER_INJECT_CHOICE",
     "TI_TRIGGER_INJECT_CHOICE",
+    "CLIP_SKIP_REPRESENTATION",
     "ImageGenerationParameters",
+    "BasicImageGenerationParameters",
+    "ImageGenerationParametersTemplate",
+    "BasicImageGenerationParametersTemplate",
     "TextGenerationParameters",
+    "BasicTextGenerationFormatParameters",
+    "BasicTextGenerationParameters",
+    "KoboldAITextGenerationParameters",
 ]

horde_sdk/generation_parameters/alchemy/object_models.py

@@ -1,4 +1,5 @@
-from pydantic import BaseModel, Field
+from pydantic import Field
+from typing_extensions import override
 
 from horde_sdk.generation_parameters.alchemy.consts import (
     KNOWN_ALCHEMY_FORMS,
@@ -10,16 +11,17 @@
     KNOWN_UPSCALERS,
 )
 from horde_sdk.generation_parameters.generic import ComposedParameterSetBase
+from horde_sdk.generation_parameters.generic.object_models import GenerationFeatureFlags
 
 
-class AlchemyFeatureFlags(BaseModel):
+class AlchemyFeatureFlags(GenerationFeatureFlags):
     """Feature flags for an alchemy worker."""
 
     alchemy_types: list[KNOWN_ALCHEMY_TYPES] = Field(default_factory=list)
     """The alchemy types supported by the worker."""
 
 
-class SingleAlchemyParameters(BaseModel):
+class SingleAlchemyParameters(ComposedParameterSetBase):
     """Represents the common bare minimum parameters for any alchemy generation."""
 
     generation_id: str
@@ -31,6 +33,11 @@ class SingleAlchemyParameters(BaseModel):
     source_image: bytes | str | None
     """The source image to use for the generation."""
 
+    @override
+    def get_number_expected_results(self) -> int:
+        """Get the number of expected results."""
+        return 1
+
 
 class UpscaleAlchemyParameters(SingleAlchemyParameters):
     """Represents the parameters for an upscale alchemy generation."""
@@ -86,7 +93,7 @@ class AlchemyParameters(ComposedParameterSetBase):
     def all_alchemy_operations(self) -> list[SingleAlchemyParameters]:
         """Get all operations."""
         if self._all_alchemy_operations is not None:
-            return self._all_alchemy_operations
+            return self._all_alchemy_operations.copy()
 
         all_operations: list[SingleAlchemyParameters] = []
         if self.upscalers:
@@ -104,4 +111,9 @@ def all_alchemy_operations(self) -> list[SingleAlchemyParameters]:
 
         self._all_alchemy_operations = all_operations
 
-        return all_operations
+        return all_operations.copy()
+
+    @override
+    def get_number_expected_results(self) -> int:
+        """Get the number of expected results."""
+        return len(self.all_alchemy_operations)

horde_sdk/generation_parameters/generic/__init__.py

@@ -4,22 +4,50 @@
 base model for generation parameters.
 """
 
+from abc import ABC, abstractmethod
+from typing import Self, Union
+
 from horde_model_reference.meta_consts import KNOWN_IMAGE_GENERATION_BASELINE
-from pydantic import BaseModel
+from pydantic import BaseModel, ConfigDict, Field, create_model
 
 
-class ComposedParameterSetBase(BaseModel):
+class ComposedParameterSetBase(ABC, BaseModel):
     """Base class for all combined (composed) parameter sets.
 
     The top level classes which contain BasicModelGenerationParameters instance and/or other specific parameters
-    should inherit from this class.
+    should inherit from this class. These classes should always represent complete parameter sets that can be used
+    for generation.
     """
 
+    model_config = ConfigDict(
+        use_attribute_docstrings=True,
+    )
+
+    @abstractmethod
+    def get_number_expected_results(self) -> int:
+        """Return the number of expected results for this parameter set.
+
+        Returns:
+            int: The number of expected results.
+        """
+
+
+class GenerationParameterComponentBase(BaseModel):
+    """Base class for all generation parameters components.
+
+    These classes represent components of generation parameters that can be combined to form a complete
+    parameter set. This includes the use of specific auxiliary features such as controlnets, LoRAs, etc.
+    """
+
+    model_config = ConfigDict(
+        use_attribute_docstrings=True,
+    )
+
 
-class BasicModelGenerationParameters(BaseModel):
+class BasicModelGenerationParameters(GenerationParameterComponentBase):
     """Represents the common bare minimum parameters for any model-based generative inference or similar."""
 
-    model: str
+    model: str | None = None
     """The model to use for the generation."""
 
     model_baseline: str | KNOWN_IMAGE_GENERATION_BASELINE | None = None

horde_sdk/generation_parameters/generic/object_models.py

@@ -1,4 +1,4 @@
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, ConfigDict, Field
 
 
 class GenerationFeatureFlags(BaseModel):
@@ -12,4 +12,3 @@ class GenerationFeatureFlags(BaseModel):
 
     extra_source_images: bool = Field(default=False)
     """Whether there is  support for extra source images."""
-