sdkrouter 0.1.1__py3-none-any.whl

sdkrouter/_client.py

@@ -0,0 +1,432 @@
+"""Main SDK client classes."""
+
+import json
+import os
+from typing import Any, Optional, Type
+
+from openai import AsyncOpenAI, OpenAI
+
+from ._config import SDKConfig
+from ._constants import (
+    DEFAULT_BASE_URL,
+    DEFAULT_MAX_RETRIES,
+    DEFAULT_OPENROUTER_URL,
+    DEFAULT_TIMEOUT,
+    ENV_API_KEY,
+    ENV_OPENROUTER_KEY,
+)
+from ._types.parsed import ParsedChatCompletion, ParsedChoice
+from .tools.vision import AsyncVisionResource, VisionResource
+from .tools.cdn import AsyncCDNResource, CDNResource
+from .tools.shortlinks import AsyncShortlinksResource, ShortlinksResource
+from .tools.keys import AsyncKeysResource, KeysResource
+from .tools.cleaner import AsyncCleanerResource, CleanerResource
+from .tools.models import AsyncModelsResource, ModelsResource
+from .utils.parsing import ResponseFormatT, type_to_response_format
+
+
+def _parse_completion(
+    raw_response: Any,
+    response_format: Type[ResponseFormatT],
+) -> ParsedChatCompletion[ResponseFormatT]:
+    """
+    Parse raw ChatCompletion into ParsedChatCompletion with typed content.
+
+    Args:
+        raw_response: Raw ChatCompletion from OpenAI API
+        response_format: Pydantic model class for parsing
+
+    Returns:
+        ParsedChatCompletion with parsed content in each choice
+    """
+    parsed_choices: list[ParsedChoice[ResponseFormatT]] = []
+
+    for choice in raw_response.choices:
+        parsed_content = None
+        content = getattr(choice.message, "content", None)
+
+        if content:
+            try:
+                data = json.loads(content)
+                parsed_content = response_format.model_validate(data)
+            except (json.JSONDecodeError, Exception):
+                # If parsing fails, leave parsed as None
+                pass
+
+        parsed_choices.append(
+            ParsedChoice.from_choice(choice, parsed_content=parsed_content)
+        )
+
+    return ParsedChatCompletion.from_completion(raw_response, parsed_choices)
+
+
+class SDKRouter(OpenAI):
+    """
+    Main SDK client - OpenAI-compatible with additional tools.
+
+    Extends OpenAI client with vision, OCR, CDN, and shortlinks tools.
+
+    Example:
+        ```python
+        from sdkrouter import SDKRouter
+
+        client = SDKRouter(api_key="your-api-key")
+
+        # OpenAI-compatible chat
+        response = client.chat.completions.create(
+            model="openai/gpt-4o",
+            messages=[{"role": "user", "content": "Hello!"}],
+        )
+
+        # Vision analysis
+        result = client.vision.analyze(image_url="https://example.com/image.jpg")
+
+        # CDN upload
+        file = client.cdn.upload(Path("image.png"))
+        ```
+    """
+
+    def __init__(
+        self,
+        *,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        use_self_hosted: bool = True,
+        openrouter_api_key: Optional[str] = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        **kwargs,
+    ):
+        """
+        Initialize SDKRouter client.
+
+        Args:
+            api_key: API key (or set SDKROUTER_API_KEY env var)
+            base_url: Base URL for API (default: ai.sdkrouter.com)
+            use_self_hosted: If True, use self-hosted proxy. If False, direct to OpenRouter
+            openrouter_api_key: OpenRouter API key (for direct mode)
+            timeout: Request timeout in seconds
+            max_retries: Number of retries for failed requests
+            **kwargs: Additional arguments passed to OpenAI client
+        """
+        # Resolve API key
+        resolved_key = (
+            api_key
+            or os.getenv(ENV_API_KEY)
+            or openrouter_api_key
+            or os.getenv(ENV_OPENROUTER_KEY)
+        )
+        if not resolved_key:
+            raise ValueError(
+                "API key required. Set SDKROUTER_API_KEY environment variable "
+                "or pass api_key= parameter."
+            )
+
+        # Resolve base URL
+        if use_self_hosted:
+            resolved_url = base_url or os.getenv("SDKROUTER_BASE_URL") or DEFAULT_BASE_URL
+        else:
+            resolved_url = DEFAULT_OPENROUTER_URL
+
+        # Initialize OpenAI client
+        super().__init__(
+            api_key=resolved_key,
+            base_url=resolved_url,
+            timeout=timeout,
+            max_retries=max_retries,
+            **kwargs,
+        )
+
+        # Store configuration
+        self._sdk_config = SDKConfig(
+            api_key=resolved_key,
+            base_url=resolved_url,
+            use_self_hosted=use_self_hosted,
+            timeout=timeout,
+            max_retries=max_retries,
+        )
+
+        # Lazy-loaded tool resources
+        self._vision: Optional[VisionResource] = None
+        self._cdn: Optional[CDNResource] = None
+        self._shortlinks: Optional[ShortlinksResource] = None
+        self._keys: Optional[KeysResource] = None
+        self._cleaner: Optional[CleanerResource] = None
+        self._models: Optional[ModelsResource] = None
+
+    @property
+    def vision(self) -> VisionResource:
+        """Vision analysis and OCR tool."""
+        if self._vision is None:
+            self._vision = VisionResource(self._sdk_config)
+        return self._vision
+
+    @property
+    def cdn(self) -> CDNResource:
+        """CDN file storage tool."""
+        if self._cdn is None:
+            self._cdn = CDNResource(self._sdk_config)
+        return self._cdn
+
+    @property
+    def shortlinks(self) -> ShortlinksResource:
+        """URL shortening tool."""
+        if self._shortlinks is None:
+            self._shortlinks = ShortlinksResource(self._sdk_config)
+        return self._shortlinks
+
+    @property
+    def keys(self) -> KeysResource:
+        """API keys management tool."""
+        if self._keys is None:
+            self._keys = KeysResource(self._sdk_config)
+        return self._keys
+
+    @property
+    def cleaner(self) -> CleanerResource:
+        """HTML cleaner tool."""
+        if self._cleaner is None:
+            self._cleaner = CleanerResource(self._sdk_config)
+        return self._cleaner
+
+    @property
+    def models(self) -> ModelsResource:
+        """LLM models listing tool."""
+        if self._models is None:
+            self._models = ModelsResource(self._sdk_config)
+        return self._models
+
+    @property
+    def config(self) -> SDKConfig:
+        """SDK configuration."""
+        return self._sdk_config
+
+    def parse(
+        self,
+        *,
+        model: str,
+        messages: list[dict[str, Any]],
+        response_format: Type[ResponseFormatT],
+        **kwargs: Any,
+    ) -> ParsedChatCompletion[ResponseFormatT]:
+        """
+        Create chat completion with structured output.
+
+        Automatically converts Pydantic model to JSON Schema and parses
+        the response back into the model.
+
+        Args:
+            model: Model ID (e.g., "openai/gpt-4o")
+            messages: Chat messages
+            response_format: Pydantic model class for response parsing
+            **kwargs: Additional parameters (temperature, max_tokens, etc.)
+
+        Returns:
+            ParsedChatCompletion with .choices[0].message.parsed
+
+        Example:
+            ```python
+            class MathResponse(BaseModel):
+                steps: list[str]
+                answer: float
+
+            result = client.parse(
+                model="openai/gpt-4o",
+                messages=[{"role": "user", "content": "Solve 2+2"}],
+                response_format=MathResponse,
+            )
+            print(result.choices[0].message.parsed.answer)
+            ```
+        """
+        # Convert Pydantic model to response_format
+        format_param = type_to_response_format(response_format)
+
+        # Make API call
+        raw_response = self.chat.completions.create(
+            model=model,
+            messages=messages,
+            response_format=format_param,
+            **kwargs,
+        )
+
+        # Parse response
+        return _parse_completion(raw_response, response_format)
+
+
+class AsyncSDKRouter(AsyncOpenAI):
+    """
+    Async SDK client - OpenAI-compatible with additional tools.
+
+    Async version of SDKRouter for use in async contexts.
+
+    Example:
+        ```python
+        from sdkrouter import AsyncSDKRouter
+
+        client = AsyncSDKRouter(api_key="your-api-key")
+
+        # Async chat
+        response = await client.chat.completions.create(
+            model="openai/gpt-4o",
+            messages=[{"role": "user", "content": "Hello!"}],
+        )
+
+        # Async vision
+        result = await client.vision.analyze(image_url="https://example.com/image.jpg")
+        ```
+    """
+
+    def __init__(
+        self,
+        *,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        use_self_hosted: bool = True,
+        openrouter_api_key: Optional[str] = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        **kwargs,
+    ):
+        """Initialize async SDKRouter client."""
+        # Resolve API key
+        resolved_key = (
+            api_key
+            or os.getenv(ENV_API_KEY)
+            or openrouter_api_key
+            or os.getenv(ENV_OPENROUTER_KEY)
+        )
+        if not resolved_key:
+            raise ValueError(
+                "API key required. Set SDKROUTER_API_KEY environment variable "
+                "or pass api_key= parameter."
+            )
+
+        # Resolve base URL
+        if use_self_hosted:
+            resolved_url = base_url or os.getenv("SDKROUTER_BASE_URL") or DEFAULT_BASE_URL
+        else:
+            resolved_url = DEFAULT_OPENROUTER_URL
+
+        # Initialize AsyncOpenAI client
+        super().__init__(
+            api_key=resolved_key,
+            base_url=resolved_url,
+            timeout=timeout,
+            max_retries=max_retries,
+            **kwargs,
+        )
+
+        # Store configuration
+        self._sdk_config = SDKConfig(
+            api_key=resolved_key,
+            base_url=resolved_url,
+            use_self_hosted=use_self_hosted,
+            timeout=timeout,
+            max_retries=max_retries,
+        )
+
+        # Lazy-loaded async tool resources
+        self._vision: Optional[AsyncVisionResource] = None
+        self._cdn: Optional[AsyncCDNResource] = None
+        self._shortlinks: Optional[AsyncShortlinksResource] = None
+        self._keys: Optional[AsyncKeysResource] = None
+        self._cleaner: Optional[AsyncCleanerResource] = None
+        self._models: Optional[AsyncModelsResource] = None
+
+    @property
+    def vision(self) -> AsyncVisionResource:
+        """Vision analysis and OCR tool (async)."""
+        if self._vision is None:
+            self._vision = AsyncVisionResource(self._sdk_config)
+        return self._vision
+
+    @property
+    def cdn(self) -> AsyncCDNResource:
+        """CDN file storage tool (async)."""
+        if self._cdn is None:
+            self._cdn = AsyncCDNResource(self._sdk_config)
+        return self._cdn
+
+    @property
+    def shortlinks(self) -> AsyncShortlinksResource:
+        """URL shortening tool (async)."""
+        if self._shortlinks is None:
+            self._shortlinks = AsyncShortlinksResource(self._sdk_config)
+        return self._shortlinks
+
+    @property
+    def keys(self) -> AsyncKeysResource:
+        """API keys management tool (async)."""
+        if self._keys is None:
+            self._keys = AsyncKeysResource(self._sdk_config)
+        return self._keys
+
+    @property
+    def cleaner(self) -> AsyncCleanerResource:
+        """HTML cleaner tool (async)."""
+        if self._cleaner is None:
+            self._cleaner = AsyncCleanerResource(self._sdk_config)
+        return self._cleaner
+
+    @property
+    def models(self) -> AsyncModelsResource:
+        """LLM models listing tool (async)."""
+        if self._models is None:
+            self._models = AsyncModelsResource(self._sdk_config)
+        return self._models
+
+    @property
+    def config(self) -> SDKConfig:
+        """SDK configuration."""
+        return self._sdk_config
+
+    async def parse(
+        self,
+        *,
+        model: str,
+        messages: list[dict[str, Any]],
+        response_format: Type[ResponseFormatT],
+        **kwargs: Any,
+    ) -> ParsedChatCompletion[ResponseFormatT]:
+        """
+        Create async chat completion with structured output.
+
+        Automatically converts Pydantic model to JSON Schema and parses
+        the response back into the model.
+
+        Args:
+            model: Model ID (e.g., "openai/gpt-4o")
+            messages: Chat messages
+            response_format: Pydantic model class for response parsing
+            **kwargs: Additional parameters (temperature, max_tokens, etc.)
+
+        Returns:
+            ParsedChatCompletion with .choices[0].message.parsed
+
+        Example:
+            ```python
+            class MathResponse(BaseModel):
+                steps: list[str]
+                answer: float
+
+            result = await client.parse(
+                model="openai/gpt-4o",
+                messages=[{"role": "user", "content": "Solve 2+2"}],
+                response_format=MathResponse,
+            )
+            print(result.choices[0].message.parsed.answer)
+            ```
+        """
+        # Convert Pydantic model to response_format
+        format_param = type_to_response_format(response_format)
+
+        # Make API call
+        raw_response = await self.chat.completions.create(
+            model=model,
+            messages=messages,
+            response_format=format_param,
+            **kwargs,
+        )
+
+        # Parse response
+        return _parse_completion(raw_response, response_format)

sdkrouter/_config.py

@@ -0,0 +1,74 @@
+"""SDK configuration."""
+
+from typing import Optional
+
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+from ._constants import (
+    DEFAULT_BASE_URL,
+    DEFAULT_CDN_URL,
+    DEFAULT_CONNECT_TIMEOUT,
+    DEFAULT_DJANGO_URL,
+    DEFAULT_MAX_RETRIES,
+    DEFAULT_OPENAI_URL,
+    DEFAULT_OPENROUTER_URL,
+    DEFAULT_TIMEOUT,
+)
+
+
+class SDKConfig(BaseSettings):
+    """SDK configuration with environment variable support."""
+
+    model_config = SettingsConfigDict(
+        env_prefix="SDKROUTER_",
+        env_file=".env",
+        extra="ignore",
+    )
+
+    # API Keys
+    api_key: Optional[str] = None
+    openrouter_api_key: Optional[str] = None
+    openai_api_key: Optional[str] = None
+
+    # Base URLs (for self-hosted or direct)
+    base_url: str = DEFAULT_BASE_URL
+    django_url: str = DEFAULT_DJANGO_URL
+    cdn_url: str = DEFAULT_CDN_URL
+
+    # Direct provider URLs (bypass self-hosted)
+    openrouter_url: str = DEFAULT_OPENROUTER_URL
+    openai_url: str = DEFAULT_OPENAI_URL
+
+    # Routing mode
+    use_self_hosted: bool = True  # False = direct to OpenRouter/OpenAI
+
+    # Timeouts
+    timeout: float = DEFAULT_TIMEOUT
+    connect_timeout: float = DEFAULT_CONNECT_TIMEOUT
+
+    # Retry
+    max_retries: int = DEFAULT_MAX_RETRIES
+
+
+_config: Optional[SDKConfig] = None
+
+
+def get_config() -> SDKConfig:
+    """Get or create SDK configuration."""
+    global _config
+    if _config is None:
+        _config = SDKConfig()
+    return _config
+
+
+def configure(**kwargs) -> SDKConfig:
+    """Configure SDK with custom settings."""
+    global _config
+    _config = SDKConfig(**kwargs)
+    return _config
+
+
+def reset_config() -> None:
+    """Reset configuration to defaults."""
+    global _config
+    _config = None

sdkrouter/_constants.py

@@ -0,0 +1,21 @@
+"""SDK constants and defaults."""
+
+# Environment variable names
+ENV_API_KEY = "SDKROUTER_API_KEY"
+ENV_OPENROUTER_KEY = "OPENROUTER_API_KEY"
+ENV_OPENAI_KEY = "OPENAI_API_KEY"
+ENV_BASE_URL = "SDKROUTER_BASE_URL"
+ENV_DJANGO_URL = "SDKROUTER_DJANGO_URL"
+ENV_CDN_URL = "SDKROUTER_CDN_URL"
+
+# Default URLs
+DEFAULT_BASE_URL = "https://ai.sdkrouter.com/v1"
+DEFAULT_DJANGO_URL = "https://api.sdkrouter.com"
+DEFAULT_CDN_URL = "https://cdn.sdkrouter.com"
+DEFAULT_OPENROUTER_URL = "https://openrouter.ai/api/v1"
+DEFAULT_OPENAI_URL = "https://api.openai.com/v1"
+
+# Default settings
+DEFAULT_TIMEOUT = 60.0
+DEFAULT_CONNECT_TIMEOUT = 5.0
+DEFAULT_MAX_RETRIES = 2

sdkrouter/_internal/__init__.py

@@ -0,0 +1 @@
+"""Internal helpers (not part of public API)."""

sdkrouter/_types/__init__.py

@@ -0,0 +1,30 @@
+"""Type definitions for SDK resources."""
+
+from .cdn import CDNFile, CDNUploadRequest
+from .models import Model, ModelPricing
+from .ocr import OCRRequest, OCRResponse
+from .parsed import ParsedChatCompletion, ParsedChoice, ParsedMessage
+from .shortlinks import ShortLink, ShortLinkCreateRequest
+from .vision import VisionAnalyzeRequest, VisionAnalyzeResponse
+
+__all__ = [
+    # CDN
+    "CDNFile",
+    "CDNUploadRequest",
+    # Models
+    "Model",
+    "ModelPricing",
+    # OCR
+    "OCRRequest",
+    "OCRResponse",
+    # Parsed (structured output)
+    "ParsedChatCompletion",
+    "ParsedChoice",
+    "ParsedMessage",
+    # Shortlinks
+    "ShortLink",
+    "ShortLinkCreateRequest",
+    # Vision
+    "VisionAnalyzeRequest",
+    "VisionAnalyzeResponse",
+]

sdkrouter/_types/cdn.py

@@ -0,0 +1,27 @@
+"""CDN types."""
+
+from datetime import datetime
+from typing import Optional
+
+from pydantic import BaseModel, Field
+
+
+class CDNUploadRequest(BaseModel):
+    """Request for CDN file upload."""
+
+    filename: Optional[str] = Field(default=None, description="Original filename")
+    content_type: Optional[str] = Field(default=None, description="MIME type")
+    ttl: str = Field(default="30d", description="Time to live (e.g., '7d', '30d', '1y')")
+
+
+class CDNFile(BaseModel):
+    """CDN file information."""
+
+    uuid: str = Field(description="Unique file identifier")
+    short_code: str = Field(description="Short code for URL")
+    filename: str = Field(description="Original filename")
+    content_type: str = Field(description="MIME type")
+    size_bytes: int = Field(description="File size in bytes")
+    url: str = Field(description="Full URL to access file")
+    expires_at: Optional[datetime] = Field(default=None, description="Expiration time")
+    created_at: Optional[datetime] = Field(default=None, description="Upload time")

sdkrouter/_types/models.py

@@ -0,0 +1,26 @@
+"""Model types."""
+
+from typing import Optional
+
+from pydantic import BaseModel, Field
+
+
+class ModelPricing(BaseModel):
+    """Model pricing information."""
+
+    prompt: float = Field(description="Cost per 1M input tokens")
+    completion: float = Field(description="Cost per 1M output tokens")
+    image: Optional[float] = Field(default=None, description="Cost per image")
+
+
+class Model(BaseModel):
+    """LLM model information."""
+
+    id: str = Field(description="Model identifier")
+    name: str = Field(description="Display name")
+    provider: str = Field(description="Provider name")
+    context_length: int = Field(description="Max context length")
+    pricing: ModelPricing = Field(description="Pricing information")
+    supports_vision: bool = Field(default=False, description="Supports image input")
+    supports_tools: bool = Field(default=False, description="Supports function calling")
+    supports_json: bool = Field(default=False, description="Supports JSON mode")

sdkrouter/_types/ocr.py

@@ -0,0 +1,24 @@
+"""OCR types."""
+
+from typing import Literal, Optional
+
+from pydantic import BaseModel, Field
+
+
+class OCRRequest(BaseModel):
+    """Request for OCR text extraction."""
+
+    image: Optional[str] = Field(default=None, description="Base64 encoded image")
+    image_url: Optional[str] = Field(default=None, description="URL of image")
+    mode: Literal["tiny", "small", "base", "gundam"] = Field(
+        default="base", description="OCR model size/quality"
+    )
+
+
+class OCRResponse(BaseModel):
+    """Response from OCR extraction."""
+
+    text: str = Field(description="Extracted text")
+    model: str = Field(description="Model used")
+    cost_usd: float = Field(description="Cost in USD")
+    cached: bool = Field(default=False, description="Whether result was from cache")