# SuperU - AI Voice Assistant Platform

[![PyPI version](https://img.shields.io/pypi/v/superu.svg)](https://pypi.org/project/superu/)
[![Python 3.7+](https://img.shields.io/badge/python-3.7+-blue.svg)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)

SuperU is a Python SDK for creating AI-powered voice assistants, running phone calls, and managing assistants, tools, folders, contacts, audiences, and knowledge bases from your SuperU account.

## Installation

```bash
pip install superu
```

## Quickstart

```python
import superu

client = superu.SuperU("your_api_key")

# 1) List existing agents
agents = client.agents.list(limit=5)
print(agents)

# 2) Start an outbound call
call = client.calls.create_outbound_call(
    assistant_id="assistant_id_from_dashboard",
    to="+15557654321",
    campaign_id="demo_call",
    customer_name="Ava",
    customer_id="cust_123"
)
print(call)
```

## Client Overview

The SDK exposes a single top-level client, `SuperU`, which validates your API key and provides service wrappers.

```python
import superu

client = superu.SuperU("your_api_key")

# Wrappers available on the client
client.calls
client.agents
client.folders
client.call_logs
client.tools
client.phone_numbers
client.contacts
client.audience
client.knowledge_base
```

## API Reference

### `SuperU`

High-level client that validates your API key and exposes service wrappers.

Constructor

- `SuperU(api_key)`

Methods

- `validate_api_key(api_key)`

Attributes

- `calls`: `CallWrapper`
- `agents`: `AssistantWrapper`
- `folders`: `FolderWrapper`
- `call_logs`: `CallLogsWrapper`
- `tools`: `ToolsWrapper`
- `phone_numbers`: `PhoneNumberWrapper`
- `contacts`: `ContactWrapper`
- `audience`: `AudienceWrapper`
- `knowledge_base`: `KnowledgeBaseWrapper`

---

### `CallWrapper`

Create and analyze calls.

Methods

- `create_twilio_call(phoneNumberId, to_, assistant_id, additional_payload=None)`
- `analysis_twilio_call(call_uuid, custom_fields=None)`
- `create_outbound_call(assistant_id, to, from_=None, campaign_id='demo_call', customer_name='Unknown', customer_id='Unknown', variable_values=None)`

Custom analysis fields format

- Each item must be a dict with keys: `field`, `definition`, `outputs_options`.
- `field` and `definition` must be strings.
- `outputs_options` must be a list of strings.

Example

```python
twilio_call = client.calls.create_twilio_call(
    phoneNumberId="pn_123",
    to_="+15557654321",
    assistant_id="assistant_id_from_dashboard"
)
print(twilio_call)

analysis = client.calls.analysis_twilio_call(
    call_uuid="call_uuid_here",
    custom_fields=[
        {
            "field": "intent",
            "definition": "Primary intent of the caller",
            "outputs_options": ["sales", "support", "other"]
        }
    ]
)
print(analysis)
```

---

### `AssistantWrapper`

Manage agents and agent versions.

Methods

- `create_version(agent_id, version, assistant_data, knowledge_base=None, tools=None, call_forwarding=None)`
- `update_version(agent_id, version_id, version=None, assistant_data=None, composio_app=None)`
- `list(page=1, limit=20, inbound_or_outbound=None, search_query=None)`
- `get_version(agent_id, version)`
- `list_versions(agent_id)`
- `deploy_version(agent_id, version_id)`
- `create_agent(type=None, name=None, company_name=None, assistant_name=None, first_message=None, voice_id=None, voice_provider='11labs', speed='1.0', bg_noice=False, system_prompt=None, industry='Blank Template', useCase='Blank Template', form_model=None, assistant_data=None, knowledge_base=None, tools=None, call_forwarding=None)`
- `update_name(agent_id, name)`
- `import_agents()`
- `delete(agent_id)`

Example

```python
agent = client.agents.create_agent(
    type="outbound",
    name="Demo Assistant",
    assistant_name="Demo Voice",
    first_message="Hello! This is a demo call.",
    system_prompt="You are a friendly assistant.",
    voice_id="90ipbRoKi4CpHXvKVtl0"
)
print(agent)
```

---

### `PhoneNumberWrapper`

Retrieve owned phone numbers.

Methods

- `get_owned()`

Example

```python
numbers = client.phone_numbers.get_owned()
print(numbers)
```

---

### `CallLogsWrapper`

Retrieve call logs with filtering.

Methods

- `get_logs(assistant_id='all', limit=20, page=1, before=None, after=None, status=None, campaign_id=None, search_query=None)`

Example

```python
logs = client.call_logs.get_logs(assistant_id="all", limit=10, page=1)
print(logs)
```

---

### `ToolsWrapper`

Create and manage tools your agents can call.

Methods

- `create(tool_data)`
- `list(page=1, per_page=20, tool_type=None)`
- `get(tool_id)`
- `update(tool_id, update_data)`
- `delete(tool_id)`

Example

```python
tool = client.tools.create({
    "name": "check-user-status",
    "description": "Check if a user exists in our database",
    "parameters": {
        "type": "object",
        "properties": {
            "email": {"type": "string", "description": "User email"}
        },
        "required": ["email"]
    },
    "tool_url": "/api/check-user",
    "tool_url_domain": "https://your-api.com",
    "async_": False
})
print(tool)
```

---

### `FolderWrapper`

Organize agents into folders.

Methods

- `create(folder_name, description=None)`
- `list(page=1, per_page=20)`
- `get(folder_id)`
- `update(folder_id, folder_name=None, description=None)`
- `delete(folder_id)`
- `assign_agent(agent_id, folder_id=None)`
- `get_agents(folder_id, page=1, per_page=20)`

Example

```python
folder = client.folders.create("Outbound Agents", description="Sales and support")
folder_id = folder.get("folder_id")

if folder_id:
    client.folders.assign_agent(agent_id="assistant_id_from_dashboard", folder_id=folder_id)
    print(client.folders.get_agents(folder_id))
```

---

### `ContactWrapper`

Create and list contacts with validation.

Methods

- `create(first_name, last_name, email, country_code, phone_number, audience_id=None)`
- `list(page=1, limit=10, search_query=None)`

Validation

- Email, phone number, and country code are validated before sending the request.

Example

```python
contact = client.contacts.create(
    first_name="Ava",
    last_name="Patel",
    email="ava.patel@example.com",
    country_code="+1",
    phone_number="5551234567"
)
print(contact)
```

---

### `AudienceWrapper`

Create, update, and manage audiences and their contacts.

Methods

- `create(audience_name, contacts, audience_description='')`
- `list()`
- `get(audience_id)`
- `get_contacts(audience_id, page=1, limit=10)`
- `update(audience_id, audience_name=None, audience_description=None)`
- `add_contacts(audience_id, contacts)`
- `delete(audience_id)`

Contact format

- Required: `first_name`, `country_code`, `phone_number`
- Optional: `last_name`, `email`, `variable_values`

Example

```python
audience = client.audience.create(
    audience_name="Demo Audience",
    contacts=[
        {
            "first_name": "Ava",
            "country_code": "+1",
            "phone_number": "5551234567"
        }
    ]
)
print(audience)
```

---

### `KnowledgeBaseWrapper`

Create and manage knowledge bases with file uploads.

Methods

- `create(name, description, files)`
- `list(page=1, limit=10)`
- `get(knowledge_base_id)`

Files format

- File-like objects: `open("file.pdf", "rb")`
- Tuples: `(filename, content, content_type)`

Example

```python
with open("faq.pdf", "rb") as f:
    kb = client.knowledge_base.create(
        name="FAQ",
        description="Frequently asked questions",
        files=[f]
    )
print(kb)
```

## Error Handling

Methods validate inputs and raise `ValueError` for invalid data. API failures raise `Exception` when non-success status codes are returned.

## Support

- Documentation: [https://dev.superu.ai](https://dev.superu.ai)
- Issues: [https://github.com/superu/superu-python/issues](https://github.com/superu/superu-python/issues)
- Email: Contact support via your SuperU dashboard

## License

This project is licensed under the MIT License. See [LICENSE](LICENSE).
