sonzai 1.0.0__py3-none-any.whl

sonzai/__init__.py

@@ -0,0 +1,281 @@
+"""Sonzai Python SDK - Client for the Sonzai Character Engine API."""
+
+from ._client import AsyncSonzai, Sonzai
+from ._exceptions import (
+    APIError,
+    AuthenticationError,
+    BadRequestError,
+    InternalServerError,
+    NotFoundError,
+    PermissionDeniedError,
+    RateLimitError,
+    SonzaiError,
+    StreamError,
+)
+from .types import (
+    Agent,
+    AgentCapabilities,
+    AgentIndex,
+    AgentInstance,
+    AgentListResponse,
+    AtomicFact,
+    BatchPersonalityEntry,
+    BatchPersonalityResponse,
+    Big5,
+    Big5Trait,
+    BreakthroughsResponse,
+    ChatMessage,
+    ChatResponse,
+    ChatStreamEvent,
+    ChatUsage,
+    ConsolidateResponse,
+    ConstellationResponse,
+    CustomState,
+    CustomStateListResponse,
+    CustomToolDefinition,
+    CustomToolListResponse,
+    DeleteResponse,
+    DeliveryAttemptsResponse,
+    DialogueResponse,
+    DiaryResponse,
+    EvalCategory,
+    EvalRun,
+    EvalRunListResponse,
+    EvalTemplate,
+    EvalTemplateCategory,
+    EvalTemplateListResponse,
+    EvaluationResult,
+    Fact,
+    FactHistoryResponse,
+    FactListResponse,
+    GenerateBioResponse,
+    GenerateCharacterResponse,
+    GeneratedGoal,
+    GenerateSeedMemoriesResponse,
+    Goal,
+    GoalsResponse,
+    HabitsResponse,
+    ImageGenerateResponse,
+    InitialGoal,
+    InstanceListResponse,
+    InterestsResponse,
+    InventoryBatchImportResponse,
+    InventoryDirectUpdateResponse,
+    InventoryGroupResult,
+    InventoryItem,
+    InventoryQueryResponse,
+    # Inventory
+    InventoryUpdateResponse,
+    # KB Bulk Update
+    KBBulkUpdateEntry,
+    KBBulkUpdateResponse,
+    KBCandidate,
+    KBResolutionInfo,
+    ListAllFactsResponse,
+    MemoryNode,
+    MemoryResetResponse,
+    MemoryResponse,
+    MemorySearchResponse,
+    MemorySearchResult,
+    MemorySummary,
+    MemoryTimelineResponse,
+    MoodAggregateResponse,
+    MoodResponse,
+    Notification,
+    NotificationListResponse,
+    PersonalityBehaviors,
+    PersonalityDelta,
+    PersonalityDimensions,
+    PersonalityPreferences,
+    PersonalityProfile,
+    PersonalityResponse,
+    PersonalityShift,
+    PersonalityUpdateResponse,
+    RecentShiftsResponse,
+    RelationshipResponse,
+    RunRef,
+    ScheduledWakeup,
+    SeedMemoriesResponse,
+    SessionResponse,
+    SetStatusResponse,
+    SignificantMoment,
+    SignificantMomentsResponse,
+    SimulationEvent,
+    StoredFact,
+    StructuredColumnMapping,
+    StructuredImportSpec,
+    SummariesResponse,
+    TimelineSession,
+    TimeMachineMoodSnapshot,
+    TimeMachineResponse,
+    TriggerEventResponse,
+    TTSResponse,
+    UpdateProjectResponse,
+    UserOverlayDetailResponse,
+    UserOverlaysListResponse,
+    UserPersona,
+    UserPersonalityOverlay,
+    UsersResponse,
+    Voice,
+    VoiceChatResponse,
+    VoiceListResponse,
+    VoiceMatchResponse,
+    VoiceStreamEvent,
+    VoiceStreamToken,
+    WakeupsResponse,
+    WebhookDeliveryAttempt,
+    WebhookEndpoint,
+    WebhookListResponse,
+    WebhookRegisterResponse,
+)
+
+__version__ = "1.0.0"
+
+__all__ = [
+    # Clients
+    "Sonzai",
+    "AsyncSonzai",
+    # Exceptions
+    "SonzaiError",
+    "APIError",
+    "AuthenticationError",
+    "BadRequestError",
+    "InternalServerError",
+    "NotFoundError",
+    "PermissionDeniedError",
+    "RateLimitError",
+    "StreamError",
+    # Types - Agent CRUD
+    "Agent",
+    "AgentCapabilities",
+    "AgentIndex",
+    "AgentListResponse",
+    "DeleteResponse",
+    "SetStatusResponse",
+    "UpdateProjectResponse",
+    # Types - Chat
+    "ChatMessage",
+    "ChatResponse",
+    "ChatStreamEvent",
+    "ChatUsage",
+    # Types - Dialogue / Events
+    "DialogueResponse",
+    "TriggerEventResponse",
+    # Types - Memory
+    "AtomicFact",
+    "Fact",
+    "FactHistoryResponse",
+    "FactListResponse",
+    "MemoryNode",
+    "MemoryResetResponse",
+    "MemoryResponse",
+    "MemorySearchResponse",
+    "MemorySearchResult",
+    "MemorySummary",
+    "MemoryTimelineResponse",
+    "SeedMemoriesResponse",
+    "TimelineSession",
+    # Types - Personality
+    "BatchPersonalityEntry",
+    "BatchPersonalityResponse",
+    "Big5",
+    "Big5Trait",
+    "PersonalityBehaviors",
+    "PersonalityDelta",
+    "PersonalityDimensions",
+    "PersonalityPreferences",
+    "PersonalityProfile",
+    "PersonalityResponse",
+    "PersonalityShift",
+    "PersonalityUpdateResponse",
+    "RecentShiftsResponse",
+    "SignificantMoment",
+    "SignificantMomentsResponse",
+    "UserOverlayDetailResponse",
+    "UserOverlaysListResponse",
+    "UserPersonalityOverlay",
+    # Types - Context Engine
+    "BreakthroughsResponse",
+    "ConstellationResponse",
+    "DiaryResponse",
+    "Goal",
+    "GoalsResponse",
+    "InitialGoal",
+    "HabitsResponse",
+    "InterestsResponse",
+    "MoodAggregateResponse",
+    "MoodResponse",
+    "RelationshipResponse",
+    "UsersResponse",
+    "WakeupsResponse",
+    # Types - Instances
+    "AgentInstance",
+    "InstanceListResponse",
+    # Types - Notifications
+    "Notification",
+    "NotificationListResponse",
+    # Types - Sessions
+    "SessionResponse",
+    # Types - Voice
+    "TTSResponse",
+    "Voice",
+    "VoiceChatResponse",
+    "VoiceListResponse",
+    "VoiceMatchResponse",
+    "VoiceStreamEvent",
+    "VoiceStreamToken",
+    # Types - Generation
+    "GenerateBioResponse",
+    "GenerateCharacterResponse",
+    "GeneratedGoal",
+    "GenerateSeedMemoriesResponse",
+    "ImageGenerateResponse",
+    # Types - Custom States
+    "CustomState",
+    "CustomStateListResponse",
+    # Types - Webhooks
+    "DeliveryAttemptsResponse",
+    "WebhookDeliveryAttempt",
+    "WebhookEndpoint",
+    "WebhookListResponse",
+    "WebhookRegisterResponse",
+    # Types - Wakeups
+    "ScheduledWakeup",
+    # Types - Capabilities
+    "CustomToolDefinition",
+    "CustomToolListResponse",
+    # Types - Consolidation / Summaries
+    "ConsolidateResponse",
+    "SummariesResponse",
+    # Types - Time Machine
+    "TimeMachineMoodSnapshot",
+    "TimeMachineResponse",
+    # Types - Evaluation
+    "EvalCategory",
+    "EvalRun",
+    "EvalRunListResponse",
+    "EvalTemplate",
+    "EvalTemplateCategory",
+    "EvalTemplateListResponse",
+    "EvaluationResult",
+    "RunRef",
+    "SimulationEvent",
+    # Types - User Persona
+    "UserPersona",
+    # Types - Inventory
+    "InventoryUpdateResponse",
+    "InventoryQueryResponse",
+    "InventoryItem",
+    "InventoryGroupResult",
+    "InventoryBatchImportResponse",
+    "InventoryDirectUpdateResponse",
+    "KBResolutionInfo",
+    "KBCandidate",
+    "StoredFact",
+    "ListAllFactsResponse",
+    "StructuredColumnMapping",
+    "StructuredImportSpec",
+    # Types - KB Bulk Update
+    "KBBulkUpdateEntry",
+    "KBBulkUpdateResponse",
+]

sonzai/_client.py

@@ -0,0 +1,171 @@
+"""Main Sonzai client classes."""
+
+from __future__ import annotations
+
+import os
+
+from ._http import AsyncHTTPClient, HTTPClient
+from .resources.agents import Agents, AsyncAgents
+from .resources.eval_runs import AsyncEvalRuns, EvalRuns
+from .resources.eval_templates import AsyncEvalTemplates, EvalTemplates
+from .resources.knowledge import AsyncKnowledge, Knowledge
+from .resources.voice import AsyncVoices, Voices
+from .resources.webhooks import AsyncWebhooks, Webhooks
+
+DEFAULT_BASE_URL = "https://api.sonz.ai"
+
+
+class Sonzai:
+    """Synchronous client for the Sonzai Character Engine API.
+
+    Usage::
+
+        from sonzai import Sonzai
+
+        client = Sonzai(api_key="your-api-key")
+
+        # Create an agent
+        agent = client.agents.create(name="Luna")
+
+        # Chat with an agent
+        response = client.agents.chat(
+            agent_id="agent-id",
+            messages=[{"role": "user", "content": "Hello!"}],
+        )
+        print(response.content)
+
+        # Stream chat
+        for event in client.agents.chat(
+            agent_id="agent-id",
+            messages=[{"role": "user", "content": "Tell me a story"}],
+            stream=True,
+        ):
+            print(event.content, end="", flush=True)
+
+        client.close()
+    """
+
+    agents: Agents
+    knowledge: Knowledge
+    eval_templates: EvalTemplates
+    eval_runs: EvalRuns
+    voices: Voices
+    webhooks: Webhooks
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        timeout: float = 30.0,
+        max_retries: int = 2,
+    ) -> None:
+        """Initialize the Sonzai client.
+
+        Args:
+            api_key: Your project API key. Falls back to ``SONZAI_API_KEY`` env var.
+            base_url: API base URL. Falls back to ``SONZAI_BASE_URL`` or the default.
+            timeout: Request timeout in seconds.
+            max_retries: Maximum number of retries for failed requests.
+        """
+        resolved_key = api_key or os.environ.get("SONZAI_API_KEY", "")
+        if not resolved_key:
+            raise ValueError(
+                "api_key must be provided or set via the SONZAI_API_KEY environment variable"
+            )
+
+        resolved_url = base_url or os.environ.get("SONZAI_BASE_URL", DEFAULT_BASE_URL)
+
+        self._http = HTTPClient(
+            base_url=resolved_url,
+            api_key=resolved_key,
+            timeout=timeout,
+            max_retries=max_retries,
+        )
+
+        self.agents = Agents(self._http)
+        self.knowledge = Knowledge(self._http)
+        self.eval_templates = EvalTemplates(self._http)
+        self.eval_runs = EvalRuns(self._http)
+        self.voices = Voices(self._http)
+        self.webhooks = Webhooks(self._http)
+
+    def close(self) -> None:
+        """Close the underlying HTTP client."""
+        self._http.close()
+
+    def __enter__(self) -> Sonzai:
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.close()
+
+
+class AsyncSonzai:
+    """Asynchronous client for the Sonzai Character Engine API.
+
+    Usage::
+
+        import asyncio
+        from sonzai import AsyncSonzai
+
+        async def main():
+            client = AsyncSonzai(api_key="your-api-key")
+
+            response = await client.agents.chat(
+                "agent-id",
+                messages=[{"role": "user", "content": "Hello!"}],
+            )
+            print(response.content)
+
+            await client.close()
+
+        asyncio.run(main())
+    """
+
+    agents: AsyncAgents
+    knowledge: AsyncKnowledge
+    eval_templates: AsyncEvalTemplates
+    eval_runs: AsyncEvalRuns
+    voices: AsyncVoices
+    webhooks: AsyncWebhooks
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        timeout: float = 30.0,
+        max_retries: int = 2,
+    ) -> None:
+        resolved_key = api_key or os.environ.get("SONZAI_API_KEY", "")
+        if not resolved_key:
+            raise ValueError(
+                "api_key must be provided or set via the SONZAI_API_KEY environment variable"
+            )
+
+        resolved_url = base_url or os.environ.get("SONZAI_BASE_URL", DEFAULT_BASE_URL)
+
+        self._http = AsyncHTTPClient(
+            base_url=resolved_url,
+            api_key=resolved_key,
+            timeout=timeout,
+            max_retries=max_retries,
+        )
+
+        self.agents = AsyncAgents(self._http)
+        self.knowledge = AsyncKnowledge(self._http)
+        self.eval_templates = AsyncEvalTemplates(self._http)
+        self.eval_runs = AsyncEvalRuns(self._http)
+        self.voices = AsyncVoices(self._http)
+        self.webhooks = AsyncWebhooks(self._http)
+
+    async def close(self) -> None:
+        """Close the underlying HTTP client."""
+        await self._http.close()
+
+    async def __aenter__(self) -> AsyncSonzai:
+        return self
+
+    async def __aexit__(self, *args: object) -> None:
+        await self.close()

sonzai/_exceptions.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+
+class SonzaiError(Exception):
+    """Base exception for all Sonzai SDK errors."""
+
+
+class AuthenticationError(SonzaiError):
+    """Raised when the API key is invalid or missing."""
+
+    def __init__(self, message: str = "Invalid or missing API key") -> None:
+        super().__init__(message)
+
+
+class NotFoundError(SonzaiError):
+    """Raised when the requested resource is not found."""
+
+
+class BadRequestError(SonzaiError):
+    """Raised when the request is invalid."""
+
+
+class PermissionDeniedError(SonzaiError):
+    """Raised when the API key lacks permission for the operation."""
+
+
+class RateLimitError(SonzaiError):
+    """Raised when rate limit is exceeded."""
+
+
+class InternalServerError(SonzaiError):
+    """Raised when the server returns a 5xx error."""
+
+
+class APIError(SonzaiError):
+    """Raised for unexpected API errors."""
+
+    def __init__(self, status_code: int, message: str) -> None:
+        self.status_code = status_code
+        super().__init__(f"[{status_code}] {message}")
+
+
+class StreamError(SonzaiError):
+    """Raised when an error occurs during SSE streaming."""