huitzo-sdk 0.0.0__py3-none-any.whl

huitzo_sdk/integrations/telegram.py

@@ -0,0 +1,117 @@
+"""
+Module: integrations.telegram
+Description: Telegram integration client for sending messages, documents, and photos.
+
+Implements:
+    - docs/sdk/integrations.md#telegram-integration
+
+See Also:
+    - docs/sdk/error-handling.md (for IntegrationError)
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class TelegramBackend(Protocol):
+    """Backend protocol for Telegram bot API."""
+
+    async def send(
+        self,
+        *,
+        chat_id: str,
+        message: str,
+        parse_mode: str | None,
+    ) -> None: ...
+
+    async def send_document(
+        self,
+        *,
+        chat_id: str,
+        document: bytes,
+        filename: str,
+        caption: str | None,
+    ) -> None: ...
+
+    async def send_photo(
+        self,
+        *,
+        chat_id: str,
+        photo: bytes,
+        caption: str | None,
+    ) -> None: ...
+
+
+@dataclass
+class TelegramClient:
+    """Client for sending Telegram messages and media.
+
+    This is the SDK-side interface. The backend injects a real implementation
+    at runtime that calls the Telegram Bot API.
+    """
+
+    _backend: TelegramBackend
+
+    async def send(
+        self,
+        *,
+        chat_id: str,
+        message: str,
+        parse_mode: str | None = None,
+    ) -> None:
+        """Send a text message.
+
+        Args:
+            chat_id: Target chat ID.
+            message: Message text.
+            parse_mode: "Markdown" or "HTML".
+
+        Raises:
+            IntegrationError: If sending fails.
+        """
+        await self._backend.send(chat_id=chat_id, message=message, parse_mode=parse_mode)
+
+    async def send_document(
+        self,
+        *,
+        chat_id: str,
+        document: bytes,
+        filename: str,
+        caption: str | None = None,
+    ) -> None:
+        """Send a document.
+
+        Args:
+            chat_id: Target chat ID.
+            document: File bytes.
+            filename: Filename for the document.
+            caption: Optional caption.
+
+        Raises:
+            IntegrationError: If sending fails.
+        """
+        await self._backend.send_document(
+            chat_id=chat_id, document=document, filename=filename, caption=caption
+        )
+
+    async def send_photo(
+        self,
+        *,
+        chat_id: str,
+        photo: bytes,
+        caption: str | None = None,
+    ) -> None:
+        """Send a photo.
+
+        Args:
+            chat_id: Target chat ID.
+            photo: Image bytes.
+            caption: Optional caption.
+
+        Raises:
+            IntegrationError: If sending fails.
+        """
+        await self._backend.send_photo(chat_id=chat_id, photo=photo, caption=caption)

huitzo_sdk/storage/__init__.py

@@ -0,0 +1,21 @@
+"""
+Module: storage
+Description: Storage interface, backends, and key scoping for the Huitzo SDK.
+
+Implements:
+    - docs/sdk/storage.md
+    - docs/sdk/storage-backends.md
+
+See Also:
+    - docs/sdk/context.md#ctx-storage (for Context integration)
+"""
+
+from huitzo_sdk.storage.memory import InMemoryBackend
+from huitzo_sdk.storage.namespace import StorageNamespace
+from huitzo_sdk.storage.protocol import StorageBackend
+
+__all__ = [
+    "StorageBackend",
+    "InMemoryBackend",
+    "StorageNamespace",
+]

huitzo_sdk/storage/memory.py

@@ -0,0 +1,181 @@
+"""
+Module: storage.memory
+Description: In-memory storage backend for testing and development.
+
+Implements:
+    - docs/sdk/storage-backends.md#storage-backend-protocol
+    - docs/sdk/storage.md#core-methods
+    - docs/sdk/storage.md#ttl-time-to-live
+    - docs/sdk/storage.md#batch-operations
+    - docs/sdk/storage.md#transactions
+    - docs/sdk/storage.md#query-by-metadata
+
+See Also:
+    - docs/sdk/storage.md (for high-level storage API)
+"""
+
+from __future__ import annotations
+
+import builtins
+import copy
+import time
+from contextlib import asynccontextmanager
+from dataclasses import dataclass, field
+from typing import Any, AsyncIterator
+
+
+@dataclass
+class _Entry:
+    """Internal storage entry."""
+
+    value: Any
+    metadata: dict[str, Any] = field(default_factory=dict)
+    expires_at: float | None = None
+
+    def is_expired(self) -> bool:
+        return self.expires_at is not None and time.monotonic() >= self.expires_at
+
+
+class InMemoryBackend:
+    """In-memory implementation of StorageBackend for testing.
+
+    Supports all protocol methods including TTL, batch operations,
+    metadata queries, and transactions.
+
+    Note: This backend has the following limitations:
+    - Expired entries are cleaned up lazily (only when accessed), which may
+      cause memory usage to grow with many TTL-based entries that are never
+      accessed again.
+    - Transaction implementation is not thread-safe for concurrent operations.
+      The _in_transaction flag check and setting are not atomic.
+    - Transactions create a deep copy of all data, which has O(n) time and
+      space overhead where n is the total number of keys in storage.
+    """
+
+    def __init__(self) -> None:
+        self._data: dict[str, _Entry] = {}
+        self._in_transaction: bool = False
+        self._snapshot: dict[str, _Entry] | None = None
+
+    def _clean_expired(self, key: str) -> None:
+        entry = self._data.get(key)
+        if entry is not None and entry.is_expired():
+            del self._data[key]
+
+    def _set_expiration_for_testing(self, key: str, expires_at: float) -> None:
+        """Set expiration time for a key (for testing purposes only).
+
+        Args:
+            key: The key to modify
+            expires_at: Expiration timestamp (from time.monotonic())
+        """
+        if key in self._data:
+            self._data[key].expires_at = expires_at
+
+    def _get_entry(self, key: str) -> _Entry | None:
+        self._clean_expired(key)
+        return self._data.get(key)
+
+    async def save(
+        self,
+        key: str,
+        value: Any,
+        *,
+        ttl: int | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> str:
+        expires_at = (time.monotonic() + ttl) if ttl is not None else None
+        self._data[key] = _Entry(
+            value=value,
+            metadata=metadata or {},
+            expires_at=expires_at,
+        )
+        return key
+
+    async def get(self, key: str, *, default: Any = None) -> Any:
+        entry = self._get_entry(key)
+        if entry is None:
+            return default
+        return entry.value
+
+    async def delete(self, key: str) -> bool:
+        self._clean_expired(key)
+        if key in self._data:
+            del self._data[key]
+            return True
+        return False
+
+    async def exists(self, key: str) -> bool:
+        return self._get_entry(key) is not None
+
+    async def list(
+        self, prefix: str = "", *, limit: int = 100, offset: int = 0
+    ) -> builtins.list[str]:
+        # Clean expired keys lazily
+        keys = [k for k in self._data if k.startswith(prefix) and not self._data[k].is_expired()]
+        keys.sort()
+        return keys[offset : offset + limit]
+
+    async def save_many(self, items: dict[str, Any], *, ttl: int | None = None) -> None:
+        for key, value in items.items():
+            await self.save(key, value, ttl=ttl)
+
+    async def get_many(self, keys: builtins.list[str]) -> dict[str, Any]:
+        return {key: await self.get(key) for key in keys}
+
+    async def delete_many(self, keys: builtins.list[str]) -> int:
+        count = 0
+        for key in keys:
+            if await self.delete(key):
+                count += 1
+        return count
+
+    async def query(
+        self,
+        prefix: str = "",
+        *,
+        metadata: dict[str, Any] | None = None,
+        limit: int = 100,
+    ) -> builtins.list[dict[str, Any]]:
+        results: builtins.list[dict[str, Any]] = []
+        for key, entry in sorted(self._data.items()):
+            if entry.is_expired():
+                continue
+            if not key.startswith(prefix):
+                continue
+            if metadata:
+                if not all(entry.metadata.get(k) == v for k, v in metadata.items()):
+                    continue
+            results.append(
+                {"key": key, "value": entry.value, "metadata": copy.deepcopy(entry.metadata)}
+            )
+            if len(results) >= limit:
+                break
+        return results
+
+    @asynccontextmanager
+    async def transaction(self) -> AsyncIterator[None]:
+        """Atomic transaction with snapshot-based rollback."""
+        if self._in_transaction:
+            # Nested transaction: just yield (no new snapshot)
+            yield
+            return
+
+        # Take snapshot
+        self._snapshot = {
+            k: _Entry(copy.deepcopy(v.value), copy.deepcopy(v.metadata), v.expires_at)
+            for k, v in self._data.items()
+        }
+        self._in_transaction = True
+        try:
+            yield
+            # Commit: discard snapshot
+            self._snapshot = None
+        except BaseException:
+            # Rollback: restore snapshot
+            if self._snapshot is not None:
+                self._data = self._snapshot
+                self._snapshot = None
+            raise
+        finally:
+            self._in_transaction = False

huitzo_sdk/storage/namespace.py

@@ -0,0 +1,64 @@
+"""
+Module: storage.namespace
+Description: Key scoping for tenant-isolated storage.
+
+Implements:
+    - docs/sdk/storage.md#automatic-scoping
+    - docs/sdk/storage.md#scope-levels
+
+See Also:
+    - docs/sdk/storage-backends.md (for backend protocol)
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from uuid import UUID
+
+
+@dataclass(frozen=True)
+class StorageNamespace:
+    """Builds scoped storage keys for tenant isolation.
+
+    Keys are scoped as:
+        user scope:   tenant:{tenant_id}:user:{user_id}:pack:{pack_id}:{key}
+        tenant scope: tenant:{tenant_id}:pack:{pack_id}:{key}
+        pack scope:   pack:{pack_id}:{key}
+    """
+
+    tenant_id: UUID
+    user_id: UUID
+    pack_id: str
+
+    def scope_key(self, key: str, scope: str = "user") -> str:
+        """Build a fully-scoped storage key.
+
+        Args:
+            key: The user-provided key.
+            scope: Scope level - "user" (default), "tenant", or "pack".
+
+        Returns:
+            The scoped key string.
+
+        Raises:
+            ValueError: If scope is invalid.
+        """
+        if scope == "user":
+            return f"tenant:{self.tenant_id}:user:{self.user_id}:pack:{self.pack_id}:{key}"
+        if scope == "tenant":
+            return f"tenant:{self.tenant_id}:pack:{self.pack_id}:{key}"
+        if scope == "pack":
+            return f"pack:{self.pack_id}:{key}"
+        raise ValueError(f"Invalid scope: {scope!r}. Must be 'user', 'tenant', or 'pack'.")
+
+    def scope_prefix(self, prefix: str, scope: str = "user") -> str:
+        """Build a scoped prefix for listing keys.
+
+        Args:
+            prefix: The user-provided prefix.
+            scope: Scope level.
+
+        Returns:
+            The scoped prefix string.
+        """
+        return self.scope_key(prefix, scope)

huitzo_sdk/storage/protocol.py

@@ -0,0 +1,173 @@
+"""
+Module: storage.protocol
+Description: StorageBackend Protocol defining the abstract storage interface.
+
+Implements:
+    - docs/sdk/storage-backends.md#storage-backend-protocol
+    - docs/sdk/storage.md#core-methods
+
+See Also:
+    - docs/sdk/storage.md (for high-level storage API)
+    - docs/sdk/context.md#ctx-storage (for Context integration)
+"""
+
+from __future__ import annotations
+
+import builtins
+from contextlib import AbstractAsyncContextManager
+from typing import Any, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class StorageBackend(Protocol):
+    """Abstract storage interface enabling multiple backends.
+
+    All storage backends must implement this protocol. Keys are pre-scoped
+    by StorageNamespace before reaching the backend.
+    """
+
+    async def save(
+        self,
+        key: str,
+        value: Any,
+        *,
+        ttl: int | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> str:
+        """Save a value to storage.
+
+        Args:
+            key: Storage key (max 256 characters, pre-scoped).
+            value: JSON-serializable value.
+            ttl: Time-to-live in seconds.
+            metadata: Optional metadata for querying.
+
+        Returns:
+            The storage key.
+
+        Raises:
+            StorageError: If save operation fails.
+        """
+        ...
+
+    async def get(self, key: str, *, default: Any = None) -> Any:
+        """Retrieve a value from storage.
+
+        Args:
+            key: Storage key.
+            default: Value returned if key not found.
+
+        Returns:
+            The stored value, or default if not found.
+
+        Raises:
+            StorageError: If retrieval fails.
+        """
+        ...
+
+    async def delete(self, key: str) -> bool:
+        """Delete a value from storage.
+
+        Args:
+            key: Storage key.
+
+        Returns:
+            True if deleted, False if not found.
+
+        Raises:
+            StorageError: If deletion fails.
+        """
+        ...
+
+    async def exists(self, key: str) -> bool:
+        """Check if a key exists in storage.
+
+        Args:
+            key: Storage key.
+
+        Returns:
+            True if key exists and is not expired.
+        """
+        ...
+
+    async def list(
+        self, prefix: str = "", *, limit: int = 100, offset: int = 0
+    ) -> builtins.list[str]:
+        """List keys matching a prefix.
+
+        Args:
+            prefix: Key prefix to match.
+            limit: Maximum number of keys to return.
+            offset: Pagination offset.
+
+        Returns:
+            List of matching keys.
+
+        Raises:
+            StorageError: If listing fails.
+        """
+        ...
+
+    async def save_many(self, items: dict[str, Any], *, ttl: int | None = None) -> None:
+        """Save multiple key-value pairs.
+
+        Args:
+            items: Dictionary of key-value pairs.
+            ttl: Optional TTL applied to all items.
+
+        Raises:
+            StorageError: If any save fails.
+        """
+        ...
+
+    async def get_many(self, keys: builtins.list[str]) -> dict[str, Any]:
+        """Retrieve multiple values.
+
+        Args:
+            keys: List of keys to retrieve.
+
+        Returns:
+            Dictionary mapping keys to values (None for missing keys).
+        """
+        ...
+
+    async def delete_many(self, keys: builtins.list[str]) -> int:
+        """Delete multiple keys.
+
+        Args:
+            keys: List of keys to delete.
+
+        Returns:
+            Number of keys actually deleted.
+        """
+        ...
+
+    async def query(
+        self,
+        prefix: str = "",
+        *,
+        metadata: dict[str, Any] | None = None,
+        limit: int = 100,
+    ) -> builtins.list[dict[str, Any]]:
+        """Query storage by prefix and metadata filters.
+
+        Args:
+            prefix: Key prefix to match.
+            metadata: Metadata key-value filters (exact match).
+            limit: Maximum number of results.
+
+        Returns:
+            List of records with key, value, and metadata.
+        """
+        ...
+
+    def transaction(self) -> AbstractAsyncContextManager[None]:
+        """Begin an atomic transaction.
+
+        Usage:
+            async with backend.transaction():
+                await backend.save("k1", v1)
+                await backend.save("k2", v2)
+                # Both commit or both rollback.
+        """
+        ...

huitzo_sdk/types.py

@@ -0,0 +1,47 @@
+"""
+Module: types
+Description: Core type definitions for the Huitzo SDK.
+
+Implements:
+    - docs/sdk/commands.md#decorator-parameters
+    - docs/sdk/context.md#deployment-mode
+
+See Also:
+    - docs/sdk/overview.md (for SDK design philosophy)
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any, Union
+
+from pydantic import BaseModel
+
+
+class DeploymentMode(Enum):
+    """Deployment mode for the Huitzo platform."""
+
+    CLOUD = "cloud"
+    SELF_HOSTED = "self_hosted"
+    EDGE = "edge"
+
+
+@dataclass(frozen=True)
+class CommandMetadata:
+    """Metadata stored on decorated command functions."""
+
+    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
+
+
+# Result can be a dict, Pydantic model, str, int, or None
+Result = Union[dict[str, Any], BaseModel, str, int, None]

huitzo_sdk-0.0.0.dist-info/METADATA

@@ -0,0 +1,12 @@
+Metadata-Version: 2.4
+Name: huitzo-sdk
+Version: 0.0.0
+Summary: Huitzo SDK for building Intelligence Packs
+Requires-Python: >=3.11
+Requires-Dist: pydantic>=2.12
+Provides-Extra: dev
+Requires-Dist: mypy>=1.19; extra == 'dev'
+Requires-Dist: pytest-asyncio>=1.0; extra == 'dev'
+Requires-Dist: pytest-cov>=7.0; extra == 'dev'
+Requires-Dist: pytest>=9.0; extra == 'dev'
+Requires-Dist: ruff>=0.14; extra == 'dev'

huitzo_sdk-0.0.0.dist-info/RECORD

@@ -0,0 +1,18 @@
+huitzo_sdk/__init__.py,sha256=3FeobaJAjqVkTA2r3mp0eeHGL8wZHea4zO-ZJ_7HvTo,1776
+huitzo_sdk/command.py,sha256=ANsJ6pY4ADI6CNi2ZKtEdtjY8NqEO2n6d98hwtTk5HU,5512
+huitzo_sdk/context.py,sha256=YXJfe2m79IlDE7_sGacPM6G-JJP6_T9XByDWKcuS_vE,4044
+huitzo_sdk/errors.py,sha256=ZVXVH6a-mqiVvq8Ma5Uc1_7fcoAE7xdvXXQbmkqy758,5816
+huitzo_sdk/types.py,sha256=2ZbkH_MKz2LAz8Dwnexv1pjTU-4uyWzh0R4p-xCPGLo,1036
+huitzo_sdk/integrations/__init__.py,sha256=cx2U6Z0vOwkkEeli1IyGxE70NaY1b1n7tYjcRxHdR1w,685
+huitzo_sdk/integrations/email.py,sha256=9hDSt5lgbh_w4P3sFTHfmaL15x0lCCeYVTVzSRP5G9o,2631
+huitzo_sdk/integrations/files.py,sha256=c92RdjxGPUDpD6x1Mepi8sHfcugiziQTl_Pmy98eKYY,4961
+huitzo_sdk/integrations/http.py,sha256=cBwOmTW9SyT9ltmIQB-ihemrHVy0OH4opbamcFD8rqU,4574
+huitzo_sdk/integrations/llm.py,sha256=9EHBTX6piIFs2PNRQJDU2ruUpYZLc5Iop0pozdMlUW8,4178
+huitzo_sdk/integrations/telegram.py,sha256=v6yjzuYADYLHBP0UokWqo95wvcbR61bSni1IPX9SuLQ,2716
+huitzo_sdk/storage/__init__.py,sha256=D3M5-3JrGey3GDV-qenTqQKQtwutoiYArrMJWzkUsvQ,503
+huitzo_sdk/storage/memory.py,sha256=dCPng8zqOHU5ucXK-zhgC2ctFEGfQWwKMxXwb8e8Giw,5855
+huitzo_sdk/storage/namespace.py,sha256=24dSCIj7n4tVvFippqJSq0J7rMHpYvnzk6rye3xWLaQ,1803
+huitzo_sdk/storage/protocol.py,sha256=xNPfdPsiOKG7ku0uGsUoJaN07GvO1_TlS9j-lmRwvAI,4363
+huitzo_sdk-0.0.0.dist-info/METADATA,sha256=6DuYxD3GsdgzBBssIJHNK00IxEynnWCx1iEAnh1gDSQ,405
+huitzo_sdk-0.0.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+huitzo_sdk-0.0.0.dist-info/RECORD,,

huitzo_sdk-0.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any