ciris-agent 1.7.7__py3-none-any.whl

ciris_sdk/pagination.py

@@ -0,0 +1,214 @@
+"""
+Pagination utilities for CIRIS SDK.
+
+Provides standardized cursor-based pagination for all list endpoints.
+"""
+
+import base64
+import json
+import logging
+from typing import Any, AsyncIterator, Awaitable, Callable, Dict, Generic, List, Optional, TypeVar
+
+from pydantic import BaseModel, ConfigDict, Field
+
+logger = logging.getLogger(__name__)
+
+T = TypeVar("T", bound=BaseModel)
+
+
+class CursorInfo(BaseModel):
+    """Decoded cursor information."""
+
+    offset: int = Field(0, description="Current offset")
+    filters: Dict[str, Any] = Field(default_factory=dict, description="Applied filters")
+    sort_key: Optional[str] = Field(None, description="Sort field")
+    sort_value: Optional[Any] = Field(None, description="Last item's sort value")
+
+
+class PaginatedResponse(BaseModel, Generic[T]):
+    """
+    Standardized paginated response.
+
+    All list endpoints return data in this format with cursor-based pagination.
+    """
+
+    items: List[T] = Field(..., description="List of items in current page")
+    total: Optional[int] = Field(None, description="Total count if available")
+    cursor: Optional[str] = Field(None, description="Cursor for next page")
+    has_more: bool = Field(..., description="Whether more items exist")
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+
+class PageIterator(Generic[T]):
+    """
+    Iterator for paginated results.
+
+    Automatically fetches pages as needed for seamless iteration.
+    """
+
+    def __init__(
+        self,
+        fetch_func: Callable[..., Awaitable[Any]],
+        initial_params: Dict[str, Any],
+        item_class: type[T],
+    ):
+        """
+        Initialize page iterator.
+
+        Args:
+            fetch_func: Async function to fetch a page
+            initial_params: Initial query parameters
+            item_class: Class for items in the response
+        """
+        self.fetch_func = fetch_func
+        self.params = initial_params.copy()
+        self.item_class = item_class
+        self._current_page: Optional[PaginatedResponse[T]] = None
+        self._current_index = 0
+        self._exhausted = False
+
+    async def __aiter__(self) -> AsyncIterator[T]:
+        """Async iteration support."""
+        while not self._exhausted:
+            # Fetch next page if needed
+            if self._current_page is None or self._current_index >= len(self._current_page.items):
+                await self._fetch_next_page()
+
+                # Check if we're done
+                if self._current_page is None or not self._current_page.items:
+                    self._exhausted = True
+                    break
+
+                self._current_index = 0
+
+            # Yield current item
+            yield self._current_page.items[self._current_index]
+            self._current_index += 1
+
+    async def _fetch_next_page(self) -> None:
+        """Fetch the next page of results."""
+        try:
+            # Use cursor if we have one
+            if self._current_page and self._current_page.cursor:
+                self.params["cursor"] = self._current_page.cursor
+
+            # Fetch page
+            response = await self.fetch_func(**self.params)
+
+            # Parse response
+            if isinstance(response, dict):
+                # Type assertion: we know item_class is bound to T
+                assert isinstance(self.item_class, type)
+                self._current_page = PaginatedResponse[T](**response)
+            else:
+                self._current_page = response
+
+            # Check if we should continue
+            if self._current_page is None or not self._current_page.has_more:
+                self._exhausted = True
+
+        except Exception as e:
+            logger.error(f"Error fetching page: {e}")
+            self._exhausted = True
+            raise
+
+
+def encode_cursor(cursor_info: CursorInfo) -> str:
+    """
+    Encode cursor information.
+
+    Args:
+        cursor_info: Cursor information to encode
+
+    Returns:
+        Base64-encoded cursor string
+    """
+    data = cursor_info.model_dump(exclude_none=True)
+    json_str = json.dumps(data, sort_keys=True)
+    return base64.urlsafe_b64encode(json_str.encode()).decode()
+
+
+def decode_cursor(cursor: str) -> CursorInfo:
+    """
+    Decode cursor string.
+
+    Args:
+        cursor: Base64-encoded cursor
+
+    Returns:
+        Decoded cursor information
+    """
+    try:
+        json_str = base64.urlsafe_b64decode(cursor.encode()).decode()
+        data = json.loads(json_str)
+        return CursorInfo(**data)
+    except Exception as e:
+        logger.error(f"Invalid cursor: {e}")
+        # Return default cursor on error
+        return CursorInfo()
+
+
+class PaginationParams(BaseModel):
+    """Standard pagination parameters."""
+
+    cursor: Optional[str] = Field(None, description="Cursor for pagination")
+    limit: int = Field(50, ge=1, le=200, description="Items per page")
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dict for API calls."""
+        return self.model_dump(exclude_none=True)
+
+
+class QueryParams(PaginationParams):
+    """
+    Extended query parameters with filtering.
+
+    Base class for resource-specific query parameters.
+    """
+
+    # Common filter fields
+    since: Optional[str] = Field(None, description="Filter by creation time")
+    until: Optional[str] = Field(None, description="Filter by creation time")
+    sort: Optional[str] = Field(None, description="Sort field")
+    order: Optional[str] = Field("desc", pattern="^(asc|desc)$", description="Sort order")
+
+    # Search
+    q: Optional[str] = Field(None, description="Search query")
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dict, handling special cases."""
+        data = super().to_dict()
+
+        # Remove empty strings
+        return {k: v for k, v in data.items() if v != ""}
+
+
+async def paginate_all(
+    fetch_func: Callable[..., Awaitable[Any]],
+    params: Dict[str, Any],
+    item_class: type[T],
+    max_items: Optional[int] = None,
+) -> List[T]:
+    """
+    Fetch all pages of a paginated endpoint.
+
+    Args:
+        fetch_func: Async function to fetch a page
+        params: Query parameters
+        item_class: Class for items
+        max_items: Maximum items to fetch (None = all)
+
+    Returns:
+        List of all items
+    """
+    all_items = []
+    iterator = PageIterator(fetch_func, params, item_class)
+
+    async for item in iterator:
+        all_items.append(item)
+
+        if max_items and len(all_items) >= max_items:
+            break
+
+    return all_items

ciris_sdk/rate_limiter.py

@@ -0,0 +1,188 @@
+"""
+Rate limiting for CIRIS SDK.
+
+Provides client-side rate limiting to prevent hitting server limits.
+"""
+
+import asyncio
+import logging
+import time
+from datetime import datetime, timezone
+from typing import Dict, Optional
+
+logger = logging.getLogger(__name__)
+
+
+class RateLimiter:
+    """
+    Token bucket rate limiter with automatic refill.
+
+    Implements a token bucket algorithm that:
+    - Starts with a full bucket of tokens
+    - Consumes tokens for each request
+    - Refills tokens at a steady rate
+    - Blocks when no tokens available
+    """
+
+    def __init__(self, requests_per_minute: int = 60, burst_size: Optional[int] = None):
+        """
+        Initialize rate limiter.
+
+        Args:
+            requests_per_minute: Sustained request rate (default: 60)
+            burst_size: Maximum burst size (default: same as rate)
+        """
+        self.rate: float = float(requests_per_minute)
+        self.burst_size = burst_size or requests_per_minute
+        self.tokens = float(self.burst_size)
+        self.last_update = time.monotonic()
+        self._lock = asyncio.Lock()
+
+        # Calculate refill rate (tokens per second)
+        self.refill_rate = self.rate / 60.0
+
+        logger.info(f"Rate limiter initialized: {self.rate} req/min, " f"burst size: {self.burst_size}")
+
+    async def acquire(self, tokens: int = 1) -> None:
+        """
+        Acquire tokens, blocking if necessary.
+
+        Args:
+            tokens: Number of tokens to acquire (default: 1)
+        """
+        async with self._lock:
+            while True:
+                now = time.monotonic()
+                elapsed = now - self.last_update
+
+                # Refill tokens based on elapsed time
+                self.tokens = min(self.burst_size, self.tokens + elapsed * self.refill_rate)
+                self.last_update = now
+
+                # Check if we have enough tokens
+                if self.tokens >= tokens:
+                    self.tokens -= tokens
+                    return
+
+                # Calculate wait time
+                tokens_needed = tokens - self.tokens
+                wait_time = tokens_needed / self.refill_rate
+
+                logger.debug(f"Rate limit: need {tokens_needed:.1f} tokens, " f"waiting {wait_time:.1f}s")
+
+                # Wait for tokens to refill
+                await asyncio.sleep(wait_time)
+
+    def update_from_headers(self, headers: Dict[str, str]) -> None:
+        """
+        Update rate limits from response headers.
+
+        Args:
+            headers: Response headers containing rate limit info
+        """
+        # Parse rate limit headers
+        limit = headers.get("X-RateLimit-Limit")
+        remaining = headers.get("X-RateLimit-Remaining")
+        reset = headers.get("X-RateLimit-Reset")
+        window = headers.get("X-RateLimit-Window")
+
+        if not all([limit, remaining]):
+            return
+
+        # Type narrowing - we know limit and remaining are not None
+        assert limit is not None
+        assert remaining is not None
+
+        try:
+            limit_val = int(limit)
+            remaining_val = int(remaining)
+
+            # Update our rate if server's is different
+            if window:
+                window_minutes = int(window) / 60
+                server_rate = limit_val / window_minutes
+                if abs(server_rate - self.rate) > 1:
+                    logger.info(f"Updating rate limit from server: " f"{self.rate} -> {server_rate} req/min")
+                    self.rate = server_rate
+                    self.refill_rate = self.rate / 60.0
+
+            # Sync tokens with server's count
+            # Be conservative - use minimum of our count and server's
+            self.tokens = min(self.tokens, float(remaining_val))
+
+            # Log if we're getting close to limit
+            if remaining_val < limit_val * 0.2:  # Less than 20% remaining
+                logger.warning(f"Rate limit warning: {remaining_val}/{limit_val} remaining")
+
+        except (ValueError, TypeError) as e:
+            logger.debug(f"Failed to parse rate limit headers: {e}")
+
+
+class AdaptiveRateLimiter(RateLimiter):
+    """
+    Rate limiter that adapts based on server responses.
+
+    Features:
+    - Starts conservative and increases rate if no errors
+    - Backs off on 429 (Too Many Requests) errors
+    - Learns optimal rate over time
+    """
+
+    def __init__(self, initial_rate: int = 30, max_rate: int = 120):
+        """
+        Initialize adaptive rate limiter.
+
+        Args:
+            initial_rate: Starting requests per minute (default: 30)
+            max_rate: Maximum requests per minute (default: 120)
+        """
+        super().__init__(initial_rate)
+        self.min_rate = 10
+        self.max_rate = max_rate
+        self.initial_rate = initial_rate
+
+        # Adaptation parameters
+        self.success_count = 0
+        self.error_count = 0
+        self.last_429: Optional[datetime] = None
+        self.increase_threshold = 100  # Successes before increasing
+        self.decrease_factor = 0.5  # Reduce by 50% on 429
+        self.increase_factor = 1.1  # Increase by 10% on success
+
+    def record_success(self) -> None:
+        """Record a successful request."""
+        self.success_count += 1
+
+        # Consider increasing rate after many successes
+        if self.success_count >= self.increase_threshold:
+            self._increase_rate()
+            self.success_count = 0
+
+    def record_429(self) -> None:
+        """Record a 429 (Too Many Requests) error."""
+        self.error_count += 1
+        self.last_429 = datetime.now(timezone.utc)
+        self._decrease_rate()
+
+        # Reset success count on error
+        self.success_count = 0
+
+    def _increase_rate(self) -> None:
+        """Increase rate limit cautiously."""
+        old_rate = self.rate
+        self.rate = min(self.max_rate, self.rate * self.increase_factor)
+        self.refill_rate = self.rate / 60.0
+
+        if self.rate > old_rate:
+            logger.info(f"Increased rate limit: {old_rate:.0f} -> {self.rate:.0f} req/min")
+
+    def _decrease_rate(self) -> None:
+        """Decrease rate limit on error."""
+        old_rate = self.rate
+        self.rate = max(self.min_rate, self.rate * self.decrease_factor)
+        self.refill_rate = self.rate / 60.0
+
+        # Also reduce current tokens to prevent immediate retry
+        self.tokens = min(self.tokens, self.rate / 10)
+
+        logger.warning(f"Decreased rate limit: {old_rate:.0f} -> {self.rate:.0f} req/min")

ciris_sdk/setup.py

@@ -0,0 +1,17 @@
+"""Setup configuration for CIRIS SDK."""
+
+from setuptools import find_packages, setup
+
+setup(
+    name="ciris-sdk",
+    version="0.1.0",
+    description="CIRIS SDK for Python",
+    author="CIRIS AI",
+    packages=find_packages(),
+    python_requires=">=3.8",
+    install_requires=[
+        "aiohttp>=3.8.0",
+        "pydantic>=2.0.0",
+        "websockets>=11.0",
+    ],
+)

ciris_sdk/telemetry_models.py

@@ -0,0 +1,257 @@
+"""
+Telemetry-specific models for CIRIS SDK.
+
+These models provide type-safe alternatives to Dict[str, Any] usage
+in telemetry operations.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any, Dict, List, Optional, Union
+
+from pydantic import BaseModel, ConfigDict, Field, field_serializer
+
+
+# Resource Models
+class ResourceUsage(BaseModel):
+    """Current resource usage metrics."""
+
+    cpu_percent: float = Field(..., description="CPU usage percentage")
+    memory_mb: float = Field(..., description="Memory usage in MB")
+    memory_percent: float = Field(..., description="Memory usage percentage")
+    disk_gb: Optional[float] = Field(None, description="Disk usage in GB")
+    disk_percent: Optional[float] = Field(None, description="Disk usage percentage")
+    network_connections: Optional[int] = Field(None, description="Active network connections")
+    open_files: Optional[int] = Field(None, description="Open file descriptors")
+    threads: Optional[int] = Field(None, description="Active threads")
+
+    model_config = ConfigDict(extra="allow")
+
+
+class ResourceLimits(BaseModel):
+    """Resource limits configuration."""
+
+    max_memory_mb: Optional[float] = Field(None, description="Maximum memory in MB")
+    max_cpu_percent: Optional[float] = Field(None, description="Maximum CPU percentage")
+    max_disk_gb: Optional[float] = Field(None, description="Maximum disk in GB")
+    max_connections: Optional[int] = Field(None, description="Maximum network connections")
+    max_open_files: Optional[int] = Field(None, description="Maximum open files")
+
+    model_config = ConfigDict(extra="allow")
+
+
+class ResourceHealth(BaseModel):
+    """Resource health status."""
+
+    status: str = Field(..., description="Overall health status: healthy|degraded|critical")
+    warnings: List[str] = Field(default_factory=list, description="Health warnings")
+
+    # Optional fields for backward compatibility
+    cpu_health: Optional[str] = Field(None, description="CPU health status")
+    memory_health: Optional[str] = Field(None, description="Memory health status")
+    disk_health: Optional[str] = Field(None, description="Disk health status")
+
+    model_config = ConfigDict(extra="allow")
+
+
+class ResourceHistoryPoint(BaseModel):
+    """Single point in resource history."""
+
+    timestamp: datetime = Field(..., description="Measurement timestamp")
+    value: float = Field(..., description="Measured value")
+    unit: Optional[str] = Field(None, description="Unit of measurement")
+
+    @field_serializer("timestamp")
+    def serialize_datetime(self, dt: Optional[datetime], _info: Any) -> Optional[str]:
+        return dt.isoformat() if dt else None
+
+
+# Metric Models
+class MetricData(BaseModel):
+    """Individual metric data."""
+
+    name: str = Field(..., description="Metric name")
+    value: float = Field(..., description="Current value")
+    unit: Optional[str] = Field(None, description="Unit of measurement")
+    timestamp: datetime = Field(..., description="Measurement time")
+    tags: Dict[str, str] = Field(default_factory=dict, description="Metric tags")
+    service: Optional[str] = Field(None, description="Service that produced metric")
+
+    @field_serializer("timestamp")
+    def serialize_datetime(self, dt: Optional[datetime], _info: Any) -> Optional[str]:
+        return dt.isoformat() if dt else None
+
+
+class MetricAggregate(BaseModel):
+    """Aggregated metric statistics."""
+
+    min: float = Field(..., description="Minimum value")
+    max: float = Field(..., description="Maximum value")
+    avg: float = Field(..., description="Average value")
+    sum: float = Field(..., description="Sum of values")
+    count: int = Field(..., description="Number of data points")
+    p50: Optional[float] = Field(None, description="50th percentile")
+    p95: Optional[float] = Field(None, description="95th percentile")
+    p99: Optional[float] = Field(None, description="99th percentile")
+
+
+class MetricTrend(BaseModel):
+    """Metric trend information."""
+
+    direction: str = Field(..., description="Trend direction: up|down|stable")
+    change_percent: float = Field(..., description="Percentage change")
+    change_absolute: float = Field(..., description="Absolute change")
+    period: str = Field(..., description="Period of comparison")
+
+
+# Query Models
+class QueryFilter(BaseModel):
+    """Filter for telemetry queries."""
+
+    field: str = Field(..., description="Field to filter on")
+    operator: str = Field(..., description="Comparison operator: eq|ne|gt|lt|gte|lte|contains|in")
+    value: Union[str, int, float, bool, List[Union[str, int, float]]] = Field(..., description="Filter value")
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class QueryFilters(BaseModel):
+    """Collection of query filters."""
+
+    filters: List[QueryFilter] = Field(default_factory=list, description="List of filters")
+    logic: str = Field(default="AND", description="Filter logic: AND|OR")
+
+    model_config = ConfigDict(extra="forbid")
+
+
+# Thought Models for Traces
+class ThoughtData(BaseModel):
+    """Thought information in traces."""
+
+    thought_id: str = Field(..., description="Unique thought ID")
+    content: str = Field(..., description="Thought content")
+    handler: str = Field(..., description="Handler that processed thought")
+    created_at: datetime = Field(..., description="Creation time")
+    completed_at: Optional[datetime] = Field(None, description="Completion time")
+    status: str = Field(..., description="Status: PENDING|PROCESSING|COMPLETED|FAILED")
+    result: Optional[str] = Field(None, description="Processing result")
+
+    @field_serializer("created_at", "completed_at")
+    def serialize_datetime(self, dt: Optional[datetime], _info: Any) -> Optional[str]:
+        return dt.isoformat() if dt else None
+
+
+# Lineage Models
+class LineageInfo(BaseModel):
+    """Agent lineage information."""
+
+    version: str = Field(..., description="Agent version")
+    commit: Optional[str] = Field(None, description="Git commit hash")
+    build_date: Optional[datetime] = Field(None, description="Build date")
+    parent_version: Optional[str] = Field(None, description="Parent version")
+    environment: Optional[str] = Field(None, description="Deployment environment")
+
+    model_config = ConfigDict(extra="allow")
+
+    @field_serializer("build_date")
+    def serialize_datetime(self, dt: Optional[datetime], _info: Any) -> Optional[str]:
+        return dt.isoformat() if dt else None
+
+
+# Processor State Models
+class ProcessorStateData(BaseModel):
+    """Processor state information."""
+
+    is_running: bool = Field(..., description="Whether processor is running")
+    current_state: str = Field(..., description="Current cognitive state")
+    current_round: int = Field(..., description="Current processing round")
+    thoughts_pending: int = Field(..., description="Pending thoughts")
+    thoughts_processing: int = Field(..., description="Currently processing thoughts")
+    last_activity: Optional[datetime] = Field(None, description="Last activity time")
+    idle_rounds: int = Field(..., description="Consecutive idle rounds")
+
+    model_config = ConfigDict(extra="allow")
+
+    @field_serializer("last_activity")
+    def serialize_datetime(self, dt: Optional[datetime], _info: Any) -> Optional[str]:
+        return dt.isoformat() if dt else None
+
+
+# Configuration Models
+class ConfigurationData(BaseModel):
+    """System configuration snapshot."""
+
+    profile: str = Field(..., description="Active configuration profile")
+    environment: str = Field(..., description="Deployment environment")
+    debug_mode: bool = Field(..., description="Debug mode enabled")
+    log_level: str = Field(..., description="Logging level")
+    features: Dict[str, bool] = Field(default_factory=dict, description="Feature flags")
+
+    model_config = ConfigDict(extra="allow")
+
+
+# Service Metadata Models
+class ServiceMetadata(BaseModel):
+    """Service metadata information."""
+
+    version: Optional[str] = Field(None, description="Service version")
+    uptime_seconds: Optional[float] = Field(None, description="Service uptime")
+    last_restart: Optional[datetime] = Field(None, description="Last restart time")
+    restart_count: Optional[int] = Field(None, description="Number of restarts")
+    error_count: Optional[int] = Field(None, description="Error count")
+
+    model_config = ConfigDict(extra="allow")
+
+    @field_serializer("last_restart")
+    def serialize_datetime(self, dt: Optional[datetime], _info: Any) -> Optional[str]:
+        return dt.isoformat() if dt else None
+
+
+# Context Models
+class InteractionContext(BaseModel):
+    """Context for agent interactions."""
+
+    channel_id: Optional[str] = Field(None, description="Channel identifier")
+    user_id: Optional[str] = Field(None, description="User identifier")
+    session_id: Optional[str] = Field(None, description="Session identifier")
+    metadata: Dict[str, str] = Field(default_factory=dict, description="Additional metadata")
+
+    model_config = ConfigDict(extra="allow")
+
+
+class AuditContext(BaseModel):
+    """Context for audit entries."""
+
+    ip_address: Optional[str] = Field(None, description="Client IP address")
+    user_agent: Optional[str] = Field(None, description="User agent string")
+    request_id: Optional[str] = Field(None, description="Request identifier")
+    session_id: Optional[str] = Field(None, description="Session identifier")
+    metadata: Dict[str, str] = Field(default_factory=dict, description="Additional metadata")
+
+    model_config = ConfigDict(extra="allow")
+
+
+class DeferralContext(BaseModel):
+    """Context for deferrals."""
+
+    original_thought_id: str = Field(..., description="Original thought ID")
+    authority_id: str = Field(..., description="Authority that created deferral")
+    priority: str = Field(..., description="Deferral priority")
+    metadata: Dict[str, str] = Field(default_factory=dict, description="Additional metadata")
+
+    model_config = ConfigDict(extra="allow")
+
+
+# Verification Models
+class VerificationResult(BaseModel):
+    """Result of verification operations."""
+
+    is_valid: bool = Field(..., description="Whether verification passed")
+    verified_at: datetime = Field(..., description="Verification timestamp")
+    method: str = Field(..., description="Verification method used")
+    details: Dict[str, str] = Field(default_factory=dict, description="Verification details")
+
+    @field_serializer("verified_at")
+    def serialize_datetime(self, dt: Optional[datetime], _info: Any) -> Optional[str]:
+        return dt.isoformat() if dt else None