llms-py 3.0.10__py3-none-any.whl → 3.0.18__py3-none-any.whl

llms/main.py

@@ -18,17 +18,33 @@ import mimetypes
 import os
 import re
 import secrets
+import shlex
 import shutil
 import site
 import subprocess
 import sys
+import tempfile
 import time
 import traceback
 from datetime import datetime
+from enum import Enum, IntEnum
 from importlib import resources  # Py≥3.9  (pip install importlib_resources for 3.7/3.8)
 from io import BytesIO
 from pathlib import Path
-from typing import Optional, get_type_hints
+from typing import (
+    Annotated,
+    Any,
+    Callable,
+    Dict,
+    List,
+    Literal,
+    Optional,
+    Tuple,
+    Union,
+    get_args,
+    get_origin,
+    get_type_hints,
+)
 from urllib.parse import parse_qs, urlencode, urljoin
 
 import aiohttp
@@ -41,7 +57,7 @@ try:
 except ImportError:
     HAS_PIL = False
 
-VERSION = "3.0.10"
+VERSION = "3.0.18"
 _ROOT = None
 DEBUG = os.getenv("DEBUG") == "1"
 MOCK = os.getenv("MOCK") == "1"
@@ -59,6 +75,12 @@ g_oauth_states = {}  # CSRF protection: {state: {created, redirect_uri}}
 g_app = None  # ExtensionsContext Singleton
 
 
+class ExitCode(IntEnum):
+    SUCCESS = 0
+    FAILED = 1
+    UNHANDLED = 9
+
+
 def _log(message):
     if g_verbose:
         print(f"{g_logprefix}{message}", flush=True)
@@ -340,22 +362,102 @@ def to_content(result):
         return str(result)
 
 
+def get_literal_values(typ):
+    """Recursively extract values from Literal and Union types."""
+    origin = get_origin(typ)
+    if origin is Literal:
+        return list(get_args(typ))
+    elif origin is Union:
+        values = []
+        for arg in get_args(typ):
+            # Recurse for nested Unions or Literals
+            nested_values = get_literal_values(arg)
+            if nested_values:
+                for v in nested_values:
+                    if v not in values:
+                        values.append(v)
+        return values
+    return None
+
+
+def _py_type_to_json_type(param_type):
+    param_type_name = "string"
+    enum_values = None
+    items = None
+
+    # Check for Enum
+    if inspect.isclass(param_type) and issubclass(param_type, Enum):
+        enum_values = [e.value for e in param_type]
+    elif get_origin(param_type) is list or get_origin(param_type) is list:
+        param_type_name = "array"
+        args = get_args(param_type)
+        if args:
+            items_type, _, _ = _py_type_to_json_type(args[0])
+            items = {"type": items_type}
+    elif get_origin(param_type) is dict:
+        param_type_name = "object"
+    else:
+        # Check for Literal / Union[Literal]
+        enum_values = get_literal_values(param_type)
+
+    if enum_values:
+        # Infer type from the first value
+        value_type = type(enum_values[0])
+        if value_type is int:
+            param_type_name = "integer"
+        elif value_type is float:
+            param_type_name = "number"
+        elif value_type is bool:
+            param_type_name = "boolean"
+
+    elif param_type is int:
+        param_type_name = "integer"
+    elif param_type is float:
+        param_type_name = "number"
+    elif param_type is bool:
+        param_type_name = "boolean"
+
+    return param_type_name, enum_values, items
+
+
 def function_to_tool_definition(func):
-    type_hints = get_type_hints(func)
+    type_hints = get_type_hints(func, include_extras=True)
     signature = inspect.signature(func)
     parameters = {"type": "object", "properties": {}, "required": []}
 
     for name, param in signature.parameters.items():
         param_type = type_hints.get(name, str)
-        param_type_name = "string"
-        if param_type is int:
-            param_type_name = "integer"
-        elif param_type is float:
-            param_type_name = "number"
-        elif param_type is bool:
-            param_type_name = "boolean"
+        description = None
+
+        # Check for Annotated (for description)
+        if get_origin(param_type) is Annotated:
+            args = get_args(param_type)
+            param_type = args[0]
+            for arg in args[1:]:
+                if isinstance(arg, str):
+                    description = arg
+                    break
+
+        # Unwrap Optional / Union[T, None]
+        origin = get_origin(param_type)
+        if origin is Union:
+            args = get_args(param_type)
+            # Filter out NoneType
+            non_none_args = [arg for arg in args if arg is not type(None)]
+            if len(non_none_args) == 1:
+                param_type = non_none_args[0]
+
+        param_type_name, enum_values, items = _py_type_to_json_type(param_type)
+
+        prop = {"type": param_type_name}
+        if description:
+            prop["description"] = description
+        if enum_values:
+            prop["enum"] = enum_values
+        if items:
+            prop["items"] = items
+        parameters["properties"][name] = prop
 
-        parameters["properties"][name] = {"type": param_type_name}
         if param.default == inspect.Parameter.empty:
             parameters["required"].append(name)
 
@@ -363,7 +465,7 @@ def function_to_tool_definition(func):
         "type": "function",
         "function": {
             "name": func.__name__,
-            "description": func.__doc__ or "",
+            "description": (func.__doc__ or "").strip(),
             "parameters": parameters,
         },
     }
@@ -783,7 +885,7 @@ def chat_to_prompt(chat):
     prompt = ""
     if "messages" in chat:
         for message in chat["messages"]:
-            if message["role"] == "user":
+            if message.get("role") == "user":
                 # if content is string
                 if isinstance(message["content"], str):
                     if prompt:
@@ -802,7 +904,7 @@ def chat_to_prompt(chat):
 def chat_to_system_prompt(chat):
     if "messages" in chat:
         for message in chat["messages"]:
-            if message["role"] == "system":
+            if message.get("role") == "system":
                 # if content is string
                 if isinstance(message["content"], str):
                     return message["content"]
@@ -830,7 +932,7 @@ def last_user_prompt(chat):
     prompt = ""
     if "messages" in chat:
         for message in chat["messages"]:
-            if message["role"] == "user":
+            if message.get("role") == "user":
                 # if content is string
                 if isinstance(message["content"], str):
                     prompt = message["content"]
@@ -1114,8 +1216,8 @@ class OpenAiCompatible:
     def chat_summary(self, chat):
         return chat_summary(chat)
 
-    def process_chat(self, chat, provider_id=None):
-        return process_chat(chat, provider_id)
+    async def process_chat(self, chat, provider_id=None):
+        return await process_chat(chat, provider_id)
 
     async def chat(self, chat, context=None):
         chat["model"] = self.provider_model(chat["model"]) or chat["model"]
@@ -1170,7 +1272,7 @@ class OpenAiCompatible:
         if self.enable_thinking is not None:
             chat["enable_thinking"] = self.enable_thinking
 
-        chat = await process_chat(chat, provider_id=self.id)
+        chat = await self.process_chat(chat, provider_id=self.id)
         _log(f"POST {self.chat_url}")
         _log(chat_summary(chat))
         # remove metadata if any (conflicts with some providers, e.g. Z.ai)
@@ -1202,6 +1304,15 @@ class GroqProvider(OpenAiCompatible):
             kwargs["api"] = "https://api.groq.com/openai/v1"
         super().__init__(**kwargs)
 
+    async def process_chat(self, chat, provider_id=None):
+        ret = await process_chat(chat, provider_id)
+        chat.pop("modalities", None)  # groq doesn't support modalities
+        messages = chat.get("messages", []).copy()
+        for message in messages:
+            message.pop("timestamp", None)  # groq doesn't support timestamp
+        ret["messages"] = messages
+        return ret
+
 
 class XaiProvider(OpenAiCompatible):
     sdk = "@ai-sdk/xai"
@@ -1505,6 +1616,7 @@ def g_tool_result(result, function_name: Optional[str] = None, function_args: Op
     content = []
     resources = []
     args = function_args or {}
+    _dbg(f"{function_name} tool result type: {type(result)}")
     if isinstance(result, dict):
         text, res = tool_result_part(result, function_name, args)
         if text:
@@ -1525,9 +1637,118 @@ def g_tool_result(result, function_name: Optional[str] = None, function_args: Op
     return text, resources
 
 
+def convert_tool_args(function_name, function_args):
+    """
+    Convert tool arg values to their specified types.
+    types: string, number, integer, boolean, object, array, null
+    example prop_def = [
+        {
+            "type": "string"
+        },
+        {
+            "default": "name",
+            "type": "string",
+            "enum": ["name", "size"]
+        },
+        {
+            "default": [],
+            "type": "array",
+            "items": {
+                "type": "string"
+            }
+        },
+        {
+            "anyOf": [
+                {
+                    "type": "string"
+                },
+                {
+                    "type": "null"
+                }
+            ],
+            "default": null,
+        },
+    ]
+    """
+    tool_def = g_app.get_tool_definition(function_name)
+    if not tool_def:
+        return function_args
+
+    if "function" in tool_def and "parameters" in tool_def["function"]:
+        parameters = tool_def.get("function", {}).get("parameters")
+        properties = parameters.get("properties", {})
+        required = parameters.get("required", [])
+        new_args = function_args.copy()
+
+        for key, value in function_args.items():
+            if key in properties and isinstance(value, str):
+                prop_type = properties[key].get("type")
+                str_val = value.strip()
+
+                if str_val == "":
+                    if prop_type in ("integer", "number"):
+                        new_args[key] = None
+                    else:
+                        new_args.pop(key)
+                    continue
+
+                if prop_type == "integer":
+                    with contextlib.suppress(ValueError, TypeError):
+                        new_args[key] = int(str_val)
+
+                elif prop_type == "number":
+                    with contextlib.suppress(ValueError, TypeError):
+                        new_args[key] = float(str_val)
+
+                elif prop_type == "boolean":
+                    lower_val = str_val.lower()
+                    if lower_val in ("true", "1", "yes"):
+                        new_args[key] = True
+                    elif lower_val in ("false", "0", "no"):
+                        new_args[key] = False
+
+                elif prop_type == "object":
+                    if str_val == "":
+                        new_args[key] = None
+                    else:
+                        with contextlib.suppress(json.JSONDecodeError, TypeError):
+                            new_args[key] = json.loads(str_val)
+
+                elif prop_type == "array":
+                    if str_val == "":
+                        new_args[key] = []
+                    else:
+                        # Simple CSV split for arrays; could be more robust with JSON parsing if wrapped in brackets
+                        # Check if it looks like a JSON array
+                        if str_val.startswith("[") and str_val.endswith("]"):
+                            with contextlib.suppress(json.JSONDecodeError):
+                                items = json.loads(str_val)
+                        else:
+                            items = [s.strip() for s in str_val.split(",")]
+                        item_type = properties[key].get("items", {}).get("type")
+                        if item_type == "integer":
+                            items = [int(i) for i in items]
+                        elif item_type == "number":
+                            items = [float(i) for i in items]
+                        new_args[key] = items
+
+        # Validate required parameters
+        missing = [key for key in required if key not in new_args]
+        if missing:
+            raise ValueError(f"Missing required arguments: {', '.join(missing)}")
+
+        return new_args
+
+    return function_args
+
+
 async def g_exec_tool(function_name, function_args):
+    _log(f"g_exec_tool: {function_name}")
     if function_name in g_app.tools:
         try:
+            # Type conversion based on tool definition
+            function_args = convert_tool_args(function_name, function_args)
+
             func = g_app.tools[function_name]
             is_async = inspect.iscoroutinefunction(func)
             _dbg(f"Executing {'async' if is_async else 'sync'} tool '{function_name}' with args: {function_args}")
@@ -1536,7 +1757,7 @@ async def g_exec_tool(function_name, function_args):
             else:
                 return g_tool_result(func(**function_args), function_name, function_args)
         except Exception as e:
-            return f"Error executing tool '{function_name}': {to_error_message(e)}", None
+            return f"Error executing tool '{function_name}':\n{to_error_message(e)}", None
     return f"Error: Tool '{function_name}' not found", None
 
 
@@ -1547,7 +1768,7 @@ def group_resources(resources: list):
     {"images": [{"type": "image_url", "image_url": {"url": "/image.jpg"}}] }
     """
     grouped = {}
-    for res in resources:
+    for res in resources or []:
         type = res.get("type")
         if not type:
             continue
@@ -1576,6 +1797,9 @@ async def g_chat_completion(chat, context=None):
         if context is None:
             context = {"chat": chat, "tools": "all"}
 
+        if "request_id" not in context:
+            context["request_id"] = str(int(time.time() * 1000))
+
         # get first provider that has the model
         candidate_providers = [name for name, provider in g_handlers.items() if provider.provider_model(model)]
         if len(candidate_providers) == 0:
@@ -1620,10 +1844,15 @@ async def g_chat_completion(chat, context=None):
             tool_history = []
             final_response = None
 
-            for _ in range(max_iterations):
+            for request_count in range(max_iterations):
                 if should_cancel_thread(context):
                     return
 
+                if DEBUG:
+                    messages = current_chat.get("messages", [])
+                    last_message = messages[-1] if messages else None
+                    _dbg(f"Provider {provider_name}, request {request_count}:\n{json.dumps(last_message, indent=2)}")
+
                 response = await provider.chat(current_chat, context=context)
 
                 if should_cancel_thread(context):
@@ -1722,7 +1951,12 @@ async def g_chat_completion(chat, context=None):
             continue
 
     # If we get here, all providers failed
-    raise first_exception
+    if first_exception:
+        raise first_exception
+
+    e = Exception("All providers failed")
+    await g_app.on_chat_error(e, context or {"chat": chat})
+    raise e
 
 
 async def cli_chat(chat, tools=None, image=None, audio=None, file=None, args=None, raw=False):
@@ -1853,12 +2087,18 @@ def config_str(key):
     return key in g_config and g_config[key] or None
 
 
-def load_config(config, providers, verbose=None):
+def load_config(config, providers, verbose=None, debug=None, disable_extensions: List[str] = None):
     global g_config, g_providers, g_verbose
     g_config = config
     g_providers = providers
-    if verbose:
+    if verbose is not None:
         g_verbose = verbose
+    if debug is not None:
+        global DEBUG
+        DEBUG = debug
+    if disable_extensions:
+        global DISABLE_EXTENSIONS
+        DISABLE_EXTENSIONS = disable_extensions
 
 
 def init_llms(config, providers):
@@ -2539,7 +2779,7 @@ class AppExtensions:
     APIs extensions can use to extend the app
     """
 
-    def __init__(self, cli_args, extra_args):
+    def __init__(self, cli_args: argparse.Namespace, extra_args: Dict[str, Any]):
         self.cli_args = cli_args
         self.extra_args = extra_args
         self.config = None
@@ -2563,6 +2803,7 @@ class AppExtensions:
         self.tool_groups = {}
         self.index_headers = []
         self.index_footers = []
+        self.allowed_directories = []
         self.request_args = {
             "image_config": dict,  # e.g. { "aspect_ratio": "1:1" }
             "temperature": float,  # e.g: 0.7
@@ -2615,12 +2856,28 @@ class AppExtensions:
             "ctx.mjs": "/ui/ctx.mjs",
         }
 
-    def set_config(self, config):
+    def set_config(self, config: Dict[str, Any]):
         self.config = config
         self.auth_enabled = self.config.get("auth", {}).get("enabled", False)
 
+    def set_allowed_directories(
+        self, directories: List[Annotated[str, "List of absolute paths that are allowed to be accessed."]]
+    ) -> None:
+        """Set the list of allowed directories."""
+        self.allowed_directories = [os.path.abspath(d) for d in directories]
+
+    def add_allowed_directory(self, path: str) -> None:
+        """Add an allowed directory."""
+        abs_path = os.path.abspath(path)
+        if abs_path not in self.allowed_directories:
+            self.allowed_directories.append(abs_path)
+
+    def get_allowed_directories(self) -> List[str]:
+        """Get the list of allowed directories."""
+        return self.allowed_directories
+
     # Authentication middleware helper
-    def check_auth(self, request):
+    def check_auth(self, request: web.Request) -> Tuple[bool, Optional[Dict[str, Any]]]:
         """Check if request is authenticated. Returns (is_authenticated, user_data)"""
         if not self.auth_enabled:
             return True, None
@@ -2639,7 +2896,7 @@ class AppExtensions:
 
         return False, None
 
-    def get_session(self, request):
+    def get_session(self, request: web.Request) -> Optional[Dict[str, Any]]:
         session_token = get_session_token(request)
 
         if not session_token or session_token not in g_sessions:
@@ -2648,58 +2905,71 @@ class AppExtensions:
         session_data = g_sessions[session_token]
         return session_data
 
-    def get_username(self, request):
+    def get_username(self, request: web.Request) -> Optional[str]:
         session = self.get_session(request)
         if session:
             return session.get("userName")
         return None
 
-    def get_user_path(self, username=None):
+    def get_user_path(self, username: Optional[str] = None) -> str:
         if username:
             return home_llms_path(os.path.join("user", username))
         return home_llms_path(os.path.join("user", "default"))
 
-    def chat_request(self, template=None, text=None, model=None, system_prompt=None):
+    def get_providers(self) -> Dict[str, Any]:
+        return g_handlers
+
+    def chat_request(
+        self,
+        template: Optional[str] = None,
+        text: Optional[str] = None,
+        model: Optional[str] = None,
+        system_prompt: Optional[str] = None,
+    ) -> Dict[str, Any]:
         return g_chat_request(template=template, text=text, model=model, system_prompt=system_prompt)
 
-    async def chat_completion(self, chat, context=None):
+    async def chat_completion(self, chat: Dict[str, Any], context: Optional[Dict[str, Any]] = None) -> Any:
         response = await g_chat_completion(chat, context)
         return response
 
-    def on_cache_saved_filters(self, context):
+    def on_cache_saved_filters(self, context: Dict[str, Any]):
         # _log(f"on_cache_saved_filters {len(self.cache_saved_filters)}: {context['url']}")
         for filter_func in self.cache_saved_filters:
             filter_func(context)
 
-    async def on_chat_error(self, e, context):
+    async def on_chat_error(self, e: Exception, context: Dict[str, Any]):
         # Apply chat error filters
         if "stackTrace" not in context:
             context["stackTrace"] = traceback.format_exc()
         for filter_func in self.chat_error_filters:
             try:
-                await filter_func(e, context)
+                task = filter_func(e, context)
+                if asyncio.isfuture(task):
+                    await task
             except Exception as e:
                 _err("chat error filter failed", e)
 
-    async def on_chat_tool(self, chat, context):
+    async def on_chat_tool(self, chat: Dict[str, Any], context: Dict[str, Any]):
         m_len = len(chat.get("messages", []))
         t_len = len(self.chat_tool_filters)
         _dbg(
-            f"on_tool_call for thread {context.get('threadId', None)} with {m_len} {pluralize('message', m_len)}, invoking {t_len} {pluralize('filter', t_len)}:"
+            f"on_tool_call for thread {context.get('threadId')} with {m_len} {pluralize('message', m_len)}, invoking {t_len} {pluralize('filter', t_len)}:"
         )
         for filter_func in self.chat_tool_filters:
             await filter_func(chat, context)
 
-    def exit(self, exit_code=0):
+    def shutdown(self):
         if len(self.shutdown_handlers) > 0:
             _dbg(f"running {len(self.shutdown_handlers)} shutdown handlers...")
             for handler in self.shutdown_handlers:
                 handler()
 
+    def exit(self, exit_code: int = 0):
+        self.shutdown()
         _dbg(f"exit({exit_code})")
         sys.exit(exit_code)
 
-    def create_chat_with_tools(self, chat, use_tools="all"):
+    def create_chat_with_tools(self, chat: Dict[str, Any], use_tools: str = "all") -> Dict[str, Any]:
         # Inject global tools if present
         current_chat = chat.copy()
         tools = current_chat.get("tools")
@@ -2713,6 +2983,11 @@ class AppExtensions:
                 if "tools" not in current_chat:
                     current_chat["tools"] = []
 
+                _dbg(
+                    f"create_chat_with_tools: all_tools:{include_all_tools}, only_tools:{only_tools_list}, chat tools: "
+                    + str(len(current_chat["tools"]))
+                )
+
                 existing_tools = {t["function"]["name"] for t in current_chat["tools"]}
                 for tool_def in self.tool_definitions:
                     name = tool_def["function"]["name"]
@@ -2720,6 +2995,12 @@ class AppExtensions:
                         current_chat["tools"].append(tool_def)
         return current_chat
 
+    def get_tool_definition(self, name: str) -> Optional[Dict[str, Any]]:
+        for tool_def in self.tool_definitions:
+            if tool_def["function"]["name"] == name:
+                return tool_def
+        return None
+
 
 def handler_name(handler):
     if hasattr(handler, "__name__"):
@@ -2728,7 +3009,7 @@ def handler_name(handler):
 
 
 class ExtensionContext:
-    def __init__(self, app, path):
+    def __init__(self, app: AppExtensions, path: str):
         self.app = app
         self.cli_args = app.cli_args
         self.extra_args = app.extra_args
@@ -2746,101 +3027,121 @@ class ExtensionContext:
         self.request_args = app.request_args
         self.disabled = False
 
-    def chat_to_prompt(self, chat):
+    def set_allowed_directories(
+        self, directories: List[Annotated[str, "List of absolute paths that are allowed to be accessed."]]
+    ) -> None:
+        """Set the list of allowed directories."""
+        self.app.set_allowed_directories(directories)
+
+    def add_allowed_directory(self, path: str) -> None:
+        """Add an allowed directory."""
+        self.app.add_allowed_directory(path)
+
+    def get_allowed_directories(self) -> List[str]:
+        """Get the list of allowed directories."""
+        return self.app.get_allowed_directories()
+
+    def chat_to_prompt(self, chat: Dict[str, Any]) -> str:
         return chat_to_prompt(chat)
 
-    def chat_to_system_prompt(self, chat):
+    def chat_to_system_prompt(self, chat: Dict[str, Any]) -> str:
         return chat_to_system_prompt(chat)
 
-    def chat_response_to_message(self, response):
+    def chat_response_to_message(self, response: Dict[str, Any]) -> Dict[str, Any]:
         return chat_response_to_message(response)
 
-    def last_user_prompt(self, chat):
+    def last_user_prompt(self, chat: Dict[str, Any]) -> str:
         return last_user_prompt(chat)
 
-    def to_file_info(self, chat, info=None, response=None):
+    def to_file_info(
+        self, chat: Dict[str, Any], info: Optional[Dict[str, Any]] = None, response: Optional[Dict[str, Any]] = None
+    ) -> Dict[str, Any]:
         return to_file_info(chat, info=info, response=response)
 
-    def save_image_to_cache(self, base64_data, filename, image_info, ignore_info=False):
+    def save_image_to_cache(
+        self, base64_data: Union[str, bytes], filename: str, image_info: Dict[str, Any], ignore_info: bool = False
+    ) -> Tuple[str, Optional[Dict[str, Any]]]:
         return save_image_to_cache(base64_data, filename, image_info, ignore_info=ignore_info)
 
-    def save_bytes_to_cache(self, bytes_data, filename, file_info):
+    def save_bytes_to_cache(
+        self, bytes_data: Union[str, bytes], filename: str, file_info: Optional[Dict[str, Any]]
+    ) -> Tuple[str, Optional[Dict[str, Any]]]:
         return save_bytes_to_cache(bytes_data, filename, file_info)
 
-    def text_from_file(self, path):
+    def text_from_file(self, path: str) -> str:
         return text_from_file(path)
 
-    def json_from_file(self, path):
+    def json_from_file(self, path: str) -> Any:
         return json_from_file(path)
 
-    def download_file(self, url):
+    def download_file(self, url: str) -> Tuple[bytes, Dict[str, Any]]:
         return download_file(url)
 
-    def session_download_file(self, session, url):
+    def session_download_file(self, session: aiohttp.ClientSession, url: str) -> Tuple[bytes, Dict[str, Any]]:
         return session_download_file(session, url)
 
-    def read_binary_file(self, url):
+    def read_binary_file(self, url: str) -> Tuple[bytes, Dict[str, Any]]:
         return read_binary_file(url)
 
-    def log(self, message):
+    def log(self, message: Any):
         if self.verbose:
             print(f"[{self.name}] {message}", flush=True)
         return message
 
-    def log_json(self, obj):
+    def log_json(self, obj: Any):
         if self.verbose:
             print(f"[{self.name}] {json.dumps(obj, indent=2)}", flush=True)
         return obj
 
-    def dbg(self, message):
+    def dbg(self, message: Any):
         if self.debug:
             print(f"DEBUG [{self.name}]: {message}", flush=True)
 
-    def err(self, message, e):
+    def err(self, message: str, e: Exception):
         print(f"ERROR [{self.name}]: {message}", e)
         if self.verbose:
             print(traceback.format_exc(), flush=True)
 
-    def error_message(self, e):
+    def error_message(self, e: Exception) -> str:
         return to_error_message(e)
 
-    def error_response(self, e, stacktrace=False):
+    def error_response(self, e: Exception, stacktrace: bool = False) -> Dict[str, Any]:
         return to_error_response(e, stacktrace=stacktrace)
 
-    def add_provider(self, provider):
+    def add_provider(self, provider: Any):
         self.log(f"Registered provider: {provider.__name__}")
         self.app.all_providers.append(provider)
 
-    def register_ui_extension(self, index):
+    def register_ui_extension(self, index: str):
         path = os.path.join(self.ext_prefix, index)
         self.log(f"Registered UI extension: {path}")
         self.app.ui_extensions.append({"id": self.name, "path": path})
 
-    def register_chat_request_filter(self, handler):
+    def register_chat_request_filter(self, handler: Callable):
         self.log(f"Registered chat request filter: {handler_name(handler)}")
         self.app.chat_request_filters.append(handler)
 
-    def register_chat_tool_filter(self, handler):
+    def register_chat_tool_filter(self, handler: Callable):
         self.log(f"Registered chat tool filter: {handler_name(handler)}")
         self.app.chat_tool_filters.append(handler)
 
-    def register_chat_response_filter(self, handler):
+    def register_chat_response_filter(self, handler: Callable):
         self.log(f"Registered chat response filter: {handler_name(handler)}")
         self.app.chat_response_filters.append(handler)
 
-    def register_chat_error_filter(self, handler):
+    def register_chat_error_filter(self, handler: Callable):
         self.log(f"Registered chat error filter: {handler_name(handler)}")
         self.app.chat_error_filters.append(handler)
 
-    def register_cache_saved_filter(self, handler):
+    def register_cache_saved_filter(self, handler: Callable):
         self.log(f"Registered cache saved filter: {handler_name(handler)}")
         self.app.cache_saved_filters.append(handler)
 
-    def register_shutdown_handler(self, handler):
+    def register_shutdown_handler(self, handler: Callable):
         self.log(f"Registered shutdown handler: {handler_name(handler)}")
         self.app.shutdown_handlers.append(handler)
 
-    def add_static_files(self, ext_dir):
+    def add_static_files(self, ext_dir: str):
         self.log(f"Registered static files: {ext_dir}")
 
         async def serve_static(request):
@@ -2852,57 +3153,66 @@ class ExtensionContext:
 
         self.app.server_add_get.append((os.path.join(self.ext_prefix, "{path:.*}"), serve_static, {}))
 
-    def web_path(self, method, path):
+    def web_path(self, method: str, path: str) -> str:
         full_path = os.path.join(self.ext_prefix, path) if path else self.ext_prefix
         self.dbg(f"Registered {method:<6} {full_path}")
         return full_path
 
-    def add_get(self, path, handler, **kwargs):
+    def add_get(self, path: str, handler: Callable, **kwargs: Any):
         self.app.server_add_get.append((self.web_path("GET", path), handler, kwargs))
 
-    def add_post(self, path, handler, **kwargs):
+    def add_post(self, path: str, handler: Callable, **kwargs: Any):
         self.app.server_add_post.append((self.web_path("POST", path), handler, kwargs))
 
-    def add_put(self, path, handler, **kwargs):
+    def add_put(self, path: str, handler: Callable, **kwargs: Any):
         self.app.server_add_put.append((self.web_path("PUT", path), handler, kwargs))
 
-    def add_delete(self, path, handler, **kwargs):
+    def add_delete(self, path: str, handler: Callable, **kwargs: Any):
         self.app.server_add_delete.append((self.web_path("DELETE", path), handler, kwargs))
 
-    def add_patch(self, path, handler, **kwargs):
+    def add_patch(self, path: str, handler: Callable, **kwargs: Any):
         self.app.server_add_patch.append((self.web_path("PATCH", path), handler, kwargs))
 
-    def add_importmaps(self, dict):
+    def add_importmaps(self, dict: Dict[str, str]):
         self.app.import_maps.update(dict)
 
-    def add_index_header(self, html):
+    def add_index_header(self, html: str):
         self.app.index_headers.append(html)
 
-    def add_index_footer(self, html):
+    def add_index_footer(self, html: str):
         self.app.index_footers.append(html)
 
-    def get_config(self):
+    def get_home_path(self, name: str = "") -> str:
+        return home_llms_path(name)
+
+    def get_config(self) -> Optional[Dict[str, Any]]:
         return g_config
 
-    def get_cache_path(self, path=""):
+    def get_cache_path(self, path: str = "") -> str:
         return get_cache_path(path)
 
-    def get_file_mime_type(self, filename):
+    def get_file_mime_type(self, filename: str) -> str:
         return get_file_mime_type(filename)
 
-    def chat_request(self, template=None, text=None, model=None, system_prompt=None):
+    def chat_request(
+        self,
+        template: Optional[str] = None,
+        text: Optional[str] = None,
+        model: Optional[str] = None,
+        system_prompt: Optional[str] = None,
+    ) -> Dict[str, Any]:
         return self.app.chat_request(template=template, text=text, model=model, system_prompt=system_prompt)
 
-    def chat_completion(self, chat, context=None):
-        return self.app.chat_completion(chat, context=context)
+    async def chat_completion(self, chat: Dict[str, Any], context: Optional[Dict[str, Any]] = None) -> Any:
+        return await self.app.chat_completion(chat, context=context)
 
-    def get_providers(self):
+    def get_providers(self) -> Dict[str, Any]:
         return g_handlers
 
-    def get_provider(self, name):
+    def get_provider(self, name: str) -> Optional[Any]:
         return g_handlers.get(name)
 
-    def sanitize_tool_def(self, tool_def):
+    def sanitize_tool_def(self, tool_def: Dict[str, Any]) -> Dict[str, Any]:
         """
         Merge $defs parameter into tool_def property to reduce client/server complexity
         """
@@ -2942,7 +3252,7 @@ class ExtensionContext:
             parameters = func_def.get("parameters", {})
             defs = parameters.get("$defs", {})
             properties = parameters.get("properties", {})
-            for prop_name, prop_def in properties.items():
+            for _, prop_def in properties.items():
                 if "$ref" in prop_def:
                     ref = prop_def["$ref"]
                     if ref.startswith("#/$defs/"):
@@ -2954,7 +3264,7 @@ class ExtensionContext:
                 del parameters["$defs"]
         return tool_def
 
-    def register_tool(self, func, tool_def=None, group=None):
+    def register_tool(self, func: Callable, tool_def: Optional[Dict[str, Any]] = None, group: Optional[str] = None):
         if tool_def is None:
             tool_def = function_to_tool_definition(func)
 
@@ -2976,54 +3286,58 @@ class ExtensionContext:
             self.app.tool_groups[group] = []
         self.app.tool_groups[group].append(name)
 
-    def get_tool_definition(self, name):
-        for tool_def in self.app.tool_definitions:
-            if tool_def["function"]["name"] == name:
-                return tool_def
-        return None
+    def get_tool_definition(self, name: str) -> Optional[Dict[str, Any]]:
+        return self.app.get_tool_definition(name)
 
-    def group_resources(self, resources: list):
+    def group_resources(self, resources: List[Dict[str, Any]]) -> Dict[str, List[Dict[str, Any]]]:
         return group_resources(resources)
 
-    def check_auth(self, request):
+    def check_auth(self, request: web.Request) -> Tuple[bool, Optional[Dict[str, Any]]]:
         return self.app.check_auth(request)
 
-    def get_session(self, request):
+    def get_session(self, request: web.Request) -> Optional[Dict[str, Any]]:
         return self.app.get_session(request)
 
-    def get_username(self, request):
+    def get_username(self, request: web.Request) -> Optional[str]:
         return self.app.get_username(request)
 
-    def get_user_path(self, username=None):
+    def get_user_path(self, username: Optional[str] = None) -> str:
         return self.app.get_user_path(username)
 
-    def context_to_username(self, context):
+    def context_to_username(self, context: Optional[Dict[str, Any]]) -> Optional[str]:
         if context and "request" in context:
             return self.get_username(context["request"])
         return None
 
-    def should_cancel_thread(self, context):
+    def should_cancel_thread(self, context: Dict[str, Any]) -> bool:
         return should_cancel_thread(context)
 
-    def cache_message_inline_data(self, message):
+    def cache_message_inline_data(self, message: Dict[str, Any]):
         return cache_message_inline_data(message)
 
-    async def exec_tool(self, name, args):
+    async def exec_tool(self, name: str, args: Dict[str, Any]) -> Tuple[Optional[str], List[Dict[str, Any]]]:
         return await g_exec_tool(name, args)
 
-    def tool_result(self, result, function_name: Optional[str] = None, function_args: Optional[dict] = None):
+    def tool_result(
+        self, result: Any, function_name: Optional[str] = None, function_args: Optional[Dict[str, Any]] = None
+    ) -> Dict[str, Any]:
         return g_tool_result(result, function_name, function_args)
 
-    def tool_result_part(self, result: dict, function_name: Optional[str] = None, function_args: Optional[dict] = None):
+    def tool_result_part(
+        self,
+        result: Dict[str, Any],
+        function_name: Optional[str] = None,
+        function_args: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
         return tool_result_part(result, function_name, function_args)
 
-    def to_content(self, result):
+    def to_content(self, result: Any) -> str:
         return to_content(result)
 
-    def create_chat_with_tools(self, chat, use_tools="all"):
+    def create_chat_with_tools(self, chat: Dict[str, Any], use_tools: str = "all") -> Dict[str, Any]:
         return self.app.create_chat_with_tools(chat, use_tools)
 
-    def chat_to_aspect_ratio(self, chat):
+    def chat_to_aspect_ratio(self, chat: Dict[str, Any]) -> str:
         return chat_to_aspect_ratio(chat)
 
 
@@ -3080,7 +3394,21 @@ def get_extensions_dirs():
     return ret
 
 
+def verify_root_path():
+    global _ROOT
+    _ROOT = os.getenv("LLMS_ROOT", resolve_root())
+    if not _ROOT:
+        print("Resource root not found")
+        exit(1)
+
+
 def init_extensions(parser):
+    """
+    Programmatic entry point for the CLI.
+    Example: cli("ls minimax")
+    """
+    verify_root_path()
+
     """
     Initializes extensions by loading their __init__.py files and calling the __parser__ function if it exists.
     """
@@ -3235,14 +3563,7 @@ def run_extension_cli():
                     return False
 
 
-def main():
-    global _ROOT, g_verbose, g_default_model, g_logprefix, g_providers, g_config, g_config_path, g_app
-
-    _ROOT = os.getenv("LLMS_ROOT", resolve_root())
-    if not _ROOT:
-        print("Resource root not found")
-        exit(1)
-
+def create_arg_parser():
     parser = argparse.ArgumentParser(description=f"llms v{VERSION}")
     parser.add_argument("--config", default=None, help="Path to config file", metavar="FILE")
     parser.add_argument("--providers", default=None, help="Path to models.dev providers file", metavar="FILE")
@@ -3311,11 +3632,13 @@ def main():
         help="Update an extension (use 'all' to update all extensions)",
         metavar="EXTENSION",
     )
+    return parser
 
-    # Load parser extensions, go through all extensions and load their parser arguments
-    init_extensions(parser)
 
-    cli_args, extra_args = parser.parse_known_args()
+def cli_exec(cli_args, extra_args):
+    global _ROOT, g_verbose, g_default_model, g_logprefix, g_providers, g_config, g_config_path, g_app
+
+    verify_root_path()
 
     g_app = AppExtensions(cli_args, extra_args)
 
@@ -3351,12 +3674,12 @@ def main():
         else:
             asyncio.run(save_text_url(github_url("providers-extra.json"), home_providers_extra_path))
             print(f"Created default extra providers config at {home_providers_extra_path}")
-        exit(0)
+        return ExitCode.SUCCESS
 
     if cli_args.providers:
         if not os.path.exists(cli_args.providers):
             print(f"providers.json not found at {cli_args.providers}")
-            exit(1)
+            return ExitCode.FAILED
         g_providers = json.loads(text_from_file(cli_args.providers))
 
     if cli_args.config:
@@ -3385,7 +3708,7 @@ def main():
     if cli_args.update_providers:
         asyncio.run(update_providers(home_providers_path))
         print(f"Updated {home_providers_path}")
-        exit(0)
+        return ExitCode.SUCCESS
 
     # if home_providers_path is older than 1 day, update providers list
     if (
@@ -3418,7 +3741,7 @@ def main():
                 print("  llms --add <github-user>/<repo>")
 
             asyncio.run(list_extensions())
-            exit(0)
+            return ExitCode.SUCCESS
 
         async def install_extension(name):
             # Determine git URL and target directory name
@@ -3481,7 +3804,7 @@ def main():
                     os.rmdir(target_path)
 
         asyncio.run(install_extension(cli_args.add))
-        exit(0)
+        return ExitCode.SUCCESS
 
     if cli_args.remove is not None:
         if cli_args.remove == "ls":
@@ -3490,11 +3813,11 @@ def main():
             extensions = os.listdir(extensions_path)
             if len(extensions) == 0:
                 print("No extensions installed.")
-                exit(0)
+                return ExitCode.SUCCESS
             print("Installed extensions:")
             for extension in extensions:
                 print(f"  {extension}")
-            exit(0)
+            return ExitCode.SUCCESS
         # Remove an extension
         extension_name = cli_args.remove
         extensions_path = get_extensions_path()
@@ -3502,7 +3825,7 @@ def main():
 
         if not os.path.exists(target_path):
             print(f"Extension {extension_name} not found at {target_path}")
-            exit(1)
+            return ExitCode.FAILED
 
         print(f"Removing extension: {extension_name}...")
         try:
@@ -3510,9 +3833,9 @@ def main():
             print(f"Extension {extension_name} removed successfully.")
         except Exception as e:
             print(f"Failed to remove extension: {e}")
-            exit(1)
+            return ExitCode.FAILED
 
-        exit(0)
+        return ExitCode.SUCCESS
 
     if cli_args.update:
         if cli_args.update == "ls":
@@ -3521,7 +3844,7 @@ def main():
             extensions = os.listdir(extensions_path)
             if len(extensions) == 0:
                 print("No extensions installed.")
-                exit(0)
+                return ExitCode.SUCCESS
             print("Installed extensions:")
             for extension in extensions:
                 print(f"  {extension}")
@@ -3529,7 +3852,7 @@ def main():
             print("\nUsage:")
             print("  llms --update <extension>")
             print("  llms --update all")
-            exit(0)
+            return ExitCode.SUCCESS
 
         async def update_extensions(extension_name):
             extensions_path = get_extensions_path()
@@ -3546,7 +3869,11 @@ def main():
                     _log(result.stdout.decode("utf-8"))
 
         asyncio.run(update_extensions(cli_args.update))
-        exit(0)
+        return ExitCode.SUCCESS
+
+    g_app.add_allowed_directory(home_llms_path(".agent"))  # info for agents, e.g: skills
+    g_app.add_allowed_directory(os.getcwd())  # add current directory
+    g_app.add_allowed_directory(tempfile.gettempdir())  # add temp directory
 
     g_app.extensions = install_extensions()
 
@@ -3604,7 +3931,7 @@ def main():
         print(f"\n{model_count} models available from {provider_count} providers")
 
         print_status()
-        g_app.exit(0)
+        return ExitCode.SUCCESS
 
     if cli_args.check is not None:
         # Check validity of models for a provider
@@ -3613,7 +3940,7 @@ def main():
         provider_name = cli_args.check
         model_names = extra_args if len(extra_args) > 0 else None
         loop.run_until_complete(check_models(provider_name, model_names))
-        g_app.exit(0)
+        return ExitCode.SUCCESS
 
     if cli_args.serve is not None:
         # Disable inactive providers and save to config before starting server
@@ -3658,7 +3985,7 @@ def main():
                 print("ERROR: Authentication is enabled but GitHub OAuth is not properly configured.")
                 print("Please set GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET environment variables,")
                 print("or disable authentication by setting 'auth.enabled' to false in llms.json")
-                exit(1)
+                return ExitCode.FAILED
 
             _log("Authentication enabled - GitHub OAuth configured")
 
@@ -4252,7 +4579,7 @@ def main():
 
         print(f"Starting server on port {port}...")
         web.run_app(app, host="0.0.0.0", port=port, print=_log)
-        g_app.exit(0)
+        return ExitCode.SUCCESS
 
     if cli_args.enable is not None:
         if cli_args.enable.endswith(","):
@@ -4271,7 +4598,7 @@ def main():
             if provider not in g_config["providers"]:
                 print(f"Provider '{provider}' not found")
                 print(f"Available providers: {', '.join(g_config['providers'].keys())}")
-                exit(1)
+                return ExitCode.FAILED
             if provider in g_config["providers"]:
                 provider_config, msg = enable_provider(provider)
                 print(f"\nEnabled provider {provider}:")
@@ -4282,7 +4609,7 @@ def main():
         print_status()
         if len(msgs) > 0:
             print("\n" + "\n".join(msgs))
-        g_app.exit(0)
+        return ExitCode.SUCCESS
 
     if cli_args.disable is not None:
         if cli_args.disable.endswith(","):
@@ -4300,24 +4627,24 @@ def main():
             if provider not in g_config["providers"]:
                 print(f"Provider {provider} not found")
                 print(f"Available providers: {', '.join(g_config['providers'].keys())}")
-                exit(1)
+                return ExitCode.FAILED
             disable_provider(provider)
             print(f"\nDisabled provider {provider}")
 
         print_status()
-        g_app.exit(0)
+        return ExitCode.SUCCESS
 
     if cli_args.default is not None:
         default_model = cli_args.default
         provider_model = get_provider_model(default_model)
         if provider_model is None:
             print(f"Model {default_model} not found")
-            exit(1)
+            return ExitCode.FAILED
         default_text = g_config["defaults"]["text"]
         default_text["model"] = default_model
         save_config(g_config)
         print(f"\nDefault model set to: {default_model}")
-        g_app.exit(0)
+        return ExitCode.SUCCESS
 
     if (
         cli_args.chat is not None
@@ -4339,13 +4666,13 @@ def main():
                 template = f"out:{cli_args.out}"
                 if template not in g_config["defaults"]:
                     print(f"Template for output modality '{cli_args.out}' not found")
-                    exit(1)
+                    return ExitCode.FAILED
                 chat = g_config["defaults"][template]
             if cli_args.chat is not None:
                 chat_path = os.path.join(os.path.dirname(__file__), cli_args.chat)
                 if not os.path.exists(chat_path):
                     print(f"Chat request template not found: {chat_path}")
-                    exit(1)
+                    return ExitCode.FAILED
                 _log(f"Using chat: {chat_path}")
 
                 with open(chat_path) as f:
@@ -4386,19 +4713,48 @@ def main():
                     raw=cli_args.raw,
                 )
             )
-            g_app.exit(0)
+            return ExitCode.SUCCESS
         except Exception as e:
             print(f"{cli_args.logprefix}Error: {e}")
             if cli_args.verbose:
                 traceback.print_exc()
-            g_app.exit(1)
+            return ExitCode.FAILED
 
     handled = run_extension_cli()
+    return ExitCode.SUCCESS if handled else ExitCode.UNHANDLED
+
+
+def get_app():
+    return g_app
 
-    if not handled:
+
+def cli(command_line: str):
+    parser = create_arg_parser()
+
+    # Load parser extensions, go through all extensions and load their parser arguments
+    if load_extensions:
+        init_extensions(parser)
+
+    args = shlex.split(command_line)
+    cli_args, extra_args = parser.parse_known_args(args)
+    return cli_exec(cli_args, extra_args)
+
+
+def main():
+    parser = create_arg_parser()
+
+    # Load parser extensions, go through all extensions and load their parser arguments
+    init_extensions(parser)
+
+    cli_args, extra_args = parser.parse_known_args()
+    exit_code = cli_exec(cli_args, extra_args)
+
+    if exit_code == ExitCode.UNHANDLED:
         # show usage from ArgumentParser
         parser.print_help()
-        g_app.exit(0)
+        g_app.exit(0) if g_app else exit(0)
+
+    g_app.exit(exit_code) if g_app else exit(exit_code)
 
 
 if __name__ == "__main__":