janito 1.14.2__py3-none-any.whl → 2.0.0__py3-none-any.whl

janito/tools/tool_events.py

@@ -0,0 +1,58 @@
+import attr
+from typing import Any, ClassVar
+from janito.event_bus.event import Event
+
+
+@attr.s(auto_attribs=True, kw_only=True)
+class ToolEvent(Event):
+    """
+    Base class for events related to tool calls (external or internal tools).
+    Includes tool name and request ID for correlation.
+    """
+
+    category: ClassVar[str] = "tool"
+    tool_name: str
+    request_id: str
+
+
+@attr.s(auto_attribs=True, kw_only=True)
+class ToolCallStarted(ToolEvent):
+    """
+    Event indicating that a tool call has started.
+    Contains the arguments passed to the tool.
+    """
+
+    arguments: Any
+
+
+@attr.s(auto_attribs=True, kw_only=True)
+class ToolCallFinished(ToolEvent):
+    """
+    Event indicating that a tool call has finished.
+    Contains the result returned by the tool.
+    """
+
+    result: Any
+
+
+@attr.s(auto_attribs=True, kw_only=True)
+class ToolRunError(ToolEvent):
+    """
+    Event indicating that an error occurred during tool execution (for event bus, not exception handling).
+    """
+
+    error: str
+    exception: Exception = None
+    arguments: Any = None
+
+
+@attr.s(auto_attribs=True, kw_only=True)
+class ToolCallError(ToolEvent):
+    """
+    Event indicating that the tool could not be called (e.g., tool not found, invalid arguments, or invocation failure).
+    This is distinct from ToolRunError, which is for errors during execution after the tool has started running.
+    """
+
+    error: str
+    exception: Exception = None
+    arguments: Any = None

janito/tools/tool_run_exception.py

@@ -0,0 +1,12 @@
+class ToolRunException(Exception):
+    """
+    Exception raised when a tool runs but fails due to an internal error or runtime exception.
+    This is distinct from ToolRunError event, which is for event bus notification.
+    """
+
+    def __init__(self, tool_name, error, arguments=None, exception=None):
+        self.tool_name = tool_name
+        self.error = error
+        self.arguments = arguments
+        self.original_exception = exception
+        super().__init__(f"ToolRunException: {tool_name}: {error}")

janito/{agent → tools}/tool_use_tracker.py

@@ -48,7 +48,7 @@ class ToolUseTracker:
     def file_fully_read(self, file_path: str) -> bool:
         norm_file_path = normalize_path(file_path)
         for entry in self._history:
-            if entry["tool"] == "get_lines":
+            if entry["tool"] == "view_file":
                 params = entry["params"]
                 if (
                     "file_path" in params
@@ -67,9 +67,7 @@ class ToolUseTracker:
         if not ops:
             return False
         last = ops[-1]
-        if last["tool"] == "replace_file":
-            return True
-        if last["tool"] == "get_lines":
+        if last["tool"] == "view_file":
             params = last["params"]
             if params.get("from_line") is None and params.get("to_line") is None:
                 return True

janito/{agent/tools_utils/utils.py → tools/tool_utils.py}

@@ -1,16 +1,28 @@
+"""
+Utility functions for the janito project.
+Add your shared helper functions here.
+"""
+
 import os
 import urllib.parse
-from janito.agent.runtime_config import runtime_config
+
+
+def example_utility_function(x):
+    """A simple example utility function."""
+    return f"Processed: {x}"
 
 
 def display_path(path):
     """
-    Returns a display-friendly path. If runtime_config['termweb_port'] is set, injects an ANSI hyperlink to the local web file viewer.
+    Returns a display-friendly path. Injects an ANSI hyperlink to a local web file viewer using a hardcoded port.
     Args:
         path (str): Path to display.
     Returns:
-        str: Display path, optionally as an ANSI hyperlink.
+        str: Display path, as an ANSI hyperlink.
     """
+    from janito.cli.config import get_termweb_port
+
+    port = get_termweb_port()
     if os.path.isabs(path):
         cwd = os.path.abspath(os.getcwd())
         abs_path = os.path.abspath(path)
@@ -21,12 +33,9 @@ def display_path(path):
             disp = path
     else:
         disp = os.path.relpath(path)
-    port = runtime_config.get("termweb_port")
-    if port:
-        url = f"http://localhost:{port}/?path={urllib.parse.quote(path)}"
-        # Use Rich markup for hyperlinks
-        return f"[link={url}]{disp}[/link]"
-    return disp
+    url = f"http://localhost:{port}/?path={urllib.parse.quote(path)}"
+    # Use Rich markup for hyperlinks
+    return f"[link={url}]{disp}[/link]"
 
 
 def pluralize(word: str, count: int) -> str:

janito/tools/tools_adapter.py

@@ -0,0 +1,207 @@
+from janito.tools.tool_base import ToolBase
+from janito.tools.tool_events import ToolCallStarted, ToolCallFinished, ToolCallError
+from janito.exceptions import ToolCallException
+from typing import Optional
+
+
+class ToolsAdapterBase:
+    """
+    Composable entry point for tools management and provisioning in LLM pipelines.
+    This class represents an external or plugin-based provider of tool definitions.
+    Extend and customize this to load, register, or serve tool implementations dynamically.
+    After refactor, also responsible for tool execution.
+    """
+
+    def __init__(
+        self, tools=None, event_bus=None, allowed_tools: Optional[list] = None
+    ):
+        self._tools = tools or []
+        self._event_bus = event_bus  # event bus can be set on all adapters
+        self._allowed_tools = set(allowed_tools) if allowed_tools is not None else None
+        self.verbose_tools = False
+
+    def set_verbose_tools(self, value: bool):
+        self.verbose_tools = value
+
+    @property
+    def event_bus(self):
+        return self._event_bus
+
+    @event_bus.setter
+    def event_bus(self, bus):
+        self._event_bus = bus
+
+    def get_tools(self):
+        """Return the list of tools managed by this provider."""
+        return self._tools
+
+    def add_tool(self, tool):
+        self._tools.append(tool)
+
+    def clear_tools(self):
+        self._tools = []
+
+    def _validate_arguments_against_schema(self, arguments: dict, schema: dict):
+        properties = schema.get("properties", {})
+        required = schema.get("required", [])
+        missing = [field for field in required if field not in arguments]
+        if missing:
+            return f"Missing required argument(s): {', '.join(missing)}"
+        type_map = {
+            "string": str,
+            "integer": int,
+            "number": (int, float),
+            "boolean": bool,
+            "array": list,
+            "object": dict,
+        }
+        for key, value in arguments.items():
+            if key not in properties:
+                continue
+            expected_type = properties[key].get("type")
+            if expected_type and expected_type in type_map:
+                if not isinstance(value, type_map[expected_type]):
+                    return f"Argument '{key}' should be of type '{expected_type}', got '{type(value).__name__}'"
+        return None
+
+    def execute(self, tool, *args, **kwargs):
+
+        if self.verbose_tools:
+            print(
+                f"[tools-adapter] [execute] Executing tool: {getattr(tool, 'tool_name', repr(tool))} with args: {args}, kwargs: {kwargs}"
+            )
+        if isinstance(tool, ToolBase):
+            tool.event_bus = self._event_bus
+        result = None
+        if callable(tool):
+            result = tool(*args, **kwargs)
+        elif hasattr(tool, "execute") and callable(getattr(tool, "execute")):
+            result = tool.execute(*args, **kwargs)
+        elif hasattr(tool, "run") and callable(getattr(tool, "run")):
+            result = tool.run(*args, **kwargs)
+        else:
+            raise ValueError("Provided tool is not executable.")
+
+        return result
+
+    def execute_by_name(
+        self, tool_name: str, *args, request_id=None, arguments=None, **kwargs
+    ):
+        self._check_tool_permissions(tool_name, request_id, arguments)
+        tool = self.get_tool(tool_name)
+        self._ensure_tool_exists(tool, tool_name, request_id, arguments)
+        schema = getattr(tool, "schema", None)
+        if schema and arguments is not None:
+            validation_error = self._validate_arguments_against_schema(
+                arguments, schema
+            )
+            if validation_error:
+                if self._event_bus:
+                    self._event_bus.publish(
+                        ToolCallError(
+                            tool_name=tool_name,
+                            request_id=request_id,
+                            error=validation_error,
+                            arguments=arguments,
+                        )
+                    )
+                return validation_error
+        if self.verbose_tools:
+            print(
+                f"[tools-adapter] Executing tool: {tool_name} with arguments: {arguments}"
+            )
+        if self._event_bus:
+            self._event_bus.publish(
+                ToolCallStarted(
+                    tool_name=tool_name, request_id=request_id, arguments=arguments
+                )
+            )
+        try:
+            result = self.execute(tool, **(arguments or {}), **kwargs)
+        except Exception as e:
+            self._handle_execution_error(tool_name, request_id, e, arguments)
+        if self.verbose_tools:
+            print(f"[tools-adapter] Tool execution finished: {tool_name} -> {result}")
+        if self._event_bus:
+            self._event_bus.publish(
+                ToolCallFinished(
+                    tool_name=tool_name, request_id=request_id, result=result
+                )
+            )
+        return result
+
+    def execute_function_call_message_part(self, function_call_message_part):
+        """
+        Execute a FunctionCallMessagePart by extracting the tool name and arguments and dispatching to execute_by_name.
+        """
+        import json
+
+        function = getattr(function_call_message_part, "function", None)
+        tool_call_id = getattr(function_call_message_part, "tool_call_id", None)
+        if function is None or not hasattr(function, "name"):
+            raise ValueError(
+                "FunctionCallMessagePart does not contain a valid function object."
+            )
+        tool_name = function.name
+        arguments = function.arguments
+        # Parse arguments if they are a JSON string
+        if isinstance(arguments, str):
+            try:
+                arguments = json.loads(arguments)
+            except Exception:
+                pass  # Leave as string if not JSON
+        if self.verbose_tools:
+            print(
+                f"[tools-adapter] Executing FunctionCallMessagePart: tool={tool_name}, arguments={arguments}, tool_call_id={tool_call_id}"
+            )
+        return self.execute_by_name(
+            tool_name, request_id=tool_call_id, arguments=arguments
+        )
+
+    def _check_tool_permissions(self, tool_name, request_id, arguments):
+        if self._allowed_tools is not None and tool_name not in self._allowed_tools:
+            error_msg = f"Tool '{tool_name}' is not permitted by adapter allow-list."
+            if self._event_bus:
+                self._event_bus.publish(
+                    ToolCallError(
+                        tool_name=tool_name,
+                        request_id=request_id,
+                        error=error_msg,
+                        arguments=arguments,
+                    )
+                )
+            raise ToolCallException(tool_name, error_msg, arguments=arguments)
+
+    def _ensure_tool_exists(self, tool, tool_name, request_id, arguments):
+        if tool is None:
+            error_msg = f"Tool '{tool_name}' not found in registry."
+            if self._event_bus:
+                self._event_bus.publish(
+                    ToolCallError(
+                        tool_name=tool_name,
+                        request_id=request_id,
+                        error=error_msg,
+                        arguments=arguments,
+                    )
+                )
+            raise ToolCallException(tool_name, error_msg, arguments=arguments)
+
+    def _handle_execution_error(self, tool_name, request_id, exception, arguments):
+        error_msg = f"Exception during execution of tool '{tool_name}': {exception}"
+        if self._event_bus:
+            self._event_bus.publish(
+                ToolCallError(
+                    tool_name=tool_name,
+                    request_id=request_id,
+                    error=error_msg,
+                    exception=exception,
+                    arguments=arguments,
+                )
+            )
+        raise ToolCallException(
+            tool_name, error_msg, arguments=arguments, exception=exception
+        )
+
+    def get_tool(self, tool_name):
+        """Abstract method: implement in subclass to return tool instance by name"""
+        raise NotImplementedError()

janito/tools/tools_schema.py

@@ -0,0 +1,104 @@
+import inspect
+import typing
+import re
+
+
+class ToolSchemaBase:
+    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):
+        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 validate_tool_class(self, tool_class):
+        if not hasattr(tool_class, "tool_name") or not isinstance(
+            tool_class.tool_name, str
+        ):
+            raise ValueError(
+                "Tool class must have a class-level 'tool_name' attribute (str) for registry and schema generation."
+            )
+        if not hasattr(tool_class, "run") or not callable(getattr(tool_class, "run")):
+            raise ValueError("Tool class must have a callable 'run' method.")
+        func = tool_class.run
+        tool_name = tool_class.tool_name
+        sig = inspect.signature(func)
+        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}"
+            )
+        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)}.\nAll parameters must have explicit type hints for schema generation."
+            )
+        class_doc = (
+            tool_class.__doc__.strip() if tool_class and tool_class.__doc__ else ""
+        )
+        summary, param_descs, return_desc = self.parse_docstring(class_doc)
+        description = summary
+        if return_desc:
+            description += f"\n\nReturns: {return_desc}"
+        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)}.\nParameter documentation must be provided in the Tool class docstring, not the method docstring."
+            )
+        return func, tool_name, sig, summary, param_descs, return_desc, description

janito/utils.py

@@ -0,0 +1,11 @@
+import inspect
+
+
+def kwargs_from_locals(*names):
+    """
+    Return a dict of {name: value} for each name from the caller's local scope.
+    Usage:
+        event = GenerationStarted(**kwargs_from_locals('driver_name', 'request_id', 'conversation_history'))
+    """
+    frame = inspect.currentframe().f_back
+    return {name: frame.f_locals[name] for name in names}

janito/version.py

@@ -0,0 +1,4 @@
+# janito/version.py
+"""Single source of truth for the janito package version."""
+
+__version__ = "2.0.0"