org.slashlib.py.agent 0.1.0__py3-none-any.whl

org/slashlib/py/agent/__init__.py

@@ -0,0 +1,46 @@
+# -*- coding: utf-8 -*-
+# file src/org/slashlib/py/agent/__init__.py
+# @AI:
+# - INTEGRITY RULES:
+#   - STRICT PRESERVATION: Do not remove, move, or modify ANY existing lines of code or comments 
+#     unless they are the explicit target of the requested change. 
+#   - DEBUG MARKERS: Commented-out code (e.g., debug prints) MUST be kept exactly where they are.
+#   - WHITESPACE & STRUCTURE: Maintain all original empty lines and the existing file structure. 
+#     Structural integrity takes precedence over "clean code" or "elegance".
+#   - LEAD-IN/OUT: The very first and last lines (and all comments in between) are immutable anchors.
+# - MAINTENANCE:
+#   - Only update pydoc strings (args, returns, raises) if the function signature changes.
+#   - Do NOT delete existing examples or descriptions in pydoc.
+# - LANGUAGE: en-US for all comments and documentation.
+
+from src.org.slashlib.py.agent.agent import Agent
+from src.org.slashlib.py.agent.tool import tool
+from src.org.slashlib.py.agent.agent_response import AgentResponse
+from src.org.slashlib.py.agent.inference_bases import (
+    InferenceAdapter,
+    InferenceResult,
+    InferenceError,
+    InferenceConnectionError,
+    InferenceConfigError,
+    InferencePayloadError
+)
+from src.org.slashlib.py.agent.inference_complements_for_ollama import (
+    OllamaInferenceAdapter,
+    OllamaInferenceResult
+)
+
+__all__ = [
+    "Agent",
+    "tool",
+    "AgentResponse",
+    "InferenceAdapter",
+    "InferenceResult",
+    "InferenceError",
+    "InferenceConnectionError",
+    "InferenceConfigError",
+    "InferencePayloadError",
+    "OllamaInferenceAdapter",
+    "OllamaInferenceResult"
+]
+
+# end of file src/org/slashlib/py/agent/__init__.py

org/slashlib/py/agent/__main__.py

@@ -0,0 +1,91 @@
+# -*- coding: utf-8 -*-
+# file src/org/slashlib/py/agent/__main__.py
+# @AI:
+# - INTEGRITY RULES:
+#   - STRICT PRESERVATION: Do not remove, move, or modify ANY existing lines of code or comments 
+#     unless they are the explicit target of the requested change. 
+#   - DEBUG MARKERS: Commented-out code (e.g., debug prints) MUST be kept exactly where they are.
+#   - WHITESPACE & STRUCTURE: Maintain all original empty lines and the existing file structure. 
+#     Structural integrity takes precedence over "clean code" or "elegance".
+#   - LEAD-IN/OUT: The very first and last lines (and all comments in between) are immutable anchors.
+# - MAINTENANCE:
+#   - Only update pydoc strings (args, returns, raises) if the function signature changes.
+#   - Do NOT delete existing examples or descriptions in pydoc.
+# - LANGUAGE: en-US for all comments and documentation.
+#
+# pragma: no cover
+#
+"""
+Entry point for the org.slashlib.py.agent package.
+"""
+
+# Import python packages
+import argparse
+import logging
+import pathlib
+import sys
+from importlib import metadata
+
+# Compatibility layer for TOML (Python 3.11+ uses tomllib, older use tomli)
+if sys.version_info >= (3, 11):
+    import tomllib
+else:
+    try:
+        import tomli as tomllib
+    except ImportError:
+        tomllib = None
+
+# Import thirdparty packages
+import org.slashlib.py.configloader
+
+# setup logging
+org.slashlib.py.configloader.setup_logging()
+
+log = logging.getLogger(f"org.slashlib.py.agent.{pathlib.Path(__file__).stem}")
+
+def get_version() -> str:
+    """
+    Retrieve the version of the package from metadata or local pyproject.toml.
+    """
+    # 1. Try metadata (works if installed via pip)
+    try:
+        return metadata.version("org.slashlib.py.agent")
+    except metadata.PackageNotFoundError:
+        pass
+
+    # 2. Fallback: Parse pyproject.toml directly (works during development)
+    if tomllib is not None:
+        try:
+            # Search for pyproject.toml relative to this file's location
+            # Path: src/org/slashlib/py/agent/__main__.py -> root is 4 levels up
+            root_path = pathlib.Path(__file__).parents[5]
+            toml_path = root_path / "pyproject.toml"
+            
+            if toml_path.exists():
+                with open(toml_path, "rb") as f:
+                    data = tomllib.load(f)
+                    return data.get("project", {}).get("version", "unknown (local)")
+        except Exception:
+            pass
+
+    return "unknown"
+
+def start():
+    """
+    Bootstrap function to instantiate and run the bot.
+    """
+    parser = argparse.ArgumentParser(description="org.slashlib.py.agent CLI")
+    parser.add_argument("--version", action="store_true", help="Show the package version and exit")
+    
+    args, unknown = parser.parse_known_args()
+
+    if args.version:
+        print(f"org.slashlib.py.agent version {get_version()}")
+        sys.exit(0)
+    else:
+        parser.print_help()
+ 
+if __name__ == "__main__":
+    start()
+    
+# end of file src/org/slashlib/py/agent/__main__.py

org/slashlib/py/agent/agent.py

@@ -0,0 +1,334 @@
+# -*- coding: utf-8 -*-
+# file src/org/slashlib/py/agent/agent.py
+# @AI:
+# - INTEGRITY RULES:
+#   - STRICT PRESERVATION: Do not remove, move, or modify ANY existing lines of code or comments 
+#     unless they are the explicit target of the requested change. 
+#   - DEBUG MARKERS: Commented-out code (e.g., debug prints) MUST be kept exactly where they are.
+#   - WHITESPACE & STRUCTURE: Maintain all original empty lines and the existing file structure. 
+#     Structural integrity takes precedence over "clean code" or "elegance".
+#   - LEAD-IN/OUT: The very first and last lines (and all comments in between) are immutable anchors.
+# - MAINTENANCE:
+#   - Only update pydoc strings (args, returns, raises) if the function signature changes.
+#   - Do NOT delete existing examples or descriptions in pydoc.
+# - LANGUAGE: en-US for all comments and documentation.
+#
+
+# Python imports
+import asyncio
+import logging
+import pathlib
+import typing
+
+# Third party imports
+import org.slashlib.py.configloader as config
+
+# Internal imports
+import src.org.slashlib.py.agent.tool as tool
+import src.org.slashlib.py.agent.agent_response as response
+import src.org.slashlib.py.agent.inference_bases as inference
+
+
+# Module-level instance registry to implement the Multiton pattern
+_instances: typing.Dict[str, "Agent"] = {}
+
+
+class Agent:
+    """
+    Base class for an AI Agent.
+    
+    This class orchestrates the interaction between an inference adapter and a set of tools.
+    """
+
+    def __new__(cls, identifier: str, tools: typing.List[tool.Tool], adapter: inference.InferenceAdapter, multi: bool = True):
+        """
+        Create a new instance or return an existing one based on the identifier.
+
+        Args:
+            identifier (str): A unique identifier for the agent instance.
+            tools (typing.List[tool.Tool]): A list of Tool objects the agent can use.
+            adapter (inference.InferenceAdapter): The adapter to use for inference.
+            multi (bool): Whether the agent can run multiple tasks simultaneously.
+
+        Returns:
+            Agent: The new or existing agent instance.
+        """
+        if identifier in _instances:
+            return _instances[identifier]
+        
+        instance = super(Agent, cls).__new__(cls)
+        _instances[identifier] = instance
+        return instance
+
+    def __init__(self, identifier: str, tools: typing.List[tool.Tool], adapter: inference.InferenceAdapter, multi: bool = True):
+        """
+        Initialize the Agent.
+
+        Args:
+            identifier (str): A unique identifier for the agent instance.
+            tools (typing.List[tool.Tool]): A list of Tool objects. Must not be empty.
+            adapter (inference.InferenceAdapter): The adapter providing the inference capabilities.
+            multi (bool): If False, the agent allows only one active task at a time. Defaults to True.
+
+        Raises:
+            ValueError: If tools or adapter is None.
+        """
+        # Skip initialization if already initialized (for __new__ multiton logic)
+        if hasattr(self, "_initialized") and self._initialized:
+            return
+
+        self.log = logging.getLogger(f"org.slashlib.py.agent.{pathlib.Path(__file__).stem}.{self.__class__.__name__}")
+        self._identifier = identifier
+        self._multi = multi
+
+        if not tools:
+            raise ValueError("The tools list must not be empty.")
+        
+        if not adapter:
+            raise ValueError("An InferenceAdapter is required.")
+
+        self._tools = tools
+        self._adapter = adapter
+        self._active_tasks: typing.Set[asyncio.Task] = set()
+        self._initialized = True
+        self.log.debug(f"Agent initialized with {len(self._tools)} tools and adapter {type(adapter).__name__} (multi={self._multi})")
+
+    def __del__(self):
+        """
+        Destructor called when the agent object is about to be destroyed.
+        Ensures all running tasks are cancelled.
+        """
+        # Note: During interpreter shutdown, globals/imports might be None.
+        try:
+            if hasattr(self, "_active_tasks") and self._active_tasks:
+                self.cancel()
+        except Exception:
+            # Destructors should not raise exceptions
+            pass
+
+    @property
+    def identifier(self) -> str:
+        """
+        Get the identifier of the agent.
+
+        Returns:
+            str: The agent's identifier.
+        """
+        return self._identifier
+
+    @property
+    def tools(self) -> typing.List[tool.Tool]:
+        """
+        Get the list of tools available to the agent.
+        
+        Returns:
+            List[tool.Tool]: The registered tools.
+        """
+        return self._tools
+
+    @property
+    def has_active_tasks(self) -> bool:
+        """
+        Check if the agent is currently processing any tasks.
+
+        Returns:
+            bool: True if there are running background tasks.
+        """
+        return len(self._active_tasks) > 0
+
+    def get_tool_schemas(self) -> typing.List[dict]:
+        """
+        Collects all JSON schemas from the registered tools.
+
+        Returns:
+            typing.List[dict]: A list of tool schemas for LLM consumption.
+        """
+        return [tool_obj.get_schema() for tool_obj in self._tools]
+
+    def _init_response_object(self, **kwargs) -> response.AgentResponse:
+        """
+        Initializes a new AgentResponse object and sets up the initial context.
+
+        Args:
+            **kwargs: Arguments containing 'user_prompt' and optional 'system_prompt'.
+
+        Returns:
+            response.AgentResponse: The initialized response object.
+        """
+        response_obj = response.AgentResponse()
+        
+        user_prompt = kwargs.get("user_prompt")
+        system_prompt = kwargs.get("system_prompt")
+        
+        if not user_prompt:
+            err = ValueError("A 'user_prompt' is required to run the agent.")
+            response_obj.append_error(err)
+            return response_obj
+
+        if system_prompt:
+            response_obj.append_context(role="system", content=system_prompt)
+            
+        response_obj.append_context(role="user", content=user_prompt)
+        return response_obj
+
+    async def _execute_tool(self, name: str, arguments: dict) -> typing.Any:
+        """
+        Internal helper to find and execute a tool by its name.
+
+        Args:
+            name (str): The name of the tool to execute.
+            arguments (dict): The arguments to pass to the tool.
+
+        Returns:
+            Any: The result of the tool execution.
+
+        Raises:
+            ValueError: If no tool with the given name is found.
+        """
+        for tool_obj in self._tools:
+            if tool_obj.name == name:
+                self.log.info(f"Agent {self.identifier} executing tool '{name}' with {arguments}")
+                return await tool_obj(**arguments)
+        
+        raise ValueError(f"Tool '{name}' not found in agent's toolbox.")
+
+    async def _run_tool_calls(self, response_obj: response.AgentResponse, tool_calls: typing.Optional[typing.List[dict]]) -> bool:
+        """
+        Processes tool calls if present.
+
+        Args:
+            response_obj (response.AgentResponse): The current response object to update.
+            tool_calls (Optional[List[dict]]): The list of tool calls from the LLM.
+
+        Returns:
+            bool: True if tool calls were processed, False otherwise.
+        """
+        if not tool_calls:
+            return False
+
+        self.log.info(f"Agent {self.identifier} received {len(tool_calls)} tool call(s).")
+        
+        for call in tool_calls:
+            tool_name = call.get("function", {}).get("name")
+            tool_args = call.get("function", {}).get("arguments")
+            
+            try:
+                result = await self._execute_tool(tool_name, tool_args)
+                response_obj.append_context(
+                    role="tool",
+                    content=result,
+                    name=tool_name
+                )
+            except Exception as tool_err:
+                self.log.error(f"Tool execution failed: {tool_err}")
+                response_obj.append_tool_error(tool_err)
+                response_obj.append_context(
+                    role="tool",
+                    content=f"Error: {str(tool_err)}",
+                    name=tool_name
+                )
+        return True
+
+    async def _run(self, **kwargs) -> response.AgentResponse:
+        """
+        Internal asynchronous task execution.
+        
+        Orchestrates the loop between the inference adapter and tool execution.
+
+        Args:
+            **kwargs: Arbitrary keyword arguments. 
+                      Supports 'user_prompt', 'system_prompt', 'model', 'timeout' and 'think'.
+
+        Returns:
+            response.AgentResponse: The result object containing the history and any errors.
+        """
+        response_obj = self._init_response_object(**kwargs)
+        
+        if response_obj.has_error:
+            return response_obj
+
+        try:
+            is_running = True
+            while is_running:
+                self.log.debug(f"Agent {self.identifier} initiating inference call...")
+                
+                # The adapter handles all provider-specific details and config resolution
+                inference_result = await self._adapter.chat(
+                    messages=response_obj.get_context(),
+                    tools=self.get_tool_schemas(),
+                    **kwargs
+                )
+
+                # Use the standardized to_dict() for AgentResponse
+                response_obj.append_context(**inference_result.to_dict())
+
+                if await self._run_tool_calls(response_obj, inference_result.tool_calls):
+                    continue
+
+                is_running = False
+                self.log.info(f"Agent {self.identifier} finished task.")
+                
+        except asyncio.CancelledError:
+            self.log.debug(f"Task for agent {self.identifier} was cancelled.")
+            raise
+        except inference.InferenceError as ie:
+            self.log.error(f"Inference failed for agent {self.identifier}: {ie}")
+            response_obj.append_error(ie)
+        except Exception as e:
+            self.log.error(f"Unexpected error in background task for agent {self.identifier}: {e}", exc_info=True)
+            response_obj.append_error(e)
+        finally:
+            current_task = asyncio.current_task()
+            if current_task in self._active_tasks:
+                self._active_tasks.remove(current_task)
+            
+            return response_obj
+
+    def run(self, **kwargs) -> asyncio.Task:
+        """
+        Starts the agent logic in a non-blocking background task.
+
+        Args:
+            **kwargs: Arbitrary keyword arguments passed to the internal _run method.
+
+        Returns:
+            asyncio.Task: The task object managing the background execution. 
+                          The result of this task will be an AgentResponse object.
+
+        Raises:
+            RuntimeError: If multi is False and a task is already running.
+        """
+        if not self._multi and self.has_active_tasks:
+            raise RuntimeError(f"Agent {self.identifier} is already running a task and multi-tasking is disabled.")
+
+        task = asyncio.create_task(self._run(**kwargs))
+        self._active_tasks.add(task)
+        return task
+
+    def cancel(self, task: typing.Optional[asyncio.Task] = None):
+        """
+        Cancels running tasks. 
+
+        Args:
+            task (Optional[asyncio.Task]): The specific task to cancel.
+        """
+        if task is not None:
+            if task in self._active_tasks:
+                task.cancel()
+                self.log.debug(f"Specific task cancelled for agent {self.identifier}.")
+            else:
+                self.log.warning(f"Task cancel requested but task not found in active tasks for agent {self.identifier}.")
+            return
+
+        if not self._active_tasks:
+            self.log.debug(f"No active tasks to cancel for agent {self.identifier}.")
+            return
+
+        self.log.debug(f"Cancelling all ({len(self._active_tasks)}) active tasks for agent {self.identifier}.")
+        for t in list(self._active_tasks):
+            t.cancel()
+
+
+__all__ = ["Agent"]
+
+# end of file src/org/slashlib/py/agent/agent.py

org/slashlib/py/agent/agent_response.py

@@ -0,0 +1,207 @@
+# -*- coding: utf-8 -*-
+# file src/org/slashlib/py/agent/agent_response.py
+# @AI:
+# - INTEGRITY RULES:
+#   - STRICT PRESERVATION: Do not remove, move, or modify ANY existing lines of code or comments 
+#     unless they are the explicit target of the requested change. 
+#   - DEBUG MARKERS: Commented-out code (e.g., debug prints) MUST be kept exactly where they are.
+#   - WHITESPACE & STRUCTURE: Maintain all original empty lines and the existing file structure. 
+#     Structural integrity takes precedence over "clean code" or "elegance".
+#   - LEAD-IN/OUT: The very first and last lines (and all comments in between) are immutable anchors.
+# - MAINTENANCE:
+#   - Only update pydoc strings (args, returns, raises) if the function signature changes.
+#   - Do NOT delete existing examples or descriptions in pydoc.
+# - LANGUAGE: en-US for all comments and documentation.
+
+# Python imports
+import copy
+import json
+import logging
+import pathlib
+import typing
+
+
+class AgentResponse:
+    """
+    Represents the result of an Agent execution, including history and errors.
+    
+    Separates process errors (fatal to the run) from tool errors (non-fatal execution errors).
+    """
+
+    def __init__(self):
+        """
+        Initialize a new AgentResponse instance.
+        """
+        self.log = logging.getLogger(f"org.slashlib.py.agent.{pathlib.Path(__file__).stem}.{self.__class__.__name__}")
+        self._context: typing.List[typing.Dict[str, typing.Any]] = []
+        self._errors: typing.List[Exception] = []
+        self._tool_errors: typing.List[Exception] = []
+
+    def append_context(self, **kwargs):
+        """
+        Public interface to add a message to the context.
+
+        Args:
+            **kwargs: Arbitrary keyword arguments (e.g., role, content).
+        """
+        self._append_context(**kwargs)
+
+    def append_error(self, error: Exception):
+        """
+        Public interface to record a process error.
+
+        Args:
+            error (Exception): The exception instance to record.
+        """
+        self._append_error(error)
+
+    def append_tool_error(self, error: Exception):
+        """
+        Public interface to record a tool error.
+
+        Args:
+            error (Exception): The exception instance to record.
+        """
+        self._append_tool_error(error)
+
+    def _append_context(self, **kwargs):
+        """
+        Internal method to append a message to the context.
+
+        Args:
+            **kwargs: Arbitrary keyword arguments. Expected to contain 'role' (str)
+                and 'content' (str, dict, or list).
+
+        Raises:
+            TypeError: If 'content' is not a string, dict, or list.
+            ValueError: If 'content' cannot be serialized to JSON.
+        """
+        role = kwargs.get("role")
+        content = kwargs.get("content")
+
+        if (not role) or (content is None):
+            self.log.warning(f"Skipped context update: 'role' or 'content' missing in {kwargs}")
+            return
+
+        # Ensure content is a string (convert if it's a JSON-like structure)
+        if isinstance(content, (dict, list)):
+            try:
+                kwargs["content"] = json.dumps(content, ensure_ascii=False)
+            except (TypeError, ValueError) as e:
+                self.log.error(f"Failed to serialize context content to JSON: {e}")
+                raise
+        elif not isinstance(content, str):
+            msg = f"Unsupported content type: {type(content)}. Expected str, dict or list."
+            self.log.error(msg)
+            raise TypeError(msg)
+
+        self._context.append(kwargs)
+
+    def _append_error(self, error: Exception):
+        """
+        Appends a process exception (fatal) to the error list.
+
+        Args:
+            error (Exception): The exception instance to record.
+        """
+        if isinstance(error, Exception):
+            self._errors.append(error)
+            self.log.debug(f"Process error recorded in AgentResponse: {error}")
+
+    def _append_tool_error(self, error: Exception):
+        """
+        Appends a tool-specific exception (non-fatal) to the tool error list.
+
+        Args:
+            error (Exception): The exception instance to record.
+        """
+        if isinstance(error, Exception):
+            self._tool_errors.append(error)
+            self.log.debug(f"Tool error recorded in AgentResponse: {error}")
+
+    def get_context(self, index: typing.Optional[int] = None) -> typing.Union[typing.List[dict], dict]:
+        """
+        Returns a deep copy of the context.
+
+        Args:
+            index (Optional[int]): If provided, returns only the node at this index.
+                Otherwise, returns the entire list. Defaults to None.
+
+        Returns:
+            Union[List[dict], dict]: A deep copy of the entire context list or a single 
+                context dictionary if an index was provided.
+        """
+        if index is not None:
+            return copy.deepcopy(self._context[index])
+        return copy.deepcopy(self._context)
+
+    @property
+    def response(self) -> typing.Optional[str]:
+        """
+        Returns the content of the last assistant message in the context.
+        
+        Returns:
+            Optional[str]: The final response string from the assistant, 
+                or None if no assistant message exists in the history.
+        """
+        for msg in reversed(self._context):
+            if msg.get("role") == "assistant":
+                return msg.get("content")
+        return None
+
+    @property
+    def context_size(self) -> int:
+        """
+        Returns the number of messages in the context.
+
+        Returns:
+            int: The total count of context entries.
+        """
+        return len(self._context)
+
+    @property
+    def has_error(self) -> bool:
+        """
+        Checks if any process errors occurred during execution.
+
+        Returns:
+            bool: True if one or more process errors were recorded.
+        """
+        return len(self._errors) > 0
+
+    @property
+    def has_tool_error(self) -> bool:
+        """
+        Checks if any tool-specific errors occurred during execution.
+
+        Returns:
+            bool: True if one or more tool errors were recorded.
+        """
+        return len(self._tool_errors) > 0
+
+    def raise_errors(self):
+        """
+        Raises the first process error if any exist. 
+        Tool errors are ignored by this method as they are non-fatal.
+
+        Raises:
+            Exception: The first process exception stored in the error list.
+        """
+        if self.has_error:
+            if len(self._errors) > 1:
+                self.log.warning(f"Multiple process errors ({len(self._errors)}) found. Raising the first one.")
+            raise self._errors[0]
+
+    def get_tool_errors(self) -> typing.List[Exception]:
+        """
+        Returns all recorded tool errors.
+
+        Returns:
+            List[Exception]: A list of exceptions that occurred during tool execution.
+        """
+        return self._tool_errors
+
+
+__all__ = ["AgentResponse"]
+
+# end of file src/org/slashlib/py/agent/agent_response.py

org/slashlib/py/agent/inference_bases.py

@@ -0,0 +1,120 @@
+# -*- coding: utf-8 -*-
+# file src/org/slashlib/py/agent/inference_bases.py
+# @AI:
+# - INTEGRITY RULES:
+#   - STRICT PRESERVATION: Do not remove, move, or modify ANY existing lines of code or comments 
+#     unless they are the explicit target of the requested change. 
+#   - DEBUG MARKERS: Commented-out code (e.g., debug prints) MUST be kept exactly where they are.
+#   - WHITESPACE & STRUCTURE: Maintain all original empty lines and the existing file structure. 
+#     Structural integrity takes precedence over "clean code" or "elegance".
+#   - LEAD-IN/OUT: The very first and last lines (and all comments in between) are immutable anchors.
+# - MAINTENANCE:
+#   - Only update pydoc strings (args, returns, raises) if the function signature changes.
+#   - Do NOT delete existing examples or descriptions in pydoc.
+# - LANGUAGE: en-US for all comments and documentation.
+
+# Python imports
+import abc
+import typing
+
+
+class InferenceError(Exception):
+    """Base exception for all inference related errors."""
+    pass
+
+
+class InferenceConnectionError(InferenceError):
+    """Raised when the connection to the AI provider fails."""
+    pass
+
+
+class InferenceConfigError(InferenceError):
+    """Raised when the model configuration (e.g. model name) is invalid."""
+    pass
+
+
+class InferencePayloadError(InferenceError):
+    """Raised when the response payload is malformed or invalid."""
+    pass
+
+
+class InferenceResult(abc.ABC):
+    """
+    Abstract interface for the result of an inference execution.
+    Standardizes how the Agent accesses model responses and tool calls.
+    """
+
+    @property
+    @abc.abstractmethod
+    def role(self) -> str:
+        """Returns the role of the message (e.g., 'assistant')."""
+        pass
+
+    @property
+    @abc.abstractmethod
+    def content(self) -> typing.Optional[str]:
+        """Returns the text content of the response."""
+        pass
+
+    @property
+    @abc.abstractmethod
+    def tool_calls(self) -> typing.Optional[typing.List[typing.Dict[str, typing.Any]]]:
+        """
+        Returns tool calls in a standardized format:
+        [{"function": {"name": str, "arguments": dict}}]
+        """
+        pass
+
+    @abc.abstractmethod
+    def to_dict(self) -> typing.Dict[str, typing.Any]:
+        """
+        Converts the result into a dictionary compatible with the 
+        internal storage format of AgentResponse.
+        """
+        pass
+
+
+class InferenceAdapter(abc.ABC):
+    """
+    Abstract interface for an Inference Adapter.
+    Encapsulates the communication with a specific AI model provider.
+    """
+
+    @abc.abstractmethod
+    async def chat(
+        self, 
+        model: typing.Optional[str] = None, 
+        messages: typing.List[typing.Dict[str, typing.Any]] = None, 
+        tools: typing.Optional[typing.List[typing.Dict[str, typing.Any]]] = None,
+        **kwargs
+    ) -> InferenceResult:
+        """
+        Executes a chat request and returns a standardized InferenceResult.
+
+        Args:
+            model (str): The name/identifier of the model to use.
+            messages (list): The full conversation context.
+            tools (list, optional): Available tool schemas.
+            **kwargs: Provider-specific options (timeout, think, temperature, etc.)
+
+        Returns:
+            InferenceResult: The validated and standardized result.
+
+        Raises:
+            InferenceConnectionError: If the provider is unreachable.
+            InferencePayloadError: If the response is malformed.
+            InferenceConfigError: If configuration/model is wrong.
+        """
+        pass
+
+
+__all__ = [
+    "InferenceResult", 
+    "InferenceAdapter", 
+    "InferenceError", 
+    "InferenceConnectionError", 
+    "InferenceConfigError", 
+    "InferencePayloadError"
+]
+
+# end of file src/org/slashlib/py/agent/inference_bases.py

org/slashlib/py/agent/inference_complements_for_ollama.py

@@ -0,0 +1,186 @@
+# -*- coding: utf-8 -*-
+# file src/org/slashlib/py/agent/inference_complements_for_ollama.py
+# @AI:
+# - INTEGRITY RULES:
+#   - STRICT PRESERVATION: Do not remove, move, or modify ANY existing lines of code or comments 
+#     unless they are the explicit target of the requested change. 
+#   - DEBUG MARKERS: Commented-out code (e.g., debug prints) MUST be kept exactly where they are.
+#   - WHITESPACE & STRUCTURE: Maintain all original empty lines and the existing file structure. 
+#     Structural integrity takes precedence over "clean code" or "elegance".
+#   - LEAD-IN/OUT: The very first and last lines (and all comments in between) are immutable anchors.
+# - MAINTENANCE:
+#   - Only update pydoc strings (args, returns, raises) if the function signature changes.
+#   - Do NOT delete existing examples or descriptions in pydoc.
+# - LANGUAGE: en-US for all comments and documentation.
+#
+
+# Python imports
+import logging
+import pathlib
+import typing
+
+# Third party imports
+import ollama
+import org.slashlib.py.configloader as config
+
+# Internal imports
+import src.org.slashlib.py.agent.inference_bases as inference
+
+
+class OllamaInferenceResult(inference.InferenceResult):
+    """
+    Specific implementation of InferenceResult for Ollama.
+
+    This class takes the raw dictionary response from the Ollama API, 
+    validates its mandatory fields (role, content/tool_calls), and 
+    provides standardized accessors for the Agent.
+    """
+
+    def __init__(self, raw_response: typing.Dict[str, typing.Any]):
+        """
+        Initialize and validate the Ollama response.
+
+        Args:
+            raw_response (Dict[str, Any]): The 'message' part of the Ollama API response.
+
+        Raises:
+            inference.InferencePayloadError: If the 'role' is missing or if both 
+                'content' and 'tool_calls' are empty/None.
+        """
+        self._role = raw_response.get("role")
+        self._content = raw_response.get("content")
+        self._tool_calls = raw_response.get("tool_calls")
+
+        if not self._role:
+            raise inference.InferencePayloadError(f"Invalid Ollama response: 'role' is missing. Data: {raw_response}")
+        
+        # Note: content can be None if tool_calls are present, which is valid.
+        if self._content is None and not self._tool_calls:
+            raise inference.InferencePayloadError(f"Invalid Ollama response: Both 'content' and 'tool_calls' are empty.")
+
+    @property
+    def role(self) -> str:
+        """
+        The role of the message sender.
+
+        Returns:
+            str: Typically 'assistant'.
+        """
+        return self._role
+
+    @property
+    def content(self) -> typing.Optional[str]:
+        """
+        The text content of the model's response.
+
+        Returns:
+            Optional[str]: The message text or None if only tool calls are present.
+        """
+        return self._content
+
+    @property
+    def tool_calls(self) -> typing.Optional[typing.List[typing.Dict[str, typing.Any]]]:
+        """
+        A list of tool calls generated by the model.
+
+        Returns:
+            Optional[List[Dict[str, Any]]]: Standardized tool call objects or None.
+        """
+        return self._tool_calls
+
+    def to_dict(self) -> typing.Dict[str, typing.Any]:
+        """
+        Converts the result into a standardized dictionary.
+
+        Returns:
+            Dict[str, Any]: A dictionary containing 'role', 'content', and 'tool_calls'.
+        """
+        return {
+            "role": self._role,
+            "content": self._content,
+            "tool_calls": self._tool_calls
+        }
+
+
+class OllamaInferenceAdapter(inference.InferenceAdapter):
+    """
+    Inference Adapter for the Ollama API.
+
+    Handles asynchronous communication with an Ollama server, including 
+    parameter resolution from config and error mapping to the neutral 
+    inference exception hierarchy.
+    """
+
+    def __init__(self):
+        """
+        Initialize the adapter and its logger.
+        """
+        self.log = logging.getLogger(f"org.slashlib.py.agent.{pathlib.Path(__file__).stem}.{self.__class__.__name__}")
+
+    async def chat(
+        self, 
+        model: typing.Optional[str] = None, 
+        messages: typing.List[typing.Dict[str, typing.Any]] = None, 
+        tools: typing.Optional[typing.List[typing.Dict[str, typing.Any]]] = None,
+        **kwargs
+    ) -> inference.InferenceResult:
+        """
+        Sends a chat request to Ollama and returns a validated result.
+
+        Resolves model parameters using a priority chain: 
+        1. Explicit kwargs, 2. Method arguments, 3. pyproject.json via configloader.
+
+        Args:
+            model (Optional[str]): The model name. Defaults to config value.
+            messages (List[Dict[str, Any]]): The message history/context.
+            tools (Optional[List[Dict[str, Any]]]): JSON schemas of available tools.
+            **kwargs: Additional parameters like 'timeout' or 'think'.
+
+        Returns:
+            inference.InferenceResult: An instance of OllamaInferenceResult.
+
+        Raises:
+            inference.InferenceConfigError: If the model is not found or config is invalid.
+            inference.InferenceConnectionError: If the Ollama server is unreachable or times out.
+            inference.InferencePayloadError: If the response from Ollama is malformed.
+            inference.InferenceError: For any other unexpected errors during inference.
+        """
+        # Resolve parameters: priority is kwargs -> method arg -> pyproject.json
+        target_model = model or kwargs.get("model", config.resolve("adapter.ollama.model"))
+        timeout = kwargs.get("timeout", config.resolve("adapter.ollama.timeout"))
+        think = kwargs.get("think", config.resolve("adapter.ollama.think"))
+
+        try:
+            self.log.debug(f"Ollama request: model={target_model}, timeout={timeout}, think={think}")
+            
+            client = ollama.AsyncClient(timeout=timeout)
+            response = await client.chat(
+                model=target_model,
+                messages=messages,
+                tools=tools,
+                think=think
+            )
+
+            message = response.get("message")
+            if not message:
+                raise inference.InferencePayloadError(f"Ollama API returned an empty response for model '{target_model}'.")
+
+            return OllamaInferenceResult(message)
+
+        except (ollama.ResponseError) as e:
+            self.log.error(f"Ollama logical/config error: {e}")
+            raise inference.InferenceConfigError(f"Ollama model or config invalid: {str(e)}")
+        except (ollama.RequestError) as e:
+            self.log.error(f"Ollama communication error: {e}")
+            raise inference.InferenceConnectionError(f"Failed to connect to Ollama: {str(e)}")
+        except inference.InferenceError:
+            # Re-raise internal inference errors to prevent them from being caught by the general Exception block
+            raise
+        except Exception as e:
+            self.log.error(f"Unexpected error in OllamaInferenceAdapter: {e}", exc_info=True)
+            raise inference.InferenceError(f"Internal adapter error: {str(e)}")
+
+
+__all__ = ["OllamaInferenceAdapter", "OllamaInferenceResult"]
+
+# end of file src/org/slashlib/py/agent/inference_complements_for_ollama.py

org/slashlib/py/agent/tool.py

@@ -0,0 +1,158 @@
+# -*- coding: utf-8 -*-
+# file src/org/slashlib/py/agent/tool.py
+# @AI:
+# - INTEGRITY RULES:
+#   - STRICT PRESERVATION: Do not remove, move, or modify ANY existing lines of code or comments 
+#     unless they are the explicit target of the requested change. 
+#   - DEBUG MARKERS: Commented-out code (e.g., debug prints) MUST be kept exactly where they are.
+#   - WHITESPACE & STRUCTURE: Maintain all original empty lines and the existing file structure. 
+#     Structural integrity takes precedence over "clean code" or "elegance".
+#   - LEAD-IN/OUT: The very first and last lines (and all comments in between) are immutable anchors.
+# - MAINTENANCE:
+#   - Only update pydoc strings (args, returns, raises) if the function signature changes.
+#   - Do NOT delete existing examples or descriptions in pydoc.
+# - LANGUAGE: en-US for all comments and documentation.
+#
+
+# Python imports
+import functools
+import inspect
+import typing
+
+# Third party imports
+
+
+class Tool:
+    """
+    A wrapper class that transforms a Python function into a schema-aware tool.
+    
+    This class is designed to be used by AI agents (like Gemma 4) to understand 
+    the capabilities, parameters, and requirements of a specific function.
+    """
+
+    def __init__(self, func, name=None, description=None):
+        """
+        Initialize the Tool instance.
+
+        Args:
+            func (Callable): The function to be wrapped as a tool.
+            name (Optional[str]): Override for the function's name. Defaults to func.__name__.
+            description (Optional[str]): Override for the function's description. 
+                Defaults to the function's docstring.
+        """
+        self._func = func
+        self.name = name or func.__name__
+        self.description = description or func.__doc__ or "No description provided."
+        # Wir kopieren Metadaten der Originalfunktion (für Dokumentation etc.)
+        functools.update_wrapper(self, func)
+
+    def _map_type(self, annotation: typing.Any) -> str:
+        """
+        Maps Python type annotations to JSON schema compatible type strings.
+
+        Args:
+            annotation (Any): The Python type annotation to map.
+
+        Returns:
+            str: The corresponding JSON schema type (e.g., 'string', 'integer', 'array').
+        """
+        # Handle Optional[T] or Union[T, None]
+        origin = typing.get_origin(annotation)
+        if origin is typing.Union:
+            args = typing.get_args(annotation)
+            # Filter out NoneType to find the actual type
+            actual_types = [a for a in args if a is not type(None)]
+            if actual_types:
+                return self._map_type(actual_types[0])
+
+        mapping = {
+            int: "integer",
+            float: "number",
+            str: "string",
+            bool: "boolean",
+            list: "array",
+            dict: "object",
+            typing.List: "array",
+            typing.Dict: "object",
+        }
+        
+        return mapping.get(annotation if origin is None else origin, "string")
+
+    def get_schema(self) -> dict:
+        """
+        Generates a JSON schema based on the function's signature and annotations.
+        
+        The schema follows the standard expected by modern LLMs for tool calling.
+
+        Returns:
+            dict: A dictionary representing the tool's schema, including name, 
+                description, and parameter definitions.
+        """
+        sig = inspect.signature(self._func)
+        parameters = {"type": "object", "properties": {}, "required": []}
+
+        for param_name, param in sig.parameters.items():
+            # Skip 'self' or 'cls' if decorated inside a class (though unlikely here)
+            if param_name in ("self", "cls"):
+                continue
+
+            param_type = self._map_type(param.annotation)
+            
+            param_info = {
+                "type": param_type,
+                "description": f"Parameter {param_name}"
+            }
+
+            # If there's a default value, mention it in the description
+            if param.default is not inspect.Parameter.empty:
+                param_info["default"] = param.default
+                param_info["description"] += f" (defaults to {param.default})"
+            else:
+                parameters["required"].append(param_name)
+
+            parameters["properties"][param_name] = param_info
+
+        return {
+            "name": self.name,
+            "description": self.description.strip(),
+            "parameters": parameters
+        }
+
+    async def __call__(self, *args, **kwargs):
+        """
+        Executes the wrapped function.
+        
+        Supports both synchronous and asynchronous functions transparently.
+
+        Args:
+            *args: Positional arguments for the wrapped function.
+            **kwargs: Keyword arguments for the wrapped function.
+
+        Returns:
+            Any: The result of the function execution.
+        """
+        if inspect.iscoroutinefunction(self._func):
+            return await self._func(*args, **kwargs)
+        return self._func(*args, **kwargs)
+
+
+def tool(name: str = None, description: str = None):
+    """
+    A decorator that converts a function into a Tool object.
+
+    Args:
+        name (Optional[str]): A custom name for the tool.
+        description (Optional[str]): A custom description for the tool.
+
+    Returns:
+        Callable: A decorator function that wraps the target function in a Tool instance.
+    """
+    def decorator(func):
+        # Wir geben eine Instanz von Tool zurück
+        return Tool(func, name=name, description=description)
+    return decorator
+
+
+__all__ = ["tool", "Tool"]
+
+# end of file src/org/slashlib/py/agent/tool.py

org_slashlib_py_agent-0.1.0.dist-info/METADATA

@@ -0,0 +1,100 @@
+Metadata-Version: 2.4
+Name: org.slashlib.py.agent
+Version: 0.1.0
+Summary: python agent for inference handling
+Author-email: Dirk Brenckmann <db.developer@gmx.de>
+Project-URL: Homepage, https://github.com/org-slashlib/org.slashlib.py.agent
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+Dynamic: license-file
+
+[Bottom](#license) [AI](AI.md) [CHANGELOG](CHANGELOG.md) [LICENSE](LICENSE.md)
+# org.slashlib.py.agent
+
+A highly decoupled, asynchronous framework for building AI agents in Python.
+
+[![PyPI version](https://img.shields.io/pypi/v/org.slashlib.py.agent.svg)](https://pypi.org/project/org.slashlib.py.agent/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Core Concept
+
+This package provides a robust infrastructure to connect AI models (Inference Engines) with functional tools. The focus lies on **Provider Agnosticism**: The agent does not need to know whether it is communicating with Ollama, OpenAI, or a local model—it uses standardized adapters to ensure seamless integration.
+
+### Key Features
+- **Asynchronous Core**: Built on `asyncio` for non-blocking task execution.
+- **Provider Agnostic**: Easily swap the AI engine using the Adapter pattern.
+- **Automatic Tool Schemas**: Automatically transforms Python functions into JSON schemas for LLMs via decorators.
+- **Multiton Pattern**: Ensures unique agent instances by identifier, preventing redundant resource allocation.
+- **Robust Exception Hierarchy**: Clearly separates connection, configuration, and tool execution errors.
+
+---
+## Installation
+
+Install the package via pip:
+
+```bash
+pip install org.slashlib.py.agent
+```
+
+---
+## Quick Start
+
+Setting up an agent with a tool and the Ollama adapter is straightforward:
+
+```python
+import asyncio
+from org.slashlib.py.agent import Agent, OllamaInferenceAdapter, tool
+
+# 1. Define a tool
+@tool(description="Adds two numbers.")
+async def add_numbers(a: int, b: int) -> int:
+    return a + b
+
+async def main():
+    # 2. Configure Adapter and Agent
+    adapter = OllamaInferenceAdapter()
+    my_agent = Agent(
+        identifier="MathExpert",
+        tools=[add_numbers],
+        adapter=adapter
+    )
+
+    # 3. Start task (non-blocking)
+    task = my_agent.run(user_prompt="What is 123 + 456?")
+    
+    # 4. Retrieve result
+    response = await task
+    print(f"Response: {response.get_last_content()}")
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+---
+## Documentation & Obsidian
+
+The project root is pre-configured as an **Obsidian Vault**. If you open this folder directly in Obsidian, all settings and documentation links will be available immediately via the included `.obsidian` directory.
+
+The following community plugins are pre-configured in the vault to enhance the documentation experience:
+
+* **[File Include](https://github.com/tillahoffmann/obsidian-file-include)**: Embed code files directly into your markdown documentation.
+* **[Folder Notes](https://github.com/LostPaul/obsidian-folder-notes)**: Add descriptions at the folder level.
+* **[Front Matter Title](https://github.com/snezhig/obsidian-front-matter-title)**: Use metadata for descriptive file titles.
+* **[Hide Folders](https://github.com/JonasDoesThings/obsidian-hide-folders)**: Keeps the structure clean by hiding internal directories.
+* **[Iconic](https://github.com/gfxholo/iconic)** & **[Icons](https://github.com/visini/obsidian-icons-plugin)**: Improved visual navigation.
+
+[More docs](docs)
+
+---
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE.md) file for details.
+
+---
+© 2026 org.slashlib
+
+[TOP](#org-slashlib-py-agent) [AI](AI.md) [CHANGELOG](CHANGELOG.md) [LICENSE](LICENSE.md)

org_slashlib_py_agent-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+org/slashlib/py/agent/__init__.py,sha256=XMV_X4I7bKJjRYrEOMf9_Hs9Tw94lDDaylpKJ_2HNzo,1738
+org/slashlib/py/agent/__main__.py,sha256=_Ldk6mqVZO9gEDD_Tq7GvY__GMdoqafOO8iWuSMxY2A,3105
+org/slashlib/py/agent/agent.py,sha256=eGBXVc804dlJ8TA_Veg6SkTbqnZCYYczv65eLuq_tXI,12665
+org/slashlib/py/agent/agent_response.py,sha256=Km1AA8ZrQ8heG42EbfIAcWAOGWn61H3y26_PLBXTtEk,7274
+org/slashlib/py/agent/inference_bases.py,sha256=MdbbxBwAQGJKGxOYB6VKvLQYJcWxZ0ULFS7Ylekhxuc,3920
+org/slashlib/py/agent/inference_complements_for_ollama.py,sha256=4dosSeZIiLr9jQGX3JPw9bxXv0rv9kzbMboWnktQCuo,7477
+org/slashlib/py/agent/tool.py,sha256=rvBt-zCeaBtY9GNrQ-uaDCje2YOMNUX3diO8c6tn7DQ,5838
+org_slashlib_py_agent-0.1.0.dist-info/licenses/LICENSE.md,sha256=u_SrMZcAG0bjypv4AKPAgE9VFf-2vn8L0fRdizujhfI,1144
+org_slashlib_py_agent-0.1.0.dist-info/METADATA,sha256=mdkOpZF9eCTxxVCAsEGA5Ref9YBFam-6xwt8cm92WgQ,3992
+org_slashlib_py_agent-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+org_slashlib_py_agent-0.1.0.dist-info/org.slashlib.py.agent.egg-info.md,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+org_slashlib_py_agent-0.1.0.dist-info/top_level.txt,sha256=Y-Q3pQ6MMlBKzHVfq3nXGvODPPpbfj5OBXrcr17O02w,4
+org_slashlib_py_agent-0.1.0.dist-info/RECORD,,

org_slashlib_py_agent-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

org_slashlib_py_agent-0.1.0.dist-info/licenses/LICENSE.md

@@ -0,0 +1,23 @@
+[AI](AI.md) [CHANGELOG](CHANGELOG.md) [README](README.md)
+
+MIT License
+
+Copyright (c) 2019 Dirk Brenckmann, db-developer
+
+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.

org_slashlib_py_agent-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+org