janito 1.9.0__py3-none-any.whl → 1.10.0__py3-none-any.whl

janito/agent/openai_schema_generator.py

@@ -1,8 +1,9 @@
 """
-MUST BE IMPLEMENTED:
-- check that all params found in the signature have documentation in the docstring which is provided in the parameter schema doc
-- the Return must be documented and integrated in the sechema description
-- backward compatibility is not required
+Generates OpenAI-compatible function schemas from Python callables and class docstrings.
+
+- Ensures all parameters are documented and type-annotated.
+- Integrates return documentation into the schema description.
+- Supports Google, NumPy, and relaxed docstring formats.
 """
 
 import inspect
@@ -20,135 +21,167 @@ PYTHON_TYPE_TO_JSON = {
 }
 
 
-def _type_to_json_schema(annotation):
-    if hasattr(annotation, "__origin__"):
-        if annotation.__origin__ is list or annotation.__origin__ is typing.List:
-            return {
-                "type": "array",
-                "items": _type_to_json_schema(annotation.__args__[0]),
-            }
-        if annotation.__origin__ is dict or annotation.__origin__ is typing.Dict:
-            return {"type": "object"}
-    return {"type": PYTHON_TYPE_TO_JSON.get(annotation, "string")}
-
-
-def _parse_docstring(docstring: str):
+class OpenAISchemaGenerator:
     """
-    Parses a docstring to extract summary, parameter descriptions, and return description.
-    Accepts Google, NumPy, and relaxed formats.
-    Returns: summary, {param: description}, return_description
+    Generates OpenAI-compatible function schemas from Python callables and class docstrings.
+
+    - Ensures all parameters are documented and type-annotated.
+    - Integrates return documentation into the schema description.
+    - Supports Google, NumPy, and relaxed docstring formats.
     """
-    if not docstring:
-        return "", {}, ""
-    lines = docstring.strip().split("\n")
-    summary = lines[0].strip()
-    param_descs = {}
-    return_desc = ""
-    in_params = False
-    in_returns = False
-    param_section_headers = ("args", "arguments", "params", "parameters")
-    for line in lines[1:]:
-        stripped_line = line.strip()
-        if any(
-            stripped_line.lower().startswith(h + ":") or stripped_line.lower() == h
-            for h in param_section_headers
-        ):
-            in_params = True
-            in_returns = False
-            continue
-        if (
-            stripped_line.lower().startswith("returns:")
-            or stripped_line.lower() == "returns"
-        ):
-            in_returns = True
-            in_params = False
-            continue
-        if in_params:
-            # Accept: name: desc, name (type): desc, name - desc, name desc
-            m = re.match(
-                r"([a-zA-Z_][a-zA-Z0-9_]*)\s*(?:\(([^)]+)\))?\s*[:\-]?\s*(.+)",
-                stripped_line,
-            )
-            if m:
-                param, _, desc = m.groups()
-                param_descs[param] = desc.strip()
-            elif stripped_line and stripped_line[0] != "-":
-                # Continuation of previous param
-                if param_descs:
-                    last = list(param_descs)[-1]
-                    param_descs[last] += " " + stripped_line
-        elif in_returns:
-            if stripped_line:
-                return_desc += (" " if return_desc else "") + stripped_line
-    return summary, param_descs, return_desc
 
+    def __init__(self):
+        pass
 
-def generate_openai_function_schema(func, tool_name: str, tool_class=None):
-    """
-    Generates an OpenAI-compatible function schema for a callable.
-    Raises ValueError if the return type is not explicitly str or if any parameter is missing a type hint.
-    """
-    sig = inspect.signature(func)
-    # Enforce explicit str return type
-    if sig.return_annotation is inspect._empty or sig.return_annotation is not str:
-        raise ValueError(
-            f"Tool '{tool_name}' must have an explicit return type of 'str'. Found: {sig.return_annotation}"
-        )
-    # Enforce type hints for all parameters (except self)
-    missing_type_hints = [
-        name
-        for name, param in sig.parameters.items()
-        if name != "self" and param.annotation is inspect._empty
-    ]
-    if missing_type_hints:
-        raise ValueError(
-            f"Tool '{tool_name}' is missing type hints for parameter(s): {', '.join(missing_type_hints)}.\n"
-            f"All parameters must have explicit type hints for schema generation."
-        )
-    # Only use the class docstring for schema generation
-    class_doc = tool_class.__doc__.strip() if tool_class and tool_class.__doc__ else ""
-    summary, param_descs, return_desc = _parse_docstring(class_doc)
-    description = summary
-    if return_desc:
-        description += f"\n\nReturns: {return_desc}"
-    # Check that all parameters in the signature have documentation
-    undocumented = [
-        name
-        for name, param in sig.parameters.items()
-        if name != "self" and name not in param_descs
-    ]
-    if undocumented:
-        raise ValueError(
-            f"Tool '{tool_name}' is missing docstring documentation for parameter(s): {', '.join(undocumented)}.\n"
-            f"Parameter documentation must be provided in the Tool class docstring, not the method docstring."
+    def type_to_json_schema(self, annotation):
+        if hasattr(annotation, "__origin__"):
+            if annotation.__origin__ is list or annotation.__origin__ is typing.List:
+                return {
+                    "type": "array",
+                    "items": self.type_to_json_schema(annotation.__args__[0]),
+                }
+            if annotation.__origin__ is dict or annotation.__origin__ is typing.Dict:
+                return {"type": "object"}
+        return {"type": PYTHON_TYPE_TO_JSON.get(annotation, "string")}
+
+    def parse_param_section(self, lines, param_section_headers):
+        param_descs = {}
+        in_params = False
+        for line in lines:
+            stripped_line = line.strip()
+            if any(
+                stripped_line.lower().startswith(h + ":") or stripped_line.lower() == h
+                for h in param_section_headers
+            ):
+                in_params = True
+                continue
+            if in_params:
+                m = re.match(
+                    r"([a-zA-Z_][a-zA-Z0-9_]*)\s*(?:\(([^)]+)\))?\s*[:\-]?\s*(.+)",
+                    stripped_line,
+                )
+                if m:
+                    param, _, desc = m.groups()
+                    param_descs[param] = desc.strip()
+                elif stripped_line and stripped_line[0] != "-":
+                    if param_descs:
+                        last = list(param_descs)[-1]
+                        param_descs[last] += " " + stripped_line
+            if (
+                stripped_line.lower().startswith("returns:")
+                or stripped_line.lower() == "returns"
+            ):
+                break
+        return param_descs
+
+    def parse_return_section(self, lines):
+        in_returns = False
+        return_desc = ""
+        for line in lines:
+            stripped_line = line.strip()
+            if (
+                stripped_line.lower().startswith("returns:")
+                or stripped_line.lower() == "returns"
+            ):
+                in_returns = True
+                continue
+            if in_returns:
+                if stripped_line:
+                    return_desc += (" " if return_desc else "") + stripped_line
+        return return_desc
+
+    def parse_docstring(self, docstring: str):
+        """
+        Parses a docstring to extract summary, parameter descriptions, and return description.
+        Accepts Google, NumPy, and relaxed formats.
+        Returns: summary, {param: description}, return_description
+        """
+        if not docstring:
+            return "", {}, ""
+        lines = docstring.strip().split("\n")
+        summary = lines[0].strip()
+        param_section_headers = ("args", "arguments", "params", "parameters")
+        param_descs = self.parse_param_section(lines[1:], param_section_headers)
+        return_desc = self.parse_return_section(lines[1:])
+        return summary, param_descs, return_desc
+
+    def generate_schema(self, tool_class):
+        """
+        Generates an OpenAI-compatible function schema for a tool class.
+        The tool class must have _tool_run_method and _tool_name attributes set by the tool registration decorator.
+        Raises ValueError if the return type is not explicitly str or if any parameter is missing a type hint.
+        """
+        if not hasattr(tool_class, "_tool_run_method") or not hasattr(
+            tool_class, "_tool_name"
+        ):
+            raise ValueError(
+                "Tool class must have _tool_run_method and _tool_name attributes (set by @register_tool)."
+            )
+        func = tool_class._tool_run_method
+        tool_name = tool_class._tool_name
+        sig = inspect.signature(func)
+        # Enforce explicit str return type
+        if sig.return_annotation is inspect._empty or sig.return_annotation is not str:
+            raise ValueError(
+                f"Tool '{tool_name}' must have an explicit return type of 'str'. Found: {sig.return_annotation}"
+            )
+        # Enforce type hints for all parameters (except self)
+        missing_type_hints = [
+            name
+            for name, param in sig.parameters.items()
+            if name != "self" and param.annotation is inspect._empty
+        ]
+        if missing_type_hints:
+            raise ValueError(
+                f"Tool '{tool_name}' is missing type hints for parameter(s): {', '.join(missing_type_hints)}.\n"
+                f"All parameters must have explicit type hints for schema generation."
+            )
+        # Only use the class docstring for schema generation
+        class_doc = (
+            tool_class.__doc__.strip() if tool_class and tool_class.__doc__ else ""
         )
-    properties = OrderedDict()
-    required = []
-    # Inject tool_call_reason as the first required parameter, unless --ntt is set
-    from janito.agent.runtime_config import runtime_config
+        summary, param_descs, return_desc = self.parse_docstring(class_doc)
+        description = summary
+        if return_desc:
+            description += f"\n\nReturns: {return_desc}"
+        # Check that all parameters in the signature have documentation
+        undocumented = [
+            name
+            for name, param in sig.parameters.items()
+            if name != "self" and name not in param_descs
+        ]
+        if undocumented:
+            raise ValueError(
+                f"Tool '{tool_name}' is missing docstring documentation for parameter(s): {', '.join(undocumented)}.\n"
+                f"Parameter documentation must be provided in the Tool class docstring, not the method docstring."
+            )
+        properties = OrderedDict()
+        required = []
+        # Inject tool_call_reason as the first required parameter, unless --ntt is set
+        from janito.agent.runtime_config import runtime_config
 
-    if not runtime_config.get("no_tools_tracking", False):
-        properties["tool_call_reason"] = {
-            "type": "string",
-            "description": "The reason or context for why this tool is being called. This is required for traceability.",
+        if not runtime_config.get("no_tools_tracking", False):
+            properties["tool_call_reason"] = {
+                "type": "string",
+                "description": "The reason or context for why this tool is being called. This is required for traceability.",
+            }
+            required.append("tool_call_reason")
+        for name, param in sig.parameters.items():
+            if name == "self":
+                continue
+            annotation = param.annotation
+            pdesc = param_descs.get(name, "")
+            schema = self.type_to_json_schema(annotation)
+            schema["description"] = pdesc
+            properties[name] = schema
+            if param.default == inspect._empty:
+                required.append(name)
+        return {
+            "name": tool_name,
+            "description": description,
+            "parameters": {
+                "type": "object",
+                "properties": properties,
+                "required": required,
+            },
         }
-        required.append("tool_call_reason")
-    for name, param in sig.parameters.items():
-        if name == "self":
-            continue
-        annotation = param.annotation
-        pdesc = param_descs.get(name, "")
-        schema = _type_to_json_schema(annotation)
-        schema["description"] = pdesc
-        properties[name] = schema
-        if param.default == inspect._empty:
-            required.append(name)
-    return {
-        "name": tool_name,
-        "description": description,
-        "parameters": {
-            "type": "object",
-            "properties": properties,
-            "required": required,
-        },
-    }

janito/agent/platform_discovery.py

@@ -1,90 +1,147 @@
+import os
 import platform
+import subprocess
 import sys
 
 
-def detect_shell():
-    import os
-    import subprocess
-
-    shell_info = None
-
-    # 1. Detect shell (prefer Git Bash if detected)
-    if os.environ.get("MSYSTEM"):
-        shell_info = f"Git Bash ({os.environ.get('MSYSTEM')})"
-    # 2. Detect WSL (before PowerShell)
-    elif os.environ.get("WSL_DISTRO_NAME"):
-        shell = os.environ.get("SHELL")
-        shell_name = shell.split("/")[-1] if shell else "unknown"
-        distro = os.environ.get("WSL_DISTRO_NAME")
-        shell_info = f"{shell_name} (WSL: {distro})"
-    else:
-        # 3. Try to detect PowerShell by running $host.Name
+class PlatformDiscovery:
+    """
+    Provides utilities for detecting the current shell, platform, and Python version.
+    Uses the system's environment and subprocess modules internally.
+    """
+
+    def __init__(self):
+        """
+        Initialize the PlatformDiscovery instance.
+        Uses os.environ and subprocess by default.
+        """
+        self.os_environ = os.environ
+        self.subprocess_mod = subprocess
+
+    def _detect_git_bash(self):
+        if self.os_environ.get("MSYSTEM"):
+            return f"Git Bash ({self.os_environ.get('MSYSTEM')})"
+        return None
+
+    def _detect_wsl(self):
+        if self.os_environ.get("WSL_DISTRO_NAME"):
+            shell = self.os_environ.get("SHELL")
+            shell_name = shell.split("/")[-1] if shell else "unknown"
+            distro = self.os_environ.get("WSL_DISTRO_NAME")
+            return f"{shell_name} (WSL: {distro})"
+        return None
+
+    def _detect_powershell(self):
         try:
-            result = subprocess.run(
+            result = self.subprocess_mod.run(
                 ["powershell.exe", "-NoProfile", "-Command", "$host.Name"],
                 capture_output=True,
                 text=True,
                 timeout=2,
             )
             if result.returncode == 0 and "ConsoleHost" in result.stdout:
-                shell_info = "PowerShell"
-            else:
-                shell_info = None
+                return "PowerShell"
         except Exception:
-            shell_info = None
-
-        # 4. If not PowerShell, check SHELL
-        if not shell_info:
-            shell = os.environ.get("SHELL")
-            if shell:
-                shell_info = shell
+            pass
+        return None
+
+    def _detect_shell_env(self):
+        shell = self.os_environ.get("SHELL")
+        if shell:
+            return shell
+        return None
+
+    def _detect_comspec(self):
+        comspec = self.os_environ.get("COMSPEC")
+        if comspec:
+            if "powershell" in comspec.lower():
+                return "PowerShell"
+            elif "cmd" in comspec.lower():
+                return "cmd.exe"
             else:
-                # 5. If not, check COMSPEC for PowerShell or cmd.exe
-                comspec = os.environ.get("COMSPEC")
-                if comspec:
-                    if "powershell" in comspec.lower():
-                        shell_info = "PowerShell"
-                    elif "cmd" in comspec.lower():
-                        shell_info = "cmd.exe"
-                    else:
-                        shell_info = "Unknown shell"
-                else:
-                    shell_info = "Unknown shell"
-
-    # 6. Always append TERM and TERM_PROGRAM if present
-    term_env = os.environ.get("TERM")
-    if term_env:
-        shell_info += f" [TERM={term_env}]"
-
-    term_program = os.environ.get("TERM_PROGRAM")
-    if term_program:
-        shell_info += f" [TERM_PROGRAM={term_program}]"
-
-    return shell_info
-
-
-def get_platform_name():
-    sys_platform = platform.system().lower()
-    if sys_platform.startswith("win"):
-        return "windows"
-    elif sys_platform.startswith("linux"):
-        return "linux"
-    elif sys_platform.startswith("darwin"):
-        return "darwin"
-    return sys_platform
-
-
-def get_python_version():
-    return platform.python_version()
-
-
-def is_windows():
-    return sys.platform.startswith("win")
-
-
-def is_linux():
-    return sys.platform.startswith("linux")
-
-
-def is_mac():
-    return sys.platform.startswith("darwin")
+                return "Unknown shell"
+        return "Unknown shell"
+
+    def _append_term_info(self, shell_info):
+        term_env = self.os_environ.get("TERM")
+        if term_env:
+            shell_info += f" [TERM={term_env}]"
+        term_program = self.os_environ.get("TERM_PROGRAM")
+        if term_program:
+            shell_info += f" [TERM_PROGRAM={term_program}]"
+        return shell_info
+
+    def detect_shell(self) -> str:
+        """
+        Detects the current shell environment and returns a descriptive string,
+        including terminal information if available.
+
+        Note:
+            This method may invoke subprocesses to execute shell commands
+            (e.g., to detect PowerShell), which could have side effects or
+            performance implications.
+
+        Returns:
+            str: Description of the detected shell and terminal info.
+        """
+        shell_info = (
+            self._detect_git_bash()
+            or self._detect_wsl()
+            or self._detect_powershell()
+            or self._detect_shell_env()
+            or self._detect_comspec()
+        )
+        shell_info = self._append_term_info(shell_info)
+        return shell_info
+
+    def get_platform_name(self) -> str:
+        """
+        Returns the normalized platform name.
+
+        Returns:
+            str: One of 'windows', 'linux', 'darwin', or the raw platform string.
+        """
+        sys_platform = platform.system().lower()
+        if sys_platform.startswith("win"):
+            return "windows"
+        elif sys_platform.startswith("linux"):
+            return "linux"
+        elif sys_platform.startswith("darwin"):
+            return "darwin"
+        return sys_platform
+
+    def get_python_version(self) -> str:
+        """
+        Returns the current Python version as a string.
+
+        Returns:
+            str: Python version (e.g., '3.12.0').
+        """
+        return platform.python_version()
+
+    def is_windows(self) -> bool:
+        """
+        Checks if the current platform is Windows.
+
+        Returns:
+            bool: True if running on Windows, False otherwise.
+        """
+        return sys.platform.startswith("win")
+
+    def is_linux(self) -> bool:
+        """
+        Checks if the current platform is Linux.
+
+        Returns:
+            bool: True if running on Linux, False otherwise.
+        """
+        return sys.platform.startswith("linux")
+
+    def is_mac(self) -> bool:
+        """
+        Checks if the current platform is macOS.
+
+        Returns:
+            bool: True if running on macOS, False otherwise.
+        """
+        return sys.platform.startswith("darwin")

janito/agent/profile_manager.py

@@ -1,8 +1,7 @@
 from openai import OpenAI
 from jinja2 import Environment, FileSystemLoader, select_autoescape
 from pathlib import Path
-from janito.agent.platform_discovery import get_platform_name, get_python_version
-from janito.agent.platform_discovery import detect_shell
+from janito.agent.platform_discovery import PlatformDiscovery
 
 
 class AgentProfileManager:
@@ -21,9 +20,10 @@ class AgentProfileManager:
             main_template_name = "system_prompt_template_base_pt.txt.j2"
         else:
             main_template_name = "system_prompt_template_base.txt.j2"
-        platform_name = get_platform_name()
-        python_version = get_python_version()
-        shell_info = detect_shell()
+        pd = PlatformDiscovery()
+        platform_name = pd.get_platform_name()
+        python_version = pd.get_python_version()
+        shell_info = pd.detect_shell()
 
         context = {
             "role": self.role,