callaider 0.1.0__tar.gz

callaider-0.1.0/.gitignore

@@ -0,0 +1,219 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+.idea/
+*.iml
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml

callaider-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gleb
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

callaider-0.1.0/PKG-INFO

@@ -0,0 +1,144 @@
+Metadata-Version: 2.5
+Name: callaider
+Version: 0.1.0
+Summary: Python SDK for Callaider AI Voice Platform
+Project-URL: Homepage, https://github.com/astatdeglebantiy/callaider-sdk-python
+Author-email: AstatdeGlebantiy <glebsh2chko@gmail.com>
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: httpx2>=2.12.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pytest-asyncio>=0.23.0
+Requires-Dist: pytest>=8.0.0
+Requires-Dist: respx>=0.21.0
+Description-Content-Type: text/markdown
+
+# Callaider Python SDK
+
+[![PyPI version](https://img.shields.io/pypi/v/callaider.svg)](https://pypi.org/project/callaider/)
+[![Python versions](https://img.shields.io/pypi/pyversions/callaider.svg)](https://pypi.org/project/callaider/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+The official Python client library for the [Callaider](https://callaider.ai) AI voice calling and conversational platform.
+
+Built on top of the [Callaider OpenAPI 3.0.3 specification](https://github.com/NBM-Labs/callaider_openapi).
+
+---
+
+## Features
+
+- ⚡ **Sync & Async clients** built on modern `httpx`.
+- 🛡️ **Fully typed** request/response models with Pydantic v2.
+- 🔄 **Automatic retries** with exponential backoff on 429/5xx errors.
+- 📞 **Complete Ringing API support**: Campaigns, batch calls, recordings, and statistics.
+- 🤖 **External Conversation Bridge**: Direct AI assistant messaging integration (ideal for Telegram bots).
+- 🪝 **Built-in Webhooks parser**: Typed events parsing for callback handling.
+
+---
+
+## Installation
+
+```bash
+pip install callaider
+```
+
+Or using `uv`:
+
+```bash
+uv add callaider
+```
+
+---
+
+## Quickstart
+
+### Synchronous Usage
+
+```python
+from callaider import Callaider
+
+client = Callaider(api_key="your_api_key_here")
+
+# 1. Check API status
+health = client.health()
+print(f"API status: {health.status}")
+
+# 2. Create an automated call campaign
+campaign = client.ringing.create_campaign(
+    assistant_id="asst_sales_01",
+    recipients=[
+        {"phone": "+380501234567", "name": "Alex"}
+    ],
+    name="VIP Outreach Campaign"
+)
+print(f"Created campaign #{campaign.id} with status: {campaign.status}")
+
+# 3. Launch the campaign
+client.ringing.launch_campaign(campaign.id)
+```
+
+### Asynchronous Usage (FastAPI, Asyncio, Telegram Bots)
+
+```python
+import asyncio
+from callaider import AsyncCallaider
+
+async def main():
+    async with AsyncCallaider(api_key="your_api_key_here") as client:
+        # Send a message to AI assistant bridge
+        response = await client.assistants.send_message(
+            assistant_id="asst_support_01",
+            external_conversation_id="telegram_user_12345",
+            message="Hello! I need help with my order."
+        )
+        print("AI Response:", response.text)
+
+asyncio.run(main())
+```
+
+---
+
+## Webhooks Handling
+
+Easily parse incoming Callaider webhook payloads in FastAPI or Flask:
+
+```python
+from fastapi import FastAPI, Request
+from callaider import Webhooks
+
+app = FastAPI()
+
+@app.post("/webhooks/callaider")
+async def handle_webhook(request: Request):
+    payload = await request.body()
+    event = Webhooks.construct_event(payload)
+
+    if event.event == "call.completed":
+        print(f"Call {event.data.call_id} finished. Duration: {event.data.duration_seconds}s")
+        print(f"Audio recording: {event.data.recording_url}")
+
+    return {"status": "ok"}
+```
+
+---
+
+## Development & Testing
+
+```bash
+# Clone the repository
+git clone https://github.com/astatdeglebantiy/callaider-python.git
+cd callaider-python
+
+# Install dependencies with uv
+uv sync --all-extras
+
+# Run unit tests
+uv run pytest
+```
+
+---
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

callaider-0.1.0/README.md

@@ -0,0 +1,128 @@
+# Callaider Python SDK
+
+[![PyPI version](https://img.shields.io/pypi/v/callaider.svg)](https://pypi.org/project/callaider/)
+[![Python versions](https://img.shields.io/pypi/pyversions/callaider.svg)](https://pypi.org/project/callaider/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+The official Python client library for the [Callaider](https://callaider.ai) AI voice calling and conversational platform.
+
+Built on top of the [Callaider OpenAPI 3.0.3 specification](https://github.com/NBM-Labs/callaider_openapi).
+
+---
+
+## Features
+
+- ⚡ **Sync & Async clients** built on modern `httpx`.
+- 🛡️ **Fully typed** request/response models with Pydantic v2.
+- 🔄 **Automatic retries** with exponential backoff on 429/5xx errors.
+- 📞 **Complete Ringing API support**: Campaigns, batch calls, recordings, and statistics.
+- 🤖 **External Conversation Bridge**: Direct AI assistant messaging integration (ideal for Telegram bots).
+- 🪝 **Built-in Webhooks parser**: Typed events parsing for callback handling.
+
+---
+
+## Installation
+
+```bash
+pip install callaider
+```
+
+Or using `uv`:
+
+```bash
+uv add callaider
+```
+
+---
+
+## Quickstart
+
+### Synchronous Usage
+
+```python
+from callaider import Callaider
+
+client = Callaider(api_key="your_api_key_here")
+
+# 1. Check API status
+health = client.health()
+print(f"API status: {health.status}")
+
+# 2. Create an automated call campaign
+campaign = client.ringing.create_campaign(
+    assistant_id="asst_sales_01",
+    recipients=[
+        {"phone": "+380501234567", "name": "Alex"}
+    ],
+    name="VIP Outreach Campaign"
+)
+print(f"Created campaign #{campaign.id} with status: {campaign.status}")
+
+# 3. Launch the campaign
+client.ringing.launch_campaign(campaign.id)
+```
+
+### Asynchronous Usage (FastAPI, Asyncio, Telegram Bots)
+
+```python
+import asyncio
+from callaider import AsyncCallaider
+
+async def main():
+    async with AsyncCallaider(api_key="your_api_key_here") as client:
+        # Send a message to AI assistant bridge
+        response = await client.assistants.send_message(
+            assistant_id="asst_support_01",
+            external_conversation_id="telegram_user_12345",
+            message="Hello! I need help with my order."
+        )
+        print("AI Response:", response.text)
+
+asyncio.run(main())
+```
+
+---
+
+## Webhooks Handling
+
+Easily parse incoming Callaider webhook payloads in FastAPI or Flask:
+
+```python
+from fastapi import FastAPI, Request
+from callaider import Webhooks
+
+app = FastAPI()
+
+@app.post("/webhooks/callaider")
+async def handle_webhook(request: Request):
+    payload = await request.body()
+    event = Webhooks.construct_event(payload)
+
+    if event.event == "call.completed":
+        print(f"Call {event.data.call_id} finished. Duration: {event.data.duration_seconds}s")
+        print(f"Audio recording: {event.data.recording_url}")
+
+    return {"status": "ok"}
+```
+
+---
+
+## Development & Testing
+
+```bash
+# Clone the repository
+git clone https://github.com/astatdeglebantiy/callaider-python.git
+cd callaider-python
+
+# Install dependencies with uv
+uv sync --all-extras
+
+# Run unit tests
+uv run pytest
+```
+
+---
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

callaider-0.1.0/examples/test_mock.py

@@ -0,0 +1,58 @@
+import asyncio
+from callaider import AsyncCallaider, Callaider, Webhooks
+
+MOCK_SERVER_URL = "http://127.0.0.1:4010"
+API_KEY = "test_token"
+
+
+def test_sync():
+    print("=== Testing Sync Client ===")
+    client = Callaider(api_key=API_KEY, base_url=MOCK_SERVER_URL)
+
+    # 1. Health
+    health = client.health()
+    print("Health:", health.status)
+
+    # 2. Campaigns
+    campaigns = client.ringing.list_campaigns()
+    print("Campaigns count:", len(campaigns))
+
+    # 3. Assistants message
+    assistant_reply = client.assistants.send_message(
+        assistant_id=1,
+        external_conversation_id="telegram_chat_987654",
+        message="Hello AI, this is a test message!",
+    )
+    print("Assistant Full Response:", assistant_reply)
+    print("Assistant Text Reply:", assistant_reply.text)
+
+
+async def test_async():
+    print("\n=== Testing Async Client ===")
+    async with AsyncCallaider(api_key=API_KEY, base_url=MOCK_SERVER_URL) as client:
+        health = await client.health()
+        print("Async Health:", health.status)
+
+
+def test_webhooks():
+    print("\n=== Testing Webhooks Parser ===")
+    raw_payload = """
+    {
+        "event": "call.completed",
+        "timestamp": "2026-09-04T12:00:00Z",
+        "data": {
+            "call_id": 12345,
+            "phone": "+380501234567",
+            "duration_seconds": 45,
+            "recording_url": "https://storage.callaider.ai/recordings/12345.mp3"
+        }
+    }
+    """
+    event = Webhooks.construct_event(raw_payload)
+    print(f"Parsed Event: {event.event} for call #{event.data.call_id}")
+
+
+if __name__ == "__main__":
+    test_sync()
+    asyncio.run(test_async())
+    test_webhooks()

callaider-0.1.0/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "callaider"
+version = "0.1.0"
+description = "Python SDK for Callaider AI Voice Platform"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [
+    { name = "AstatdeGlebantiy", email = "glebsh2chko@gmail.com" }
+]
+dependencies = [
+    "httpx2>=2.12.0",
+    "pydantic>=2.0.0",
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.23.0",
+    "respx>=0.21.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/astatdeglebantiy/callaider-sdk-python"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"

callaider-0.1.0/src/callaider/__init__.py

@@ -0,0 +1,27 @@
+from callaider._client import AsyncCallaider, Callaider
+from callaider.exceptions import (
+    APIConnectionError,
+    APIError,
+    APIStatusError,
+    AuthenticationError,
+    CallaiderError,
+    InternalServerError,
+    NotFoundError,
+    RateLimitError,
+)
+from callaider.webhooks import WebhookParsingError, Webhooks
+
+__all__ = [
+    "Callaider",
+    "AsyncCallaider",
+    "Webhooks",
+    "WebhookParsingError",
+    "CallaiderError",
+    "APIError",
+    "APIStatusError",
+    "AuthenticationError",
+    "NotFoundError",
+    "RateLimitError",
+    "InternalServerError",
+    "APIConnectionError",
+]