langwatch 0.7.2__py3-none-any.whl → 0.8.0__py3-none-any.whl

langwatch/__init__.py

@@ -8,6 +8,8 @@ from .login import login
 from .state import get_api_key, get_endpoint
 from .__version__ import __version__
 from .utils.initialization import ensure_setup, setup
+from .prompts.types import FetchPolicy
+
 
 # Type hints for IntelliSense (only imported for typing)
 from typing import TYPE_CHECKING
@@ -153,5 +155,5 @@ __all__ = [
     "evaluations",
     "langchain",
     "dspy",
-    "prompts",
+    "FetchPolicy",
 ]

langwatch/__version__.py

@@ -1,3 +1,3 @@
 """Version information for LangWatch."""
 
-__version__ = "0.7.2" # x-release-please-version
+__version__ = "0.8.0" # x-release-please-version

langwatch/prompts/__init__.py

@@ -1,5 +1,36 @@
 from .prompt_facade import PromptsFacade
+from .types import FetchPolicy
 
 __all__ = [
     "PromptsFacade",
+    "FetchPolicy",
 ]
+
+# Cached PromptsFacade instance for module-level method delegation
+_facade_instance: PromptsFacade | None = None
+
+
+def _get_facade() -> PromptsFacade:
+    """Get or create the cached PromptsFacade instance."""
+    global _facade_instance
+    if _facade_instance is None:
+        _facade_instance = PromptsFacade.from_global()
+    return _facade_instance
+
+
+def __getattr__(name: str):
+    """
+    Delegate attribute access to PromptsFacade instance.
+
+    This allows langwatch.prompts to work both as:
+    - A module (for submodule access like `from langwatch.prompts.types import FetchPolicy`)
+    - A facade (for method access like `langwatch.prompts.get(...)`)
+
+    When Python imports `langwatch.prompts.types`, it stores `langwatch.prompts` as a module
+    in sys.modules, which shadows the lazy-loaded PromptsFacade instance from langwatch.__getattr__.
+    This __getattr__ ensures method calls still work by delegating to a PromptsFacade instance.
+    """
+    facade = _get_facade()
+    if hasattr(facade, name):
+        return getattr(facade, name)
+    raise AttributeError(f"module '{__name__}' has no attribute '{name}'")

langwatch/prompts/errors.py

@@ -139,7 +139,8 @@ def unwrap_response(
         error_detail = f": {msg}" if msg else ""
         raise ValueError(f"Invalid prompt request{error_detail}")
     if status == 401:
-        raise RuntimeError("Authentication error")
+        error_detail = f": {msg}" if msg else ""
+        raise RuntimeError(f"Authentication error{error_detail}")
     if status >= 500:
         error_detail = f" - {msg}" if msg else ""
         raise RuntimeError(

langwatch/prompts/local_loader.py

@@ -25,8 +25,13 @@ class LocalPromptLoader:
     """Loads prompts from local files in CLI format."""
 
     def __init__(self, base_path: Optional[Path] = None):
-        """Initialize with base path (defaults to current working directory)."""
-        self.base_path = base_path or Path.cwd()
+        """Initialize with base path (defaults to current working directory at load time)."""
+        self._base_path = base_path
+
+    @property
+    def base_path(self) -> Path:
+        """Get the base path, defaulting to current working directory if not set."""
+        return self._base_path or Path.cwd()
 
     def load_prompt(self, prompt_id: str) -> Optional[PromptData]:
         """

langwatch/prompts/prompt_facade.py

@@ -8,7 +8,8 @@ or when API is unavailable.
 
 Follows the facade pattern to coordinate between LocalPromptLoader and PromptApiService.
 """
-from typing import Dict, List, Literal, Optional
+from typing import Any, Dict, List, Literal, Optional
+import time
 from langwatch.generated.langwatch_rest_api_client.client import (
     Client as LangWatchRestApiClient,
 )
@@ -16,9 +17,13 @@ from langwatch.generated.langwatch_rest_api_client.client import (
 from langwatch.utils.initialization import ensure_setup
 from langwatch.state import get_instance
 from .prompt import Prompt
+from .types import FetchPolicy
 from .prompt_api_service import PromptApiService
 from .local_loader import LocalPromptLoader
 from .types import MessageDict, InputDict, OutputDict
+from logging import getLogger
+
+logger = getLogger(__name__)
 
 
 class PromptsFacade:
@@ -34,6 +39,7 @@ class PromptsFacade:
         """Initialize the prompt service facade with dependencies."""
         self._api_service = PromptApiService(rest_api_client)
         self._local_loader = LocalPromptLoader()
+        self._cache: Dict[str, Dict[str, Any]] = {}
 
     @classmethod
     def from_global(cls) -> "PromptsFacade":
@@ -46,17 +52,43 @@ class PromptsFacade:
             )
         return cls(instance.rest_api_client)
 
-    def get(self, prompt_id: str, version_number: Optional[int] = None) -> Prompt:
+    def get(
+        self,
+        prompt_id: str,
+        version_number: Optional[int] = None,
+        fetch_policy: Optional[FetchPolicy] = None,
+        cache_ttl_minutes: Optional[int] = None,
+    ) -> Prompt:
         """
-        Retrieve a prompt by its ID with guaranteed availability.
+        Retrieve a prompt by its ID with configurable fetch policy.
 
-        Tries local files first, then falls back to API.
-        You can optionally specify a version number to get a specific version of the prompt.
+        Args:
+            prompt_id: The prompt ID to retrieve
+            version_number: Optional specific version number to retrieve
+            fetch_policy: How to fetch the prompt. Defaults to MATERIALIZED_FIRST.
+            cache_ttl_minutes: Cache TTL in minutes (only used with CACHE_TTL policy). Defaults to 5.
 
         Raises:
             ValueError: If the prompt is not found (404 error).
             RuntimeError: If the API call fails for other reasons (auth, server errors, etc.).
         """
+        fetch_policy = fetch_policy or FetchPolicy.MATERIALIZED_FIRST
+
+        if fetch_policy == FetchPolicy.MATERIALIZED_ONLY:
+            return self._get_materialized_only(prompt_id)
+        elif fetch_policy == FetchPolicy.ALWAYS_FETCH:
+            return self._get_always_fetch(prompt_id, version_number)
+        elif fetch_policy == FetchPolicy.CACHE_TTL:
+            return self._get_cache_ttl(
+                prompt_id, version_number, cache_ttl_minutes or 5
+            )
+        else:  # MATERIALIZED_FIRST (default)
+            return self._get_materialized_first(prompt_id, version_number)
+
+    def _get_materialized_first(
+        self, prompt_id: str, version_number: Optional[int] = None
+    ) -> Prompt:
+        """Get prompt using MATERIALIZED_FIRST policy (local first, API fallback)."""
         # Try to load from local files first
         local_data = self._local_loader.load_prompt(prompt_id)
         if local_data is not None:
@@ -66,6 +98,64 @@ class PromptsFacade:
         api_data = self._api_service.get(prompt_id, version_number)
         return Prompt(api_data)
 
+    def _get_materialized_only(self, prompt_id: str) -> Prompt:
+        """Get prompt using MATERIALIZED_ONLY policy (local only, no API calls)."""
+        local_data = self._local_loader.load_prompt(prompt_id)
+        if local_data is not None:
+            return Prompt(local_data)
+
+        raise ValueError(f"Prompt '{prompt_id}' not found in materialized files")
+
+    def _get_always_fetch(
+        self, prompt_id: str, version_number: Optional[int] = None
+    ) -> Prompt:
+        """Get prompt using ALWAYS_FETCH policy (API first, local fallback)."""
+        try:
+            api_data = self._api_service.get(prompt_id, version_number)
+            return Prompt(api_data)
+        except Exception:
+            # Fall back to local if API fails
+            local_data = self._local_loader.load_prompt(prompt_id)
+            if local_data is not None:
+                return Prompt(local_data)
+            raise ValueError(f"Prompt '{prompt_id}' not found locally or on server")
+
+    def _get_cache_ttl(
+        self,
+        prompt_id: str,
+        version_number: Optional[int] = None,
+        cache_ttl_minutes: int = 5,
+    ) -> Prompt:
+        """Get prompt using CACHE_TTL policy (cache with TTL, fallback to local)."""
+        cache_key = f"{prompt_id}::version:{version_number or ''}"
+        ttl_ms = cache_ttl_minutes * 60 * 1000
+        now = time.time() * 1000  # Convert to milliseconds
+
+        cached = self._cache.get(cache_key)
+        if cached and now - cached["timestamp"] < ttl_ms:
+            return Prompt(cached["data"])
+
+        try:
+            api_data = self._api_service.get(prompt_id, version_number)
+            self._cache[cache_key] = {"data": api_data, "timestamp": now}
+            return Prompt(api_data)
+        except Exception:
+            logger.warning(
+                f"Failed to fetch prompt '{prompt_id}' from API, falling back to local",
+                exc_info=True,
+                stack_info=True,
+                extra={
+                    "prompt_id": prompt_id,
+                    "version_number": version_number,
+                    "cache_ttl_minutes": cache_ttl_minutes,
+                },
+            )
+            # Fall back to local if API fails
+            local_data = self._local_loader.load_prompt(prompt_id)
+            if local_data is not None:
+                return Prompt(local_data)
+            raise ValueError(f"Prompt '{prompt_id}' not found locally or on server")
+
     def create(
         self,
         handle: str,

langwatch/prompts/types/__init__.py

@@ -8,6 +8,9 @@ organized by their purpose and scope.
 # Core prompt data structure
 from .prompt_data import PromptData
 
+# Fetch policy
+from .fetch_policy import FetchPolicy
+
 # Standardized data structures
 from .structures import (
     MessageDict,
@@ -24,4 +27,5 @@ __all__ = [
     "InputDict",
     "OutputDict",
     "ResponseFormatDict",
+    "FetchPolicy",
 ]

langwatch/prompts/types/fetch_policy.py

@@ -0,0 +1,26 @@
+from enum import Enum
+
+
+class FetchPolicy(Enum):
+    """
+    Fetch policy for prompt retrieval.
+
+    Controls how prompts are fetched and cached.
+    """
+
+    # Use local file if available, otherwise fetch from API (default)
+    MATERIALIZED_FIRST = "MATERIALIZED_FIRST"
+
+    # Always try API first, fall back to materialized
+    ALWAYS_FETCH = "ALWAYS_FETCH"
+
+    # Fetch every X minutes, use materialized between fetches
+    CACHE_TTL = "CACHE_TTL"
+
+    # Never fetch, use materialized files only
+    MATERIALIZED_ONLY = "MATERIALIZED_ONLY"
+
+
+__all__ = [
+    "FetchPolicy",
+]

{langwatch-0.7.2.dist-info → langwatch-0.8.0.dist-info}/METADATA

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

{langwatch-0.7.2.dist-info → langwatch-0.8.0.dist-info}/RECORD

@@ -1,5 +1,5 @@
-langwatch/__init__.py,sha256=TzPHzqCFGZJByI3sAIKrNB33Qi4PqVmgYDZuBwPnhPc,4222
-langwatch/__version__.py,sha256=xd61VXC9KB2dkBlREW18eiU4DnZ96PU7rNiffqTsMn0,91
+langwatch/__init__.py,sha256=GMq4SV2Tz2i0JD05shqnw2lBW5cgMx4Zzo141hp106k,4266
+langwatch/__version__.py,sha256=vwG-FkKYsGya3EzNIEIMvFwGCI2K-gXNyKE3Y88jHc4,91
 langwatch/attributes.py,sha256=nXdI_G85wQQCAdAcwjCiLYdEYj3wATmfgCmhlf6dVIk,3910
 langwatch/batch_evaluation.py,sha256=piez7TYqUZPb9NlIShTuTPmSzrZqX-vm2Grz_NGXe04,16078
 langwatch/client.py,sha256=WTNcYSik7kZ2kH-qGDnhbMTosc8e_Xhab_lZlfh5TC8,25559
@@ -390,16 +390,16 @@ langwatch/generated/langwatch_rest_api_client/models/search_request_filters.py,s
 langwatch/generated/langwatch_rest_api_client/models/search_response.py,sha256=zDYmJ8bFBSJyF9D3cEn_ffrey-ITIfwr-_7eu72zLyk,2832
 langwatch/generated/langwatch_rest_api_client/models/timestamps.py,sha256=-nRKUPZTAJQNxiKz128xF7DKgZNbFo4G3mr5xNXrkaw,2173
 langwatch/generated/langwatch_rest_api_client/models/trace.py,sha256=K9Lc_EQOrJ2dqMXx9EpiUXReT1_uYF7WRfYyhlfbi3I,7537
-langwatch/prompts/__init__.py,sha256=2BcFhTrcCfxMxDGc5gd09oNZdzY_wlcAGFlt4Mz2lv4,77
-langwatch/prompts/errors.py,sha256=9WKzLiOLJAm7DhtKc9c74oquh0IyDQOHNs6xeTFiQRg,5060
-langwatch/prompts/local_loader.py,sha256=JL2l1v8ymyhi8LvTndVIqhzP7XDHm4HXKygYDvSaV5w,6596
+langwatch/prompts/__init__.py,sha256=OGf3BrzVsTZnSPYSqSqe_eWmGIBRiOUlovOduYzKCx4,1259
+langwatch/prompts/errors.py,sha256=kmaGeA1QPot9Ii5lgooxmAFlvUPOGjAnzzPBuw4h6Bw,5124
+langwatch/prompts/local_loader.py,sha256=luvk39Kc4S-x4lBSms-AoWqg0Im_Uu-Lcpt3cRJFmdY,6774
 langwatch/prompts/prompt.py,sha256=SgLDo9hO-CuRE-AZ8zx9v7-KqjiabiW8GzD9jdx1IoA,6914
 langwatch/prompts/prompt_api_service.py,sha256=tHhwIRjUBSM43_jwDAoGCHJjvvqVeSCrUPwcwMvUHho,9823
-langwatch/prompts/prompt_facade.py,sha256=kf-IXFWX_39Z5WD8nmKzWpO13pYwqMl12qfVfyw4A3E,5228
-langwatch/prompts/types.py,sha256=p1bRMvfCCpGGiVwzFtQijVtWl5GWugL_vBOFc4B2348,269
+langwatch/prompts/prompt_facade.py,sha256=fc16TB4ZBhKpwXVx9SNTJxLvQVms4eu4w0ZOH4Kk55w,8950
 langwatch/prompts/decorators/prompt_service_tracing.py,sha256=uSYw0vExo7AuxbcCRnxbYl6UOfOQSC0IsisSqYy153Y,2395
 langwatch/prompts/decorators/prompt_tracing.py,sha256=x_PQvJlGbGF1h2HtGNiqaZ8K1qNd1jRf5pTOBTQx-7M,3963
-langwatch/prompts/types/__init__.py,sha256=uEnjOQC4LkLMWQ0fXfKe573xKOvoMdPgC6uY-yo9B_g,506
+langwatch/prompts/types/__init__.py,sha256=jwaFV4VJHrOE6dm6yyLtWk6_7dqZpR5uZjN1cswtga4,579
+langwatch/prompts/types/fetch_policy.py,sha256=AyS4J2x4IYjlcFo-6hSJY16awhll6hK2c3jncLUgZxc,578
 langwatch/prompts/types/prompt_data.py,sha256=g_EQ94-PGfa4Ptwd3e2rMqoIZiX052MEEZKyF77m9D0,3137
 langwatch/prompts/types/structures.py,sha256=cB94bn-qhFgHHYXcrmJV6Bk9idk5ZmyfXhFNQAaXw-M,951
 langwatch/telemetry/context.py,sha256=q0hUG9PM3aifIr6ZRuuNNbsGtcAImu9Pv2XTKUp3CGc,4029
@@ -415,6 +415,6 @@ langwatch/utils/initialization.py,sha256=1KoZmkHOvGEVF0j-4t4xRQdA_2C_SPiF7qFXqEG
 langwatch/utils/module.py,sha256=KLBNOK3mA9gCSifCcQX_lOtU48BJQDWvFKtF6NMvwVA,688
 langwatch/utils/transformation.py,sha256=76MGXyrYTxM0Yri36NJqLK-XxL4BBYdmKWAXXlw3D4Q,7690
 langwatch/utils/utils.py,sha256=ZCOSie4o9LdJ7odshNfCNjmgwgQ27ojc5ENqt1rXuSs,596
-langwatch-0.7.2.dist-info/METADATA,sha256=QeRx1wldxr7sSCCONIKDKVcmdmENX8yK-_TLIO-J9Ig,13192
-langwatch-0.7.2.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-langwatch-0.7.2.dist-info/RECORD,,
+langwatch-0.8.0.dist-info/METADATA,sha256=RVtrzq4jjZAzk9s80xxjXz4Wd_grAzp0vRJ73oN7WNs,13192
+langwatch-0.8.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+langwatch-0.8.0.dist-info/RECORD,,

langwatch/prompts/types.py

@@ -1,16 +0,0 @@
-# Re-export types for backward compatibility
-from .types import (
-    PromptData,
-    MessageDict,
-    InputDict,
-    OutputDict,
-    ResponseFormatDict,
-)
-
-__all__ = [
-    "PromptData",
-    "MessageDict",
-    "InputDict",
-    "OutputDict",
-    "ResponseFormatDict",
-]