tracia 0.0.1__py3-none-any.whl → 0.1.0__py3-none-any.whl

tracia/resources/prompts.py

@@ -0,0 +1,273 @@
+"""Prompts API resource."""
+
+from __future__ import annotations
+
+from urllib.parse import quote
+from typing import TYPE_CHECKING, Any
+
+from .._types import (
+    CreatePromptOptions,
+    Prompt,
+    PromptListItem,
+    RunOptions,
+    RunResult,
+    UpdatePromptOptions,
+)
+
+if TYPE_CHECKING:
+    from .._http import AsyncHttpClient, HttpClient
+
+
+class Prompts:
+    """Prompts API resource for managing prompt templates."""
+
+    def __init__(
+        self,
+        client: "HttpClient",
+        async_client: "AsyncHttpClient | None" = None,
+    ) -> None:
+        """Initialize the Prompts resource.
+
+        Args:
+            client: The synchronous HTTP client.
+            async_client: Optional async HTTP client.
+        """
+        self._client = client
+        self._async_client = async_client
+
+    def list(self) -> list[PromptListItem]:
+        """List all prompts.
+
+        Returns:
+            The list of prompts.
+
+        Raises:
+            TraciaError: If the request fails.
+        """
+        data = self._client.get("/api/v1/prompts")
+        return [PromptListItem.model_validate(item) for item in data]
+
+    async def alist(self) -> list[PromptListItem]:
+        """List all prompts asynchronously.
+
+        Returns:
+            The list of prompts.
+
+        Raises:
+            TraciaError: If the request fails.
+        """
+        if self._async_client is None:
+            raise RuntimeError("Async client not initialized")
+
+        data = await self._async_client.get("/api/v1/prompts")
+        return [PromptListItem.model_validate(item) for item in data]
+
+    def get(self, slug: str) -> Prompt:
+        """Get a prompt by slug.
+
+        Args:
+            slug: The prompt slug.
+
+        Returns:
+            The prompt.
+
+        Raises:
+            TraciaError: If the request fails.
+        """
+        data = self._client.get(f"/api/v1/prompts/{quote(slug, safe='')}")
+        return Prompt.model_validate(data)
+
+    async def aget(self, slug: str) -> Prompt:
+        """Get a prompt by slug asynchronously.
+
+        Args:
+            slug: The prompt slug.
+
+        Returns:
+            The prompt.
+
+        Raises:
+            TraciaError: If the request fails.
+        """
+        if self._async_client is None:
+            raise RuntimeError("Async client not initialized")
+
+        data = await self._async_client.get(f"/api/v1/prompts/{quote(slug, safe='')}")
+        return Prompt.model_validate(data)
+
+    def create(self, options: CreatePromptOptions) -> Prompt:
+        """Create a new prompt.
+
+        Args:
+            options: The prompt creation options.
+
+        Returns:
+            The created prompt.
+
+        Raises:
+            TraciaError: If the request fails.
+        """
+        data = self._client.post(
+            "/api/v1/prompts",
+            options.model_dump(by_alias=True, exclude_none=True),
+        )
+        return Prompt.model_validate(data)
+
+    async def acreate(self, options: CreatePromptOptions) -> Prompt:
+        """Create a new prompt asynchronously.
+
+        Args:
+            options: The prompt creation options.
+
+        Returns:
+            The created prompt.
+
+        Raises:
+            TraciaError: If the request fails.
+        """
+        if self._async_client is None:
+            raise RuntimeError("Async client not initialized")
+
+        data = await self._async_client.post(
+            "/api/v1/prompts",
+            options.model_dump(by_alias=True, exclude_none=True),
+        )
+        return Prompt.model_validate(data)
+
+    def update(self, slug: str, options: UpdatePromptOptions) -> Prompt:
+        """Update an existing prompt.
+
+        Args:
+            slug: The prompt slug.
+            options: The update options.
+
+        Returns:
+            The updated prompt.
+
+        Raises:
+            TraciaError: If the request fails.
+        """
+        data = self._client.put(
+            f"/api/v1/prompts/{quote(slug, safe='')}",
+            options.model_dump(by_alias=True, exclude_none=True),
+        )
+        return Prompt.model_validate(data)
+
+    async def aupdate(self, slug: str, options: UpdatePromptOptions) -> Prompt:
+        """Update an existing prompt asynchronously.
+
+        Args:
+            slug: The prompt slug.
+            options: The update options.
+
+        Returns:
+            The updated prompt.
+
+        Raises:
+            TraciaError: If the request fails.
+        """
+        if self._async_client is None:
+            raise RuntimeError("Async client not initialized")
+
+        data = await self._async_client.put(
+            f"/api/v1/prompts/{quote(slug, safe='')}",
+            options.model_dump(by_alias=True, exclude_none=True),
+        )
+        return Prompt.model_validate(data)
+
+    def delete(self, slug: str) -> None:
+        """Delete a prompt.
+
+        Args:
+            slug: The prompt slug.
+
+        Raises:
+            TraciaError: If the request fails.
+        """
+        self._client.delete(f"/api/v1/prompts/{quote(slug, safe='')}")
+
+    async def adelete(self, slug: str) -> None:
+        """Delete a prompt asynchronously.
+
+        Args:
+            slug: The prompt slug.
+
+        Raises:
+            TraciaError: If the request fails.
+        """
+        if self._async_client is None:
+            raise RuntimeError("Async client not initialized")
+
+        await self._async_client.delete(f"/api/v1/prompts/{quote(slug, safe='')}")
+
+    def run(
+        self,
+        slug: str,
+        variables: dict[str, str] | None = None,
+        options: RunOptions | None = None,
+    ) -> RunResult:
+        """Run a prompt template.
+
+        Args:
+            slug: The prompt slug.
+            variables: Optional variables to interpolate.
+            options: Optional run options.
+
+        Returns:
+            The run result.
+
+        Raises:
+            TraciaError: If the request fails.
+        """
+        body = self._build_run_body(variables, options)
+        data = self._client.post(f"/api/v1/prompts/{quote(slug, safe='')}/run", body)
+        return RunResult.model_validate(data)
+
+    async def arun(
+        self,
+        slug: str,
+        variables: dict[str, str] | None = None,
+        options: RunOptions | None = None,
+    ) -> RunResult:
+        """Run a prompt template asynchronously.
+
+        Args:
+            slug: The prompt slug.
+            variables: Optional variables to interpolate.
+            options: Optional run options.
+
+        Returns:
+            The run result.
+
+        Raises:
+            TraciaError: If the request fails.
+        """
+        if self._async_client is None:
+            raise RuntimeError("Async client not initialized")
+
+        body = self._build_run_body(variables, options)
+        data = await self._async_client.post(f"/api/v1/prompts/{quote(slug, safe='')}/run", body)
+        return RunResult.model_validate(data)
+
+    def _build_run_body(
+        self,
+        variables: dict[str, str] | None,
+        options: RunOptions | None,
+    ) -> dict[str, Any]:
+        """Build the request body for the run endpoint."""
+        body: dict[str, Any] = {}
+
+        if variables:
+            body["variables"] = variables
+
+        if options:
+            if options.model is not None:
+                body["model"] = options.model
+            if options.tags is not None:
+                body["tags"] = options.tags
+            if options.user_id is not None:
+                body["userId"] = options.user_id
+            if options.session_id is not None:
+                body["sessionId"] = options.session_id
+
+        return body

tracia/resources/spans.py

@@ -0,0 +1,227 @@
+"""Spans API resource."""
+
+from __future__ import annotations
+
+from urllib.parse import quote
+from typing import TYPE_CHECKING, Any
+
+from .._types import (
+    CreateSpanPayload,
+    CreateSpanResult,
+    EvaluateOptions,
+    EvaluateResult,
+    ListSpansOptions,
+    ListSpansResult,
+    Span,
+)
+
+if TYPE_CHECKING:
+    from .._http import AsyncHttpClient, HttpClient
+
+
+class Spans:
+    """Spans API resource for managing trace spans."""
+
+    def __init__(
+        self,
+        client: "HttpClient",
+        async_client: "AsyncHttpClient | None" = None,
+    ) -> None:
+        """Initialize the Spans resource.
+
+        Args:
+            client: The synchronous HTTP client.
+            async_client: Optional async HTTP client.
+        """
+        self._client = client
+        self._async_client = async_client
+
+    def create(self, payload: CreateSpanPayload) -> CreateSpanResult:
+        """Create a new span.
+
+        Args:
+            payload: The span creation payload.
+
+        Returns:
+            The created span result.
+
+        Raises:
+            TraciaError: If the request fails.
+        """
+        data = self._client.post(
+            "/api/v1/spans",
+            payload.model_dump(by_alias=True, exclude_none=True),
+        )
+        return CreateSpanResult.model_validate(data)
+
+    async def acreate(self, payload: CreateSpanPayload) -> CreateSpanResult:
+        """Create a new span asynchronously.
+
+        Args:
+            payload: The span creation payload.
+
+        Returns:
+            The created span result.
+
+        Raises:
+            TraciaError: If the request fails.
+        """
+        if self._async_client is None:
+            raise RuntimeError("Async client not initialized")
+
+        data = await self._async_client.post(
+            "/api/v1/spans",
+            payload.model_dump(by_alias=True, exclude_none=True),
+        )
+        return CreateSpanResult.model_validate(data)
+
+    def get(self, span_id: str) -> Span:
+        """Get a span by ID.
+
+        Args:
+            span_id: The span ID.
+
+        Returns:
+            The span.
+
+        Raises:
+            TraciaError: If the request fails.
+        """
+        data = self._client.get(f"/api/v1/spans/{quote(span_id, safe='')}")
+        return Span.model_validate(data)
+
+    async def aget(self, span_id: str) -> Span:
+        """Get a span by ID asynchronously.
+
+        Args:
+            span_id: The span ID.
+
+        Returns:
+            The span.
+
+        Raises:
+            TraciaError: If the request fails.
+        """
+        if self._async_client is None:
+            raise RuntimeError("Async client not initialized")
+
+        data = await self._async_client.get(f"/api/v1/spans/{quote(span_id, safe='')}")
+        return Span.model_validate(data)
+
+    def list(self, options: ListSpansOptions | None = None) -> ListSpansResult:
+        """List spans with optional filtering.
+
+        Args:
+            options: Optional filtering and pagination options.
+
+        Returns:
+            The list of spans.
+
+        Raises:
+            TraciaError: If the request fails.
+        """
+        params = self._build_list_params(options)
+        data = self._client.get("/api/v1/spans", params=params)
+        return ListSpansResult.model_validate(data)
+
+    async def alist(self, options: ListSpansOptions | None = None) -> ListSpansResult:
+        """List spans asynchronously with optional filtering.
+
+        Args:
+            options: Optional filtering and pagination options.
+
+        Returns:
+            The list of spans.
+
+        Raises:
+            TraciaError: If the request fails.
+        """
+        if self._async_client is None:
+            raise RuntimeError("Async client not initialized")
+
+        params = self._build_list_params(options)
+        data = await self._async_client.get("/api/v1/spans", params=params)
+        return ListSpansResult.model_validate(data)
+
+    def _build_list_params(
+        self, options: ListSpansOptions | None
+    ) -> dict[str, Any] | None:
+        """Build query parameters for list endpoint."""
+        if options is None:
+            return None
+
+        params: dict[str, Any] = {}
+
+        if options.prompt_slug is not None:
+            params["promptSlug"] = options.prompt_slug
+        if options.status is not None:
+            params["status"] = options.status
+        if options.start_date is not None:
+            params["startDate"] = options.start_date.isoformat()
+        if options.end_date is not None:
+            params["endDate"] = options.end_date.isoformat()
+        if options.user_id is not None:
+            params["userId"] = options.user_id
+        if options.session_id is not None:
+            params["sessionId"] = options.session_id
+        if options.tags is not None and len(options.tags) > 0:
+            params["tags"] = ",".join(options.tags)
+        if options.limit is not None:
+            params["limit"] = options.limit
+        if options.cursor is not None:
+            params["cursor"] = options.cursor
+
+        return params if params else None
+
+    def evaluate(self, span_id: str, options: EvaluateOptions) -> EvaluateResult:
+        """Evaluate a span.
+
+        Args:
+            span_id: The span ID to evaluate.
+            options: The evaluation options.
+
+        Returns:
+            The evaluation result.
+
+        Raises:
+            TraciaError: If the request fails.
+        """
+        body = {
+            "evaluatorKey": options.evaluator,
+            "value": options.value,
+        }
+        if options.note is not None:
+            body["note"] = options.note
+
+        data = self._client.post(f"/api/v1/spans/{quote(span_id, safe='')}/evaluations", body)
+        return EvaluateResult.model_validate(data)
+
+    async def aevaluate(
+        self, span_id: str, options: EvaluateOptions
+    ) -> EvaluateResult:
+        """Evaluate a span asynchronously.
+
+        Args:
+            span_id: The span ID to evaluate.
+            options: The evaluation options.
+
+        Returns:
+            The evaluation result.
+
+        Raises:
+            TraciaError: If the request fails.
+        """
+        if self._async_client is None:
+            raise RuntimeError("Async client not initialized")
+
+        body = {
+            "evaluatorKey": options.evaluator,
+            "value": options.value,
+        }
+        if options.note is not None:
+            body["note"] = options.note
+
+        data = await self._async_client.post(
+            f"/api/v1/spans/{quote(span_id, safe='')}/evaluations", body
+        )
+        return EvaluateResult.model_validate(data)