latentkit 0.1.1__py3-none-any.whl

latentkit/__init__.py

@@ -0,0 +1,5 @@
+from latentkit._exceptions import LatentKitAPIError, LatentKitError
+from latentkit.client import AsyncLatentKit, LatentKit
+from latentkit.types import StreamEvent
+
+__all__ = ["AsyncLatentKit", "LatentKit", "LatentKitAPIError", "LatentKitError", "StreamEvent"]

latentkit/_exceptions.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+class LatentKitError(Exception):
+    """Base exception for the Python SDK."""
+
+
+class LatentKitAPIError(LatentKitError):
+    """Raised when the LatentKit API returns a non-2xx response."""
+
+    def __init__(self, status_code: int, body: Any) -> None:
+        self.status_code = status_code
+        self.body = body
+        self.code = _extract_code(body)
+        message = _extract_message(body)
+        if message:
+            super().__init__(f"LatentKit API error {status_code}: {message}")
+        else:
+            super().__init__(f"LatentKit API error {status_code}: {body!r}")
+
+
+def _extract_message(body: Any) -> str | None:
+    if isinstance(body, str):
+        return body or None
+    if not isinstance(body, dict):
+        return None
+    for key in ("message", "detail", "error"):
+        value = body.get(key)
+        if isinstance(value, str) and value:
+            return value
+    nested = body.get("error")
+    if isinstance(nested, dict):
+        value = nested.get("message")
+        if isinstance(value, str) and value:
+            return value
+    return None
+
+
+def _extract_code(body: Any) -> str | None:
+    if not isinstance(body, dict):
+        return None
+    value = body.get("code")
+    if isinstance(value, str) and value:
+        return value
+    nested = body.get("error")
+    if isinstance(nested, dict):
+        value = nested.get("code")
+        if isinstance(value, str) and value:
+            return value
+    return None

latentkit/_stream.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+import json
+from collections.abc import AsyncIterator, Iterator
+
+import httpx
+
+from latentkit.types import StreamEvent
+
+
+def iter_sse_events(response: httpx.Response) -> Iterator[StreamEvent]:
+    buffer: list[str] = []
+    for line in response.iter_lines():
+        if line == "":
+            if buffer:
+                yield _parse_sse_event(buffer)
+                buffer = []
+            continue
+        buffer.append(line)
+    if buffer:
+        yield _parse_sse_event(buffer)
+
+
+async def aiter_sse_events(response: httpx.Response) -> AsyncIterator[StreamEvent]:
+    buffer: list[str] = []
+    async for line in response.aiter_lines():
+        if line == "":
+            if buffer:
+                yield _parse_sse_event(buffer)
+                buffer = []
+            continue
+        buffer.append(line)
+    if buffer:
+        yield _parse_sse_event(buffer)
+
+
+def _parse_sse_event(lines: list[str]) -> StreamEvent:
+    event_name: str | None = None
+    data_lines: list[str] = []
+    for raw_line in lines:
+        if raw_line.startswith("event:"):
+            event_name = raw_line.partition(":")[2].strip() or None
+            continue
+        if raw_line.startswith("data:"):
+            data_lines.append(raw_line.partition(":")[2].lstrip())
+    payload = "\n".join(data_lines)
+    if payload == "[DONE]":
+        return StreamEvent(data=payload, event=event_name or "done", is_done=True)
+    try:
+        parsed = json.loads(payload)
+    except json.JSONDecodeError:
+        parsed = payload
+    return StreamEvent(data=parsed, event=event_name)

latentkit/_transport.py

@@ -0,0 +1,113 @@
+from __future__ import annotations
+
+from collections.abc import AsyncIterator, Iterator
+from typing import Any
+
+import httpx
+
+from latentkit._exceptions import LatentKitAPIError
+from latentkit._stream import aiter_sse_events, iter_sse_events
+from latentkit.types import JSONDict, StreamEvent
+
+
+def normalize_base_url(base_url: str) -> str:
+    raw = base_url.rstrip("/")
+    return raw if raw.endswith("/v1") else f"{raw}/v1"
+
+
+def build_headers(api_key: str, extra_headers: dict[str, str] | None = None) -> dict[str, str]:
+    headers = {
+        "Authorization": f"Bearer {api_key}",
+        "Content-Type": "application/json",
+    }
+    if extra_headers:
+        headers.update(extra_headers)
+    return headers
+
+
+def request_json(
+    client: httpx.Client,
+    *,
+    method: str,
+    url: str,
+    headers: dict[str, str],
+    body: JSONDict | None = None,
+) -> JSONDict:
+    request_kwargs: dict[str, Any] = {"headers": headers}
+    if body is not None:
+        request_kwargs["json"] = body
+    response = client.request(method, url, **request_kwargs)
+    return _decode_json_response(response)
+
+
+async def arequest_json(
+    client: httpx.AsyncClient,
+    *,
+    method: str,
+    url: str,
+    headers: dict[str, str],
+    body: JSONDict | None = None,
+) -> JSONDict:
+    request_kwargs: dict[str, Any] = {"headers": headers}
+    if body is not None:
+        request_kwargs["json"] = body
+    response = await client.request(method, url, **request_kwargs)
+    return _decode_json_response(response)
+
+
+def stream_events(
+    client: httpx.Client,
+    *,
+    method: str,
+    url: str,
+    headers: dict[str, str],
+    body: JSONDict | None = None,
+) -> Iterator[StreamEvent]:
+    def generator() -> Iterator[StreamEvent]:
+        request_kwargs: dict[str, Any] = {"headers": {**headers, "Accept": "text/event-stream"}}
+        if body is not None:
+            request_kwargs["json"] = body
+        with client.stream(method, url, **request_kwargs) as response:
+            _ensure_success(response)
+            yield from iter_sse_events(response)
+
+    return generator()
+
+
+def astream_events(
+    client: httpx.AsyncClient,
+    *,
+    method: str,
+    url: str,
+    headers: dict[str, str],
+    body: JSONDict | None = None,
+) -> AsyncIterator[StreamEvent]:
+    async def generator() -> AsyncIterator[StreamEvent]:
+        request_kwargs: dict[str, Any] = {"headers": {**headers, "Accept": "text/event-stream"}}
+        if body is not None:
+            request_kwargs["json"] = body
+        async with client.stream(method, url, **request_kwargs) as response:
+            _ensure_success(response)
+            async for event in aiter_sse_events(response):
+                yield event
+
+    return generator()
+
+
+def _decode_json_response(response: httpx.Response) -> JSONDict:
+    _ensure_success(response)
+    payload = response.json()
+    if not isinstance(payload, dict):
+        raise LatentKitAPIError(response.status_code, payload)
+    return payload
+
+
+def _ensure_success(response: httpx.Response) -> None:
+    if response.is_success:
+        return
+    body: Any
+    try:
+        body = response.json()
+    except Exception:
+        body = response.text
+    raise LatentKitAPIError(response.status_code, body)

latentkit/client.py

@@ -0,0 +1,107 @@
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from latentkit._transport import arequest_json, astream_events, build_headers, normalize_base_url, request_json, stream_events
+from latentkit.resources.agents import AgentsResource, AsyncAgentsResource
+from latentkit.resources.audio import AsyncTranscriptionResource, AsyncTranslationResource, TranscriptionResource, TranslationResource
+from latentkit.resources.chat import AsyncChatResource, ChatResource
+from latentkit.resources.completions import AsyncCompletionsResource, CompletionsResource
+from latentkit.resources.embeddings import AsyncEmbeddingsResource, EmbeddingsResource
+from latentkit.resources.image import AsyncImageResource, ImageResource
+from latentkit.resources.queue import AsyncQueueResource, QueueResource
+from latentkit.resources.speech import AsyncSpeechResource, SpeechResource
+from latentkit.resources.video import AsyncVideoResource, VideoResource
+from latentkit.resources.vision import AsyncVisionResource, VisionResource
+
+
+class LatentKit:
+    """Synchronous Python client for LatentKit's canonical `/v1` API."""
+
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        base_url: str = "https://ai.latentkit.com",
+        timeout: float = 120.0,
+        headers: dict[str, str] | None = None,
+        http_client: httpx.Client | None = None,
+    ) -> None:
+        self._base_v1 = normalize_base_url(base_url)
+        self._headers = build_headers(api_key, headers)
+        self._owns_client = http_client is None
+        self._http = http_client or httpx.Client(timeout=timeout)
+        self.chat = ChatResource(self._request_json, self._stream_events, self._base_v1)
+        self.completions = CompletionsResource(self._request_json, self._stream_events, self._base_v1)
+        self.embeddings = EmbeddingsResource(self._request_json, self._base_v1)
+        self.image = ImageResource(self._request_json, self._base_v1)
+        self.speech = SpeechResource(self._request_json, self._base_v1)
+        self.transcription = TranscriptionResource(self._request_json, self._base_v1)
+        self.translation = TranslationResource(self._request_json, self._base_v1)
+        self.video = VideoResource(self._request_json, self._base_v1)
+        self.vision = VisionResource(self._request_json, self._stream_events, self._base_v1)
+        self.queue = QueueResource(self._request_json, self._base_v1)
+        self.agents = AgentsResource(self._request_json, self._stream_events, self._base_v1)
+
+    def _request_json(self, method: str, url: str, body: dict[str, Any] | None) -> dict[str, Any]:
+        return request_json(self._http, method=method, url=url, headers=self._headers, body=body)
+
+    def _stream_events(self, method: str, url: str, body: dict[str, Any] | None):
+        return stream_events(self._http, method=method, url=url, headers=self._headers, body=body)
+
+    def close(self) -> None:
+        if self._owns_client:
+            self._http.close()
+
+    def __enter__(self) -> LatentKit:
+        return self
+
+    def __exit__(self, *_exc: object) -> None:
+        self.close()
+
+
+class AsyncLatentKit:
+    """Async Python client for LatentKit's canonical `/v1` API."""
+
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        base_url: str = "https://ai.latentkit.com",
+        timeout: float = 120.0,
+        headers: dict[str, str] | None = None,
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        self._base_v1 = normalize_base_url(base_url)
+        self._headers = build_headers(api_key, headers)
+        self._owns_client = http_client is None
+        self._http = http_client or httpx.AsyncClient(timeout=timeout)
+        self.chat = AsyncChatResource(self._request_json, self._stream_events, self._base_v1)
+        self.completions = AsyncCompletionsResource(self._request_json, self._stream_events, self._base_v1)
+        self.embeddings = AsyncEmbeddingsResource(self._request_json, self._base_v1)
+        self.image = AsyncImageResource(self._request_json, self._base_v1)
+        self.speech = AsyncSpeechResource(self._request_json, self._base_v1)
+        self.transcription = AsyncTranscriptionResource(self._request_json, self._base_v1)
+        self.translation = AsyncTranslationResource(self._request_json, self._base_v1)
+        self.video = AsyncVideoResource(self._request_json, self._base_v1)
+        self.vision = AsyncVisionResource(self._request_json, self._stream_events, self._base_v1)
+        self.queue = AsyncQueueResource(self._request_json, self._base_v1)
+        self.agents = AsyncAgentsResource(self._request_json, self._stream_events, self._base_v1)
+
+    async def _request_json(self, method: str, url: str, body: dict[str, Any] | None) -> dict[str, Any]:
+        return await arequest_json(self._http, method=method, url=url, headers=self._headers, body=body)
+
+    def _stream_events(self, method: str, url: str, body: dict[str, Any] | None):
+        return astream_events(self._http, method=method, url=url, headers=self._headers, body=body)
+
+    async def close(self) -> None:
+        if self._owns_client:
+            await self._http.aclose()
+
+    async def __aenter__(self) -> AsyncLatentKit:
+        return self
+
+    async def __aexit__(self, *_exc: object) -> None:
+        await self.close()

latentkit/resources/__init__.py

@@ -0,0 +1,35 @@
+from latentkit.resources.agents import AgentsResource, AsyncAgentsResource
+from latentkit.resources.audio import AsyncTranscriptionResource, AsyncTranslationResource, TranscriptionResource, TranslationResource
+from latentkit.resources.chat import AsyncChatResource, ChatResource
+from latentkit.resources.completions import AsyncCompletionsResource, CompletionsResource
+from latentkit.resources.embeddings import AsyncEmbeddingsResource, EmbeddingsResource
+from latentkit.resources.image import AsyncImageResource, ImageResource
+from latentkit.resources.queue import AsyncQueueResource, QueueResource
+from latentkit.resources.speech import AsyncSpeechResource, SpeechResource
+from latentkit.resources.video import AsyncVideoResource, VideoResource
+from latentkit.resources.vision import AsyncVisionResource, VisionResource
+
+__all__ = [
+    "AgentsResource",
+    "AsyncAgentsResource",
+    "AsyncChatResource",
+    "AsyncCompletionsResource",
+    "AsyncEmbeddingsResource",
+    "AsyncImageResource",
+    "AsyncQueueResource",
+    "AsyncSpeechResource",
+    "AsyncTranscriptionResource",
+    "AsyncTranslationResource",
+    "AsyncVideoResource",
+    "AsyncVisionResource",
+    "ChatResource",
+    "CompletionsResource",
+    "EmbeddingsResource",
+    "ImageResource",
+    "QueueResource",
+    "SpeechResource",
+    "TranscriptionResource",
+    "TranslationResource",
+    "VideoResource",
+    "VisionResource",
+]

latentkit/resources/agents.py

@@ -0,0 +1,86 @@
+from __future__ import annotations
+
+from collections.abc import AsyncIterator, Iterator
+from typing import Any
+
+from latentkit.types import JSONDict, StreamEvent
+
+
+class AgentSessionsResource:
+    def __init__(self, request_json: Any, stream_events: Any, base_v1: str) -> None:
+        self._request_json = request_json
+        self._stream_events = stream_events
+        self._base = f"{base_v1}/agent/sessions"
+
+    def create(self, **payload: Any) -> JSONDict:
+        return self._request_json("POST", self._base, payload)
+
+    def run(self, session_id: str, *, stream: bool = False) -> JSONDict:
+        return self._request_json("POST", f"{self._base}/{session_id}/run", {"stream": stream})
+
+    def run_stream(self, session_id: str) -> Iterator[StreamEvent]:
+        return self._stream_events("POST", f"{self._base}/{session_id}/run", {"stream": True})
+
+    def input(self, session_id: str, *, message: str, policy_id: str | None = None) -> JSONDict:
+        return self._request_json(
+            "POST",
+            f"{self._base}/{session_id}/input",
+            {"message": message, "policy_id": policy_id},
+        )
+
+    def cancel(self, session_id: str) -> JSONDict:
+        return self._request_json("POST", f"{self._base}/{session_id}/cancel", None)
+
+    def retrieve(self, session_id: str) -> JSONDict:
+        return self._request_json("GET", f"{self._base}/{session_id}", None)
+
+    def steps(self, session_id: str) -> JSONDict:
+        return self._request_json("GET", f"{self._base}/{session_id}/steps", None)
+
+    def stream(self, session_id: str) -> Iterator[StreamEvent]:
+        return self._stream_events("GET", f"{self._base}/{session_id}/stream", None)
+
+
+class AsyncAgentSessionsResource:
+    def __init__(self, request_json: Any, stream_events: Any, base_v1: str) -> None:
+        self._request_json = request_json
+        self._stream_events = stream_events
+        self._base = f"{base_v1}/agent/sessions"
+
+    async def create(self, **payload: Any) -> JSONDict:
+        return await self._request_json("POST", self._base, payload)
+
+    async def run(self, session_id: str, *, stream: bool = False) -> JSONDict:
+        return await self._request_json("POST", f"{self._base}/{session_id}/run", {"stream": stream})
+
+    def run_stream(self, session_id: str) -> AsyncIterator[StreamEvent]:
+        return self._stream_events("POST", f"{self._base}/{session_id}/run", {"stream": True})
+
+    async def input(self, session_id: str, *, message: str, policy_id: str | None = None) -> JSONDict:
+        return await self._request_json(
+            "POST",
+            f"{self._base}/{session_id}/input",
+            {"message": message, "policy_id": policy_id},
+        )
+
+    async def cancel(self, session_id: str) -> JSONDict:
+        return await self._request_json("POST", f"{self._base}/{session_id}/cancel", None)
+
+    async def retrieve(self, session_id: str) -> JSONDict:
+        return await self._request_json("GET", f"{self._base}/{session_id}", None)
+
+    async def steps(self, session_id: str) -> JSONDict:
+        return await self._request_json("GET", f"{self._base}/{session_id}/steps", None)
+
+    def stream(self, session_id: str) -> AsyncIterator[StreamEvent]:
+        return self._stream_events("GET", f"{self._base}/{session_id}/stream", None)
+
+
+class AgentsResource:
+    def __init__(self, request_json: Any, stream_events: Any, base_v1: str) -> None:
+        self.sessions = AgentSessionsResource(request_json, stream_events, base_v1)
+
+
+class AsyncAgentsResource:
+    def __init__(self, request_json: Any, stream_events: Any, base_v1: str) -> None:
+        self.sessions = AsyncAgentSessionsResource(request_json, stream_events, base_v1)

latentkit/resources/audio.py

@@ -0,0 +1,133 @@
+from __future__ import annotations
+
+from typing import Any
+
+from latentkit.types import JSONDict
+
+
+class TranscriptionResource:
+    def __init__(self, request_json: Any, base_v1: str) -> None:
+        self._request_json = request_json
+        self._url = f"{base_v1}/transcription"
+
+    def create(
+        self,
+        *,
+        audio: JSONDict | None = None,
+        input: Any = None,
+        language: str | None = None,
+        prompt: str | None = None,
+        response_format: str | None = None,
+        temperature: float | None = None,
+        response_profile: str | None = None,
+        extra_body: JSONDict | None = None,
+    ) -> JSONDict:
+        body: JSONDict = {
+            "audio": audio,
+            "input": input,
+            "language": language,
+            "prompt": prompt,
+            "response_format": response_format,
+            "temperature": temperature,
+        }
+        if response_profile:
+            body["response_profile"] = response_profile
+        if extra_body:
+            body.update(extra_body)
+        return self._request_json("POST", self._url, body)
+
+
+class AsyncTranscriptionResource:
+    def __init__(self, request_json: Any, base_v1: str) -> None:
+        self._request_json = request_json
+        self._url = f"{base_v1}/transcription"
+
+    async def create(
+        self,
+        *,
+        audio: JSONDict | None = None,
+        input: Any = None,
+        language: str | None = None,
+        prompt: str | None = None,
+        response_format: str | None = None,
+        temperature: float | None = None,
+        response_profile: str | None = None,
+        extra_body: JSONDict | None = None,
+    ) -> JSONDict:
+        body: JSONDict = {
+            "audio": audio,
+            "input": input,
+            "language": language,
+            "prompt": prompt,
+            "response_format": response_format,
+            "temperature": temperature,
+        }
+        if response_profile:
+            body["response_profile"] = response_profile
+        if extra_body:
+            body.update(extra_body)
+        return await self._request_json("POST", self._url, body)
+
+
+class TranslationResource:
+    def __init__(self, request_json: Any, base_v1: str) -> None:
+        self._request_json = request_json
+        self._url = f"{base_v1}/translation"
+
+    def create(
+        self,
+        *,
+        audio: JSONDict | None = None,
+        input: Any = None,
+        target_language: str | None = None,
+        prompt: str | None = None,
+        response_format: str | None = None,
+        temperature: float | None = None,
+        response_profile: str | None = None,
+        extra_body: JSONDict | None = None,
+    ) -> JSONDict:
+        body: JSONDict = {
+            "audio": audio,
+            "input": input,
+            "target_language": target_language,
+            "prompt": prompt,
+            "response_format": response_format,
+            "temperature": temperature,
+        }
+        if response_profile:
+            body["response_profile"] = response_profile
+        if extra_body:
+            body.update(extra_body)
+        return self._request_json("POST", self._url, body)
+
+
+class AsyncTranslationResource:
+    def __init__(self, request_json: Any, base_v1: str) -> None:
+        self._request_json = request_json
+        self._url = f"{base_v1}/translation"
+
+    async def create(
+        self,
+        *,
+        audio: JSONDict | None = None,
+        input: Any = None,
+        target_language: str | None = None,
+        prompt: str | None = None,
+        response_format: str | None = None,
+        temperature: float | None = None,
+        response_profile: str | None = None,
+        extra_body: JSONDict | None = None,
+    ) -> JSONDict:
+        body: JSONDict = {
+            "audio": audio,
+            "input": input,
+            "target_language": target_language,
+            "prompt": prompt,
+            "response_format": response_format,
+            "temperature": temperature,
+        }
+        if response_profile:
+            body["response_profile"] = response_profile
+        if extra_body:
+            body.update(extra_body)
+        return await self._request_json("POST", self._url, body)

latentkit/resources/chat.py

@@ -0,0 +1,102 @@
+from __future__ import annotations
+
+from collections.abc import AsyncIterator, Iterator
+from typing import Any
+
+from latentkit.types import JSONDict, StreamEvent
+
+
+class ChatResource:
+    def __init__(self, request_json: Any, stream_events: Any, base_v1: str) -> None:
+        self._request_json = request_json
+        self._stream_events = stream_events
+        self._url = f"{base_v1}/chat"
+
+    def create(
+        self,
+        *,
+        messages: list[dict[str, Any]],
+        max_tokens: int = 1000,
+        temperature: float = 0.7,
+        response_profile: str | None = None,
+        extra_body: JSONDict | None = None,
+    ) -> JSONDict:
+        body: JSONDict = {
+            "messages": messages,
+            "max_tokens": max_tokens,
+            "temperature": temperature,
+        }
+        if response_profile:
+            body["response_profile"] = response_profile
+        if extra_body:
+            body.update(extra_body)
+        return self._request_json("POST", self._url, body)
+
+    def stream(
+        self,
+        *,
+        messages: list[dict[str, Any]],
+        max_tokens: int = 1000,
+        temperature: float = 0.7,
+        response_profile: str | None = None,
+        extra_body: JSONDict | None = None,
+    ) -> Iterator[StreamEvent]:
+        body: JSONDict = {
+            "messages": messages,
+            "max_tokens": max_tokens,
+            "temperature": temperature,
+            "stream": True,
+        }
+        if response_profile:
+            body["response_profile"] = response_profile
+        if extra_body:
+            body.update(extra_body)
+        return self._stream_events("POST", self._url, body)
+
+
+class AsyncChatResource:
+    def __init__(self, request_json: Any, stream_events: Any, base_v1: str) -> None:
+        self._request_json = request_json
+        self._stream_events = stream_events
+        self._url = f"{base_v1}/chat"
+
+    async def create(
+        self,
+        *,
+        messages: list[dict[str, Any]],
+        max_tokens: int = 1000,
+        temperature: float = 0.7,
+        response_profile: str | None = None,
+        extra_body: JSONDict | None = None,
+    ) -> JSONDict:
+        body: JSONDict = {
+            "messages": messages,
+            "max_tokens": max_tokens,
+            "temperature": temperature,
+        }
+        if response_profile:
+            body["response_profile"] = response_profile
+        if extra_body:
+            body.update(extra_body)
+        return await self._request_json("POST", self._url, body)
+
+    def stream(
+        self,
+        *,
+        messages: list[dict[str, Any]],
+        max_tokens: int = 1000,
+        temperature: float = 0.7,
+        response_profile: str | None = None,
+        extra_body: JSONDict | None = None,
+    ) -> AsyncIterator[StreamEvent]:
+        body: JSONDict = {
+            "messages": messages,
+            "max_tokens": max_tokens,
+            "temperature": temperature,
+            "stream": True,
+        }
+        if response_profile:
+            body["response_profile"] = response_profile
+        if extra_body:
+            body.update(extra_body)
+        return self._stream_events("POST", self._url, body)