Metadata-Version: 2.4
Name: zephyrcode
Version: 3.0.0
Summary: Official Python SDK for ZephyrCode — the AI coding agent platform
Author-email: ZephyrCode Labs <hackerkk826@gmail.com>
License: MIT
Project-URL: Homepage, https://zephyrcode.space-z.ai
Project-URL: Documentation, https://zephyrcode.space-z.ai/docs
Project-URL: Repository, https://zephyrcode.space-z.ai
Project-URL: Bug Tracker, https://zephyrcode.space-z.ai/account
Keywords: zephyrcode,ai,coding,agent,code-generation,tts,text-to-speech,voice-cloning,llm,api,sdk
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.25.0

# ZephyrCode Python SDK

<div align="center">

**Official Python SDK for [ZephyrCode](https://zephyrcode.space-z.ai) — the AI coding agent platform**

[![PyPI version](https://badge.fury.io/py/zephyrcode.svg)](https://pypi.org/project/zephyrcode/)
[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

</div>

---

## Installation

```bash
pip install zephyrcode
```

## Quickstart

### 1. Get an API key

Create one at [zephyrcode.space-z.ai/apikey](https://zephyrcode.space-z.ai/apikey). Your key will look like:

```
zephyr-yourname-aBcD123eFgH456...
```

### 2. Stream a chat completion

```python
from zephyrcode import ZephyrCode, ContentEvent, DoneEvent

client = ZephyrCode(api_key="zephyr-yourname-xxx")

for chunk in client.chat.stream(
    message="Build a React login form with Tailwind CSS",
    model="z-code-ultra",
    mode="code",
):
    if isinstance(chunk, ContentEvent):
        print(chunk.delta, end="", flush=True)
    elif isinstance(chunk, DoneEvent):
        print(f"\n\n✅ Done — tools used: {chunk.tools_used}")
```

### 3. Non-streaming response

```python
response = client.chat.create(
    message="Explain async/await in Python",
    model="z-code-pro",
)
print(response.content)
print(f"Reasoning steps: {len(response.reasoning)}")
print(f"Tool calls: {len(response.tool_calls)}")
```

---

## API Reference

### `ZephyrCode(api_key, base_url, timeout)`

Main client.

| Parameter  | Type | Default | Description |
|------------|------|---------|-------------|
| `api_key`  | `str` | required | Your `zephyr-{username}-{secret}` key |
| `base_url` | `str` | `https://zephyrcode.space-z.ai` | API base URL |
| `timeout`  | `int` | `60` | Request timeout in seconds |

---

### `client.chat.stream(...)`

Stream a chat completion as Server-Sent Events.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `message` | `str` | — | A single user message |
| `messages` | `list[Message]` | — | Full conversation history (alternative to `message`) |
| `model` | `str` | `"z-code-ultra"` | Model: `z-code-ultra`, `z-code-pro`, `z-code-local` |
| `mode` | `str` | `"code"` | Mode: `code`, `agentic`, `architect`, `debug`, `review`, `explain`, `website`, `mobile` |
| `thinking` | `bool` | `True` | Enable extended chain-of-thought |
| `project_context` | `dict` | `None` | `{language, framework, files}` |

**Yields** typed event objects:

| Event | Description |
|-------|-------------|
| `MetaEvent` | Stream start — model + mode info |
| `PlanEvent` | Task decomposition with steps |
| `ReasoningEvent` | Chain-of-thought chunk |
| `ToolCallEvent` | Agent invokes a tool |
| `ToolResultEvent` | Structured tool output |
| `ContentEvent` | Markdown content delta (`.delta` attribute) |
| `DoneEvent` | Terminal event with stats |
| `ErrorEvent` | Fatal error (raises `StreamError`) |

---

### `client.chat.create(...)`

Same parameters as `.stream()`, but returns a single `ChatResponse` with `.content`, `.reasoning`, `.tool_calls`, `.plan`.

---

### `client.tts.create(text, voice, speed, translate, target_language)`

Text-to-speech synthesis.

```python
audio = client.tts.create(
    text="Hello, welcome to ZephyrCode!",
    voice="rachel",
    speed=1.0,
)
audio.save("welcome.wav")
```

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `text` | `str` | required | Text to synthesize (max 4000 chars) |
| `voice` | `str` | `"rachel"` | Voice ID (see [voice catalog](https://zephyrcode.space-z.ai/voices)) |
| `speed` | `float` | `1.0` | Playback speed (0.5–2.0) |
| `translate` | `bool` | `False` | Translate text before synthesis |
| `target_language` | `str` | `None` | Target language (e.g. `"Hindi"`, `"Spanish"`) |

**Returns** `TTSResponse` with `.audio` (bytes) and `.save(path)`.

**Popular voices:** `adam`, `rachel`, `antoni`, `bella`, `arnold`, `hindi-priya`, `hindi-arjun`, `sofia`, `carlos`, `mei`, `yuki`.

---

### `client.apikeys` — API Key Management

```python
# List all keys
keys = client.apikeys.list()

# Create a new key
new_key = client.apikeys.create(
    name="Production",
    permissions="all",        # "all", "restricted", "readonly"
    expiration="60d",         # "1d", "3d", "7d", "21d", "60d", "never"
    credit=100.0,             # USD spending limit (0 = unlimited)
    project="My App",
)
print(f"Save this key (shown once): {new_key.key}")

# Revoke a key
client.apikeys.revoke("key_abc123")

# Delete a key
client.apikeys.delete("key_abc123")
```

---

### `client.projects` — Project Management

```python
# List projects
projects = client.projects.list()

# Create a project
project = client.projects.create(name="My App")
print(f"Created project: {project.id}")

# Delete a project
client.projects.delete(project.id)
```

---

### `client.models` — Model Information

```python
models = client.models.list()
for m in models:
    print(f"{m.id} — {m.label}: {m.description}")
```

---

## Models

| Model | ID | Best for |
|-------|----|----------|
| Z Code Ultra | `z-code-ultra` | Frontier reasoning, multi-file refactors |
| Z Code Pro | `z-code-pro` | Everyday coding, quick fixes |
| Z Code Local | `z-code-local` | On-device, privacy-first |

## Modes

| Mode | Description |
|------|-------------|
| `website` | Website Builder |
| `mobile` | Mobile App Builder |
| `code` | Write, edit, refactor production code |
| `agentic` | Autonomous multi-step engineering |
| `architect` | Design systems, evaluate tradeoffs |
| `debug` | Root-cause failures and fixes |
| `review` | Review diffs for security & performance |
| `explain` | Explain code and concepts |

---

## Error Handling

```python
from zephyrcode import (
    ZephyrCode,
    AuthenticationError,
    RateLimitError,
    APIError,
    StreamError,
)

client = ZephyrCode(api_key="zephyr-...")

try:
    response = client.chat.create("Build a counter")
except AuthenticationError:
    print("Invalid API key")
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after}s")
except APIError as e:
    print(f"API error ({e.status_code}): {e}")
except StreamError as e:
    print(f"Stream error: {e}")
```

---

## Multi-turn Conversations

```python
from zephyrcode import ZephyrCode, Message

client = ZephyrCode(api_key="zephyr-...")

history = [
    Message(role="user", content="Create a Python function to reverse a string"),
    Message(role="assistant", content="def reverse(s): return s[::-1]"),
    Message(role="user", content="Now add type hints and a docstring"),
]

for chunk in client.chat.stream(messages=history, model="z-code-ultra"):
    if hasattr(chunk, "delta") and chunk.delta:
        print(chunk.delta, end="", flush=True)
```

---

## Project Context

```python
response = client.chat.create(
    message="Add a login form to the App.tsx",
    model="z-code-ultra",
    mode="code",
    project_context={
        "language": "TypeScript",
        "framework": "React",
        "files": ["src/App.tsx", "src/components/Login.tsx"],
    },
)
```

---

## License

MIT © ZephyrCode Labs

## Links

- **Documentation:** [zephyrcode.space-z.ai/docs](https://zephyrcode.space-z.ai/docs)
- **API Keys:** [zephyrcode.space-z.ai/apikey](https://zephyrcode.space-z.ai/apikey)
- **Support:** hackerkk826@gmail.com
