huitzo-sdk 0.0.0__py3-none-any.whl

huitzo_sdk/integrations/email.py

@@ -0,0 +1,109 @@
+"""
+Module: integrations.email
+Description: Email integration client for sending emails and templates.
+
+Implements:
+    - docs/sdk/integrations.md#email-integration
+
+See Also:
+    - docs/sdk/error-handling.md (for EmailError)
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class EmailBackend(Protocol):
+    """Backend protocol for email providers."""
+
+    async def send(
+        self,
+        *,
+        to: str | list[str],
+        subject: str,
+        body: str | None,
+        html: str | None,
+        cc: list[str] | None,
+        bcc: list[str] | None,
+        attachments: list[dict[str, Any]] | None,
+    ) -> None: ...
+
+    async def send_template(
+        self,
+        *,
+        to: str | list[str],
+        template_id: str,
+        template_data: dict[str, Any] | None,
+    ) -> None: ...
+
+
+@dataclass
+class EmailClient:
+    """Client for sending emails.
+
+    This is the SDK-side interface. The backend injects a real implementation
+    at runtime (SendGrid, SMTP, etc.).
+    """
+
+    _backend: EmailBackend
+
+    async def send(
+        self,
+        *,
+        to: str | list[str],
+        subject: str,
+        body: str | None = None,
+        html: str | None = None,
+        cc: list[str] | None = None,
+        bcc: list[str] | None = None,
+        attachments: list[dict[str, Any]] | None = None,
+    ) -> None:
+        """Send an email.
+
+        Args:
+            to: Recipient(s).
+            subject: Email subject.
+            body: Plain text body.
+            html: HTML body.
+            cc: CC recipients.
+            bcc: BCC recipients.
+            attachments: List of attachment dicts with filename, content, content_type.
+
+        Raises:
+            EmailError: If sending fails.
+        """
+        await self._backend.send(
+            to=to,
+            subject=subject,
+            body=body,
+            html=html,
+            cc=cc,
+            bcc=bcc,
+            attachments=attachments,
+        )
+
+    async def send_template(
+        self,
+        *,
+        to: str | list[str],
+        template_id: str,
+        template_data: dict[str, Any] | None = None,
+    ) -> None:
+        """Send a templated email.
+
+        Args:
+            to: Recipient(s).
+            template_id: Provider template ID.
+            template_data: Template variable substitutions.
+
+        Raises:
+            EmailError: If sending fails.
+        """
+        await self._backend.send_template(
+            to=to,
+            template_id=template_id,
+            template_data=template_data,
+        )

huitzo_sdk/integrations/files.py

@@ -0,0 +1,188 @@
+"""
+Module: integrations.files
+Description: File integration client for reading and writing files with backend abstraction.
+
+Implements:
+    - docs/sdk/integrations.md#files-integration
+
+See Also:
+    - docs/sdk/context.md (for Context wiring)
+"""
+
+from __future__ import annotations
+
+import builtins
+from dataclasses import dataclass
+from typing import Any, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class FileStorageBackend(Protocol):
+    """Backend protocol for file storage (local, S3, Azure, GCS)."""
+
+    async def read(self, path: str) -> bytes: ...
+
+    async def write(self, path: str, content: bytes) -> None: ...
+
+    async def info(self, path: str) -> dict[str, Any]: ...
+
+    async def list(self, prefix: str) -> builtins.list[dict[str, Any]]: ...
+
+    async def exists(self, path: str) -> bool: ...
+
+    async def get_url(self, path: str, *, expires: int) -> str: ...
+
+
+@dataclass
+class FileClient:
+    """Client for reading and writing files.
+
+    Backend-agnostic: works with local filesystem, S3, Azure Blob, or GCS.
+    Tenant path isolation is handled automatically by the backend.
+    """
+
+    _backend: FileStorageBackend
+
+    async def read_excel(
+        self,
+        path: str,
+        *,
+        sheet: str | None = None,
+    ) -> Any:
+        """Read an Excel file and return a DataFrame.
+
+        Args:
+            path: Relative file path.
+            sheet: Specific sheet name (default: first sheet).
+
+        Returns:
+            pandas DataFrame.
+
+        Raises:
+            ImportError: If pandas is not installed.
+            IntegrationError: If the backend read fails.
+        """
+        data = await self._backend.read(path)
+        import io
+
+        try:
+            import pandas as pd
+        except ImportError as exc:
+            raise ImportError("pandas is required for read_excel") from exc
+        kwargs: dict[str, Any] = {}
+        if sheet is not None:
+            kwargs["sheet_name"] = sheet
+        return pd.read_excel(io.BytesIO(data), **kwargs)
+
+    async def read_csv(
+        self,
+        path: str,
+        *,
+        delimiter: str = ",",
+        encoding: str = "utf-8",
+    ) -> Any:
+        """Read a CSV file and return a DataFrame.
+
+        Args:
+            path: Relative file path.
+            delimiter: Column delimiter.
+            encoding: File encoding.
+
+        Returns:
+            pandas DataFrame.
+
+        Raises:
+            ImportError: If pandas is not installed.
+            IntegrationError: If the backend read fails.
+        """
+        data = await self._backend.read(path)
+        import io
+
+        try:
+            import pandas as pd
+        except ImportError as exc:
+            raise ImportError("pandas is required for read_csv") from exc
+        return pd.read_csv(io.BytesIO(data), delimiter=delimiter, encoding=encoding)
+
+    async def read_json(self, path: str) -> Any:
+        """Read a JSON file.
+
+        Args:
+            path: Relative file path.
+
+        Returns:
+            Parsed JSON data.
+
+        Raises:
+            IntegrationError: If the backend read fails.
+            json.JSONDecodeError: If file content is not valid JSON.
+        """
+        import json
+
+        data = await self._backend.read(path)
+        return json.loads(data)
+
+    async def write(
+        self,
+        path: str,
+        content: str | bytes,
+        *,
+        binary: bool = False,
+    ) -> None:
+        """Write content to a file.
+
+        Args:
+            path: Relative file path.
+            content: File content (string or bytes).
+            binary: If True, content is bytes.
+
+        Raises:
+            IntegrationError: If the backend write fails.
+        """
+        if isinstance(content, str):
+            raw = content.encode("utf-8")
+        else:
+            raw = content
+        await self._backend.write(path, raw)
+
+    async def info(self, path: str) -> dict[str, Any]:
+        """Get file metadata.
+
+        Args:
+            path: Relative file path.
+
+        Returns:
+            Dict with size, created, modified, type.
+        """
+        return await self._backend.info(path)
+
+    async def list(self, prefix: str = "") -> builtins.list[dict[str, Any]]:
+        """List files matching a prefix.
+
+        Args:
+            prefix: Path prefix (e.g. "uploads/").
+
+        Returns:
+            List of file info dicts.
+        """
+        return await self._backend.list(prefix)
+
+    async def exists(self, path: str) -> bool:
+        """Check if a file exists.
+
+        Args:
+            path: Relative file path.
+        """
+        return await self._backend.exists(path)
+
+    async def get_url(self, path: str, *, expires: int = 3600) -> str:
+        """Generate a download URL for a file.
+
+        Args:
+            path: Relative file path.
+            expires: URL expiration in seconds.
+
+        Returns:
+            Presigned download URL.
+        """
+        return await self._backend.get_url(path, expires=expires)

huitzo_sdk/integrations/http.py

@@ -0,0 +1,173 @@
+"""
+Module: integrations.http
+Description: HTTP integration client for external API requests with domain restrictions.
+
+Implements:
+    - docs/sdk/integrations.md#http-integration
+
+See Also:
+    - docs/sdk/error-handling.md (for HTTPError, HTTPSecurityError)
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Protocol, runtime_checkable
+from urllib.parse import urlparse
+
+from huitzo_sdk.errors import HTTPSecurityError
+
+
+@runtime_checkable
+class HTTPBackend(Protocol):
+    """Backend protocol for HTTP requests."""
+
+    async def request(
+        self,
+        method: str,
+        url: str,
+        *,
+        headers: dict[str, str] | None,
+        params: dict[str, Any] | None,
+        json: Any | None,
+        data: dict[str, Any] | None,
+        files: dict[str, bytes] | None,
+        timeout: int | None,
+    ) -> Any: ...
+
+
+@dataclass
+class HTTPClient:
+    """Client for making HTTP requests to external APIs.
+
+    Supports domain restrictions to limit which external services
+    a pack can communicate with.
+    """
+
+    _backend: HTTPBackend
+    _allowed_domains: list[str] = field(default_factory=list)
+
+    def _check_domain(self, url: str) -> None:
+        """Validate the URL domain against allowed domains."""
+        if not self._allowed_domains:
+            return
+        parsed = urlparse(url)
+        domain = parsed.hostname or ""
+        for allowed in self._allowed_domains:
+            if allowed.startswith("*."):
+                base = allowed[2:]  # e.g. "trusted-domain.org"
+                if domain.endswith("." + base):
+                    return
+            elif domain == allowed:
+                return
+        raise HTTPSecurityError(domain=domain)
+
+    async def get(
+        self,
+        url: str,
+        *,
+        headers: dict[str, str] | None = None,
+        params: dict[str, Any] | None = None,
+        timeout: int | None = None,
+    ) -> Any:
+        """Send a GET request.
+
+        Raises:
+            HTTPError: If the request fails.
+            HTTPSecurityError: If domain not allowed.
+        """
+        self._check_domain(url)
+        return await self._backend.request(
+            "GET",
+            url,
+            headers=headers,
+            params=params,
+            json=None,
+            data=None,
+            files=None,
+            timeout=timeout,
+        )
+
+    async def post(
+        self,
+        url: str,
+        *,
+        headers: dict[str, str] | None = None,
+        params: dict[str, Any] | None = None,
+        json: Any | None = None,
+        data: dict[str, Any] | None = None,
+        files: dict[str, bytes] | None = None,
+        timeout: int | None = None,
+    ) -> Any:
+        """Send a POST request.
+
+        Raises:
+            HTTPError: If the request fails.
+            HTTPSecurityError: If domain not allowed.
+        """
+        self._check_domain(url)
+        return await self._backend.request(
+            "POST",
+            url,
+            headers=headers,
+            params=params,
+            json=json,
+            data=data,
+            files=files,
+            timeout=timeout,
+        )
+
+    async def put(
+        self,
+        url: str,
+        *,
+        headers: dict[str, str] | None = None,
+        params: dict[str, Any] | None = None,
+        json: Any | None = None,
+        data: dict[str, Any] | None = None,
+        files: dict[str, bytes] | None = None,
+        timeout: int | None = None,
+    ) -> Any:
+        """Send a PUT request.
+
+        Raises:
+            HTTPError: If the request fails.
+            HTTPSecurityError: If domain not allowed.
+        """
+        self._check_domain(url)
+        return await self._backend.request(
+            "PUT",
+            url,
+            headers=headers,
+            params=params,
+            json=json,
+            data=data,
+            files=files,
+            timeout=timeout,
+        )
+
+    async def delete(
+        self,
+        url: str,
+        *,
+        headers: dict[str, str] | None = None,
+        params: dict[str, Any] | None = None,
+        timeout: int | None = None,
+    ) -> Any:
+        """Send a DELETE request.
+
+        Raises:
+            HTTPError: If the request fails.
+            HTTPSecurityError: If domain not allowed.
+        """
+        self._check_domain(url)
+        return await self._backend.request(
+            "DELETE",
+            url,
+            headers=headers,
+            params=params,
+            json=None,
+            data=None,
+            files=None,
+            timeout=timeout,
+        )

huitzo_sdk/integrations/llm.py

@@ -0,0 +1,157 @@
+"""
+Module: integrations.llm
+Description: LLM integration client for AI completions and streaming.
+
+Implements:
+    - docs/sdk/integrations.md#llm-integration
+
+See Also:
+    - docs/sdk/error-handling.md (for LLMError)
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, AsyncIterator, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class LLMBackend(Protocol):
+    """Backend protocol for LLM providers."""
+
+    async def complete(
+        self,
+        *,
+        prompt: str,
+        system: str | None,
+        model: str,
+        temperature: float,
+        max_tokens: int | None,
+        top_p: float | None,
+        stop: list[str] | None,
+        response_format: str | None,
+        schema: type[Any] | None,
+    ) -> str: ...
+
+    def stream(
+        self,
+        *,
+        prompt: str,
+        system: str | None,
+        model: str,
+        temperature: float,
+        max_tokens: int | None,
+        top_p: float | None,
+        stop: list[str] | None,
+    ) -> AsyncIterator[str]: ...
+
+
+@dataclass
+class TokenUsage:
+    """Token usage tracking for a single LLM call."""
+
+    prompt_tokens: int = 0
+    completion_tokens: int = 0
+
+    @property
+    def total_tokens(self) -> int:
+        return self.prompt_tokens + self.completion_tokens
+
+
+@dataclass
+class LLMClient:
+    """Client for LLM completions and streaming.
+
+    This is the SDK-side interface. The backend injects a real implementation
+    at runtime that handles actual API calls.
+    """
+
+    _backend: LLMBackend
+    _usage: list[TokenUsage] = field(default_factory=list, init=False)
+
+    async def complete(
+        self,
+        prompt: str,
+        *,
+        model: str = "gpt-4o-mini",
+        system: str | None = None,
+        temperature: float = 1.0,
+        max_tokens: int | None = None,
+        top_p: float | None = None,
+        stop: list[str] | None = None,
+        response_format: str | None = None,
+        schema: type[Any] | None = None,
+    ) -> str:
+        """Generate a completion from an LLM.
+
+        Args:
+            prompt: The user prompt.
+            model: Model identifier (e.g. "gpt-4o", "claude-3-5-sonnet").
+            system: Optional system message.
+            temperature: Sampling temperature (0.0-2.0).
+            max_tokens: Maximum response tokens.
+            top_p: Nucleus sampling parameter.
+            stop: Stop sequences.
+            response_format: "json" for structured output.
+            schema: Pydantic model for JSON mode validation.
+
+        Returns:
+            The completion text.
+
+        Raises:
+            LLMError: If the LLM call fails.
+        """
+        return await self._backend.complete(
+            prompt=prompt,
+            system=system,
+            model=model,
+            temperature=temperature,
+            max_tokens=max_tokens,
+            top_p=top_p,
+            stop=stop,
+            response_format=response_format,
+            schema=schema,
+        )
+
+    def stream(
+        self,
+        prompt: str,
+        *,
+        model: str = "gpt-4o-mini",
+        system: str | None = None,
+        temperature: float = 1.0,
+        max_tokens: int | None = None,
+        top_p: float | None = None,
+        stop: list[str] | None = None,
+    ) -> AsyncIterator[str]:
+        """Stream a completion from an LLM.
+
+        Args:
+            prompt: The user prompt.
+            model: Model identifier.
+            system: Optional system message.
+            temperature: Sampling temperature.
+            max_tokens: Maximum response tokens.
+            top_p: Nucleus sampling parameter.
+            stop: Stop sequences.
+
+        Returns:
+            An async iterator yielding text chunks.
+
+        Raises:
+            LLMError: If the LLM call fails.
+        """
+        return self._backend.stream(
+            prompt=prompt,
+            system=system,
+            model=model,
+            temperature=temperature,
+            max_tokens=max_tokens,
+            top_p=top_p,
+            stop=stop,
+        )
+
+    @property
+    def usage(self) -> list[TokenUsage]:
+        """Token usage records for this client."""
+        return list(self._usage)