langwatch 0.7.1__tar.gz → 0.8.0__tar.gz

langwatch-0.8.0/AGENTS.md

@@ -0,0 +1,46 @@
+## Python SDK Testing Antipatterns
+
+| Antipattern | Correct Behavior |
+|-------------|------------------|
+| Writing E2E tests mixed with unit tests | Keep E2E tests isolated in `tests/e2e/` directory with `@pytest.mark.e2e`. E2E tests verify real API behavior with external services, while examples serve as user demonstrations. |
+| Repeating happy paths in integration/unit tests | Do not duplicate E2E/example coverage in integrations or units. Focus integration tests on edge/error cases, and unit tests on pure logic. |
+| Failing to follow [TESTING.md](../TESTING.md) hierarchy | Always start with a `.feature` file, drive from E2E tests in `tests/e2e/`, then add integration tests in `tests/` and unit tests as outlined. Examples in `examples/` serve as user demonstrations. |
+| Using `pip` or `python` directly for installing, running, or testing | Always use [`uv`](https://github.com/astral-sh/uv) for all dependency installation, package management, and test running. Do not use `pip` commands or `python -m pip`, prefer `uv` equivalents throughout documentation, scripts, and workflows. |
+
+## Testing Structure
+
+The Python SDK follows a hierarchical testing approach:
+
+### `tests/e2e/` - End-to-End Tests
+- **Purpose**: Verify real API behavior with external services
+- **Location**: `tests/e2e/` directory
+- **Markers**: `@pytest.mark.e2e`
+- **Run with**: `pytest tests/e2e/` or `pytest -m e2e`
+- **Examples**: `test_fetch_policies_e2e.py` - verifies fetch policies work with real API calls
+
+### `examples/` - User Demonstrations
+- **Purpose**: Show users how to use the SDK features
+- **Location**: `examples/` directory
+- **Markers**: None (automatically tested by `test_examples.py`)
+- **Run with**: `pytest tests/test_examples.py` or manually as scripts
+- **Examples**: `generic_bot.py`, `langchain_bot.py`, etc.
+
+### `tests/` - Integration & Unit Tests
+- **Purpose**: Test components and error cases
+- **Location**: `tests/` directory
+- **Markers**: `@pytest.mark.integration`, `@pytest.mark.unit` (default)
+- **Run with**: `pytest tests/` or `pytest -m "not e2e"`
+
+### Running Tests Selectively
+```bash
+# Run all tests except E2E (fast CI)
+pytest tests/ -m "not e2e"
+
+# Run only E2E tests (requires API keys)
+pytest tests/e2e/
+
+# Run examples as demonstrations
+pytest tests/test_examples.py
+```
+
+

{langwatch-0.7.1 → langwatch-0.8.0}/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## [0.8.0](https://github.com/langwatch/langwatch/compare/python-sdk@v0.7.2...python-sdk@v0.8.0) (2025-12-16)
+
+
+### Features
+
+* implement FetchPolicy enum for Python SDK  ([#989](https://github.com/langwatch/langwatch/issues/989)) ([43de904](https://github.com/langwatch/langwatch/commit/43de904de08ec54a78aece35da155a8a3cb4289d))
+
+### Bug Fixes
+
+* rerun evaluations if new spans arrive even after 30s but less than 1h ([79ba316](https://github.com/langwatch/langwatch/commit/79ba3163c64f224e3d2b640b5340f1503fc57c48))
+
+## [0.7.2](https://github.com/langwatch/langwatch/compare/python-sdk@v0.7.1...python-sdk@v0.7.2) (2025-12-03)
+
+
+### Bug Fixes
+
+* **python-sdk:** add httpx.ReadTimeout to transient error skip list ([#910](https://github.com/langwatch/langwatch/issues/910)) ([dbdae14](https://github.com/langwatch/langwatch/commit/dbdae1465b5da364aa23097d9d91ff2072ee6d13)), closes [#909](https://github.com/langwatch/langwatch/issues/909)
+
 ## [0.7.1](https://github.com/langwatch/langwatch/compare/python-sdk@v0.7.0...python-sdk@v0.7.1) (2025-11-28)
 
 

{langwatch-0.7.1 → langwatch-0.8.0}/Makefile

@@ -1,7 +1,10 @@
 .PHONY: test test-tracing install example
 
-test: test-tracing
-	LANGWATCH_API_KEY="testkey" PYTHONPATH=$$PYTHONPATH:. uv run pytest -s -vv -m "not integration" -k "not test_example and not test_prompt_service_tracing and not test_prompt_tracing and not test_context and not test_tracing" $(filter-out $@,$(MAKECMDGOALS))
+test-unit:
+	LANGWATCH_API_KEY="testkey" PYTHONPATH=$$PYTHONPATH:. uv run pytest -s -vv -m "not integration and not e2e" -k "not test_example and not test_prompt_service_tracing and not test_prompt_tracing and not test_context and not test_tracing" $(filter-out $@,$(MAKECMDGOALS))
+
+test-e2e:
+	PYTHONPATH=$$PYTHONPATH:. uv run pytest -s -vv -m "e2e"
 
 # Run tracing tests in isolation to avoid global OpenTelemetry state conflicts
 test-tracing:
@@ -14,6 +17,11 @@ test-tracing:
 	@echo "Running telemetry tracing tests..."
 	@LANGWATCH_API_KEY="testkey" PYTHONPATH=$$PYTHONPATH:. uv run pytest -s -vv tests/telemetry/test_tracing.py
 
+test: install
+	$(MAKE) test-unit
+	$(MAKE) test-tracing
+	$(MAKE) test-e2e
+
 # Test bot/chatbot examples (excludes CLI examples)
 # Call it with `make test-examples -- -k examples/openai_bot.py` to run a specific example
 test-examples:
@@ -46,6 +54,8 @@ example:
 		uv run python $$args; \
 	elif [[ $$args =~ "streamlit" ]]; then \
 		uv run streamlit run $$args; \
+	elif [[ $$args =~ "fetch_policies" ]]; then \
+		PYTHONPATH=$$PYTHONPATH:. uv run python $$args; \
 	else \
 		uv run chainlit run -w --port 9000 $$args; \
 	fi
@@ -60,7 +70,7 @@ ensure-openapi-python-client:
 
 generate/api-client: ensure-openapi-python-client
 	@echo "Generating OpenAPI spec..."
-	@cd ../langwatch && npm run task generateOpenAPISpec
+	@cd ../langwatch && pnpm run task generateOpenAPISpec
 	@echo "Deleting old API client..."
 	@rm -rf src/langwatch/generated/langwatch_rest_api_client
 	@echo "Building API client..."

{langwatch-0.7.1 → langwatch-0.8.0}/PKG-INFO

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

langwatch-0.8.0/examples/README.md

@@ -0,0 +1,167 @@
+# LangWatch Python SDK Examples
+
+This directory contains examples demonstrating various LangWatch SDK features. Each example is a runnable Python script that shows real-world usage patterns.
+
+## 📋 Categories
+
+### 🤖 Core Bot Examples
+
+Basic chatbot implementations showing fundamental LangWatch tracing:
+
+| Example | Description | Key Features |
+|---------|-------------|--------------|
+| [`generic_bot.py`](generic_bot.py) | Simple synchronous chatbot | Basic tracing, metadata |
+| [`generic_bot_sync_function.py`](generic_bot_sync_function.py) | Sync function usage | Function-level tracing |
+| [`generic_bot_async_streaming.py`](generic_bot_async_streaming.py) | Async streaming responses | Streaming support, async/await |
+| [`generic_bot_streaming.py`](generic_bot_streaming.py) | Synchronous streaming | Streaming without async |
+| [`generic_bot_span_context_manager.py`](generic_bot_span_context_manager.py) | Manual span management | Context managers, custom spans |
+| [`generic_bot_span_low_level.py`](generic_bot_span_low_level.py) | Low-level span control | Direct span manipulation |
+
+### 🔗 Framework Integrations
+
+Examples showing integration with popular AI frameworks:
+
+| Example | Framework | Features |
+|---------|-----------|----------|
+| [`langchain_bot.py`](langchain_bot.py) | LangChain | LCEL, chains, agents |
+| [`langchain_bot_with_memory.py`](langchain_bot_with_memory.py) | LangChain + Memory | Conversation history |
+| [`langchain_rag_bot.py`](langchain_rag_bot.py) | LangChain RAG | Retrieval-augmented generation |
+| [`langchain_rag_bot_with_threads.py`](langchain_rag_bot_with_threads.py) | LangChain RAG + Threads | Multi-threading |
+| [`langchain_rag_bot_vertex_ai.py`](langchain_rag_bot_vertex_ai.py) | LangChain + Vertex AI | Google Cloud integration |
+| [`langgraph_rag_bot_with_threads.py`](langgraph_rag_bot_with_threads.py) | LangGraph | Graph-based workflows |
+| [`haystack_bot.py`](haystack_bot.py) | Haystack | Document search, pipelines |
+| [`dspy_bot.py`](dspy_bot.py) | DSPy | Programmatic prompting |
+| [`litellm_bot.py`](litellm_bot.py) | LiteLLM | Multi-provider support |
+
+### 🌐 Web Framework Examples
+
+Examples showing web application integration:
+
+| Example | Framework | Features |
+|---------|-----------|----------|
+| [`fastapi_app.py`](fastapi_app.py) | FastAPI | Web API with tracing |
+| [`prompt_management_fastapi.py`](prompt_management_fastapi.py) | FastAPI | Prompt management API |
+| [`streamlit_openai_assistants_api_bot.py`](streamlit_openai_assistants_api_bot.py) | Streamlit | UI with assistants API |
+
+### 📊 Evaluation & Analysis
+
+Examples focused on evaluation and analytics:
+
+| Example | Purpose | Features |
+|---------|---------|----------|
+| [`evaluation_manual_call.py`](evaluation_manual_call.py) | Manual evaluation | Custom evaluation logic |
+| [`span_evaluation.py`](span_evaluation.py) | Span-based evaluation | Automatic span analysis |
+| [`custom_evaluation_bot.py`](custom_evaluation_bot.py) | Custom evaluators | User-defined metrics |
+
+### 🛡️ Safety & Reliability
+
+Examples demonstrating guardrails and error handling:
+
+| Example | Focus | Features |
+|---------|-------|----------|
+| [`guardrails.py`](guardrails.py) | Content safety | Input/output filtering |
+| [`guardrails_parallel.py`](guardrails_parallel.py) | Parallel guardrails | Concurrent safety checks |
+| [`guardrails_without_tracing.py`](guardrails_without_tracing.py) | Standalone guardrails | Safety without tracing |
+| [`generic_bot_exception.py`](generic_bot_exception.py) | Error handling | Exception tracing |
+
+### 🔍 RAG & Retrieval Examples
+
+Advanced retrieval-augmented generation patterns:
+
+| Example | Approach | Features |
+|---------|----------|----------|
+| [`generic_bot_rag.py`](generic_bot_rag.py) | Basic RAG | Document retrieval |
+| [`generic_bot_rag_multithreaded.py`](generic_bot_rag_multithreaded.py) | Multi-threaded RAG | Concurrent processing |
+| [`openai_bot_rag.py`](openai_bot_rag.py) | OpenAI + RAG | Embeddings, vector search |
+
+### 📈 Advanced Features
+
+Specialized functionality examples:
+
+| Example | Feature | Description |
+|---------|---------|-------------|
+| [`fetch_policies_example.py`](fetch_policies_example.py) | Fetch policies | Prompt retrieval strategies |
+| [`distributed_tracing.py`](distributed_tracing.py) | Distributed tracing | Multi-service tracing |
+| [`dataset_kitchen_sink.py`](dataset_kitchen_sink.py) | Dataset operations | Full dataset workflow |
+| [`offline_evaluation.ipynb`](offline_evaluation.ipynb) | Offline analysis | Jupyter notebook evaluation |
+
+### 🔧 Specialized Integrations
+
+Examples for specific use cases and integrations:
+
+| Example | Integration | Purpose |
+|---------|-------------|---------|
+| [`azure_openai_stream_bot.py`](azure_openai_stream_bot.py) | Azure OpenAI | Cloud provider integration |
+| [`strands_bot.py`](strands_bot.py) | Strands | Multi-agent systems |
+
+## 🚀 Running Examples
+
+### Prerequisites
+```bash
+# Install dependencies
+uv sync
+
+# Set API keys (varies by example)
+export OPENAI_API_KEY="your-key"
+export LANGWATCH_API_KEY="your-langwatch-key"
+```
+
+### Run Individual Examples
+```bash
+# Basic bot
+python examples/generic_bot.py
+
+# LangChain integration
+python examples/langchain_bot.py
+
+# FastAPI web app
+uvicorn examples.fastapi_app:app --reload
+```
+
+### Run All Examples (Testing)
+```bash
+# Run all examples as tests
+pytest tests/test_examples.py
+
+# Run specific example
+pytest tests/test_examples.py -k "generic_bot"
+```
+
+## 📁 Directory Structure
+
+```text
+examples/
+├── README.md              # This file
+├── *.py                   # Individual examples
+├── cli/                   # CLI-specific examples
+│   └── README.md
+├── data/                  # Example data files
+├── documentation/         # Documentation examples
+├── openinference/         # OpenInference integration
+├── opentelemetry/         # OpenTelemetry integration
+├── prompt_cli/           # Prompt CLI examples
+├── sanity/               # Setup/sanity check examples
+├── test_utils/           # Utilities for testing examples
+└── weaviate_setup/       # Weaviate-specific setup
+```
+
+## 🎯 Example Categories
+
+- **Beginner**: `generic_bot.py`, `generic_bot_sync_function.py`
+- **Intermediate**: Framework integrations, basic RAG
+- **Advanced**: Multi-threading, distributed tracing, custom evaluations, fetch policies
+- **Integration**: Web frameworks, cloud providers, specialized tools
+
+## 📝 Contributing
+
+When adding new examples:
+1. Follow naming convention: `{feature/framework}_bot.py`
+2. Include docstring explaining what it demonstrates
+3. Add to appropriate category in this README
+4. Ensure it runs with `pytest tests/test_examples.py`
+
+## 🔗 Related Documentation
+
+- [Main SDK Documentation](../README.md)
+- [Testing Guidelines](../TESTING.md)
+- [Agent Guidelines](../AGENTS.md)

{langwatch-0.7.1 → langwatch-0.8.0}/examples/cli/guaranteed_availability_with_cli.py

@@ -23,33 +23,13 @@ from pathlib import Path
 
 from dotenv import load_dotenv
 import langwatch
+from examples.test_utils.run_cli import run_cli
 
 load_dotenv()
 
 CLI_EXECUTABLE = ["npx", "langwatch@latest"]
 
 
-def run_cli(command: list, cwd: Path):
-    """Run CLI command and handle errors."""
-    print(f"▶️  {' '.join(command)}")
-    try:
-        result = subprocess.run(
-            command,
-            cwd=cwd,
-            capture_output=True,
-            text=True,
-            timeout=30,  # 30 second timeout
-            input="Y\n",  # Answer "Y" to prompts
-        )
-        if result.returncode != 0:
-            print(f"❌ Failed: {result.stderr}")
-            raise subprocess.CalledProcessError(result.returncode, command)
-        return result
-    except subprocess.TimeoutExpired:
-        print("❌ Command timed out after 30 seconds")
-        raise
-
-
 def main():
     langwatch.setup()
 

{langwatch-0.7.1 → langwatch-0.8.0}/examples/distributed_tracing.py

@@ -59,11 +59,11 @@ async def main(message: cl.Message):
                             "span_id": f"span_{nanoid.generate()}",
                             "input": {
                                 "type": "text",
-                                "value": message.content,
+                                "value": "" if index == 0 else message.content,
                             },
                             "output": {
                                 "type": "text",
-                                "value": f"{full_response} (span {index})",
+                                "value": "" if index == 0 else f"{full_response} (span {index})",
                             },
                             "timestamps": {
                                 "started_at": int(time.time() * 1000),
@@ -79,10 +79,11 @@ async def main(message: cl.Message):
             )
 
     threads = []
-    for i in range(10):
+    for i in range(2):
         thread = threading.Thread(target=send_span, args=(i,))
         threads.append(thread)
         thread.start()
+        time.sleep(30)
 
     # Wait for all threads to complete
     for thread in threads:

langwatch-0.8.0/examples/test_utils/run_cli.py

@@ -0,0 +1,23 @@
+import subprocess
+from pathlib import Path
+
+
+def run_cli(command: list, cwd: Path):
+    """Run CLI command and handle errors."""
+    print(f"▶️  {' '.join(command)}")
+    try:
+        result = subprocess.run(
+            command,
+            cwd=cwd,
+            capture_output=True,
+            text=True,
+            timeout=30,  # 30 second timeout
+            input="Y\n",  # Answer "Y" to prompts
+        )
+        if result.returncode != 0:
+            print(f"❌ Failed: {result.stderr}")
+            raise subprocess.CalledProcessError(result.returncode, command)
+        return result
+    except subprocess.TimeoutExpired:
+        print("❌ Command timed out after 30 seconds")
+        raise

{langwatch-0.7.1 → langwatch-0.8.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "langwatch"
-version = "0.7.1" # remember to also update it in src/langwatch/__version__.py
+version = "0.8.0" # remember to also update it in src/langwatch/__version__.py
 description = "LangWatch Python SDK, for monitoring your LLMs"
 authors = [{ name = "Langwatch Engineers", email = "engineering@langwatch.ai" }]
 requires-python = ">=3.10,<3.14"
@@ -64,6 +64,11 @@ packages = ["src/langwatch"]
 testpaths = ["tests"]
 python_files = "test_*.py"
 python_functions = "test_*"
+markers = [
+    "e2e: End-to-end tests that require external services",
+    "integration: Integration tests",
+    "unit: Unit tests (default)",
+]
 
 [dependency-groups]
 dev = ["black>=25.1.0"]
@@ -99,4 +104,8 @@ examples = [
     "strands-agents[otel]>=1.14.0,<2.0.0",
     "unstructured[pdf]>=0.18.3",
 ]
-tests = ["pytest-asyncio>=0.21.2"]
+tests = [
+    "factory-boy>=3.3.3",
+    "pytest-asyncio>=0.21.2",
+    "python-dotenv==1.0.1"
+]

langwatch-0.8.0/specs/prompts/fetch-policy.feature

@@ -0,0 +1,7 @@
+# DO NOT EDIT THIS FILE - IT IS TO MAINTAIN PARITY WITH TYPESCRIPT SDK
+
+Feature: Prompt Fetch Policy
+  As a developer using the Python SDK
+  I want to retrieve prompts using with the same behavior as the
+  typescript feature: ../typescript-sdk/specs/prompts/fetch-policy.feature
+

{langwatch-0.7.1 → langwatch-0.8.0}/src/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-0.8.0/src/langwatch/__version__.py

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

langwatch-0.8.0/src/langwatch/prompts/__init__.py

@@ -0,0 +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-0.7.1 → langwatch-0.8.0}/src/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-0.7.1 → langwatch-0.8.0}/src/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-0.7.1 → langwatch-0.8.0}/src/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-0.7.1 → langwatch-0.8.0}/src/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",
 ]