syllable-sdk-python

Summary

SyllableSDK:

Syllable Platform SDK

Syllable SDK gives you the power of awesome AI agentry. 🚀

Overview

The Syllable SDK provides a comprehensive set of tools and APIs to integrate powerful AI capabilities into your communication applications. Whether you're building chatbots, virtual assistants, or any other AI-driven solutions, Syllable SDK has got you covered.

Features

Natural Language Processing (NLP): Understand and generate human language with ease.
Machine Learning Models: Leverage pre-trained models or train your own custom models.
Speech Recognition: Convert speech to text and vice versa.
Data Analytics: Analyze and visualize data to gain insights.
Integration: Seamlessly integrate with other services and platforms.

SDK Installation

Note

Python version upgrade policy

Once a Python version reaches its official end of life date, a 3-month grace period is provided for users to upgrade. Following this grace period, the minimum python version supported in the SDK will be updated.

The SDK can be installed with either pip or poetry package managers.

PIP

PIP is the default package installer for Python, enabling easy installation and management of packages from PyPI via the command line.

pip install syllable-sdk

Poetry

Poetry is a modern tool that simplifies dependency management and package publishing by using a single pyproject.toml file to handle project metadata and dependencies.

poetry add syllable-sdk

Shell and script usage with `uv`

You can use this SDK in a Python shell with uv and the uvx command that comes with it like so:

uvx --from syllable-sdk python

It's also possible to write a standalone Python script without needing to set up a whole project like so:

#!/usr/bin/env -S uv run --script
# /// script
# requires-python = ">=3.9"
# dependencies = [
#     "syllable-sdk",
# ]
# ///

from syllable_sdk import SyllableSDK

sdk = SyllableSDK(
  # SDK arguments
)

# Rest of script here...

Once that is saved to a file, you can run it with uv run script.py where script.py can be replaced with the actual file name.

IDE Support

PyCharm

Generally, the SDK will work well with most IDEs out of the box. However, when using PyCharm, you can enjoy much better integration with Pydantic by installing an additional plugin.

PyCharm Pydantic Plugin

SDK Example Usage

Example

# Synchronous Example
import os
import syllable_sdk
from syllable_sdk import SyllableSDK


with SyllableSDK(
    api_key_header=os.getenv("SYLLABLESDK_API_KEY_HEADER", ""),
) as ss_client:

    res = ss_client.agents.list(page=0, limit=25, search_fields=[
        syllable_sdk.AgentProperties.NAME,
    ], search_field_values=[
        "Some Object Name",
    ], start_datetime="2023-01-01T00:00:00Z", end_datetime="2024-01-01T00:00:00Z")

    # Handle response
    print(res)

The same SDK client can also be used to make asychronous requests by importing asyncio.

# Asynchronous Example
import asyncio
import os
import syllable_sdk
from syllable_sdk import SyllableSDK

async def main():

    async with SyllableSDK(
        api_key_header=os.getenv("SYLLABLESDK_API_KEY_HEADER", ""),
    ) as ss_client:

        res = await ss_client.agents.list_async(page=0, limit=25, search_fields=[
            syllable_sdk.AgentProperties.NAME,
        ], search_field_values=[
            "Some Object Name",
        ], start_datetime="2023-01-01T00:00:00Z", end_datetime="2024-01-01T00:00:00Z")

        # Handle response
        print(res)

asyncio.run(main())

Authentication

Per-Client Security Schemes

This SDK supports the following security scheme globally:

Name	Type	Scheme	Environment Variable
`api_key_header`	apiKey	API key	`SYLLABLESDK_API_KEY_HEADER`

To authenticate with the API the api_key_header parameter must be set when initializing the SDK client instance. For example:

import os
import syllable_sdk
from syllable_sdk import SyllableSDK


with SyllableSDK(
    api_key_header=os.getenv("SYLLABLESDK_API_KEY_HEADER", ""),
) as ss_client:

    res = ss_client.agents.list(page=0, limit=25, search_fields=[
        syllable_sdk.AgentProperties.NAME,
    ], search_field_values=[
        "Some Object Name",
    ], start_datetime="2023-01-01T00:00:00Z", end_datetime="2024-01-01T00:00:00Z")

    # Handle response
    print(res)

Available Resources and Operations

Available methods

agents

list - Agent List
create - Create Agent
update - Update Agent
get_by_id - Get Agent By Id
delete - Delete Agent
agent_get_available_voices - Get Available Agent Voices

agents.test

send_test_message - Send New Message

channels

list - Get Channels
delete - Delete Channel Target

channels.targets

available_targets - Available Targets List
list - Get Channel Targets
create - Assign A Channel Target
get_by_id - Get A Channel Target
update - Edit Channel Target

channels.twilio

get_by_id - Get Twilio Channel By Id
update - Update Twilio Channel
create - Create Twilio Channel

channels.twilio.numbers

add - Add Twilio Number
update - Update Twilio Number
list - List Twilio Phone Numbers

conversations

list - Conversations List

custom_messages

list - Custom Messages List
create - Create Custom Message
update - Update Custom Message
get_by_id - Get Custom Message By Id
delete - Delete Custom Message

dashboards

post_list_dashboard - Post List Dashboards
post_get_dashboard - Post Fetch Info
~~post_session_events_dashboard~~ - Post Session Events ⚠️ Deprecated
~~post_session_summary_dashboard~~ - Post Session Summary ⚠️ Deprecated
~~post_session_transfers_dashboard~~ - Post Session Transfers ⚠️ Deprecated
~~post_sessions_dashboard~~ - Post Sessions ⚠️ Deprecated

data_sources

list - List Data Sources
create - Create Data Source
update - Update Data Source
get_by_id - Get Data Source
delete - Delete Data Source

events

list - Events List

incidents

list - List Incidents
create - Create Incident
update - Update Incident
incident_get_organizations - Get Organizations
get_by_id - Get Incident By Id
delete - Delete Incident

insights

list - Insights List

insights.folders

list - List Insights Upload Folders
create - Create Insights Upload Folder
get_by_id - Get Insights Folder Details
delete - Delete Insights Folder
update - Update Insights Folder
upload_file - Upload Insights Upload Folder
list_files - Fetch Insights Upload Files
move_files - Move Insights Upload Files

insights.tools

list - List Insight Tool Configurations
create - Create Insight Tool Configuration
get_by_id - Get Insight Tool Config By Id
delete - Delete Insight Tool Configuration
update - Update Insights Tool Configuration
insights_tool_test - Test Insights Tool
insight_tool_get_definitions - Get Insight Tool Definitions

insights.workflows

list - Insight Workflow List
create - Create Insight Workflow
get_by_id - Get Insight Workflow By Id
update - Update Insights Workflow
delete - Delete Insights Workflow
inactivate - Inactivate Insights Workflow
activate - Activate Insights Workflow
queue_work - Queue Insights Workflow For Sessions/Files

language_groups

list - List Language Groups
create - Create Language Group
update - Update Language Group
get_by_id - Get Language Group
delete - Delete Language Group
language_groups_create_voice_sample - Create Voice Sample

organizations

organizations_get - Get Current Organization
update - Update Current Organization
create - Create Organization
delete - Delete Current Organization

outbound

outbound.batches

list - List Outbound Communication Batches
create - Create Outbound Communication Batch
get_by_id - Get Outbound Communication Batch
update - Update Outbound Communication Batch
delete - Delete Outbound Communication Batch
upload - Upload Outbound Communication Batch
results - Fetch Outbound Communication Batch Results
add - Create Outbound Communication Request
remove - Delete Requests By List Of Reference Ids

outbound.campaigns

list - List Outbound Communication Campaigns
create - Create Outbound Communication Campaign
get_by_id - Get Outbound Communication Campaign
update - Update Outbound Communication Campaign
delete - Delete Outbound Communication Campaign

permissions

list - List Permissions

prompts

list - Prompt List
create - Create Prompt
update - Update Prompt
get_by_id - Get Prompt By Id
delete - Delete Prompt
prompts_history - Get Prompt History
prompt_get_supported_llms - Get Supported Llm Configs

roles

list - List Roles
create - Create Role
update - Update Role
get_by_id - Get Role
delete - Delete Role

services

list - Service List
create - Create Service
update - Update Service
get_by_id - Get Service By Id
delete - Delete Service

session_debug

get_session_data_by_sid - Get Session Data By Sid
get_session_data_by_session_id - Get Session Data By Session Id
get_session_tool_call_result_by_id - Get Session Tool Call Result By Id

session_labels

get_by_id - Get Label By Id
create - Create Label
list - Session Labels List

sessions

list - Sessions List
get_by_id - Get A Single Session By Id
generate_session_recording_urls - Generate Recording Urls
session_recording_stream - Stream Recording

sessions.full_summary

get_by_id - Get Full Session Summary By Id

sessions.latency

get_by_id - Inspect Latency For Session

sessions.transcript

get_by_id - Get Session Transcript By Id

takeouts

create - Create Takeout
takeouts_get_by_job_id - Get Takeout
takeouts_get_file - Get File

tools

list - Tool List
create - Create Tool
update - Update Tool
get_by_name - Tool Info
delete - Delete Tool

users

list - List Users
create - Create User
update - Update User
delete - Delete User
users_get_by_email - Get User
users_send_email - Send User Email
users_delete_account - Request Removal Of This Account

v1

list - List Users
create - Create User
update - Update User
delete - Delete User
users_get_by_email - Get User
users_send_email - Send User Email
users_delete_account - Request Removal Of This Account

File uploads

Certain SDK methods accept file objects as part of a request body or multi-part request. It is possible and typically recommended to upload files as a stream rather than reading the entire contents into memory. This avoids excessive memory consumption and potentially crashing with out-of-memory errors when working with very large files. The following example demonstrates how to attach a file stream to a request.

Tip

For endpoints that handle file uploads bytes arrays can also be used. However, using streams is recommended for large files.

import os
from syllable_sdk import SyllableSDK


with SyllableSDK(
    api_key_header=os.getenv("SYLLABLESDK_API_KEY_HEADER", ""),
) as ss_client:

    res = ss_client.insights.folders.upload_file(folder_id=444923, call_id="<id>")

    # Handle response
    print(res)

Retries

Some of the endpoints in this SDK support retries. If you use the SDK without any configuration, it will fall back to the default retry strategy provided by the API. However, the default retry strategy can be overridden on a per-operation basis, or across the entire SDK.

To change the default retry strategy for a single API call, simply provide a RetryConfig object to the call:

import os
import syllable_sdk
from syllable_sdk import SyllableSDK
from syllable_sdk.utils import BackoffStrategy, RetryConfig


with SyllableSDK(
    api_key_header=os.getenv("SYLLABLESDK_API_KEY_HEADER", ""),
) as ss_client:

    res = ss_client.agents.list(page=0, limit=25, search_fields=[
        syllable_sdk.AgentProperties.NAME,
    ], search_field_values=[
        "Some Object Name",
    ], start_datetime="2023-01-01T00:00:00Z", end_datetime="2024-01-01T00:00:00Z",
        RetryConfig("backoff", BackoffStrategy(1, 50, 1.1, 100), False))

    # Handle response
    print(res)

If you'd like to override the default retry strategy for all operations that support retries, you can use the retry_config optional parameter when initializing the SDK:

import os
import syllable_sdk
from syllable_sdk import SyllableSDK
from syllable_sdk.utils import BackoffStrategy, RetryConfig


with SyllableSDK(
    retry_config=RetryConfig("backoff", BackoffStrategy(1, 50, 1.1, 100), False),
    api_key_header=os.getenv("SYLLABLESDK_API_KEY_HEADER", ""),
) as ss_client:

    res = ss_client.agents.list(page=0, limit=25, search_fields=[
        syllable_sdk.AgentProperties.NAME,
    ], search_field_values=[
        "Some Object Name",
    ], start_datetime="2023-01-01T00:00:00Z", end_datetime="2024-01-01T00:00:00Z")

    # Handle response
    print(res)

Error Handling

SyllableSDKError is the base class for all HTTP error responses. It has the following properties:

Property	Type	Description
`err.message`	`str`	Error message
`err.status_code`	`int`	HTTP response status code eg `404`
`err.headers`	`httpx.Headers`	HTTP response headers
`err.body`	`str`	HTTP body. Can be empty string if no body is returned.
`err.raw_response`	`httpx.Response`	Raw HTTP response
`err.data`		Optional. Some errors may contain structured data. See Error Classes.

Example

import os
import syllable_sdk
from syllable_sdk import SyllableSDK, models


with SyllableSDK(
    api_key_header=os.getenv("SYLLABLESDK_API_KEY_HEADER", ""),
) as ss_client:
    res = None
    try:

        res = ss_client.agents.list(page=0, limit=25, search_fields=[
            syllable_sdk.AgentProperties.NAME,
        ], search_field_values=[
            "Some Object Name",
        ], start_datetime="2023-01-01T00:00:00Z", end_datetime="2024-01-01T00:00:00Z")

        # Handle response
        print(res)


    except models.SyllableSDKError as e:
        # The base class for HTTP error responses
        print(e.message)
        print(e.status_code)
        print(e.body)
        print(e.headers)
        print(e.raw_response)

        # Depending on the method different errors may be thrown
        if isinstance(e, models.HTTPValidationError):
            print(e.data.detail)  # Optional[List[syllable_sdk.ValidationError]]

Error Classes

Primary errors:

SyllableSDKError: The base class for HTTP error responses.
- HTTPValidationError: Validation Error. Status code 422. *

Less common errors (5)

Network errors:

httpx.RequestError: Base class for request errors.
- httpx.ConnectError: HTTP client was unable to make a request to a server.
- httpx.TimeoutException: HTTP request timed out.

Inherit from SyllableSDKError:

ResponseValidationError: Type mismatch between the response data and the expected Pydantic model. Provides access to the Pydantic validation error via the cause attribute.

* Check the method documentation to see if the error is applicable.

Server Selection

Override Server URL Per-Client

The default server can be overridden globally by passing a URL to the server_url: str optional parameter when initializing the SDK client instance. For example:

import os
import syllable_sdk
from syllable_sdk import SyllableSDK


with SyllableSDK(
    server_url="https://api.syllable.cloud",
    api_key_header=os.getenv("SYLLABLESDK_API_KEY_HEADER", ""),
) as ss_client:

    res = ss_client.agents.list(page=0, limit=25, search_fields=[
        syllable_sdk.AgentProperties.NAME,
    ], search_field_values=[
        "Some Object Name",
    ], start_datetime="2023-01-01T00:00:00Z", end_datetime="2024-01-01T00:00:00Z")

    # Handle response
    print(res)

Custom HTTP Client

The Python SDK makes API calls using the httpx HTTP library. In order to provide a convenient way to configure timeouts, cookies, proxies, custom headers, and other low-level configuration, you can initialize the SDK client with your own HTTP client instance. Depending on whether you are using the sync or async version of the SDK, you can pass an instance of HttpClient or AsyncHttpClient respectively, which are Protocol's ensuring that the client has the necessary methods to make API calls. This allows you to wrap the client with your own custom logic, such as adding custom headers, logging, or error handling, or you can just pass an instance of httpx.Client or httpx.AsyncClient directly.

For example, you could specify a header for every request that this sdk makes as follows:

from syllable_sdk import SyllableSDK
import httpx

http_client = httpx.Client(headers={"x-custom-header": "someValue"})
s = SyllableSDK(client=http_client)

or you could wrap the client with your own custom logic:

from syllable_sdk import SyllableSDK
from syllable_sdk.httpclient import AsyncHttpClient
import httpx

class CustomClient(AsyncHttpClient):
    client: AsyncHttpClient

    def __init__(self, client: AsyncHttpClient):
        self.client = client

    async def send(
        self,
        request: httpx.Request,
        *,
        stream: bool = False,
        auth: Union[
            httpx._types.AuthTypes, httpx._client.UseClientDefault, None
        ] = httpx.USE_CLIENT_DEFAULT,
        follow_redirects: Union[
            bool, httpx._client.UseClientDefault
        ] = httpx.USE_CLIENT_DEFAULT,
    ) -> httpx.Response:
        request.headers["Client-Level-Header"] = "added by client"

        return await self.client.send(
            request, stream=stream, auth=auth, follow_redirects=follow_redirects
        )

    def build_request(
        self,
        method: str,
        url: httpx._types.URLTypes,
        *,
        content: Optional[httpx._types.RequestContent] = None,
        data: Optional[httpx._types.RequestData] = None,
        files: Optional[httpx._types.RequestFiles] = None,
        json: Optional[Any] = None,
        params: Optional[httpx._types.QueryParamTypes] = None,
        headers: Optional[httpx._types.HeaderTypes] = None,
        cookies: Optional[httpx._types.CookieTypes] = None,
        timeout: Union[
            httpx._types.TimeoutTypes, httpx._client.UseClientDefault
        ] = httpx.USE_CLIENT_DEFAULT,
        extensions: Optional[httpx._types.RequestExtensions] = None,
    ) -> httpx.Request:
        return self.client.build_request(
            method,
            url,
            content=content,
            data=data,
            files=files,
            json=json,
            params=params,
            headers=headers,
            cookies=cookies,
            timeout=timeout,
            extensions=extensions,
        )

s = SyllableSDK(async_client=CustomClient(httpx.AsyncClient()))

Resource Management

The SyllableSDK class implements the context manager protocol and registers a finalizer function to close the underlying sync and async HTTPX clients it uses under the hood. This will close HTTP connections, release memory and free up other resources held by the SDK. In short-lived Python programs and notebooks that make a few SDK method calls, resource management may not be a concern. However, in longer-lived programs, it is beneficial to create a single SDK instance via a context manager and reuse it across the application.

import os
from syllable_sdk import SyllableSDK
def main():

    with SyllableSDK(
        api_key_header=os.getenv("SYLLABLESDK_API_KEY_HEADER", ""),
    ) as ss_client:
        # Rest of application here...


# Or when using async:
async def amain():

    async with SyllableSDK(
        api_key_header=os.getenv("SYLLABLESDK_API_KEY_HEADER", ""),
    ) as ss_client:
        # Rest of application here...

Debugging

You can setup your SDK to emit debug logs for SDK requests and responses.

You can pass your own logger class directly into your SDK.

from syllable_sdk import SyllableSDK
import logging

logging.basicConfig(level=logging.DEBUG)
s = SyllableSDK(debug_logger=logging.getLogger("syllable_sdk"))

You can also enable a default debug logger by setting an environment variable SYLLABLESDK_DEBUG to true.

Name		Name	Last commit message	Last commit date
Latest commit History 398 Commits
.devcontainer		.devcontainer
.github/workflows		.github/workflows
.speakeasy		.speakeasy
.vscode		.vscode
docs		docs
scripts		scripts
src/syllable_sdk		src/syllable_sdk
.gitattributes		.gitattributes
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
README-PYPI.md		README-PYPI.md
README.md		README.md
RELEASES.md		RELEASES.md
USAGE.md		USAGE.md
codeSamples.yaml		codeSamples.yaml
openapi.json		openapi.json
openapi.yaml		openapi.yaml
overlay-remove-V1.yaml		overlay-remove-V1.yaml
poetry.lock		poetry.lock
poetry.toml		poetry.toml
py.typed		py.typed
pylintrc		pylintrc
pyproject.toml		pyproject.toml

speakeasy-sdks/syllable-sdk-python

Folders and files

Latest commit

History

Repository files navigation

syllable-sdk-python

Summary

Syllable Platform SDK

Overview

Features

Table of Contents

SDK Installation

PIP

Poetry

Shell and script usage with uv

IDE Support

PyCharm

SDK Example Usage

Example

Authentication

Per-Client Security Schemes

Available Resources and Operations

File uploads

Retries

Error Handling

Example

Error Classes

Server Selection

Override Server URL Per-Client

Custom HTTP Client

Resource Management

Debugging

About

Resources

Uh oh!

Stars

Watchers

Forks

Languages

Shell and script usage with `uv`