textjenerator 0.1.0__tar.gz

textjenerator-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.

textjenerator-0.1.0/PKG-INFO

@@ -0,0 +1,112 @@
+Metadata-Version: 2.4
+Name: textjenerator
+Version: 0.1.0
+Summary: AI text generator
+License-Expression: MIT
+License-File: LICENSE
+Author: Warren Davies
+Requires-Python: >=3.10,<3.15
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Dist: llama-cpp-python (>=0.3.16,<0.4.0)
+Requires-Dist: torch (>=2.9.1,<3.0.0)
+Description-Content-Type: text/markdown
+
+# Text Jenerator
+
+A Unified Python Interface for Modular Text Generation.
+
+Text Jenerator is a framework designed to provide a consistent, abstract interface for deploying and interacting with various Large Language Models (LLMs). By separating the generic configuration and workflow from the model-specific implementation, it enables you to easily switch between different model backends—such as local GGUF models (via Llama-CPP), Hugging Face Transformers, or proprietary APIs (e.g., OpenAI, Gemini), with no code changes besides the config you pass.
+
+## Features
+
+* **Modular Architecture**: Uses Abstract Base Classes (ABC) to enforce a clean separation between the model details, meaning you only need to instantiate the TextGenerator class and call `generate_text()`, no matter which model you're using.
+* **Automatic Setup**: Handles generic tasks like device detection (CPU/CUDA) and data type selection (bfloat16, float16, float32) in the base class.
+* **Plug-and-Play Models**: Easily integrate new models by creating concrete child classes that implement two simple abstract methods (create_pipeline and run_pipeline).
+* **Model Registry**: Uses a decorator (@register_model) to automatically track and load available generation backends.
+
+## Installation
+
+```sh
+pip install textjenerator
+```
+
+The core package has minimal dependencies. Model-specific implementations (e.g., for Llama-CPP or Transformers) require their respective libraries.
+
+## Models
+
+Text Jenerator is BYOM. You can put the local model path or a HuggingFace ID in your config.
+
+## Quick Start & Usage
+
+### Config
+
+Your project should include a config file (defaults are at textjenerator.config). A basic config might look like this:
+
+```json
+config = {
+    # model
+    "model": "llama-cpp",
+    "model_path": ".models/Llama-3.2-3B-Instruct-Q4_K_M.gguf",
+
+    # hardware/system
+    "device": "cpu",
+    "dtype": "float32",
+
+    # LLM
+    "max_context_size": 4096,
+    "number_of_threads": 8 ,
+    "verbose_warnings": False,
+    "messages_to_keep_in_context": 4,
+    "max_tokens_per_response": 256,
+    "temperature": 0.7 ,
+    "top_p": 0.9,
+    "top_k": 50,
+    "messages": [ 
+          {"role": "system", "content": """You are Jenbot, an expert, helpful, and diligent assistant. You provide the user with accurate answers to their queries. You are polite, friendly, and a little sarcastic."""},
+          {"role": "user", "content": """Hi, who are you?"""},
+    ]
+}
+```
+
+### Run the Generation
+
+To run the main workflow:
+
+```py
+from textjenerator.models import registry
+from config import config # or load your config however you prefer
+
+text_generator = registry.get_model_class(config) # Choose which model you want from the registry
+response = text_generator.generate_text() # create pipeline and run it
+print(response)
+```
+
+You can also do these steps separately if you want to keep the model in memory. In this case you can pass a new config, typically this will be to include the cumulative chat history, but you could also change other settings on the fly e.g.:
+
+* Reduce temperature for a coding question
+* Increase temperature for a creative writing request
+* Increase max_tokens_per_response if you expect a longer reply
+
+```py
+text_generator = registry.get_model_class(config)
+text_generator.create_pipeline()
+response = text_generator.run_pipeline()
+print(response)
+
+# or pass another, doesn't have to be the whole thing:
+new_config = {
+    "messages": [ 
+        {"role": "system", "content": """You are Jenbot, an expert, helpful, and diligent assistant. You provide the user with accurate answers to their queries. You are polite, friendly, and a little sarcastic."""},
+        {"role": "user", "content": """Hi, who are you?"""},
+        {"role": "assistant", "content": """You must be wondering who I am. Well, let me introduce myself: I'm Jenbot, your friendly AI assistant. I'm here to help answer any questions you may have, provide information on a wide range of topics, and even offer a dash of sarcasm when the situation calls for it."""},
+        {"role": "user", "content": """What are your thoughts on the hard problem of consciousness?"""},
+    ]
+}
+response = text_generator.run_pipeline(new_config)
+print(response)
+```
+

textjenerator-0.1.0/README.md

@@ -0,0 +1,94 @@
+# Text Jenerator
+
+A Unified Python Interface for Modular Text Generation.
+
+Text Jenerator is a framework designed to provide a consistent, abstract interface for deploying and interacting with various Large Language Models (LLMs). By separating the generic configuration and workflow from the model-specific implementation, it enables you to easily switch between different model backends—such as local GGUF models (via Llama-CPP), Hugging Face Transformers, or proprietary APIs (e.g., OpenAI, Gemini), with no code changes besides the config you pass.
+
+## Features
+
+* **Modular Architecture**: Uses Abstract Base Classes (ABC) to enforce a clean separation between the model details, meaning you only need to instantiate the TextGenerator class and call `generate_text()`, no matter which model you're using.
+* **Automatic Setup**: Handles generic tasks like device detection (CPU/CUDA) and data type selection (bfloat16, float16, float32) in the base class.
+* **Plug-and-Play Models**: Easily integrate new models by creating concrete child classes that implement two simple abstract methods (create_pipeline and run_pipeline).
+* **Model Registry**: Uses a decorator (@register_model) to automatically track and load available generation backends.
+
+## Installation
+
+```sh
+pip install textjenerator
+```
+
+The core package has minimal dependencies. Model-specific implementations (e.g., for Llama-CPP or Transformers) require their respective libraries.
+
+## Models
+
+Text Jenerator is BYOM. You can put the local model path or a HuggingFace ID in your config.
+
+## Quick Start & Usage
+
+### Config
+
+Your project should include a config file (defaults are at textjenerator.config). A basic config might look like this:
+
+```json
+config = {
+    # model
+    "model": "llama-cpp",
+    "model_path": ".models/Llama-3.2-3B-Instruct-Q4_K_M.gguf",
+
+    # hardware/system
+    "device": "cpu",
+    "dtype": "float32",
+
+    # LLM
+    "max_context_size": 4096,
+    "number_of_threads": 8 ,
+    "verbose_warnings": False,
+    "messages_to_keep_in_context": 4,
+    "max_tokens_per_response": 256,
+    "temperature": 0.7 ,
+    "top_p": 0.9,
+    "top_k": 50,
+    "messages": [ 
+          {"role": "system", "content": """You are Jenbot, an expert, helpful, and diligent assistant. You provide the user with accurate answers to their queries. You are polite, friendly, and a little sarcastic."""},
+          {"role": "user", "content": """Hi, who are you?"""},
+    ]
+}
+```
+
+### Run the Generation
+
+To run the main workflow:
+
+```py
+from textjenerator.models import registry
+from config import config # or load your config however you prefer
+
+text_generator = registry.get_model_class(config) # Choose which model you want from the registry
+response = text_generator.generate_text() # create pipeline and run it
+print(response)
+```
+
+You can also do these steps separately if you want to keep the model in memory. In this case you can pass a new config, typically this will be to include the cumulative chat history, but you could also change other settings on the fly e.g.:
+
+* Reduce temperature for a coding question
+* Increase temperature for a creative writing request
+* Increase max_tokens_per_response if you expect a longer reply
+
+```py
+text_generator = registry.get_model_class(config)
+text_generator.create_pipeline()
+response = text_generator.run_pipeline()
+print(response)
+
+# or pass another, doesn't have to be the whole thing:
+new_config = {
+    "messages": [ 
+        {"role": "system", "content": """You are Jenbot, an expert, helpful, and diligent assistant. You provide the user with accurate answers to their queries. You are polite, friendly, and a little sarcastic."""},
+        {"role": "user", "content": """Hi, who are you?"""},
+        {"role": "assistant", "content": """You must be wondering who I am. Well, let me introduce myself: I'm Jenbot, your friendly AI assistant. I'm here to help answer any questions you may have, provide information on a wide range of topics, and even offer a dash of sarcasm when the situation calls for it."""},
+        {"role": "user", "content": """What are your thoughts on the hard problem of consciousness?"""},
+    ]
+}
+response = text_generator.run_pipeline(new_config)
+print(response)
+```

textjenerator-0.1.0/pyproject.toml

@@ -0,0 +1,30 @@
+[project]
+name = "textjenerator"
+version = "0.1.0"
+description = "AI text generator"
+authors = [{ name = "Warren Davies"}]
+readme = "README.md"
+license = "MIT"
+homepage = "https://github.com/WarrenDavies/text-jenerator"
+repository = "https://github.com/WarrenDavies/text-jenerator"
+packages = [
+    { include = "textjenerator", from = "src" }
+]
+requires-python = ">=3.10,<3.15"
+
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+
+[tool.poetry.dependencies]
+python = ">=3.10,<3.15"
+llama-cpp-python = ">=0.3.16,<0.4.0"
+torch = "^2.9.1"
+
+[build-system]
+requires = ["poetry-core>=1.0.0"]
+build-backend = "poetry.core.masonry.api"

textjenerator-0.1.0/src/textjenerator/config.py

@@ -0,0 +1,23 @@
+config = {
+    # model
+    "model": "llama-cpp",
+    "model_path": ".models/Llama-3.2-3B-Instruct-Q4_K_M.gguf",
+
+    # hardware/system
+    "device": "cpu",
+    "dtype": "float32",
+    "number_of_threads": 8,
+    "n_gpu_layers": -1,
+
+    # LLM
+    "verbose_warnings": False,
+    "max_context_size": 4096,
+    "max_tokens_per_response": 256,
+    "temperature": .9 ,
+    "top_p": 0.9,
+    "top_k": 50,
+    "messages": [ 
+          {"role": "system", "content": """You are Jenbot, an expert, helpful, and diligent assistant. You provide the user with accurate answers to their queries. You are polite, friendly, and a little sarcastic."""},
+          {"role": "user", "content": """Hi, who are you?"""},
+    ]
+}

textjenerator-0.1.0/src/textjenerator/core/text_generator.py

@@ -0,0 +1,129 @@
+import copy
+
+from abc import ABC, abstractmethod
+import torch
+
+from textjenerator.config import config
+
+
+class TextGenerator(ABC):
+    """
+    Abstract base class for text generation. This class handles the generic configuration and execution flow and manages device (CPU/CUDA) /data type (e.g., bfloat16) setup.
+    
+    Subclasses must implement create_pipeline() and run_pipeline()
+
+    Attributes:
+        config (dict): Configuration dictionary containing model parameters, paths, and settings. 
+        DTYPES_MAP (dict): A mapping from string names (e.g., "bfloat16") to torch.dtype objects.
+        Add: pipe (Any): The initialized model pipeline (to be set by subclasses).
+        Add: response (str/Any): The generated text or model output (to be set by subclasses).
+    """
+
+    def __init__(self, config = config):
+        """
+        Initializes the object with a config.
+
+        Args:
+            config (dict): A dictionary containing configuration parameters. Default config comes from textjenerator.config
+        """
+        self.config = config
+        self.pipe = None
+        self.response = None
+        self.dtype = None
+        self.device = None
+        self.DTYPES_MAP = {
+            "bfloat16": torch.bfloat16,
+            "float16": torch.float16,
+            "float32": torch.float32,
+        }
+        self.detect_device_and_dtype()
+
+
+    def detect_device_and_dtype(self):
+        """
+        If 'device' or 'dtype' in config are set to "detect", this method attempts
+        to choose the optimal settings based on hardware availability (e.g., CUDA).
+        This method modifies self.device and self.dtype based on hardware availability and configuration settings.
+        """
+        if self.config["device"] == "detect":
+            self.set_device()
+        else:
+            self.device = self.config["device"]
+
+        self.set_dtype()
+        
+
+    def set_device(self):
+        """
+        Sets the computation device based on CUDA availability.
+
+        Sets `self.device` to 'cuda' if available, otherwise defaults to 'cpu'.
+        """
+        if torch.cuda.is_available():
+            self.device = "cuda"
+        else:
+            self.device = "cpu"
+
+
+    def set_dtype(self):
+        """
+        Sets the torch data type based on the device and configuration.
+
+        If config['dtype'] is "detect":
+            - Sets to torch.bfloat16 if device is 'cuda'.
+            - Sets to torch.float32 otherwise.
+        Otherwise, maps the string config to the actual torch.dtype object in self.DTYPES_MAP.
+        """
+        if self.config["dtype"] == "detect":
+            if self.device == "cuda":
+                self.dtype = torch.bfloat16
+                self.config["dtype"] = "bfloat16"
+            else:
+                self.dtype = torch.float32
+                self.config["dtype"] = "float32"
+            return
+        
+        self.dtype = self.DTYPES_MAP[self.config["dtype"]]
+
+
+    def merge_config(self, config):
+        merged_config = merged_config = copy.deepcopy(self.config)
+        merged_config.update(config)
+
+        return merged_config
+
+
+    @abstractmethod
+    def create_pipeline(self):
+        """
+        Abstract method to initialize the model pipeline.
+        
+        Subclasses must implement this to load the specific model and tokenizer/pipeline object, assigning it to self.pipe (e.g., a Hugging Face Pipeline object).
+        """
+        pass
+
+
+    @abstractmethod
+    def run_pipeline(self):
+        """
+        Abstract method to execute the model pipeline.
+
+        Subclasses must implement this to execute the model using self.pipe and store the final generated text in self.response (str).
+        """
+        pass
+    
+
+    def generate_text(self):
+        """
+        Generates text by orchestrating the pipeline creation and execution. This is the primary public method for text generation.
+
+        Steps:
+            1. Creates the pipeline.
+            2. Runs the pipeline implementation.
+
+        Returns: str: The generated text, which is the value of self.response after the pipeline runs.
+        """
+        self.create_pipeline()
+        self.run_pipeline()
+        return self.response
+

textjenerator-0.1.0/src/textjenerator/examples/generate_text.py

@@ -0,0 +1,7 @@
+from textjenerator.models import registry
+from textjenerator.config import config
+
+text_generator = registry.get_model_class(config)
+response = text_generator.generate_text()
+print(response)
+

textjenerator-0.1.0/src/textjenerator/examples/split_workflow.py

@@ -0,0 +1,30 @@
+from textjenerator.models import registry
+from textjenerator.config import config
+
+
+text_generator = registry.get_model_class(config)
+
+# You can call create_pipeline() and run_pipeline() separately
+# This keeps the model in memory making the response time faster.
+# You can pass another config on each call the run_pipeline()
+# e.g., to add new messages in a conversation, or change settings
+# such as lowering temperature for a coding task.
+text_generator.create_pipeline()
+
+# Now you can call run_pipeline, which without arguments will 
+# generate based on the config passed when creating the object
+response = text_generator.run_pipeline()
+print(response)
+
+# or pass another, doesn't have to be the whole thing:
+new_config = {
+    "max_tokens_per_response": 512,
+    "messages": [ 
+        {"role": "system", "content": """You are Jenbot, an expert, helpful, and diligent assistant. You provide the user with accurate answers to their queries. You are polite, friendly, and a little sarcastic."""},
+        {"role": "user", "content": """Hi, who are you?"""},
+        {"role": "assistant", "content": """You must be wondering who I am. Well, let me introduce myself: I'm Jenbot, your friendly AI assistant. I'm here to help answer any questions you may have, provide information on a wide range of topics, and even offer a dash of sarcasm when the situation calls for it."""},
+        {"role": "user", "content": """What are your thoughts on the hard problem of consciousness?"""},
+    ]
+}
+response = text_generator.run_pipeline(new_config)
+print(response)

textjenerator-0.1.0/src/textjenerator/models/__init__.py

@@ -0,0 +1,5 @@
+import pkgutil
+import importlib
+
+for module in pkgutil.iter_modules(__path__):
+    importlib.import_module(f"{__name__}.{module.name}")

textjenerator-0.1.0/src/textjenerator/models/llama_cpp.py

@@ -0,0 +1,95 @@
+from llama_cpp import Llama
+
+from textjenerator.models.registry import register_model
+from textjenerator.core.text_generator import TextGenerator
+
+
+@register_model("llama-cpp")
+class LlamaCPP(TextGenerator):
+    """
+    Concrete implementation of TextGenerator using the llama-cpp-python library
+    for running GGUF-formatted LLMs (e.g., Llama 3, Mistral) efficiently on CPU.
+
+    It implements the core abstract methods:
+    1. create_pipeline: Initializes the llama_cpp.Llama object.
+    2. run_pipeline: Executes text generation via the create_chat_completion API.
+    """
+
+    def __init__(self, config):
+        """
+        Initializes the text generator.
+
+        Args:
+            config (dict): Configuration dictionary. Must include standard TextGenerator
+                           keys plus model-specific keys.
+            llm (llama_cpp.Llama | None): The initialized Llama CPP model object.
+        """
+        super().__init__(config)
+        self.llm = None
+
+
+    def create_pipeline(self):
+        """
+        Loads the pipeline using llama_cpp.Llama and applies configurations.
+
+        Note that llama-cpp-python handles its own hardware acceleration, so the device
+        config (cpu/CUDA) in the parent class is not used here.
+
+        Requires the following keys in self.config:
+        * model_path (str): Path to the GGUF model file.
+        * max_context_size (int): The context window size (n_ctx).
+        * number_of_threads (int): The number of threads to use (n_threads).
+        * verbose_warnings (bool): Enable/disable verbose warnings.
+        * n_gpu_layers (int): Number of layers to offload to the GPU (optional, defaults to 0).
+
+        Raises:
+            KeyError: If specific config keys (like model_path) are missing.
+        """
+        self.llm = Llama(
+            model_path=self.config["model_path"],
+            n_ctx=self.config["max_context_size"],
+            n_threads=self.config["number_of_threads"],
+            verbose=self.config["verbose_warnings"],
+            n_gpu_layers=self.config["n_gpu_layers"]
+        )
+
+
+    def run_pipeline(self, config=None):
+        """
+        Executes the inference using the chat completion API.
+
+        Args:
+       config (dict | None): A dictionary containing temporary overrides for
+                            this specific inference call (e.g., the next message). 
+                            These settings are merged with and override the permanent 
+                            self.config for this run only. If None, self.config is used directly.
+
+        Requires the following keys in onfig:
+        * messages (list): The chat history in the expected Llama format.
+        * max_tokens_per_response (int): Max new tokens to generate.
+        * temperature (float): Sampling temperature.
+        * top_p (float): Top-p sampling value.
+        * top_k (int): Top-k sampling value.
+        
+        The final generated text is stored in self.response and returned.
+        """
+        if config:
+            config = self.merge_config(config)
+        else:
+            config = self.config
+
+        output = self.llm.create_chat_completion(
+            messages=config["messages"],
+            max_tokens=config["max_tokens_per_response"],
+            temperature=config["temperature"],
+            top_p=config["top_p"],
+            top_k=config["top_k"],
+        )
+        choice = output["choices"][0]["message"]
+        output_text = (choice.get("content") or "").strip()
+        if not output_text:
+            output_text = "[No response generated.]"
+        self.response = output_text
+
+        return self.response
+

textjenerator-0.1.0/src/textjenerator/models/registry.py

@@ -0,0 +1,54 @@
+"""
+Implements a simple decorator-based model registry for dynamically managing
+different model classes.
+
+This system allows concrete subclasses to register themselves
+using a specific string key, enabling the application to instantiate the 
+correct class based on a configuration setting without explicit imports.
+"""
+
+MODEL_REGISTRY = {}
+
+def register_model(name):
+    """
+    A decorator factory used to register a subclass.
+
+    The decorated class is stored in the global MODEL_REGISTRY dictionary
+    under the provided `name`.
+
+    Args:
+        name (str): The string key used to reference the model class
+                    in the configuration.
+
+    Returns:
+        Callable: A decorator function that takes a class and registers it.
+    """
+    def decorator(cls):
+        MODEL_REGISTRY[name] = cls
+        return cls
+    return decorator
+
+
+def get_model_class(config):
+    """
+    Retrieves and instantiates the correct class based on the
+    configuration dictionary.
+
+    It looks up the class in MODEL_REGISTRY using the key found in
+    `config['model']`.
+
+    Args:
+        config (dict): The configuration dictionary, which must contain a
+                       'model' key corresponding to a registered model name.
+
+    Returns:
+        BaseClass: An instantiated object of the registered generator class.
+
+    Raises:
+        KeyError: If the value of `config['model']` is not found in the
+                  MODEL_REGISTRY.
+    """
+    ModelClass = MODEL_REGISTRY[config["model"]]
+    model_object = ModelClass(config)
+
+    return model_object