ciris-agent 1.7.7__py3-none-any.whl

ciris_sdk/auth_store.py

@@ -0,0 +1,261 @@
+"""
+Persistent authentication storage for CIRIS SDK.
+
+Provides secure storage for API keys and auth tokens with:
+- File-based persistence with proper permissions
+- Optional encryption for sensitive data
+- Automatic token refresh management
+"""
+
+import json
+import os
+import stat
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+from pydantic import BaseModel, Field
+
+from .exceptions import CIRISError
+
+
+class AuthToken(BaseModel):
+    """Authentication token with metadata."""
+
+    token: str = Field(..., description="The authentication token")
+    expires_at: Optional[datetime] = Field(None, description="Token expiration time")
+    refresh_token: Optional[str] = Field(None, description="Refresh token if available")
+    token_type: str = Field("Bearer", description="Token type")
+    scope: Optional[str] = Field(None, description="Token scope/permissions")
+
+    def is_expired(self) -> bool:
+        """Check if token is expired."""
+        if not self.expires_at:
+            return False
+        return datetime.now(timezone.utc) >= self.expires_at
+
+
+class AuthStore:
+    """
+    Persistent storage for authentication credentials.
+
+    Stores API keys and tokens in a JSON file with restricted permissions.
+    Default location is ~/.ciris/auth.json
+    """
+
+    def __init__(self, auth_file: Optional[Path] = None):
+        """
+        Initialize auth store.
+
+        Args:
+            auth_file: Path to auth file (default: ~/.ciris/auth.json)
+        """
+        if auth_file is None:
+            auth_file = Path.home() / ".ciris" / "auth.json"
+
+        self.auth_file = auth_file
+        self._ensure_auth_dir()
+
+    def _ensure_auth_dir(self) -> None:
+        """Ensure auth directory exists with proper permissions."""
+        auth_dir = self.auth_file.parent
+        auth_dir.mkdir(parents=True, exist_ok=True)
+
+        # Set directory permissions to 700 (owner only)
+        try:
+            os.chmod(auth_dir, stat.S_IRWXU)
+        except Exception:
+            # Windows may not support chmod
+            pass
+
+    def _load_auth_data(self) -> Dict[str, Any]:
+        """Load auth data from file."""
+        if not self.auth_file.exists():
+            return {}
+
+        try:
+            with open(self.auth_file, "r") as f:
+                data = json.load(f)
+
+            # Ensure data is a dict (json.load returns Any)
+            assert isinstance(data, dict), "Auth data must be a dictionary"
+
+            # Convert ISO strings back to datetime objects
+            for key in ["token_expires_at", "api_key_created_at"]:
+                if key in data and data[key]:
+                    data[key] = datetime.fromisoformat(data[key])
+
+            return data
+        except Exception as e:
+            raise CIRISError(f"Failed to load auth data: {e}")
+
+    def _save_auth_data(self, data: Dict[str, Any]) -> None:
+        """Save auth data to file with restricted permissions."""
+        # Convert datetime objects to ISO strings for JSON
+        save_data = data.copy()
+        for key, value in save_data.items():
+            if isinstance(value, datetime):
+                save_data[key] = value.isoformat()
+
+        try:
+            # Write to temp file first
+            temp_file = self.auth_file.with_suffix(".tmp")
+            with open(temp_file, "w") as f:
+                json.dump(save_data, f, indent=2)
+
+            # Set file permissions to 600 (owner read/write only)
+            try:
+                os.chmod(temp_file, stat.S_IRUSR | stat.S_IWUSR)
+            except Exception:
+                # Windows may not support chmod
+                pass
+
+            # Atomically replace old file
+            temp_file.replace(self.auth_file)
+
+        except Exception as e:
+            raise CIRISError(f"Failed to save auth data: {e}")
+
+    def store_api_key(self, api_key: str, base_url: str) -> None:
+        """
+        Store API key for a specific base URL.
+
+        Args:
+            api_key: The API key to store
+            base_url: The base URL this key is for
+        """
+        data = self._load_auth_data()
+
+        # Store API key info
+        data["api_keys"] = data.get("api_keys", {})
+        data["api_keys"][base_url] = {"key": api_key, "created_at": datetime.now(timezone.utc).isoformat()}
+
+        self._save_auth_data(data)
+
+    def get_api_key(self, base_url: str) -> Optional[str]:
+        """
+        Get stored API key for a base URL.
+
+        Args:
+            base_url: The base URL to get key for
+
+        Returns:
+            API key if found, None otherwise
+        """
+        data = self._load_auth_data()
+        api_keys = data.get("api_keys", {})
+
+        if base_url in api_keys:
+            key = api_keys[base_url].get("key")
+            # Ensure key is a string or None
+            return str(key) if key is not None else None
+
+        return None
+
+    def store_token(self, token: AuthToken, base_url: str) -> None:
+        """
+        Store authentication token.
+
+        Args:
+            token: The auth token to store
+            base_url: The base URL this token is for
+        """
+        data = self._load_auth_data()
+
+        # Store token info
+        data["tokens"] = data.get("tokens", {})
+        data["tokens"][base_url] = {
+            "token": token.token,
+            "expires_at": token.expires_at.isoformat() if token.expires_at else None,
+            "refresh_token": token.refresh_token,
+            "token_type": token.token_type,
+            "scope": token.scope,
+            "created_at": datetime.now(timezone.utc).isoformat(),
+        }
+
+        self._save_auth_data(data)
+
+    def get_token(self, base_url: str) -> Optional[AuthToken]:
+        """
+        Get stored token for a base URL.
+
+        Args:
+            base_url: The base URL to get token for
+
+        Returns:
+            AuthToken if found and valid, None otherwise
+        """
+        data = self._load_auth_data()
+        tokens = data.get("tokens", {})
+
+        if base_url not in tokens:
+            return None
+
+        token_data = tokens[base_url]
+        token = AuthToken(
+            token=token_data["token"],
+            expires_at=datetime.fromisoformat(token_data["expires_at"]) if token_data.get("expires_at") else None,
+            refresh_token=token_data.get("refresh_token"),
+            token_type=token_data.get("token_type", "Bearer"),
+            scope=token_data.get("scope"),
+        )
+
+        # Don't return expired tokens
+        if token.is_expired():
+            return None
+
+        return token
+
+    def clear_auth(self, base_url: Optional[str] = None) -> None:
+        """
+        Clear stored authentication data.
+
+        Args:
+            base_url: If provided, only clear auth for this URL.
+                     If None, clear all auth data.
+        """
+        if base_url is None:
+            # Clear all auth data
+            if self.auth_file.exists():
+                self.auth_file.unlink()
+        else:
+            # Clear auth for specific URL
+            data = self._load_auth_data()
+
+            api_keys = data.get("api_keys", {})
+            tokens = data.get("tokens", {})
+
+            if base_url in api_keys:
+                del api_keys[base_url]
+            if base_url in tokens:
+                del tokens[base_url]
+
+            self._save_auth_data(data)
+
+    def list_stored_urls(self) -> Dict[str, Dict[str, bool]]:
+        """
+        List all URLs with stored auth data.
+
+        Returns:
+            Dict mapping URLs to auth info (has_api_key, has_token)
+        """
+        data = self._load_auth_data()
+        api_keys = data.get("api_keys", {})
+        tokens = data.get("tokens", {})
+
+        all_urls = set(api_keys.keys()) | set(tokens.keys())
+
+        result = {}
+        for url in all_urls:
+            result[url] = {"has_api_key": url in api_keys, "has_token": url in tokens}
+
+            # Check if token is expired
+            if url in tokens:
+                token_data = tokens[url]
+                if token_data.get("expires_at"):
+                    expires_at = datetime.fromisoformat(token_data["expires_at"])
+                    result[url]["token_expired"] = datetime.now(timezone.utc) >= expires_at
+                else:
+                    result[url]["token_expired"] = False
+
+        return result

ciris_sdk/client.py

@@ -0,0 +1,261 @@
+from __future__ import annotations
+
+import asyncio
+from typing import Any, Dict, List, Optional
+
+from .exceptions import CIRISConnectionError
+from .resources.agent import AgentIdentity, AgentResource, AgentStatus, ConversationHistory, InteractResponse
+from .resources.audit import AuditResource
+from .resources.auth import AuthResource
+from .resources.billing import BillingResource
+from .resources.config import ConfigResource
+from .resources.consent import ConsentResource
+from .resources.emergency import EmergencyResource
+from .resources.jobs import JobsResource
+from .resources.memory import MemoryResource
+from .resources.setup import SetupResource
+from .resources.system import SystemResource
+from .resources.telemetry import TelemetryResource
+from .resources.wa import WiseAuthorityResource
+from .transport import Transport
+from .websocket import EventChannel, WebSocketClient
+
+
+class CIRISClient:
+    """
+    Main client for interacting with CIRIS v1 API (Pre-Beta).
+
+    **WARNING**: This SDK is for the v1 API which is in pre-beta stage.
+    The API and SDK interfaces may change without notice.
+    No backwards compatibility is guaranteed.
+
+    The client provides access to all API resources through a clean, typed interface.
+    It handles authentication, retries, and connection management automatically.
+
+    Example:
+        async with CIRISClient() as client:
+            # Simple interaction
+            response = await client.interact("Hello, CIRIS!")
+            print(response.response)
+
+            # Get agent status
+            status = await client.status()
+            print(f"Agent state: {status.cognitive_state}")
+
+    Note: All endpoints are under /v1/ prefix except the emergency shutdown endpoint.
+    """
+
+    def __init__(
+        self,
+        base_url: str = "http://localhost:8080",
+        api_key: Optional[str] = None,
+        timeout: float = 50.0,  # Increased to support longer processing times
+        max_retries: int = 3,
+        use_auth_store: bool = True,
+        rate_limit: bool = True,
+    ):
+        """Initialize CIRIS client.
+
+        Args:
+            base_url: Base URL of CIRIS API (default: http://localhost:8080)
+            api_key: Optional API key for authentication
+            timeout: Request timeout in seconds (default: 50.0)
+            max_retries: Number of retries for failed requests (default: 3)
+            use_auth_store: Whether to use persistent auth storage (default: True)
+            rate_limit: Whether to enable client-side rate limiting (default: True)
+        """
+        self.base_url = base_url
+        self.api_key = api_key
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self.use_auth_store = use_auth_store
+        self.rate_limit = rate_limit
+        self._transport = Transport(base_url, api_key, timeout, use_auth_store, rate_limit)
+
+        # Core resources matching v1 API structure
+        # Note: Many endpoints have been consolidated in the v1 API
+        self.agent = AgentResource(self._transport)
+        self.audit = AuditResource(self._transport)
+        self.billing = BillingResource(self._transport)  # NEW: Credit and billing management
+        self.memory = MemoryResource(self._transport)
+        self.system = SystemResource(self._transport)  # NEW: Consolidated system ops
+        self.telemetry = TelemetryResource(self._transport)
+        self.auth = AuthResource(self._transport)
+        self.setup = SetupResource(self._transport)  # NEW: First-run setup wizard
+        self.wa = WiseAuthorityResource(self._transport)
+        self.config = ConfigResource(self._transport)
+        self.consent = ConsentResource(self._transport)  # NEW: Consent management
+        self.emergency = EmergencyResource(self._transport)  # NEW: Emergency operations
+        self.jobs = JobsResource(self._transport)  # NEW: Async job management
+
+        # Legacy resource references for backwards compatibility
+        # These will be removed in future versions
+        self.runtime = self.system  # Deprecated: use client.system
+        self.visibility = self.telemetry  # Deprecated: use client.telemetry
+
+    async def __aenter__(self) -> "CIRISClient":
+        await self._transport.__aenter__()
+        return self
+
+    async def __aexit__(self, exc_type: Any, exc: Any, tb: Any) -> None:
+        await self._transport.__aexit__(exc_type, exc, tb)
+
+    def set_api_key(self, api_key: Optional[str], persist: bool = True) -> None:
+        """
+        Set or update the API key.
+
+        Args:
+            api_key: The API key to use (None to clear)
+            persist: Whether to store persistently (default: True)
+        """
+        self.api_key = api_key
+        self._transport.set_api_key(api_key, persist)
+
+    def clear_stored_auth(self) -> None:
+        """Clear any stored authentication data for this server."""
+        if self.use_auth_store and self._transport.auth_store:
+            self._transport.auth_store.clear_auth(self.base_url)
+
+    async def _request_with_retry(self, method: str, path: str, **kwargs: Any) -> Any:
+        for attempt in range(self.max_retries):
+            try:
+                return await self._transport.request(method, path, **kwargs)
+            except CIRISConnectionError:
+                if attempt < self.max_retries - 1:
+                    await asyncio.sleep(2**attempt)
+                else:
+                    raise
+
+    # Convenience methods for primary agent interactions
+
+    async def interact(self, message: str, context: Optional[Dict[str, Any]] = None) -> InteractResponse:
+        """Send message and get response from agent.
+
+        This is the primary method for interacting with the agent.
+        It sends your message and waits for the agent's response.
+
+        Args:
+            message: Message to send to the agent
+            context: Optional context for the interaction
+
+        Returns:
+            InteractResponse with the agent's response and metadata
+
+        Example:
+            response = await client.interact("What is the weather like?")
+            print(response.response)  # Agent's response text
+            print(f"Processing took {response.processing_time_ms}ms")
+        """
+        return await self.agent.interact(message, context)
+
+    async def ask(self, question: str, context: Optional[Dict[str, Any]] = None) -> str:
+        """Ask a question and get just the response text.
+
+        Convenience method that returns only the response content.
+
+        Args:
+            question: Question to ask the agent
+            context: Optional context
+
+        Returns:
+            Agent's response as a string
+
+        Example:
+            answer = await client.ask("What is 2 + 2?")
+            print(answer)  # "4"
+        """
+        return await self.agent.ask(question, context)
+
+    async def history(self, limit: int = 50) -> ConversationHistory:
+        """Get conversation history.
+
+        Args:
+            limit: Maximum messages to return (1-200)
+
+        Returns:
+            ConversationHistory with recent messages
+        """
+        return await self.agent.get_history(limit)
+
+    async def status(self) -> AgentStatus:
+        """Get agent status and cognitive state.
+
+        Returns:
+            AgentStatus with current state information
+        """
+        return await self.agent.get_status()
+
+    def create_websocket(
+        self, channels: Optional[List[EventChannel]] = None, reconnect: bool = True, heartbeat_interval: float = 30.0
+    ) -> WebSocketClient:
+        """
+        Create a WebSocket client for real-time streaming.
+
+        The WebSocket client provides real-time updates with:
+        - Automatic reconnection on disconnect
+        - Channel-based event filtering
+        - Health monitoring with heartbeat
+
+        Args:
+            channels: List of channels to subscribe to (default: all)
+            reconnect: Whether to auto-reconnect (default: True)
+            heartbeat_interval: Heartbeat interval in seconds (default: 30)
+
+        Returns:
+            WebSocketClient instance
+
+        Example:
+            # Create WebSocket for specific channels
+            ws = client.create_websocket(channels=[
+                EventChannel.AGENT_STATE,
+                EventChannel.SYSTEM_HEALTH
+            ])
+
+            # Register event handlers
+            @ws.on("message")
+            async def on_message(data):
+                print(f"Received: {data}")
+
+            @ws.on("channel:agent.state")
+            async def on_state_change(data):
+                print(f"State changed: {data}")
+
+            # Connect and listen
+            await ws.connect()
+
+            # Later: close connection
+            await ws.close()
+        """
+        return WebSocketClient(
+            base_url=self.base_url,
+            api_key=self.api_key,
+            channels=channels,
+            reconnect=reconnect,
+            heartbeat_interval=heartbeat_interval,
+            use_auth_store=self.use_auth_store,
+        )
+
+    async def identity(self) -> AgentIdentity:
+        """Get agent identity and capabilities.
+
+        Returns:
+            AgentIdentity with comprehensive identity info
+        """
+        return await self.agent.get_identity()
+
+    # Authentication helpers
+
+    async def login(self, username: str, password: str) -> None:
+        """Login to the API and store authentication token.
+
+        Args:
+            username: Username for authentication
+            password: Password for authentication
+        """
+        response = await self.auth.login(username, password)
+        self._transport.set_api_key(response.access_token)
+
+    async def logout(self) -> None:
+        """Logout and invalidate current token."""
+        await self.auth.logout()
+        self._transport.set_api_key(None)

ciris_sdk/exceptions.py

@@ -0,0 +1,73 @@
+"""
+CIRIS SDK Exceptions for v1 API (Pre-Beta).
+
+These exceptions match the error format returned by the v1 API.
+"""
+
+from typing import Any, Dict, Optional
+
+
+class CIRISError(Exception):
+    """Base exception for the SDK."""
+
+
+class CIRISAPIError(CIRISError):
+    """
+    API errors with status codes and structured error information.
+
+    The v1 API returns errors in a standard format:
+    {
+        "error": {
+            "code": "RESOURCE_NOT_FOUND",
+            "message": "The requested resource was not found",
+            "details": {...}
+        }
+    }
+    """
+
+    def __init__(
+        self, status_code: int, message: str, code: Optional[str] = None, details: Optional[Dict[str, Any]] = None
+    ):
+        super().__init__(f"API Error {status_code}: {message}")
+        self.status_code = status_code
+        self.message = message
+        self.code = code
+        self.details = details or {}
+
+
+class CIRISTimeoutError(CIRISError):
+    """Request timeout errors."""
+
+
+class CIRISConnectionError(CIRISError):
+    """Connection errors - triggers retry logic."""
+
+
+class CIRISAuthenticationError(CIRISAPIError):
+    """Authentication failed (401)."""
+
+    def __init__(self, message: str = "Authentication failed"):
+        super().__init__(401, message, "UNAUTHORIZED")
+
+
+class CIRISPermissionError(CIRISAPIError):
+    """Insufficient permissions (403)."""
+
+    def __init__(self, message: str = "Insufficient permissions", required_role: Optional[str] = None):
+        details = {"required_role": required_role} if required_role else {}
+        super().__init__(403, message, "FORBIDDEN", details)
+
+
+class CIRISNotFoundError(CIRISAPIError):
+    """Resource not found (404)."""
+
+    def __init__(self, resource_type: str, resource_id: str):
+        message = f"{resource_type} '{resource_id}' not found"
+        super().__init__(404, message, "NOT_FOUND", {"resource_type": resource_type, "resource_id": resource_id})
+
+
+class CIRISValidationError(CIRISAPIError):
+    """Request validation failed (422)."""
+
+    def __init__(self, message: str, validation_errors: Optional[Dict[str, Any]] = None):
+        super().__init__(422, message, "VALIDATION_ERROR", validation_errors)