tlnw-tools 0.1.0__tar.gz

tlnw_tools-0.1.0/PKG-INFO

@@ -0,0 +1,70 @@
+Metadata-Version: 2.4
+Name: tlnw-tools
+Version: 0.1.0
+Summary: A collection of tools for various tasks and functionalities in the Tellers Network ecosystem.
+Author-email: Tellers Network <admin@tlnw.uk>
+Project-URL: Homepage, https://github.com/tellersnetwork/tlnw-tools
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: PyYAML>=6.0
+
+# Tellers Network Tools CLI (`tlnw-tools`)
+
+`tlnw-tools` is a modular, dynamic command-line interface (CLI) to manage and run a collection of independent tools in the Tellers Network ecosystem. Each tool is developed as a separate package published to PyPI and registered in `tools.yml`. When invoked, the main CLI dynamically verifies, downloads (if missing), and executes the tool either in-process (by default) or as a subprocess.
+
+## Features
+- **Dynamic Tool Execution**: Run tools registered in `tools.yml` directly using `tlnw-tools <tool>`.
+- **Automatic Packaging Management**: Automatically downloads, installs, or updates tools dynamically via `pip` on invocation.
+- **Configurable Isolation**: Supports executing tools either via in-process module importing or subprocess delegation, configurable on a per-tool basis in `tools.yml`.
+- **Consistent CLI**: Standard common arguments like `--help` and `--debug`.
+
+## Installation
+You can install the main CLI via PyPI:
+```bash
+pip install tlnw-tools
+```
+
+## Configuration (`tools.yml`)
+The main CLI registry lies in `tools.yml` located in the root of the project (or can be customized):
+```yaml
+version: 0.1.0
+description: "A collection of tools for various tasks and functionalities in the Tellers Network ecosystem."
+tools:
+  - name: "generate-image"
+    package: "tlnw-generate-image"
+    execution_mode: "inprocess_import"
+    module: "tlnw_generate_image.cli"
+    entry_point: "main"
+    description: "Generate images and illustrations with OpenAI and Gemini models."
+```
+
+## Commands
+```bash
+# General help
+tlnw-tools --help
+
+# Running a registered tool (e.g., generate-image)
+tlnw-tools generate-image --help
+```
+
+---
+
+# Tool: `generate-image`
+
+`generate-image` is the first unified tool package. It integrates and harmonizes image generation capabilities for story folders and specific scenes across both OpenAI (DALL-E 2/3, `gpt-image-1.5`) and Google Imagen 4.
+
+### Usage
+```bash
+tlnw-tools generate-image <story_folders> [options]
+```
+
+### Options
+- `--model <model>`: Specify model to use. Defaults to `gpt-image-1.5`. Available models: `dall-e-3`, `gpt-image-1.5`, `imagen-4`, etc.
+- `--quality <quality>`: Normalize quality across OpenAI and Gemini. Choices: `low`, `medium`, `high`, `standard`, `hd`, `auto`.
+- `--landscape` / `--portrait`: Control dimensions. Defaults to square (1024x1024).
+- `--size`: Manually specify dimensions (e.g., `1024x1024`).
+- `--reference`: Supply reference images.
+- `--output-prefix`: Prepend a custom prefix to generated files.
+- `--skip-update`: Avoid updating the Jekyll/Hugo `index.md` frontmatter.

tlnw_tools-0.1.0/README.md

@@ -0,0 +1,58 @@
+# Tellers Network Tools CLI (`tlnw-tools`)
+
+`tlnw-tools` is a modular, dynamic command-line interface (CLI) to manage and run a collection of independent tools in the Tellers Network ecosystem. Each tool is developed as a separate package published to PyPI and registered in `tools.yml`. When invoked, the main CLI dynamically verifies, downloads (if missing), and executes the tool either in-process (by default) or as a subprocess.
+
+## Features
+- **Dynamic Tool Execution**: Run tools registered in `tools.yml` directly using `tlnw-tools <tool>`.
+- **Automatic Packaging Management**: Automatically downloads, installs, or updates tools dynamically via `pip` on invocation.
+- **Configurable Isolation**: Supports executing tools either via in-process module importing or subprocess delegation, configurable on a per-tool basis in `tools.yml`.
+- **Consistent CLI**: Standard common arguments like `--help` and `--debug`.
+
+## Installation
+You can install the main CLI via PyPI:
+```bash
+pip install tlnw-tools
+```
+
+## Configuration (`tools.yml`)
+The main CLI registry lies in `tools.yml` located in the root of the project (or can be customized):
+```yaml
+version: 0.1.0
+description: "A collection of tools for various tasks and functionalities in the Tellers Network ecosystem."
+tools:
+  - name: "generate-image"
+    package: "tlnw-generate-image"
+    execution_mode: "inprocess_import"
+    module: "tlnw_generate_image.cli"
+    entry_point: "main"
+    description: "Generate images and illustrations with OpenAI and Gemini models."
+```
+
+## Commands
+```bash
+# General help
+tlnw-tools --help
+
+# Running a registered tool (e.g., generate-image)
+tlnw-tools generate-image --help
+```
+
+---
+
+# Tool: `generate-image`
+
+`generate-image` is the first unified tool package. It integrates and harmonizes image generation capabilities for story folders and specific scenes across both OpenAI (DALL-E 2/3, `gpt-image-1.5`) and Google Imagen 4.
+
+### Usage
+```bash
+tlnw-tools generate-image <story_folders> [options]
+```
+
+### Options
+- `--model <model>`: Specify model to use. Defaults to `gpt-image-1.5`. Available models: `dall-e-3`, `gpt-image-1.5`, `imagen-4`, etc.
+- `--quality <quality>`: Normalize quality across OpenAI and Gemini. Choices: `low`, `medium`, `high`, `standard`, `hd`, `auto`.
+- `--landscape` / `--portrait`: Control dimensions. Defaults to square (1024x1024).
+- `--size`: Manually specify dimensions (e.g., `1024x1024`).
+- `--reference`: Supply reference images.
+- `--output-prefix`: Prepend a custom prefix to generated files.
+- `--skip-update`: Avoid updating the Jekyll/Hugo `index.md` frontmatter.

tlnw_tools-0.1.0/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["setuptools>=61.0.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "tlnw-tools"
+version = "0.1.0"
+description = "A collection of tools for various tasks and functionalities in the Tellers Network ecosystem."
+readme = "README.md"
+authors = [
+    { name = "Tellers Network", email = "admin@tlnw.uk" }
+]
+requires-python = ">=3.10"
+dependencies = [
+    "PyYAML>=6.0",
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+]
+
+[project.urls]
+Homepage = "https://github.com/tellersnetwork/tlnw-tools"
+
+[project.scripts]
+tlnw-tools = "tlnw_tools.cli:main"
+
+[tool.setuptools]
+packages = ["tlnw_tools"]
+
+[tool.setuptools.package-data]
+tlnw_tools = ["tools.yml"]

tlnw_tools-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

tlnw_tools-0.1.0/tests/test_loader.py

@@ -0,0 +1,71 @@
+import os
+import sys
+import io
+from unittest import mock
+
+try:
+    import pytest
+except ImportError:
+    class MockPytest:
+        class RaisesContext:
+            def __init__(self, expected_exception):
+                self.expected_exception = expected_exception
+                self.value = None
+            def __enter__(self):
+                return self
+            def __exit__(self, exc_type, exc_val, exc_tb):
+                if exc_type is None:
+                    raise AssertionError(f"Did not raise {self.expected_exception}")
+                if issubclass(exc_type, self.expected_exception):
+                    self.value = exc_val
+                    return True
+                return False
+        def raises(self, expected_exception):
+            return self.RaisesContext(expected_exception)
+    pytest = MockPytest()
+from tlnw_tools.cli import find_tools_config, load_tools_config, is_package_installed, main
+
+def test_find_tools_config():
+    config_path = find_tools_config()
+    assert config_path is not None
+    assert os.path.exists(config_path)
+    assert config_path.endswith("tools.yml")
+
+def test_load_tools_config():
+    config = load_tools_config()
+    assert isinstance(config, dict)
+    assert "tools" in config
+    assert isinstance(config["tools"], list)
+    
+    # Ensure our first tool is registered
+    generate_image_tool = next((t for t in config["tools"] if t["name"] == "generate-image"), None)
+    assert generate_image_tool is not None
+    assert generate_image_tool["package"] == "tlnw-generate-image"
+    assert generate_image_tool["execution_mode"] == "inprocess_import"
+
+def test_is_package_installed():
+    # 'yaml' should be installed as it's a dependency
+    assert is_package_installed("yaml") is True
+    # 'sys' is built-in
+    assert is_package_installed("sys") is True
+    # A random fake package name should not be installed
+    assert is_package_installed("non_existent_fake_package_xyz123") is False
+
+def test_cli_help_stdout():
+    with mock.patch('sys.stdout', new_callable=io.StringIO) as mock_stdout:
+        with mock.patch.object(sys, 'argv', ['tlnw-tools', '--help']):
+            with pytest.raises(SystemExit) as exc_info:
+                main()
+            assert exc_info.value.code == 0
+        captured = mock_stdout.getvalue()
+    assert "Usage: tlnw-tools" in captured
+    assert "generate-image" in captured
+
+def test_cli_invalid_tool():
+    with mock.patch('sys.stdout', new_callable=io.StringIO) as mock_stdout:
+        with mock.patch.object(sys, 'argv', ['tlnw-tools', 'non-existent-tool']):
+            with pytest.raises(SystemExit) as exc_info:
+                main()
+            assert exc_info.value.code == 1
+        captured = mock_stdout.getvalue()
+    assert "Error: Tool 'non-existent-tool' not registered" in captured

tlnw_tools-0.1.0/tlnw_tools/__init__.py

@@ -0,0 +1,2 @@
+# Tellers Network Tools CLI Package
+__version__ = "0.1.0"

tlnw_tools-0.1.0/tlnw_tools/cli.py

@@ -0,0 +1,228 @@
+import sys
+import os
+import yaml
+import logging
+import importlib
+import importlib.util
+import subprocess
+import shutil
+
+# Configure logging format
+logging.basicConfig(format="%(asctime)s [%(levelname)s] %(name)s: %(message)s")
+logger = logging.getLogger("tlnw-tools")
+
+def find_tools_config():
+    # 1. Check current working directory
+    cwd_path = os.path.join(os.getcwd(), "tools.yml")
+    if os.path.exists(cwd_path):
+        return cwd_path
+    
+    # 2. Check sibling to this module's parent (dev mode)
+    dev_path = os.path.join(os.path.dirname(os.path.dirname(os.path.abspath(__file__))), "tools.yml")
+    if os.path.exists(dev_path):
+        return dev_path
+    
+    # 3. Check inside the module directory itself (packaged mode)
+    pkg_path = os.path.join(os.path.dirname(os.path.abspath(__file__)), "tools.yml")
+    if os.path.exists(pkg_path):
+        return pkg_path
+    
+    return None
+
+def load_tools_config():
+    config_path = find_tools_config()
+    if not config_path:
+        logger.error("Configuration file 'tools.yml' not found in workspace or package.")
+        sys.exit(1)
+        
+    try:
+        with open(config_path, "r", encoding="utf-8") as f:
+            return yaml.safe_load(f)
+    except Exception as e:
+        logger.error(f"Failed to parse tools.yml: {e}")
+        sys.exit(1)
+
+def is_package_installed(module_name):
+    if not module_name:
+        return False
+    top_level = module_name.split('.')[0]
+    try:
+        spec = importlib.util.find_spec(top_level)
+        return spec is not None
+    except Exception:
+        return False
+
+def install_package(package_name):
+    logger.info(f"Package '{package_name}' not found. Installing dynamically from PyPI...")
+    try:
+        subprocess.check_call([sys.executable, "-m", "pip", "install", package_name])
+        logger.info(f"Successfully installed package '{package_name}'.")
+        return True
+    except subprocess.CalledProcessError as e:
+        logger.error(f"Failed to dynamically install package '{package_name}': {e}")
+        return False
+
+def run_inprocess(tool_info, tool_args):
+    module_name = tool_info.get("module")
+    entry_point_name = tool_info.get("entry_point", "main")
+    
+    if not module_name:
+        logger.error(f"Missing 'module' entry for tool '{tool_info.get('name')}' in tools.yml.")
+        sys.exit(1)
+        
+    # Check installation
+    if not is_package_installed(module_name):
+        package_name = tool_info.get("package")
+        if not package_name:
+            logger.error(f"Tool '{tool_info.get('name')}' is not installed, and no 'package' is specified in tools.yml to install it.")
+            sys.exit(1)
+        if not install_package(package_name):
+            sys.exit(1)
+            
+    # Dynamic import and execution
+    try:
+        # Clear module from sys.modules to ensure a fresh import after installation
+        if module_name in sys.modules:
+            del sys.modules[module_name]
+            
+        module = importlib.import_module(module_name)
+        entry_point = getattr(module, entry_point_name)
+    except Exception as e:
+        logger.error(f"Failed to load entry point '{entry_point_name}' from module '{module_name}': {e}")
+        sys.exit(1)
+        
+    # Replace sys.argv with our tool arguments
+    # argv[0] is typically the script or subcommand name
+    sys.argv = [tool_info.get("name")] + tool_args
+    
+    try:
+        return entry_point()
+    except SystemExit as se:
+        return se.code
+    except Exception as e:
+        logger.error(f"Error during tool execution: {e}")
+        return 1
+
+def run_subprocess(tool_info, tool_args):
+    tool_name = tool_info.get("name")
+    package_name = tool_info.get("package")
+    module_name = tool_info.get("module")
+    
+    # Check if executable / script is on path
+    executable_path = shutil.which(tool_name)
+    
+    if not executable_path:
+        # If not on path, verify if installed via python module, otherwise install
+        if not is_package_installed(module_name):
+            if not package_name:
+                logger.error(f"Tool '{tool_name}' executable not found on PATH, and no 'package' specified to install.")
+                sys.exit(1)
+            if not install_package(package_name):
+                sys.exit(1)
+        
+        # Try finding executable again after install
+        executable_path = shutil.which(tool_name)
+        if not executable_path:
+            # Fall back to running via python -m
+            if module_name:
+                logger.debug(f"Executable '{tool_name}' not on PATH. Falling back to executing via 'python -m {module_name}'.")
+                cmd = [sys.executable, "-m", module_name] + tool_args
+                try:
+                    res = subprocess.run(cmd)
+                    return res.returncode
+                except Exception as e:
+                    logger.error(f"Failed to execute module '{module_name}' via subprocess: {e}")
+                    sys.exit(1)
+            else:
+                logger.error(f"Executable '{tool_name}' not found on PATH, and no module fallback available.")
+                sys.exit(1)
+                
+    # If executable is found
+    logger.debug(f"Executing '{executable_path}' with args {tool_args} via subprocess.")
+    try:
+        res = subprocess.run([executable_path] + tool_args)
+        return res.returncode
+    except Exception as e:
+        logger.error(f"Failed to run executable '{executable_path}': {e}")
+        return 1
+
+def print_help(config):
+    print("Usage: tlnw-tools [--debug] <tool> [args...]")
+    print("\nCommon Options:")
+    print("  -h, --help    Show this help message and exit")
+    print("  --debug       Enable debug-level logging")
+    print("\nAvailable Tools:")
+    
+    tools = config.get("tools", [])
+    if not tools:
+        print("  (No tools registered)")
+        return
+        
+    for tool in tools:
+        name = tool.get("name", "unknown")
+        desc = tool.get("description", "No description available.")
+        print(f"  {name:<15} {desc}")
+    print()
+
+def main():
+    config = load_tools_config()
+    
+    # Parse CLI arguments manually to support generic tool arguments forwarding
+    args = sys.argv[1:]
+    
+    # Handle help at main level
+    if not args or "-h" in args or "--help" in args:
+        # If we have args but first arg is a tool, let the tool handle its own help
+        if args and args[0] in [t.get("name") for t in config.get("tools", [])]:
+            # This is help for a specific tool, let the tool handle it
+            pass
+        else:
+            print_help(config)
+            sys.exit(0)
+            
+    # Parse debug flag
+    debug_mode = False
+    if "--debug" in args:
+        debug_mode = True
+        logger.setLevel(logging.DEBUG)
+        logging.getLogger("").setLevel(logging.DEBUG)
+        logger.debug("Debug logging enabled for tlnw-tools CLI.")
+        # Remove --debug from args so it doesn't pollute subcommand matching
+        args.remove("--debug")
+        
+    if not args:
+        print_help(config)
+        sys.exit(1)
+        
+    tool_name = args[0]
+    tool_args = args[1:]
+    
+    # Re-append --debug if we had it, so the tool also gets it if it wants it
+    if debug_mode and "--debug" not in tool_args:
+        tool_args.append("--debug")
+        
+    # Find matching tool
+    matching_tool = None
+    for tool in config.get("tools", []):
+        if tool.get("name") == tool_name:
+            matching_tool = tool
+            break
+            
+    if not matching_tool:
+        print(f"Error: Tool '{tool_name}' not registered in tools.yml.")
+        print_help(config)
+        sys.exit(1)
+        
+    # Execute according to mode
+    mode = matching_tool.get("execution_mode", "inprocess_import")
+    logger.debug(f"Executing tool '{tool_name}' in '{mode}' mode.")
+    
+    if mode == "subprocess":
+        exit_code = run_subprocess(matching_tool, tool_args)
+    else:
+        exit_code = run_inprocess(matching_tool, tool_args)
+        
+    sys.exit(exit_code or 0)
+
+if __name__ == "__main__":
+    main()

tlnw_tools-0.1.0/tlnw_tools/tools.yml

@@ -0,0 +1,9 @@
+version: "0.1.0"
+description: "A collection of tools for various tasks and functionalities in the Tellers Network ecosystem."
+tools:
+  - name: "generate-image"
+    package: "tlnw-generate-image"
+    execution_mode: "inprocess_import"
+    module: "tlnw_generate_image.cli"
+    entry_point: "main"
+    description: "Generate images and illustrations with OpenAI and Gemini models."

tlnw_tools-0.1.0/tlnw_tools.egg-info/PKG-INFO

@@ -0,0 +1,70 @@
+Metadata-Version: 2.4
+Name: tlnw-tools
+Version: 0.1.0
+Summary: A collection of tools for various tasks and functionalities in the Tellers Network ecosystem.
+Author-email: Tellers Network <admin@tlnw.uk>
+Project-URL: Homepage, https://github.com/tellersnetwork/tlnw-tools
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: PyYAML>=6.0
+
+# Tellers Network Tools CLI (`tlnw-tools`)
+
+`tlnw-tools` is a modular, dynamic command-line interface (CLI) to manage and run a collection of independent tools in the Tellers Network ecosystem. Each tool is developed as a separate package published to PyPI and registered in `tools.yml`. When invoked, the main CLI dynamically verifies, downloads (if missing), and executes the tool either in-process (by default) or as a subprocess.
+
+## Features
+- **Dynamic Tool Execution**: Run tools registered in `tools.yml` directly using `tlnw-tools <tool>`.
+- **Automatic Packaging Management**: Automatically downloads, installs, or updates tools dynamically via `pip` on invocation.
+- **Configurable Isolation**: Supports executing tools either via in-process module importing or subprocess delegation, configurable on a per-tool basis in `tools.yml`.
+- **Consistent CLI**: Standard common arguments like `--help` and `--debug`.
+
+## Installation
+You can install the main CLI via PyPI:
+```bash
+pip install tlnw-tools
+```
+
+## Configuration (`tools.yml`)
+The main CLI registry lies in `tools.yml` located in the root of the project (or can be customized):
+```yaml
+version: 0.1.0
+description: "A collection of tools for various tasks and functionalities in the Tellers Network ecosystem."
+tools:
+  - name: "generate-image"
+    package: "tlnw-generate-image"
+    execution_mode: "inprocess_import"
+    module: "tlnw_generate_image.cli"
+    entry_point: "main"
+    description: "Generate images and illustrations with OpenAI and Gemini models."
+```
+
+## Commands
+```bash
+# General help
+tlnw-tools --help
+
+# Running a registered tool (e.g., generate-image)
+tlnw-tools generate-image --help
+```
+
+---
+
+# Tool: `generate-image`
+
+`generate-image` is the first unified tool package. It integrates and harmonizes image generation capabilities for story folders and specific scenes across both OpenAI (DALL-E 2/3, `gpt-image-1.5`) and Google Imagen 4.
+
+### Usage
+```bash
+tlnw-tools generate-image <story_folders> [options]
+```
+
+### Options
+- `--model <model>`: Specify model to use. Defaults to `gpt-image-1.5`. Available models: `dall-e-3`, `gpt-image-1.5`, `imagen-4`, etc.
+- `--quality <quality>`: Normalize quality across OpenAI and Gemini. Choices: `low`, `medium`, `high`, `standard`, `hd`, `auto`.
+- `--landscape` / `--portrait`: Control dimensions. Defaults to square (1024x1024).
+- `--size`: Manually specify dimensions (e.g., `1024x1024`).
+- `--reference`: Supply reference images.
+- `--output-prefix`: Prepend a custom prefix to generated files.
+- `--skip-update`: Avoid updating the Jekyll/Hugo `index.md` frontmatter.

tlnw_tools-0.1.0/tlnw_tools.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+README.md
+pyproject.toml
+tests/test_loader.py
+tlnw_tools/__init__.py
+tlnw_tools/cli.py
+tlnw_tools/tools.yml
+tlnw_tools.egg-info/PKG-INFO
+tlnw_tools.egg-info/SOURCES.txt
+tlnw_tools.egg-info/dependency_links.txt
+tlnw_tools.egg-info/entry_points.txt
+tlnw_tools.egg-info/requires.txt
+tlnw_tools.egg-info/top_level.txt

tlnw_tools-0.1.0/tlnw_tools.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

tlnw_tools-0.1.0/tlnw_tools.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+tlnw-tools = tlnw_tools.cli:main

tlnw_tools-0.1.0/tlnw_tools.egg-info/requires.txt

@@ -0,0 +1 @@
+PyYAML>=6.0

tlnw_tools-0.1.0/tlnw_tools.egg-info/top_level.txt

@@ -0,0 +1 @@
+tlnw_tools