audiokit-ai 0.1.0__tar.gz

audiokit_ai-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+node_modules/
+.venv/
+**/dist/
+**/__pycache__/
+.mypy_cache/
+**/*.tgz

audiokit_ai-0.1.0/PKG-INFO

@@ -0,0 +1,45 @@
+Metadata-Version: 2.4
+Name: audiokit-ai
+Version: 0.1.0
+Summary: Generated Python client and webhook verification for the AudioKit API
+Project-URL: Homepage, https://audiokit.ai/docs/sdks/
+Project-URL: Repository, https://github.com/epsilon-records/audiokit
+License-Expression: LicenseRef-Proprietary
+Requires-Python: >=3.11
+Requires-Dist: httpx<1,>=0.28.1
+Requires-Dist: typing-extensions<5,>=4.13
+Description-Content-Type: text/markdown
+
+# AudioKit for Python
+
+Generated from AudioKit's OpenAPI contract; includes raw-body webhook verification. Python 3.11+.
+
+**0.1.0 release candidate — not yet on PyPI.** After publication, install with pip install audiokit-ai. For local testing, install the wheel built from this directory.
+
+```python
+import os
+from audiokit_ai import AudioKit, ApiError, verify_webhook
+from audiokit_ai.models import JobRequest
+
+with AudioKit(api_key=os.environ['AUDIOKIT_API_KEY']) as client:
+    request: JobRequest = {
+        'job_id': 'my-first-job',
+        'operation': 'probe',
+        'input': {'url': signed_input_url, 'sha256': input_sha256},
+        'webhook': {'url': 'https://example.com/audiokit/webhook'},
+    }
+    job = client.submit_job(request)
+    status = client.get_job(job['provider_job_id'])
+
+# In a webhook handler, before parsing JSON:
+if not verify_webhook(raw_body, signature_header, webhook_secret):
+    # Return 401. Do not use the event.
+    raise ValueError('Invalid webhook signature')
+# After verification, parse the body and deduplicate event_id.
+```
+
+Set base_url for another API instance. Methods include get_health, get_capabilities, get_open_api, submit_job, get_job and cancel_job. Generated models are TypedDicts, so requests and responses are ordinary dictionaries. Use the context manager or call close() to release connections.
+
+HTTP failures raise ApiError with status and code. Network failures are native httpx exceptions. Unknown API codes are preserved; treat unfamiliar ones as internal failures. There are no automatic retries or redirects; requests have a 30-second timeout. The verifier takes raw bytes and returns a boolean with a 300-second tolerance in both time directions. Its optional now argument is Unix seconds for deterministic tests. It does not deduplicate events.
+
+[API documentation](https://audiokit.ai/docs/) · [SDK guide](https://audiokit.ai/docs/sdks/)

audiokit_ai-0.1.0/README.md

@@ -0,0 +1,33 @@
+# AudioKit for Python
+
+Generated from AudioKit's OpenAPI contract; includes raw-body webhook verification. Python 3.11+.
+
+**0.1.0 release candidate — not yet on PyPI.** After publication, install with pip install audiokit-ai. For local testing, install the wheel built from this directory.
+
+```python
+import os
+from audiokit_ai import AudioKit, ApiError, verify_webhook
+from audiokit_ai.models import JobRequest
+
+with AudioKit(api_key=os.environ['AUDIOKIT_API_KEY']) as client:
+    request: JobRequest = {
+        'job_id': 'my-first-job',
+        'operation': 'probe',
+        'input': {'url': signed_input_url, 'sha256': input_sha256},
+        'webhook': {'url': 'https://example.com/audiokit/webhook'},
+    }
+    job = client.submit_job(request)
+    status = client.get_job(job['provider_job_id'])
+
+# In a webhook handler, before parsing JSON:
+if not verify_webhook(raw_body, signature_header, webhook_secret):
+    # Return 401. Do not use the event.
+    raise ValueError('Invalid webhook signature')
+# After verification, parse the body and deduplicate event_id.
+```
+
+Set base_url for another API instance. Methods include get_health, get_capabilities, get_open_api, submit_job, get_job and cancel_job. Generated models are TypedDicts, so requests and responses are ordinary dictionaries. Use the context manager or call close() to release connections.
+
+HTTP failures raise ApiError with status and code. Network failures are native httpx exceptions. Unknown API codes are preserved; treat unfamiliar ones as internal failures. There are no automatic retries or redirects; requests have a 30-second timeout. The verifier takes raw bytes and returns a boolean with a 300-second tolerance in both time directions. Its optional now argument is Unix seconds for deterministic tests. It does not deduplicate events.
+
+[API documentation](https://audiokit.ai/docs/) · [SDK guide](https://audiokit.ai/docs/sdks/)

audiokit_ai-0.1.0/pyproject.toml

@@ -0,0 +1,19 @@
+[build-system]
+requires = ["hatchling==1.27.0"]
+build-backend = "hatchling.build"
+
+[project]
+name = "audiokit-ai"
+version = "0.1.0"
+description = "Generated Python client and webhook verification for the AudioKit API"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "LicenseRef-Proprietary"
+dependencies = ["httpx>=0.28.1,<1", "typing-extensions>=4.13,<5"]
+
+[project.urls]
+Homepage = "https://audiokit.ai/docs/sdks/"
+Repository = "https://github.com/epsilon-records/audiokit"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/audiokit_ai"]

audiokit_ai-0.1.0/src/audiokit_ai/__init__.py

@@ -0,0 +1,7 @@
+"""AudioKit API client and raw-body webhook verification."""
+
+from .client import AudioKit
+from .transport import ApiError
+from .webhook import verify_webhook
+
+__all__ = ["AudioKit", "ApiError", "verify_webhook"]

audiokit_ai-0.1.0/src/audiokit_ai/client.py

@@ -0,0 +1,32 @@
+# Generated from openapi.yaml by sdks/generate.mjs. Do not edit.
+from urllib.parse import quote
+from typing import cast
+
+from . import models
+from .transport import Transport
+
+
+class AudioKit(Transport):
+    def get_health(self) -> models.Health:
+        """Liveness and version."""
+        return cast(models.Health, self._request("GET", "/v1/health", None, False, True))
+
+    def get_capabilities(self) -> models.Capabilities:
+        """Operations that work end to end on this instance."""
+        return cast(models.Capabilities, self._request("GET", "/v1/capabilities", None, False, True))
+
+    def get_open_api(self) -> str:
+        """This contract."""
+        return cast(str, self._request("GET", "/v1/openapi.yaml", None, False, False))
+
+    def submit_job(self, body: models.JobRequest) -> models.Job:
+        """Submit a job."""
+        return cast(models.Job, self._request("POST", "/v1/jobs", body, True, True))
+
+    def get_job(self, provider_job_id: str) -> models.Job:
+        """Job status and result."""
+        return cast(models.Job, self._request("GET", f"/v1/jobs/{quote(provider_job_id, safe='')}", None, True, True))
+
+    def cancel_job(self, provider_job_id: str) -> models.Job:
+        """Cancel a job."""
+        return cast(models.Job, self._request("POST", f"/v1/jobs/{quote(provider_job_id, safe='')}/cancel", None, True, True))

audiokit_ai-0.1.0/src/audiokit_ai/models.py

@@ -0,0 +1,449 @@
+# generated by datamodel-codegen:
+#   filename:  openapi.yaml
+
+from __future__ import annotations
+
+from typing import Any, Literal, NotRequired, TypedDict
+
+from typing_extensions import TypeAliasType
+
+
+class Health(TypedDict):
+    status: Literal['ok']
+    version: str
+
+
+ApiErrorCode = TypeAliasType(
+    "ApiErrorCode",
+    Literal[
+        'invalid_request',
+        'operation_unavailable',
+        'unauthorized',
+        'not_found',
+        'idempotency_conflict',
+        'client_bootstrap',
+        'rate_limited',
+        'unavailable',
+    ]
+    | str,
+)
+
+
+class ClientUpsert(TypedDict):
+    id: str
+    api_key_sha256: str
+    webhook_secret: str
+
+
+JobErrorCode = TypeAliasType(
+    "JobErrorCode",
+    Literal[
+        'input_url_rejected',
+        'input_unreachable',
+        'input_too_large',
+        'input_hash_mismatch',
+        'unsupported_format',
+        'unsupported_codec',
+        'corrupt_input',
+        'invalid_params',
+        'operation_unavailable',
+        'encode_failed',
+        'output_url_rejected',
+        'output_upload_failed',
+        'stems_unavailable',
+        'stems_failed',
+        'timeout',
+        'canceled',
+        'internal',
+    ]
+    | str,
+)
+
+
+class JobError(TypedDict):
+    code: JobErrorCode
+    message: str
+
+
+Operation = TypeAliasType(
+    "Operation",
+    Literal[
+        'probe',
+        'loudness',
+        'waveform',
+        'transcode',
+        'preview',
+        'normalize',
+        'tempo',
+        'key',
+        'fingerprint',
+        'analyze',
+        'tags',
+        'stems',
+    ],
+)
+
+
+OutputName = TypeAliasType(
+    "OutputName", Literal['audio', 'vocals', 'drums', 'bass', 'other']
+)
+
+
+Sha256 = TypeAliasType("Sha256", str)
+
+
+HttpsUrl = TypeAliasType("HttpsUrl", str)
+
+
+class InputFile(TypedDict):
+    url: HttpsUrl
+    sha256: Sha256
+    filename: NotRequired[str]
+
+
+class OutputTarget(TypedDict):
+    url: HttpsUrl
+    headers: NotRequired[dict[str, str]]
+
+
+class WebhookTarget(TypedDict):
+    url: HttpsUrl
+
+
+class AuthorizationRef(TypedDict):
+    decision_id: str
+    purpose: NotRequired[str]
+
+
+class NoParams(TypedDict):
+    pass
+
+
+class WaveformParams(TypedDict):
+    points: NotRequired[int]
+
+
+class TempoParams(TypedDict):
+    min_bpm: NotRequired[float]
+    max_bpm: NotRequired[float]
+
+
+class TagsParams(TypedDict):
+    embedding: NotRequired[bool]
+
+
+StemsModel = TypeAliasType("StemsModel", Literal['htdemucs_ft', 'htdemucs'])
+
+
+class StemsParams(TypedDict):
+    model: NotRequired[StemsModel]
+
+
+Format = TypeAliasType("Format", Literal['wav', 'flac', 'mp3', 'aac'])
+
+
+SampleRate = TypeAliasType(
+    "SampleRate", Literal[22050, 24000, 32000, 44100, 48000, 96000]
+)
+
+
+class TranscodeParams(TypedDict):
+    format: Format
+    sample_rate: NotRequired[SampleRate]
+    channels: NotRequired[Literal[1, 2]]
+    bit_depth: NotRequired[Literal[16, 24]]
+    bitrate_kbps: NotRequired[int]
+
+
+class PreviewParams(TypedDict):
+    start_seconds: NotRequired[float]
+    duration_seconds: NotRequired[float]
+    fade_seconds: NotRequired[float]
+    format: NotRequired[Format]
+    bitrate_kbps: NotRequired[int]
+
+
+class NormalizeParams(TypedDict):
+    target_lufs: float
+    true_peak_dbtp: NotRequired[float]
+    format: NotRequired[Format]
+    sample_rate: NotRequired[SampleRate]
+    channels: NotRequired[Literal[1, 2]]
+    bit_depth: NotRequired[Literal[16, 24]]
+    bitrate_kbps: NotRequired[int]
+
+
+JobStatus = TypeAliasType(
+    "JobStatus", Literal['queued', 'running', 'succeeded', 'failed', 'canceled']
+)
+
+
+class Provenance(TypedDict):
+    input_sha256: Sha256
+    audiokit_version: str
+    operation: Operation
+    params: dict[str, Any]
+
+
+Decibels = TypeAliasType("Decibels", float | None)
+
+
+class ProbeResult(TypedDict):
+    container: str
+    codec: str
+    sample_rate: int
+    channels: int
+    bits_per_sample: int | None
+    frames: int
+    duration_seconds: float
+    size_bytes: int
+    decode_errors: int
+    valid: bool
+
+
+class StreamFields(TypedDict):
+    sample_rate: int
+    channels: int
+    duration_seconds: float
+
+
+class LoudnessFields(TypedDict):
+    integrated_lufs: Decibels | None
+    loudness_range_lu: Decibels | None
+    true_peak_dbtp: Decibels | None
+    sample_peak_dbfs: Decibels | None
+
+
+class LoudnessResult(LoudnessFields, StreamFields):
+    pass
+
+
+class TempoFields(TypedDict):
+    bpm: float | None
+    confidence: float | None
+    steady: bool
+    beat_count: int
+    beats: list[float]
+
+
+class TempoResult(TempoFields, StreamFields):
+    pass
+
+
+KeyName = TypeAliasType("KeyName", str)
+
+
+Camelot = TypeAliasType("Camelot", str)
+
+
+class Candidate(TypedDict):
+    key: KeyName
+    camelot: Camelot
+    score: float
+
+
+class KeyFields(TypedDict):
+    key: KeyName | None
+    tonic: (
+        Literal['C', 'C#', 'D', 'Eb', 'E', 'F', 'F#', 'G', 'Ab', 'A', 'Bb', 'B'] | None
+    )
+    mode: Literal['major', 'minor'] | None
+    camelot: Camelot | None
+    confidence: float | None
+    tuning_cents: float | None
+    candidates: list[Candidate]
+    chroma: list[float] | None
+
+
+class KeyResult(KeyFields, StreamFields):
+    pass
+
+
+class FingerprintFields(TypedDict):
+    fingerprint: str | None
+    algorithm: Literal['chromaprint-2']
+    fingerprint_seconds: float
+
+
+class FingerprintResult(FingerprintFields, StreamFields):
+    pass
+
+
+class TagScore(TypedDict):
+    tag: str
+    score: float
+
+
+class TagsFields(TypedDict):
+    model: str
+    windows: int
+    embedding: NotRequired[list[float]]
+
+
+class TagsResult(TypedDict):
+    model: str
+    windows: int
+    embedding: NotRequired[list[float]]
+    sample_rate: int
+    channels: int
+    duration_seconds: float
+
+
+class WaveformResult(TypedDict):
+    points: int
+    peaks: list[float]
+    sample_rate: int
+    channels: int
+    duration_seconds: float
+
+
+class AudioOutputFields1(TypedDict):
+    format: Format
+    content_type: Literal['audio/wav', 'audio/flac', 'audio/mpeg', 'audio/mp4']
+    sample_rate: int
+    channels: int
+    duration_seconds: float
+    bit_depth: int
+    bitrate_kbps: NotRequired[int]
+    sha256: Sha256
+    size_bytes: int
+
+
+class AudioOutputFields2(TypedDict):
+    format: Format
+    content_type: Literal['audio/wav', 'audio/flac', 'audio/mpeg', 'audio/mp4']
+    sample_rate: int
+    channels: int
+    duration_seconds: float
+    bit_depth: NotRequired[int]
+    bitrate_kbps: int
+    sha256: Sha256
+    size_bytes: int
+
+
+AudioOutputFields = TypeAliasType(
+    "AudioOutputFields", AudioOutputFields1 | AudioOutputFields2
+)
+
+
+class AudioOutput(TypedDict):
+    pass
+
+
+class PreviewAudioOutput(TypedDict):
+    start_seconds: float
+    fade_seconds: float
+
+
+class Outputs(TypedDict):
+    audio: AudioOutput
+
+
+class TranscodeResult(TypedDict):
+    outputs: Outputs
+
+
+class Outputs1(TypedDict):
+    audio: PreviewAudioOutput
+
+
+class PreviewResult(TypedDict):
+    outputs: Outputs1
+
+
+class Outputs2(TypedDict):
+    audio: AudioOutput
+
+
+class NormalizeResult(TypedDict):
+    target_lufs: float
+    true_peak_ceiling_dbtp: float
+    target_reached: bool
+    gain_db: float
+    before: LoudnessFields
+    after: LoudnessFields
+    outputs: Outputs2
+
+
+class StemOutput(TypedDict):
+    sha256: Sha256
+    size_bytes: int
+    format: NotRequired[str]
+    content_type: NotRequired[str]
+    sample_rate: NotRequired[int]
+    channels: NotRequired[int]
+    duration_seconds: NotRequired[float]
+
+
+class Outputs3(TypedDict):
+    vocals: StemOutput
+    drums: StemOutput
+    bass: StemOutput
+    other: StemOutput
+
+
+class StemsResult(TypedDict):
+    model: StemsModel
+    outputs: Outputs3
+
+
+Capability = TypedDict(
+    'Capability',
+    {
+        'operation': Operation,
+        'outputs': list[OutputName],
+        'async': bool,
+        'requires_consent': bool,
+    },
+)
+
+
+class Error1(TypedDict):
+    code: ApiErrorCode
+    message: str
+
+
+class Error(TypedDict):
+    error: Error1
+
+
+class JobRequest(TypedDict):
+    job_id: str
+    operation: Operation
+    input: InputFile
+    params: NotRequired[dict[str, Any] | None]
+    outputs: NotRequired[dict[str, OutputTarget]]
+    webhook: NotRequired[WebhookTarget]
+    authorization: NotRequired[AuthorizationRef]
+
+
+class Job(TypedDict):
+    provider_job_id: str
+    job_id: str
+    operation: Operation
+    status: JobStatus
+    result: NotRequired[dict[str, Any]]
+    error: NotRequired[JobError]
+    provenance: NotRequired[Provenance]
+    created_at: str
+    started_at: NotRequired[str]
+    finished_at: NotRequired[str]
+
+
+class WebhookEvent(TypedDict):
+    event_id: str
+    type: Literal['job.succeeded', 'job.failed', 'job.canceled']
+    created_at: str
+    data: Job
+
+
+class AnalyzeResult(StreamFields):
+    loudness: LoudnessFields
+    tempo: TempoFields
+    key: KeyFields
+    fingerprint: FingerprintFields
+    tags: NotRequired[TagsFields | None]
+
+
+class Capabilities(TypedDict):
+    operations: list[Capability]

audiokit_ai-0.1.0/src/audiokit_ai/transport.py

@@ -0,0 +1,49 @@
+"""HTTP transport. No retries or redirects; HTTP errors preserve API codes."""
+from __future__ import annotations
+
+from types import TracebackType
+from typing import Any, Self
+
+import httpx
+
+
+class ApiError(Exception):
+    def __init__(self, status: int, code: str, message: str) -> None:
+        super().__init__(message)
+        self.status = status
+        self.code = code
+
+
+class Transport:
+    def __init__(self, api_key: str, base_url: str = "https://api.audiokit.ai") -> None:
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._client = httpx.Client(timeout=30, follow_redirects=False)
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(self, exc_type: type[BaseException] | None, exc: BaseException | None,
+                 traceback: TracebackType | None) -> None:
+        self.close()
+
+    def _request(self, method: str, path: str, body: Any, auth: bool, json: bool) -> Any:
+        headers = {"Accept": "application/json" if json else "application/yaml"}
+        if auth:
+            headers["Authorization"] = f"Bearer {self._api_key}"
+        response = self._client.request(method, self._base_url + path, headers=headers, json=body)
+        if not response.is_success:
+            try:
+                payload = response.json()
+            except ValueError:
+                payload = None
+            error = payload.get("error") if isinstance(payload, dict) else None
+            error = error if isinstance(error, dict) else {}
+            code = error.get("code")
+            message = error.get("message")
+            raise ApiError(response.status_code, code if isinstance(code, str) else "internal",
+                           message if isinstance(message, str) else f"HTTP {response.status_code}")
+        return response.json() if json else response.text

audiokit_ai-0.1.0/src/audiokit_ai/webhook.py

@@ -0,0 +1,22 @@
+"""Verify the existing AudioKit v1 signature using Python's HMAC primitives."""
+import hashlib
+import hmac
+import math
+import re
+import time
+
+
+def verify_webhook(raw_body: bytes, signature: str | None, secret: str,
+                   now: float | None = None) -> bool:
+    """Check raw bytes before JSON parsing; deduplicate event_id separately."""
+    if not signature:
+        return False
+    match = re.fullmatch(r"t=([0-9]{1,16}),v1=([0-9a-f]{64})", signature)
+    if not match:
+        return False
+    timestamp = int(match[1])
+    current = time.time() if now is None else now
+    if timestamp > 9007199254740991 or not math.isfinite(current) or abs(current - timestamp) > 300:
+        return False
+    expected = hmac.new(secret.encode(), str(timestamp).encode() + b"." + raw_body, hashlib.sha256).digest()
+    return hmac.compare_digest(expected, bytes.fromhex(match[2]))

audiokit_ai-0.1.0/test/test_sdk.py

@@ -0,0 +1,71 @@
+import json
+from pathlib import Path
+import unittest
+
+import httpx
+
+from audiokit_ai import AudioKit, ApiError, verify_webhook
+
+VECTOR = json.loads((Path(__file__).parents[2] / "signature-vector.json").read_text())
+NOW = int(VECTOR["header"].split(",")[0][2:])
+
+
+class SdkTests(unittest.TestCase):
+    def test_signatures(self):
+        body = VECTOR["body"].encode()
+        header, secret = VECTOR["header"], VECTOR["secret"]
+        for delta in [0, -300, 300]:
+            self.assertTrue(verify_webhook(body, header, secret, NOW + delta))
+        for delta in [-301, 301]:
+            self.assertFalse(verify_webhook(body, header, secret, NOW + delta))
+        self.assertFalse(verify_webhook(body + b" ", header, secret, NOW))
+        self.assertFalse(verify_webhook(body, header, "wrong", NOW))
+        self.assertFalse(verify_webhook(body, header, secret, float("nan")))
+        for bad in [None, "", "garbage", "t=1,v1=abcd", header + "\n", header + ",t=1",
+                    header.replace("t=", "t=-"), header.replace("1793440800", "9" * 300),
+                    header.replace("27d3", "zzzz")]:
+            self.assertFalse(verify_webhook(body, bad, secret, NOW), bad)
+
+    def test_transport(self):
+        seen = []
+        def handle(req):
+            seen.append(req)
+            path = req.url.path
+            if path.endswith("/conflict"):
+                return httpx.Response(409, json={"error": {"code": "idempotency_conflict", "message": "Different request"}})
+            if path.endswith("/unknown"):
+                return httpx.Response(429, json={"error": {"code": "future_code", "message": "Limited"}})
+            if path.endswith("/gateway"):
+                return httpx.Response(502, text="Bad gateway")
+            if path.endswith("/redirect"):
+                return httpx.Response(307, headers={"Location": "/v1/jobs/leaked"})
+            if path.endswith("openapi.yaml"):
+                return httpx.Response(200, text="openapi: 3.1.0")
+            return httpx.Response(200, json={"provider_job_id": "id", "job_id": "sdk-test"})
+        with AudioKit("test-key", "https://example.com/") as client:
+            client._client.close()
+            client._client = httpx.Client(transport=httpx.MockTransport(handle))
+            client.submit_job({"job_id": "sdk-test", "operation": "probe", "input": {"url": "https://example.com/test.wav", "sha256": "a" * 64}})
+            self.assertEqual(seen[-1].headers["Authorization"], "Bearer test-key")
+            self.assertEqual(seen[-1].method, "POST")
+            self.assertEqual(json.loads(seen[-1].content)["job_id"], "sdk-test")
+            client.get_job("a/b?c")
+            self.assertEqual(seen[-1].url.raw_path, b"/v1/jobs/a%2Fb%3Fc")
+            client.cancel_job("id")
+            self.assertEqual(seen[-1].url.path, "/v1/jobs/id/cancel")
+            self.assertEqual(seen[-1].method, "POST")
+            for method in [client.get_health, client.get_capabilities, client.get_open_api]:
+                method()
+                self.assertNotIn("Authorization", seen[-1].headers)
+            self.assertEqual(client.get_open_api(), "openapi: 3.1.0")
+            for name, status, code in [("conflict", 409, "idempotency_conflict"), ("unknown", 429, "future_code"), ("gateway", 502, "internal"), ("redirect", 307, "internal")]:
+                before = len(seen)
+                with self.assertRaises(ApiError) as error:
+                    client.get_job(name)
+                self.assertEqual(error.exception.status, status)
+                self.assertEqual(error.exception.code, code)
+                self.assertEqual(len(seen), before + 1)
+
+
+if __name__ == "__main__":
+    unittest.main()