audacity-sdk 0.1.0__py3-none-any.whl

audacity/__init__.py

@@ -0,0 +1,20 @@
+"""
+audacity — Audacity Investments AI SDK (Python).
+
+Usage::
+
+    from audacity import Audacity
+
+    client = Audacity(api_key="audacity_api_…")
+    response = client.converse(
+        modelId="gpt-5.4-mini",
+        messages=[{"role": "user", "content": [{"text": "Hi"}]}],
+    )
+    print(response["output"]["message"]["content"][0]["text"])
+"""
+from __future__ import annotations
+
+from ._client import Audacity
+from ._version import __version__
+
+__all__ = ["Audacity", "__version__"]

audacity/_client.py

@@ -0,0 +1,256 @@
+"""
+Audacity SDK client.
+
+Public surface (spec §2):
+  from audacity import Audacity
+
+  client = Audacity(api_key=None, base_url=None, timeout=120.0, max_retries=2)
+  response = client.converse(**kwargs)        # returns dict
+  stream   = client.converse_stream(**kwargs) # returns {"stream": generator}
+"""
+from __future__ import annotations
+
+import http.client
+import json
+import os
+import random
+import socket
+import ssl
+import time
+import urllib.parse
+from typing import Any, Dict, Optional, Tuple
+
+from .exceptions import (
+    AudacityError,
+    MissingApiKeyError,
+    SdkError,
+    _ExceptionsNamespace,
+    parse_error_response,
+)
+from ._mapping import build_request_body, map_converse_response
+from ._sse import iter_stream_events
+from ._version import __version__ as _VERSION
+
+
+_DEFAULT_BASE_URL = "https://portal.audacityinvestments.com"
+_DEFAULT_TIMEOUT = 120.0
+_DEFAULT_MAX_RETRIES = 2
+_USER_AGENT = "audacity-sdk-python/" + _VERSION
+
+# HTTP status codes on which we retry (unless the specific error code overrides)
+_RETRY_STATUSES = frozenset({408, 429, 500, 502, 503, 504})
+
+# Network exception types we treat as transient
+_NETWORK_ERRORS = (OSError, socket.timeout, http.client.HTTPException)
+
+
+def _should_retry(exc: BaseException) -> bool:
+    """Return True if this exception warrants a retry attempt.
+
+    Every AudacityError carries a ``retryable`` attribute; for SdkError it is
+    per-instance (network failures retryable, decode failures not — spec §4).
+    """
+    if isinstance(exc, AudacityError):
+        return bool(getattr(exc, "retryable", False))
+    return False
+
+
+def _backoff_seconds(attempt: int, exc: Optional[BaseException]) -> float:
+    """
+    Compute sleep duration for retry *attempt* (1-based).
+
+    Formula: min(20, 0.5 * 2^attempt) with full jitter.
+    If the exception carries retry_after_seconds, use max(that, jittered).
+    """
+    cap = min(20.0, 0.5 * (2 ** attempt))
+    jittered = random.uniform(0.0, cap)
+
+    retry_after: Optional[float] = getattr(exc, "retry_after_seconds", None)
+    if retry_after is not None:
+        return max(float(retry_after), jittered)
+    return jittered
+
+
+class Audacity:
+    """
+    Audacity Investments LLM gateway client.
+
+    Constructor parameters
+    ----------------------
+    api_key      : str | None
+        API key (``audacity_api_…``).  Falls back to ``AUDACITY_API_KEY`` env var.
+    base_url     : str | None
+        Override gateway URL.  Falls back to ``AUDACITY_BASE_URL`` env var, then
+        ``https://portal.audacityinvestments.com``.
+    timeout      : float
+        Per-socket-operation timeout in seconds (default 120): each connect,
+        write, and read must complete within this window.  For ``converse``
+        this bounds every step of the request; for ``converse_stream`` it acts
+        as an idle timeout between stream reads and never bounds the total
+        stream duration (spec §1).
+    max_retries  : int
+        Maximum number of retry attempts after a transient failure (default 2,
+        so up to 3 total attempts).
+
+    Attributes
+    ----------
+    exceptions : _ExceptionsNamespace
+        boto3-parity namespace giving attribute access to all exception classes,
+        e.g. ``client.exceptions.ThrottlingException``.
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        timeout: float = _DEFAULT_TIMEOUT,
+        max_retries: int = _DEFAULT_MAX_RETRIES,
+    ) -> None:
+        resolved_key = api_key or os.environ.get("AUDACITY_API_KEY")
+        if not resolved_key:
+            raise MissingApiKeyError()
+        self._api_key = resolved_key
+
+        self._base_url = (
+            (base_url or os.environ.get("AUDACITY_BASE_URL") or _DEFAULT_BASE_URL)
+            .rstrip("/")
+        )
+        self._timeout = float(timeout)
+        self._max_retries = int(max_retries)
+
+        parsed = urllib.parse.urlparse(self._base_url)
+        self._scheme = parsed.scheme
+        self._host = parsed.netloc
+        # Path prefix for the request path
+        self._path_prefix = parsed.path.rstrip("/")
+
+        self._ssl_context: Optional[ssl.SSLContext] = (
+            ssl.create_default_context() if self._scheme == "https" else None
+        )
+
+        self.exceptions = _ExceptionsNamespace()
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def converse(self, **kwargs: Any) -> Dict[str, Any]:
+        """
+        Non-streaming inference (Bedrock Converse parity).
+
+        Returns a dict with keys: output, stopReason, usage, metrics.
+        """
+        body = build_request_body(kwargs, stream=False)
+        headers = self._make_headers(stream=False)
+        body_bytes = json.dumps(body).encode("utf-8")
+
+        raw, _, start_time = self._request_with_retries(body_bytes, headers, stream=False)
+        return map_converse_response(raw, start_time)
+
+    def converse_stream(self, **kwargs: Any) -> Dict[str, Any]:
+        """
+        Streaming inference (Bedrock ConverseStream parity).
+
+        Returns ``{"stream": <generator of event dicts>}``.
+        Iterate ``response["stream"]`` to receive events.
+
+        Retries apply only until the HTTP 200 response is received.
+        Once the first SSE byte is consumed the generator owns the connection;
+        mid-stream failures surface as ``ModelStreamErrorException``.
+        """
+        body = build_request_body(kwargs, stream=True)
+        headers = self._make_headers(stream=True)
+        body_bytes = json.dumps(body).encode("utf-8")
+
+        response, conn, start_time = self._request_with_retries(body_bytes, headers, stream=True)
+        # Ownership of conn + response passes to the generator
+        return {"stream": iter_stream_events(response, conn, start_time)}
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _request_with_retries(
+        self,
+        body_bytes: bytes,
+        headers: Dict[str, str],
+        stream: bool,
+    ) -> Tuple[Any, Optional[http.client.HTTPConnection], float]:
+        """
+        POST the request, applying the retry policy (spec §4): up to
+        ``max_retries`` retries on network errors and retryable HTTP errors,
+        with capped exponential backoff, full jitter, and Retry-After support.
+
+        Returns a tuple for the successful (HTTP 200) attempt:
+          stream=False → ``(raw_body_bytes, None, start_time)`` — body fully
+            read, connection closed.
+          stream=True  → ``(open_response, open_connection, start_time)`` —
+            no body bytes consumed; the caller takes ownership of both.
+
+        Raises the mapped AudacityError (or SdkError for network failures)
+        once retries are exhausted or the error is not retryable.
+        """
+        path = self._path_prefix + "/v1/chat/completions"
+
+        last_exc: Optional[BaseException] = None
+        for attempt in range(self._max_retries + 1):
+            if attempt > 0:
+                time.sleep(_backoff_seconds(attempt, last_exc))
+
+            start_time = time.time()
+            conn = self._new_connection()
+            handed_off = False
+            try:
+                conn.request("POST", path, body_bytes, headers)
+                response = conn.getresponse()
+                status = response.status
+                if status == 200 and stream:
+                    # Hand off ownership of conn + response to the caller
+                    handed_off = True
+                    return response, conn, start_time
+                raw = response.read()
+            except _NETWORK_ERRORS as e:
+                exc = SdkError(str(e), cause=e)
+                if attempt < self._max_retries:
+                    last_exc = exc
+                    continue
+                raise exc from e
+            finally:
+                if not handed_off:
+                    conn.close()
+
+            if status == 200:
+                return raw, None, start_time
+
+            # Parse the error
+            retry_after_hdr = response.headers.get("Retry-After") if response.headers else None
+            exc = parse_error_response(status, raw, retry_after_hdr)
+            if attempt < self._max_retries and _should_retry(exc):
+                last_exc = exc
+                continue
+            raise exc
+
+        # Should not reach here, but make the type-checker happy
+        if last_exc is not None:
+            raise last_exc
+        raise SdkError("Exhausted retries")  # pragma: no cover
+
+    def _new_connection(self) -> http.client.HTTPConnection:
+        if self._scheme == "https":
+            return http.client.HTTPSConnection(
+                self._host,
+                timeout=self._timeout,
+                context=self._ssl_context,
+            )
+        return http.client.HTTPConnection(
+            self._host,
+            timeout=self._timeout,
+        )
+
+    def _make_headers(self, stream: bool) -> Dict[str, str]:
+        return {
+            "Authorization": "Bearer " + self._api_key,
+            "Content-Type": "application/json",
+            "Accept": "text/event-stream" if stream else "application/json",
+            "User-Agent": _USER_AGENT,
+        }

audacity/_mapping.py

@@ -0,0 +1,346 @@
+"""
+Request/response mapping — spec §3 (normative).
+
+Transforms between Bedrock-shaped dicts and OpenAI wire format.
+"""
+from __future__ import annotations
+
+import base64
+import json
+import time
+from typing import Any, Dict, List, Optional
+
+from .exceptions import SdkError, ValidationException
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _map_finish_reason(finish_reason: Optional[str]) -> str:
+    """Map OpenAI finish_reason to Bedrock stopReason."""
+    if finish_reason == "stop":
+        return "end_turn"
+    if finish_reason == "length":
+        return "max_tokens"
+    if finish_reason in ("tool_calls", "function_call"):
+        return "tool_use"
+    if finish_reason == "content_filter":
+        return "content_filtered"
+    return "end_turn"
+
+
+def _map_usage(usage: Optional[Dict[str, Any]]) -> Dict[str, Any]:
+    """Map an OpenAI usage object to the Bedrock usage shape."""
+    usage = usage or {}
+    return {
+        "inputTokens":  usage.get("prompt_tokens", 0),
+        "outputTokens": usage.get("completion_tokens", 0),
+        "totalTokens":  usage.get("total_tokens", 0),
+    }
+
+
+def _toolresult_content_text(content_list: List[Dict[str, Any]]) -> str:
+    """Flatten toolResult content blocks into a single string."""
+    parts: List[str] = []
+    for block in content_list:
+        if "text" in block:
+            parts.append(block["text"])
+        elif "json" in block:
+            parts.append(json.dumps(block["json"]))
+    return "".join(parts)
+
+
+def _image_block_to_part(image: Dict[str, Any]) -> Dict[str, Any]:
+    """
+    Map a Bedrock-style image block to an OpenAI image_url content part (spec §3).
+
+    source.url is passed through verbatim; source.bytes is base64-encoded into a
+    data URL. A str passed as bytes is treated as already-base64 (not re-encoded).
+    """
+    fmt = image.get("format", "png")
+    source = image.get("source", {})
+
+    if "url" in source:
+        url = source["url"]
+    else:
+        data = source.get("bytes", b"")
+        if isinstance(data, str):
+            b64 = data
+        else:
+            b64 = base64.b64encode(bytes(data)).decode("ascii")
+        url = f"data:image/{fmt};base64,{b64}"
+
+    return {"type": "image_url", "image_url": {"url": url}}
+
+
+# ---------------------------------------------------------------------------
+# Converse input → OpenAI request body (spec §3)
+# ---------------------------------------------------------------------------
+
+def _build_openai_messages(
+    canonical_messages: List[Dict[str, Any]],
+    system: Optional[List[Dict[str, Any]]],
+) -> List[Dict[str, Any]]:
+    """
+    Convert Bedrock-shaped messages + system prompt to an OpenAI messages list.
+
+    Mapping rules (spec §3 steps 2–3):
+    - system blocks: join all .text with "\\n\\n" → single leading system message.
+    - user turn:
+        toolResult blocks → role:tool messages (emitted first)
+        text blocks → joined role:user message (emitted after tool messages)
+    - assistant turn:
+        content = joined text blocks (or null if none)
+        tool_calls = mapped toolUse blocks (omitted if none)
+    """
+    result: List[Dict[str, Any]] = []
+
+    # Step 2: system
+    if system:
+        texts = [b.get("text", "") for b in system if "text" in b]
+        joined = "\n\n".join(texts)
+        if joined:
+            result.append({"role": "system", "content": joined})
+
+    # Step 3: messages
+    for msg in canonical_messages:
+        role = msg.get("role", "")
+        content_blocks: List[Dict[str, Any]] = msg.get("content", [])
+
+        if role == "user":
+            tool_msgs: List[Dict[str, Any]] = []
+            # Ordered (kind, payload) pairs for text/image blocks so the
+            # multimodal path preserves original block order (spec §3).
+            user_parts: List[Dict[str, Any]] = []
+            has_image = False
+
+            for block in content_blocks:
+                if "toolResult" in block:
+                    tr = block["toolResult"]
+                    text = _toolresult_content_text(tr.get("content", []))
+                    tool_msgs.append({
+                        "role": "tool",
+                        "tool_call_id": tr.get("toolUseId", ""),
+                        "content": text,
+                    })
+                elif "text" in block:
+                    user_parts.append({"type": "text", "text": block["text"]})
+                elif "image" in block:
+                    has_image = True
+                    user_parts.append(_image_block_to_part(block["image"]))
+
+            result.extend(tool_msgs)
+            if has_image:
+                result.append({"role": "user", "content": user_parts})
+            elif user_parts:
+                # Text-only turn keeps the plain-string form (spec §3).
+                result.append({
+                    "role": "user",
+                    "content": "\n".join(p["text"] for p in user_parts),
+                })
+
+        elif role == "assistant":
+            text_parts = []
+            tool_calls: List[Dict[str, Any]] = []
+
+            for block in content_blocks:
+                if "text" in block:
+                    text_parts.append(block["text"])
+                elif "toolUse" in block:
+                    tu = block["toolUse"]
+                    tool_calls.append({
+                        "id": tu.get("toolUseId", ""),
+                        "type": "function",
+                        "function": {
+                            "name": tu.get("name", ""),
+                            "arguments": json.dumps(tu.get("input", {})),
+                        },
+                    })
+
+            oai_msg: Dict[str, Any] = {"role": "assistant"}
+            oai_msg["content"] = "\n".join(text_parts) if text_parts else None
+            if tool_calls:
+                oai_msg["tool_calls"] = tool_calls
+            result.append(oai_msg)
+
+    return result
+
+
+def _build_tool_list(
+    tools: List[Dict[str, Any]],
+) -> List[Dict[str, Any]]:
+    """Map toolConfig.tools to OpenAI tools array."""
+    out: List[Dict[str, Any]] = []
+    for t in tools:
+        spec = t.get("toolSpec", {})
+        func: Dict[str, Any] = {"name": spec.get("name", "")}
+        if spec.get("description"):
+            func["description"] = spec["description"]
+        input_schema = spec.get("inputSchema", {})
+        if "json" in input_schema:
+            func["parameters"] = input_schema["json"]
+        out.append({"type": "function", "function": func})
+    return out
+
+
+def _build_tool_choice(tc: Dict[str, Any]) -> Any:
+    """Map toolConfig.toolChoice to OpenAI tool_choice."""
+    if "auto" in tc:
+        return "auto"
+    if "any" in tc:
+        return "required"
+    if "tool" in tc:
+        return {"type": "function", "function": {"name": tc["tool"]["name"]}}
+    return "auto"
+
+
+def build_request_body(kwargs: Dict[str, Any], stream: bool = False) -> Dict[str, Any]:
+    """
+    Construct the full OpenAI request body from Bedrock-shaped kwargs.
+
+    Spec §3 steps 1–7.
+    """
+    body: Dict[str, Any] = {}
+
+    # Client-side validation (spec §2: modelId REQUIRED, messages min 1)
+    model_id = kwargs.get("modelId")
+    if not model_id:
+        raise ValidationException(
+            message="modelId is required.",
+            status_code=0,
+        )
+    messages = kwargs.get("messages")
+    if not messages:
+        raise ValidationException(
+            message="messages is required and must contain at least one message.",
+            status_code=0,
+        )
+
+    # Step 1: modelId → model
+    body["model"] = model_id
+
+    # Steps 2–3: system + messages
+    body["messages"] = _build_openai_messages(
+        canonical_messages=messages,
+        system=kwargs.get("system"),
+    )
+
+    # Step 4: inferenceConfig
+    ic = kwargs.get("inferenceConfig") or {}
+    if "maxTokens" in ic:
+        body["max_tokens"] = ic["maxTokens"]
+    if "temperature" in ic:
+        body["temperature"] = ic["temperature"]
+    if "topP" in ic:
+        body["top_p"] = ic["topP"]
+    if "stopSequences" in ic:
+        body["stop"] = ic["stopSequences"]
+
+    # Step 5: toolConfig
+    tc_cfg = kwargs.get("toolConfig") or {}
+    if "tools" in tc_cfg:
+        body["tools"] = _build_tool_list(tc_cfg["tools"])
+    if "toolChoice" in tc_cfg:
+        body["tool_choice"] = _build_tool_choice(tc_cfg["toolChoice"])
+
+    # Step 7: stream flag
+    if stream:
+        body["stream"] = True
+
+    # Step 6: additionalModelRequestFields (shallow-merged last)
+    amrf = kwargs.get("additionalModelRequestFields") or {}
+    for k, v in amrf.items():
+        body[k] = v
+
+    return body
+
+
+# ---------------------------------------------------------------------------
+# OpenAI response → Converse output (spec §3)
+# ---------------------------------------------------------------------------
+
+def map_converse_response(
+    raw_body: bytes,
+    start_time: float,
+) -> Dict[str, Any]:
+    """
+    Parse a non-streaming HTTP 200 response into the Bedrock Converse output shape.
+
+    Implements the defensive unwrap rule (spec §1):
+      if parsed 200 body has no 'choices' but has 'data.choices', use body['data'].
+    """
+    try:
+        parsed = json.loads(raw_body)
+    except (json.JSONDecodeError, ValueError) as e:
+        raise SdkError(
+            f"Failed to decode 200 response body as JSON: {e}",
+            cause=e,
+            retryable=False,
+        ) from e
+
+    if not isinstance(parsed, dict):
+        raise SdkError(
+            "Malformed 200 response: body is not a JSON object",
+            retryable=False,
+        )
+
+    # Defensive unwrap
+    if "choices" not in parsed and isinstance(parsed.get("data"), dict):
+        if "choices" in parsed["data"]:
+            parsed = parsed["data"]
+
+    choices = parsed.get("choices")
+    if not isinstance(choices, list) or not choices:
+        raise SdkError(
+            "Malformed 200 response: missing or empty 'choices'",
+            retryable=False,
+        )
+    choice = choices[0]
+    msg = choice.get("message") if isinstance(choice, dict) else None
+    if not isinstance(msg, dict):
+        raise SdkError(
+            "Malformed 200 response: missing 'message' in choices[0]",
+            retryable=False,
+        )
+
+    content_blocks: List[Dict[str, Any]] = []
+
+    # text content
+    if msg.get("content"):
+        content_blocks.append({"text": msg["content"]})
+
+    # tool_calls
+    for tc in msg.get("tool_calls") or []:
+        func = tc.get("function") or {}
+        raw_args = func.get("arguments") or "{}"
+        try:
+            input_val: Any = json.loads(raw_args)
+        except (json.JSONDecodeError, ValueError):
+            input_val = raw_args
+        content_blocks.append({
+            "toolUse": {
+                "toolUseId": tc.get("id", ""),
+                "name": func.get("name", ""),
+                "input": input_val,
+            }
+        })
+
+    finish_reason = choice.get("finish_reason")
+    stop_reason = _map_finish_reason(finish_reason)
+
+    latency_ms = int((time.time() - start_time) * 1000)
+
+    return {
+        "output": {
+            "message": {
+                "role": "assistant",
+                "content": content_blocks,
+            }
+        },
+        "stopReason": stop_reason,
+        "usage": _map_usage(parsed.get("usage")),
+        "metrics": {
+            "latencyMs": latency_ms,
+        },
+    }