latitude-sdk 0.1.0b1__py3-none-any.whl

latitude_sdk/__init__.py

@@ -0,0 +1 @@
+from .sdk import *

latitude_sdk/client/__init__.py

@@ -0,0 +1,3 @@
+from .client import *
+from .payloads import *
+from .router import *

latitude_sdk/client/client.py

@@ -0,0 +1,140 @@
+import asyncio
+import json
+from contextlib import asynccontextmanager
+from typing import Any, AsyncGenerator, Optional
+
+import httpx
+import httpx_sse
+
+from latitude_sdk.client.payloads import ErrorResponse, RequestBody, RequestHandler, RequestParams
+from latitude_sdk.client.router import Router, RouterOptions
+from latitude_sdk.sdk.errors import (
+    ApiError,
+    ApiErrorCodes,
+    ApiErrorDbRef,
+)
+from latitude_sdk.sdk.types import LogSources
+from latitude_sdk.util import Model
+
+RETRIABLE_STATUSES = [429, 500, 502, 503, 504]
+
+ClientEvent = httpx_sse.ServerSentEvent
+
+
+class ClientResponse(httpx.Response):
+    async def sse(self: httpx.Response) -> AsyncGenerator[ClientEvent, Any]:
+        source = httpx_sse.EventSource(self)
+
+        async for event in source.aiter_sse():
+            yield event
+
+
+httpx.Response.sse = ClientResponse.sse  # pyright: ignore [reportAttributeAccessIssue]
+
+
+class ClientOptions(Model):
+    api_key: str
+    retries: int
+    delay: float
+    timeout: float
+    source: LogSources
+    router: RouterOptions
+
+
+class Client:
+    options: ClientOptions
+    router: Router
+
+    def __init__(self, options: ClientOptions):
+        self.options = options
+        self.router = Router(options.router)
+
+    @asynccontextmanager
+    async def request(
+        self, handler: RequestHandler, params: RequestParams, body: Optional[RequestBody] = None
+    ) -> AsyncGenerator[ClientResponse, Any]:
+        client = httpx.AsyncClient(
+            headers={
+                "Authorization": f"Bearer {self.options.api_key}",
+                "Content-Type": "application/json",
+            },
+            timeout=self.options.timeout,
+            follow_redirects=False,
+            max_redirects=0,
+        )
+        response = None
+        attempt = 1
+
+        try:
+            method, url = self.router.resolve(handler, params)
+            content = None
+            if body:
+                content = json.dumps(
+                    {
+                        **json.loads(body.model_dump_json()),
+                        "__internal": {"source": self.options.source},
+                    }
+                )
+
+            while attempt <= self.options.retries:
+                try:
+                    response = await client.request(method=method, url=url, content=content)
+                    response.raise_for_status()
+
+                    yield response  # pyright: ignore [reportReturnType]
+                    break
+
+                except Exception as exception:
+                    if isinstance(exception, ApiError):
+                        raise exception
+
+                    if attempt >= self.options.retries:
+                        raise await self._exception(exception, response) from exception
+
+                    if response and response.status_code in RETRIABLE_STATUSES:
+                        await asyncio.sleep(self.options.delay * (2 ** (attempt - 1)))
+                    else:
+                        raise await self._exception(exception, response) from exception
+
+                finally:
+                    if response:
+                        await response.aclose()
+
+                    attempt += 1
+
+        except Exception as exception:
+            if isinstance(exception, ApiError):
+                raise exception
+
+            raise await self._exception(exception, response) from exception
+
+        finally:
+            await client.aclose()
+
+    async def _exception(self, exception: Exception, response: Optional[httpx.Response] = None) -> ApiError:
+        if not response:
+            return ApiError(
+                status=500,
+                code=ApiErrorCodes.InternalServerError,
+                message=str(exception),
+                response=str(exception),
+            )
+
+        try:
+            error = ErrorResponse.model_validate_json(response.content)
+
+            return ApiError(
+                status=response.status_code,
+                code=error.code,
+                message=error.message,
+                response=response.text,
+                db_ref=ApiErrorDbRef(**dict(error.db_ref)) if error.db_ref else None,
+            )
+
+        except Exception:
+            return ApiError(
+                status=response.status_code,
+                code=ApiErrorCodes.InternalServerError,
+                message=str(exception),
+                response=response.text,
+            )

latitude_sdk/client/payloads.py

@@ -0,0 +1,117 @@
+from typing import Any, Dict, List, Optional, Union
+
+from latitude_sdk.sdk.types import DbErrorRef, Message
+from latitude_sdk.util import Field, Model, StrEnum
+
+
+class ErrorResponse(Model):
+    name: str
+    code: str = Field(alias=str("errorCode"))
+    message: str
+    details: Dict[str, Any]
+    db_ref: Optional[DbErrorRef] = Field(None, alias=str("dbErrorRef"))
+
+
+class PromptRequestParams(Model):
+    project_id: int
+    version_uuid: Optional[str] = None
+
+
+class GetPromptRequestParams(PromptRequestParams, Model):
+    path: str
+
+
+class GetOrCreatePromptRequestParams(PromptRequestParams, Model):
+    pass
+
+
+class GetOrCreatePromptRequestBody(Model):
+    path: str
+    prompt: Optional[str] = None
+
+
+class RunPromptRequestParams(PromptRequestParams, Model):
+    pass
+
+
+class RunPromptRequestBody(Model):
+    path: str
+    parameters: Optional[Dict[str, Any]] = None
+    custom_identifier: Optional[str] = Field(None, alias=str("customIdentifier"))
+    stream: Optional[bool] = None
+
+
+class ChatPromptRequestParams(Model):
+    conversation_uuid: str
+
+
+class ChatPromptRequestBody(Model):
+    messages: List[Message]
+    stream: Optional[bool] = None
+
+
+class LogRequestParams(Model):
+    project_id: int
+    version_uuid: Optional[str] = None
+
+
+class CreateLogRequestParams(LogRequestParams, Model):
+    pass
+
+
+class CreateLogRequestBody(Model):
+    path: str
+    messages: List[Message]
+    response: Optional[str] = None
+
+
+class EvaluationRequestParams(Model):
+    conversation_uuid: str
+
+
+class TriggerEvaluationRequestParams(EvaluationRequestParams, Model):
+    pass
+
+
+class TriggerEvaluationRequestBody(Model):
+    evaluation_uuids: Optional[List[str]] = Field(None, alias=str("evaluationUuids"))
+
+
+class CreateEvaluationResultRequestParams(EvaluationRequestParams, Model):
+    evaluation_uuid: str
+
+
+class CreateEvaluationResultRequestBody(Model):
+    result: Union[str, bool, int]
+    reason: str
+
+
+RequestParams = Union[
+    GetPromptRequestParams,
+    GetOrCreatePromptRequestParams,
+    RunPromptRequestParams,
+    ChatPromptRequestParams,
+    CreateLogRequestParams,
+    TriggerEvaluationRequestParams,
+    CreateEvaluationResultRequestParams,
+]
+
+
+RequestBody = Union[
+    GetOrCreatePromptRequestBody,
+    RunPromptRequestBody,
+    ChatPromptRequestBody,
+    CreateLogRequestBody,
+    TriggerEvaluationRequestBody,
+    CreateEvaluationResultRequestBody,
+]
+
+
+class RequestHandler(StrEnum):
+    GetPrompt = "GET_PROMPT"
+    GetOrCreatePrompt = "GET_OR_CREATE_PROMPT"
+    RunPrompt = "RUN_PROMPT"
+    ChatPrompt = "CHAT_PROMPT"
+    CreateLog = "CREATE_LOG"
+    TriggerEvaluation = "TRIGGER_EVALUATION"
+    CreateEvaluationResult = "CREATE_EVALUATION_RESULT"

latitude_sdk/client/router.py

@@ -0,0 +1,117 @@
+from typing import Callable, Optional, Tuple
+
+from latitude_sdk.client.payloads import (
+    ChatPromptRequestParams,
+    CreateEvaluationResultRequestParams,
+    CreateLogRequestParams,
+    GetOrCreatePromptRequestParams,
+    GetPromptRequestParams,
+    RequestHandler,
+    RequestParams,
+    RunPromptRequestParams,
+    TriggerEvaluationRequestParams,
+)
+from latitude_sdk.sdk.types import GatewayOptions
+from latitude_sdk.util import Model
+
+HEAD_COMMIT = "live"
+
+
+class RouterOptions(Model):
+    gateway: GatewayOptions
+
+
+class Router:
+    options: RouterOptions
+
+    def __init__(self, options: RouterOptions):
+        self.options = options
+
+    def resolve(self, handler: RequestHandler, params: RequestParams) -> Tuple[str, str]:
+        if handler == RequestHandler.GetPrompt:
+            assert isinstance(params, GetPromptRequestParams)
+
+            return "GET", self.prompts(
+                project_id=params.project_id,
+                version_uuid=params.version_uuid,
+            ).prompt(params.path)
+
+        elif handler == RequestHandler.GetOrCreatePrompt:
+            assert isinstance(params, GetOrCreatePromptRequestParams)
+
+            return "POST", self.prompts(
+                project_id=params.project_id,
+                version_uuid=params.version_uuid,
+            ).get_or_create
+
+        elif handler == RequestHandler.RunPrompt:
+            assert isinstance(params, RunPromptRequestParams)
+
+            return "POST", self.prompts(
+                project_id=params.project_id,
+                version_uuid=params.version_uuid,
+            ).run
+
+        elif handler == RequestHandler.ChatPrompt:
+            assert isinstance(params, ChatPromptRequestParams)
+
+            return "POST", self.conversations().chat(params.conversation_uuid)
+
+        elif handler == RequestHandler.CreateLog:
+            assert isinstance(params, CreateLogRequestParams)
+
+            return "POST", self.prompts(
+                project_id=params.project_id,
+                version_uuid=params.version_uuid,
+            ).logs
+
+        elif handler == RequestHandler.TriggerEvaluation:
+            assert isinstance(params, TriggerEvaluationRequestParams)
+
+            return "POST", self.conversations().evaluate(params.conversation_uuid)
+
+        elif handler == RequestHandler.CreateEvaluationResult:
+            assert isinstance(params, CreateEvaluationResultRequestParams)
+
+            return "POST", self.conversations().evaluation_result(params.conversation_uuid, params.evaluation_uuid)
+
+        raise TypeError(f"Unknown handler: {handler}")
+
+    class Conversations(Model):
+        chat: Callable[[str], str]
+        evaluate: Callable[[str], str]
+        evaluation_result: Callable[[str, str], str]
+
+    def conversations(self) -> Conversations:
+        base_url = f"{self.options.gateway.base_url}/conversations"
+
+        return self.Conversations(
+            chat=lambda uuid: f"{base_url}/{uuid}/chat",
+            evaluate=lambda uuid: f"{base_url}/{uuid}/evaluate",
+            evaluation_result=lambda conversation_uuid,
+            evaluation_uuid: f"{base_url}/{conversation_uuid}/evaluations/{evaluation_uuid}/evaluation-results",
+        )
+
+    class Prompts(Model):
+        prompt: Callable[[str], str]
+        get_or_create: str
+        run: str
+        logs: str
+
+    def prompts(self, project_id: int, version_uuid: Optional[str]) -> Prompts:
+        base_url = f"{self.commits_url(project_id, version_uuid)}/documents"
+
+        return self.Prompts(
+            prompt=lambda path: f"{base_url}/{path}",
+            get_or_create=f"{base_url}/get-or-create",
+            run=f"{base_url}/run",
+            logs=f"{base_url}/logs",
+        )
+
+    def commits_url(self, project_id: int, version_uuid: Optional[str]) -> str:
+        version_uuid = version_uuid if version_uuid else HEAD_COMMIT
+
+        return f"{self.projects_url(project_id)}/versions/{version_uuid}"
+
+    def projects_url(self, project_id: int) -> str:
+        return f"{self.options.gateway.base_url}/projects/{project_id}"

latitude_sdk/env/__init__.py

@@ -0,0 +1 @@
+from .env import *

latitude_sdk/env/env.py

@@ -0,0 +1,18 @@
+from latitude_sdk.util import Model, get_env
+
+DEFAULT_GATEWAY_HOSTNAME = "gateway.latitude.so"
+DEFAULT_GATEWAY_PORT = 8787
+DEFAULT_GATEWAY_SSL = True
+
+
+class Env(Model):
+    GATEWAY_HOSTNAME: str
+    GATEWAY_PORT: int
+    GATEWAY_SSL: bool
+
+
+env = Env(
+    GATEWAY_HOSTNAME=get_env("GATEWAY_HOSTNAME", DEFAULT_GATEWAY_HOSTNAME),
+    GATEWAY_PORT=get_env("GATEWAY_PORT", DEFAULT_GATEWAY_PORT),
+    GATEWAY_SSL=get_env("GATEWAY_SSL", DEFAULT_GATEWAY_SSL),
+)

latitude_sdk/sdk/__init__.py

@@ -0,0 +1,6 @@
+from .errors import *
+from .evaluations import *
+from .latitude import *
+from .logs import *
+from .prompts import *
+from .types import *

latitude_sdk/sdk/errors.py

@@ -0,0 +1,59 @@
+from typing import Optional, Union
+
+from latitude_sdk.util import Model, StrEnum
+
+
+# NOTE: Incomplete list
+class ApiErrorCodes(StrEnum):
+    # LatitudeErrorCodes
+    NotFoundError = "NotFoundError"
+
+    # RunErrorCodes
+    AIRunError = "ai_run_error"
+
+    # ApiErrorCodes
+    HTTPException = "http_exception"
+    InternalServerError = "internal_server_error"
+
+
+UNEXPECTED_ERROR_CODES = [
+    str(ApiErrorCodes.HTTPException),
+    str(ApiErrorCodes.InternalServerError),
+]
+
+
+class ApiErrorDbRef(Model):
+    entity_uuid: str
+    entity_type: str
+
+
+class ApiError(Exception):
+    status: int
+    code: str  # NOTE: Cannot be ApiErrorCodes because the list is incomplete
+    message: str
+    response: str
+    db_ref: Optional[ApiErrorDbRef]
+
+    def __init__(
+        self,
+        status: int,
+        code: Union[str, ApiErrorCodes],
+        message: str,
+        response: str,
+        db_ref: Optional[ApiErrorDbRef] = None,
+    ):
+        message = self._exception_message(status, str(code), message)
+        super().__init__(message)
+
+        self.status = status
+        self.code = str(code)
+        self.message = message
+        self.response = response
+        self.db_ref = db_ref
+
+    @staticmethod
+    def _exception_message(status: int, code: str, message: str) -> str:
+        if code in UNEXPECTED_ERROR_CODES:
+            return f"Unexpected API Error: {status} {message}"
+
+        return message

latitude_sdk/sdk/evaluations.py

@@ -0,0 +1,69 @@
+from typing import List, Optional, Union
+
+from latitude_sdk.client import (
+    Client,
+    CreateEvaluationResultRequestBody,
+    CreateEvaluationResultRequestParams,
+    RequestHandler,
+    TriggerEvaluationRequestBody,
+    TriggerEvaluationRequestParams,
+)
+from latitude_sdk.sdk.types import (
+    EvaluationResult,
+    SdkOptions,
+)
+from latitude_sdk.util import Model
+
+
+class TriggerEvaluationOptions(Model):
+    evaluation_uuids: Optional[List[str]] = None
+
+
+class TriggerEvaluationResult(Model):
+    evaluations: List[str]
+
+
+class CreateEvaluationResultOptions(Model):
+    result: Union[str, bool, int]
+    reason: str
+
+
+class CreateEvaluationResultResult(EvaluationResult, Model):
+    pass
+
+
+class Evaluations:
+    _options: SdkOptions
+    _client: Client
+
+    def __init__(self, client: Client, options: SdkOptions):
+        self._options = options
+        self._client = client
+
+    async def trigger(self, uuid: str, options: TriggerEvaluationOptions) -> TriggerEvaluationResult:
+        async with self._client.request(
+            handler=RequestHandler.TriggerEvaluation,
+            params=TriggerEvaluationRequestParams(
+                conversation_uuid=uuid,
+            ),
+            body=TriggerEvaluationRequestBody(
+                evaluation_uuids=options.evaluation_uuids,
+            ),
+        ) as response:
+            return TriggerEvaluationResult.model_validate_json(response.content)
+
+    async def create_result(
+        self, uuid: str, evaluation_uuid: str, options: CreateEvaluationResultOptions
+    ) -> CreateEvaluationResultResult:
+        async with self._client.request(
+            handler=RequestHandler.CreateEvaluationResult,
+            params=CreateEvaluationResultRequestParams(
+                conversation_uuid=uuid,
+                evaluation_uuid=evaluation_uuid,
+            ),
+            body=CreateEvaluationResultRequestBody(
+                result=options.result,
+                reason=options.reason,
+            ),
+        ) as response:
+            return CreateEvaluationResultResult.model_validate_json(response.content)

latitude_sdk/sdk/latitude.py

@@ -0,0 +1,76 @@
+from typing import Optional
+
+from latitude_sdk.client import Client, ClientOptions, RouterOptions
+from latitude_sdk.env import env
+from latitude_sdk.sdk.evaluations import Evaluations
+from latitude_sdk.sdk.logs import Logs
+from latitude_sdk.sdk.prompts import Prompts
+from latitude_sdk.sdk.types import GatewayOptions, LogSources, SdkOptions
+from latitude_sdk.util import Model
+
+
+class InternalOptions(Model):
+    gateway: Optional[GatewayOptions] = None
+    source: Optional[LogSources] = None
+    retries: Optional[int] = None
+    delay: Optional[float] = None
+    timeout: Optional[float] = None
+
+
+class LatitudeOptions(SdkOptions, Model):
+    internal: Optional[InternalOptions] = None
+
+
+DEFAULT_INTERNAL_OPTIONS = InternalOptions(
+    gateway=GatewayOptions(
+        host=env.GATEWAY_HOSTNAME,
+        port=env.GATEWAY_PORT,
+        ssl=env.GATEWAY_SSL,
+        api_version="v2",
+    ),
+    source=LogSources.Api,
+    retries=3,
+    delay=0.5,
+    timeout=30,
+)
+
+
+DEFAULT_LATITUDE_OPTIONS = LatitudeOptions(internal=DEFAULT_INTERNAL_OPTIONS)
+
+
+class Latitude:
+    _options: LatitudeOptions
+    _client: Client
+
+    prompts: Prompts
+    logs: Logs
+    evaluations: Evaluations
+
+    def __init__(self, api_key: str, options: LatitudeOptions = DEFAULT_LATITUDE_OPTIONS):
+        options.internal = options.internal or DEFAULT_INTERNAL_OPTIONS
+        options.internal = InternalOptions(**{**dict(DEFAULT_INTERNAL_OPTIONS), **dict(options.internal)})
+        options = LatitudeOptions(**{**dict(DEFAULT_LATITUDE_OPTIONS), **dict(options)})
+
+        assert options.internal is not None
+        assert options.internal.gateway is not None
+        assert options.internal.source is not None
+        assert options.internal.retries is not None
+        assert options.internal.delay is not None
+        assert options.internal.timeout is not None
+
+        self._options = options
+        self._client = Client(
+            ClientOptions(
+                api_key=api_key,
+                retries=options.internal.retries,
+                delay=options.internal.delay,
+                timeout=options.internal.timeout,
+                source=options.internal.source,
+                router=RouterOptions(gateway=options.internal.gateway),
+            )
+        )
+
+        self.prompts = Prompts(self._client, self._options)
+        self.logs = Logs(self._client, self._options)
+        self.evaluations = Evaluations(self._client, self._options)
+        # TODO: Telemetry - needs Telemetry SDK in Python

latitude_sdk/sdk/logs.py

@@ -0,0 +1,66 @@
+from typing import List, Optional
+
+from latitude_sdk.client import Client, CreateLogRequestBody, CreateLogRequestParams, RequestHandler
+from latitude_sdk.sdk.errors import ApiError, ApiErrorCodes
+from latitude_sdk.sdk.types import (
+    Log,
+    Message,
+    SdkOptions,
+)
+from latitude_sdk.util import Model
+
+
+class LogOptions(Model):
+    project_id: Optional[int] = None
+    version_uuid: Optional[str] = None
+
+
+class CreateLogOptions(LogOptions, Model):
+    response: Optional[str] = None
+
+
+class CreateLogResult(Log, Model):
+    pass
+
+
+class Logs:
+    _options: SdkOptions
+    _client: Client
+
+    def __init__(self, client: Client, options: SdkOptions):
+        self._options = options
+        self._client = client
+
+    def _ensure_options(self, options: LogOptions) -> LogOptions:
+        project_id = options.project_id or self._options.project_id
+        if not project_id:
+            raise ApiError(
+                status=404,
+                code=ApiErrorCodes.NotFoundError,
+                message="Project ID is required",
+                response="Project ID is required",
+            )
+
+        version_uuid = options.version_uuid or self._options.version_uuid
+
+        return LogOptions(project_id=project_id, version_uuid=version_uuid)
+
+    async def create(self, path: str, messages: List[Message], options: CreateLogOptions) -> CreateLogResult:
+        log_options = self._ensure_options(options)
+        options = CreateLogOptions(**{**dict(options), **dict(log_options)})
+
+        assert options.project_id is not None
+
+        async with self._client.request(
+            handler=RequestHandler.CreateLog,
+            params=CreateLogRequestParams(
+                project_id=options.project_id,
+                version_uuid=options.version_uuid,
+            ),
+            body=CreateLogRequestBody(
+                path=path,
+                messages=messages,
+                response=options.response,
+            ),
+        ) as response:
+            return CreateLogResult.model_validate_json(response.content)