liteai-sdk 0.3.21__py3-none-any.whl

liteai_sdk/__init__.py

@@ -0,0 +1,264 @@
+import asyncio
+import queue
+from typing import cast
+from collections.abc import AsyncGenerator, Generator
+from litellm import CustomStreamWrapper, completion, acompletion
+from litellm.exceptions import (  
+    AuthenticationError,
+    PermissionDeniedError,
+    RateLimitError,
+    ContextWindowExceededError,
+    BadRequestError,
+    InvalidRequestError,
+    InternalServerError,
+    ServiceUnavailableError,
+    ContentPolicyViolationError,
+    APIError,
+    Timeout,
+)
+from litellm.utils import get_valid_models
+from litellm.types.utils import LlmProviders,\
+                                ModelResponse as LiteLlmModelResponse,\
+                                ModelResponseStream as LiteLlmModelResponseStream,\
+                                Choices as LiteLlmModelResponseChoices
+from .debug import enable_debugging
+from .param_parser import ParamParser
+from .stream import AssistantMessageCollector
+from .tool import ToolFn, ToolDef, RawToolDef, ToolLike
+from .tool.execute import execute_tool_sync, execute_tool
+from .tool.utils import find_tool_by_name
+from .types import LlmRequestParams, GenerateTextResponse, StreamTextResponseSync, StreamTextResponseAsync
+from .types.exceptions import *
+from .types.message import ChatMessage, UserMessage, SystemMessage, AssistantMessage, ToolMessage,\
+                           MessageChunk, TextChunk, ReasoningChunk, AudioChunk, ImageChunk, ToolCallChunk,\
+                           ToolCallTuple, openai_chunk_normalizer
+from .logger import logger, enable_logging
+
+class LLM:
+    """
+    The `generate_text` and `stream_text` API will return ToolMessage in the returned sequence
+    only if `params.execute_tools` is True.
+
+    - - -
+
+    Possible exceptions raises for `generate_text` and `stream_text`:
+        - AuthenticationError
+        - PermissionDeniedError
+        - RateLimitError
+        - ContextWindowExceededError
+        - BadRequestError
+        - InvalidRequestError
+        - InternalServerError
+        - ServiceUnavailableError
+        - ContentPolicyViolationError
+        - APIError
+        - Timeout
+    """
+
+    def __init__(self,
+                 provider: LlmProviders,
+                 base_url: str,
+                 api_key: str):
+        self.provider = provider
+        self.base_url = base_url
+        self.api_key = api_key
+        self._param_parser = ParamParser(self.provider, self.base_url, self.api_key)
+
+    @staticmethod
+    def _should_resolve_tool_calls(
+            params: LlmRequestParams,
+            message: AssistantMessage,
+            ) -> tuple[list[ToolLike],
+                       list[ToolCallTuple]] | None:
+        parsed_tool_calls = message.parse_tool_calls()
+        condition = params.execute_tools and\
+                    params.tools is not None and\
+                    parsed_tool_calls is not None
+        if condition:
+            assert params.tools is not None
+            assert parsed_tool_calls is not None
+            return params.tools, parsed_tool_calls
+        return None
+
+    @staticmethod
+    async def _execute_tool_calls(
+        tools: list[ToolLike],
+        tool_call_tuples: list[ToolCallTuple]
+        ) -> list[ToolMessage]:
+        results = []
+        for tool_call_tuple in tool_call_tuples:
+            id, function_name, function_arguments = tool_call_tuple
+            if (target_tool := find_tool_by_name(tools, function_name)) is None:
+                logger.warning(f"Tool \"{function_name}\" not found, skipping execution.")
+                continue
+            if isinstance(target_tool, dict):
+                logger.warning(f"Tool \"{function_name}\" is a raw tool, skipping execution.")
+                continue
+
+            result, error = None, None
+            try:
+                result = await execute_tool(target_tool, function_arguments)
+            except Exception as e:
+                error = f"{type(e).__name__}: {str(e)}"
+            results.append(ToolMessage(
+                id=id,
+                name=function_name,
+                arguments=function_arguments,
+                result=result,
+                error=error).with_tool_def(target_tool))
+        return results
+
+    @staticmethod
+    def _execute_tool_calls_sync(
+        tools: list[ToolLike],
+        tool_call_tuples: list[ToolCallTuple]
+        ) -> list[ToolMessage]:
+        results = []
+        for tool_call_tuple in tool_call_tuples:
+            id, function_name, function_arguments = tool_call_tuple
+            if (target_tool := find_tool_by_name(tools, function_name)) is None:
+                logger.warning(f"Tool \"{function_name}\" not found, skipping execution.")
+                continue
+            if isinstance(target_tool, dict):
+                logger.warning(f"Tool \"{function_name}\" is a raw tool, skipping execution.")
+                continue
+
+            result, error = None, None
+            try:
+                result = execute_tool_sync(target_tool, function_arguments)
+            except Exception as e:
+                error = f"{type(e).__name__}: {str(e)}"
+            results.append(ToolMessage(
+                id=id,
+                name=function_name,
+                arguments=function_arguments,
+                result=result,
+                error=error).with_tool_def(target_tool))
+        return results
+
+    def list_models(self) -> list[str]:
+        return get_valid_models(
+            custom_llm_provider=self.provider.value,
+            check_provider_endpoint=True,
+            api_base=self.base_url,
+            api_key=self.api_key)
+
+    def generate_text_sync(self, params: LlmRequestParams) -> GenerateTextResponse:
+        response = completion(**self._param_parser.parse_nonstream(params))
+        response = cast(LiteLlmModelResponse, response)
+        choices = cast(list[LiteLlmModelResponseChoices], response.choices)
+        message = choices[0].message
+        assistant_message = AssistantMessage\
+                            .from_litellm_message(message)\
+                            .with_request_params(params)
+        result: GenerateTextResponse = [assistant_message]
+        if (tools_and_tool_calls := self._should_resolve_tool_calls(params, assistant_message)):
+            tools, tool_calls = tools_and_tool_calls
+            result += self._execute_tool_calls_sync(tools, tool_calls)
+        return result
+
+    async def generate_text(self, params: LlmRequestParams) -> GenerateTextResponse:
+        response = await acompletion(**self._param_parser.parse_nonstream(params))
+        response = cast(LiteLlmModelResponse, response)
+        choices = cast(list[LiteLlmModelResponseChoices], response.choices)
+        message = choices[0].message
+        assistant_message = AssistantMessage\
+                            .from_litellm_message(message)\
+                            .with_request_params(params)
+        result: GenerateTextResponse = [assistant_message]
+        if (tools_and_tool_calls := self._should_resolve_tool_calls(params, assistant_message)):
+            tools, tool_calls = tools_and_tool_calls
+            result += await self._execute_tool_calls(tools, tool_calls)
+        return result
+
+    def stream_text_sync(self, params: LlmRequestParams) -> StreamTextResponseSync:
+        def stream(response: CustomStreamWrapper) -> Generator[MessageChunk]:
+            nonlocal message_collector
+            for chunk in response:
+                chunk = cast(LiteLlmModelResponseStream, chunk)
+                yield from openai_chunk_normalizer(chunk)
+                message_collector.collect(chunk)
+
+            message = message_collector.get_message().with_request_params(params)
+            full_message_queue.put(message)
+            if (tools_and_tool_calls := self._should_resolve_tool_calls(params, message)):
+                tools, tool_calls = tools_and_tool_calls
+                tool_messages = self._execute_tool_calls_sync(tools, tool_calls)
+                for tool_message in tool_messages:
+                    full_message_queue.put(tool_message)
+            full_message_queue.put(None)
+
+        response = completion(**self._param_parser.parse_stream(params))
+        message_collector = AssistantMessageCollector()
+        returned_stream = stream(cast(CustomStreamWrapper, response))
+        full_message_queue = queue.Queue[AssistantMessage | ToolMessage | None]()
+        return returned_stream, full_message_queue
+
+    async def stream_text(self, params: LlmRequestParams) -> StreamTextResponseAsync:
+        async def stream(response: CustomStreamWrapper) -> AsyncGenerator[TextChunk | ReasoningChunk | AudioChunk | ImageChunk | ToolCallChunk]:
+            nonlocal message_collector
+            async for chunk in response:
+                chunk = cast(LiteLlmModelResponseStream, chunk)
+                for normalized_chunk in openai_chunk_normalizer(chunk):
+                    yield normalized_chunk
+                message_collector.collect(chunk)
+
+            message = message_collector.get_message().with_request_params(params)
+            await full_message_queue.put(message)
+            if (tools_and_tool_calls := self._should_resolve_tool_calls(params, message)):
+                tools, tool_calls = tools_and_tool_calls
+                tool_messages = await self._execute_tool_calls(tools, tool_calls)
+                for tool_message in tool_messages:
+                    await full_message_queue.put(tool_message)
+            await full_message_queue.put(None)
+
+        response = await acompletion(**self._param_parser.parse_stream(params))
+        message_collector = AssistantMessageCollector()
+        returned_stream = stream(cast(CustomStreamWrapper, response))
+        full_message_queue = asyncio.Queue[AssistantMessage | ToolMessage | None]()
+        return returned_stream, full_message_queue
+
+__all__ = [
+    # Exceptions
+    "AuthenticationError",
+    "PermissionDeniedError",
+    "RateLimitError",
+    "ContextWindowExceededError",
+    "BadRequestError",
+    "InvalidRequestError",
+    "InternalServerError",
+    "ServiceUnavailableError",
+    "ContentPolicyViolationError",
+    "APIError",
+    "Timeout",
+
+    "LLM",
+    "LlmRequestParams",
+
+    "ToolFn",
+    "ToolDef",
+    "RawToolDef",
+    "ToolLike",
+    "execute_tool",
+    "execute_tool_sync",
+
+    "ChatMessage",
+    "UserMessage",
+    "SystemMessage",
+    "AssistantMessage",
+    "ToolMessage",
+
+    "MessageChunk",
+    "TextChunk",
+    "ReasoningChunk",
+    "AudioChunk",
+    "ImageChunk",
+    "ToolCallChunk",
+
+    "GenerateTextResponse",
+    "StreamTextResponseSync",
+    "StreamTextResponseAsync",
+
+    "enable_debugging",
+    "enable_logging",
+]

liteai_sdk/debug.py

@@ -0,0 +1,4 @@
+import litellm
+
+def enable_debugging():
+    litellm._turn_on_debug()

liteai_sdk/logger.py

@@ -0,0 +1,22 @@
+import sys
+import logging
+
+logger = logging.getLogger("LiteAI-SDK")
+logger.addHandler(logging.NullHandler())
+
+def enable_logging(level=logging.INFO):
+    """
+    Enable logging for the LiteAI SDK.
+
+    Args:
+        level: The logging level (default: logging.INFO).
+
+               Common values: logging.DEBUG, logging.INFO, logging.WARNING, logging.ERROR
+    """
+    logger.setLevel(level)
+
+    if not any(isinstance(h, logging.StreamHandler) for h in logger.handlers):
+        handler = logging.StreamHandler(sys.stderr)
+        formatter = logging.Formatter("%(asctime)s - %(name)s - %(message)s")
+        handler.setFormatter(formatter)
+        logger.addHandler(handler)

liteai_sdk/param_parser.py

@@ -0,0 +1,48 @@
+from typing import Any
+from litellm.types.utils import LlmProviders
+from .tool import prepare_tools
+from .types import LlmRequestParams, ToolMessage
+
+ParsedParams = dict[str, Any]
+
+class ParamParser:
+    def __init__(self,
+                 provider: LlmProviders,
+                 base_url: str,
+                 api_key: str):
+        self._provider = provider
+        self._base_url = base_url
+        self._api_key = api_key
+
+    def _parse(self, params: LlmRequestParams) -> ParsedParams:
+        tools = params.tools and prepare_tools(params.tools)
+        transformed_messages = []
+        for message in params.messages:
+            if type(message) is ToolMessage and\
+               message.result is None and\
+               message.error is None:
+                # skip ToolMessage that is not resolved
+                continue
+            transformed_messages.append(message.to_litellm_message())
+
+        return {
+            "model": f"{self._provider.value}/{params.model}",
+            "messages": transformed_messages,
+            "base_url": self._base_url,
+            "api_key": self._api_key,
+            "tools": tools,
+            "tool_choice": params.tool_choice,
+            "timeout": params.timeout_sec,
+            "extra_headers": params.headers,
+            **(params.extra_args or {})
+        }
+
+    def parse_nonstream(self, params: LlmRequestParams) -> ParsedParams:
+        parsed = self._parse(params)
+        parsed["stream"] = False
+        return parsed
+
+    def parse_stream(self, params: LlmRequestParams) -> ParsedParams:
+        parsed = self._parse(params)
+        parsed["stream"] = True
+        return parsed

liteai_sdk/stream.py

@@ -0,0 +1,82 @@
+import dataclasses
+from litellm import ChatCompletionAssistantToolCall
+from litellm.types.utils import ChatCompletionDeltaToolCall,\
+                                ModelResponseStream as LiteLlmModelResponseStream
+from .types.message import AssistantMessage
+
+@dataclasses.dataclass
+class ToolCallTemp:
+    id: str | None = None
+    name: str = ""
+    arguments: str = ""
+
+class ToolCallCollector:
+    def __init__(self):
+        self.tool_call_map: dict[int, ToolCallTemp] = {}
+
+    def collect(self, tool_call_chunk: ChatCompletionDeltaToolCall):
+        if tool_call_chunk.index not in self.tool_call_map:
+            self.tool_call_map[tool_call_chunk.index] = ToolCallTemp()
+
+        temp_tool_call = self.tool_call_map[tool_call_chunk.index]
+        if tool_call_chunk.get("id"):
+            temp_tool_call.id = tool_call_chunk.id
+        if tool_call_chunk.function.get("name"):
+            assert tool_call_chunk.function.name is not None
+            temp_tool_call.name += tool_call_chunk.function.name
+        if tool_call_chunk.function.get("arguments"):
+            assert tool_call_chunk.function.arguments is not None
+            temp_tool_call.arguments += tool_call_chunk.function.arguments
+
+    def get_tool_calls(self) -> list[ChatCompletionAssistantToolCall]:
+        return [{
+            "id": tool_call.id,
+            "function": {
+                "name": tool_call.name,
+                "arguments": tool_call.arguments,
+            },
+            "type": "function"
+        } for tool_call in self.tool_call_map.values()]
+
+class AssistantMessageCollector:
+    def __init__(self):
+        self.message_buf = AssistantMessage(content=None)
+        self.tool_call_collector = ToolCallCollector()
+
+    def collect(self, chunk: LiteLlmModelResponseStream):
+        delta = chunk.choices[0].delta
+        if delta.get("content"):
+            assert delta.content is not None
+            if self.message_buf.content is None:
+                self.message_buf.content = ""
+            self.message_buf.content += delta.content
+
+        if delta.get("reasoning_content"):
+            assert delta.reasoning_content is not None
+            if self.message_buf.reasoning_content is None:
+                self.message_buf.reasoning_content = ""
+            self.message_buf.reasoning_content += delta.reasoning_content
+
+        if delta.get("tool_calls"):
+            assert delta.tool_calls is not None
+            for tool_call_chunk in delta.tool_calls:
+                self.tool_call_collector.collect(tool_call_chunk)
+
+        if delta.get("images"):
+            assert delta.images is not None
+            if self.message_buf.images is None:
+                self.message_buf.images = []
+            self.message_buf.images = delta.images
+        
+        if delta.get("audio"):
+            assert delta.audio is not None
+            self.message_buf.audio = delta.audio
+
+    def get_message(self) -> AssistantMessage:
+        self.message_buf.tool_calls = self.tool_call_collector.get_tool_calls()
+        return self.message_buf
+
+    def clear(self):
+        """
+        This class will be created for each stream, so we don't need to clear it.
+        """

liteai_sdk/tool/__init__.py

@@ -0,0 +1,310 @@
+"""
+source: https://github.com/mozilla-ai/any-llm/blob/main/src/any_llm/tools.py
+"""
+
+import dataclasses
+import enum
+import inspect
+import types as _types
+from collections.abc import Callable, Mapping, Sequence
+from datetime import date, datetime, time
+from typing import Annotated as _Annotated, Literal as _Literal, is_typeddict as _is_typeddict,\
+                   Any, Awaitable, get_args, get_origin, get_type_hints
+from pydantic import BaseModel as PydanticBaseModel
+
+ToolFn = Callable[..., Any] | Callable[..., Awaitable[Any]]
+
+"""
+RawToolDef example:
+{
+    "name": "get_current_weather",
+    "description": "Get the current weather in a given location",
+    "parameters": {
+        "type": "object",
+        "properties": {
+            "location": {
+                "type": "string",
+                "description": "The city and state, e.g. San Francisco, CA",
+            },
+            "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]},
+        },
+        "required": ["location"],
+    }
+}
+"""
+RawToolDef = dict[str, Any]
+
+@dataclasses.dataclass
+class ToolDef:
+    name: str
+    description: str
+    execute: ToolFn
+
+ToolLike = ToolDef | RawToolDef | ToolFn
+
+def _python_type_to_json_schema(python_type: Any) -> dict[str, Any]:
+    """Convert Python type annotation to a JSON Schema for a parameter.
+
+    Supported mappings (subset tailored for LLM tool schemas):
+    - Primitives: str/int/float/bool -> string/integer/number/boolean
+    - bytes -> string with contentEncoding base64
+    - datetime/date/time -> string with format date-time/date/time
+    - list[T] / Sequence[T] / set[T] / frozenset[T] -> array with items=schema(T)
+      - set/frozenset include uniqueItems=true
+      - list without type args defaults items to string
+    - dict[K,V] / Mapping[K,V] -> object with additionalProperties=schema(V)
+      - dict without type args defaults additionalProperties to string
+    - tuple[T1, T2, ...] -> array with prefixItems per element and min/maxItems
+    - tuple[T, ...] -> array with items=schema(T)
+    - Union[X, Y] and X | Y -> oneOf=[schema(X), schema(Y)] (without top-level type)
+    - Optional[T] (Union[T, None]) -> schema(T) (nullability not encoded)
+    - Literal[...]/Enum -> enum with appropriate type inference when uniform
+    - TypedDict -> object with properties/required per annotations
+    - dataclass/Pydantic BaseModel -> object with nested properties inferred from fields
+    """
+    origin = get_origin(python_type)
+    args = get_args(python_type)
+
+    if _Annotated is not None and origin is _Annotated and len(args) >= 1:
+        python_type = args[0]
+        origin = get_origin(python_type)
+        args = get_args(python_type)
+
+    if python_type is Any:
+        return {"type": "string"}
+
+    primitive_map = {str: "string", int: "integer", float: "number", bool: "boolean"}
+    if python_type in primitive_map:
+        return {"type": primitive_map[python_type]}
+
+    if python_type is bytes:
+        return {"type": "string", "contentEncoding": "base64"}
+    if python_type is datetime:
+        return {"type": "string", "format": "date-time"}
+    if python_type is date:
+        return {"type": "string", "format": "date"}
+    if python_type is time:
+        return {"type": "string", "format": "time"}
+
+    if python_type is list:
+        return {"type": "array", "items": {"type": "string"}}
+    if python_type is dict:
+        return {"type": "object", "additionalProperties": {"type": "string"}}
+
+    if origin is _Literal:
+        literal_values = list(args)
+        schema_lit: dict[str, Any] = {"enum": literal_values}
+        if all(isinstance(v, bool) for v in literal_values):
+            schema_lit["type"] = "boolean"
+        elif all(isinstance(v, str) for v in literal_values):
+            schema_lit["type"] = "string"
+        elif all(isinstance(v, int) and not isinstance(v, bool) for v in literal_values):
+            schema_lit["type"] = "integer"
+        elif all(isinstance(v, int | float) and not isinstance(v, bool) for v in literal_values):
+            schema_lit["type"] = "number"
+        return schema_lit
+
+    if inspect.isclass(python_type) and issubclass(python_type, enum.Enum):
+        enum_values = [e.value for e in python_type]
+        value_types = {type(v) for v in enum_values}
+        schema: dict[str, Any] = {"enum": enum_values}
+        if value_types == {str}:
+            schema["type"] = "string"
+        elif value_types == {int}:
+            schema["type"] = "integer"
+        elif value_types <= {int, float}:
+            schema["type"] = "number"
+        elif value_types == {bool}:
+            schema["type"] = "boolean"
+        return schema
+
+    if _is_typeddict(python_type):
+        annotations: dict[str, Any] = getattr(python_type, "__annotations__", {}) or {}
+        required_keys = set(getattr(python_type, "__required_keys__", set()))
+        td_properties: dict[str, Any] = {}
+        td_required: list[str] = []
+        for field_name, field_type in annotations.items():
+            td_properties[field_name] = _python_type_to_json_schema(field_type)
+            if field_name in required_keys:
+                td_required.append(field_name)
+        schema_td: dict[str, Any] = {
+            "type": "object",
+            "properties": td_properties,
+        }
+        if td_required:
+            schema_td["required"] = td_required
+        return schema_td
+
+    if inspect.isclass(python_type) and dataclasses.is_dataclass(python_type):
+        type_hints = get_type_hints(python_type)
+        dc_properties: dict[str, Any] = {}
+        dc_required: list[str] = []
+        for field in dataclasses.fields(python_type):
+            field_type = type_hints.get(field.name, Any)
+            dc_properties[field.name] = _python_type_to_json_schema(field_type)
+            if (
+                field.default is dataclasses.MISSING
+                and getattr(field, "default_factory", dataclasses.MISSING) is dataclasses.MISSING
+            ):
+                dc_required.append(field.name)
+        schema_dc: dict[str, Any] = {"type": "object", "properties": dc_properties}
+        if dc_required:
+            schema_dc["required"] = dc_required
+        return schema_dc
+
+    if inspect.isclass(python_type) and issubclass(python_type, PydanticBaseModel):
+        model_type_hints = get_type_hints(python_type)
+        pd_properties: dict[str, Any] = {}
+        pd_required: list[str] = []
+        model_fields = getattr(python_type, "model_fields", {})
+        for name, field_info in model_fields.items():
+            pd_properties[name] = _python_type_to_json_schema(model_type_hints.get(name, Any))
+            is_required = getattr(field_info, "is_required", None)
+            if callable(is_required) and is_required():
+                pd_required.append(name)
+        schema_pd: dict[str, Any] = {"type": "object", "properties": pd_properties}
+        if pd_required:
+            schema_pd["required"] = pd_required
+        return schema_pd
+
+    if origin in (list, Sequence, set, frozenset):
+        item_type = args[0] if args else Any
+        item_schema = _python_type_to_json_schema(item_type)
+        schema_arr: dict[str, Any] = {"type": "array", "items": item_schema or {"type": "string"}}
+        if origin in (set, frozenset):
+            schema_arr["uniqueItems"] = True
+        return schema_arr
+    if origin is tuple:
+        if not args:
+            return {"type": "array", "items": {"type": "string"}}
+        if len(args) == 2 and args[1] is Ellipsis:
+            return {"type": "array", "items": _python_type_to_json_schema(args[0])}
+        prefix_items = [_python_type_to_json_schema(a) for a in args]
+        return {
+            "type": "array",
+            "prefixItems": prefix_items,
+            "minItems": len(prefix_items),
+            "maxItems": len(prefix_items),
+        }
+
+    if origin in (dict, Mapping):
+        value_type = args[1] if len(args) >= 2 else Any
+        value_schema = _python_type_to_json_schema(value_type)
+        return {"type": "object", "additionalProperties": value_schema or {"type": "string"}}
+
+    typing_union = getattr(__import__("typing"), "Union", None)
+    if origin in (typing_union, _types.UnionType):
+        non_none_args = [a for a in args if a is not type(None)]
+        if len(non_none_args) > 1:
+            schemas = [_python_type_to_json_schema(arg) for arg in non_none_args]
+            return {"oneOf": schemas}
+        if non_none_args:
+            return _python_type_to_json_schema(non_none_args[0])
+        return {"type": "string"}
+
+    return {"type": "string"}
+
+def _parse_callable_properties(func: ToolFn) -> tuple[dict[str, dict[str, Any]], list[str]]:
+    sig = inspect.signature(func)
+    type_hints = get_type_hints(func)
+
+    properties: dict[str, dict[str, Any]] = {}
+    required: list[str] = []
+
+    for param_name, param in sig.parameters.items():
+        if param.kind in (inspect.Parameter.VAR_POSITIONAL, inspect.Parameter.VAR_KEYWORD):
+            continue
+
+        annotated_type = type_hints.get(param_name, str)
+        param_schema = _python_type_to_json_schema(annotated_type)
+
+        type_name = getattr(annotated_type, "__name__", str(annotated_type))
+        properties[param_name] = {
+            **param_schema,
+            "description": f"Parameter {param_name} of type {type_name}",
+        }
+
+        if param.default == inspect.Parameter.empty:
+            required.append(param_name)
+
+    return properties, required
+
+def generate_tool_definition_from_callable(func: ToolFn) -> dict[str, Any]:
+    """Convert a Python callable to OpenAI tools format.
+
+    Args:
+        func: A Python callable (function) to convert to a tool
+
+    Returns:
+        Dictionary in OpenAI tools format
+
+    Raises:
+        ValueError: If the function doesn't have proper docstring or type annotations
+
+    Example:
+        >>> def get_weather(location: str, unit: str = "celsius") -> str:
+        ...     '''Get weather information for a location.'''
+        ...     return f"Weather in {location} is sunny, 25°{unit[0].upper()}"
+        >>>
+        >>> tool = generate_tool_definition_from_callable(get_weather)
+        >>> # Returns OpenAI tools format dict
+
+    """
+    if not func.__doc__:
+        msg = f"Function {func.__name__} must have a docstring"
+        raise ValueError(msg)
+
+    properties, required = _parse_callable_properties(func)
+    return {
+        "type": "function",
+        "function": {
+            "name": func.__name__,
+            "description": func.__doc__.strip(),
+            "parameters": {"type": "object", "properties": properties, "required": required},
+        },
+    }
+
+def generate_tool_definition_from_tool_def(tool_def: ToolDef) -> dict[str, Any]:
+    """Convert a ToolDef to OpenAI tools format.
+
+    Args:
+        tool_def: A ToolDef to convert to a tool
+
+    Returns:
+        Dictionary in OpenAI tools format
+
+    Example:
+        >>> tool_def = ToolDef(
+        ...     name="get_weather",
+        ...     description="Get weather information for a location.",
+        ...     execute=SomeFunction(),
+        ... )
+        >>> tool = generate_tool_definition_from_tool_def(tool_def)
+        >>> # Returns OpenAI tools format dict
+    """
+    properties, required = _parse_callable_properties(tool_def.execute)
+    return {
+        "type": "function",
+        "function": {
+            "name": tool_def.name,
+            "description": tool_def.description,
+            "parameters": {"type": "object", "properties": properties, "required": required},
+        },
+    }
+
+def generate_tool_definition_from_raw_tool_def(raw_tool_def: RawToolDef) -> dict[str, Any]:
+    return {
+        "type": "function",
+        "function": raw_tool_def,
+    }
+
+def prepare_tools(tools: list[ToolLike]) -> list[dict]:
+    tool_defs = []
+    for tool in tools:
+        if callable(tool):
+            tool_defs.append(generate_tool_definition_from_callable(tool))
+        elif isinstance(tool, ToolDef):
+            tool_defs.append(generate_tool_definition_from_tool_def(tool))
+        else:
+            tool_defs.append(generate_tool_definition_from_raw_tool_def(tool))
+    return tool_defs

liteai_sdk/tool/execute.py

@@ -0,0 +1,65 @@
+import asyncio
+import json
+from functools import singledispatch
+from typing import Any, Awaitable, Callable, cast
+from types import FunctionType, MethodType, CoroutineType
+from . import ToolDef
+
+async def _coroutine_wrapper(awaitable: Awaitable[Any]) -> CoroutineType:
+    return await awaitable
+
+def _arguments_normalizer(arguments: str | dict) -> dict:
+    if isinstance(arguments, str):
+        parsed = json.loads(arguments)
+        return cast(dict, parsed)
+    elif isinstance(arguments, dict):
+        return arguments
+    else:
+        raise ValueError(f"Invalid arguments type: {type(arguments)}")
+
+def _result_normalizer(result: Any) -> str:
+    if isinstance(result, str):
+        return result
+    return json.dumps(result, ensure_ascii=False)
+
+@singledispatch
+def execute_tool_sync(tool, arguments: str | dict) -> str:
+    raise ValueError(f"Invalid tool type: {type(tool)}")
+
+@execute_tool_sync.register(FunctionType)
+@execute_tool_sync.register(MethodType)
+def _(toolfn: Callable, arguments: str | dict) -> str:
+    arguments = _arguments_normalizer(arguments)
+    result = asyncio.run(_coroutine_wrapper(toolfn(**arguments)))\
+             if asyncio.iscoroutinefunction(toolfn)\
+             else toolfn(**arguments)
+    return _result_normalizer(result)
+
+@execute_tool_sync.register(ToolDef)
+def _(tooldef: ToolDef, arguments: str | dict) -> str:
+    arguments = _arguments_normalizer(arguments)
+    result = asyncio.run(_coroutine_wrapper(tooldef.execute(**arguments)))\
+             if asyncio.iscoroutinefunction(tooldef.execute)\
+             else tooldef.execute(**arguments)
+    return _result_normalizer(result)
+
+@singledispatch
+async def execute_tool(tool, arguments: str | dict) -> str:
+    raise ValueError(f"Invalid tool type: {type(tool)}")
+
+@execute_tool.register(FunctionType)
+@execute_tool.register(MethodType)
+async def _(toolfn: Callable, arguments: str | dict) -> str:
+    arguments = _arguments_normalizer(arguments)
+    result = await toolfn(**arguments)\
+             if asyncio.iscoroutinefunction(toolfn)\
+             else toolfn(**arguments)
+    return _result_normalizer(result)
+
+@execute_tool.register(ToolDef)
+async def _(tooldef: ToolDef, arguments: str | dict) -> str:
+    arguments = _arguments_normalizer(arguments)
+    result = await tooldef.execute(**arguments)\
+             if asyncio.iscoroutinefunction(tooldef.execute)\
+             else tooldef.execute(**arguments)
+    return _result_normalizer(result)

liteai_sdk/tool/utils.py

@@ -0,0 +1,11 @@
+from . import ToolFn, ToolDef, ToolLike
+
+def find_tool_by_name(tools: list[ToolLike], name: str) -> ToolLike | None:
+    for tool in tools:
+        if callable(tool) and tool.__name__ == name:
+            return tool
+        elif isinstance(tool, ToolDef) and tool.name == name:
+            return tool
+        elif isinstance(tool, dict) and tool.get("name") == name:
+            return tool
+    return None

liteai_sdk/types/__init__.py

@@ -0,0 +1,32 @@
+import asyncio
+import dataclasses
+import queue
+from typing import Any, Generator, Literal
+from collections.abc import AsyncGenerator, Generator
+from ..tool import ToolLike
+from .message import ChatMessage, AssistantMessage, ToolMessage, MessageChunk
+
+@dataclasses.dataclass
+class LlmRequestParams:
+    model: str
+    messages: list[ChatMessage]
+    tools: list[ToolLike] | None = None
+    tool_choice: Literal["auto", "required", "none"] = "auto"
+    execute_tools: bool = False
+
+    timeout_sec: float | None = None
+    temperature: float | None = None
+    max_tokens: int | None = None
+    headers: dict[str, str] | None = None
+
+    extra_args: dict[str, Any] | None = None
+
+# --- --- --- --- --- ---
+
+GenerateTextResponse = list[AssistantMessage | ToolMessage]
+StreamTextResponseSync = tuple[
+    Generator[MessageChunk],
+    queue.Queue[AssistantMessage | ToolMessage | None]]
+StreamTextResponseAsync = tuple[
+    AsyncGenerator[MessageChunk],
+    asyncio.Queue[AssistantMessage | ToolMessage | None]]

liteai_sdk/types/exceptions.py

@@ -0,0 +1,27 @@
+from litellm.exceptions import (  
+    AuthenticationError,
+    PermissionDeniedError,
+    RateLimitError,
+    ContextWindowExceededError,
+    BadRequestError,
+    InvalidRequestError,
+    InternalServerError,
+    ServiceUnavailableError,
+    ContentPolicyViolationError,
+    APIError,
+    Timeout,
+)
+
+__all__ = [
+    "AuthenticationError",
+    "PermissionDeniedError",
+    "RateLimitError",
+    "ContextWindowExceededError",
+    "BadRequestError",
+    "InvalidRequestError",
+    "InternalServerError",
+    "ServiceUnavailableError",
+    "ContentPolicyViolationError",
+    "APIError",
+    "Timeout",
+]

liteai_sdk/types/message.py

@@ -0,0 +1,242 @@
+from __future__ import annotations
+
+import json
+import dataclasses
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING, Any, Literal, cast
+from pydantic import BaseModel, ConfigDict, PrivateAttr, field_validator
+from litellm.types.utils import Message as LiteLlmMessage,\
+                                ModelResponseStream as LiteLlmModelResponseStream,\
+                                ChatCompletionAudioResponse,\
+                                ChatCompletionMessageToolCall,\
+                                ChatCompletionDeltaToolCall
+from litellm.types.llms.openai import (
+    AllMessageValues,
+    OpenAIMessageContent,
+    ChatCompletionAssistantToolCall,
+    ImageURLListItem as ChatCompletionImageURL,
+
+    ChatCompletionUserMessage,
+    ChatCompletionAssistantMessage,
+    ChatCompletionToolMessage,
+    ChatCompletionSystemMessage,
+)
+from ..tool import ToolLike
+from ..tool.utils import find_tool_by_name
+from ..logger import logger
+
+if TYPE_CHECKING:
+    from . import LlmRequestParams
+
+class ChatMessage(BaseModel, ABC):    
+    model_config = ConfigDict(
+        arbitrary_types_allowed=True,
+        validate_assignment=True,
+    )
+
+    @abstractmethod
+    def to_litellm_message(self) -> AllMessageValues: ...
+
+class UserMessage(ChatMessage):
+    content: OpenAIMessageContent
+    role: Literal["user"] = "user"
+
+    def to_litellm_message(self) -> ChatCompletionUserMessage:
+        return ChatCompletionUserMessage(role=self.role, content=self.content)
+
+class ToolMessage(ChatMessage):
+    """
+    The `tool_def` field is ref to the target tool of the tool call, and 
+    it will only be None when the target tool is not found
+    """
+    id: str
+    name: str
+    arguments: str
+    result: str | None = None
+    error: str | None = None
+    role: Literal["tool"] = "tool"
+
+    _tool_def: ToolLike | None = PrivateAttr(default=None)
+
+    @field_validator("result", mode="before")
+    def validate_result(cls, v: Any) -> Any:
+        if v is None: return v
+        if isinstance(v, str): return v
+        return json.dumps(v, ensure_ascii=False)
+
+    @property
+    def tool_def(self) -> ToolLike | None:
+        return self._tool_def
+
+    def with_tool_def(self, tool_def: ToolLike) -> "ToolMessage":
+        self._tool_def = tool_def
+        return self
+
+    def to_litellm_message(self) -> ChatCompletionToolMessage:
+        if self.result is None and self.error is None:
+            raise ValueError(f"ToolMessage({self.id}, {self.name}) is incomplete, "
+                              "result and error cannot be both None")
+
+        if self.error is not None:
+            content = json.dumps({"error": self.error}, ensure_ascii=False)
+        else:
+            assert self.result is not None
+            content = self.result
+
+        return ChatCompletionToolMessage(
+            role=self.role,
+            content=content,
+            tool_call_id=self.id)
+
+ToolCallTuple = tuple[str, str, str]
+class AssistantMessage(ChatMessage):
+    content: str | None = None
+    reasoning_content: str | None = None
+    tool_calls: list[ChatCompletionAssistantToolCall] | None = None
+    audio: ChatCompletionAudioResponse | None = None
+    images: list[ChatCompletionImageURL] | None = None
+    role: Literal["assistant"] = "assistant"
+
+    _request_params_ref: LlmRequestParams | None = PrivateAttr(default=None)
+
+    @classmethod
+    def from_litellm_message(cls, message: LiteLlmMessage) -> "AssistantMessage":
+        tool_calls: list[ChatCompletionAssistantToolCall] | None = None
+        if (message_tool_calls := message.get("tool_calls")) is not None:
+            tool_calls = [ChatCompletionAssistantToolCall(
+                id=tool_call.id,
+                function={
+                    "name": tool_call.function.name,
+                    "arguments": tool_call.function.arguments,
+                },
+                type="function",
+            ) for tool_call in cast(list[ChatCompletionMessageToolCall], message_tool_calls)]
+
+        return cls.model_construct(
+            content=message.get("content"),
+            reasoning_content=message.get("reasoning_content"),
+            tool_calls=tool_calls,
+            audio=message.get("audio"),
+            images=message.get("images"),
+        )
+
+    def with_request_params(self, request_params: LlmRequestParams) -> "AssistantMessage":
+        self._request_params_ref = request_params
+        return self
+
+    def to_litellm_message(self) -> ChatCompletionAssistantMessage:
+        return ChatCompletionAssistantMessage(role=self.role,
+                                              content=self.content or "",
+                                              reasoning_content=self.reasoning_content,
+                                              tool_calls=self.tool_calls)
+
+    def parse_tool_calls(self) -> list[ToolCallTuple] | None:
+        if self.tool_calls is None: return None
+        results = []
+        for tool_call in self.tool_calls:
+            id = tool_call.get("id")
+            function = tool_call.get("function") # this can not be None
+            function_name = function.get("name")
+            function_arguments = function.get("arguments")
+            if id is None or\
+               function is None or\
+               function_name is None or\
+               function_arguments is None:
+                return None
+            results.append((id, function_name, function_arguments))
+        return results
+
+    def get_partial_tool_messages(self) -> list[ToolMessage] | None:
+        """
+        Get a partial tool message from the assistant message.
+        The returned tool message is not complete,
+        it only contains the tool call id, name and arguments.
+        Returns None if there is no tool call in the assistant message.
+        """
+        has_tool_def = self._request_params_ref is not None and\
+                       self._request_params_ref.tools is not None
+        if not has_tool_def:
+            logger.warning("AssistantMessage.get_partial_tool_messages() called without request params. "
+                           "Call with_request_params() first to enable auto tool_def attachment feature.")
+
+        parsed_tool_calls = self.parse_tool_calls()
+        if parsed_tool_calls is None: return None
+
+        results = []
+        for tool_call in parsed_tool_calls:
+            id, name, arguments = tool_call
+
+            tool_message = ToolMessage(
+                id=id,
+                name=name,
+                arguments=arguments,
+                result=None,
+                error=None)
+
+            if has_tool_def:
+                assert self._request_params_ref and self._request_params_ref.tools
+                target_tool = find_tool_by_name(self._request_params_ref.tools, name)
+                if target_tool:
+                    tool_message = tool_message.with_tool_def(target_tool)
+                else:
+                    logger.warning(f"Tool {name} not found in request params, "
+                                    "tool_def will not be attached to the tool message")
+
+            results.append(tool_message)
+        return results
+
+class SystemMessage(ChatMessage):
+    content: str
+    role: Literal["system"] = "system"
+
+    def to_litellm_message(self) -> ChatCompletionSystemMessage:
+        return ChatCompletionSystemMessage(role=self.role, content=self.content)
+
+@dataclasses.dataclass
+class TextChunk:
+    content: str
+
+@dataclasses.dataclass
+class ReasoningChunk:
+    content: str
+
+@dataclasses.dataclass
+class AudioChunk:
+    data: ChatCompletionAudioResponse
+
+@dataclasses.dataclass
+class ImageChunk:
+    data: list[ChatCompletionImageURL]
+
+@dataclasses.dataclass
+class ToolCallChunk:
+    id: str | None
+    name: str | None
+    arguments: str
+    index: int
+
+MessageChunk = TextChunk | ReasoningChunk | AudioChunk | ImageChunk | ToolCallChunk
+
+def openai_chunk_normalizer(
+        chunk: LiteLlmModelResponseStream
+        ) -> list[MessageChunk]:
+    if len(chunk.choices) == 0: return []
+
+    result = []
+    delta = chunk.choices[0].delta
+    if delta.get("content"):
+        result.append(TextChunk(cast(str, delta.content)))
+    if delta.get("reasoning_content"):
+        result.append(ReasoningChunk(cast(str, delta.reasoning_content)))
+    if delta.get("audio"):
+        result.append(AudioChunk(cast(ChatCompletionAudioResponse, delta.audio)))
+    if delta.get("images"):
+        result.append(ImageChunk(cast(list[ChatCompletionImageURL], delta.images)))
+    if delta.get("tool_calls"):
+        for tool_call in cast(list[ChatCompletionDeltaToolCall], delta.tool_calls):
+            result.append(ToolCallChunk(
+                tool_call.id,
+                tool_call.function.name,
+                tool_call.function.arguments,
+                tool_call.index))
+    return result

liteai_sdk-0.3.21.dist-info/METADATA

@@ -0,0 +1,100 @@
+Metadata-Version: 2.4
+Name: liteai_sdk
+Version: 0.3.21
+Summary: A wrapper of LiteLLM
+Author-email: BHznJNs <bhznjns@outlook.com>
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+License-File: LICENSE
+Requires-Dist: litellm>=1.80.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: python-dotenv>=1.2.1 ; extra == "dev"
+Requires-Dist: pytest-cov ; extra == "test"
+Requires-Dist: pytest-mock ; extra == "test"
+Requires-Dist: pytest-runner ; extra == "test"
+Requires-Dist: pytest ; extra == "test"
+Requires-Dist: pytest-github-actions-annotate-failures ; extra == "test"
+Project-URL: Source, https://github.com/BHznJNs/liteai
+Project-URL: Tracker, https://github.com/BHznJNs/liteai/issues
+Provides-Extra: dev
+Provides-Extra: test
+
+# LiteAI-SDK
+
+LiteAI-SDK is a wrapper of LiteLLM which provides a more intuitive API and [AI SDK](https://github.com/vercel/ai) like DX.
+
+## Installation
+
+```
+pip install liteai-sdk
+```
+
+### Develop with coding agent
+
+You can access the complete usage guidance with [llms.txt](https://raw.githubusercontent.com/BHznJNs/liteai/refs/heads/main/llms.txt), just give it to your coding agent to tell it how to use LiteAI-SDK.
+
+## Examples
+
+Below is a simple example of just a API call:
+
+```python
+import os
+from dotenv import load_dotenv
+from liteai_sdk import LLM, LlmProviders, LlmRequestParams, UserMessage
+
+load_dotenv()
+
+llm = LLM(provider=LlmProviders.OPENAI,
+          api_key=os.getenv("API_KEY", ""),
+          base_url=os.getenv("BASE_URL", ""))
+
+response = llm.generate_text_sync( # sync API of generate_text
+    LlmRequestParams(
+        model="deepseek-v3.1",
+        messages=[UserMessage(content="Hello.")]))
+print(response)
+```
+
+Below is an example that shows the automatically tool call:
+
+```python
+import os
+from dotenv import load_dotenv
+from liteai_sdk import LLM, LlmProviders, LlmRequestParams, UserMessage
+
+load_dotenv()
+
+def example_tool():
+    """
+    This is a test tool that is used to test the tool calling functionality.
+    """
+    print("The example tool is called.")
+    return "Hello World"
+
+llm = LLM(provider=LlmProviders.OPENAI,
+          api_key=os.getenv("API_KEY", ""),
+          base_url=os.getenv("BASE_URL", ""))
+
+params = LlmRequestParams(
+        model="deepseek-v3.1",
+        tools=[example_tool],
+        execute_tools=True,
+        messages=[UserMessage(content="Please call the tool example_tool.")])
+
+print("User: ", "Please call the tool example_tool.")
+messages = llm.generate_text_sync(params)
+for message in messages:
+    match message.role:
+        case "assistant":
+            print("Assistant: ", message.content)
+        case "tool":
+            print("Tool: ", message.result)
+```
+

liteai_sdk-0.3.21.dist-info/RECORD

@@ -0,0 +1,15 @@
+liteai_sdk/__init__.py,sha256=KTHDeLyGGtVA-H8nJhJMBr_rKFV1h5cD5voZ8oPXI00,10608
+liteai_sdk/debug.py,sha256=T7qIy1BeeUGlF40l9JCMMVn8pvvMJAEQeG4adQbOydA,69
+liteai_sdk/logger.py,sha256=99vJAQRKcu4CuHgZYAJ2zDQtGea6Bn3vJJrS-mtza7c,677
+liteai_sdk/param_parser.py,sha256=xykvUesZzwZNf4-n1j4JfVk0L2y_wvnSWSsHo5vjBU8,1655
+liteai_sdk/stream.py,sha256=T9MLmgPC8te6qvSkBOh7vkl-I4OGCKuW1kEN6RkiCe0,3176
+liteai_sdk/tool/__init__.py,sha256=c1qJaEpoYlgOCtAjFODhrSR73ZW17OuamsO__yeYAkY,12150
+liteai_sdk/tool/execute.py,sha256=1CfRlJZgqoev42fDH4vygXyEtCEEBPcRfbqaP77jxu4,2462
+liteai_sdk/tool/utils.py,sha256=Djd1-EoLPfIqgPbWWvOreozQ76NHX4FZ6OXc1evKqPM,409
+liteai_sdk/types/__init__.py,sha256=CMmweIGMgreZlbvBtRTKfvdcC7war2ApLNf-9Fz0yzc,1006
+liteai_sdk/types/exceptions.py,sha256=hIGu06htOJxfEBAHx7KTvLQr0Y8GYnBLFJFlr_IGpDs,602
+liteai_sdk/types/message.py,sha256=AnhJ5wKKcWuAt0lW3mPXpIyvUBy3u-iFLa1dpeUTp18,8785
+liteai_sdk-0.3.21.dist-info/licenses/LICENSE,sha256=cTeVgQVJJcRdm1boa2P1FBnOeXfA_egV6s4PouyrCxg,1064
+liteai_sdk-0.3.21.dist-info/WHEEL,sha256=G2gURzTEtmeR8nrdXUJfNiB3VYVxigPQ-bEQujpNiNs,82
+liteai_sdk-0.3.21.dist-info/METADATA,sha256=uUYWHL4MKkSTsqokLBEN2EcJd60HkinQthNXRRTabzU,3024
+liteai_sdk-0.3.21.dist-info/RECORD,,

liteai_sdk-0.3.21.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: flit 3.12.0
+Root-Is-Purelib: true
+Tag: py3-none-any

liteai_sdk-0.3.21.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 BHznJNs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.