dais-sdk 0.6.0__tar.gz

dais_sdk-0.6.0/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.

dais_sdk-0.6.0/PKG-INFO

@@ -0,0 +1,100 @@
+Metadata-Version: 2.4
+Name: dais-sdk
+Version: 0.6.0
+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: httpx==0.28.1
+Requires-Dist: mcp==1.25.0
+Requires-Dist: starlette==0.50.0
+Requires-Dist: uvicorn==0.40.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/Dais-Project/Dais-SDK
+Project-URL: Tracker, https://github.com/Dais-Project/Dais-SDK/issues
+Provides-Extra: dev
+Provides-Extra: test
+
+# Dais-SDK
+
+Dais-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 dais_sdk
+```
+
+## Examples
+
+Below is a simple example of just a API call:
+
+```python
+import os
+from dotenv import load_dotenv
+from dais_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 dais_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)
+```
+

dais_sdk-0.6.0/README.md

@@ -0,0 +1,67 @@
+# Dais-SDK
+
+Dais-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 dais_sdk
+```
+
+## Examples
+
+Below is a simple example of just a API call:
+
+```python
+import os
+from dotenv import load_dotenv
+from dais_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 dais_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)
+```

dais_sdk-0.6.0/pyproject.toml

@@ -0,0 +1,102 @@
+[build-system]
+requires = ["flit_core >=2,<4"]
+build-backend = "flit_core.buildapi"
+
+[project]
+name = "dais-sdk"
+authors = [{ name = "BHznJNs", email = "bhznjns@outlook.com" }]
+description = "A wrapper of LiteLLM"
+readme = "README.md"
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+requires-python = ">=3.10"
+version = "0.6.0"
+
+dependencies = [
+    "litellm>=1.80.0",
+    "pydantic>=2.0.0",
+
+    # MCP client dependencies
+    "httpx==0.28.1",
+    "mcp==1.25.0",
+    "starlette==0.50.0",
+    "uvicorn==0.40.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "python-dotenv>=1.2.1"
+]
+test = [
+    "pytest-cov",
+    "pytest-mock",
+    "pytest-runner",
+    "pytest",
+    "pytest-github-actions-annotate-failures",
+]
+
+[project.urls]
+Source = "https://github.com/Dais-Project/Dais-SDK"
+Tracker = "https://github.com/Dais-Project/Dais-SDK/issues"
+
+[tool.flit.module]
+name = "dais_sdk"
+
+[tool.bandit]
+exclude_dirs = ["build", "dist", "tests", "scripts"]
+number = 4
+recursive = true
+targets = "src"
+
+[tool.black]
+line-length = 120
+fast = true
+
+[tool.coverage.run]
+branch = true
+
+[tool.coverage.report]
+fail_under = 100
+
+[tool.flake8]
+max-line-length = 120
+select = "F,E,W,B,B901,B902,B903"
+exclude = [
+    ".eggs",
+    ".git",
+    ".tox",
+    "nssm",
+    "obj",
+    "out",
+    "packages",
+    "pywin32",
+    "tests",
+    "swagger_client",
+]
+ignore = ["E722", "B001", "W503", "E203"]
+
+[tool.pyright]
+include = ["src"]
+pythonVersion = "3.11"
+typeCheckingMode = "standard"
+
+[tool.pytest.ini_options]
+addopts = "--cov-report xml:coverage.xml --cov src --cov-fail-under 0 --cov-append -m 'not integration'"
+pythonpath = ["src"]
+testpaths = "tests"
+junit_family = "xunit2"
+markers = [
+    "integration: marks as integration test",
+    "notebooks: marks as notebook test",
+    "gpu: marks as gpu test",
+    "spark: marks tests which need Spark",
+    "slow: marks tests as slow",
+    "unit: fast offline tests",
+]

dais_sdk-0.6.0/src/dais_sdk/__init__.py

@@ -0,0 +1,320 @@
+import asyncio
+import queue
+from typing import cast
+from collections.abc import AsyncGenerator, Generator
+from litellm import CustomStreamWrapper, completion, acompletion
+from litellm.utils import ProviderConfigManager
+from litellm.types.utils import (
+    LlmProviders,
+    ModelResponse as LiteLlmModelResponse,
+    ModelResponseStream as LiteLlmModelResponseStream
+)
+from .debug import enable_debugging
+from .param_parser import ParamParser
+from .stream import AssistantMessageCollector
+from .tool.execute import execute_tool_sync, execute_tool
+from .tool.toolset import (
+    Toolset,
+    python_tool,
+    PythonToolset,
+    McpToolset,
+    LocalMcpToolset,
+    RemoteMcpToolset,
+)
+from .tool.utils import find_tool_by_name
+from .mcp_client import (
+    McpClient,
+    McpTool,
+    McpToolResult,
+    LocalMcpClient,
+    RemoteMcpClient,
+    LocalServerParams,
+    RemoteServerParams,
+    OAuthParams,
+)
+from .types import (
+    GenerateTextResponse,
+    StreamTextResponseSync, StreamTextResponseAsync,
+    FullMessageQueueSync, FullMessageQueueAsync,
+)
+from .types.request_params import LlmRequestParams
+from .types.tool import ToolFn, ToolDef, RawToolDef, ToolLike
+from .types.exceptions import (
+    AuthenticationError,
+    PermissionDeniedError,
+    RateLimitError,
+    ContextWindowExceededError,
+    BadRequestError,
+    InvalidRequestError,
+    InternalServerError,
+    ServiceUnavailableError,
+    ContentPolicyViolationError,
+    APIError,
+    Timeout,
+)
+from .types.message import (
+    ChatMessage, UserMessage, SystemMessage, AssistantMessage, ToolMessage,
+    MessageChunk, TextChunk, UsageChunk, ReasoningChunk, AudioChunk, ImageChunk, ToolCallChunk,
+    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
+    async def execute_tool_call(
+            params: LlmRequestParams,
+            incomplete_tool_message: ToolMessage
+            ) -> tuple[str | None, str | None]:
+        """
+        Receive incomplete tool messages, execute the tool calls and
+        return the result and error tuple.
+        """
+        name, arguments = incomplete_tool_message.name, incomplete_tool_message.arguments
+        tool_def = params.find_tool(incomplete_tool_message.name)
+        if tool_def is None:
+            raise LlmRequestParams.ToolDoesNotExistError(name)
+
+        result, error = None, None
+        try:
+            result = await execute_tool(tool_def, arguments)
+        except Exception as e:
+            error = f"{type(e).__name__}: {str(e)}"
+        return result, error
+
+    @staticmethod
+    def execute_tool_call_sync(
+            params: LlmRequestParams,
+            incomplete_tool_message: ToolMessage
+            ) -> tuple[str | None, str | None]:
+        """
+        Synchronous version of `execute_tool_call`.
+        """
+        name, arguments = incomplete_tool_message.name, incomplete_tool_message.arguments
+        tool_def = params.find_tool(incomplete_tool_message.name)
+        if tool_def is None:
+            raise LlmRequestParams.ToolDoesNotExistError(name)
+
+        result, error = None, None
+        try:
+            result = execute_tool_sync(tool_def, arguments)
+        except Exception as e:
+            error = f"{type(e).__name__}: {str(e)}"
+        return result, error
+
+    def _resolve_tool_calls_sync(self, params: LlmRequestParams, assistant_message: AssistantMessage) -> Generator[ToolMessage]:
+        if not params.execute_tools: return
+        if (incomplete_tool_messages
+            := assistant_message.get_incomplete_tool_messages()) is None:
+            return
+        for incomplete_tool_message in incomplete_tool_messages:
+            try:
+                result, error = LLM.execute_tool_call_sync(params, incomplete_tool_message)
+            except LlmRequestParams.ToolDoesNotExistError as e:
+                logger.warning(f"{e.message} Skipping this tool call.")
+                continue
+            yield ToolMessage(
+                tool_call_id=incomplete_tool_message.tool_call_id,
+                name=incomplete_tool_message.name,
+                arguments=incomplete_tool_message.arguments,
+                result=result,
+                error=error)
+
+    async def _resolve_tool_calls(self, params: LlmRequestParams, assistant_message: AssistantMessage) -> AsyncGenerator[ToolMessage]:
+        if not params.execute_tools: return
+        if (incomplete_tool_messages :=
+            assistant_message.get_incomplete_tool_messages()) is None:
+            return
+        for incomplete_tool_message in incomplete_tool_messages:
+            try:
+                result, error = await LLM.execute_tool_call(params, incomplete_tool_message)
+            except LlmRequestParams.ToolDoesNotExistError as e:
+                logger.warning(f"{e.message} Skipping this tool call.")
+                continue
+            yield ToolMessage(
+                tool_call_id=incomplete_tool_message.tool_call_id,
+                name=incomplete_tool_message.name,
+                arguments=incomplete_tool_message.arguments,
+                result=result,
+                error=error)
+
+    def list_models(self) -> list[str]:
+        provider_config = ProviderConfigManager.get_provider_model_info(
+            model=None,
+            provider=self.provider,
+        )
+
+        if provider_config is None:
+            raise ValueError(f"The '{self.provider}' provider is not supported to list models.")
+
+        try:
+            models = provider_config.get_models(
+                api_key=self.api_key,
+                api_base=self.base_url
+            )
+        except Exception as e:
+            raise e
+        return models
+
+    def generate_text_sync(self, params: LlmRequestParams) -> GenerateTextResponse:
+        response = completion(**self._param_parser.parse_nonstream(params))
+        response = cast(LiteLlmModelResponse, response)
+        assistant_message = AssistantMessage.from_litellm_message(response)
+        result: GenerateTextResponse = [assistant_message]
+        for tool_message in self._resolve_tool_calls_sync(params, assistant_message):
+            result.append(tool_message)
+        return result
+
+    async def generate_text(self, params: LlmRequestParams) -> GenerateTextResponse:
+        response = await acompletion(**self._param_parser.parse_nonstream(params))
+        response = cast(LiteLlmModelResponse, response)
+        assistant_message = AssistantMessage.from_litellm_message(response)
+        result: GenerateTextResponse = [assistant_message]
+        async for tool_message in self._resolve_tool_calls(params, assistant_message):
+            result.append(tool_message)
+        return result
+
+    def stream_text_sync(self, params: LlmRequestParams) -> StreamTextResponseSync:
+        """
+        Returns:
+            - stream: Generator yielding `MessageChunk` objects
+            - full_message_queue: Queue containing complete `AssistantMessage`, `ToolMessage` (or `None` when done)
+        """
+        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()
+            full_message_queue.put(message)
+
+            for tool_message in self._resolve_tool_calls_sync(params, message):
+                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 = FullMessageQueueSync()
+        return returned_stream, full_message_queue
+
+    async def stream_text(self, params: LlmRequestParams) -> StreamTextResponseAsync:
+        """
+        Returns:
+            - stream: Generator yielding `MessageChunk` objects
+            - full_message_queue: Queue containing complete `AssistantMessage`, `ToolMessage` (or `None` when done)
+        """
+        async def stream(response: CustomStreamWrapper) -> AsyncGenerator[MessageChunk]:
+            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()
+            await full_message_queue.put(message)
+            async for tool_message in self._resolve_tool_calls(params, message):
+                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 = FullMessageQueueAsync()
+        return returned_stream, full_message_queue
+
+__all__ = [
+    "LLM",
+    "LlmProviders",
+    "LlmRequestParams",
+
+    "Toolset",
+    "python_tool",
+    "PythonToolset",
+    "McpToolset",
+    "LocalMcpToolset",
+    "RemoteMcpToolset",
+
+    "McpClient",
+    "McpTool",
+    "McpToolResult",
+    "LocalMcpClient",
+    "RemoteMcpClient",
+    "LocalServerParams",
+    "RemoteServerParams",
+    "OAuthParams",
+
+    "ToolFn",
+    "ToolDef",
+    "RawToolDef",
+    "ToolLike",
+    "execute_tool",
+    "execute_tool_sync",
+
+    "ChatMessage",
+    "UserMessage",
+    "SystemMessage",
+    "AssistantMessage",
+    "ToolMessage",
+
+    "MessageChunk",
+    "TextChunk",
+    "UsageChunk",
+    "ReasoningChunk",
+    "AudioChunk",
+    "ImageChunk",
+    "ToolCallChunk",
+
+    "GenerateTextResponse",
+    "StreamTextResponseSync",
+    "StreamTextResponseAsync",
+    "FullMessageQueueSync",
+    "FullMessageQueueAsync",
+
+    "enable_debugging",
+    "enable_logging",
+
+    # Exceptions
+    "AuthenticationError",
+    "PermissionDeniedError",
+    "RateLimitError",
+    "ContextWindowExceededError",
+    "BadRequestError",
+    "InvalidRequestError",
+    "InternalServerError",
+    "ServiceUnavailableError",
+    "ContentPolicyViolationError",
+    "APIError",
+    "Timeout",
+]

dais_sdk-0.6.0/src/dais_sdk/debug.py

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

dais_sdk-0.6.0/src/dais_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)

dais_sdk-0.6.0/src/dais_sdk/mcp_client/__init__.py

@@ -0,0 +1,15 @@
+from .base_mcp_client import McpClient, McpTool, ToolResult as McpToolResult
+from .local_mcp_client import LocalMcpClient, LocalServerParams
+from .remote_mcp_client import RemoteMcpClient, RemoteServerParams, OAuthParams
+
+__all__ = [
+    "McpClient",
+    "McpTool",
+    "McpToolResult",
+
+    "LocalMcpClient",
+    "LocalServerParams",
+    "RemoteMcpClient",
+    "RemoteServerParams",
+    "OAuthParams",
+]

dais_sdk-0.6.0/src/dais_sdk/mcp_client/base_mcp_client.py

@@ -0,0 +1,38 @@
+from abc import ABC, abstractmethod
+from typing import Any, NamedTuple
+from mcp import Tool as McpTool
+from mcp.types import ContentBlock as ToolResultBlock
+
+Tool = McpTool
+
+class ToolResult(NamedTuple):
+    is_error: bool
+    content: list[ToolResultBlock]
+
+class McpClient(ABC):
+    @property
+    @abstractmethod
+    def name(self) -> str: ...
+
+    @abstractmethod
+    async def connect(self): ...
+    @abstractmethod
+    async def disconnect(self): ...
+    @abstractmethod
+    async def list_tools(self) -> list[Tool]:
+        """
+        Raises:
+            McpSessionNotEstablishedError: If the session is not established.
+        """
+    @abstractmethod
+    async def call_tool(
+        self, tool_name: str, arguments: dict[str, Any] | None = None
+    ) -> ToolResult:
+        """
+        Raises:
+            McpSessionNotEstablishedError: If the session is not established.
+        """
+
+class McpSessionNotEstablishedError(RuntimeError):
+    def __init__(self):
+        super().__init__("MCP Session not established, please call connect() first")