Merge branch 'main' into marlies/lfe-dataset-fetch-consistencies

Author: marliessophie

.github/workflows/release.yml

@@ -12,7 +12,6 @@ This is the Langfuse Python SDK, a client library for accessing the Langfuse obs
 ```bash
 # Install Poetry plugins (one-time setup)
 poetry self add poetry-dotenv-plugin
-poetry self add poetry-bumpversion
 
 # Install all dependencies including optional extras
 poetry install --all-extras
@@ -50,16 +49,21 @@ poetry run pre-commit run --all-files
 
 ### Building and Releasing
 ```bash
-# Build the package
+# Build the package locally (for testing)
 poetry build
 
-# Run release script (handles versioning, building, tagging, and publishing)
-poetry run release
-
 # Generate documentation
 poetry run pdoc -o docs/ --docformat google --logo "https://langfuse.com/langfuse_logo.svg" langfuse
 ```
 
+Releases are automated via GitHub Actions. To release:
+1. Go to Actions > "Release Python SDK" workflow
+2. Click "Run workflow"
+3. Select version bump type (patch/minor/major/prerelease)
+4. For prereleases, select the type (alpha/beta/rc)
+
+The workflow handles versioning, building, PyPI publishing (via OIDC), and GitHub release creation.
+
 ## Architecture
 
 ### Core Components
@@ -112,7 +116,7 @@ Environment variables (defined in `_client/environment_variables.py`):
 - `pyproject.toml`: Poetry configuration, dependencies, and tool settings
 - `ruff.toml`: Local development linting config (stricter)
 - `ci.ruff.toml`: CI linting config (more permissive)
-- `langfuse/version.py`: Version string (updated by release script)
+- `langfuse/version.py`: Version string (updated by CI release workflow)
 
 ## API Generation
 

CLAUDE.md

@@ -6,7 +6,6 @@
 
 ```
 poetry self add poetry-dotenv-plugin
-poetry self add poetry-bumpversion
 ```
 
 ### Install dependencies
@@ -58,34 +57,25 @@ poetry run mypy langfuse --no-error-summary
 
 ### Publish release
 
-#### Release script
-
-Make sure you have your PyPi API token setup in your poetry config. If not, you can set it up by running:
-
-```sh
-poetry config pypi-token.pypi $your-api-token
-```
-
-Run the release script:
-
-```sh
-poetry run release
-```
-
-#### Manual steps (for prepatch versions)
-
-1. `poetry version patch`
-   - `poetry version prepatch` for pre-release versions
-2. `poetry install`
-3. `poetry build`
-4. `git commit -am "chore: release v{version}"`
-5. `git push`
-6. `git tag v{version}`
-7. `git push --tags`
-8. `poetry publish`
-   - Create PyPi API token: <https://pypi.org/manage/account/token/>
-   - Setup: `poetry config pypi-token.pypi your-api-token`
-9. Create a release on GitHub with the changelog
+Releases are automated via GitHub Actions using PyPI Trusted Publishing (OIDC).
+
+To create a release:
+
+1. Go to [Actions > Release Python SDK](https://github.com/langfuse/langfuse-python/actions/workflows/release.yml)
+2. Click "Run workflow"
+3. Select the version bump type:
+   - `patch` - Bug fixes (1.0.0 → 1.0.1)
+   - `minor` - New features (1.0.0 → 1.1.0)
+   - `major` - Breaking changes (1.0.0 → 2.0.0)
+   - `prerelease` - Pre-release versions (1.0.0 → 1.0.0a1)
+4. For pre-releases, select the type: `alpha`, `beta`, or `rc`
+5. Click "Run workflow"
+
+The workflow will automatically:
+- Bump the version in `pyproject.toml` and `langfuse/version.py`
+- Build the package
+- Publish to PyPI
+- Create a git tag and GitHub release with auto-generated release notes
 
 ### SDK Reference
 

CONTRIBUTING.md

@@ -84,6 +84,7 @@
     DeleteDatasetRunResponse,
     PaginatedDatasetRuns,
 )
+from langfuse.api.resources.commons.errors.not_found_error import NotFoundError
 from langfuse.api.resources.ingestion.types.score_body import ScoreBody
 from langfuse.api.resources.prompts.types import (
     CreatePromptRequest_Chat,
@@ -1976,6 +1977,7 @@ def create_score(
         comment: Optional[str] = None,
         config_id: Optional[str] = None,
         metadata: Optional[Any] = None,
+        timestamp: Optional[datetime] = None,
     ) -> None: ...
 
     @overload
@@ -1993,6 +1995,7 @@ def create_score(
         comment: Optional[str] = None,
         config_id: Optional[str] = None,
         metadata: Optional[Any] = None,
+        timestamp: Optional[datetime] = None,
     ) -> None: ...
 
     def create_score(
@@ -2009,6 +2012,7 @@ def create_score(
         comment: Optional[str] = None,
         config_id: Optional[str] = None,
         metadata: Optional[Any] = None,
+        timestamp: Optional[datetime] = None,
     ) -> None:
         """Create a score for a specific trace or observation.
 
@@ -2027,6 +2031,7 @@ def create_score(
             comment: Optional comment or explanation for the score
             config_id: Optional ID of a score config defined in Langfuse
             metadata: Optional metadata to be attached to the score
+            timestamp: Optional timestamp for the score (defaults to current UTC time)
 
         Example:
             ```python
@@ -2073,7 +2078,7 @@ def create_score(
             event = {
                 "id": self.create_trace_id(),
                 "type": "score-create",
-                "timestamp": _get_timestamp(),
+                "timestamp": timestamp or _get_timestamp(),
                 "body": new_body,
             }
 
@@ -3327,20 +3332,28 @@ def create_dataset(
         name: str,
         description: Optional[str] = None,
         metadata: Optional[Any] = None,
+        input_schema: Optional[Any] = None,
+        expected_output_schema: Optional[Any] = None,
     ) -> Dataset:
         """Create a dataset with the given name on Langfuse.
 
         Args:
             name: Name of the dataset to create.
             description: Description of the dataset. Defaults to None.
             metadata: Additional metadata. Defaults to None.
+            input_schema: JSON Schema for validating dataset item inputs. When set, all new items will be validated against this schema.
+            expected_output_schema: JSON Schema for validating dataset item expected outputs. When set, all new items will be validated against this schema.
 
         Returns:
             Dataset: The created dataset as returned by the Langfuse API.
         """
         try:
             body = CreateDatasetRequest(
-                name=name, description=description, metadata=metadata
+                name=name,
+                description=description,
+                metadata=metadata,
+                inputSchema=input_schema,
+                expectedOutputSchema=expected_output_schema,
             )
             langfuse_logger.debug(f"Creating datasets {body}")
 
@@ -3674,6 +3687,14 @@ def fetch_prompts() -> Any:
 
             return prompt
 
+        except NotFoundError as not_found_error:
+            langfuse_logger.warning(
+                f"Prompt '{cache_key}' not found during refresh, evicting from cache."
+            )
+            if self._resources is not None:
+                self._resources.prompt_cache.delete(cache_key)
+            raise not_found_error
+
         except Exception as e:
             langfuse_logger.error(
                 f"Error while fetching prompt '{cache_key}': {str(e)}"

langfuse/_client/client.py

@@ -52,6 +52,8 @@ def _create_client_from_instance(
         mask=instance.mask,
         blocked_instrumentation_scopes=instance.blocked_instrumentation_scopes,
         additional_headers=instance.additional_headers,
+        tracer_provider=instance.tracer_provider,
+        httpx_client=instance.httpx_client,
     )
 
 

langfuse/_client/get_client.py

@@ -32,6 +32,7 @@
     "metadata",
     "version",
     "tags",
+    "trace_name",
 ]
 
 InternalPropagatedKeys = Literal[
@@ -50,6 +51,7 @@
     "metadata",
     "version",
     "tags",
+    "trace_name",
     "experiment_id",
     "experiment_name",
     "experiment_metadata",
@@ -77,6 +79,7 @@ def propagate_attributes(
     metadata: Optional[Dict[str, str]] = None,
     version: Optional[str] = None,
     tags: Optional[List[str]] = None,
+    trace_name: Optional[str] = None,
     as_baggage: bool = False,
 ) -> _AgnosticContextManager[Any]:
     """Propagate trace-level attributes to all spans created within this context.
@@ -109,6 +112,8 @@ def propagate_attributes(
             - AVOID: large payloads, sensitive data, non-string values (will be dropped with warning)
         version: Version identfier for parts of your application that are independently versioned, e.g. agents
         tags: List of tags to categorize the group of observations
+        trace_name: Name to assign to the trace. Must be US-ASCII string, ≤200 characters.
+            Use this to set a consistent trace name for all spans created within this context.
         as_baggage: If True, propagates attributes using OpenTelemetry baggage for
             cross-process/service propagation. **Security warning**: When enabled,
             attribute values are added to HTTP headers on ALL outbound requests.
@@ -195,6 +200,7 @@ def propagate_attributes(
         metadata=metadata,
         version=version,
         tags=tags,
+        trace_name=trace_name,
         as_baggage=as_baggage,
     )
 
@@ -207,6 +213,7 @@ def _propagate_attributes(
     metadata: Optional[Dict[str, str]] = None,
     version: Optional[str] = None,
     tags: Optional[List[str]] = None,
+    trace_name: Optional[str] = None,
     as_baggage: bool = False,
     experiment: Optional[PropagatedExperimentAttributes] = None,
 ) -> Generator[Any, Any, Any]:
@@ -218,6 +225,7 @@ def _propagate_attributes(
         "session_id": session_id,
         "version": version,
         "tags": tags,
+        "trace_name": trace_name,
     }
 
     propagated_string_attributes = propagated_string_attributes | (
@@ -456,6 +464,7 @@ def _get_propagated_span_key(key: str) -> str:
         "user_id": LangfuseOtelSpanAttributes.TRACE_USER_ID,
         "version": LangfuseOtelSpanAttributes.VERSION,
         "tags": LangfuseOtelSpanAttributes.TRACE_TAGS,
+        "trace_name": LangfuseOtelSpanAttributes.TRACE_NAME,
         "experiment_id": LangfuseOtelSpanAttributes.EXPERIMENT_ID,
         "experiment_name": LangfuseOtelSpanAttributes.EXPERIMENT_NAME,
         "experiment_metadata": LangfuseOtelSpanAttributes.EXPERIMENT_METADATA,

langfuse/_client/propagation.py

@@ -173,12 +173,14 @@ def _initialize_instance(
         self.sample_rate = sample_rate
         self.blocked_instrumentation_scopes = blocked_instrumentation_scopes
         self.additional_headers = additional_headers
+        self.tracer_provider: Optional[TracerProvider] = None
 
         # OTEL Tracer
         if tracing_enabled:
             tracer_provider = tracer_provider or _init_tracer_provider(
                 environment=environment, release=release, sample_rate=sample_rate
             )
+            self.tracer_provider = tracer_provider
 
             langfuse_processor = LangfuseSpanProcessor(
                 public_key=self.public_key,
@@ -397,9 +399,10 @@ def _stop_and_join_consumer_threads(self) -> None:
             )
 
     def flush(self) -> None:
-        tracer_provider = cast(TracerProvider, otel_trace_api.get_tracer_provider())
-        if not isinstance(tracer_provider, otel_trace_api.ProxyTracerProvider):
-            tracer_provider.force_flush()
+        if self.tracer_provider is not None and not isinstance(
+            self.tracer_provider, otel_trace_api.ProxyTracerProvider
+        ):
+            self.tracer_provider.force_flush()
             langfuse_logger.debug("Successfully flushed OTEL tracer provider")
 
         self._score_ingestion_queue.join()
@@ -412,10 +415,7 @@ def shutdown(self) -> None:
         # Unregister the atexit handler first
         atexit.unregister(self.shutdown)
 
-        tracer_provider = cast(TracerProvider, otel_trace_api.get_tracer_provider())
-        if not isinstance(tracer_provider, otel_trace_api.ProxyTracerProvider):
-            tracer_provider.force_flush()
-
+        self.flush()
         self._stop_and_join_consumer_threads()
 
 

langfuse/_client/resource_manager.py

@@ -276,6 +276,7 @@ def score(
         data_type: Optional[Literal["NUMERIC", "BOOLEAN"]] = None,
         comment: Optional[str] = None,
         config_id: Optional[str] = None,
+        timestamp: Optional[datetime] = None,
     ) -> None: ...
 
     @overload
@@ -288,6 +289,7 @@ def score(
         data_type: Optional[Literal["CATEGORICAL"]] = "CATEGORICAL",
         comment: Optional[str] = None,
         config_id: Optional[str] = None,
+        timestamp: Optional[datetime] = None,
     ) -> None: ...
 
     def score(
@@ -299,6 +301,7 @@ def score(
         data_type: Optional[ScoreDataType] = None,
         comment: Optional[str] = None,
         config_id: Optional[str] = None,
+        timestamp: Optional[datetime] = None,
     ) -> None:
         """Create a score for this specific span.
 
@@ -312,6 +315,7 @@ def score(
             data_type: Type of score (NUMERIC, BOOLEAN, or CATEGORICAL)
             comment: Optional comment or explanation for the score
             config_id: Optional ID of a score config defined in Langfuse
+            timestamp: Optional timestamp for the score (defaults to current UTC time)
 
         Example:
             ```python
@@ -337,6 +341,7 @@ def score(
             data_type=cast(Literal["CATEGORICAL"], data_type),
             comment=comment,
             config_id=config_id,
+            timestamp=timestamp,
         )
 
     @overload
@@ -349,6 +354,7 @@ def score_trace(
         data_type: Optional[Literal["NUMERIC", "BOOLEAN"]] = None,
         comment: Optional[str] = None,
         config_id: Optional[str] = None,
+        timestamp: Optional[datetime] = None,
     ) -> None: ...
 
     @overload
@@ -361,6 +367,7 @@ def score_trace(
         data_type: Optional[Literal["CATEGORICAL"]] = "CATEGORICAL",
         comment: Optional[str] = None,
         config_id: Optional[str] = None,
+        timestamp: Optional[datetime] = None,
     ) -> None: ...
 
     def score_trace(
@@ -372,6 +379,7 @@ def score_trace(
         data_type: Optional[ScoreDataType] = None,
         comment: Optional[str] = None,
         config_id: Optional[str] = None,
+        timestamp: Optional[datetime] = None,
     ) -> None:
         """Create a score for the entire trace that this span belongs to.
 
@@ -386,6 +394,7 @@ def score_trace(
             data_type: Type of score (NUMERIC, BOOLEAN, or CATEGORICAL)
             comment: Optional comment or explanation for the score
             config_id: Optional ID of a score config defined in Langfuse
+            timestamp: Optional timestamp for the score (defaults to current UTC time)
 
         Example:
             ```python
@@ -410,6 +419,7 @@ def score_trace(
             data_type=cast(Literal["CATEGORICAL"], data_type),
             comment=comment,
             config_id=config_id,
+            timestamp=timestamp,
         )
 
     def _set_processed_span_attributes(