# Yemaya Python SDK

The official Python SDK for the Yemaya platform - end-to-end movie and game creation with AI-powered tools.

## Installation

```bash
pip install yemaya
```

For CLI support:
```bash
pip install yemaya[cli]
```

## Quick Start

### Synchronous Usage

```python
from yemaya import YemayaClient

# Initialize client (reads API key from YEMAYA_API_KEY env var)
client = YemayaClient()

# Or provide API key directly
client = YemayaClient(api_key="your-api-key")

# Create a project
project = client.projects.create(
    name="My Game",
    type="game",
    description="An awesome game project"
)

# Work with project resources
ctx = client.project(project.id)

# Create assets
asset = ctx.assets.create(
    name="Hero Character",
    type="character"
)

# Create scenes
scene = ctx.scenes.create(
    name="Level 1",
    description="The first level"
)

# Create characters
character = ctx.characters.create(
    name="Hero",
    role="main",
    personality={
        "traits": ["brave", "curious"],
        "motivations": ["save the world"]
    }
)

# Use AI generation
response = client.ai.generate_text(
    prompt="Write a backstory for a medieval knight",
    model="claude-3-sonnet"
)

print(response.result)

# Close the client when done
client.close()
```

### Context Manager

```python
from yemaya import YemayaClient

with YemayaClient(api_key="your-api-key") as client:
    projects = client.projects.list()
    for project in projects.data:
        print(f"{project.name} ({project.type})")
```

### Async Usage

```python
import asyncio
from yemaya import AsyncYemayaClient

async def main():
    async with AsyncYemayaClient(api_key="your-api-key") as client:
        # Create a project
        project = await client.projects.create(
            name="My Async Project",
            type="movie"
        )

        # Work with resources
        ctx = client.project(project.id)
        scenes = await ctx.scenes.list()

        # AI generation
        response = await client.ai.generate_image(
            prompt="A majestic castle at sunset",
            model="dalle-3"
        )

        print(f"Generated image: {response.generation.output_url}")

asyncio.run(main())
```

## CLI Usage

The Yemaya CLI provides command-line access to the platform:

```bash
# Login with your API key
yemaya auth login

# List projects
yemaya projects list

# Create a project
yemaya projects create --name "My Project" --type game

# Generate content with AI
yemaya ai generate --prompt "Write a game story" --type text

# List assets in a project
yemaya assets list --project proj_123
```

## Configuration

### Environment Variables

- `YEMAYA_API_KEY` - Your Yemaya API key
- `YEMAYA_BASE_URL` - API base URL (default: https://api.yemaya.dev)
- `YEMAYA_WS_URL` - WebSocket URL (default: wss://api.yemaya.dev/ws)
- `YEMAYA_DEBUG` - Enable debug logging (1, true, yes)
- `YEMAYA_TIMEOUT` - Request timeout in seconds
- `YEMAYA_MAX_RETRIES` - Maximum retry attempts

### Programmatic Configuration

```python
from yemaya import YemayaClient, YemayaConfig
from yemaya.config import TimeoutConfig, RetryConfig

config = YemayaConfig(
    api_key="your-api-key",
    base_url="https://custom.api.example.com",
    timeout=TimeoutConfig(read=60.0, connect=10.0),
    retry=RetryConfig(max_retries=5),
    debug=True,
)

client = YemayaClient(config=config)
```

## API Resources

### Projects

```python
# List projects
projects = client.projects.list(page=1, per_page=20)

# Get a project
project = client.projects.get("proj_123")

# Create a project
project = client.projects.create(
    name="My Project",
    type="game",
    description="Project description",
    tags=["rpg", "fantasy"]
)

# Update a project
project = client.projects.update(
    "proj_123",
    name="Updated Name",
    status="active"
)

# Delete a project
client.projects.delete("proj_123")

# Duplicate a project
copy = client.projects.duplicate("proj_123", name="Project Copy")

# Archive a project
project = client.projects.archive("proj_123")
```

### Assets

```python
ctx = client.project("proj_123")

# List assets
assets = ctx.assets.list(type="texture")

# Upload a file
asset = ctx.assets.upload(
    file="/path/to/file.png",
    name="Background Texture",
    type="texture"
)

# Download an asset
content = ctx.assets.download("asset_123")

# Get asset versions
versions = ctx.assets.get_versions("asset_123")
```

### Scenes

```python
ctx = client.project("proj_123")

# List scenes
scenes = ctx.scenes.list()

# Create a scene
scene = ctx.scenes.create(
    name="Opening Scene",
    settings={"ambientColor": "#404040"}
)

# Add objects to a scene
obj = ctx.scenes.add_object(
    scene_id="scene_123",
    name="Player Spawn",
    position={"x": 0, "y": 0, "z": 0}
)

# Reorder scenes
ctx.scenes.reorder(["scene_3", "scene_1", "scene_2"])
```

### Characters

```python
ctx = client.project("proj_123")

# Create a character
character = ctx.characters.create(
    name="Hero",
    role="main",
    appearance={
        "height": 1.8,
        "hairColor": "brown"
    },
    personality={
        "traits": ["brave", "kind"],
        "backstory": "A young adventurer..."
    }
)

# Generate a backstory with AI
character = ctx.characters.generate_backstory(
    "char_123",
    style="dramatic",
    length="detailed"
)
```

### AI Generation

```python
# Text generation
response = client.ai.generate_text(
    prompt="Write a fantasy story opening",
    model="claude-3-opus",
    temperature=0.7
)

# Image generation
response = client.ai.generate_image(
    prompt="A magical forest",
    model="dalle-3",
    style="fantasy",
    aspect_ratio="16:9"
)

# Code generation
response = client.ai.generate_code(
    prompt="Create a player movement script",
    language="python"
)

# List available models
models = client.ai.list_models()
```

## Error Handling

```python
from yemaya import YemayaClient
from yemaya.exceptions import (
    YemayaError,
    YemayaAPIError,
    YemayaAuthenticationError,
    YemayaNotFoundError,
    YemayaRateLimitError,
    YemayaValidationError,
)

try:
    client = YemayaClient()
    project = client.projects.get("invalid_id")
except YemayaNotFoundError as e:
    print(f"Project not found: {e}")
except YemayaAuthenticationError as e:
    print(f"Authentication failed: {e}")
except YemayaRateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after} seconds")
except YemayaValidationError as e:
    print(f"Validation error: {e.errors}")
except YemayaAPIError as e:
    print(f"API error [{e.status_code}]: {e.message}")
except YemayaError as e:
    print(f"SDK error: {e}")
```

## Development

```bash
# Clone the repository
git clone https://github.com/yemaya/yemaya
cd libs/yemaya/sdk-python

# Install development dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Type checking
mypy src/yemaya

# Linting
ruff check src/yemaya
```

## License

MIT License - see LICENSE for details.