langwatch 0.2.19__py3-none-any.whl → 0.3.1__py3-none-any.whl

langwatch/prompts/prompt.py

@@ -1,13 +1,12 @@
-from typing import List, Any, Dict, Union, Optional, cast
-from openai.types.chat import ChatCompletionMessageParam
+from typing import List, Any, Dict, Union, Optional, cast, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from openai.types.chat import ChatCompletionMessageParam
+
 from liquid import Environment, StrictUndefined, Undefined
 from liquid.exceptions import UndefinedError
-from langwatch.generated.langwatch_rest_api_client.models.get_api_prompts_by_id_response_200 import (
-    GetApiPromptsByIdResponse200,
-)
-from .formatter import PromptFormatter
 from .decorators.prompt_tracing import prompt_tracing
-from .types import MessageDict
+from .types import PromptData, MessageDict
 
 
 class PromptCompilationError(Exception):
@@ -34,31 +33,30 @@ class Prompt:
     Handles formatting messages with variables using Liquid templating.
     """
 
-    def __init__(
-        self,
-        config: GetApiPromptsByIdResponse200,
-        formatter: PromptFormatter = PromptFormatter(),
-    ):
-        self._config = config
-        self._formatter = formatter
+    def __init__(self, data: PromptData):
+        # Store raw data for backward compatibility
+        self._data = data.copy()
 
-    def __getattr__(self, name: str) -> Any:
-        """Delegate attribute access to the underlying config object"""
-        if hasattr(self._config, name):
-            return getattr(self._config, name)
-        raise AttributeError(
-            f"'{self.__class__.__name__}' object has no attribute '{name}'"
-        )
+        # Assign all fields directly as instance attributes
+        for key, value in data.items():
+            setattr(self, key, value)
 
-    @property
-    def raw(self) -> Any:
-        """Get the raw prompt data from the API"""
-        return self._config
+        # Set prompt default only if not provided (like TypeScript)
+        if not hasattr(self, "prompt") or self.prompt is None:
+            self.prompt = self._extract_system_prompt()
 
     @property
-    def version_number(self) -> int:
-        """Returns the version number of the prompt."""
-        return int(self._config.version)
+    def raw(self) -> PromptData:
+        """Get the raw prompt data"""
+        return self._data
+
+    def _extract_system_prompt(self) -> str:
+        """Extract system prompt from messages, like TypeScript version."""
+        if hasattr(self, "messages") and self.messages:
+            for message in self.messages:
+                if message.get("role") == "system":
+                    return message.get("content", "")
+        return ""
 
     def _compile(self, variables: TemplateVariables, strict: bool) -> "CompiledPrompt":
         """
@@ -70,19 +68,19 @@ class Prompt:
 
             # Compile main prompt
             compiled_prompt = ""
-            if self._config.prompt:
-                template = env.from_string(self._config.prompt)
+            if hasattr(self, "prompt") and self.prompt:
+                template = env.from_string(self.prompt)
                 compiled_prompt = template.render(**variables)
 
             # Compile messages
             compiled_messages: List[MessageDict] = []
-            if self._config.messages:
-                for message in self._config.messages:
-                    content: str = message.content
+            if hasattr(self, "messages") and self.messages:
+                for message in self.messages:
+                    content: str = message["content"]
                     template = env.from_string(content)
                     compiled_content = template.render(**variables)
                     compiled_message = MessageDict(
-                        role=message.role.value,
+                        role=message["role"],
                         content=compiled_content,
                     )
                     compiled_messages.append(compiled_message)
@@ -96,12 +94,16 @@ class Prompt:
             )
 
         except UndefinedError as error:
-            template_str = self._config.prompt or str(self._config.messages or [])
+            template_str = getattr(self, "prompt", "") or str(
+                getattr(self, "messages", [])
+            )
             raise PromptCompilationError(
                 f"Failed to compile prompt template: {str(error)}", template_str, error
             )
         except Exception as error:
-            template_str = self._config.prompt or str(self._config.messages or [])
+            template_str = getattr(self, "prompt", "") or str(
+                getattr(self, "messages", [])
+            )
             raise PromptCompilationError(
                 f"Failed to compile prompt template: {str(error)}", template_str, error
             )
@@ -168,21 +170,17 @@ class CompiledPrompt:
         self.variables = variables  # Store the original compilation variables
         self._compiled_messages = compiled_messages
 
-        # Expose original prompt properties for convenience
-        self.id = original_prompt.id
-        self.version = original_prompt.version
-        self.version_id = original_prompt.version_id
-        # ... other properties as needed
+        # Properties are delegated via __getattr__ below
 
     @property
-    def messages(self) -> List[ChatCompletionMessageParam]:
+    def messages(self) -> List["ChatCompletionMessageParam"]:
         """
         Returns the compiled messages as a list of ChatCompletionMessageParam objects.
         This is a convenience method to make the messages accessible as a list of
         ChatCompletionMessageParam objects, which is the format expected by the OpenAI API.
         """
         messages = [
-            cast(ChatCompletionMessageParam, msg) for msg in self._compiled_messages
+            cast("ChatCompletionMessageParam", msg) for msg in self._compiled_messages
         ]
 
         return messages

langwatch/prompts/{service.py → prompt_api_service.py}

@@ -1,12 +1,14 @@
-# src/langwatch/prompt/service.py
+# src/langwatch/prompts/prompt_api_service.py
 """
-Service layer for managing LangWatch prompts via REST API.
+API service layer for managing LangWatch prompts via REST API.
 
-This module provides a high-level interface for CRUD operations on prompts,
+This module provides a focused interface for CRUD operations on prompts via API only,
 handling API communication, error handling, and response unwrapping.
 Uses TypedDict for clean interfaces and from_dict methods for type safety.
+
+This service is responsible only for API operations and does not handle local file loading.
 """
-from typing import Dict, List, Literal, Optional, Any, TypedDict
+from typing import Dict, List, Literal, Optional, Any
 from langwatch.generated.langwatch_rest_api_client.types import UNSET
 from langwatch.generated.langwatch_rest_api_client.client import (
     Client as LangWatchRestApiClient,
@@ -60,36 +62,28 @@ from langwatch.generated.langwatch_rest_api_client.models.delete_api_prompts_by_
 
 from langwatch.utils.initialization import ensure_setup
 from langwatch.state import get_instance
-from .prompt import Prompt
 from .errors import unwrap_response
 from .decorators.prompt_service_tracing import prompt_service_tracing
-from .types import MessageDict, InputDict, OutputDict
-
-
-def _convert_api_response_to_get_format(response: Any) -> GetApiPromptsByIdResponse200:
-    """Convert any API response to GetApiPromptsByIdResponse200 format using from_dict."""
-    if isinstance(response, GetApiPromptsByIdResponse200):
-        return response
+from .types import PromptData, MessageDict, InputDict, OutputDict
 
-    # All response types have the same structure, so we can convert via dict
-    return GetApiPromptsByIdResponse200.from_dict(response.to_dict())
 
-
-class PromptService:
+class PromptApiService:
     """
-    Service for managing LangWatch prompts via REST API.
+    API service for managing LangWatch prompts via REST API only.
 
     Provides CRUD operations for prompts with proper error handling and response
     unwrapping. Uses TypedDict interfaces for clean, type-safe API.
+
+    This service handles only API operations and does not handle local file loading.
     """
 
     def __init__(self, rest_api_client: LangWatchRestApiClient):
-        """Initialize the prompt service with a REST API client."""
+        """Initialize the prompt API service with a REST API client."""
         self._client = rest_api_client
 
     @classmethod
-    def from_global(cls) -> "PromptService":
-        """Create a PromptService instance using the global LangWatch configuration."""
+    def from_global(cls) -> "PromptApiService":
+        """Create a PromptApiService instance using the global LangWatch configuration."""
         ensure_setup()
         instance = get_instance()
         if instance is None:
@@ -99,8 +93,8 @@ class PromptService:
         return cls(instance.rest_api_client)
 
     @prompt_service_tracing.get
-    def get(self, prompt_id: str, version_number: Optional[int] = None) -> Prompt:
-        """Retrieve a prompt by its ID. You can optionally specify a version number to get a specific version of the prompt."""
+    def get(self, prompt_id: str, version_number: Optional[int] = None) -> PromptData:
+        """Retrieve a prompt by its ID from the API. You can optionally specify a version number to get a specific version of the prompt."""
         resp = get_api_prompts_by_id.sync_detailed(
             id=prompt_id,
             client=self._client,
@@ -116,7 +110,7 @@ class PromptService:
             raise RuntimeError(
                 f"Failed to fetch prompt with handle_or_id={prompt_id} version={version_number if version_number is not None else 'latest'}"
             )
-        return Prompt(ok)
+        return PromptData.from_api_response(ok)
 
     def create(
         self,
@@ -127,7 +121,7 @@ class PromptService:
         messages: Optional[List[MessageDict]] = None,
         inputs: Optional[List[InputDict]] = None,
         outputs: Optional[List[OutputDict]] = None,
-    ) -> Prompt:
+    ) -> PromptData:
         """
         Create a new prompt with clean dictionary interfaces.
 
@@ -141,7 +135,7 @@ class PromptService:
             outputs: List of output dicts with 'identifier', 'type', and optional 'json_schema' keys
 
         Returns:
-            Prompt object containing the created prompt data
+            PromptData dictionary containing the created prompt data
         """
         # Convert dicts to API models using from_dict
         api_messages = UNSET
@@ -181,9 +175,7 @@ class PromptService:
         if ok is None:
             raise RuntimeError(f"Failed to create prompt with handle={handle}")
 
-        # Convert response to expected format for Prompt class
-        converted = _convert_api_response_to_get_format(ok)
-        return Prompt(converted)
+        return PromptData.from_api_response(ok)
 
     def update(
         self,
@@ -194,7 +186,7 @@ class PromptService:
         messages: Optional[List[MessageDict]] = None,
         inputs: Optional[List[InputDict]] = None,
         outputs: Optional[List[OutputDict]] = None,
-    ) -> Prompt:
+    ) -> PromptData:
         """
         Update an existing prompt with clean dictionary interfaces.
 
@@ -208,7 +200,7 @@ class PromptService:
             outputs: New list of output dicts
 
         Returns:
-            Prompt object containing the updated prompt data
+            PromptData dictionary containing the updated prompt data
         """
         # Convert dicts to API models using from_dict
         api_messages = UNSET
@@ -253,9 +245,7 @@ class PromptService:
         if ok is None:
             raise RuntimeError(f"Failed to update prompt with id={prompt_id_or_handle}")
 
-        # Convert response to expected format for Prompt class
-        converted = _convert_api_response_to_get_format(ok)
-        return Prompt(converted)
+        return PromptData.from_api_response(ok)
 
     def delete(self, prompt_id: str) -> Dict[str, bool]:
         """Delete a prompt by its ID."""

langwatch/prompts/prompt_facade.py

@@ -0,0 +1,139 @@
+# src/langwatch/prompts/service.py
+"""
+Facade service for managing LangWatch prompts with guaranteed availability.
+
+This module provides a high-level interface that tries local file loading first,
+then falls back to API operations. This ensures prompts work even when offline
+or when API is unavailable.
+
+Follows the facade pattern to coordinate between LocalPromptLoader and PromptApiService.
+"""
+from typing import Dict, List, Literal, Optional
+from langwatch.generated.langwatch_rest_api_client.client import (
+    Client as LangWatchRestApiClient,
+)
+
+from langwatch.utils.initialization import ensure_setup
+from langwatch.state import get_instance
+from .prompt import Prompt
+from .prompt_api_service import PromptApiService
+from .local_loader import LocalPromptLoader
+from .types import MessageDict, InputDict, OutputDict
+
+
+class PromptsFacade:
+    """
+    Facade service for managing LangWatch prompts with guaranteed availability.
+
+    Provides CRUD operations for prompts with local-first loading and API fallback.
+    Coordinates between LocalPromptLoader and PromptApiService to ensure prompts
+    work even when offline or when API is unavailable.
+    """
+
+    def __init__(self, rest_api_client: LangWatchRestApiClient):
+        """Initialize the prompt service facade with dependencies."""
+        self._api_service = PromptApiService(rest_api_client)
+        self._local_loader = LocalPromptLoader()
+
+    @classmethod
+    def from_global(cls) -> "PromptsFacade":
+        """Create a PromptsFacade instance using the global LangWatch configuration."""
+        ensure_setup()
+        instance = get_instance()
+        if instance is None:
+            raise RuntimeError(
+                "LangWatch client has not been initialized. Call setup() first."
+            )
+        return cls(instance.rest_api_client)
+
+    def get(self, prompt_id: str, version_number: Optional[int] = None) -> Prompt:
+        """
+        Retrieve a prompt by its ID with guaranteed availability.
+
+        Tries local files first, then falls back to API.
+        You can optionally specify a version number to get a specific version of the prompt.
+        """
+        # Try to load from local files first
+        local_data = self._local_loader.load_prompt(prompt_id)
+        if local_data is not None:
+            return Prompt(local_data)
+
+        # Fall back to API if not found locally
+        api_data = self._api_service.get(prompt_id, version_number)
+        return Prompt(api_data)
+
+    def create(
+        self,
+        handle: str,
+        author_id: Optional[str] = None,
+        scope: Literal["PROJECT", "ORGANIZATION"] = "PROJECT",
+        prompt: Optional[str] = None,
+        messages: Optional[List[MessageDict]] = None,
+        inputs: Optional[List[InputDict]] = None,
+        outputs: Optional[List[OutputDict]] = None,
+    ) -> Prompt:
+        """
+        Create a new prompt via API.
+
+        Args:
+            handle: Unique identifier for the prompt
+            author_id: ID of the author
+            scope: Scope of the prompt ('PROJECT' or 'ORGANIZATION')
+            prompt: The prompt text content
+            messages: List of message dicts with 'role' and 'content' keys
+            inputs: List of input dicts with 'identifier' and 'type' keys
+            outputs: List of output dicts with 'identifier', 'type', and optional 'json_schema' keys
+
+        Returns:
+            Prompt object containing the created prompt data
+        """
+        data = self._api_service.create(
+            handle=handle,
+            author_id=author_id,
+            scope=scope,
+            prompt=prompt,
+            messages=messages,
+            inputs=inputs,
+            outputs=outputs,
+        )
+        return Prompt(data)
+
+    def update(
+        self,
+        prompt_id_or_handle: str,
+        scope: Literal["PROJECT", "ORGANIZATION"],
+        handle: Optional[str] = None,
+        prompt: Optional[str] = None,
+        messages: Optional[List[MessageDict]] = None,
+        inputs: Optional[List[InputDict]] = None,
+        outputs: Optional[List[OutputDict]] = None,
+    ) -> Prompt:
+        """
+        Update an existing prompt via API.
+
+        Args:
+            prompt_id_or_handle: ID or handle of the prompt to update
+            scope: Scope of the prompt
+            handle: New handle for the prompt
+            prompt: New prompt text content
+            messages: New list of message dicts
+            inputs: New list of input dicts
+            outputs: New list of output dicts
+
+        Returns:
+            Prompt object containing the updated prompt data
+        """
+        data = self._api_service.update(
+            prompt_id_or_handle=prompt_id_or_handle,
+            scope=scope,
+            handle=handle,
+            prompt=prompt,
+            messages=messages,
+            inputs=inputs,
+            outputs=outputs,
+        )
+        return Prompt(data)
+
+    def delete(self, prompt_id: str) -> Dict[str, bool]:
+        """Delete a prompt by its ID via API."""
+        return self._api_service.delete(prompt_id)

langwatch/prompts/types/__init__.py

@@ -0,0 +1,27 @@
+"""
+Type definitions for the prompts module.
+
+This module contains all type definitions used across the prompts system,
+organized by their purpose and scope.
+"""
+
+# Core prompt data structure
+from .prompt_data import PromptData
+
+# Standardized data structures
+from .structures import (
+    MessageDict,
+    InputDict,
+    OutputDict,
+    ResponseFormatDict,
+)
+
+__all__ = [
+    # Core types
+    "PromptData",
+    # API types
+    "MessageDict",
+    "InputDict",
+    "OutputDict",
+    "ResponseFormatDict",
+]

langwatch/prompts/types/prompt_data.py

@@ -0,0 +1,93 @@
+"""
+Core PromptData structure for prompts.
+
+This module contains only the PromptData TypedDict with conversion methods,
+following the TypeScript PromptData interface structure.
+"""
+
+from typing import TypedDict, Literal, Optional, List, Union
+
+from langwatch.generated.langwatch_rest_api_client.models.get_api_prompts_by_id_response_200 import (
+    GetApiPromptsByIdResponse200,
+)
+from langwatch.generated.langwatch_rest_api_client.models.put_api_prompts_by_id_response_200 import (
+    PutApiPromptsByIdResponse200,
+)
+from langwatch.generated.langwatch_rest_api_client.models.post_api_prompts_response_200 import (
+    PostApiPromptsResponse200,
+)
+
+from .structures import MessageDict, ResponseFormatDict
+
+
+class PromptData(TypedDict, total=False):
+    """
+    Core data structure for prompts, matching the TypeScript PromptData interface.
+
+    Contains both core functionality fields and optional metadata for identification/tracing.
+    """
+
+    # === Core functionality (required) ===
+    model: str
+    messages: List[MessageDict]  # Use standardized message structure
+
+    # === Optional core fields ===
+    prompt: Optional[str]
+    temperature: Optional[float]
+    max_tokens: Optional[int]  # Note: using snake_case to match Python conventions
+    response_format: Optional[ResponseFormatDict]  # Use standardized response format
+
+    # === Optional identification (for tracing) ===
+    id: Optional[str]
+    handle: Optional[str]
+    version: Optional[int]
+    version_id: Optional[str]
+    scope: Optional[Literal["PROJECT", "ORGANIZATION"]]
+
+    @staticmethod
+    def from_api_response(
+        response: Union[
+            GetApiPromptsByIdResponse200,
+            PutApiPromptsByIdResponse200,
+            PostApiPromptsResponse200,
+        ],
+    ) -> "PromptData":
+        """
+        Create PromptData from API response object.
+
+        Args:
+            response: GetApiPromptsByIdResponse200 object from API
+
+        Returns:
+            PromptData dictionary with converted fields
+        """
+        # Import standardized structures here to avoid circular imports
+        from .structures import MessageDict, ResponseFormatDict
+
+        messages = []
+        if response.messages:
+            messages = [
+                MessageDict(role=msg.role.value, content=msg.content)
+                for msg in response.messages
+            ]
+
+        # Convert response format if present
+        response_format = None
+        if hasattr(response, "response_format") and response.response_format:
+            response_format = ResponseFormatDict(
+                type="json_schema", json_schema=response.response_format
+            )
+
+        return PromptData(
+            id=response.id,
+            handle=response.handle,
+            model=response.model,
+            messages=messages,
+            prompt=response.prompt,
+            temperature=response.temperature,
+            max_tokens=response.max_tokens,
+            response_format=response_format,
+            version=response.version,
+            version_id=response.version_id,
+            scope=response.scope.value if response.scope else None,
+        )

langwatch/prompts/types/structures.py

@@ -0,0 +1,37 @@
+"""
+API-related types and structures for prompts.
+
+Contains TypedDict classes that match the API structure for messages,
+inputs, outputs, and response formats.
+"""
+
+from typing import TypedDict, Literal, Optional, Dict, Any
+
+
+class MessageDict(TypedDict):
+    """Message dictionary that matches the API structure."""
+
+    role: Literal["system", "user", "assistant"]
+    content: str
+
+
+class InputDict(TypedDict):
+    """Input dictionary that matches the API structure."""
+
+    identifier: str
+    type: Literal["str", "int", "float", "bool", "json"]
+
+
+class OutputDict(TypedDict):
+    """Output dictionary that matches the API structure."""
+
+    identifier: str
+    type: Literal["str", "int", "float", "bool", "json"]
+    json_schema: Optional[Dict[str, Any]]
+
+
+class ResponseFormatDict(TypedDict, total=False):
+    """Response format dictionary for structured outputs."""
+
+    type: Literal["json_schema"]
+    json_schema: Optional[Dict[str, Any]]

langwatch/prompts/types.py

@@ -1,24 +1,16 @@
-from typing import TypedDict, Literal, Optional, Dict, Any
-
-
-# Clean TypedDict interfaces that match the expected API
-class MessageDict(TypedDict):
-    """Message dictionary that matches the API structure."""
-
-    role: Literal["system", "user", "assistant"]
-    content: str
-
-
-class InputDict(TypedDict):
-    """Input dictionary that matches the API structure."""
-
-    identifier: str
-    type: Literal["str", "int", "float", "bool", "json"]
-
-
-class OutputDict(TypedDict):
-    """Output dictionary that matches the API structure."""
-
-    identifier: str
-    type: Literal["str", "int", "float", "bool", "json"]
-    json_schema: Optional[Dict[str, Any]]
+# Re-export types for backward compatibility
+from .types import (
+    PromptData,
+    MessageDict,
+    InputDict,
+    OutputDict,
+    ResponseFormatDict,
+)
+
+__all__ = [
+    "PromptData",
+    "MessageDict",
+    "InputDict",
+    "OutputDict",
+    "ResponseFormatDict",
+]

langwatch/utils/transformation.py

@@ -180,11 +180,22 @@ def truncate_object_recursively(
         return obj
 
     def truncate_string(s: str):
-        return (
-            s[:max_string_length] + "... (truncated string)"
-            if len(s) > max_string_length
-            else s
-        )
+        # Always use errors='replace' to handle any malformed Unicode gracefully
+        if len(s.encode('utf-8', errors='replace')) <= max_string_length:
+            return s
+
+        # Binary search to find the right truncation point
+        left, right = 0, len(s)
+        while left < right:
+            mid = (left + right + 1) // 2
+            byte_length = len(s[:mid].encode('utf-8', errors='replace'))
+
+            if byte_length <= max_string_length - 25:  # Reserve space for suffix
+                left = mid
+            else:
+                right = mid - 1
+
+        return s[:left] + "... (truncated string)"
 
     def process_item(item: Any):
         if isinstance(item, str):

{langwatch-0.2.19.dist-info → langwatch-0.3.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: langwatch
-Version: 0.2.19
+Version: 0.3.1
 Summary: LangWatch Python SDK, for monitoring your LLMs
 Author-email: Langwatch Engineers <engineering@langwatch.ai>
 License: MIT