minions-py 0.2.0__py3-none-any.whl

minions/__init__.py

@@ -0,0 +1,64 @@
+'''
+    ******************************************************************************************
+      Assembly:                minions
+      Filename:                __init__.py
+      Author:                  Terry D. Eppler
+      Created:                 09-02-2026
+
+      Last Modified By:        Terry D. Eppler
+      Last Modified On:        09-06-2026
+    ******************************************************************************************
+    <copyright file="__init__.py" company="Terry D. Eppler">
+
+         __init__.py
+         Copyright © 2026 Terry D. Eppler
+
+     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 NON-INFRINGEMENT. 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.
+
+     You can contact me at: terryeppler@gmail.com or eppler.terry@epa.gov
+
+    </copyright>
+    <summary>
+        Public package utilities for provider-specific Minions.
+    </summary>
+    ******************************************************************************************
+'''
+from __future__ import annotations
+
+
+def throw_if( name: str, value: object ) -> None:
+    """Validate a required value.
+
+    Purpose:
+        Raises a consistent error when a required value is empty.
+
+    Args:
+        name (str): Argument name included in the error.
+        value (object): Value to validate.
+
+    Returns:
+        None: Validation succeeds without returning a value.
+    """
+    if not value:
+        raise ValueError( f'Argument "{name}" cannot be empty!' )
+
+
+__version__ = '0.2.0'
+
+__all__: list[ str ] = [ 'throw_if' ]

minions/claude.py

@@ -0,0 +1,286 @@
+'''
+    ******************************************************************************************
+      Assembly:                minions
+      Filename:                claude.py
+      Author:                  Terry D. Eppler
+      Created:                 09-05-2026
+
+      Last Modified By:        Terry D. Eppler
+      Last Modified On:        09-06-2026
+    ******************************************************************************************
+    <copyright file="claude.py" company="Terry D. Eppler">
+
+         claude.py
+         Copyright © 2026 Terry D. Eppler
+
+     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 NON-INFRINGEMENT. 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.
+
+     You can contact me at: terryeppler@gmail.com or eppler.terry@epa.gov
+
+    </copyright>
+    <summary>
+        Anthropic Claude Minion implementations.
+    </summary>
+    ******************************************************************************************
+'''
+from __future__ import annotations
+
+from collections.abc import Sequence
+import asyncio
+import os
+
+from anthropic import Anthropic, AsyncAnthropic, beta_async_tool
+from anthropic.lib.tools import (
+    BetaAsyncFunctionTool,
+    BetaAsyncStreamingToolRunner,
+    BetaFunctionTool,
+)
+from anthropic.types.beta import (
+    BetaCodeExecutionTool20260521Param,
+    BetaMessage,
+    BetaToolUnionParam,
+    BetaWebFetchTool20260318Param,
+    BetaWebSearchTool20260318Param,
+)
+
+from . import throw_if
+
+
+ClaudeTool = BetaFunctionTool | BetaToolUnionParam
+ClaudeAsyncTool = BetaAsyncFunctionTool | BetaToolUnionParam
+
+
+class Minion:
+    """Claude workflow agent backed by Anthropic's native tool runner."""
+
+    minion_name: str = 'Claude Minion'
+
+    def __init__( self, model: str, instructions: str,
+            tools: Sequence[ ClaudeTool ] | None=None, max_turns: int=10,
+            max_tokens: int=4096, api_key: str | None=None,
+            name: str | None=None ) -> None:
+        """Initialize a Claude Minion.
+
+        Args:
+            model (str): Claude model identifier.
+            instructions (str): System instructions for the agent.
+            tools (Sequence[ClaudeTool] | None): Optional Anthropic local or server tools.
+            max_turns (int): Maximum model iterations per execution.
+            max_tokens (int): Maximum output tokens per model iteration.
+            api_key (str | None): Optional Anthropic API key override.
+            name (str | None): Optional name overriding the implementation default.
+
+        Returns:
+            None: Configuration and native clients are stored.
+        """
+        throw_if( 'model', model )
+        throw_if( 'instructions', instructions )
+        if max_turns < 1:
+            raise ValueError( 'Argument "max_turns" must be at least 1!' )
+        if max_tokens < 1:
+            raise ValueError( 'Argument "max_tokens" must be at least 1!' )
+        self.name = name or self.minion_name
+        throw_if( 'name', self.name )
+        self.model = model
+        self.instructions = instructions
+        self.tools = list( tools or [ ] )
+        self.max_turns = max_turns
+        self.max_tokens = max_tokens
+        self.api_key = api_key or os.getenv( 'ANTHROPIC_API_KEY' )
+        throw_if( 'api_key', self.api_key )
+        self.async_tools: list[ ClaudeAsyncTool ] = [
+            self.create_async_tool( tool ) if isinstance( tool, BetaFunctionTool ) else tool
+            for tool in self.tools
+        ]
+        self.client = Anthropic( api_key=self.api_key )
+        self.async_client = AsyncAnthropic( api_key=self.api_key )
+        self.result: BetaMessage | BetaAsyncStreamingToolRunner[ object ] | None = None
+
+
+    def create_async_tool( self, tool: BetaFunctionTool ) -> BetaAsyncFunctionTool:
+        """Create an async adapter without changing the provider schema.
+
+        Args:
+            tool (BetaFunctionTool): Synchronous Anthropic beta tool.
+
+        Returns:
+            BetaAsyncFunctionTool: Schema-identical asynchronous tool.
+        """
+        async def invoke( **arguments: object ) -> object:
+            return await asyncio.to_thread( tool.func, **arguments )
+        
+        invoke.__name__ = tool.name
+        invoke.__doc__ = tool.description
+        return beta_async_tool( invoke, name=tool.name, description=tool.description,
+            input_schema=tool.input_schema, )
+
+
+    def run( self, prompt: str ) -> BetaMessage:
+        """Execute the complete Claude workflow synchronously.
+
+        Args:
+            prompt (str): User input for the workflow.
+
+        Returns:
+            BetaMessage: Final provider-native message.
+        """
+        throw_if( 'prompt', prompt )
+        runner = self.client.beta.messages.tool_runner( model=self.model,
+            max_tokens=self.max_tokens, max_iterations=self.max_turns, system=self.instructions,
+            tools=self.tools, messages=[ { 'role': 'user', 'content': prompt } ], )
+        result = runner.until_done( )
+        self.result = result
+        return self.result
+
+
+    async def run_async( self, prompt: str ) -> BetaMessage:
+        """Execute the complete Claude workflow asynchronously.
+
+        Args:
+            prompt (str): User input for the workflow.
+
+        Returns:
+            BetaMessage: Final provider-native message.
+        """
+        throw_if( 'prompt', prompt )
+        runner = self.async_client.beta.messages.tool_runner(
+            model=self.model,
+            max_tokens=self.max_tokens,
+            max_iterations=self.max_turns,
+            system=self.instructions,
+            tools=self.async_tools,
+            messages=[ { 'role': 'user', 'content': prompt } ],
+        )
+        result = await runner.until_done( )
+        self.result = result
+        return result
+
+
+    def stream( self, prompt: str ) -> BetaAsyncStreamingToolRunner[ object ]:
+        """Start Anthropic's complete async streaming tool runner.
+
+        Args:
+            prompt (str): User input for the workflow.
+
+        Returns:
+            BetaAsyncStreamingToolRunner[object]: Native runner that streams and executes tools.
+        """
+        throw_if( 'prompt', prompt )
+        runner = self.async_client.beta.messages.tool_runner(
+            model=self.model,
+            max_tokens=self.max_tokens,
+            max_iterations=self.max_turns,
+            system=self.instructions,
+            tools=self.async_tools,
+            messages=[ { 'role': 'user', 'content': prompt } ],
+            stream=True,
+        )
+        self.result = runner
+        return runner
+
+
+class DataMinion( Minion ):
+    """Claude Minion specialized for data workflows."""
+
+    minion_name: str = 'Data Minion'
+
+
+class GovernanceMinion( Minion ):
+    """Claude Minion specialized for governance workflows."""
+
+    minion_name: str = 'Governance Minion'
+
+
+class ResearchMinion( Minion ):
+    """Claude Minion specialized for research workflows."""
+
+    minion_name: str = 'Research Minion'
+
+
+class CodingMinion( Minion ):
+    """Claude Minion specialized for software workflows."""
+
+    minion_name: str = 'Coding Minion'
+
+
+class WritingMinion( Minion ):
+    """Claude Minion specialized for writing workflows."""
+
+    minion_name: str = 'Writing Minion'
+
+
+class PlanningMinion( Minion ):
+    """Claude Minion specialized for planning workflows."""
+
+    minion_name: str = 'Planning Minion'
+
+
+class ComplianceMinion( Minion ):
+    """Claude Minion specialized for compliance, legal, and budget workflows."""
+
+    minion_name: str = 'Compliance Minion'
+
+
+class BusinessMinion( Minion ):
+    """Claude Minion specialized for business, finance, and marketing workflows."""
+
+    minion_name: str = 'Business Minion'
+
+
+class ImageGenerationMinion( Minion ):
+    """Claude Minion specialized for image-generation workflows."""
+
+    minion_name: str = 'Image Generation Minion'
+
+
+class ImageAnalysisMinion( Minion ):
+    """Claude Minion specialized for image-analysis workflows."""
+
+    minion_name: str = 'Image Analysis Minion'
+
+
+class ImageEditingMinion( Minion ):
+    """Claude Minion specialized for image-editing workflows."""
+
+    minion_name: str = 'Image Editing Minion'
+
+
+class TranslationMinion( Minion ):
+    """Claude Minion specialized for translation workflows."""
+
+    minion_name: str = 'Translation Minion'
+
+
+class TranscriptionMinion( Minion ):
+    """Claude Minion specialized for transcription workflows."""
+
+    minion_name: str = 'Transcription Minion'
+
+
+class SpeechMinion( Minion ):
+    """Claude Minion specialized for speech workflows."""
+
+    minion_name: str = 'Speech Minion'
+
+__all__: list[ str ] = [ 'BetaCodeExecutionTool20260521Param',
+        'BetaWebFetchTool20260318Param', 'BetaWebSearchTool20260318Param', 'BusinessMinion',
+        'ClaudeAsyncTool', 'ClaudeTool', 'CodingMinion', 'ComplianceMinion', 'DataMinion',
+        'GovernanceMinion', 'ImageAnalysisMinion', 'ImageEditingMinion',
+        'ImageGenerationMinion', 'Minion', 'PlanningMinion', 'ResearchMinion', 'SpeechMinion',
+        'TranscriptionMinion', 'TranslationMinion', 'WritingMinion', ]

minions/config.py

@@ -0,0 +1,211 @@
+'''
+    ******************************************************************************************
+      Assembly:                minions
+      Filename:                config.py
+      Author:                  Terry D. Eppler
+      Created:                 09-03-2026
+
+      Last Modified By:        Terry D. Eppler
+      Last Modified On:        09-06-2026
+    ******************************************************************************************
+    <copyright file="config.py" company="Terry D. Eppler">
+
+         config.py
+         Copyright © 2026 Terry D. Eppler
+
+     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 NON-INFRINGEMENT. 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.
+
+     You can contact me at: terryeppler@gmail.com or eppler.terry@epa.gov
+
+    </copyright>
+    <summary>
+        Environment and model configuration for Minions.
+    </summary>
+    ******************************************************************************************
+'''
+
+import os
+from pathlib import Path
+
+# -------------- APP-LEVEL UTILITIES -------------
+
+def throw_if( name: str, value: object ) -> None:
+	"""Raise a ``ValueError`` when a required value is empty.
+
+	Purpose:
+		Provides a small, consistent guard for required arguments and configuration values. The
+		function treats falsy values as invalid and raises a ``ValueError`` containing the
+		caller-supplied argument or setting name.
+
+	Args:
+		name (str): Name of the argument or configuration value being validated.
+		value (object): Value to validate.
+
+	Raises:
+		ValueError: Raised when ``value`` is falsy.
+	"""
+	if not value:
+		raise ValueError( f'Argument "{name}" cannot be empty!' )
+
+def get_bool( name: str, default: bool = False ) -> bool:
+	"""Read a Boolean environment variable.
+
+	Purpose:
+		Converts environment-variable text into a deterministic Boolean value. Missing
+		variables return the caller-provided default. Values of ``1``, ``true``, ``yes``,
+		``y``, and ``on`` are treated as ``True``; all other defined values are treated as
+		``False``.
+
+	Args:
+		name (str): Environment variable name.
+		default (bool): Default value used when the environment variable is not defined.
+
+	Returns:
+		Parsed Boolean value, or the original default value when parsing fails.
+	"""
+	try:
+		throw_if( 'name', name )
+		value = os.getenv( name )
+		return default if value is None else value.strip( ).lower( ) in (
+				'1',
+				'true',
+				'yes',
+				'y',
+				'on'
+		)
+	except Exception:
+		return default
+
+def get_int( name: str, default: int ) -> int:
+	"""Read an integer environment variable.
+
+	Purpose:
+		Parses an optional environment variable as an integer while preserving a safe
+		default when the variable is missing, empty, or invalid. This keeps module import
+		safe even when deployment configuration is incomplete.
+
+	Args:
+		name (str): Environment variable name.
+		default (int): Default integer value used when parsing is not possible.
+
+	Returns:
+		Parsed integer value or the supplied default value.
+	"""
+	try:
+		throw_if( 'name', name )
+		value = os.getenv( name )
+		return default if value in (None, '') else int( str( value ).strip( ) )
+	except Exception:
+		return default
+
+def get_float( name: str, default: float ) -> float:
+	"""Read a floating-point environment variable.
+
+	Purpose:
+		Parses an optional environment variable as a float while preserving a safe default
+		when the variable is missing, empty, or invalid. This helper supports numeric
+		configuration without making module import dependent on perfect environment state.
+
+	Args:
+		name (str): Environment variable name.
+		default (float): Default floating-point value used when parsing is not possible.
+
+	Returns:
+		Parsed floating-point value or the supplied default value.
+	"""
+	try:
+		throw_if( 'name', name )
+		value = os.getenv( name )
+		return default if value in (None, '') else float( str( value ).strip( ) )
+	except Exception:
+		return default
+
+def get_path( name: str, default: Path ) -> Path:
+	"""Read a path environment variable.
+
+	Purpose:
+		Resolves optional filesystem configuration from the environment. Missing variables
+		return the resolved default path, and invalid values fall back to the resolved
+		default path rather than interrupting module import.
+
+	Args:
+		name (str): Environment variable name.
+		default (Path): Default path used when the environment variable is not defined.
+
+	Returns:
+		Resolved path value or the resolved default path.
+	"""
+	try:
+		throw_if( 'name', name )
+		throw_if( 'default', default )
+		value = os.getenv( name )
+		return Path( value ).resolve( ) if value else default.resolve( )
+	except Exception:
+		return default.resolve( )
+
+def get_text( name: str, default: str ) -> str:
+	"""Read a text environment variable.
+
+	Purpose:
+		Returns an environment variable as text while preserving the supplied default when
+		the variable is missing or empty. This keeps optional configuration centralized and
+		stable for callers that import the module early in application startup.
+
+	Args:
+		name (str): Environment variable name.
+		default (str): Default text value.
+
+	Returns:
+		Environment value or supplied default.
+	"""
+	try:
+		throw_if( 'name', name )
+		value = os.getenv( name )
+		return default if value in (None, '') else str( value )
+	except Exception:
+		return default
+
+# ------ CONSTANTS  -------------------
+
+BASE_DIR = Path( __file__ ).resolve( ).parent
+ROOT_DIR = Path( __file__ ).resolve( ).parent
+LOG_DIR: Path = get_path( 'LOG_DIR', ROOT_DIR / 'logging' )
+LOG_PATH: str = get_text( 'LOG_PATH', str( LOG_DIR / 'Exceptions.db' ) )
+LOG_FILE: str = get_text( 'LOG_FILE', 'Exceptions' )
+
+# ------ MODELS  -------------------
+
+GPT_MODELS = [ 'gpt-5.6-sol', 'gpt-5.6-luna', 'gpt-5-mini', 'gpt-5-nano', 'gpt-4.1',
+		'gpt-4.1-mini', ]
+
+GEMINI_MODELS = [ 'gemini-3.7-flash', 'gemini-3.6-flash', 'gemini-3.5-flash',
+		'gemini-3.5-flash-lite', 'gemini-3.1-pro-preview', 'gemini-3.1-flash-lite',
+		'gemini-3-flash-preview', 'gemini-2.5-pro', 'gemini-2.5-flash', 'gemini-2.5-flash-lite', ]
+
+GROK_MODELS = [ 'grok-4.6', 'grok-4.5', 'grok-4.3', 'grok-4.20-multi-agent',
+		'grok-4.20-multi-agent-latest', ]
+
+CLAUDE_MODELS = [ 'claude-fable-5', 'claude-opus-5', 'claude-opus-4-8', 'claude-opus-4-7',
+		'claude-opus-4-6', 'claude-sonnet-5', 'claude-sonnet-4-6', 'claude-sonnet-4-5-20250929',
+		'claude-haiku-4-5-20251001', ]
+
+MISTRAL_MODELS = [ 'mistral-medium-latest', 'mistral-large-latest',
+        'mistral-small-latest', 'codestral-latest',
+        'ministral-14b-latest', 'ministral-8b-latest',
+        'ministral-3b-latest', ]