Metadata-Version: 2.4
Name: wiil-python
Version: 0.0.17
Summary: Official Python SDK for WIIL Platform - AI-powered conversational services for intelligent customer interactions, voice processing, real-time translation, and business management
Author-email: WIIL <dev-support@wiil.io>
License: MIT
Project-URL: Homepage, https://console.wiil.io
Project-URL: Documentation, https://docs.wiil.io
Project-URL: Repository, https://github.com/wiil-io/wiil-python
Project-URL: Issues, https://github.com/wiil-io/wiil-python/issues
Keywords: wiil,wiil-platform,wiil-sdk,ai,artificial-intelligence,conversational-ai,chatbot,voice-ai,speech-to-text,text-to-speech,stt,tts,translation,real-time-translation,voice-translation,business-automation,appointment-booking,reservation-system,order-management,customer-service,telephony,voice-calls,agent-deployment,python,sdk
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
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: Typing :: Typed
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.31.0
Requires-Dist: pydantic<3.0.0,>=2.0.0
Requires-Dist: email-validator>=2.0.0
Requires-Dist: typing-extensions>=4.5.0; python_version < "3.11"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: httpx>=0.28.0; extra == "dev"
Requires-Dist: responses>=0.25.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: respx>=0.20.0; extra == "dev"

# WIIL Python SDK

Ship AI-powered business features without building telecom, catalog infrastructure, or integration plumbing.

[![Python](https://img.shields.io/badge/Python-3.8+-blue.svg?style=flat-square)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)

---

## What You Can Ship

This SDK gives you APIs to build:

- **Catalog-aware AI agents** - Agents grounded in real business data such as menus, products, services, reservations, and properties
- **Multi-channel conversations** - Web, phone, SMS, and email workflows through unified APIs
- **Transaction workflows** - Appointments, reservations, orders, inquiries, and outbound follow-ups
- **Outbound communications** - Automated calls, emails, and SMS without provider setup

What you skip building:

- Telephony integration, SMS gateways, SMTP servers
- Voice pipeline infrastructure for STT, LLM, and TTS workflows
- Catalog schema design and multi-location logic
- Retry logic, queue management, and delivery tracking
- Channel-specific protocols and failure handling

**You write the business logic. The SDK handles the infrastructure.**

---

## Installation

```bash
pip install wiil-python
```

For isolated projects:

```bash
python -m venv .venv
source .venv/bin/activate
pip install wiil-python
```

On Windows PowerShell:

```powershell
python -m venv .venv
.venv\Scripts\Activate.ps1
pip install wiil-python
```

---

## Quick Start

```python
import os

from wiil import WiilClient

client = WiilClient(api_key=os.environ["WIIL_API_KEY"])
```

### Deploy an AI Agent

```python
from wiil.models.service_mgt.dynamic_setup import (
    DynamicPhoneAgentSetup,
    DynamicWebAgentSetup,
)
from wiil.types import BusinessSupportServices

# Phone agent with live number
phone = client.dynamic_phone_agent.create(
    DynamicPhoneAgentSetup(
        assistant_name="Sarah",
        capabilities=[BusinessSupportServices.APPOINTMENT_MANAGEMENT],
    )
)
print("Phone number:", phone.phone_number)

# Web agent with widget snippets
web = client.dynamic_web_agent.create(
    DynamicWebAgentSetup(
        assistant_name="Emma",
        website_url="https://example.com",
        capabilities=[BusinessSupportServices.APPOINTMENT_MANAGEMENT],
    )
)
print("Widget snippets:", web.integration_snippets)
```

### Send Notifications

```python
import time

from wiil.models.conversation import (
    CreateCallRequest,
    CreateEmailRequest,
    CreateSmsRequest,
    EmailRecipient,
)
from wiil.types import ScheduleType

# Email
client.outbound_emails.create(
    CreateEmailRequest(
        to=[EmailRecipient(email="customer@example.com")],
        template_id="order_confirmation",
        subject="Order confirmed",
        body_html="<p>Your order {{orderNumber}} is confirmed.</p>",
        body_text="Your order {{orderNumber}} is confirmed.",
        variables={"orderNumber": "ORD-123"},
    )
)

# SMS
client.outbound_sms.create(
    CreateSmsRequest(
        to="+14155551234",
        from_number="+14155555678",
        body="Your appointment is confirmed for tomorrow at 2 PM.",
    )
)

# Voice call
client.outbound_calls.create(
    CreateCallRequest(
        to="+14155551234",
        from_number="+14155555678",
        agent_configuration_id="reminder_agent",
        schedule_type=ScheduleType.SCHEDULED,
        scheduled_at=int(time.time() * 1000) + 2 * 60 * 60 * 1000,
    )
)
```

### Manage Business Catalogs

```python
from wiil.models.business_mgt import (
    CreateBusinessMenuItem,
    CreateBusinessMenuItemVariant,
    CreateBusinessProduct,
    CreateBusinessProductVariant,
    CreateBusinessService,
)

# Services
service = client.business_services.create(
    CreateBusinessService(
        name="Hair Styling",
        duration=60,
        base_price=75.00,
    )
)

# Menu items with variants
menu_item = client.menus.create_item(
    CreateBusinessMenuItem(
        name="Cheeseburger",
        category_id="cat_main",
        price=12.99,
        variants=[
            CreateBusinessMenuItemVariant(
                name="Regular",
                price=12.99,
                is_default=True,
                is_active=True,
                is_available=True,
            )
        ],
    )
)

# Products with variants
product = client.products.create(
    CreateBusinessProduct(
        name="Wireless Mouse",
        category_id="cat_electronics",
        price=29.99,
        is_alcoholic=False,
        variants=[
            CreateBusinessProductVariant(
                axis_values={},
                price=29.99,
                is_default=True,
                is_active=True,
            )
        ],
    )
)
```

### Book Transactions Through AI Workflows

```python
from wiil.models.business_mgt import CreateServiceAppointment, CreateTableReservation

appointment = client.service_appointments.create(
    CreateServiceAppointment(
        business_service_id=service.id,
        customer_id="cust_123",
        start_time=int(time.time() * 1000) + 24 * 60 * 60 * 1000,
        duration=60,
    )
)

reservation = client.table_reservations.create(
    CreateTableReservation(
        resource_id="table_5",
        customer_id="cust_123",
        floor_plan_id="floor_main",
        persons_number=4,
        time=int(time.time() * 1000) + 2 * 60 * 60 * 1000,
        duration=90,
    )
)
```

---

## Examples & Guides

Comprehensive guides are in the [`examples/`](./examples/) directory.

### Getting Started

| Guide | What You Build |
| ----- | -------------- |
| [Dynamic Agent Setup](./examples/dynamic-agent-setup-guide.md) | Deploy phone/web agents in one API call |
| [Fundamental Configuration](./examples/fundamental-configuration-setup.md) | Fine-grained multi-step agent setup |

### Outbound Communications

| Guide | What You Build |
| ----- | -------------- |
| [Outbound Communications](./examples/outbound-communications-guide.md) | Full notification system across calls, email, and SMS |
| [Messaging Quick Start](./examples/messaging-guide.md) | Send your first notification in minutes |

### Business Services

| Guide | What You Build |
| ----- | -------------- |
| [Services & Appointments](./examples/business-services/services-and-appointments-guide.md) | Bookable services and appointment scheduling |
| [Menus & Orders](./examples/business-services/menus-and-orders-guide.md) | Restaurant menus and food ordering |
| [Products & Orders](./examples/business-services/products-and-orders-guide.md) | Product catalogs and retail orders |
| [Reservations](./examples/business-services/reservations-guide.md) | Tables, rooms, rentals, and bookings |
| [Property Management](./examples/business-services/property-management-guide.md) | Listings, inquiries, and lead tracking |

### Channels

| Guide | What You Build |
| ----- | -------------- |
| [Web Channels](./examples/channels/web-channels.md) | Chat widget integration |
| [Voice Channels](./examples/channels/voice-channels.md) | Phone call handling |
| [SMS Channels](./examples/channels/sms-channels.md) | Text messaging |

[See all examples](./examples/README.md)

---

## SDK Features

- **Type-Safe** - Python type hints with Pydantic models
- **Validated** - Runtime validation using Pydantic
- **Production-Grade** - Robust error handling and configurable timeouts
- **Modern** - Synchronous and asynchronous clients
- **Comprehensive** - Account, service management, business management, conversation, and outbound resources

---

## Available Resources

### Dynamic Agent Setup

```python
client.dynamic_phone_agent
client.dynamic_web_agent
client.dynamic_agent_status
```

### Outbound APIs

```python
client.outbound_templates
client.outbound_calls
client.outbound_emails
client.outbound_sms
```

### Service Configuration

```python
client.agent_configs
client.instruction_configs
client.deployment_configs
client.deployment_channels
client.provisioning_configs
client.support_models
client.telephony_provider
client.conversation_configs
client.knowledge_sources
```

### Business Management

```python
client.business_services
client.customers
client.menus
client.menu_item_variants
client.modifiers
client.products
client.product_variants
client.product_sets
client.service_appointments
client.table_reservations
client.room_reservations
client.rental_reservations
client.menu_orders
client.product_orders
client.reservation_resources
client.floor_plans
client.property_config
client.property_inquiry
```

---

## Error Handling

```python
from wiil.errors import WiilAPIError, WiilNetworkError, WiilValidationError

try:
    result = client.business_services.create(
        CreateBusinessService(name="Consultation", duration=30, base_price=50)
    )
except WiilValidationError as exc:
    print("Invalid input:", exc.details)
except WiilAPIError as exc:
    print(f"API error {exc.status_code}:", exc.message)
    print("Code:", exc.code)
except WiilNetworkError:
    print("Network error. Retry with backoff.")
```

---

## Async Support

```python
import asyncio
import os

from wiil import AsyncWiilClient


async def main() -> None:
    async with AsyncWiilClient(api_key=os.environ["WIIL_API_KEY"]) as client:
        organization = await client.organizations.get()
        print("Organization:", organization.company_name)


asyncio.run(main())
```

---

## Configuration

```python
from wiil import WiilClient

client = WiilClient(
    api_key="your-api-key",
    base_url="https://api.wiil.io/v1",
    timeout=60,
)
```

---

## Security

Server-side only. Never expose your API key in client-side code.

```python
import os

from wiil import WiilClient

# Good: environment variable
client = WiilClient(api_key=os.environ["WIIL_API_KEY"])

# Bad: hardcoded key
client = WiilClient(api_key="sk_live_...")
```

---

## Requirements

- Python 3.8 or higher
- Pydantic
- requests/httpx, depending on sync or async usage

---

## Development

```bash
pip install -e ".[dev]"
pytest
pytest --cov=wiil --cov-report=html
black wiil tests
ruff check wiil tests
mypy wiil
```

---

## Support

- **Documentation**: [https://docs.wiil.io](https://docs.wiil.io)
- **API Reference**: [https://docs.wiil.io/developer/api-reference](https://docs.wiil.io/developer/api-reference)
- **Issues**: [GitHub Issues](https://github.com/wiil-io/wiil-python/issues)
- **Email**: [dev-support@wiil.io](mailto:dev-support@wiil.io)

---

## License

MIT (c) [WIIL](https://wiil.io)

---

Built with care by the WIIL team
