huitzo-sdk 0.0.0__py3-none-any.whl

huitzo_sdk/__init__.py

@@ -0,0 +1,85 @@
+"""
+Module: huitzo_sdk
+Description: Huitzo SDK for building Intelligence Packs.
+
+Implements:
+    - docs/sdk/overview.md
+    - docs/sdk/commands.md
+    - docs/sdk/context.md
+    - docs/sdk/error-handling.md
+
+See Also:
+    - docs/sdk/storage.md
+    - docs/sdk/storage-backends.md
+    - docs/sdk/integrations.md
+"""
+
+from huitzo_sdk.command import HuitzoCommand, command
+from huitzo_sdk.context import Context
+from huitzo_sdk.errors import (
+    CommandError,
+    ConfigurationError,
+    EmailError,
+    ExternalAPIError,
+    HTTPError,
+    HTTPSecurityError,
+    HuitzoError,
+    IntegrationError,
+    LLMError,
+    PackExecutionError,
+    PermissionError,
+    RateLimitError,
+    SecretsError,
+    StorageError,
+    TimeoutError,
+    ValidationError,
+)
+from huitzo_sdk.integrations import (
+    EmailClient,
+    FileClient,
+    FileStorageBackend,
+    HTTPClient,
+    LLMClient,
+    TelegramClient,
+)
+from huitzo_sdk.storage import InMemoryBackend, StorageBackend, StorageNamespace
+from huitzo_sdk.types import CommandMetadata, DeploymentMode, Result
+
+__all__ = [
+    # Core
+    "command",
+    "HuitzoCommand",
+    "Context",
+    # Integrations
+    "LLMClient",
+    "EmailClient",
+    "HTTPClient",
+    "TelegramClient",
+    "FileClient",
+    "FileStorageBackend",
+    # Storage
+    "StorageBackend",
+    "InMemoryBackend",
+    "StorageNamespace",
+    # Types
+    "CommandMetadata",
+    "DeploymentMode",
+    "Result",
+    # Errors
+    "HuitzoError",
+    "CommandError",
+    "ValidationError",
+    "TimeoutError",
+    "StorageError",
+    "SecretsError",
+    "ExternalAPIError",
+    "IntegrationError",
+    "LLMError",
+    "EmailError",
+    "HTTPError",
+    "HTTPSecurityError",
+    "PackExecutionError",
+    "PermissionError",
+    "ConfigurationError",
+    "RateLimitError",
+]

huitzo_sdk/command.py

@@ -0,0 +1,180 @@
+"""
+Module: command
+Description: @command decorator and HuitzoCommand base class for defining Intelligence Pack commands.
+
+Implements:
+    - docs/sdk/commands.md#the-command-decorator
+    - docs/sdk/commands.md#decorator-parameters
+    - docs/sdk/commands.md#class-based-commands
+    - docs/sdk/commands.md#sync-vs-async-commands
+
+See Also:
+    - docs/sdk/context.md (for Context API)
+    - docs/sdk/error-handling.md (for error patterns)
+"""
+
+from __future__ import annotations
+
+import asyncio
+import functools
+import inspect
+from typing import Any, Callable, TypeVar, get_type_hints
+
+from pydantic import BaseModel
+
+from huitzo_sdk.context import Context
+from huitzo_sdk.types import CommandMetadata, Result
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+def command(
+    name: str,
+    namespace: str,
+    *,
+    version: str = "1.0.0",
+    timeout: int = 60,
+    retries: int = 3,
+    retry_backoff: float = 1.0,
+    retry_max_wait: int = 60,
+    queue: str = "default",
+    output_format: str = "auto",
+    description: str | None = None,
+) -> Callable[[F], F]:
+    """Decorator to register a function as a Huitzo command.
+
+    Stores CommandMetadata on the function, validates Pydantic args,
+    and supports both sync and async functions.
+    """
+    metadata = CommandMetadata(
+        name=name,
+        namespace=namespace,
+        version=version,
+        timeout=timeout,
+        retries=retries,
+        retry_backoff=retry_backoff,
+        retry_max_wait=retry_max_wait,
+        queue=queue,
+        output_format=output_format,
+        description=description,
+    )
+
+    def decorator(fn: F) -> F:
+        is_async = asyncio.iscoroutinefunction(fn)
+        hints = get_type_hints(fn)
+
+        # Find the Pydantic model type for args (first parameter)
+        params = list(inspect.signature(fn).parameters.keys())
+        args_type: type[BaseModel] | None = None
+        if params:
+            first_hint = hints.get(params[0])
+            if (
+                first_hint is not None
+                and isinstance(first_hint, type)
+                and issubclass(first_hint, BaseModel)
+            ):
+                args_type = first_hint
+
+        @functools.wraps(fn)
+        async def wrapper(args: Any, ctx: Context | None = None) -> Result:
+            # Validate args via Pydantic if type-annotated
+            validated_args = args
+            if args_type is not None and isinstance(args, dict):
+                validated_args = args_type.model_validate(args)
+
+            # Inject context if not provided
+            if ctx is None:
+                ctx = Context(
+                    command_name=metadata.name,
+                    namespace=metadata.namespace,
+                    command_version=metadata.version,
+                )
+
+            if is_async:
+                result: Result = await fn(validated_args, ctx)
+            else:
+                result = await asyncio.to_thread(fn, validated_args, ctx)
+            return result
+
+        wrapper._huitzo_command = metadata  # type: ignore[attr-defined]
+        return wrapper  # type: ignore[return-value]
+
+    return decorator
+
+
+class HuitzoCommand:
+    """Base class for class-based commands with lifecycle hooks.
+
+    Subclass and implement execute(). Optionally override lifecycle hooks.
+    """
+
+    name: str = ""
+    namespace: str = ""
+    version: str = "1.0.0"
+    timeout: int = 60
+    retries: int = 3
+    retry_backoff: float = 1.0
+    retry_max_wait: int = 60
+    queue: str = "default"
+    output_format: str = "auto"
+
+    def __init__(self) -> None:
+        self.configure()
+        self._metadata = CommandMetadata(
+            name=self.name,
+            namespace=self.namespace,
+            version=self.version,
+            timeout=self.timeout,
+            retries=self.retries,
+            retry_backoff=self.retry_backoff,
+            retry_max_wait=self.retry_max_wait,
+            queue=self.queue,
+            output_format=self.output_format,
+        )
+
+    @property
+    def metadata(self) -> CommandMetadata:
+        return self._metadata
+
+    def configure(self) -> None:
+        """Override to set options before execution."""
+
+    def on_start(self, args: Any) -> None:
+        """Called when command starts."""
+
+    def on_progress(self, percent: int, message: str) -> None:
+        """Called to report progress."""
+
+    def on_retry(self, attempt: int, error: Exception) -> None:
+        """Called before each retry."""
+
+    def on_complete(self, result: Any) -> None:
+        """Called after successful completion."""
+
+    def on_error(self, error: Exception) -> None:
+        """Called on failure."""
+
+    def update_state(self, **kwargs: Any) -> None:
+        """Update command state (e.g., progress). Stub for runtime integration."""
+
+    async def execute(self, args: Any, ctx: Context) -> Result:
+        """Main execution logic. Must be overridden."""
+        raise NotImplementedError("Subclasses must implement execute()")
+
+    async def run(self, args: Any, ctx: Context | None = None) -> Result:
+        """Execute the command with lifecycle hooks."""
+        if ctx is None:
+            ctx = Context(
+                command_name=self.name,
+                namespace=self.namespace,
+                command_version=self.version,
+            )
+
+        self.on_start(args)
+        try:
+            result = await self.execute(args, ctx)
+            self.on_complete(result)
+            return result
+        except Exception as e:
+            self.on_error(e)
+            raise

huitzo_sdk/context.py

@@ -0,0 +1,122 @@
+"""
+Module: context
+Description: Context object passed to every command with identity, metadata, and platform services.
+
+Implements:
+    - docs/sdk/context.md#context-properties
+    - docs/sdk/context.md#services
+    - docs/sdk/integrations.md
+
+See Also:
+    - docs/sdk/commands.md (for command patterns)
+    - docs/sdk/storage.md (for storage API)
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+from uuid import UUID, uuid4
+
+from huitzo_sdk.integrations.email import EmailClient
+from huitzo_sdk.integrations.files import FileClient
+from huitzo_sdk.integrations.http import HTTPClient
+from huitzo_sdk.integrations.llm import LLMClient
+from huitzo_sdk.integrations.telegram import TelegramClient
+from huitzo_sdk.types import DeploymentMode
+
+
+_NOT_WIRED = (
+    "not available. This integration is injected by the Huitzo backend at runtime. "
+    "If you see this in production, contact support."
+)
+
+# Services still stubbed for future PRs
+_FUTURE_STUBS: dict[str, str] = {
+    "storage": "Storage implemented in PR-4.",
+    "log": "Logging planned for PR-6+.",
+    "env": "Environment access planned for PR-6+.",
+    "config": "Configuration access planned for PR-6+.",
+    "secrets": "Secrets access planned for PR-6+.",
+}
+
+
+@dataclass
+class Context:
+    """Context object passed to every command execution.
+
+    Provides identity, metadata, and access to platform services.
+    """
+
+    # Identity
+    user_id: UUID = field(default_factory=uuid4)
+    tenant_id: UUID = field(default_factory=uuid4)
+    session_id: UUID = field(default_factory=uuid4)
+    correlation_id: str = field(default_factory=lambda: str(uuid4()))
+
+    # Command metadata
+    command_name: str = ""
+    namespace: str = ""
+    command_version: str = "1.0.0"
+    deployment_mode: DeploymentMode = DeploymentMode.CLOUD
+
+    # Integration clients (injected by backend at runtime)
+    _llm: LLMClient | None = field(default=None, repr=False)
+    _email: EmailClient | None = field(default=None, repr=False)
+    _http: HTTPClient | None = field(default=None, repr=False)
+    _telegram: TelegramClient | None = field(default=None, repr=False)
+    _files: FileClient | None = field(default=None, repr=False)
+
+    @property
+    def llm(self) -> LLMClient:
+        """LLM integration client."""
+        if self._llm is None:
+            raise NotImplementedError(f"ctx.llm is {_NOT_WIRED}")
+        return self._llm
+
+    @property
+    def email(self) -> EmailClient:
+        """Email integration client."""
+        if self._email is None:
+            raise NotImplementedError(f"ctx.email is {_NOT_WIRED}")
+        return self._email
+
+    @property
+    def http(self) -> HTTPClient:
+        """HTTP integration client."""
+        if self._http is None:
+            raise NotImplementedError(f"ctx.http is {_NOT_WIRED}")
+        return self._http
+
+    @property
+    def telegram(self) -> TelegramClient:
+        """Telegram integration client."""
+        if self._telegram is None:
+            raise NotImplementedError(f"ctx.telegram is {_NOT_WIRED}")
+        return self._telegram
+
+    @property
+    def files(self) -> FileClient:
+        """File integration client."""
+        if self._files is None:
+            raise NotImplementedError(f"ctx.files is {_NOT_WIRED}")
+        return self._files
+
+    def __getattr__(self, name: str) -> Any:
+        if name.startswith("_"):
+            raise AttributeError(f"'Context' has no attribute '{name}'")
+        if name in _FUTURE_STUBS:
+            raise NotImplementedError(f"ctx.{name} is not yet implemented. {_FUTURE_STUBS[name]}")
+        raise AttributeError(f"'Context' has no attribute '{name}'")
+
+    async def execute(
+        self,
+        pack: str,
+        command: str,
+        args: dict[str, Any],
+        timeout: int | None = None,
+    ) -> Any:
+        """Execute a command from another pack. Not yet implemented."""
+        raise NotImplementedError(
+            "ctx.execute() for cross-pack calls is not yet implemented. Implemented in PR-6."
+        )

huitzo_sdk/errors.py

@@ -0,0 +1,241 @@
+"""
+Module: errors
+Description: SDK exception hierarchy for structured error handling.
+
+Implements:
+    - docs/sdk/error-handling.md#sdk-exception-hierarchy
+    - docs/sdk/error-handling.md#exception-reference
+
+See Also:
+    - docs/sdk/commands.md (for command error patterns)
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class HuitzoError(Exception):
+    """Base exception for all Huitzo SDK errors."""
+
+    code: str = "HUITZO_ERROR"
+    http_status: int = 500
+    retryable: bool = False
+
+    def __init__(self, message: str, *, details: dict[str, Any] | None = None) -> None:
+        super().__init__(message)
+        self.message = message
+        self.details = details or {}
+
+
+class CommandError(HuitzoError):
+    """General command execution failure."""
+
+    code = "COMMAND_FAILED"
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        exit_code: int = 1,
+        details: dict[str, Any] | None = None,
+    ) -> None:
+        super().__init__(message, details=details)
+        self.exit_code = exit_code
+
+
+class ValidationError(HuitzoError):
+    """Input validation failed."""
+
+    code = "VALIDATION_FAILED"
+    http_status = 400
+
+    def __init__(self, *, field: str, value: Any, message: str) -> None:
+        super().__init__(message)
+        self.field = field
+        self.value = value
+
+
+class TimeoutError(HuitzoError):
+    """Command exceeded its configured timeout."""
+
+    code = "TIMEOUT"
+    http_status = 408
+    retryable = True
+
+    def __init__(self, *, timeout_seconds: int, elapsed_seconds: float) -> None:
+        super().__init__(
+            f"Command timed out after {elapsed_seconds:.1f}s (limit: {timeout_seconds}s)"
+        )
+        self.timeout_seconds = timeout_seconds
+        self.elapsed_seconds = elapsed_seconds
+
+
+class StorageError(HuitzoError):
+    """Storage operation failed."""
+
+    code = "STORAGE_ERROR"
+
+    def __init__(self, *, operation: str, key: str | None = None, message: str) -> None:
+        super().__init__(message)
+        self.operation = operation
+        self.key = key
+
+
+class SecretsError(HuitzoError):
+    """User secret access failure."""
+
+    code = "SECRET_MISSING"
+    http_status = 400
+
+    def __init__(self, *, secret_name: str, message: str) -> None:
+        super().__init__(message)
+        self.secret_name = secret_name
+
+
+class ExternalAPIError(HuitzoError):
+    """User-configured external API failure."""
+
+    code = "EXTERNAL_API_ERROR"
+    http_status = 502
+
+    def __init__(self, *, service: str, message: str) -> None:
+        super().__init__(message)
+        self.service = service
+
+
+class IntegrationError(HuitzoError):
+    """Platform service failure (base for LLM, Email, HTTP errors)."""
+
+    code = "INTEGRATION_ERROR"
+    http_status = 502
+    retryable = True
+
+    def __init__(
+        self,
+        *,
+        service: str,
+        message: str,
+        details: dict[str, Any] | None = None,
+    ) -> None:
+        super().__init__(message, details=details)
+        self.service = service
+
+
+class LLMError(IntegrationError):
+    """LLM provider error."""
+
+    code = "LLM_ERROR"
+
+    def __init__(
+        self,
+        *,
+        provider: str,
+        model: str | None = None,
+        status_code: int | None = None,
+        message: str,
+    ) -> None:
+        super().__init__(service=f"llm:{provider}", message=message)
+        self.provider = provider
+        self.model = model
+        self.status_code = status_code
+
+
+class EmailError(IntegrationError):
+    """Email sending error."""
+
+    code = "EMAIL_ERROR"
+
+    def __init__(self, *, message: str) -> None:
+        super().__init__(service="email", message=message)
+
+
+class HTTPError(IntegrationError):
+    """HTTP request error."""
+
+    code = "HTTP_ERROR"
+
+    def __init__(
+        self,
+        *,
+        url: str,
+        method: str,
+        status_code: int | None = None,
+        response_body: str | None = None,
+        message: str,
+    ) -> None:
+        super().__init__(service="http", message=message)
+        self.url = url
+        self.method = method
+        self.status_code = status_code
+        self.response_body = response_body
+
+
+class HTTPSecurityError(HuitzoError):
+    """Request to disallowed domain."""
+
+    code = "HTTP_SECURITY_ERROR"
+    http_status = 403
+
+    def __init__(self, *, domain: str, message: str | None = None) -> None:
+        super().__init__(message or f"Domain not allowed: {domain}")
+        self.domain = domain
+
+
+class PackExecutionError(HuitzoError):
+    """Cross-pack command execution failed."""
+
+    code = "PACK_EXECUTION_ERROR"
+
+    def __init__(
+        self,
+        *,
+        pack: str,
+        command: str,
+        original_error: Exception | None = None,
+        message: str,
+    ) -> None:
+        super().__init__(message)
+        self.pack = pack
+        self.command = command
+        self.original_error = original_error
+
+
+class PermissionError(HuitzoError):
+    """Insufficient permissions."""
+
+    code = "PERMISSION_DENIED"
+    http_status = 403
+
+    def __init__(self, *, message: str) -> None:
+        super().__init__(message)
+
+
+class ConfigurationError(HuitzoError):
+    """Invalid configuration."""
+
+    code = "CONFIGURATION_ERROR"
+
+    def __init__(self, *, message: str) -> None:
+        super().__init__(message)
+
+
+class RateLimitError(HuitzoError):
+    """Rate limit exceeded."""
+
+    code = "RATE_LIMITED"
+    http_status = 429
+    retryable = True
+
+    def __init__(
+        self,
+        *,
+        retry_after: float,
+        limit: str | None = None,
+        current: int | None = None,
+        message: str | None = None,
+    ) -> None:
+        super().__init__(message or f"Rate limit exceeded. Retry after {retry_after}s")
+        self.retry_after = retry_after
+        self.limit = limit
+        self.current = current

huitzo_sdk/integrations/__init__.py

@@ -0,0 +1,26 @@
+"""
+Module: integrations
+Description: Built-in platform integration clients for the Huitzo SDK.
+
+Implements:
+    - docs/sdk/integrations.md
+
+See Also:
+    - docs/sdk/context.md (for Context wiring)
+    - docs/sdk/error-handling.md (for integration errors)
+"""
+
+from huitzo_sdk.integrations.email import EmailClient
+from huitzo_sdk.integrations.files import FileClient, FileStorageBackend
+from huitzo_sdk.integrations.http import HTTPClient
+from huitzo_sdk.integrations.llm import LLMClient
+from huitzo_sdk.integrations.telegram import TelegramClient
+
+__all__ = [
+    "LLMClient",
+    "EmailClient",
+    "HTTPClient",
+    "TelegramClient",
+    "FileClient",
+    "FileStorageBackend",
+]