llms-py 3.0.0b1__py3-none-any.whl → 3.0.0b3__py3-none-any.whl

llms/main.py

@@ -9,18 +9,20 @@
 import argparse
 import asyncio
 import base64
-from datetime import datetime
 import hashlib
+import importlib.util
 import json
 import mimetypes
 import os
 import re
 import secrets
+import shutil
 import site
 import subprocess
 import sys
 import time
 import traceback
+from datetime import datetime
 from importlib import resources  # Py≥3.9  (pip install importlib_resources for 3.7/3.8)
 from io import BytesIO
 from pathlib import Path
@@ -36,10 +38,13 @@ try:
 except ImportError:
     HAS_PIL = False
 
-VERSION = "3.0.0b1"
+VERSION = "3.0.0b3"
 _ROOT = None
+DEBUG = True  # os.getenv("PYPI_SERVICESTACK") is not None
+MOCK = False
+MOCK_DIR = os.getenv("MOCK_DIR")
+MOCK = os.getenv("MOCK") == "1"
 g_config_path = None
-g_ui_path = None
 g_config = None
 g_providers = None
 g_handlers = {}
@@ -48,14 +53,25 @@ g_logprefix = ""
 g_default_model = ""
 g_sessions = {}  # OAuth session storage: {session_token: {userId, userName, displayName, profileUrl, email, created}}
 g_oauth_states = {}  # CSRF protection: {state: {created, redirect_uri}}
+g_app = None  # ExtensionsContext Singleton
 
 
 def _log(message):
-    """Helper method for logging from the global polling task."""
     if g_verbose:
         print(f"{g_logprefix}{message}", flush=True)
 
 
+def _dbg(message):
+    if DEBUG:
+        print(f"DEBUG: {message}", flush=True)
+
+
+def _err(message, e):
+    print(f"ERROR: {message}: {e}", flush=True)
+    if g_verbose:
+        print(traceback.format_exc(), flush=True)
+
+
 def printdump(obj):
     args = obj.__dict__ if hasattr(obj, "__dict__") else obj
     print(json.dumps(args, indent=2))
@@ -88,17 +104,6 @@ def chat_summary(chat):
     return json.dumps(clone, indent=2)
 
 
-def gemini_chat_summary(gemini_chat):
-    """Summarize Gemini chat completion request for logging. Replace inline_data with size of content only"""
-    clone = json.loads(json.dumps(gemini_chat))
-    for content in clone["contents"]:
-        for part in content["parts"]:
-            if "inline_data" in part:
-                data = part["inline_data"]["data"]
-                part["inline_data"]["data"] = f"({len(data)})"
-    return json.dumps(clone, indent=2)
-
-
 image_exts = ["png", "webp", "jpg", "jpeg", "gif", "bmp", "svg", "tiff", "ico"]
 audio_exts = ["mp3", "wav", "ogg", "flac", "m4a", "opus", "webm"]
 
@@ -192,6 +197,10 @@ def is_base_64(data):
         return False
 
 
+def id_to_name(id):
+    return id.replace("-", " ").title()
+
+
 def get_file_mime_type(filename):
     mime_type, _ = mimetypes.guess_type(filename)
     return mime_type or "application/octet-stream"
@@ -453,6 +462,61 @@ class HTTPError(Exception):
         super().__init__(f"HTTP {status} {reason}")
 
 
+def save_image_to_cache(base64_data, filename, image_info):
+    ext = filename.split(".")[-1]
+    mimetype = get_file_mime_type(filename)
+    content = base64.b64decode(base64_data) if isinstance(base64_data, str) else base64_data
+    sha256_hash = hashlib.sha256(content).hexdigest()
+
+    save_filename = f"{sha256_hash}.{ext}" if ext else sha256_hash
+
+    # Use first 2 chars for subdir to avoid too many files in one dir
+    subdir = sha256_hash[:2]
+    relative_path = f"{subdir}/{save_filename}"
+    full_path = get_cache_path(relative_path)
+
+    url = f"~cache/{relative_path}"
+
+    # if file and its .info.json already exists, return it
+    info_path = os.path.splitext(full_path)[0] + ".info.json"
+    if os.path.exists(full_path) and os.path.exists(info_path):
+        return url, json.load(open(info_path))
+
+    os.makedirs(os.path.dirname(full_path), exist_ok=True)
+
+    with open(full_path, "wb") as f:
+        f.write(content)
+    info = {
+        "date": int(time.time()),
+        "url": url,
+        "size": len(content),
+        "type": mimetype,
+        "name": filename,
+    }
+    info.update(image_info)
+
+    # If image, get dimensions
+    if HAS_PIL and mimetype.startswith("image/"):
+        try:
+            with Image.open(BytesIO(content)) as img:
+                info["width"] = img.width
+                info["height"] = img.height
+        except Exception:
+            pass
+
+    if "width" in info and "height" in info:
+        _log(f"Saved image to cache: {full_path} ({len(content)} bytes) {info['width']}x{info['height']}")
+    else:
+        _log(f"Saved image to cache: {full_path} ({len(content)} bytes)")
+
+    # Save metadata
+    info_path = os.path.splitext(full_path)[0] + ".info.json"
+    with open(info_path, "w") as f:
+        json.dump(info, f)
+
+    return url, info
+
+
 async def response_json(response):
     text = await response.text()
     if response.status >= 400:
@@ -462,6 +526,120 @@ async def response_json(response):
     return body
 
 
+def chat_to_prompt(chat):
+    prompt = ""
+    if "messages" in chat:
+        for message in chat["messages"]:
+            if message["role"] == "user":
+                # if content is string
+                if isinstance(message["content"], str):
+                    if prompt:
+                        prompt += "\n"
+                    prompt += message["content"]
+                elif isinstance(message["content"], list):
+                    # if content is array of objects
+                    for part in message["content"]:
+                        if part["type"] == "text":
+                            if prompt:
+                                prompt += "\n"
+                            prompt += part["text"]
+    return prompt
+
+
+def last_user_prompt(chat):
+    prompt = ""
+    if "messages" in chat:
+        for message in chat["messages"]:
+            if message["role"] == "user":
+                # if content is string
+                if isinstance(message["content"], str):
+                    prompt = message["content"]
+                elif isinstance(message["content"], list):
+                    # if content is array of objects
+                    for part in message["content"]:
+                        if part["type"] == "text":
+                            prompt = part["text"]
+    return prompt
+
+
+# Image Generator Providers
+class GeneratorBase:
+    def __init__(self, **kwargs):
+        self.id = kwargs.get("id")
+        self.api = kwargs.get("api")
+        self.api_key = kwargs.get("api_key")
+        self.headers = {
+            "Accept": "application/json",
+            "Content-Type": "application/json",
+        }
+        self.chat_url = f"{self.api}/chat/completions"
+        self.default_content = "I've generated the image for you."
+
+    def validate(self, **kwargs):
+        if not self.api_key:
+            api_keys = ", ".join(self.env)
+            return f"Provider '{self.name}' requires API Key {api_keys}"
+        return None
+
+    def test(self, **kwargs):
+        error_msg = self.validate(**kwargs)
+        if error_msg:
+            _log(error_msg)
+            return False
+        return True
+
+    async def load(self):
+        pass
+
+    def gen_summary(self, gen):
+        """Summarize gen response for logging."""
+        clone = json.loads(json.dumps(gen))
+        return json.dumps(clone, indent=2)
+
+    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 response_json(self, response):
+        return await response_json(response)
+
+    def get_headers(self, provider, chat):
+        headers = self.headers.copy()
+        if provider is not None:
+            headers["Authorization"] = f"Bearer {provider.api_key}"
+        elif self.api_key:
+            headers["Authorization"] = f"Bearer {self.api_key}"
+        return headers
+
+    def to_response(self, response, chat, started_at):
+        raise NotImplementedError
+
+    async def chat(self, chat, provider=None):
+        return {
+            "choices": [
+                {
+                    "message": {
+                        "role": "assistant",
+                        "content": "Not Implemented",
+                        "images": [
+                            {
+                                "type": "image_url",
+                                "image_url": {
+                                    "url": "data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIyNCIgaGVpZ2h0PSIyNCIgdmlld0JveD0iMCAwIDI0IDI0Ij48cGF0aCBmaWxsPSJjdXJyZW50Q29sb3IiIGQ9Ik0xMiAyMGE4IDggMCAxIDAgMC0xNmE4IDggMCAwIDAgMCAxNm0wIDJDNi40NzcgMjIgMiAxNy41MjMgMiAxMlM2LjQ3NyAyIDEyIDJzMTAgNC40NzcgMTAgMTBzLTQuNDc3IDEwLTEwIDEwbS0xLTZoMnYyaC0yem0wLTEwaDJ2OGgtMnoiLz48L3N2Zz4=",
+                                },
+                            }
+                        ],
+                    }
+                }
+            ]
+        }
+
+
+# OpenAI Providers
+
+
 class OpenAiCompatible:
     sdk = "@ai-sdk/openai-compatible"
 
@@ -473,8 +651,9 @@ class OpenAiCompatible:
 
         self.id = kwargs.get("id")
         self.api = kwargs.get("api").strip("/")
+        self.env = kwargs.get("env", [])
         self.api_key = kwargs.get("api_key")
-        self.name = kwargs.get("name", self.id.replace("-", " ").title().replace(" ", ""))
+        self.name = kwargs.get("name", id_to_name(self.id))
         self.set_models(**kwargs)
 
         self.chat_url = f"{self.api}/chat/completions"
@@ -502,6 +681,7 @@ class OpenAiCompatible:
         self.stream = bool(kwargs["stream"]) if "stream" in kwargs else None
         self.enable_thinking = bool(kwargs["enable_thinking"]) if "enable_thinking" in kwargs else None
         self.check = kwargs.get("check")
+        self.modalities = kwargs.get("modalities", {})
 
     def set_models(self, **kwargs):
         models = kwargs.get("models", {})
@@ -527,11 +707,18 @@ class OpenAiCompatible:
             _log(f"Filtering {len(self.models)} models, excluding models that match regex: {exclude_models}")
             self.models = {k: v for k, v in self.models.items() if not re.search(exclude_models, k)}
 
+    def validate(self, **kwargs):
+        if not self.api_key:
+            api_keys = ", ".join(self.env)
+            return f"Provider '{self.name}' requires API Key {api_keys}"
+        return None
+
     def test(self, **kwargs):
-        ret = self.api and self.api_key and (len(self.models) > 0)
-        if not ret:
-            _log(f"Provider {self.name} Missing: {self.api}, {self.api_key}, {len(self.models)}")
-        return ret
+        error_msg = self.validate(**kwargs)
+        if error_msg:
+            _log(error_msg)
+            return False
+        return True
 
     async def load(self):
         if not self.models:
@@ -579,56 +766,11 @@ class OpenAiCompatible:
         if "/" in model:
             last_part = model.split("/")[-1]
             return self.provider_model(last_part)
-        return None
-
-    def validate_modalities(self, chat):
-        model_id = chat.get("model")
-        if not model_id or not self.models:
-            return
 
-        model_info = None
-        # Try to find model info using provider_model logic (already resolved to ID)
-        if model_id in self.models:
-            model_info = self.models[model_id]
-        else:
-            # Fallback scan
-            for m_id, m_info in self.models.items():
-                if m_id == model_id or m_info.get("id") == model_id:
-                    model_info = m_info
-                    break
-
-        print(f"DEBUG: Validate modalities: model={model_id}, found_info={model_info is not None}")
-        if model_info:
-            print(f"DEBUG: Modalities: {model_info.get('modalities')}")
-
-        if not model_info:
-            return
-
-        modalities = model_info.get("modalities", {})
-        input_modalities = modalities.get("input", [])
-
-        # Check for unsupported modalities
-        has_audio = False
-        has_image = False
-        for message in chat.get("messages", []):
-            content = message.get("content")
-            if isinstance(content, list):
-                for item in content:
-                    type_ = item.get("type")
-                    if type_ == "input_audio" or "input_audio" in item:
-                        has_audio = True
-                    elif type_ == "image_url" or "image_url" in item:
-                        has_image = True
-
-        if has_audio and "audio" not in input_modalities:
-            raise Exception(
-                f"Model '{model_id}' does not support audio input. Supported modalities: {', '.join(input_modalities)}"
-            )
+        return None
 
-        if has_image and "image" not in input_modalities:
-            raise Exception(
-                f"Model '{model_id}' does not support image input. Supported modalities: {', '.join(input_modalities)}"
-            )
+    def response_json(self, response):
+        return response_json(response)
 
     def to_response(self, response, chat, started_at):
         if "metadata" not in response:
@@ -638,13 +780,27 @@ class OpenAiCompatible:
             pricing = self.model_cost(chat["model"])
             if pricing and "input" in pricing and "output" in pricing:
                 response["metadata"]["pricing"] = f"{pricing['input']}/{pricing['output']}"
-        _log(json.dumps(response, indent=2))
         return response
 
+    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 chat(self, chat):
         chat["model"] = self.provider_model(chat["model"]) or chat["model"]
 
-        self.validate_modalities(chat)
+        if "modalities" in chat:
+            for modality in chat["modalities"]:
+                # use default implementation for text modalities
+                if modality == "text":
+                    continue
+                modality_provider = self.modalities.get(modality)
+                if modality_provider:
+                    return await modality_provider.chat(chat, self)
+                else:
+                    raise Exception(f"Provider {self.name} does not support '{modality}' modality")
 
         # with open(os.path.join(os.path.dirname(__file__), 'chat.wip.json'), "w") as f:
         #     f.write(json.dumps(chat, indent=2))
@@ -698,193 +854,6 @@ class OpenAiCompatible:
                 return self.to_response(await response_json(response), chat, started_at)
 
 
-class OpenAiProvider(OpenAiCompatible):
-    sdk = "@ai-sdk/openai"
-
-    def __init__(self, **kwargs):
-        if "api" not in kwargs:
-            kwargs["api"] = "https://api.openai.com/v1"
-        super().__init__(**kwargs)
-
-
-class AnthropicProvider(OpenAiCompatible):
-    sdk = "@ai-sdk/anthropic"
-
-    def __init__(self, **kwargs):
-        if "api" not in kwargs:
-            kwargs["api"] = "https://api.anthropic.com/v1"
-        super().__init__(**kwargs)
-
-        # Anthropic uses x-api-key header instead of Authorization
-        if self.api_key:
-            self.headers = self.headers.copy()
-            if "Authorization" in self.headers:
-                del self.headers["Authorization"]
-            self.headers["x-api-key"] = self.api_key
-
-        if "anthropic-version" not in self.headers:
-            self.headers = self.headers.copy()
-            self.headers["anthropic-version"] = "2023-06-01"
-        self.chat_url = f"{self.api}/messages"
-
-    async def chat(self, chat):
-        chat["model"] = self.provider_model(chat["model"]) or chat["model"]
-
-        chat = await process_chat(chat, provider_id=self.id)
-
-        # Transform OpenAI format to Anthropic format
-        anthropic_request = {
-            "model": chat["model"],
-            "messages": [],
-        }
-
-        # Extract system message (Anthropic uses top-level 'system' parameter)
-        system_messages = []
-        for message in chat.get("messages", []):
-            if message.get("role") == "system":
-                content = message.get("content", "")
-                if isinstance(content, str):
-                    system_messages.append(content)
-                elif isinstance(content, list):
-                    for item in content:
-                        if item.get("type") == "text":
-                            system_messages.append(item.get("text", ""))
-
-        if system_messages:
-            anthropic_request["system"] = "\n".join(system_messages)
-
-        # Transform messages (exclude system messages)
-        for message in chat.get("messages", []):
-            if message.get("role") == "system":
-                continue
-
-            anthropic_message = {"role": message.get("role"), "content": []}
-
-            content = message.get("content", "")
-            if isinstance(content, str):
-                anthropic_message["content"] = content
-            elif isinstance(content, list):
-                for item in content:
-                    if item.get("type") == "text":
-                        anthropic_message["content"].append({"type": "text", "text": item.get("text", "")})
-                    elif item.get("type") == "image_url" and "image_url" in item:
-                        # Transform OpenAI image_url format to Anthropic format
-                        image_url = item["image_url"].get("url", "")
-                        if image_url.startswith("data:"):
-                            # Extract media type and base64 data
-                            parts = image_url.split(";base64,", 1)
-                            if len(parts) == 2:
-                                media_type = parts[0].replace("data:", "")
-                                base64_data = parts[1]
-                                anthropic_message["content"].append(
-                                    {
-                                        "type": "image",
-                                        "source": {"type": "base64", "media_type": media_type, "data": base64_data},
-                                    }
-                                )
-
-            anthropic_request["messages"].append(anthropic_message)
-
-        # Handle max_tokens (required by Anthropic, uses max_tokens not max_completion_tokens)
-        if "max_completion_tokens" in chat:
-            anthropic_request["max_tokens"] = chat["max_completion_tokens"]
-        elif "max_tokens" in chat:
-            anthropic_request["max_tokens"] = chat["max_tokens"]
-        else:
-            # Anthropic requires max_tokens, set a default
-            anthropic_request["max_tokens"] = 4096
-
-        # Copy other supported parameters
-        if "temperature" in chat:
-            anthropic_request["temperature"] = chat["temperature"]
-        if "top_p" in chat:
-            anthropic_request["top_p"] = chat["top_p"]
-        if "top_k" in chat:
-            anthropic_request["top_k"] = chat["top_k"]
-        if "stop" in chat:
-            anthropic_request["stop_sequences"] = chat["stop"] if isinstance(chat["stop"], list) else [chat["stop"]]
-        if "stream" in chat:
-            anthropic_request["stream"] = chat["stream"]
-        if "tools" in chat:
-            anthropic_request["tools"] = chat["tools"]
-        if "tool_choice" in chat:
-            anthropic_request["tool_choice"] = chat["tool_choice"]
-
-        _log(f"POST {self.chat_url}")
-        _log(f"Anthropic Request: {json.dumps(anthropic_request, indent=2)}")
-
-        async with aiohttp.ClientSession() as session:
-            started_at = time.time()
-            async with session.post(
-                self.chat_url,
-                headers=self.headers,
-                data=json.dumps(anthropic_request),
-                timeout=aiohttp.ClientTimeout(total=120),
-            ) as response:
-                return self.to_response(await response_json(response), chat, started_at)
-
-    def to_response(self, response, chat, started_at):
-        """Convert Anthropic response format to OpenAI-compatible format."""
-        # Transform Anthropic response to OpenAI format
-        openai_response = {
-            "id": response.get("id", ""),
-            "object": "chat.completion",
-            "created": int(started_at),
-            "model": response.get("model", ""),
-            "choices": [],
-            "usage": {},
-        }
-
-        # Transform content blocks to message content
-        content_parts = []
-        thinking_parts = []
-
-        for block in response.get("content", []):
-            if block.get("type") == "text":
-                content_parts.append(block.get("text", ""))
-            elif block.get("type") == "thinking":
-                # Store thinking blocks separately (some models include reasoning)
-                thinking_parts.append(block.get("thinking", ""))
-
-        # Combine all text content
-        message_content = "\n".join(content_parts) if content_parts else ""
-
-        # Create the choice object
-        choice = {
-            "index": 0,
-            "message": {"role": "assistant", "content": message_content},
-            "finish_reason": response.get("stop_reason", "stop"),
-        }
-
-        # Add thinking as metadata if present
-        if thinking_parts:
-            choice["message"]["thinking"] = "\n".join(thinking_parts)
-
-        openai_response["choices"].append(choice)
-
-        # Transform usage
-        if "usage" in response:
-            usage = response["usage"]
-            openai_response["usage"] = {
-                "prompt_tokens": usage.get("input_tokens", 0),
-                "completion_tokens": usage.get("output_tokens", 0),
-                "total_tokens": usage.get("input_tokens", 0) + usage.get("output_tokens", 0),
-            }
-
-        # Add metadata
-        if "metadata" not in openai_response:
-            openai_response["metadata"] = {}
-        openai_response["metadata"]["duration"] = int((time.time() - started_at) * 1000)
-
-        if chat is not None and "model" in chat:
-            cost = self.model_cost(chat["model"])
-            if cost and "input" in cost and "output" in cost:
-                openai_response["metadata"]["pricing"] = f"{cost['input']}/{cost['output']}"
-
-        _log(json.dumps(openai_response, indent=2))
-        return openai_response
-
-
 class MistralProvider(OpenAiCompatible):
     sdk = "@ai-sdk/mistral"
 
@@ -941,11 +910,10 @@ class OllamaProvider(OpenAiCompatible):
                 ) as response:
                     data = await response_json(response)
                     for model in data.get("models", []):
-                        name = model["model"]
-                        if name.endswith(":latest"):
-                            name = name[:-7]
-                        model_id = name.replace(":", "-")
-                        ret[model_id] = name
+                        model_id = model["model"]
+                        if model_id.endswith(":latest"):
+                            model_id = model_id[:-7]
+                        ret[model_id] = model_id
                     _log(f"Loaded Ollama models: {ret}")
         except Exception as e:
             _log(f"Error getting Ollama models: {e}")
@@ -981,8 +949,8 @@ class OllamaProvider(OpenAiCompatible):
             }
         self.models = models
 
-    def test(self, **kwargs):
-        return True
+    def validate(self, **kwargs):
+        return None
 
 
 class LMStudioProvider(OllamaProvider):
@@ -1011,237 +979,6 @@ class LMStudioProvider(OllamaProvider):
         return ret
 
 
-# class GoogleOpenAiProvider(OpenAiCompatible):
-#     sdk = "google-openai-compatible"
-
-#     def __init__(self, api_key, **kwargs):
-#         super().__init__(api="https://generativelanguage.googleapis.com", api_key=api_key, **kwargs)
-#         self.chat_url = "https://generativelanguage.googleapis.com/v1beta/chat/completions"
-
-
-class GoogleProvider(OpenAiCompatible):
-    sdk = "@ai-sdk/google"
-
-    def __init__(self, **kwargs):
-        new_kwargs = {"api": "https://generativelanguage.googleapis.com", **kwargs}
-        super().__init__(**new_kwargs)
-        self.safety_settings = kwargs.get("safety_settings")
-        self.thinking_config = kwargs.get("thinking_config")
-        self.curl = kwargs.get("curl")
-        self.headers = kwargs.get("headers", {"Content-Type": "application/json"})
-        # Google fails when using Authorization header, use query string param instead
-        if "Authorization" in self.headers:
-            del self.headers["Authorization"]
-
-    async def chat(self, chat):
-        chat["model"] = self.provider_model(chat["model"]) or chat["model"]
-
-        chat = await process_chat(chat)
-        generation_config = {}
-
-        # Filter out system messages and convert to proper Gemini format
-        contents = []
-        system_prompt = None
-
-        async with aiohttp.ClientSession() as session:
-            for message in chat["messages"]:
-                if message["role"] == "system":
-                    content = message["content"]
-                    if isinstance(content, list):
-                        for item in content:
-                            if "text" in item:
-                                system_prompt = item["text"]
-                                break
-                    elif isinstance(content, str):
-                        system_prompt = content
-                elif "content" in message:
-                    if isinstance(message["content"], list):
-                        parts = []
-                        for item in message["content"]:
-                            if "type" in item:
-                                if item["type"] == "image_url" and "image_url" in item:
-                                    image_url = item["image_url"]
-                                    if "url" not in image_url:
-                                        continue
-                                    url = image_url["url"]
-                                    if not url.startswith("data:"):
-                                        raise (Exception("Image was not downloaded: " + url))
-                                    # Extract mime type from data uri
-                                    mimetype = url.split(";", 1)[0].split(":", 1)[1] if ";" in url else "image/png"
-                                    base64_data = url.split(",", 1)[1]
-                                    parts.append({"inline_data": {"mime_type": mimetype, "data": base64_data}})
-                                elif item["type"] == "input_audio" and "input_audio" in item:
-                                    input_audio = item["input_audio"]
-                                    if "data" not in input_audio:
-                                        continue
-                                    data = input_audio["data"]
-                                    format = input_audio["format"]
-                                    mimetype = f"audio/{format}"
-                                    parts.append({"inline_data": {"mime_type": mimetype, "data": data}})
-                                elif item["type"] == "file" and "file" in item:
-                                    file = item["file"]
-                                    if "file_data" not in file:
-                                        continue
-                                    data = file["file_data"]
-                                    if not data.startswith("data:"):
-                                        raise (Exception("File was not downloaded: " + data))
-                                    # Extract mime type from data uri
-                                    mimetype = (
-                                        data.split(";", 1)[0].split(":", 1)[1]
-                                        if ";" in data
-                                        else "application/octet-stream"
-                                    )
-                                    base64_data = data.split(",", 1)[1]
-                                    parts.append({"inline_data": {"mime_type": mimetype, "data": base64_data}})
-                            if "text" in item:
-                                text = item["text"]
-                                parts.append({"text": text})
-                        if len(parts) > 0:
-                            contents.append(
-                                {
-                                    "role": message["role"]
-                                    if "role" in message and message["role"] == "user"
-                                    else "model",
-                                    "parts": parts,
-                                }
-                            )
-                    else:
-                        content = message["content"]
-                        contents.append(
-                            {
-                                "role": message["role"] if "role" in message and message["role"] == "user" else "model",
-                                "parts": [{"text": content}],
-                            }
-                        )
-
-            gemini_chat = {
-                "contents": contents,
-            }
-
-            if self.safety_settings:
-                gemini_chat["safetySettings"] = self.safety_settings
-
-            # Add system instruction if present
-            if system_prompt is not None:
-                gemini_chat["systemInstruction"] = {"parts": [{"text": system_prompt}]}
-
-            if "max_completion_tokens" in chat:
-                generation_config["maxOutputTokens"] = chat["max_completion_tokens"]
-            if "stop" in chat:
-                generation_config["stopSequences"] = [chat["stop"]]
-            if "temperature" in chat:
-                generation_config["temperature"] = chat["temperature"]
-            if "top_p" in chat:
-                generation_config["topP"] = chat["top_p"]
-            if "top_logprobs" in chat:
-                generation_config["topK"] = chat["top_logprobs"]
-
-            if "thinkingConfig" in chat:
-                generation_config["thinkingConfig"] = chat["thinkingConfig"]
-            elif self.thinking_config:
-                generation_config["thinkingConfig"] = self.thinking_config
-
-            if len(generation_config) > 0:
-                gemini_chat["generationConfig"] = generation_config
-
-            started_at = int(time.time() * 1000)
-            gemini_chat_url = f"https://generativelanguage.googleapis.com/v1beta/models/{chat['model']}:generateContent?key={self.api_key}"
-
-            _log(f"POST {gemini_chat_url}")
-            _log(gemini_chat_summary(gemini_chat))
-            started_at = time.time()
-
-            if self.curl:
-                curl_args = [
-                    "curl",
-                    "-X",
-                    "POST",
-                    "-H",
-                    "Content-Type: application/json",
-                    "-d",
-                    json.dumps(gemini_chat),
-                    gemini_chat_url,
-                ]
-                try:
-                    o = subprocess.run(curl_args, check=True, capture_output=True, text=True, timeout=120)
-                    obj = json.loads(o.stdout)
-                except Exception as e:
-                    raise Exception(f"Error executing curl: {e}") from e
-            else:
-                async with session.post(
-                    gemini_chat_url,
-                    headers=self.headers,
-                    data=json.dumps(gemini_chat),
-                    timeout=aiohttp.ClientTimeout(total=120),
-                ) as res:
-                    obj = await response_json(res)
-                    _log(f"google response:\n{json.dumps(obj, indent=2)}")
-
-            response = {
-                "id": f"chatcmpl-{started_at}",
-                "created": started_at,
-                "model": obj.get("modelVersion", chat["model"]),
-            }
-            choices = []
-            if "error" in obj:
-                _log(f"Error: {obj['error']}")
-                raise Exception(obj["error"]["message"])
-            for i, candidate in enumerate(obj["candidates"]):
-                role = "assistant"
-                if "content" in candidate and "role" in candidate["content"]:
-                    role = "assistant" if candidate["content"]["role"] == "model" else candidate["content"]["role"]
-
-                # Safely extract content from all text parts
-                content = ""
-                reasoning = ""
-                if "content" in candidate and "parts" in candidate["content"]:
-                    text_parts = []
-                    reasoning_parts = []
-                    for part in candidate["content"]["parts"]:
-                        if "text" in part:
-                            if "thought" in part and part["thought"]:
-                                reasoning_parts.append(part["text"])
-                            else:
-                                text_parts.append(part["text"])
-                    content = " ".join(text_parts)
-                    reasoning = " ".join(reasoning_parts)
-
-                choice = {
-                    "index": i,
-                    "finish_reason": candidate.get("finishReason", "stop"),
-                    "message": {
-                        "role": role,
-                        "content": content,
-                    },
-                }
-                if reasoning:
-                    choice["message"]["reasoning"] = reasoning
-                choices.append(choice)
-            response["choices"] = choices
-            if "usageMetadata" in obj:
-                usage = obj["usageMetadata"]
-                response["usage"] = {
-                    "completion_tokens": usage["candidatesTokenCount"],
-                    "total_tokens": usage["totalTokenCount"],
-                    "prompt_tokens": usage["promptTokenCount"],
-                }
-            return self.to_response(response, chat, started_at)
-
-
-ALL_PROVIDERS = [
-    OpenAiCompatible,
-    OpenAiProvider,
-    AnthropicProvider,
-    MistralProvider,
-    GroqProvider,
-    XaiProvider,
-    CodestralProvider,
-    GoogleProvider,
-    OllamaProvider,
-    LMStudioProvider,
-]
-
-
 def get_provider_model(model_name):
     for provider in g_handlers.values():
         provider_model = provider.provider_model(model_name)
@@ -1389,8 +1126,29 @@ async def cli_chat(chat, image=None, audio=None, file=None, args=None, raw=False
             print(json.dumps(response, indent=2))
             exit(0)
         else:
-            answer = response["choices"][0]["message"]["content"]
-            print(answer)
+            msg = response["choices"][0]["message"]
+            if "answer" in msg:
+                answer = msg["content"]
+                print(answer)
+
+            generated_files = []
+            for choice in response["choices"]:
+                if "message" in choice:
+                    msg = choice["message"]
+                    if "images" in msg:
+                        for image in msg["images"]:
+                            image_url = image["image_url"]["url"]
+                            generated_files.append(image_url)
+
+            if len(generated_files) > 0:
+                print("\nSaved files:")
+                for file in generated_files:
+                    if file.startswith("~cache"):
+                        print(get_cache_path(file[7:]))
+                        _log(f"http://localhost:8000/{file}")
+                    else:
+                        print(file)
+
     except HTTPError as e:
         # HTTP error (4xx, 5xx)
         print(f"{e}:\n{e.body}")
@@ -1432,22 +1190,26 @@ def init_llms(config, providers):
     providers = g_config["providers"]
 
     for id, orig in providers.items():
-        definition = orig.copy()
-        if "enabled" in definition and not definition["enabled"]:
+        if "enabled" in orig and not orig["enabled"]:
             continue
 
-        provider_id = definition.get("id", id)
-        if "id" not in definition:
-            definition["id"] = provider_id
-        provider = g_providers.get(provider_id)
-        constructor_kwargs = create_provider_kwargs(definition, provider)
-        provider = create_provider(constructor_kwargs)
-
+        provider, constructor_kwargs = create_provider_from_definition(id, orig)
         if provider and provider.test(**constructor_kwargs):
             g_handlers[id] = provider
     return g_handlers
 
 
+def create_provider_from_definition(id, orig):
+    definition = orig.copy()
+    provider_id = definition.get("id", id)
+    if "id" not in definition:
+        definition["id"] = provider_id
+    provider = g_providers.get(provider_id)
+    constructor_kwargs = create_provider_kwargs(definition, provider)
+    provider = create_provider(constructor_kwargs)
+    return provider, constructor_kwargs
+
+
 def create_provider_kwargs(definition, provider=None):
     if provider:
         provider = provider.copy()
@@ -1475,6 +1237,15 @@ def create_provider_kwargs(definition, provider=None):
         if isinstance(value, (list, dict)):
             constructor_kwargs[key] = value.copy()
     constructor_kwargs["headers"] = g_config["defaults"]["headers"].copy()
+
+    if "modalities" in definition:
+        constructor_kwargs["modalities"] = {}
+        for modality, modality_definition in definition["modalities"].items():
+            modality_provider = create_provider(modality_definition)
+            if not modality_provider:
+                return None
+            constructor_kwargs["modalities"][modality] = modality_provider
+
     return constructor_kwargs
 
 
@@ -1487,9 +1258,11 @@ def create_provider(provider):
         _log(f"Provider {provider_label} is missing 'npm' sdk")
         return None
 
-    for provider_type in ALL_PROVIDERS:
+    for provider_type in g_app.all_providers:
         if provider_type.sdk == npm_sdk:
             kwargs = create_provider_kwargs(provider)
+            if kwargs is None:
+                kwargs = provider
             return provider_type(**kwargs)
 
     _log(f"Could not find provider {provider_label} with npm sdk {npm_sdk}")
@@ -1543,11 +1316,23 @@ async def update_providers(home_providers_path):
     global g_providers
     text = await get_text("https://models.dev/api.json")
     all_providers = json.loads(text)
+    extra_providers = {}
+    extra_providers_path = home_providers_path.replace("providers.json", "providers-extra.json")
+    if os.path.exists(extra_providers_path):
+        with open(extra_providers_path) as f:
+            extra_providers = json.load(f)
 
     filtered_providers = {}
     for id, provider in all_providers.items():
         if id in g_config["providers"]:
             filtered_providers[id] = provider
+            if id in extra_providers and "models" in extra_providers[id]:
+                for model_id, model in extra_providers[id]["models"].items():
+                    if "id" not in model:
+                        model["id"] = model_id
+                    if "name" not in model:
+                        model["name"] = id_to_name(model["id"])
+                    filtered_providers[id]["models"][model_id] = model
 
     os.makedirs(os.path.dirname(home_providers_path), exist_ok=True)
     with open(home_providers_path, "w", encoding="utf-8") as f:
@@ -1600,26 +1385,18 @@ def get_config_path():
     return None
 
 
-def get_ui_path():
-    ui_paths = [home_llms_path("ui.json"), "ui.json"]
-    for ui_path in ui_paths:
-        if os.path.exists(ui_path):
-            return ui_path
-    return None
-
-
 def enable_provider(provider):
     msg = None
     provider_config = g_config["providers"][provider]
+    if not provider_config:
+        return None, f"Provider {provider} not found"
+
+    provider, constructor_kwargs = create_provider_from_definition(provider, provider_config)
+    msg = provider.validate(**constructor_kwargs)
+    if msg:
+        return None, msg
+
     provider_config["enabled"] = True
-    if "api_key" in provider_config:
-        api_key = provider_config["api_key"]
-        if isinstance(api_key, str):
-            if api_key.startswith("$"):
-                if not os.environ.get(api_key[1:], ""):
-                    msg = f"WARNING: {provider} requires missing API Key in Environment Variable {api_key}"
-            else:
-                msg = f"WARNING: {provider} is not configured with an API Key"
     save_config(g_config)
     init_llms(g_config, g_providers)
     return provider_config, msg
@@ -1944,9 +1721,14 @@ async def text_from_resource_or_url(filename):
 
 async def save_home_configs():
     home_config_path = home_llms_path("llms.json")
-    home_ui_path = home_llms_path("ui.json")
     home_providers_path = home_llms_path("providers.json")
-    if os.path.exists(home_config_path) and os.path.exists(home_ui_path) and os.path.exists(home_providers_path):
+    home_providers_extra_path = home_llms_path("providers-extra.json")
+
+    if (
+        os.path.exists(home_config_path)
+        and os.path.exists(home_providers_path)
+        and os.path.exists(home_providers_extra_path)
+    ):
         return
 
     llms_home = os.path.dirname(home_config_path)
@@ -1958,17 +1740,17 @@ async def save_home_configs():
                 f.write(config_json)
             _log(f"Created default config at {home_config_path}")
 
-        if not os.path.exists(home_ui_path):
-            ui_json = await text_from_resource_or_url("ui.json")
-            with open(home_ui_path, "w", encoding="utf-8") as f:
-                f.write(ui_json)
-            _log(f"Created default ui config at {home_ui_path}")
-
         if not os.path.exists(home_providers_path):
             providers_json = await text_from_resource_or_url("providers.json")
             with open(home_providers_path, "w", encoding="utf-8") as f:
                 f.write(providers_json)
             _log(f"Created default providers config at {home_providers_path}")
+
+        if not os.path.exists(home_providers_extra_path):
+            extra_json = await text_from_resource_or_url("providers-extra.json")
+            with open(home_providers_extra_path, "w", encoding="utf-8") as f:
+                f.write(extra_json)
+            _log(f"Created default extra providers config at {home_providers_extra_path}")
     except Exception:
         print("Could not create llms.json. Create one with --init or use --config <path>")
         exit(1)
@@ -2005,62 +1787,348 @@ async def reload_providers():
     return g_handlers
 
 
-async def watch_config_files(config_path, ui_path, interval=1):
+async def watch_config_files(config_path, providers_path, interval=1):
     """Watch config files and reload providers when they change"""
     global g_config
 
     config_path = Path(config_path)
-    ui_path = Path(ui_path) if ui_path else None
+    providers_path = Path(providers_path)
 
-    file_mtimes = {}
+    _log(f"Watching config file: {config_path}")
+    _log(f"Watching providers file: {providers_path}")
 
-    _log(f"Watching config files: {config_path}" + (f", {ui_path}" if ui_path else ""))
+    def get_latest_mtime():
+        ret = 0
+        name = "llms.json"
+        if config_path.is_file():
+            ret = config_path.stat().st_mtime
+            name = config_path.name
+        if providers_path.is_file() and providers_path.stat().st_mtime > ret:
+            ret = providers_path.stat().st_mtime
+            name = providers_path.name
+        return ret, name
+
+    latest_mtime, name = get_latest_mtime()
 
     while True:
         await asyncio.sleep(interval)
 
         # Check llms.json
         try:
-            if config_path.is_file():
-                mtime = config_path.stat().st_mtime
+            new_mtime, name = get_latest_mtime()
+            if new_mtime > latest_mtime:
+                _log(f"Config file changed: {name}")
+                latest_mtime = new_mtime
 
-                if str(config_path) not in file_mtimes:
-                    file_mtimes[str(config_path)] = mtime
-                elif file_mtimes[str(config_path)] != mtime:
-                    _log(f"Config file changed: {config_path.name}")
-                    file_mtimes[str(config_path)] = mtime
+                try:
+                    # Reload llms.json
+                    with open(config_path) as f:
+                        g_config = json.load(f)
 
-                    try:
-                        # Reload llms.json
-                        with open(config_path) as f:
-                            g_config = json.load(f)
-
-                        # Reload providers
-                        await reload_providers()
-                        _log("Providers reloaded successfully")
-                    except Exception as e:
-                        _log(f"Error reloading config: {e}")
+                    # Reload providers
+                    await reload_providers()
+                    _log("Providers reloaded successfully")
+                except Exception as e:
+                    _log(f"Error reloading config: {e}")
         except FileNotFoundError:
             pass
 
-        # Check ui.json
-        if ui_path:
+
+def get_session_token(request):
+    return request.query.get("session") or request.headers.get("X-Session-Token") or request.cookies.get("llms-token")
+
+
+class AppExtensions:
+    """
+    APIs extensions can use to extend the app
+    """
+
+    def __init__(self, cli_args, extra_args):
+        self.cli_args = cli_args
+        self.extra_args = extra_args
+        self.ui_extensions = []
+        self.chat_request_filters = []
+        self.chat_response_filters = []
+        self.server_add_get = []
+        self.server_add_post = []
+        self.all_providers = [
+            OpenAiCompatible,
+            MistralProvider,
+            GroqProvider,
+            XaiProvider,
+            CodestralProvider,
+            OllamaProvider,
+            LMStudioProvider,
+        ]
+        self.aspect_ratios = {
+            "1:1": "1024×1024",
+            "2:3": "832×1248",
+            "3:2": "1248×832",
+            "3:4": "864×1184",
+            "4:3": "1184×864",
+            "4:5": "896×1152",
+            "5:4": "1152×896",
+            "9:16": "768×1344",
+            "16:9": "1344×768",
+            "21:9": "1536×672",
+        }
+
+
+class ExtensionContext:
+    def __init__(self, app, path):
+        self.app = app
+        self.path = path
+        self.name = os.path.basename(path)
+        if self.name.endswith(".py"):
+            self.name = self.name[:-3]
+        self.ext_prefix = f"/ext/{self.name}"
+        self.MOCK = MOCK
+        self.MOCK_DIR = MOCK_DIR
+        self.debug = DEBUG
+        self.verbose = g_verbose
+
+    def chat_to_prompt(self, chat):
+        return chat_to_prompt(chat)
+
+    def last_user_prompt(self, chat):
+        return last_user_prompt(chat)
+
+    def save_image_to_cache(self, base64_data, filename, image_info):
+        return save_image_to_cache(base64_data, filename, image_info)
+
+    def text_from_file(self, path):
+        return text_from_file(path)
+
+    def log(self, message):
+        if self.verbose:
+            print(f"[{self.name}] {message}", flush=True)
+        return message
+
+    def log_json(self, obj):
+        if self.verbose:
+            print(f"[{self.name}] {json.dumps(obj, indent=2)}", flush=True)
+        return obj
+
+    def dbg(self, message):
+        if self.debug:
+            print(f"DEBUG [{self.name}]: {message}", flush=True)
+
+    def err(self, message, e):
+        print(f"ERROR [{self.name}]: {message}", e)
+        if self.verbose:
+            print(traceback.format_exc(), flush=True)
+
+    def add_provider(self, provider):
+        self.log(f"Registered provider: {provider}")
+        self.app.all_providers.append(provider)
+
+    def register_ui_extension(self, index):
+        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):
+        self.log(f"Registered chat request filter: {handler}")
+        self.app.chat_request_filters.append(handler)
+
+    def register_chat_response_filter(self, handler):
+        self.log(f"Registered chat response filter: {handler}")
+        self.app.chat_response_filters.append(handler)
+
+    def add_static_files(self, ext_dir):
+        self.log(f"Registered static files: {ext_dir}")
+
+        async def serve_static(request):
+            path = request.match_info["path"]
+            file_path = os.path.join(ext_dir, path)
+            if os.path.exists(file_path):
+                return web.FileResponse(file_path)
+            return web.Response(status=404)
+
+        self.app.server_add_get.append((os.path.join(self.ext_prefix, "{path:.*}"), serve_static, {}))
+
+    def add_get(self, path, handler, **kwargs):
+        self.dbg(f"Registered GET: {os.path.join(self.ext_prefix, path)}")
+        self.app.server_add_get.append((os.path.join(self.ext_prefix, path), handler, kwargs))
+
+    def add_post(self, path, handler, **kwargs):
+        self.dbg(f"Registered POST: {os.path.join(self.ext_prefix, path)}")
+        self.app.server_add_post.append((os.path.join(self.ext_prefix, path), handler, kwargs))
+
+    def get_config(self):
+        return g_config
+
+    def chat_completion(self, chat):
+        return chat_completion(chat)
+
+    def get_providers(self):
+        return g_handlers
+
+    def get_provider(self, name):
+        return g_handlers.get(name)
+
+    def get_session(self, request):
+        session_token = get_session_token(request)
+
+        if not session_token or session_token not in g_sessions:
+            return None
+
+        session_data = g_sessions[session_token]
+        return session_data
+
+    def get_username(self, request):
+        session = self.get_session(request)
+        if session:
+            return session.get("userName")
+        return None
+
+
+def load_builtin_extensions():
+    providers_path = _ROOT / "providers"
+    if not providers_path.exists():
+        return
+
+    for item in os.listdir(providers_path):
+        if not item.endswith(".py") or item == "__init__.py":
+            continue
+
+        item_path = providers_path / item
+        module_name = item[:-3]
+
+        try:
+            spec = importlib.util.spec_from_file_location(module_name, item_path)
+            if spec and spec.loader:
+                module = importlib.util.module_from_spec(spec)
+                sys.modules[f"llms.providers.{module_name}"] = module
+                spec.loader.exec_module(module)
+
+                install_func = getattr(module, "__install__", None)
+                if callable(install_func):
+                    install_func(ExtensionContext(g_app, item_path))
+                    _log(f"Loaded builtin extension: {module_name}")
+        except Exception as e:
+            _err(f"Failed to load builtin extension {module_name}", e)
+
+
+def get_extensions_path():
+    return os.path.join(Path.home(), ".llms", "extensions")
+
+
+def init_extensions(parser):
+    extensions_path = get_extensions_path()
+    os.makedirs(extensions_path, exist_ok=True)
+
+    for item in os.listdir(extensions_path):
+        item_path = os.path.join(extensions_path, item)
+        if os.path.isdir(item_path):
             try:
-                if ui_path.is_file():
-                    mtime = ui_path.stat().st_mtime
+                # check for __parser__ function if exists in __init.__.py and call it with parser
+                init_file = os.path.join(item_path, "__init__.py")
+                if os.path.exists(init_file):
+                    spec = importlib.util.spec_from_file_location(item, init_file)
+                    if spec and spec.loader:
+                        module = importlib.util.module_from_spec(spec)
+                        sys.modules[item] = module
+                        spec.loader.exec_module(module)
+
+                        parser_func = getattr(module, "__parser__", None)
+                        if callable(parser_func):
+                            parser_func(parser)
+                            _log(f"Extension {item} parser loaded")
+            except Exception as e:
+                _err(f"Failed to load extension {item} parser", e)
+
+
+def install_extensions():
+    """
+    Scans ensure ~/.llms/extensions/ for directories with __init__.py and loads them as extensions.
+    Calls the `__install__(ctx)` function in the extension module.
+    """
+    extensions_path = get_extensions_path()
+    os.makedirs(extensions_path, exist_ok=True)
+
+    ext_count = len(os.listdir(extensions_path))
+    if ext_count == 0:
+        _log("No extensions found")
+        return
+
+    _log(f"Installing {ext_count} extension{'' if ext_count == 1 else 's'}...")
+
+    sys.path.append(extensions_path)
+
+    for item in os.listdir(extensions_path):
+        item_path = os.path.join(extensions_path, item)
+        if os.path.isdir(item_path):
+            init_file = os.path.join(item_path, "__init__.py")
+            if os.path.exists(init_file):
+                ctx = ExtensionContext(g_app, item_path)
+                try:
+                    spec = importlib.util.spec_from_file_location(item, init_file)
+                    if spec and spec.loader:
+                        module = importlib.util.module_from_spec(spec)
+                        sys.modules[item] = module
+                        spec.loader.exec_module(module)
+
+                        install_func = getattr(module, "__install__", None)
+                        if callable(install_func):
+                            install_func(ctx)
+                            _log(f"Extension {item} installed")
+                        else:
+                            _dbg(f"Extension {item} has no __install__ function")
+                    else:
+                        _dbg(f"Extension {item} has no __init__.py")
+
+                    # if ui folder exists, serve as static files at /ext/{item}/
+                    ui_path = os.path.join(item_path, "ui")
+                    if os.path.exists(ui_path):
+                        ctx.add_static_files(ui_path)
+
+                        # Register UI extension if index.mjs exists (/ext/{item}/index.mjs)
+                        if os.path.exists(os.path.join(ui_path, "index.mjs")):
+                            ctx.register_ui_extension("index.mjs")
+
+                except Exception as e:
+                    _err(f"Failed to install extension {item}", e)
+            else:
+                _dbg(f"Extension {init_file} not found")
+        else:
+            _dbg(f"Extension {item} not found: {item_path} is not a directory {os.path.exists(item_path)}")
+
+
+def run_extension_cli():
+    """
+    Run the CLI for an extension.
+    """
+    extensions_path = get_extensions_path()
+    os.makedirs(extensions_path, exist_ok=True)
+
+    for item in os.listdir(extensions_path):
+        item_path = os.path.join(extensions_path, item)
+        if os.path.isdir(item_path):
+            init_file = os.path.join(item_path, "__init__.py")
+            if os.path.exists(init_file):
+                ctx = ExtensionContext(g_app, item_path)
+                try:
+                    spec = importlib.util.spec_from_file_location(item, init_file)
+                    if spec and spec.loader:
+                        module = importlib.util.module_from_spec(spec)
+                        sys.modules[item] = module
+                        spec.loader.exec_module(module)
+
+                    # Check for __run__ function if exists in __init__.py and call it with ctx
+                    run_func = getattr(module, "__run__", None)
+                    if callable(run_func):
+                        handled = run_func(ctx)
+                        _log(f"Extension {item} was run")
+                        return handled
 
-                    if str(ui_path) not in file_mtimes:
-                        file_mtimes[str(ui_path)] = mtime
-                    elif file_mtimes[str(ui_path)] != mtime:
-                        _log(f"Config file changed: {ui_path.name}")
-                        file_mtimes[str(ui_path)] = mtime
-                        _log("ui.json reloaded - reload page to update")
-            except FileNotFoundError:
-                pass
+                except Exception as e:
+                    _err(f"Failed to run extension {item}", e)
+                    return False
 
 
 def main():
-    global _ROOT, g_verbose, g_default_model, g_logprefix, g_providers, g_config, g_config_path, g_ui_path
+    global _ROOT, g_verbose, g_default_model, g_logprefix, g_providers, g_config, g_config_path, g_app
 
     parser = argparse.ArgumentParser(description=f"llms v{VERSION}")
     parser.add_argument("--config", default=None, help="Path to config file", metavar="FILE")
@@ -2074,6 +2142,7 @@ def main():
     parser.add_argument("--image", default=None, help="Image input to use in chat completion")
     parser.add_argument("--audio", default=None, help="Audio input to use in chat completion")
     parser.add_argument("--file", default=None, help="File input to use in chat completion")
+    parser.add_argument("--out", default=None, help="Image or Video Generation Request", metavar="MODALITY")
     parser.add_argument(
         "--args",
         default=None,
@@ -2096,14 +2165,46 @@ def main():
     parser.add_argument("--default", default=None, help="Configure the default model to use", metavar="MODEL")
 
     parser.add_argument("--init", action="store_true", help="Create a default llms.json")
-    parser.add_argument("--update", action="store_true", help="Update local models.dev providers.json")
+    parser.add_argument("--update-providers", action="store_true", help="Update local models.dev providers.json")
+    parser.add_argument("--update-extensions", action="store_true", help="Update installed extensions")
 
     parser.add_argument("--root", default=None, help="Change root directory for UI files", metavar="PATH")
     parser.add_argument("--logprefix", default="", help="Prefix used in log messages", metavar="PREFIX")
     parser.add_argument("--verbose", action="store_true", help="Verbose output")
 
+    parser.add_argument(
+        "--add",
+        nargs="?",
+        const="ls",
+        default=None,
+        help="Install an extension (lists available extensions if no name provided)",
+        metavar="EXTENSION",
+    )
+    parser.add_argument(
+        "--remove",
+        nargs="?",
+        const="ls",
+        default=None,
+        help="Remove an extension (lists installed extensions if no name provided)",
+        metavar="EXTENSION",
+    )
+
+    parser.add_argument(
+        "--update",
+        nargs="?",
+        const="ls",
+        default=None,
+        help="Update an extension (use 'all' to update all extensions)",
+        metavar="EXTENSION",
+    )
+
+    # Load parser extensions, go through all extensions and load their parser arguments
+    init_extensions(parser)
+
     cli_args, extra_args = parser.parse_known_args()
 
+    g_app = AppExtensions(cli_args, extra_args)
+
     # Check for verbose mode from CLI argument or environment variables
     verbose_env = os.environ.get("VERBOSE", "").lower()
     if cli_args.verbose or verbose_env in ("1", "true"):
@@ -2120,8 +2221,8 @@ def main():
         exit(1)
 
     home_config_path = home_llms_path("llms.json")
-    home_ui_path = home_llms_path("ui.json")
     home_providers_path = home_llms_path("providers.json")
+    home_providers_extra_path = home_llms_path("providers-extra.json")
 
     if cli_args.init:
         if os.path.exists(home_config_path):
@@ -2130,17 +2231,17 @@ def main():
             asyncio.run(save_default_config(home_config_path))
             print(f"Created default config at {home_config_path}")
 
-        if os.path.exists(home_ui_path):
-            print(f"ui.json already exists at {home_ui_path}")
-        else:
-            asyncio.run(save_text_url(github_url("ui.json"), home_ui_path))
-            print(f"Created default ui config at {home_ui_path}")
-
         if os.path.exists(home_providers_path):
             print(f"providers.json already exists at {home_providers_path}")
         else:
             asyncio.run(save_text_url(github_url("providers.json"), home_providers_path))
             print(f"Created default providers config at {home_providers_path}")
+
+        if os.path.exists(home_providers_extra_path):
+            print(f"providers-extra.json already exists at {home_providers_extra_path}")
+        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)
 
     if cli_args.providers:
@@ -2157,38 +2258,171 @@ def main():
             g_config = load_config_json(config_json)
 
         config_dir = os.path.dirname(g_config_path)
-        # look for ui.json in same directory as config
-        ui_path = os.path.join(config_dir, "ui.json")
-        if os.path.exists(ui_path):
-            g_ui_path = ui_path
-        else:
-            if not os.path.exists(home_ui_path):
-                ui_json = text_from_resource("ui.json")
-                with open(home_ui_path, "w", encoding="utf-8") as f:
-                    f.write(ui_json)
-                _log(f"Created default ui config at {home_ui_path}")
-            g_ui_path = home_ui_path
 
         if not g_providers and os.path.exists(os.path.join(config_dir, "providers.json")):
             g_providers = json.loads(text_from_file(os.path.join(config_dir, "providers.json")))
 
     else:
-        # ensure llms.json and ui.json exist in home directory
+        # ensure llms.json and providers.json exist in home directory
         asyncio.run(save_home_configs())
         g_config_path = home_config_path
-        g_ui_path = home_ui_path
         g_config = load_config_json(text_from_file(g_config_path))
 
     if not g_providers:
         g_providers = json.loads(text_from_file(home_providers_path))
 
-    if cli_args.update:
+    if cli_args.update_providers:
         asyncio.run(update_providers(home_providers_path))
         print(f"Updated {home_providers_path}")
         exit(0)
 
+    # if home_providers_path is older than 1 day, update providers list
+    if (
+        os.path.exists(home_providers_path)
+        and (time.time() - os.path.getmtime(home_providers_path)) > 86400
+        and os.environ.get("LLMS_DISABLE_UPDATE", "") != "1"
+    ):
+        try:
+            asyncio.run(update_providers(home_providers_path))
+            _log(f"Updated {home_providers_path}")
+        except Exception as e:
+            _err("Failed to update providers", e)
+
+    if cli_args.add is not None:
+        if cli_args.add == "ls":
+
+            async def list_extensions():
+                print("\nAvailable extensions:")
+                text = await get_text("https://api.github.com/orgs/llmspy/repos?per_page=100&sort=updated")
+                repos = json.loads(text)
+                max_name_length = 0
+                for repo in repos:
+                    max_name_length = max(max_name_length, len(repo["name"]))
+
+                for repo in repos:
+                    print(f"  {repo['name']:<{max_name_length + 2}} {repo['description']}")
+
+                print("\nUsage:")
+                print("  llms --add <extension>")
+                print("  llms --add <github-user>/<repo>")
+
+            asyncio.run(list_extensions())
+            exit(0)
+
+        async def install_extension(name):
+            # Determine git URL and target directory name
+            if "/" in name:
+                git_url = f"https://github.com/{name}"
+                target_name = name.split("/")[-1]
+            else:
+                git_url = f"https://github.com/llmspy/{name}"
+                target_name = name
+
+            # check extension is not already installed
+            extensions_path = get_extensions_path()
+            target_path = os.path.join(extensions_path, target_name)
+
+            if os.path.exists(target_path):
+                print(f"Extension {target_name} is already installed at {target_path}")
+                return
+
+            print(f"Installing extension: {name}")
+            print(f"Cloning from {git_url} to {target_path}...")
+
+            try:
+                subprocess.run(["git", "clone", git_url, target_path], check=True)
+
+                # Check for requirements.txt
+                requirements_path = os.path.join(target_path, "requirements.txt")
+                if os.path.exists(requirements_path):
+                    print(f"Installing dependencies from {requirements_path}...")
+                    subprocess.run(
+                        [sys.executable, "-m", "pip", "install", "-r", "requirements.txt"], cwd=target_path, check=True
+                    )
+                    print("Dependencies installed successfully.")
+
+                print(f"Extension {target_name} installed successfully.")
+
+            except subprocess.CalledProcessError as e:
+                print(f"Failed to install extension: {e}")
+                # cleanup if clone failed but directory was created (unlikely with simple git clone but good practice)
+                if os.path.exists(target_path) and not os.listdir(target_path):
+                    os.rmdir(target_path)
+
+        asyncio.run(install_extension(cli_args.add))
+        exit(0)
+
+    if cli_args.remove is not None:
+        if cli_args.remove == "ls":
+            # List installed extensions
+            extensions_path = get_extensions_path()
+            extensions = os.listdir(extensions_path)
+            if len(extensions) == 0:
+                print("No extensions installed.")
+                exit(0)
+            print("Installed extensions:")
+            for extension in extensions:
+                print(f"  {extension}")
+            exit(0)
+        # Remove an extension
+        extension_name = cli_args.remove
+        extensions_path = get_extensions_path()
+        target_path = os.path.join(extensions_path, extension_name)
+
+        if not os.path.exists(target_path):
+            print(f"Extension {extension_name} not found at {target_path}")
+            exit(1)
+
+        print(f"Removing extension: {extension_name}...")
+        try:
+            shutil.rmtree(target_path)
+            print(f"Extension {extension_name} removed successfully.")
+        except Exception as e:
+            print(f"Failed to remove extension: {e}")
+            exit(1)
+
+        exit(0)
+
+    if cli_args.update:
+        if cli_args.update == "ls":
+            # List installed extensions
+            extensions_path = get_extensions_path()
+            extensions = os.listdir(extensions_path)
+            if len(extensions) == 0:
+                print("No extensions installed.")
+                exit(0)
+            print("Installed extensions:")
+            for extension in extensions:
+                print(f"  {extension}")
+
+            print("\nUsage:")
+            print("  llms --update <extension>")
+            print("  llms --update all")
+            exit(0)
+
+        async def update_extensions(extension_name):
+            extensions_path = get_extensions_path()
+            for extension in os.listdir(extensions_path):
+                extension_path = os.path.join(extensions_path, extension)
+                if os.path.isdir(extension_path):
+                    if extension_name != "all" and extension != extension_name:
+                        continue
+                    result = subprocess.run(["git", "pull"], cwd=extension_path, capture_output=True)
+                    if result.returncode != 0:
+                        print(f"Failed to update extension {extension}: {result.stderr.decode('utf-8')}")
+                        continue
+                    print(f"Updated extension {extension}")
+                    _log(result.stdout.decode("utf-8"))
+
+        asyncio.run(update_extensions(cli_args.update))
+        exit(0)
+
+    load_builtin_extensions()
+
     asyncio.run(reload_providers())
 
+    install_extensions()
+
     # print names
     _log(f"enabled providers: {', '.join(g_handlers.keys())}")
 
@@ -2261,10 +2495,6 @@ def main():
         # Start server
         port = int(cli_args.serve)
 
-        if not os.path.exists(g_ui_path):
-            print(f"UI not found at {g_ui_path}")
-            exit(1)
-
         # Validate auth configuration if enabled
         auth_enabled = g_config.get("auth", {}).get("enabled", False)
         if auth_enabled:
@@ -2274,11 +2504,19 @@ def main():
 
             # Expand environment variables
             if client_id.startswith("$"):
-                client_id = os.environ.get(client_id[1:], "")
+                client_id = client_id[1:]
             if client_secret.startswith("$"):
-                client_secret = os.environ.get(client_secret[1:], "")
+                client_secret = client_secret[1:]
 
-            if not client_id or not client_secret:
+            client_id = os.environ.get(client_id, client_id)
+            client_secret = os.environ.get(client_secret, client_secret)
+
+            if (
+                not client_id
+                or not client_secret
+                or client_id == "GITHUB_CLIENT_ID"
+                or client_secret == "GITHUB_CLIENT_SECRET"
+            ):
                 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")
@@ -2299,7 +2537,7 @@ def main():
                 return True, None
 
             # Check for OAuth session token
-            session_token = request.query.get("session") or request.headers.get("X-Session-Token")
+            session_token = get_session_token(request)
             if session_token and session_token in g_sessions:
                 return True, g_sessions[session_token]
 
@@ -2329,13 +2567,32 @@ def main():
 
             try:
                 chat = await request.json()
+
+                # Apply pre-chat filters
+                context = {"request": request}
+                # Apply pre-chat filters
+                context = {"request": request}
+                for filter_func in g_app.chat_request_filters:
+                    chat = await filter_func(chat, context)
+
                 response = await chat_completion(chat)
+
+                # Apply post-chat filters
+                # Apply post-chat filters
+                for filter_func in g_app.chat_response_filters:
+                    response = await filter_func(response, context)
+
                 return web.json_response(response)
             except Exception as e:
                 return web.json_response({"error": str(e)}, status=500)
 
         app.router.add_post("/v1/chat/completions", chat_handler)
 
+        async def extensions_handler(request):
+            return web.json_response(g_app.ui_extensions)
+
+        app.router.add_get("/ext", extensions_handler)
+
         async def models_handler(request):
             return web.json_response(get_models())
 
@@ -2370,8 +2627,9 @@ def main():
             if provider:
                 if data.get("enable", False):
                     provider_config, msg = enable_provider(provider)
-                    _log(f"Enabled provider {provider}")
-                    await load_llms()
+                    _log(f"Enabled provider {provider} {msg}")
+                    if not msg:
+                        await load_llms()
                 elif data.get("disable", False):
                     disable_provider(provider)
                     _log(f"Disabled provider {provider}")
@@ -2491,7 +2749,7 @@ def main():
                 except Exception:
                     return web.Response(text="403: Forbidden", status=403)
 
-                with open(info_path, "r") as f:
+                with open(info_path) as f:
                     content = f.read()
                 return web.Response(text=content, content_type="application/json")
 
@@ -2527,9 +2785,12 @@ def main():
 
             # Expand environment variables
             if client_id.startswith("$"):
-                client_id = os.environ.get(client_id[1:], "")
+                client_id = client_id[1:]
             if redirect_uri.startswith("$"):
-                redirect_uri = os.environ.get(redirect_uri[1:], "")
+                redirect_uri = redirect_uri[1:]
+
+            client_id = os.environ.get(client_id, client_id)
+            redirect_uri = os.environ.get(redirect_uri, redirect_uri)
 
             if not client_id:
                 return web.json_response({"error": "GitHub client_id not configured"}, status=500)
@@ -2562,7 +2823,9 @@ def main():
 
             # Expand environment variables
             if restrict_to.startswith("$"):
-                restrict_to = os.environ.get(restrict_to[1:], "")
+                restrict_to = restrict_to[1:]
+
+            restrict_to = os.environ.get(restrict_to, None if restrict_to == "GITHUB_USERS" else restrict_to)
 
             # If restrict_to is configured, validate the user
             if restrict_to:
@@ -2583,6 +2846,14 @@ def main():
             code = request.query.get("code")
             state = request.query.get("state")
 
+            # Handle malformed URLs where query params are appended with & instead of ?
+            if not code and "tail" in request.match_info:
+                tail = request.match_info["tail"]
+                if tail.startswith("&"):
+                    params = parse_qs(tail[1:])
+                    code = params.get("code", [None])[0]
+                    state = params.get("state", [None])[0]
+
             if not code or not state:
                 return web.Response(text="Missing code or state parameter", status=400)
 
@@ -2602,11 +2873,15 @@ def main():
 
             # Expand environment variables
             if client_id.startswith("$"):
-                client_id = os.environ.get(client_id[1:], "")
+                client_id = client_id[1:]
             if client_secret.startswith("$"):
-                client_secret = os.environ.get(client_secret[1:], "")
+                client_secret = client_secret[1:]
             if redirect_uri.startswith("$"):
-                redirect_uri = os.environ.get(redirect_uri[1:], "")
+                redirect_uri = redirect_uri[1:]
+
+            client_id = os.environ.get(client_id, client_id)
+            client_secret = os.environ.get(client_secret, client_secret)
+            redirect_uri = os.environ.get(redirect_uri, redirect_uri)
 
             if not client_id or not client_secret:
                 return web.json_response({"error": "GitHub OAuth credentials not configured"}, status=500)
@@ -2654,11 +2929,13 @@ def main():
             }
 
             # Redirect to UI with session token
-            return web.HTTPFound(f"/?session={session_token}")
+            response = web.HTTPFound(f"/?session={session_token}")
+            response.set_cookie("llms-token", session_token, httponly=True, path="/", max_age=86400)
+            return response
 
         async def session_handler(request):
             """Validate and return session info"""
-            session_token = request.query.get("session") or request.headers.get("X-Session-Token")
+            session_token = get_session_token(request)
 
             if not session_token or session_token not in g_sessions:
                 return web.json_response({"error": "Invalid or expired session"}, status=401)
@@ -2675,17 +2952,19 @@ def main():
 
         async def logout_handler(request):
             """End OAuth session"""
-            session_token = request.query.get("session") or request.headers.get("X-Session-Token")
+            session_token = get_session_token(request)
 
             if session_token and session_token in g_sessions:
                 del g_sessions[session_token]
 
-            return web.json_response({"success": True})
+            response = web.json_response({"success": True})
+            response.del_cookie("llms-token")
+            return response
 
         async def auth_handler(request):
             """Check authentication status and return user info"""
             # Check for OAuth session token
-            session_token = request.query.get("session") or request.headers.get("X-Session-Token")
+            session_token = get_session_token(request)
 
             if session_token and session_token in g_sessions:
                 session_data = g_sessions[session_token]
@@ -2722,6 +3001,7 @@ def main():
         app.router.add_get("/auth", auth_handler)
         app.router.add_get("/auth/github", github_auth_handler)
         app.router.add_get("/auth/github/callback", github_callback_handler)
+        app.router.add_get("/auth/github/callback{tail:.*}", github_callback_handler)
         app.router.add_get("/auth/session", session_handler)
         app.router.add_post("/auth/logout", logout_handler)
 
@@ -2756,25 +3036,30 @@ def main():
 
         app.router.add_get("/ui/{path:.*}", ui_static, name="ui_static")
 
-        async def ui_config_handler(request):
-            with open(g_ui_path, encoding="utf-8") as f:
-                ui = json.load(f)
-                if "defaults" not in ui:
-                    ui["defaults"] = g_config["defaults"]
-                enabled, disabled = provider_status()
-                ui["status"] = {"all": list(g_config["providers"].keys()), "enabled": enabled, "disabled": disabled}
-                # Add auth configuration
-                ui["requiresAuth"] = auth_enabled
-                ui["authType"] = "oauth" if auth_enabled else "apikey"
-                return web.json_response(ui)
+        async def config_handler(request):
+            ret = {}
+            if "defaults" not in ret:
+                ret["defaults"] = g_config["defaults"]
+            enabled, disabled = provider_status()
+            ret["status"] = {"all": list(g_config["providers"].keys()), "enabled": enabled, "disabled": disabled}
+            # Add auth configuration
+            ret["requiresAuth"] = auth_enabled
+            ret["authType"] = "oauth" if auth_enabled else "apikey"
+            return web.json_response(ret)
 
-        app.router.add_get("/config", ui_config_handler)
+        app.router.add_get("/config", config_handler)
 
         async def not_found_handler(request):
             return web.Response(text="404: Not Found", status=404)
 
         app.router.add_get("/favicon.ico", not_found_handler)
 
+        # go through and register all g_app extensions
+        for handler in g_app.server_add_get:
+            app.router.add_get(handler[0], handler[1], **handler[2])
+        for handler in g_app.server_add_post:
+            app.router.add_post(handler[0], handler[1], **handler[2])
+
         # Serve index.html from root
         async def index_handler(request):
             index_content = read_resource_file_bytes("index.html")
@@ -2791,10 +3076,12 @@ def main():
         async def start_background_tasks(app):
             """Start background tasks when the app starts"""
             # Start watching config files in the background
-            asyncio.create_task(watch_config_files(g_config_path, g_ui_path))
+            asyncio.create_task(watch_config_files(g_config_path, home_providers_path))
 
         app.on_startup.append(start_background_tasks)
 
+        # go through and register all g_app extensions
+
         print(f"Starting server on port {port}...")
         web.run_app(app, host="0.0.0.0", port=port, print=_log)
         exit(0)
@@ -2869,6 +3156,7 @@ def main():
         or cli_args.image is not None
         or cli_args.audio is not None
         or cli_args.file is not None
+        or cli_args.out is not None
         or len(extra_args) > 0
     ):
         try:
@@ -2879,6 +3167,12 @@ def main():
                 chat = g_config["defaults"]["audio"]
             elif cli_args.file is not None:
                 chat = g_config["defaults"]["file"]
+            elif cli_args.out is not None:
+                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)
+                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):
@@ -2922,9 +3216,14 @@ def main():
                 traceback.print_exc()
             exit(1)
 
-    # show usage from ArgumentParser
-    parser.print_help()
+    handled = run_extension_cli()
+
+    if not handled:
+        # show usage from ArgumentParser
+        parser.print_help()
 
 
 if __name__ == "__main__":
+    if MOCK or DEBUG:
+        print(f"MOCK={MOCK} or DEBUG={DEBUG}")
     main()