tracia 0.1.0__tar.gz → 0.2.0__tar.gz

{tracia-0.1.0 → tracia-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tracia
-Version: 0.1.0
+Version: 0.2.0
 Summary: LLM prompt management and tracing SDK
 Project-URL: Homepage, https://tracia.io
 Project-URL: Documentation, https://docs.tracia.io

{tracia-0.1.0 → tracia-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "tracia"
-version = "0.1.0"
+version = "0.2.0"
 description = "LLM prompt management and tracing SDK"
 readme = "README.md"
 license = "MIT"

{tracia-0.1.0 → tracia-0.2.0}/tracia/__init__.py

@@ -66,6 +66,7 @@ from ._types import (
     PromptListItem,
     PromptMessage,
     PromptVersion,
+    ResponseFormatJsonSchema,
     ResponsesEvent,
     ResponsesFunctionCall,
     ResponsesFunctionCallOutput,
@@ -81,6 +82,7 @@ from ._types import (
     RunResponsesResult,
     RunResult,
     Span,
+    SpanListItem,
     StreamResult,
     TextPart,
     TokenUsage,
@@ -120,6 +122,8 @@ __all__ = [
     "JsonSchemaProperty",
     "ToolCall",
     "ToolChoice",
+    # Types - Response Format
+    "ResponseFormatJsonSchema",
     # Types - Run Local
     "RunLocalInput",
     "RunLocalResult",
@@ -139,6 +143,7 @@ __all__ = [
     "CreateSpanPayload",
     "CreateSpanResult",
     "Span",
+    "SpanListItem",
     "ListSpansOptions",
     "ListSpansResult",
     "EvaluateOptions",

{tracia-0.1.0 → tracia-0.2.0}/tracia/_client.py

@@ -20,13 +20,14 @@ from ._constants import (
 )
 from ._errors import TraciaError, TraciaErrorCode, sanitize_error_message
 from ._http import AsyncHttpClient, HttpClient
-from ._llm import LLMClient, build_assistant_message, resolve_provider
+from ._llm import LLMClient, build_assistant_message, convert_response_format, resolve_provider
 from ._session import TraciaSession
 from ._streaming import AsyncLocalStream, LocalStream
 from ._types import (
     CreateSpanPayload,
     LocalPromptMessage,
     LLMProvider,
+    ResponseFormat,
     RunLocalResult,
     StreamResult,
     TokenUsage,
@@ -263,6 +264,7 @@ class Tracia:
         span_id: str | None = None,
         tools: list[ToolDefinition] | None = None,
         tool_choice: ToolChoice | None = None,
+        response_format: ResponseFormat | None = None,
         trace_id: str | None = None,
         parent_span_id: str | None = None,
     ) -> RunLocalResult: ...
@@ -289,6 +291,7 @@ class Tracia:
         span_id: str | None = None,
         tools: list[ToolDefinition] | None = None,
         tool_choice: ToolChoice | None = None,
+        response_format: ResponseFormat | None = None,
         trace_id: str | None = None,
         parent_span_id: str | None = None,
     ) -> LocalStream: ...
@@ -314,6 +317,7 @@ class Tracia:
         span_id: str | None = None,
         tools: list[ToolDefinition] | None = None,
         tool_choice: ToolChoice | None = None,
+        response_format: ResponseFormat | None = None,
         trace_id: str | None = None,
         parent_span_id: str | None = None,
     ) -> RunLocalResult | LocalStream:
@@ -361,6 +365,8 @@ class Tracia:
         # Calculate timeout
         timeout_seconds = (timeout_ms or DEFAULT_TIMEOUT_MS) / 1000.0
 
+        litellm_response_format = convert_response_format(response_format)
+
         if stream:
             return self._run_local_streaming(
                 messages=prompt_messages,
@@ -382,6 +388,7 @@ class Tracia:
                 tools=tools,
                 tool_choice=tool_choice,
                 variables=variables,
+                response_format=litellm_response_format,
             )
         else:
             return self._run_local_non_streaming(
@@ -404,6 +411,7 @@ class Tracia:
                 tools=tools,
                 tool_choice=tool_choice,
                 variables=variables,
+                response_format=litellm_response_format,
             )
 
     def _run_local_non_streaming(
@@ -428,6 +436,7 @@ class Tracia:
         tools: list[ToolDefinition] | None,
         tool_choice: ToolChoice | None,
         variables: dict[str, str] | None,
+        response_format: dict[str, Any] | None = None,
     ) -> RunLocalResult:
         """Run local prompt without streaming."""
         start_time = time.time()
@@ -451,6 +460,7 @@ class Tracia:
                 tool_choice=tool_choice,
                 api_key=provider_api_key,
                 timeout=timeout,
+                response_format=response_format,
             )
 
             result_text = completion.text
@@ -537,6 +547,7 @@ class Tracia:
         tools: list[ToolDefinition] | None,
         tool_choice: ToolChoice | None,
         variables: dict[str, str] | None,
+        response_format: dict[str, Any] | None = None,
     ) -> LocalStream:
         """Run local prompt with streaming."""
         start_time = time.time()
@@ -555,6 +566,7 @@ class Tracia:
             tool_choice=tool_choice,
             api_key=provider_api_key,
             timeout=timeout,
+            response_format=response_format,
         )
 
         def wrapped_chunks():
@@ -660,6 +672,7 @@ class Tracia:
         span_id: str | None = None,
         tools: list[ToolDefinition] | None = None,
         tool_choice: ToolChoice | None = None,
+        response_format: ResponseFormat | None = None,
         trace_id: str | None = None,
         parent_span_id: str | None = None,
     ) -> RunLocalResult: ...
@@ -686,6 +699,7 @@ class Tracia:
         span_id: str | None = None,
         tools: list[ToolDefinition] | None = None,
         tool_choice: ToolChoice | None = None,
+        response_format: ResponseFormat | None = None,
         trace_id: str | None = None,
         parent_span_id: str | None = None,
     ) -> AsyncLocalStream: ...
@@ -711,6 +725,7 @@ class Tracia:
         span_id: str | None = None,
         tools: list[ToolDefinition] | None = None,
         tool_choice: ToolChoice | None = None,
+        response_format: ResponseFormat | None = None,
         trace_id: str | None = None,
         parent_span_id: str | None = None,
     ) -> RunLocalResult | AsyncLocalStream:
@@ -732,6 +747,8 @@ class Tracia:
         # Calculate timeout
         timeout_seconds = (timeout_ms or DEFAULT_TIMEOUT_MS) / 1000.0
 
+        litellm_response_format = convert_response_format(response_format)
+
         if stream:
             return await self._arun_local_streaming(
                 messages=prompt_messages,
@@ -753,6 +770,7 @@ class Tracia:
                 tools=tools,
                 tool_choice=tool_choice,
                 variables=variables,
+                response_format=litellm_response_format,
             )
         else:
             return await self._arun_local_non_streaming(
@@ -775,6 +793,7 @@ class Tracia:
                 tools=tools,
                 tool_choice=tool_choice,
                 variables=variables,
+                response_format=litellm_response_format,
             )
 
     async def _arun_local_non_streaming(
@@ -799,6 +818,7 @@ class Tracia:
         tools: list[ToolDefinition] | None,
         tool_choice: ToolChoice | None,
         variables: dict[str, str] | None,
+        response_format: dict[str, Any] | None = None,
     ) -> RunLocalResult:
         """Run local prompt without streaming (async)."""
         start_time = time.time()
@@ -823,6 +843,7 @@ class Tracia:
                 tool_choice=tool_choice,
                 api_key=provider_api_key,
                 timeout=timeout,
+                response_format=response_format,
             )
 
             result_text = completion.text
@@ -909,6 +930,7 @@ class Tracia:
         tools: list[ToolDefinition] | None,
         tool_choice: ToolChoice | None,
         variables: dict[str, str] | None,
+        response_format: dict[str, Any] | None = None,
     ) -> AsyncLocalStream:
         """Run local prompt with streaming (async)."""
         start_time = time.time()
@@ -928,6 +950,7 @@ class Tracia:
             tool_choice=tool_choice,
             api_key=provider_api_key,
             timeout=timeout,
+            response_format=response_format,
         )
 
         async def wrapped_chunks():

{tracia-0.1.0 → tracia-0.2.0}/tracia/_constants.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 # SDK Version (defined here to avoid circular imports)
-SDK_VERSION = "0.1.0"
+SDK_VERSION = "0.2.0"
 
 # API Configuration
 BASE_URL = "https://app.tracia.io"

{tracia-0.1.0 → tracia-0.2.0}/tracia/_llm.py

@@ -14,6 +14,7 @@ from ._types import (
     FinishReason,
     LLMProvider,
     LocalPromptMessage,
+    ResponseFormatJsonSchema,
     TextPart,
     ToolCall,
     ToolCallPart,
@@ -284,6 +285,49 @@ def convert_tool_choice(tool_choice: ToolChoice | None) -> str | dict[str, Any]
     return None
 
 
+def convert_response_format(
+    response_format: dict[str, Any] | ResponseFormatJsonSchema | None,
+) -> dict[str, Any] | None:
+    """Convert a Tracia response format to LiteLLM format.
+
+    Args:
+        response_format: The Tracia response format.
+
+    Returns:
+        Response format in LiteLLM/OpenAI format, or None.
+    """
+    if response_format is None:
+        return None
+
+    if isinstance(response_format, ResponseFormatJsonSchema):
+        schema = response_format.schema_
+        name = response_format.name or "response"
+        json_schema: dict[str, Any] = {"name": name, "schema": schema}
+        if response_format.description is not None:
+            json_schema["description"] = response_format.description
+        return {"type": "json_schema", "json_schema": json_schema}
+
+    # Plain dict — check for our simplified format
+    if isinstance(response_format, dict):
+        fmt_type = response_format.get("type")
+        schema = response_format.get("schema")
+
+        if fmt_type == "json" and schema is not None:
+            name = response_format.get("name", "response")
+            json_schema: dict[str, Any] = {"name": name, "schema": schema}
+            description = response_format.get("description")
+            if description is not None:
+                json_schema["description"] = description
+            return {"type": "json_schema", "json_schema": json_schema}
+
+        if fmt_type == "json":
+            return {"type": "json_object"}
+
+        return response_format
+
+    return None
+
+
 def parse_finish_reason(reason: str | None) -> FinishReason:
     """Parse the finish reason from LiteLLM response.
 
@@ -357,6 +401,7 @@ class LLMClient:
         tool_choice: ToolChoice | None = None,
         api_key: str | None = None,
         timeout: float | None = None,
+        response_format: dict[str, Any] | None = None,
     ) -> CompletionResult:
         """Make a synchronous completion request.
 
@@ -415,6 +460,8 @@ class LLMClient:
             request_kwargs["tool_choice"] = litellm_tool_choice
         if timeout is not None:
             request_kwargs["timeout"] = timeout
+        if response_format is not None:
+            request_kwargs["response_format"] = response_format
 
         try:
             response = litellm.completion(**request_kwargs)
@@ -456,6 +503,7 @@ class LLMClient:
         tool_choice: ToolChoice | None = None,
         api_key: str | None = None,
         timeout: float | None = None,
+        response_format: dict[str, Any] | None = None,
     ) -> CompletionResult:
         """Make an asynchronous completion request.
 
@@ -514,6 +562,8 @@ class LLMClient:
             request_kwargs["tool_choice"] = litellm_tool_choice
         if timeout is not None:
             request_kwargs["timeout"] = timeout
+        if response_format is not None:
+            request_kwargs["response_format"] = response_format
 
         try:
             response = await litellm.acompletion(**request_kwargs)
@@ -555,6 +605,7 @@ class LLMClient:
         tool_choice: ToolChoice | None = None,
         api_key: str | None = None,
         timeout: float | None = None,
+        response_format: dict[str, Any] | None = None,
     ) -> tuple[Iterator[str], list[CompletionResult], LLMProvider]:
         """Make a streaming completion request.
 
@@ -614,6 +665,8 @@ class LLMClient:
             request_kwargs["tool_choice"] = litellm_tool_choice
         if timeout is not None:
             request_kwargs["timeout"] = timeout
+        if response_format is not None:
+            request_kwargs["response_format"] = response_format
 
         result_holder: list[CompletionResult] = []
 
@@ -717,6 +770,7 @@ class LLMClient:
         tool_choice: ToolChoice | None = None,
         api_key: str | None = None,
         timeout: float | None = None,
+        response_format: dict[str, Any] | None = None,
     ) -> tuple[AsyncIterator[str], list[CompletionResult], LLMProvider]:
         """Make an async streaming completion request.
 
@@ -776,6 +830,8 @@ class LLMClient:
             request_kwargs["tool_choice"] = litellm_tool_choice
         if timeout is not None:
             request_kwargs["timeout"] = timeout
+        if response_format is not None:
+            request_kwargs["response_format"] = response_format
 
         result_holder: list[CompletionResult] = []
 

{tracia-0.1.0 → tracia-0.2.0}/tracia/_types.py

@@ -90,6 +90,26 @@ class ToolCall(BaseModel):
 ToolChoice = Union[Literal["auto", "none", "required"], dict[str, str]]
 
 
+# Response Format
+
+
+class ResponseFormatJsonSchema(BaseModel):
+    """JSON schema response format for structured outputs."""
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    type: Literal["json"] = "json"
+    schema_: dict[str, Any] = Field(alias="schema")
+    name: str | None = None
+    description: str | None = None
+
+
+ResponseFormat = Union[
+    dict[str, Any],
+    ResponseFormatJsonSchema,
+]
+
+
 # Messages
 
 
@@ -134,6 +154,7 @@ class RunLocalInput(BaseModel):
     span_id: str | None = Field(default=None, alias="spanId")
     tools: list[ToolDefinition] | None = None
     tool_choice: ToolChoice | None = Field(default=None, alias="toolChoice")
+    response_format: ResponseFormat | None = Field(default=None, alias="responseFormat")
     trace_id: str | None = Field(default=None, alias="traceId")
     parent_span_id: str | None = Field(default=None, alias="parentSpanId")
 
@@ -347,8 +368,27 @@ class CreateSpanResult(BaseModel):
     trace_id: str = Field(alias="traceId")
 
 
+class SpanListItem(BaseModel):
+    """A span item from the list endpoint (reduced fields)."""
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    id: str
+    span_id: str = Field(alias="spanId")
+    trace_id: str = Field(alias="traceId")
+    prompt_slug: str | None = Field(default=None, alias="promptSlug")
+    model: str
+    status: Literal["SUCCESS", "ERROR"]
+    latency_ms: int = Field(alias="latencyMs")
+    input_tokens: int = Field(alias="inputTokens")
+    output_tokens: int = Field(alias="outputTokens")
+    total_tokens: int = Field(alias="totalTokens")
+    cost: float | None = None
+    created_at: datetime = Field(alias="createdAt")
+
+
 class Span(BaseModel):
-    """A span from the API."""
+    """A span from the API (full detail)."""
 
     model_config = ConfigDict(populate_by_name=True)
 
@@ -397,7 +437,7 @@ class ListSpansResult(BaseModel):
 
     model_config = ConfigDict(populate_by_name=True)
 
-    spans: list[Span]
+    spans: list[SpanListItem]
     cursor: str | None = None
     has_more: bool = Field(default=False, alias="hasMore")
 
@@ -433,6 +473,7 @@ class EvaluateResult(BaseModel):
 class PromptMessage(BaseModel):
     """A message in a prompt template."""
 
+    id: str
     role: Literal["system", "developer", "user", "assistant"]
     content: str
 
@@ -487,12 +528,12 @@ class CreatePromptOptions(BaseModel):
 
     model_config = ConfigDict(populate_by_name=True)
 
-    slug: str
     name: str
+    slug: str | None = None
     description: str | None = None
-    messages: list[PromptMessage]
-    model: str
-    provider: LLMProvider
+    content: list[PromptMessage]
+    model: str | None = None
+    provider: LLMProvider | None = None
     temperature: float | None = None
     max_output_tokens: int | None = Field(default=None, alias="maxOutputTokens")
     top_p: float | None = Field(default=None, alias="topP")
@@ -505,8 +546,9 @@ class UpdatePromptOptions(BaseModel):
     model_config = ConfigDict(populate_by_name=True)
 
     name: str | None = None
+    slug: str | None = None
     description: str | None = None
-    messages: list[PromptMessage] | None = None
+    content: list[PromptMessage] | None = None
     model: str | None = None
     provider: LLMProvider | None = None
     temperature: float | None = None
@@ -531,10 +573,13 @@ class RunResult(BaseModel):
 
     model_config = ConfigDict(populate_by_name=True)
 
-    text: str
+    text: str | None = None
     span_id: str = Field(alias="spanId")
     trace_id: str = Field(alias="traceId")
     prompt_version: int = Field(alias="promptVersion")
     latency_ms: int = Field(alias="latencyMs")
     usage: TokenUsage
     cost: float
+    finish_reason: FinishReason | None = Field(default=None, alias="finishReason")
+    tool_calls: list[ToolCall] | None = Field(default=None, alias="toolCalls")
+    structured_output: dict[str, Any] | None = Field(default=None, alias="structuredOutput")

{tracia-0.1.0 → tracia-0.2.0}/tracia/resources/prompts.py

@@ -45,7 +45,7 @@ class Prompts:
             TraciaError: If the request fails.
         """
         data = self._client.get("/api/v1/prompts")
-        return [PromptListItem.model_validate(item) for item in data]
+        return [PromptListItem.model_validate(item) for item in data["prompts"]]
 
     async def alist(self) -> list[PromptListItem]:
         """List all prompts asynchronously.
@@ -60,7 +60,7 @@ class Prompts:
             raise RuntimeError("Async client not initialized")
 
         data = await self._async_client.get("/api/v1/prompts")
-        return [PromptListItem.model_validate(item) for item in data]
+        return [PromptListItem.model_validate(item) for item in data["prompts"]]
 
     def get(self, slug: str) -> Prompt:
         """Get a prompt by slug.