ensoul 0.1.0__tar.gz

ensoul-0.1.0/.gitignore

@@ -0,0 +1,39 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+.venv/
+*.egg
+
+# TypeScript / Node
+node_modules/
+dist/
+*.tsbuildinfo
+
+# Swift
+.build/
+.swiftpm/
+Package.resolved
+
+# Unity
+Library/
+Temp/
+obj/
+Logs/
+
+# C++
+build/
+cmake-build-*/
+*.o
+*.a
+
+# Kotlin
+.gradle/
+build/
+*.class
+
+# General
+.DS_Store
+*.swp
+*.swo

ensoul-0.1.0/PKG-INFO

@@ -0,0 +1,215 @@
+Metadata-Version: 2.4
+Name: ensoul
+Version: 0.1.0
+Summary: Official Python SDK for the Ensoul API
+Project-URL: Homepage, https://ensoul-ai.com
+Project-URL: Documentation, https://ensoul-ai.com/products/studio/docs
+Project-URL: Repository, https://github.com/ensoul-ai/ensoul-sdk
+Project-URL: Issues, https://github.com/ensoul-ai/ensoul-sdk/issues
+Author-email: Ensoul <support@ensoul.ai>
+License-Expression: Apache-2.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.25.0
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: dev
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-asyncio; extra == 'dev'
+Requires-Dist: respx; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Ensoul Python SDK
+
+Python client library for the Ensoul personality simulation API.
+
+## Installation
+
+```
+pip install ensoul
+```
+
+## Quick Start
+
+```python
+from ensoul import Ensoul
+
+client = Ensoul(api_key="your-api-key")
+
+# Create a persona
+persona = client.personas.create(name="Alex", domain="my_domain")
+
+# Send a chat message
+response = client.chat.send(persona.id, "Hello, who are you?")
+print(response.response)
+```
+
+The API key can also be set via the `ENSOUL_API_KEY` environment variable, in which case no `api_key` argument is needed.
+
+The client supports context managers for automatic cleanup:
+
+```python
+with Ensoul(api_key="your-api-key") as client:
+    persona = client.personas.get("persona-id")
+```
+
+## Async Usage
+
+```python
+import asyncio
+from ensoul import AsyncEnsoul
+
+async def main():
+    async with AsyncEnsoul(api_key="your-api-key") as client:
+        persona = await client.personas.create(name="Jordan", domain="my_domain")
+        response = await client.chat.send(persona.id, "Tell me about yourself.")
+        print(response.response)
+
+asyncio.run(main())
+```
+
+## Streaming
+
+Chat supports server-sent events (SSE) for streaming responses:
+
+```python
+from ensoul import Ensoul
+from ensoul.streaming import parse_chat_event
+
+client = Ensoul(api_key="your-api-key")
+
+stream = client.chat.stream("persona-id", "What do you think about music?")
+for event in stream.events():
+    parsed = parse_chat_event(event)
+    if not parsed.is_final:
+        print(parsed.chunk, end="", flush=True)
+    else:
+        print()  # newline after stream completes
+```
+
+The async client returns an `AsyncSSEStream` that works the same way with `async for`.
+
+## Pagination
+
+List endpoints return a `SyncPage` (or `AsyncPage`) object. Use `.auto_paging_iter()` to iterate through all pages automatically:
+
+```python
+# Manual page access
+page = client.personas.list(per_page=50)
+print(page.items)    # current page items
+print(page.total)    # total count across all pages
+
+# Automatic pagination — fetches subsequent pages as needed
+for persona in client.personas.list().auto_paging_iter():
+    print(persona.name)
+```
+
+Async pagination works the same way with `async for`.
+
+## Error Handling
+
+All SDK errors inherit from `EnsoulError`. HTTP errors are subclasses of `APIError`:
+
+```python
+from ensoul.errors import (
+    EnsoulError,
+    APIError,
+    AuthenticationError,
+    AuthorizationError,
+    NotFoundError,
+    RateLimitError,
+    ValidationError,
+    ConflictError,
+    ServerError,
+)
+
+try:
+    persona = client.personas.get("nonexistent-id")
+except NotFoundError:
+    print("Persona not found")
+except AuthenticationError:
+    print("Invalid or missing API key")
+except RateLimitError:
+    print("Rate limit exceeded — back off and retry")
+except APIError as e:
+    print(f"API error {e.status_code}: {e.message}")
+```
+
+## Configuration
+
+The client reads two environment variables as defaults:
+
+| Variable | Purpose |
+|----------|---------|
+| `ENSOUL_API_KEY` | API key (avoids passing `api_key=` in code) |
+| `ENSOUL_BASE_URL` | API base URL (default: `https://api.ensoul-ai.com`) |
+
+**Demo API** — the current hosted demo is available at:
+
+```bash
+export ENSOUL_BASE_URL="https://api.demo.ensoul-ai.com"
+export ENSOUL_API_KEY="your-api-key"
+```
+
+With these set, `Ensoul()` connects to the demo with no constructor arguments.
+
+You can also pass the base URL explicitly:
+
+```python
+client = Ensoul(api_key="ens_...", base_url="https://api.demo.ensoul-ai.com")
+```
+
+## Authentication
+
+**API key** (recommended):
+
+```python
+client = Ensoul(api_key="ens_...")
+# or set ENSOUL_API_KEY in the environment
+client = Ensoul()
+```
+
+**Bearer token**:
+
+```python
+client = Ensoul(bearer_token="eyJ...")
+```
+
+**OAuth2 token exchange** (client credentials flow):
+
+```python
+token_response = client.auth.token(
+    grant_type="client_credentials",
+    client_id="your-client-id",
+    client_secret="your-client-secret",
+)
+authed_client = Ensoul(bearer_token=token_response.access_token)
+```
+
+## Resources
+
+| Namespace | Description |
+|-----------|-------------|
+| `client.personas` | CRUD, list (paginated), batch create, personality vectors, filters, connections |
+| `client.chat` | Send messages, streaming SSE, conversation history |
+| `client.domains` | Domain configuration management |
+| `client.simulations` | Time-based evolution simulations |
+| `client.aggregate` | Aggregate queries with streaming results |
+| `client.memory` | Persona memory management |
+| `client.sessions` | Hierarchical session orchestration |
+| `client.frameworks` | Framework management |
+| `client.auth` | OAuth2 token exchange and API key management |
+| `client.health` | Service health checks |
+| `client.info` | Server info and configuration |
+
+## Requirements
+
+- Python 3.11+
+- [`httpx`](https://www.python-httpx.org/) — HTTP transport
+- [`pydantic`](https://docs.pydantic.dev/) 2.x — request and response models

ensoul-0.1.0/README.md

@@ -0,0 +1,188 @@
+# Ensoul Python SDK
+
+Python client library for the Ensoul personality simulation API.
+
+## Installation
+
+```
+pip install ensoul
+```
+
+## Quick Start
+
+```python
+from ensoul import Ensoul
+
+client = Ensoul(api_key="your-api-key")
+
+# Create a persona
+persona = client.personas.create(name="Alex", domain="my_domain")
+
+# Send a chat message
+response = client.chat.send(persona.id, "Hello, who are you?")
+print(response.response)
+```
+
+The API key can also be set via the `ENSOUL_API_KEY` environment variable, in which case no `api_key` argument is needed.
+
+The client supports context managers for automatic cleanup:
+
+```python
+with Ensoul(api_key="your-api-key") as client:
+    persona = client.personas.get("persona-id")
+```
+
+## Async Usage
+
+```python
+import asyncio
+from ensoul import AsyncEnsoul
+
+async def main():
+    async with AsyncEnsoul(api_key="your-api-key") as client:
+        persona = await client.personas.create(name="Jordan", domain="my_domain")
+        response = await client.chat.send(persona.id, "Tell me about yourself.")
+        print(response.response)
+
+asyncio.run(main())
+```
+
+## Streaming
+
+Chat supports server-sent events (SSE) for streaming responses:
+
+```python
+from ensoul import Ensoul
+from ensoul.streaming import parse_chat_event
+
+client = Ensoul(api_key="your-api-key")
+
+stream = client.chat.stream("persona-id", "What do you think about music?")
+for event in stream.events():
+    parsed = parse_chat_event(event)
+    if not parsed.is_final:
+        print(parsed.chunk, end="", flush=True)
+    else:
+        print()  # newline after stream completes
+```
+
+The async client returns an `AsyncSSEStream` that works the same way with `async for`.
+
+## Pagination
+
+List endpoints return a `SyncPage` (or `AsyncPage`) object. Use `.auto_paging_iter()` to iterate through all pages automatically:
+
+```python
+# Manual page access
+page = client.personas.list(per_page=50)
+print(page.items)    # current page items
+print(page.total)    # total count across all pages
+
+# Automatic pagination — fetches subsequent pages as needed
+for persona in client.personas.list().auto_paging_iter():
+    print(persona.name)
+```
+
+Async pagination works the same way with `async for`.
+
+## Error Handling
+
+All SDK errors inherit from `EnsoulError`. HTTP errors are subclasses of `APIError`:
+
+```python
+from ensoul.errors import (
+    EnsoulError,
+    APIError,
+    AuthenticationError,
+    AuthorizationError,
+    NotFoundError,
+    RateLimitError,
+    ValidationError,
+    ConflictError,
+    ServerError,
+)
+
+try:
+    persona = client.personas.get("nonexistent-id")
+except NotFoundError:
+    print("Persona not found")
+except AuthenticationError:
+    print("Invalid or missing API key")
+except RateLimitError:
+    print("Rate limit exceeded — back off and retry")
+except APIError as e:
+    print(f"API error {e.status_code}: {e.message}")
+```
+
+## Configuration
+
+The client reads two environment variables as defaults:
+
+| Variable | Purpose |
+|----------|---------|
+| `ENSOUL_API_KEY` | API key (avoids passing `api_key=` in code) |
+| `ENSOUL_BASE_URL` | API base URL (default: `https://api.ensoul-ai.com`) |
+
+**Demo API** — the current hosted demo is available at:
+
+```bash
+export ENSOUL_BASE_URL="https://api.demo.ensoul-ai.com"
+export ENSOUL_API_KEY="your-api-key"
+```
+
+With these set, `Ensoul()` connects to the demo with no constructor arguments.
+
+You can also pass the base URL explicitly:
+
+```python
+client = Ensoul(api_key="ens_...", base_url="https://api.demo.ensoul-ai.com")
+```
+
+## Authentication
+
+**API key** (recommended):
+
+```python
+client = Ensoul(api_key="ens_...")
+# or set ENSOUL_API_KEY in the environment
+client = Ensoul()
+```
+
+**Bearer token**:
+
+```python
+client = Ensoul(bearer_token="eyJ...")
+```
+
+**OAuth2 token exchange** (client credentials flow):
+
+```python
+token_response = client.auth.token(
+    grant_type="client_credentials",
+    client_id="your-client-id",
+    client_secret="your-client-secret",
+)
+authed_client = Ensoul(bearer_token=token_response.access_token)
+```
+
+## Resources
+
+| Namespace | Description |
+|-----------|-------------|
+| `client.personas` | CRUD, list (paginated), batch create, personality vectors, filters, connections |
+| `client.chat` | Send messages, streaming SSE, conversation history |
+| `client.domains` | Domain configuration management |
+| `client.simulations` | Time-based evolution simulations |
+| `client.aggregate` | Aggregate queries with streaming results |
+| `client.memory` | Persona memory management |
+| `client.sessions` | Hierarchical session orchestration |
+| `client.frameworks` | Framework management |
+| `client.auth` | OAuth2 token exchange and API key management |
+| `client.health` | Service health checks |
+| `client.info` | Server info and configuration |
+
+## Requirements
+
+- Python 3.11+
+- [`httpx`](https://www.python-httpx.org/) — HTTP transport
+- [`pydantic`](https://docs.pydantic.dev/) 2.x — request and response models

ensoul-0.1.0/examples/quickstart.py

@@ -0,0 +1,75 @@
+"""Ensoul SDK Quickstart Example.
+
+Set ENSOUL_API_KEY environment variable before running.
+
+Usage:
+    python examples/quickstart.py
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+
+from ensoul import AsyncEnsoul, Ensoul, NotFoundError
+
+
+def sync_example() -> None:
+    """Synchronous usage examples."""
+    client = Ensoul()  # reads ENSOUL_API_KEY from env
+
+    # List domains
+    domains = client.domains.list()
+    print("Domains:")
+    for domain in domains.items:
+        print(f"  {domain}")
+
+    # Create a persona
+    persona = client.personas.create(
+        name="Research Participant",
+        domain="example_domain",
+        personality_data={"openness": 75, "conscientiousness": 60},
+    )
+    print(f"\nCreated persona: {persona.id}")
+
+    # Chat
+    response = client.chat.send(persona.id, "What are your thoughts on technology?")
+    print(f"Response: {response.response}")
+
+    # Streaming chat
+    print("Streaming: ", end="")
+    for event in client.chat.stream(persona.id, "Tell me more."):
+        try:
+            data = json.loads(event.data)
+            if "chunk" in data:
+                print(data["chunk"], end="", flush=True)
+        except json.JSONDecodeError:
+            pass
+    print()
+
+    # Auto-pagination — iterates all pages automatically
+    print("\nAll personas:")
+    for p in client.personas.list(per_page=10).auto_paging_iter():
+        print(f"  {p.name}")
+
+    # Error handling
+    try:
+        client.personas.get("nonexistent_id")
+    except NotFoundError as e:
+        print(f"\nExpected error: {e.message}")
+
+    client.close()
+
+
+async def async_example() -> None:
+    """Async usage examples."""
+    async with AsyncEnsoul() as client:
+        personas = await client.personas.list()
+        print("Async personas:")
+        for p in personas.items:
+            print(f"  {p.name}")
+
+
+if __name__ == "__main__":
+    sync_example()
+    asyncio.run(async_example())

ensoul-0.1.0/pyproject.toml

@@ -0,0 +1,55 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "ensoul"
+version = "0.1.0"
+description = "Official Python SDK for the Ensoul API"
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.11"
+authors = [
+    { name = "Ensoul", email = "support@ensoul.ai" },
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Typing :: Typed",
+]
+dependencies = [
+    "httpx>=0.25.0",
+    "pydantic>=2.0.0",
+]
+
+[project.urls]
+Homepage = "https://ensoul-ai.com"
+Documentation = "https://ensoul-ai.com/products/studio/docs"
+Repository = "https://github.com/ensoul-ai/ensoul-sdk"
+Issues = "https://github.com/ensoul-ai/ensoul-sdk/issues"
+
+[project.optional-dependencies]
+dev = [
+    "pytest",
+    "pytest-asyncio",
+    "respx",
+    "ruff",
+    "mypy",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/ensoul"]
+
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"

ensoul-0.1.0/src/ensoul/__init__.py

@@ -0,0 +1,60 @@
+"""Ensoul SDK for Python."""
+
+from __future__ import annotations
+
+from ensoul.client import AsyncEnsoul, Ensoul
+from ensoul.config import ClientConfig
+from ensoul.errors import (
+    APIError,
+    AuthenticationError,
+    AuthorizationError,
+    ConflictError,
+    EnsoulError,
+    NotFoundError,
+    RateLimitError,
+    ServerError,
+    ValidationError,
+)
+from ensoul.generated.auth import APIKeyResponse, TokenResponse, UserResponse
+from ensoul.generated.chat import ChatRequest, ChatResponse, ConversationResponse
+from ensoul.generated.enums import SessionStatus, SimulationStatus
+from ensoul.generated.personas import (
+    PersonaBatchCreate,
+    PersonaBatchResponse,
+    PersonaCreate,
+    PersonaResponse,
+    PersonalityVectorResponse,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Ensoul",
+    "AsyncEnsoul",
+    "ClientConfig",
+    # Errors
+    "EnsoulError",
+    "APIError",
+    "AuthenticationError",
+    "AuthorizationError",
+    "NotFoundError",
+    "RateLimitError",
+    "ValidationError",
+    "ConflictError",
+    "ServerError",
+    # Types
+    "PersonaCreate",
+    "PersonaResponse",
+    "PersonaBatchCreate",
+    "PersonaBatchResponse",
+    "PersonalityVectorResponse",
+    "ChatRequest",
+    "ChatResponse",
+    "ConversationResponse",
+    "TokenResponse",
+    "APIKeyResponse",
+    "UserResponse",
+    "SimulationStatus",
+    "SessionStatus",
+    "__version__",
+]

ensoul-0.1.0/src/ensoul/_types.py

@@ -0,0 +1,29 @@
+"""Shared type aliases for the Ensoul SDK."""
+
+from __future__ import annotations
+
+from typing import Any, Protocol, TypeVar, runtime_checkable
+
+from pydantic import BaseModel
+
+__all__ = [
+    "HeadersLike",
+    "QueryParams",
+    "RequestBody",
+    "T",
+    "PaginatedResponse",
+]
+
+HeadersLike = dict[str, str]
+QueryParams = dict[str, Any]
+RequestBody = dict[str, Any] | BaseModel
+T = TypeVar("T")
+
+
+@runtime_checkable
+class PaginatedResponse(Protocol):
+    items: list
+    total: int
+    page: int
+    per_page: int
+    pages: int