assistableai 0.1.0__tar.gz

assistableai-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.pyc
+.venv/
+dist/
+build/
+*.egg-info/
+.ruff_cache/
+.pytest_cache/
+.mypy_cache/
+.uv/

assistableai-0.1.0/PKG-INFO

@@ -0,0 +1,103 @@
+Metadata-Version: 2.4
+Name: assistableai
+Version: 0.1.0
+Summary: Official Python SDK and MCP server for the Assistable AI v3 API (generated from OpenAPI).
+Project-URL: Homepage, https://github.com/assistableai/assistableai-sdk
+Project-URL: Repository, https://github.com/assistableai/assistableai-sdk
+Author: Assistable AI
+License-Expression: MIT
+Keywords: ai,api,assistable,assistableai,mcp,sdk,voice
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Requires-Dist: attrs>=22.2.0
+Requires-Dist: httpx<0.29,>=0.23.1
+Requires-Dist: python-dateutil>=2.8.0
+Provides-Extra: mcp
+Requires-Dist: fastmcp<3,>=2.8; extra == 'mcp'
+Description-Content-Type: text/markdown
+
+# assistableai (Python)
+
+Official Python SDK **and** MCP server for the **Assistable AI v3 API**, generated
+from [`spec/openapi.json`](../../spec/openapi.json) — the same source of truth as
+the TypeScript SDK, CLI, and MCP server.
+
+- **SDK** — typed operation functions + models (openapi-python-client: attrs + httpx) with a thin auth wrapper.
+- **MCP server** — every v3 operation as an MCP tool, via FastMCP's `from_openapi` (optional `[mcp]` extra).
+
+## Install
+
+```bash
+pip install assistableai            # SDK only
+pip install 'assistableai[mcp]'     # SDK + MCP server
+```
+
+## SDK usage
+
+```python
+import assistableai
+from assistableai.api.assistants import list_assistants, get_assistant
+from assistableai.api.contacts import create_contact
+from assistableai.models import ContactCreate  # example model
+
+client = assistableai.configure(
+    api_key="ask_live_…",
+    subaccount_id="<subaccount-id>",   # sent as X-Subaccount-Id (optional)
+)
+
+# Every op exposes sync / sync_detailed / asyncio / asyncio_detailed.
+# Responses are the full {data, error, request_id} envelope (a typed model).
+envelope = list_assistants.sync(client=client.raw, limit=2)
+
+# Need status codes / headers? Use *_detailed:
+resp = get_assistant.sync_detailed("<assistant-id>", client=client.raw)
+print(resp.status_code, resp.parsed)
+
+# Per-call subaccount override:
+list_assistants.sync(client=client.raw, x_subaccount_id="<other-subaccount>")
+```
+
+Credentials resolve from explicit args, then the environment
+(`ASSISTABLE_API_KEY`, `ASSISTABLE_SUBACCOUNT_ID`, `ASSISTABLE_BASE_URL`). Default
+base URL is `https://api.assistable.ai`.
+
+`configure()` stores a process-global client (`assistableai.get_client()`); for
+multiple credentials, construct `assistableai.AssistableAI(...)` instances
+directly and pass `.raw`.
+
+## MCP server
+
+```bash
+ASSISTABLE_API_KEY=ask_live_… ASSISTABLE_SUBACCOUNT_ID=<id> assistableai-mcp
+# or: python -m assistableai.mcp
+```
+
+Add to an MCP client (e.g. Claude Desktop):
+
+```json
+{
+  "mcpServers": {
+    "assistableai": {
+      "command": "assistableai-mcp",
+      "env": {
+        "ASSISTABLE_API_KEY": "ask_live_…",
+        "ASSISTABLE_SUBACCOUNT_ID": "<subaccount-id>"
+      }
+    }
+  }
+}
+```
+
+## Develop
+
+```bash
+uv sync --all-extras          # create the dev venv
+uv run python scripts/generate.py   # regenerate assistableai._client from the spec
+uv build                      # build wheel + sdist
+```
+
+The generated client (`src/assistableai/_client`) and the bundled spec
+(`src/assistableai/spec/openapi.json`) are committed; regenerate them whenever
+`spec/openapi.json` changes.

assistableai-0.1.0/README.md

@@ -0,0 +1,83 @@
+# assistableai (Python)
+
+Official Python SDK **and** MCP server for the **Assistable AI v3 API**, generated
+from [`spec/openapi.json`](../../spec/openapi.json) — the same source of truth as
+the TypeScript SDK, CLI, and MCP server.
+
+- **SDK** — typed operation functions + models (openapi-python-client: attrs + httpx) with a thin auth wrapper.
+- **MCP server** — every v3 operation as an MCP tool, via FastMCP's `from_openapi` (optional `[mcp]` extra).
+
+## Install
+
+```bash
+pip install assistableai            # SDK only
+pip install 'assistableai[mcp]'     # SDK + MCP server
+```
+
+## SDK usage
+
+```python
+import assistableai
+from assistableai.api.assistants import list_assistants, get_assistant
+from assistableai.api.contacts import create_contact
+from assistableai.models import ContactCreate  # example model
+
+client = assistableai.configure(
+    api_key="ask_live_…",
+    subaccount_id="<subaccount-id>",   # sent as X-Subaccount-Id (optional)
+)
+
+# Every op exposes sync / sync_detailed / asyncio / asyncio_detailed.
+# Responses are the full {data, error, request_id} envelope (a typed model).
+envelope = list_assistants.sync(client=client.raw, limit=2)
+
+# Need status codes / headers? Use *_detailed:
+resp = get_assistant.sync_detailed("<assistant-id>", client=client.raw)
+print(resp.status_code, resp.parsed)
+
+# Per-call subaccount override:
+list_assistants.sync(client=client.raw, x_subaccount_id="<other-subaccount>")
+```
+
+Credentials resolve from explicit args, then the environment
+(`ASSISTABLE_API_KEY`, `ASSISTABLE_SUBACCOUNT_ID`, `ASSISTABLE_BASE_URL`). Default
+base URL is `https://api.assistable.ai`.
+
+`configure()` stores a process-global client (`assistableai.get_client()`); for
+multiple credentials, construct `assistableai.AssistableAI(...)` instances
+directly and pass `.raw`.
+
+## MCP server
+
+```bash
+ASSISTABLE_API_KEY=ask_live_… ASSISTABLE_SUBACCOUNT_ID=<id> assistableai-mcp
+# or: python -m assistableai.mcp
+```
+
+Add to an MCP client (e.g. Claude Desktop):
+
+```json
+{
+  "mcpServers": {
+    "assistableai": {
+      "command": "assistableai-mcp",
+      "env": {
+        "ASSISTABLE_API_KEY": "ask_live_…",
+        "ASSISTABLE_SUBACCOUNT_ID": "<subaccount-id>"
+      }
+    }
+  }
+}
+```
+
+## Develop
+
+```bash
+uv sync --all-extras          # create the dev venv
+uv run python scripts/generate.py   # regenerate assistableai._client from the spec
+uv build                      # build wheel + sdist
+```
+
+The generated client (`src/assistableai/_client`) and the bundled spec
+(`src/assistableai/spec/openapi.json`) are committed; regenerate them whenever
+`spec/openapi.json` changes.

assistableai-0.1.0/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "assistableai"
+version = "0.1.0"
+description = "Official Python SDK and MCP server for the Assistable AI v3 API (generated from OpenAPI)."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{ name = "Assistable AI" }]
+keywords = ["assistable", "assistableai", "sdk", "mcp", "api", "voice", "ai"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+]
+# The low-level client under assistableai._client is generated by
+# openapi-python-client (attrs + httpx; python-dateutil parses datetimes).
+dependencies = [
+  "httpx>=0.23.1,<0.29",
+  "attrs>=22.2.0",
+  "python-dateutil>=2.8.0",
+]
+
+[project.optional-dependencies]
+# Python MCP server (assistableai-mcp). Optional so SDK users don't pull it in.
+mcp = ["fastmcp>=2.8,<3"]
+
+[project.scripts]
+assistableai-mcp = "assistableai.mcp:main"
+
+[project.urls]
+Homepage = "https://github.com/assistableai/assistableai-sdk"
+Repository = "https://github.com/assistableai/assistableai-sdk"
+
+[tool.hatch.build.targets.wheel]
+# Single top-level package; the generated client (assistableai._client) and the
+# bundled spec (assistableai/spec/openapi.json) ride along inside it.
+packages = ["src/assistableai"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/assistableai", "scripts", "README.md"]
+
+[dependency-groups]
+# openapi-python-client is only needed to regenerate the client
+# (scripts/generate.py invokes it via uvx; listed here for local convenience).
+dev = ["openapi-python-client>=0.24,<0.25"]

assistableai-0.1.0/scripts/generate.py

@@ -0,0 +1,74 @@
+#!/usr/bin/env python3
+"""Regenerate the low-level API client from the v3 OpenAPI spec.
+
+Mirrors the TS SDK/CLI's "spec is the source of truth" approach: reads
+``spec/openapi.json`` (repo root) and regenerates ``assistableai._client`` with
+openapi-python-client (attrs + httpx). Also copies the spec into the package as
+data so the MCP server (``assistableai.mcp``) can load it at runtime.
+
+Run from anywhere:  ``python scripts/generate.py``  (or ``uv run python scripts/generate.py``)
+The generated code is committed, like the TS ``src/gen``.
+"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+PKG_ROOT = Path(__file__).resolve().parents[1]  # python/assistableai
+SPEC = PKG_ROOT.parents[1] / "spec" / "openapi.json"  # <repo>/spec/openapi.json
+PACKAGE = PKG_ROOT / "src" / "assistableai"
+GEN_DIR = PACKAGE / "_client"
+SPEC_DATA = PACKAGE / "spec" / "openapi.json"
+
+# Pinned so regeneration is reproducible across machines and CI (Phase 6).
+OPC_VERSION = "0.24.2"
+
+
+def main() -> None:
+    if not SPEC.exists():
+        sys.exit(f"Spec not found at {SPEC} — is this running inside the monorepo?")
+
+    with tempfile.TemporaryDirectory() as tmp:
+        out = Path(tmp) / "_client"
+        # --meta none writes the package contents directly into --output-path,
+        # and the package uses relative imports, so it nests cleanly under
+        # assistableai._client.
+        subprocess.run(
+            [
+                "uvx",
+                f"openapi-python-client@{OPC_VERSION}",
+                "generate",
+                "--path",
+                str(SPEC),
+                "--meta",
+                "none",
+                "--output-path",
+                str(out),
+                "--overwrite",
+            ],
+            check=True,
+        )
+        shutil.rmtree(out / ".ruff_cache", ignore_errors=True)
+
+        if GEN_DIR.exists():
+            shutil.rmtree(GEN_DIR)
+        shutil.copytree(out, GEN_DIR)
+
+    SPEC_DATA.parent.mkdir(parents=True, exist_ok=True)
+    shutil.copyfile(SPEC, SPEC_DATA)
+
+    n_models = len(list((GEN_DIR / "models").glob("*.py")))
+    n_ops = len([p for p in (GEN_DIR / "api").rglob("*.py") if p.name != "__init__.py"])
+    print(
+        f"Generated {GEN_DIR.relative_to(PKG_ROOT)} "
+        f"({n_ops} operations, {n_models} models) and bundled spec at "
+        f"{SPEC_DATA.relative_to(PKG_ROOT)}."
+    )
+
+
+if __name__ == "__main__":
+    main()

assistableai-0.1.0/src/assistableai/__init__.py

@@ -0,0 +1,116 @@
+"""Official Python SDK for the Assistable AI v3 API.
+
+The low-level, typed surface lives under :mod:`assistableai._client` (operation
+functions + attrs models) and is generated from ``spec/openapi.json`` by
+openapi-python-client — do not hand-edit it. This module adds the auth +
+subaccount configuration on top.
+
+Usage::
+
+    import assistableai
+    from assistableai import api
+
+    client = assistableai.configure(api_key="ask_live_…", subaccount_id="…")
+    result = api.assistants.list_assistants.sync(client=client.raw, limit=2)
+    # result is the full {data, error, request_id} envelope (typed model)
+
+(``from assistableai._client.api.assistants import list_assistants`` also works.)
+
+Every operation exposes ``sync`` / ``sync_detailed`` (and ``asyncio`` /
+``asyncio_detailed``); pass ``client=<AssistableAI>.raw``. Per-call subaccount
+overrides are available via each op's ``x_subaccount_id`` argument.
+"""
+
+from __future__ import annotations
+
+import importlib
+import os
+import pkgutil
+
+# Re-export the generated surface so callers can use `assistableai.api.*`,
+# `assistableai.models.*`, etc. without reaching into the private module name.
+from assistableai._client import api, errors, models, types
+from assistableai._client.client import AuthenticatedClient, Client
+
+# Eagerly import the per-topic api submodules (assistants, contacts, …) so that
+# attribute access like `assistableai.api.assistants.list_assistants` works
+# without a separate import. We can't alias these as `assistableai.api.*`
+# submodules in sys.modules because the generated relative imports would then
+# double-load the attrs models under a second dotted name (breaking isinstance).
+for _info in pkgutil.walk_packages(api.__path__, prefix=f"{api.__name__}."):
+    importlib.import_module(_info.name)
+del importlib, pkgutil, _info
+
+__all__ = [
+    "AssistableAI",
+    "AuthenticatedClient",
+    "Client",
+    "configure",
+    "get_client",
+    "DEFAULT_BASE_URL",
+    "api",
+    "models",
+    "errors",
+    "types",
+]
+
+DEFAULT_BASE_URL = "https://api.assistable.ai"
+
+
+class AssistableAI:
+    """A configured v3 client: auth + optional default subaccount.
+
+    Wraps the generated :class:`AuthenticatedClient`, injecting
+    ``Authorization: Bearer <api_key>`` and (when set) ``X-Subaccount-Id`` on
+    every request. Pass :attr:`raw` to the generated operation functions.
+
+    Args resolve from explicit values, then environment
+    (``ASSISTABLE_API_KEY`` / ``ASSISTABLE_SUBACCOUNT_ID`` / ``ASSISTABLE_BASE_URL``).
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        subaccount_id: str | None = None,
+        base_url: str | None = None,
+    ) -> None:
+        api_key = api_key or os.environ.get("ASSISTABLE_API_KEY")
+        if not api_key:
+            raise ValueError(
+                "An API key is required: pass api_key= or set ASSISTABLE_API_KEY."
+            )
+        subaccount_id = subaccount_id or os.environ.get("ASSISTABLE_SUBACCOUNT_ID")
+        base_url = base_url or os.environ.get("ASSISTABLE_BASE_URL") or DEFAULT_BASE_URL
+
+        headers = {"X-Subaccount-Id": subaccount_id} if subaccount_id else {}
+        self.base_url = base_url
+        self.subaccount_id = subaccount_id
+        self._client = AuthenticatedClient(base_url=base_url, token=api_key, headers=headers)
+
+    @property
+    def raw(self) -> AuthenticatedClient:
+        """The underlying generated client to pass to operation functions."""
+        return self._client
+
+
+_default: AssistableAI | None = None
+
+
+def configure(
+    api_key: str | None = None,
+    *,
+    subaccount_id: str | None = None,
+    base_url: str | None = None,
+) -> AssistableAI:
+    """Create and remember a process-global client (see :func:`get_client`)."""
+    global _default
+    _default = AssistableAI(api_key, subaccount_id=subaccount_id, base_url=base_url)
+    return _default
+
+
+def get_client() -> AuthenticatedClient:
+    """Return the raw client configured via :func:`configure` (else raise)."""
+    if _default is None:
+        raise RuntimeError("assistableai is not configured — call assistableai.configure(...) first.")
+    return _default.raw

assistableai-0.1.0/src/assistableai/_client/__init__.py

@@ -0,0 +1,8 @@
+"""A client library for accessing Assistable v3 API"""
+
+from .client import AuthenticatedClient, Client
+
+__all__ = (
+    "AuthenticatedClient",
+    "Client",
+)

assistableai-0.1.0/src/assistableai/_client/api/__init__.py

@@ -0,0 +1 @@
+"""Contains methods for accessing the API"""

assistableai-0.1.0/src/assistableai/_client/api/appointments/__init__.py

@@ -0,0 +1 @@
+"""Contains endpoint functions for accessing the API"""

assistableai-0.1.0/src/assistableai/_client/api/appointments/create_appointment.py

@@ -0,0 +1,204 @@
+from http import HTTPStatus
+from typing import Any, Optional, Union
+
+import httpx
+
+from ... import errors
+from ...client import AuthenticatedClient, Client
+from ...models.api_error import ApiError
+from ...models.create_appointment_body import CreateAppointmentBody
+from ...models.create_appointment_response_201 import CreateAppointmentResponse201
+from ...types import UNSET, Response, Unset
+
+
+def _get_kwargs(
+    *,
+    body: CreateAppointmentBody,
+    x_subaccount_id: Union[Unset, str] = UNSET,
+) -> dict[str, Any]:
+    headers: dict[str, Any] = {}
+    if not isinstance(x_subaccount_id, Unset):
+        headers["X-Subaccount-Id"] = x_subaccount_id
+
+    _kwargs: dict[str, Any] = {
+        "method": "post",
+        "url": "/v3/appointments",
+    }
+
+    _body = body.to_dict()
+
+    _kwargs["json"] = _body
+    headers["Content-Type"] = "application/json"
+
+    _kwargs["headers"] = headers
+    return _kwargs
+
+
+def _parse_response(
+    *, client: Union[AuthenticatedClient, Client], response: httpx.Response
+) -> Optional[Union[ApiError, CreateAppointmentResponse201]]:
+    if response.status_code == 201:
+        response_201 = CreateAppointmentResponse201.from_dict(response.json())
+
+        return response_201
+    if response.status_code == 400:
+        response_400 = ApiError.from_dict(response.json())
+
+        return response_400
+    if response.status_code == 401:
+        response_401 = ApiError.from_dict(response.json())
+
+        return response_401
+    if response.status_code == 403:
+        response_403 = ApiError.from_dict(response.json())
+
+        return response_403
+    if response.status_code == 404:
+        response_404 = ApiError.from_dict(response.json())
+
+        return response_404
+    if response.status_code == 429:
+        response_429 = ApiError.from_dict(response.json())
+
+        return response_429
+    if client.raise_on_unexpected_status:
+        raise errors.UnexpectedStatus(response.status_code, response.content)
+    else:
+        return None
+
+
+def _build_response(
+    *, client: Union[AuthenticatedClient, Client], response: httpx.Response
+) -> Response[Union[ApiError, CreateAppointmentResponse201]]:
+    return Response(
+        status_code=HTTPStatus(response.status_code),
+        content=response.content,
+        headers=response.headers,
+        parsed=_parse_response(client=client, response=response),
+    )
+
+
+def sync_detailed(
+    *,
+    client: AuthenticatedClient,
+    body: CreateAppointmentBody,
+    x_subaccount_id: Union[Unset, str] = UNSET,
+) -> Response[Union[ApiError, CreateAppointmentResponse201]]:
+    """Create an appointment
+
+     Requires scope `appointments:create`.
+
+    Args:
+        x_subaccount_id (Union[Unset, str]):
+        body (CreateAppointmentBody):
+
+    Raises:
+        errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
+        httpx.TimeoutException: If the request takes longer than Client.timeout.
+
+    Returns:
+        Response[Union[ApiError, CreateAppointmentResponse201]]
+    """
+
+    kwargs = _get_kwargs(
+        body=body,
+        x_subaccount_id=x_subaccount_id,
+    )
+
+    response = client.get_httpx_client().request(
+        **kwargs,
+    )
+
+    return _build_response(client=client, response=response)
+
+
+def sync(
+    *,
+    client: AuthenticatedClient,
+    body: CreateAppointmentBody,
+    x_subaccount_id: Union[Unset, str] = UNSET,
+) -> Optional[Union[ApiError, CreateAppointmentResponse201]]:
+    """Create an appointment
+
+     Requires scope `appointments:create`.
+
+    Args:
+        x_subaccount_id (Union[Unset, str]):
+        body (CreateAppointmentBody):
+
+    Raises:
+        errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
+        httpx.TimeoutException: If the request takes longer than Client.timeout.
+
+    Returns:
+        Union[ApiError, CreateAppointmentResponse201]
+    """
+
+    return sync_detailed(
+        client=client,
+        body=body,
+        x_subaccount_id=x_subaccount_id,
+    ).parsed
+
+
+async def asyncio_detailed(
+    *,
+    client: AuthenticatedClient,
+    body: CreateAppointmentBody,
+    x_subaccount_id: Union[Unset, str] = UNSET,
+) -> Response[Union[ApiError, CreateAppointmentResponse201]]:
+    """Create an appointment
+
+     Requires scope `appointments:create`.
+
+    Args:
+        x_subaccount_id (Union[Unset, str]):
+        body (CreateAppointmentBody):
+
+    Raises:
+        errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
+        httpx.TimeoutException: If the request takes longer than Client.timeout.
+
+    Returns:
+        Response[Union[ApiError, CreateAppointmentResponse201]]
+    """
+
+    kwargs = _get_kwargs(
+        body=body,
+        x_subaccount_id=x_subaccount_id,
+    )
+
+    response = await client.get_async_httpx_client().request(**kwargs)
+
+    return _build_response(client=client, response=response)
+
+
+async def asyncio(
+    *,
+    client: AuthenticatedClient,
+    body: CreateAppointmentBody,
+    x_subaccount_id: Union[Unset, str] = UNSET,
+) -> Optional[Union[ApiError, CreateAppointmentResponse201]]:
+    """Create an appointment
+
+     Requires scope `appointments:create`.
+
+    Args:
+        x_subaccount_id (Union[Unset, str]):
+        body (CreateAppointmentBody):
+
+    Raises:
+        errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
+        httpx.TimeoutException: If the request takes longer than Client.timeout.
+
+    Returns:
+        Union[ApiError, CreateAppointmentResponse201]
+    """
+
+    return (
+        await asyncio_detailed(
+            client=client,
+            body=body,
+            x_subaccount_id=x_subaccount_id,
+        )
+    ).parsed