canvas 0.63.0__py3-none-any.whl → 0.89.0__py3-none-any.whl

canvas_sdk/clients/__init__.py

@@ -0,0 +1 @@
+__exports__ = ()

canvas_sdk/clients/llms/__init__.py

@@ -0,0 +1,17 @@
+from canvas_sdk.clients.llms.libraries.llm_anthropic import LlmAnthropic
+from canvas_sdk.clients.llms.libraries.llm_google import LlmGoogle
+from canvas_sdk.clients.llms.libraries.llm_openai import LlmOpenai
+from canvas_sdk.clients.llms.structures.llm_response import LlmResponse
+from canvas_sdk.clients.llms.structures.llm_tokens import LlmTokens
+from canvas_sdk.clients.llms.structures.llm_turn import LlmTurn
+from canvas_sdk.clients.llms.structures.settings.llm_settings import LlmSettings
+
+__all__ = __exports__ = (
+    "LlmAnthropic",
+    "LlmGoogle",
+    "LlmOpenai",
+    "LlmSettings",
+    "LlmResponse",
+    "LlmTokens",
+    "LlmTurn",
+)

canvas_sdk/clients/llms/libraries/__init__.py

@@ -0,0 +1,11 @@
+from canvas_sdk.clients.llms.libraries.llm_anthropic import LlmAnthropic
+from canvas_sdk.clients.llms.libraries.llm_api import LlmApi
+from canvas_sdk.clients.llms.libraries.llm_google import LlmGoogle
+from canvas_sdk.clients.llms.libraries.llm_openai import LlmOpenai
+
+__all__ = __exports__ = (
+    "LlmAnthropic",
+    "LlmApi",
+    "LlmGoogle",
+    "LlmOpenai",
+)

canvas_sdk/clients/llms/libraries/llm_anthropic.py

@@ -0,0 +1,87 @@
+import json
+from http import HTTPStatus
+
+from requests import exceptions
+
+from canvas_sdk.clients.llms.libraries.llm_api import LlmApi
+from canvas_sdk.clients.llms.structures.llm_response import LlmResponse
+from canvas_sdk.clients.llms.structures.llm_tokens import LlmTokens
+
+
+class LlmAnthropic(LlmApi):
+    """Anthropic Claude LLM API client.
+
+    Implements the LlmBase interface for Anthropic's Claude API.
+    """
+
+    def to_dict(self) -> dict:
+        """Convert prompts and add the necessary information to Anthropic API request format.
+
+        Returns:
+            Dictionary formatted for Anthropic API with messages array.
+        """
+        messages: list[dict] = []
+
+        roles = {
+            self.ROLE_SYSTEM: "user",
+            self.ROLE_USER: "user",
+            self.ROLE_MODEL: "assistant",
+        }
+        for prompt in self.prompts:
+            role = roles[prompt.role]
+            part = {"type": "text", "text": "\n".join(prompt.text)}
+            # contiguous parts for the same role are merged
+            if messages and messages[-1]["role"] == role:
+                messages[-1]["content"].append(part)
+            else:
+                messages.append({"role": role, "content": [part]})
+
+        return self.settings.to_dict() | {
+            "messages": messages,
+        }
+
+    @classmethod
+    def _api_base_url(cls) -> str:
+        return "https://api.anthropic.com"
+
+    def request(self) -> LlmResponse:
+        """Make a request to the Anthropic Claude API.
+
+        Returns:
+            Response containing status code, generated text, and token usage.
+        """
+        headers = {
+            "Content-Type": "application/json",
+            "anthropic-version": "2023-06-01",
+            "x-api-key": self.settings.api_key,
+        }
+        data = json.dumps(self.to_dict())
+
+        tokens = LlmTokens(prompt=0, generated=0)
+        try:
+            request = self.http.post("/v1/messages", headers=headers, data=data)
+            code = request.status_code
+            response = request.text
+            if code == HTTPStatus.OK.value:
+                content = json.loads(request.text)
+                response = content.get("content", [{}])[0].get("text", "")
+                usage = content.get("usage", {})
+                tokens = LlmTokens(
+                    prompt=usage.get("input_tokens") or 0,
+                    generated=usage.get("output_tokens") or 0,
+                )
+        except exceptions.RequestException as e:
+            code = HTTPStatus.BAD_REQUEST
+            response = f"Request failed: {e}"
+            if message := getattr(e, "response", None):
+                code = message.status_code
+                response = message.text
+
+        return LlmResponse(
+            code=HTTPStatus(code),
+            response=response,
+            tokens=tokens,
+        )
+
+
+__exports__ = ("LlmAnthropic",)

canvas_sdk/clients/llms/libraries/llm_api.py

@@ -0,0 +1,143 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from http import HTTPStatus
+
+from canvas_sdk.clients.llms.structures.llm_response import LlmResponse
+from canvas_sdk.clients.llms.structures.llm_tokens import LlmTokens
+from canvas_sdk.clients.llms.structures.llm_turn import LlmTurn
+from canvas_sdk.clients.llms.structures.settings.llm_settings import LlmSettings
+from canvas_sdk.utils.http import Http
+
+
+class LlmApi(ABC):
+    """Base class for LLM (Large Language Model) API clients.
+
+    Provides common functionality for managing conversation prompts and making requests
+    to various LLM services. Subclasses should implement the request() method for
+    specific LLM providers.
+
+    Class Attributes:
+        ROLE_SYSTEM: Constant for system role in conversations.
+        ROLE_USER: Constant for user role in conversations.
+        ROLE_MODEL: Constant for model/assistant role in conversations.
+    """
+
+    ROLE_SYSTEM = "system"
+    ROLE_USER = "user"
+    ROLE_MODEL = "model"
+
+    def __init__(self, settings: LlmSettings):
+        """Initialize the LLM client with settings.
+
+        Args:
+            settings: Configuration settings for the LLM API.
+        """
+        self.settings = settings
+        self.prompts: list[LlmTurn] = []
+        self.http = Http(self._api_base_url())
+
+    def reset_prompts(self) -> None:
+        """Clear all stored prompts."""
+        self.prompts = []
+
+    def add_prompt(self, prompt: LlmTurn) -> None:
+        """Add a conversation turn to the prompt history.
+
+        Routes the prompt to the appropriate method based on its role.
+
+        Args:
+            prompt: The conversation turn to add.
+        """
+        if prompt.role == self.ROLE_SYSTEM:
+            self.set_system_prompt(prompt.text)
+        elif prompt.role == self.ROLE_USER:
+            self.set_user_prompt(prompt.text)
+        elif prompt.role == self.ROLE_MODEL:
+            self.set_model_prompt(prompt.text)
+
+    def set_system_prompt(self, text: list[str]) -> None:
+        """Set or replace the system prompt.
+
+        The system prompt is always placed at the beginning of the conversation.
+        If a system prompt already exists, it is replaced.
+
+        Args:
+            text: List of text strings for the system prompt.
+        """
+        prompt = LlmTurn(role=self.ROLE_SYSTEM, text=text)
+        if self.prompts and self.prompts[0].role == LlmApi.ROLE_SYSTEM:
+            self.prompts[0] = prompt
+        else:
+            self.prompts.insert(0, prompt)
+
+    def set_user_prompt(self, text: list[str]) -> None:
+        """Add a user prompt to the conversation.
+
+        Args:
+            text: List of text strings for the user prompt.
+        """
+        self.prompts.append(LlmTurn(role=self.ROLE_USER, text=text))
+
+    def set_model_prompt(self, text: list[str]) -> None:
+        """Add a model/assistant response to the conversation.
+
+        Args:
+            text: List of text strings for the model prompt.
+        """
+        self.prompts.append(LlmTurn(role=self.ROLE_MODEL, text=text))
+
+    @abstractmethod
+    def request(self) -> LlmResponse:
+        """Make a request to the LLM API.
+
+        Returns:
+            Response from the LLM including status code, text, and token usage.
+
+        Raises:
+            NotImplementedError: This method must be implemented by subclasses.
+        """
+        ...
+
+    @classmethod
+    @abstractmethod
+    def _api_base_url(cls) -> str:
+        """Provide the API base url to the LlmApi subclass."""
+        ...
+
+    def attempt_requests(self, attempts: int) -> list[LlmResponse]:
+        """Attempt multiple requests to the LLM API until success or max attempts.
+
+        Args:
+            attempts: Maximum number of request attempts to make.
+
+        Returns:
+            All responses from the LLM.
+            If all attempts fail, returns an additional TOO_MANY_REQUESTS response.
+        """
+        result: list[LlmResponse] = []
+        for _ in range(attempts):
+            try:
+                result.append(self.request())
+                if result[-1].code == HTTPStatus.OK:
+                    break
+            except Exception as e:
+                result.append(
+                    LlmResponse(
+                        code=HTTPStatus.INTERNAL_SERVER_ERROR,
+                        response=f"Request attempt failed: {e}",
+                        tokens=LlmTokens(prompt=0, generated=0),
+                    )
+                )
+        else:
+            result.append(
+                LlmResponse(
+                    code=HTTPStatus.TOO_MANY_REQUESTS,
+                    response=f"Http error: max attempts ({attempts}) exceeded.",
+                    tokens=LlmTokens(prompt=0, generated=0),
+                )
+            )
+        return result
+
+
+__exports__ = ("LlmApi",)

canvas_sdk/clients/llms/libraries/llm_google.py

@@ -0,0 +1,92 @@
+import json
+from http import HTTPStatus
+
+from requests import exceptions
+
+from canvas_sdk.clients.llms.libraries.llm_api import LlmApi
+from canvas_sdk.clients.llms.structures.llm_response import LlmResponse
+from canvas_sdk.clients.llms.structures.llm_tokens import LlmTokens
+
+
+class LlmGoogle(LlmApi):
+    """Google Gemini LLM API client.
+
+    Implements the LlmBase interface for Google's Generative Language API.
+    """
+
+    def to_dict(self) -> dict:
+        """Convert prompts and add the necessary information to Google API request format.
+
+        Returns:
+            Dictionary formatted for Google API with contents array.
+        """
+        contents: list[dict] = []
+        roles = {
+            self.ROLE_SYSTEM: "user",
+            self.ROLE_USER: "user",
+            self.ROLE_MODEL: "model",
+        }
+        for prompt in self.prompts:
+            role = roles[prompt.role]
+            part = {"text": "\n".join(prompt.text)}
+            # contiguous parts for the same role are merged
+            if contents and contents[-1]["role"] == role:
+                contents[-1]["parts"].append(part)
+            else:
+                contents.append({"role": role, "parts": [part]})
+
+        return self.settings.to_dict() | {
+            "contents": contents,
+        }
+
+    @classmethod
+    def _api_base_url(cls) -> str:
+        return "https://generativelanguage.googleapis.com"
+
+    def request(self) -> LlmResponse:
+        """Make a request to the Google Gemini API.
+
+        Returns:
+            Response containing status code, generated text, and token usage.
+        """
+        headers = {"Content-Type": "application/json"}
+        data = json.dumps(self.to_dict())
+
+        tokens = LlmTokens(prompt=0, generated=0)
+        try:
+            request = self.http.post(
+                f"/v1beta/{self.settings.model}:generateContent?key={self.settings.api_key}",
+                headers=headers,
+                data=data,
+            )
+            code = request.status_code
+            response = request.text
+            if code == HTTPStatus.OK.value:
+                content = json.loads(request.text)
+                response = (
+                    content.get("candidates", [{}])[0]
+                    .get("content", {})
+                    .get("parts", [{}])[0]
+                    .get("text", "")
+                )
+                usage = content.get("usageMetadata", {})
+                tokens = LlmTokens(
+                    prompt=usage.get("promptTokenCount") or 0,
+                    generated=(usage.get("candidatesTokenCount") or 0)
+                    + (usage.get("thoughtsTokenCount") or 0),
+                )
+        except exceptions.RequestException as e:
+            code = HTTPStatus.BAD_REQUEST
+            response = f"Request failed: {e}"
+            if message := getattr(e, "response", None):
+                code = message.status_code
+                response = message.text
+
+        return LlmResponse(
+            code=HTTPStatus(code),
+            response=response,
+            tokens=tokens,
+        )
+
+
+__exports__ = ("LlmGoogle",)

canvas_sdk/clients/llms/libraries/llm_openai.py

@@ -0,0 +1,98 @@
+from __future__ import annotations
+
+import json
+from http import HTTPStatus
+
+from requests import exceptions
+
+from canvas_sdk.clients.llms.libraries.llm_api import LlmApi
+from canvas_sdk.clients.llms.structures.llm_response import LlmResponse
+from canvas_sdk.clients.llms.structures.llm_tokens import LlmTokens
+
+
+class LlmOpenai(LlmApi):
+    """OpenAI LLM API client.
+
+    Implements the LlmBase interface for OpenAI's API.
+    """
+
+    def to_dict(self) -> dict:
+        """Convert prompts and add the necessary information to OpenAI API request format.
+
+        Returns:
+            Dictionary formatted for OpenAI API with instructions and input messages.
+        """
+        roles = {
+            self.ROLE_SYSTEM: "developer",
+            self.ROLE_USER: "user",
+            self.ROLE_MODEL: "assistant",
+        }
+        messages: list[dict] = [
+            {
+                "role": roles[prompt.role],
+                "content": [
+                    {
+                        "type": "input_text" if prompt.role == self.ROLE_USER else "output_text",
+                        "text": "\n".join(prompt.text),
+                    }
+                ],
+            }
+            for prompt in self.prompts
+            if prompt.role != self.ROLE_SYSTEM
+        ]
+
+        system_prompt = "\n".join(
+            ["\n".join(prompt.text) for prompt in self.prompts if prompt.role == self.ROLE_SYSTEM]
+        )
+        return self.settings.to_dict() | {
+            "instructions": system_prompt,
+            "input": messages,
+        }
+
+    @classmethod
+    def _api_base_url(cls) -> str:
+        return "https://us.api.openai.com"
+
+    def request(self) -> LlmResponse:
+        """Make a request to the OpenAI API.
+
+        Returns:
+            Response containing status code, generated text, and token usage.
+        """
+        headers = {
+            "Content-Type": "application/json",
+            "Authorization": f"Bearer {self.settings.api_key}",
+        }
+        data = json.dumps(self.to_dict())
+
+        tokens = LlmTokens(prompt=0, generated=0)
+        try:
+            request = self.http.post("/v1/responses", headers=headers, data=data)
+            code = request.status_code
+            response = request.text
+            if code == HTTPStatus.OK.value:
+                content = json.loads(request.text)
+                response = ""
+                for output in content.get("output", [{}]):
+                    if output.get("type", "") == "message":
+                        response += output.get("content", [{}])[0].get("text", "")
+                usage = content.get("usage", {})
+                tokens = LlmTokens(
+                    prompt=usage.get("input_tokens") or 0,
+                    generated=usage.get("output_tokens") or 0,
+                )
+        except exceptions.RequestException as e:
+            code = HTTPStatus.BAD_REQUEST
+            response = f"Request failed: {e}"
+            if message := getattr(e, "response", None):
+                code = message.status_code
+                response = message.text
+
+        return LlmResponse(
+            code=HTTPStatus(code),
+            response=response,
+            tokens=tokens,
+        )
+
+
+__exports__ = ("LlmOpenai",)

canvas_sdk/clients/llms/structures/__init__.py

@@ -0,0 +1,9 @@
+from canvas_sdk.clients.llms.structures.llm_response import LlmResponse
+from canvas_sdk.clients.llms.structures.llm_tokens import LlmTokens
+from canvas_sdk.clients.llms.structures.llm_turn import LlmTurn
+
+__all__ = __exports__ = (
+    "LlmResponse",
+    "LlmTokens",
+    "LlmTurn",
+)

canvas_sdk/clients/llms/structures/llm_response.py

@@ -0,0 +1,33 @@
+from http import HTTPStatus
+from typing import NamedTuple
+
+from canvas_sdk.clients.llms.structures.llm_tokens import LlmTokens
+
+
+class LlmResponse(NamedTuple):
+    """Response from an LLM API call.
+
+    Attributes:
+        code: HTTP status code of the response.
+        response: Text content returned by the LLM.
+        tokens: Token usage information for the request.
+    """
+
+    code: HTTPStatus
+    response: str
+    tokens: LlmTokens
+
+    def to_dict(self) -> dict:
+        """Convert the response to a dictionary representation.
+
+        Returns:
+            Dictionary containing the response data with serialized code, response text, and tokens.
+        """
+        return {
+            "code": self.code.value,
+            "response": self.response,
+            "tokens": self.tokens.to_dict(),
+        }
+
+
+__exports__ = ("LlmResponse",)

canvas_sdk/clients/llms/structures/llm_tokens.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+
+class LlmTokens:
+    """Token usage information for LLM API calls.
+
+    Tracks the number of tokens used in prompts and generated responses.
+    """
+
+    def __init__(self, prompt: int, generated: int):
+        """Initialize token counts.
+
+        Args:
+            prompt: Number of tokens in the prompt.
+            generated: Number of tokens in the generated response.
+        """
+        self.prompt = prompt
+        self.generated = generated
+
+    def add(self, counts: LlmTokens) -> None:
+        """Add token counts from another LlmTokens instance.
+
+        Args:
+            counts: Token counts to add to this instance.
+        """
+        self.prompt = self.prompt + counts.prompt
+        self.generated = self.generated + counts.generated
+
+    def __eq__(self, other: object) -> bool:
+        """Compare two LlmTokens instances for equality.
+
+        Args:
+            other: Object to compare with.
+
+        Returns:
+            True if both prompt and generated counts are equal.
+        """
+        assert isinstance(other, LlmTokens)
+        return self.prompt == other.prompt and self.generated == other.generated
+
+    def to_dict(self) -> dict:
+        """Convert token counts to a dictionary representation.
+
+        Returns:
+            Dictionary with 'prompt' and 'generated' keys.
+        """
+        return {
+            "prompt": self.prompt,
+            "generated": self.generated,
+        }
+
+
+__exports__ = ("LlmTokens",)

canvas_sdk/clients/llms/structures/llm_turn.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+from typing import NamedTuple
+
+
+class LlmTurn(NamedTuple):
+    """A single conversation turn in an LLM interaction.
+
+    Attributes:
+        role: The role of the speaker (e.g., 'system', 'user', 'model').
+        text: List of text strings for this turn.
+    """
+
+    role: str
+    text: list[str]
+
+    def to_dict(self) -> dict:
+        """Convert the turn to a dictionary representation.
+
+        Returns:
+            Dictionary with 'role' and 'text' keys.
+        """
+        return {
+            "role": self.role,
+            "text": self.text,
+        }
+
+    @classmethod
+    def load_from_dict(cls, dict_list: list[dict]) -> list[LlmTurn]:
+        """Load a list of turns from a list of dictionaries.
+
+        Args:
+            dict_list: List of dictionaries, each containing 'role' and 'text' keys.
+
+        Returns:
+            List of LlmTurn instances created from the dictionaries.
+        """
+        return [
+            LlmTurn(
+                role=json_object.get("role") or "",
+                text=json_object.get("text") or [],
+            )
+            for json_object in dict_list
+        ]
+
+
+__exports__ = ("LlmTurn",)

canvas_sdk/clients/llms/structures/settings/__init__.py

@@ -0,0 +1,13 @@
+from canvas_sdk.clients.llms.structures.settings.llm_settings import LlmSettings
+from canvas_sdk.clients.llms.structures.settings.llm_settings_anthropic import LlmSettingsAnthropic
+from canvas_sdk.clients.llms.structures.settings.llm_settings_gemini import LlmSettingsGemini
+from canvas_sdk.clients.llms.structures.settings.llm_settings_gpt4 import LlmSettingsGpt4
+from canvas_sdk.clients.llms.structures.settings.llm_settings_gpt5 import LlmSettingsGpt5
+
+__all__ = __exports__ = (
+    "LlmSettings",
+    "LlmSettingsAnthropic",
+    "LlmSettingsGemini",
+    "LlmSettingsGpt4",
+    "LlmSettingsGpt5",
+)

canvas_sdk/clients/llms/structures/settings/llm_settings.py

@@ -0,0 +1,27 @@
+from dataclasses import dataclass
+
+
+@dataclass
+class LlmSettings:
+    """Configuration settings for an LLM API.
+
+    Attributes:
+        api_key: API authentication key for the LLM service.
+        model: Name or identifier of the LLM model to use.
+    """
+
+    api_key: str
+    model: str
+
+    def to_dict(self) -> dict:
+        """Convert settings to a dictionary representation.
+
+        Returns:
+            Dictionary containing the model name (excludes API key for security).
+        """
+        return {
+            "model": self.model,
+        }
+
+
+__exports__ = ("LlmSettings",)

canvas_sdk/clients/llms/structures/settings/llm_settings_anthropic.py

@@ -0,0 +1,43 @@
+from dataclasses import dataclass
+
+from canvas_sdk.clients.llms.structures.settings.llm_settings import LlmSettings
+
+
+@dataclass
+class LlmSettingsAnthropic(LlmSettings):
+    """Configuration settings for Anthropic Claude LLM API.
+
+    Extends LlmSettings with Anthropic-specific parameters.
+
+    Attributes:
+        api_key: API authentication key for the LLM service (inherited).
+        model: Name or identifier of the LLM model to use (inherited).
+        temperature: Controls randomness in responses (0.0-1.0).
+        max_tokens: Maximum number of tokens to generate.
+    example:
+        ```python3
+        LlmSettingsAnthropic(
+            api_key=environ.get("anthropic_key"),
+            model="claude-sonnet-4-5-20250929",
+            temperature=0.78,
+            max_tokens=8192,
+        )
+        ```
+    """
+
+    temperature: float
+    max_tokens: float
+
+    def to_dict(self) -> dict:
+        """Convert settings to Anthropic API request format.
+
+        Returns:
+            Dictionary containing model name, temperature, and max_tokens.
+        """
+        return super().to_dict() | {
+            "temperature": self.temperature,
+            "max_tokens": self.max_tokens,
+        }
+
+
+__exports__ = ("LlmSettingsAnthropic",)