lm-deluge 0.0.56__py3-none-any.whl → 0.0.69__py3-none-any.whl

lm_deluge/tool.py

@@ -1,7 +1,17 @@
 import asyncio
 import inspect
 from concurrent.futures import ThreadPoolExecutor
-from typing import Any, Callable, Coroutine, Literal, TypedDict, get_type_hints
+from typing import (
+    Any,
+    Callable,
+    Coroutine,
+    Literal,
+    Type,
+    TypedDict,
+    get_args,
+    get_origin,
+    get_type_hints,
+)
 
 from fastmcp import Client  # pip install fastmcp >= 2.0
 from mcp.types import Tool as MCPTool
@@ -11,6 +21,196 @@ from lm_deluge.image import Image
 from lm_deluge.prompt import Text, ToolResultPart
 
 
+def _python_type_to_json_schema_enhanced(python_type: Any) -> dict[str, Any]:
+    """
+    Convert Python type annotations to JSON Schema.
+    Handles: primitives, Optional, Literal, list[T], dict[str, T], Union.
+    """
+    # Get origin and args for generic types
+    origin = get_origin(python_type)
+    args = get_args(python_type)
+
+    # Handle Optional[T] or T | None
+    if origin is type(None) or python_type is type(None):
+        return {"type": "null"}
+
+    # Handle Union types (including Optional)
+    if origin is Literal:
+        # Literal["a", "b"] -> enum
+        return {"type": "string", "enum": list(args)}
+
+    # Handle list[T]
+    if origin is list:
+        if args:
+            items_schema = _python_type_to_json_schema_enhanced(args[0])
+            return {"type": "array", "items": items_schema}
+        return {"type": "array"}
+
+    # Handle dict[str, T]
+    if origin is dict:
+        if len(args) >= 2:
+            # For dict[str, T], we can set additionalProperties
+            value_schema = _python_type_to_json_schema_enhanced(args[1])
+            return {"type": "object", "additionalProperties": value_schema}
+        return {"type": "object"}
+
+    # Handle basic types
+    if python_type is int:
+        return {"type": "integer"}
+    elif python_type is float:
+        return {"type": "number"}
+    elif python_type is str:
+        return {"type": "string"}
+    elif python_type is bool:
+        return {"type": "boolean"}
+    elif python_type is list:
+        return {"type": "array"}
+    elif python_type is dict:
+        return {"type": "object"}
+    else:
+        # Default to string for unknown types
+        return {"type": "string"}
+
+
+class ToolParams:
+    """
+    Helper class for constructing tool parameters more easily.
+
+    Usage:
+        # Simple constructor with Python types
+        params = ToolParams({"city": str, "age": int})
+
+        # With extras (description, enum, etc)
+        params = ToolParams({
+            "operation": (str, {"enum": ["add", "sub"], "description": "Math operation"}),
+            "value": (int, {"description": "The value"})
+        })
+
+        # From Pydantic model
+        params = ToolParams.from_pydantic(MyModel)
+
+        # From TypedDict
+        params = ToolParams.from_typed_dict(MyTypedDict)
+
+        # From existing JSON Schema
+        params = ToolParams.from_json_schema(schema_dict, required=["field1"])
+    """
+
+    def __init__(self, spec: dict[str, Any]):
+        """
+        Create ToolParams from a dict mapping parameter names to types or (type, extras) tuples.
+
+        Args:
+            spec: Dict where values can be:
+                - A Python type (str, int, list[str], etc.)
+                - A tuple of (type, extras_dict) for additional JSON Schema properties
+                - An already-formed JSON Schema dict (passed through as-is)
+        """
+        self.parameters: dict[str, Any] = {}
+        self.required: list[str] = []
+
+        for param_name, param_spec in spec.items():
+            # If it's a tuple, extract (type, extras)
+            if isinstance(param_spec, tuple):
+                param_type, extras = param_spec
+                schema = _python_type_to_json_schema_enhanced(param_type)
+                schema.update(extras)
+                self.parameters[param_name] = schema
+                # Mark as required unless explicitly marked as optional
+                if extras.get("optional") is not True:
+                    self.required.append(param_name)
+            # If it's already a dict with "type" key, use as-is
+            elif isinstance(param_spec, dict) and "type" in param_spec:
+                self.parameters[param_name] = param_spec
+                # Assume required unless marked optional
+                if param_spec.get("optional") is not True:
+                    self.required.append(param_name)
+            # Otherwise treat as a Python type
+            else:
+                self.parameters[param_name] = _python_type_to_json_schema_enhanced(
+                    param_spec
+                )
+                self.required.append(param_name)
+
+    @classmethod
+    def from_pydantic(cls, model: Type[BaseModel]) -> "ToolParams":
+        """
+        Create ToolParams from a Pydantic model.
+
+        Args:
+            model: A Pydantic BaseModel class
+        """
+        # Get the JSON schema from Pydantic
+        schema = model.model_json_schema()
+        properties = schema.get("properties", {})
+        required = schema.get("required", [])
+
+        return cls.from_json_schema(properties, required)
+
+    @classmethod
+    def from_typed_dict(cls, typed_dict: Type) -> "ToolParams":
+        """
+        Create ToolParams from a TypedDict.
+
+        Args:
+            typed_dict: A TypedDict class
+        """
+        hints = get_type_hints(typed_dict)
+
+        # TypedDict doesn't have a built-in way to mark optional fields,
+        # but we can check for Optional in the type hints
+        params = {}
+        required = []
+
+        for field_name, field_type in hints.items():
+            # Check if it's Optional (Union with None)
+            origin = get_origin(field_type)
+            # args = get_args(field_type)
+
+            is_optional = False
+            actual_type = field_type
+
+            # Check for Union types (including Optional[T] which is Union[T, None])
+            if origin is type(None):
+                is_optional = True
+                actual_type = type(None)
+
+            # For now, treat all TypedDict fields as required unless they're explicitly Optional
+            schema = _python_type_to_json_schema_enhanced(actual_type)
+            params[field_name] = schema
+
+            if not is_optional:
+                required.append(field_name)
+
+        instance = cls.__new__(cls)
+        instance.parameters = params
+        instance.required = required
+        return instance
+
+    @classmethod
+    def from_json_schema(
+        cls, properties: dict[str, Any], required: list[str] | None = None
+    ) -> "ToolParams":
+        """
+        Create ToolParams from an existing JSON Schema properties dict.
+
+        Args:
+            properties: The "properties" section of a JSON Schema
+            required: List of required field names
+        """
+        instance = cls.__new__(cls)
+        instance.parameters = properties
+        instance.required = required or []
+        return instance
+
+    def to_dict(self) -> dict[str, Any]:
+        """
+        Convert to a dict with 'parameters' and 'required' keys.
+        Useful for unpacking into Tool constructor.
+        """
+        return {"parameters": self.parameters, "required": self.required}
+
+
 async def _load_all_mcp_tools(client: Client) -> list["Tool"]:
     metas: list[MCPTool] = await client.list_tools()
 
@@ -39,6 +239,9 @@ async def _load_all_mcp_tools(client: Client) -> list["Tool"]:
 
     tools: list[Tool] = []
     for m in metas:
+        # Extract definitions from the schema (could be $defs or definitions)
+        definitions = m.inputSchema.get("$defs") or m.inputSchema.get("definitions")
+
         tools.append(
             Tool(
                 name=m.name,
@@ -46,6 +249,7 @@ async def _load_all_mcp_tools(client: Client) -> list["Tool"]:
                 parameters=m.inputSchema.get("properties", {}),
                 required=m.inputSchema.get("required", []),
                 additionalProperties=m.inputSchema.get("additionalProperties"),
+                definitions=definitions,
                 run=make_runner(m.name),
             )
         )
@@ -68,6 +272,8 @@ class Tool(BaseModel):
     is_built_in: bool = False
     type: str | None = None
     built_in_args: dict[str, Any] = Field(default_factory=dict)
+    # JSON Schema definitions (for $ref support)
+    definitions: dict[str, Any] | None = None
 
     @field_validator("name")
     @classmethod
@@ -79,6 +285,24 @@ class Tool(BaseModel):
             )
         return v
 
+    @field_validator("parameters", mode="before")
+    @classmethod
+    def validate_parameters(cls, v: Any) -> dict[str, Any] | None:
+        """Accept ToolParams objects and convert to dict for backwards compatibility."""
+        if isinstance(v, ToolParams):
+            return v.parameters
+        return v
+
+    def model_post_init(self, __context: Any) -> None:
+        """
+        After validation, if parameters came from ToolParams, also update required list.
+        This is called by Pydantic after __init__.
+        """
+        # This is a bit tricky - we need to capture the required list from ToolParams
+        # Since Pydantic has already converted it in the validator, we can't access it here
+        # Instead, we'll handle this differently in the convenience constructors
+        pass
+
     def _is_async(self) -> bool:
         return inspect.iscoroutinefunction(self.run)
 
@@ -143,7 +367,7 @@ class Tool(BaseModel):
             param_type = type_hints.get(param_name, str)
 
             # Convert Python types to JSON Schema types
-            json_type = cls._python_type_to_json_schema(param_type)
+            json_type = _python_type_to_json_schema_enhanced(param_type)
 
             parameters[param_name] = json_type
 
@@ -209,6 +433,119 @@ class Tool(BaseModel):
                 return t
         raise ValueError(f"Tool '{tool_name}' not found on that server")
 
+    @classmethod
+    def from_params(
+        cls,
+        name: str,
+        params: ToolParams,
+        *,
+        description: str | None = None,
+        run: Callable | None = None,
+        **kwargs,
+    ) -> "Tool":
+        """
+        Create a Tool from a ToolParams object.
+
+        Args:
+            name: Tool name
+            params: ToolParams object defining the parameter schema
+            description: Optional description
+            run: Optional callable to execute the tool
+            **kwargs: Additional Tool arguments
+
+        Example:
+            params = ToolParams({"city": str, "age": int})
+            tool = Tool.from_params("get_user", params, run=my_function)
+        """
+        return cls(
+            name=name,
+            description=description,
+            parameters=params.parameters,
+            required=params.required,
+            run=run,
+            **kwargs,
+        )
+
+    @classmethod
+    def from_pydantic(
+        cls,
+        name: str,
+        model: Type[BaseModel],
+        *,
+        description: str | None = None,
+        run: Callable | None = None,
+        **kwargs,
+    ) -> "Tool":
+        """
+        Create a Tool from a Pydantic model.
+
+        Args:
+            name: Tool name
+            model: Pydantic BaseModel class
+            description: Optional description (defaults to model docstring)
+            run: Optional callable to execute the tool
+            **kwargs: Additional Tool arguments
+
+        Example:
+            class UserQuery(BaseModel):
+                city: str
+                age: int
+
+            tool = Tool.from_pydantic("get_user", UserQuery, run=my_function)
+        """
+        params = ToolParams.from_pydantic(model)
+
+        # Use model docstring as default description if not provided
+        if description is None and model.__doc__:
+            description = model.__doc__.strip()
+
+        return cls(
+            name=name,
+            description=description,
+            parameters=params.parameters,
+            required=params.required,
+            run=run,
+            **kwargs,
+        )
+
+    @classmethod
+    def from_typed_dict(
+        cls,
+        name: str,
+        typed_dict: Type,
+        *,
+        description: str | None = None,
+        run: Callable | None = None,
+        **kwargs,
+    ) -> "Tool":
+        """
+        Create a Tool from a TypedDict.
+
+        Args:
+            name: Tool name
+            typed_dict: TypedDict class
+            description: Optional description
+            run: Optional callable to execute the tool
+            **kwargs: Additional Tool arguments
+
+        Example:
+            class UserQuery(TypedDict):
+                city: str
+                age: int
+
+            tool = Tool.from_typed_dict("get_user", UserQuery, run=my_function)
+        """
+        params = ToolParams.from_typed_dict(typed_dict)
+
+        return cls(
+            name=name,
+            description=description,
+            parameters=params.parameters,
+            required=params.required,
+            run=run,
+            **kwargs,
+        )
+
     @staticmethod
     def _tool_from_meta(meta: dict[str, Any], runner) -> "Tool":
         props = meta["inputSchema"].get("properties", {})
@@ -225,22 +562,39 @@ class Tool(BaseModel):
 
     @staticmethod
     def _python_type_to_json_schema(python_type) -> dict[str, Any]:
-        """Convert Python type to JSON Schema type definition."""
-        if python_type is int:
-            return {"type": "integer"}
-        elif python_type is float:
-            return {"type": "number"}
-        elif python_type is str:
-            return {"type": "string"}
-        elif python_type is bool:
-            return {"type": "boolean"}
-        elif python_type is list:
-            return {"type": "array"}
-        elif python_type is dict:
-            return {"type": "object"}
-        else:
-            # Default to string for unknown types
-            return {"type": "string"}
+        """
+        Convert Python type to JSON Schema type definition.
+        Now delegates to enhanced version for better type support.
+        """
+        return _python_type_to_json_schema_enhanced(python_type)
+
+    def _is_strict_mode_compatible(self) -> bool:
+        """
+        Check if this tool's schema is compatible with OpenAI strict mode.
+        Strict mode requires all objects to have defined properties.
+        """
+
+        def has_undefined_objects(schema: dict | list | Any) -> bool:
+            """Recursively check for objects without defined properties."""
+            if isinstance(schema, dict):
+                # Check if this is an object type without properties
+                if schema.get("type") == "object":
+                    # If additionalProperties is True or properties is missing/empty
+                    if schema.get("additionalProperties") is True:
+                        return True
+                    if "properties" not in schema or not schema["properties"]:
+                        return True
+                # Recursively check nested schemas
+                for value in schema.values():
+                    if has_undefined_objects(value):
+                        return True
+            elif isinstance(schema, list):
+                for item in schema:
+                    if has_undefined_objects(item):
+                        return True
+            return False
+
+        return not has_undefined_objects(self.parameters or {})
 
     def _json_schema(
         self, include_additional_properties=False, remove_defaults=False
@@ -248,7 +602,8 @@ class Tool(BaseModel):
         def _add_additional_properties_recursive(
             schema: dict | list | Any, remove_defaults: bool = False
         ) -> dict | list | Any:
-            """Recursively add additionalProperties: false to all object-type schemas."""
+            """Recursively add additionalProperties: false to all object-type schemas.
+            In strict mode (when remove_defaults=True), also makes all properties required."""
             if isinstance(schema, dict):
                 # Copy the dictionary to avoid modifying the original
                 new_schema = schema.copy()
@@ -264,6 +619,10 @@ class Tool(BaseModel):
                 if new_schema.get("type") == "object":
                     new_schema["additionalProperties"] = False
 
+                    # In strict mode, all properties must be required
+                    if remove_defaults and "properties" in new_schema:
+                        new_schema["required"] = list(new_schema["properties"].keys())
+
                 # Remove default values if requested (for strict mode)
                 if remove_defaults and "default" in new_schema:
                     del new_schema["default"]
@@ -294,6 +653,14 @@ class Tool(BaseModel):
         else:
             processed_parameters = self.parameters
 
+        # Process definitions too
+        if self.definitions and include_additional_properties:
+            processed_definitions = _add_additional_properties_recursive(
+                self.definitions, remove_defaults
+            )
+        else:
+            processed_definitions = self.definitions
+
         res = {
             "type": "object",
             "properties": processed_parameters,
@@ -303,6 +670,10 @@ class Tool(BaseModel):
         if include_additional_properties:
             res["additionalProperties"] = False
 
+        # Include definitions if present (for $ref support)
+        if processed_definitions:
+            res["$defs"] = processed_definitions
+
         return res
 
     # ---------- dumpers ----------
@@ -311,6 +682,11 @@ class Tool(BaseModel):
     ) -> dict[str, Any]:
         if self.is_built_in:
             return {"type": self.type, **self.built_in_args, **kwargs}
+
+        # Check if schema is compatible with strict mode
+        if strict and not self._is_strict_mode_compatible():
+            strict = False
+
         if strict:
             # For strict mode, remove defaults and make all parameters required
             schema = self._json_schema(

lm_deluge/tracker.py

@@ -171,20 +171,24 @@ class StatusTracker:
             )
 
         # Display cumulative usage stats if available
-        if self.total_cost > 0 or self.total_input_tokens > 0 or self.total_output_tokens > 0:
+        if (
+            self.total_cost > 0
+            or self.total_input_tokens > 0
+            or self.total_output_tokens > 0
+        ):
             usage_parts = []
             if self.total_cost > 0:
-                usage_parts.append(f"Cost: ${self.total_cost:.4f}")
+                usage_parts.append(f"💰 Cost: ${self.total_cost:.4f}")
             if self.total_input_tokens > 0 or self.total_output_tokens > 0:
                 usage_parts.append(
-                    f"Tokens: {self.total_input_tokens:,} in / {self.total_output_tokens:,} out"
+                    f"🔡 Tokens: {self.total_input_tokens:,} in / {self.total_output_tokens:,} out"
                 )
             if self.total_cache_read_tokens > 0:
                 usage_parts.append(f"Cache: {self.total_cache_read_tokens:,} read")
             if self.total_cache_write_tokens > 0:
                 usage_parts.append(f"{self.total_cache_write_tokens:,} write")
 
-            print(" | ".join(usage_parts))
+            print("  ", " • ".join(usage_parts))
 
     @property
     def pbar(self) -> tqdm | None:
@@ -288,7 +292,9 @@ class StatusTracker:
                     usage_text = f"   [gold3]Usage:[/gold3] {' • '.join(usage_parts)}"
 
                 if usage_text:
-                    display = Group(self._rich_progress, in_progress, capacity_text, usage_text)
+                    display = Group(
+                        self._rich_progress, in_progress, capacity_text, usage_text
+                    )
                 else:
                     display = Group(self._rich_progress, in_progress, capacity_text)
                 live.update(display)

lm_deluge/warnings.py

@@ -0,0 +1,46 @@
+import functools
+import os
+import warnings
+
+WARNINGS: dict[str, str] = {
+    "WARN_JSON_MODE_UNSUPPORTED": "JSON mode requested for {model_name} but response_format parameter not supported.",
+    "WARN_REASONING_UNSUPPORTED": "Ignoring reasoning_effort param for non-reasoning model: {model_name}.",
+    "WARN_CACHING_UNSUPPORTED": "Cache parameter '{cache_param}' is not supported, ignoring for {model_name}.",
+    "WARN_LOGPROBS_UNSUPPORTED": "Ignoring logprobs param for non-logprobs model: {model_name}",
+}
+
+
+def maybe_warn(warning: str, **kwargs):
+    if os.getenv(warning):
+        pass
+    else:
+        warnings.warn(WARNINGS[warning].format(**kwargs))
+        os.environ[warning] = "1"
+
+
+def deprecated(replacement: str):
+    """Decorator to mark methods as deprecated and suggest replacement.
+
+    Only shows the warning once per method to avoid spam.
+
+    Args:
+        replacement: The name of the replacement method to suggest
+    """
+
+    def decorator(func):
+        warning_key = f"DEPRECATED_{func.__module__}_{func.__qualname__}"
+
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):
+            if not os.getenv(warning_key):
+                warnings.warn(
+                    f"{func.__name__} is deprecated, use {replacement} instead",
+                    DeprecationWarning,
+                    stacklevel=2,
+                )
+                os.environ[warning_key] = "1"
+            return func(*args, **kwargs)
+
+        return wrapper
+
+    return decorator

{lm_deluge-0.0.56.dist-info → lm_deluge-0.0.69.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lm_deluge
-Version: 0.0.56
+Version: 0.0.69
 Summary: Python utility for using LLM API models.
 Author-email: Benjamin Anderson <ben@trytaylor.ai>
 Requires-Python: >=3.10
@@ -23,6 +23,8 @@ Requires-Dist: pdf2image
 Requires-Dist: pillow
 Requires-Dist: fastmcp>=2.4
 Requires-Dist: rich
+Provides-Extra: openai
+Requires-Dist: openai>=1.0.0; extra == "openai"
 Dynamic: license-file
 
 # lm-deluge