basejenerator 0.1.0__tar.gz

basejenerator-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Warren Davies
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

basejenerator-0.1.0/PKG-INFO

@@ -0,0 +1,51 @@
+Metadata-Version: 2.4
+Name: basejenerator
+Version: 0.1.0
+Summary: Abstract base class and return formats for AI Generator classes within the Jeneratorverse.
+License: MIT
+License-File: LICENSE
+Author: Warren Davies
+Requires-Python: >=3.10,<3.15
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Project-URL: Homepage, https://github.com/WarrenDavies/base-jenerator
+Project-URL: Repository, https://github.com/WarrenDavies/base-jenerator
+Description-Content-Type: text/markdown
+
+# Base Jenerator
+
+Abstract base class and return formats for AI Generator classes within the Jeneratorverse, providing a unified API across different media formats. 
+
+The idea is, whether you're running Stable Diffusion 1.5 with imagejenerator, or Llama 3.2 with textjenerator, you'll always call the same methods, and get outputs returned to you in the same format.
+
+## BaseGenerator class
+
+Contract for generator classes that run model inference.
+
+Abstract methods that must be implmented by subclasses are:
+
+* `load`: load the model into memory, and assign the pipeline/model/engine to `self.model`.
+* `prepare`: Reset lifecycle without tearing down the model - e.g., reset torch generators, clear cache, etc.
+* `generate`: The public method that is called to run inference.
+* `generate_impl`: Subclasses must implement this to run inference. Called by `.generate()`.
+* `_quick_wrap`: Helper for subclasses to wrap artifacts into the Artfact class.
+* `teardown`: Purge the model from memory, empty cache, run garbage collector, etc. 
+
+## GeneratorOutput
+
+Wrapper for artifacts generated. Will always return artifacts in a list in  the `.artifacts` attribute, even for pipelines that return a single artifact (e.g., LLMs, non-batch image generation, etc.). Generation level metadata can be returned in `.extras`, however you should reserve this for things really cannot be captured anywhere else. The generator classes are meant to be stateless, besides the model/pipline. 
+
+They are like toasters - prompt in, artifact out.
+
+## Artifact
+
+Represents a single artifact created by the generator. One image, text response, wav file, or whatever.
+
+As with GeneratorOutput you can bundle metadata into `.item_extras` but again, I recommend leaving that responsibility to the calling app.
+
+

basejenerator-0.1.0/README.md

@@ -0,0 +1,31 @@
+# Base Jenerator
+
+Abstract base class and return formats for AI Generator classes within the Jeneratorverse, providing a unified API across different media formats. 
+
+The idea is, whether you're running Stable Diffusion 1.5 with imagejenerator, or Llama 3.2 with textjenerator, you'll always call the same methods, and get outputs returned to you in the same format.
+
+## BaseGenerator class
+
+Contract for generator classes that run model inference.
+
+Abstract methods that must be implmented by subclasses are:
+
+* `load`: load the model into memory, and assign the pipeline/model/engine to `self.model`.
+* `prepare`: Reset lifecycle without tearing down the model - e.g., reset torch generators, clear cache, etc.
+* `generate`: The public method that is called to run inference.
+* `generate_impl`: Subclasses must implement this to run inference. Called by `.generate()`.
+* `_quick_wrap`: Helper for subclasses to wrap artifacts into the Artfact class.
+* `teardown`: Purge the model from memory, empty cache, run garbage collector, etc. 
+
+## GeneratorOutput
+
+Wrapper for artifacts generated. Will always return artifacts in a list in  the `.artifacts` attribute, even for pipelines that return a single artifact (e.g., LLMs, non-batch image generation, etc.). Generation level metadata can be returned in `.extras`, however you should reserve this for things really cannot be captured anywhere else. The generator classes are meant to be stateless, besides the model/pipline. 
+
+They are like toasters - prompt in, artifact out.
+
+## Artifact
+
+Represents a single artifact created by the generator. One image, text response, wav file, or whatever.
+
+As with GeneratorOutput you can bundle metadata into `.item_extras` but again, I recommend leaving that responsibility to the calling app.
+

basejenerator-0.1.0/pyproject.toml

@@ -0,0 +1,19 @@
+[tool.poetry]
+name = "basejenerator"
+version = "0.1.0"
+description = "Abstract base class and return formats for AI Generator classes within the Jeneratorverse."
+authors = ["Warren Davies"]
+license = "MIT"
+readme = "README.md"
+homepage = "https://github.com/WarrenDavies/base-jenerator"
+repository = "https://github.com/WarrenDavies/base-jenerator"
+packages = [
+    { include = "basejenerator", from = "src" }
+]
+
+[tool.poetry.dependencies]
+python = ">=3.10,<3.15"
+
+[build-system]
+requires = ["poetry-core>=1.0.0"]
+build-backend = "poetry.core.masonry.api"

basejenerator-0.1.0/src/basejenerator/artifact.py

@@ -0,0 +1,15 @@
+from dataclasses import dataclass
+
+@dataclass
+class Artifact:
+    """
+    An individual item generated by a class within the Jenerator ecosystem.
+
+    Attributes:
+        data (any): E.g., PIL image from imagejenerator, string/dict from textjenerator, etc.
+        item_extras (dict): any additional metadata related to this artifact (e.g., seed, token count
+        if this is not derivable outside the generator itself, etc.)
+    """
+    data: Any 
+    item_extras: dict = field(default_factory=dict)
+

basejenerator-0.1.0/src/basejenerator/base_jenerator.py

@@ -0,0 +1,87 @@
+from abc import ABC, abstractmethod
+from typing import List, Dict, Any, Tuple
+
+from basejenerator.generator_output import GeneratorOutput
+from basejenerator.artifact import Artifact
+
+class BaseGenerator(ABC):
+    """
+    Base class with common attributes and methods GenAI models locally.
+    """
+
+    def __init__(self, config: Dict[str, Any]):
+        """
+        Initializes the generator with a config dict.
+
+        Args:
+            config (dict): Configuration dictionary.
+        """
+        self.config = config
+        self.model = None
+        
+
+    @abstractmethod
+    def load(self):
+        """
+        Abstract method to load the model into memory, and run any other initialisation
+        steps needed.
+        
+        Subclasses must implement this to load the specific model and assign 
+        it to `self.model`.
+        """
+        pass
+
+
+    @abstractmethod
+    def prepare(self):
+        """
+        Reset lifecycle without tearing down the model - e.g., reset torch generators,
+        clear cache, etc.
+        """
+        pass
+
+
+    def generate(self) -> GeneratorOutput:
+        """
+        The public API that runs inference.
+
+        Returns:
+            GeneratorOutput        
+        """
+        artifacts, global_extras = self.generate_impl()
+
+        return GeneratorOutput(
+            batch=artifacts,
+            extras=global_extras
+        )
+
+
+    @abstractmethod
+    def generate_impl(self) -> Tuple[List[Artifact], Dict[str, Any]]:
+        """
+        Abstract method containing the core generation logic.
+
+        Subclasses must implement this to run the inference and return artifacts and params.
+
+        Returns:
+            artifacts (List[Artifact]): A list of Artifact objects containing the artifacts generated by the model
+            global_extras (Dict): Dictionary of any generation (i.e., not artifact specific) metadata
+        """
+        pass
+    
+
+    def _quick_wrap(self, raw_data: list) -> List[Artifact]:
+        """
+        Helper for subclasses to wrap artifacts into the Artfact class.
+        """
+        return [Artifact(data=item, item_extras={}) for item in raw_data]
+
+
+    @abstractmethod
+    def teardown(self):
+        """
+        Purge the model from memory, empty cache, run garbage collector, etc. 
+        Clears the slate to avoid bleed between inference runs.
+        """
+        pass
+

basejenerator-0.1.0/src/basejenerator/generator_output.py

@@ -0,0 +1,11 @@
+from dataclasses import dataclass
+
+from basejenerator.artifact import Artifact
+
+@dataclass
+class GeneratorOutput:
+    """
+    Standardized return type for all GenAI pipelines within the Jenerator ecosystem
+    """
+    batch: List[Artifact]
+    extras: dict = field(default_factory=dict)