feat(api): update API spec from langfuse/langfuse 1999706 (#1615)

* feat(api): update API spec from langfuse/langfuse 1999706

* feat(scores): add TEXT type to score overloads and docstrings

Extend string-value overloads in create_score, score_current_span,
score_current_trace, score, and score_trace to accept TEXT alongside
CATEGORICAL. Update all related docstrings. Add ExperimentScoreType
to exclude TEXT from experiments/evals. Add integration test for TEXT
scores.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* docs: simplify openapi spec update instructions in CONTRIBUTING.md

The spec update is now automated via PR from the langfuse repo.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix(scores): update stale casts and export ExperimentScoreType

Update cast(Literal["CATEGORICAL"], ...) to include "TEXT" in
score/score_trace/score_current_span/score_current_trace impl bodies.
Add ExperimentScoreType to __all__ in types.py.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* ci: fix tests by adding dynamic retry

* tests: adapt to update server logic

* ci: cache pnpm store instead of node_modules to avoid stale server state

Caching node_modules directly caused postinstall hooks (e.g. prisma
generate) to be skipped, leading to stale generated artifacts that
didn't match the current langfuse-server schema. Cache the pnpm store
instead so installs are still fast but hooks run properly.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* ci: revert caching changes

---------

Co-authored-by: langfuse-bot <langfuse-bot@langfuse.com>
Co-authored-by: Tobias Wochinger <tobias.wochinger@clickhouse.com>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: 4 people

.github/workflows/ci.yml

@@ -93,9 +93,9 @@ jobs:
         uses: actions/cache@668228422ae6a00e4ad889ee87cd7109ec5666a7 # v5
         with:
           path: ./langfuse-server/node_modules
-          key: |
-            langfuse-server-${{ hashFiles('./langfuse-server/package-lock.json') }}
-            langfuse-server-
+          key: langfuse-serve-${{ hashFiles('langfuse-server/pnpm-lock.yaml') }}
+          restore-keys: |
+            langfuse-serve-
 
       - name: Run langfuse server
         run: |

CONTRIBUTING.md

@@ -45,9 +45,7 @@ uv run mypy langfuse --no-error-summary
 
 ### Update openapi spec
 
-1. Generate Fern Python SDK in [langfuse](https://github.com/langfuse/langfuse) and copy the files generated in `generated/python` into the `langfuse/api` folder in this repo.
-2. Execute the linter by running `uv run ruff format .`
-3. Rebuild and deploy the package to PyPi.
+A PR with the changes is automatically created upon changing the Spec in the langfuse repo.
 
 ### Publish release
 

langfuse/_client/client.py

@@ -1747,7 +1747,7 @@ def create_score(
         trace_id: Optional[str] = None,
         score_id: Optional[str] = None,
         observation_id: Optional[str] = None,
-        data_type: Optional[Literal["CATEGORICAL"]] = "CATEGORICAL",
+        data_type: Optional[Literal["CATEGORICAL", "TEXT"]] = "CATEGORICAL",
         comment: Optional[str] = None,
         config_id: Optional[str] = None,
         metadata: Optional[Any] = None,
@@ -1777,13 +1777,13 @@ def create_score(
 
         Args:
             name: Name of the score (e.g., "relevance", "accuracy")
-            value: Score value (can be numeric for NUMERIC/BOOLEAN types or string for CATEGORICAL)
+            value: Score value (can be numeric for NUMERIC/BOOLEAN types or string for CATEGORICAL/TEXT)
             session_id: ID of the Langfuse session to associate the score with
             dataset_run_id: ID of the Langfuse dataset run to associate the score with
             trace_id: ID of the Langfuse trace to associate the score with
             observation_id: Optional ID of the specific observation to score. Trace ID must be provided too.
             score_id: Optional custom ID for the score (auto-generated if not provided)
-            data_type: Type of score (NUMERIC, BOOLEAN, or CATEGORICAL)
+            data_type: Type of score (NUMERIC, BOOLEAN, CATEGORICAL, or TEXT)
             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
@@ -1907,7 +1907,7 @@ def score_current_span(
         name: str,
         value: str,
         score_id: Optional[str] = None,
-        data_type: Optional[Literal["CATEGORICAL"]] = "CATEGORICAL",
+        data_type: Optional[Literal["CATEGORICAL", "TEXT"]] = "CATEGORICAL",
         comment: Optional[str] = None,
         config_id: Optional[str] = None,
         metadata: Optional[Any] = None,
@@ -1931,9 +1931,9 @@ def score_current_span(
 
         Args:
             name: Name of the score (e.g., "relevance", "accuracy")
-            value: Score value (can be numeric for NUMERIC/BOOLEAN types or string for CATEGORICAL)
+            value: Score value (can be numeric for NUMERIC/BOOLEAN types or string for CATEGORICAL/TEXT)
             score_id: Optional custom ID for the score (auto-generated if not provided)
-            data_type: Type of score (NUMERIC, BOOLEAN, or CATEGORICAL)
+            data_type: Type of score (NUMERIC, BOOLEAN, CATEGORICAL, or TEXT)
             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
@@ -1971,7 +1971,7 @@ def score_current_span(
                 name=name,
                 value=cast(str, value),
                 score_id=score_id,
-                data_type=cast(Literal["CATEGORICAL"], data_type),
+                data_type=cast(Literal["CATEGORICAL", "TEXT"], data_type),
                 comment=comment,
                 config_id=config_id,
                 metadata=metadata,
@@ -1997,7 +1997,7 @@ def score_current_trace(
         name: str,
         value: str,
         score_id: Optional[str] = None,
-        data_type: Optional[Literal["CATEGORICAL"]] = "CATEGORICAL",
+        data_type: Optional[Literal["CATEGORICAL", "TEXT"]] = "CATEGORICAL",
         comment: Optional[str] = None,
         config_id: Optional[str] = None,
         metadata: Optional[Any] = None,
@@ -2022,9 +2022,9 @@ def score_current_trace(
 
         Args:
             name: Name of the score (e.g., "user_satisfaction", "overall_quality")
-            value: Score value (can be numeric for NUMERIC/BOOLEAN types or string for CATEGORICAL)
+            value: Score value (can be numeric for NUMERIC/BOOLEAN types or string for CATEGORICAL/TEXT)
             score_id: Optional custom ID for the score (auto-generated if not provided)
-            data_type: Type of score (NUMERIC, BOOLEAN, or CATEGORICAL)
+            data_type: Type of score (NUMERIC, BOOLEAN, CATEGORICAL, or TEXT)
             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
@@ -2060,7 +2060,7 @@ def score_current_trace(
                 name=name,
                 value=cast(str, value),
                 score_id=score_id,
-                data_type=cast(Literal["CATEGORICAL"], data_type),
+                data_type=cast(Literal["CATEGORICAL", "TEXT"], data_type),
                 comment=comment,
                 config_id=config_id,
                 metadata=metadata,

langfuse/_client/span.py

@@ -308,7 +308,7 @@ def score(
         value: str,
         score_id: Optional[str] = None,
         data_type: Optional[
-            Literal[ScoreDataType.CATEGORICAL]
+            Literal[ScoreDataType.CATEGORICAL, ScoreDataType.TEXT]
         ] = ScoreDataType.CATEGORICAL,
         comment: Optional[str] = None,
         config_id: Optional[str] = None,
@@ -335,9 +335,9 @@ def score(
 
         Args:
             name: Name of the score (e.g., "relevance", "accuracy")
-            value: Score value (numeric for NUMERIC/BOOLEAN, string for CATEGORICAL)
+            value: Score value (numeric for NUMERIC/BOOLEAN, string for CATEGORICAL/TEXT)
             score_id: Optional custom ID for the score (auto-generated if not provided)
-            data_type: Type of score (NUMERIC, BOOLEAN, or CATEGORICAL)
+            data_type: Type of score (NUMERIC, BOOLEAN, CATEGORICAL, or TEXT)
             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)
@@ -364,7 +364,7 @@ def score(
             trace_id=self.trace_id,
             observation_id=self.id,
             score_id=score_id,
-            data_type=cast(Literal["CATEGORICAL"], data_type),
+            data_type=cast(Literal["CATEGORICAL", "TEXT"], data_type),
             comment=comment,
             config_id=config_id,
             timestamp=timestamp,
@@ -395,7 +395,7 @@ def score_trace(
         value: str,
         score_id: Optional[str] = None,
         data_type: Optional[
-            Literal[ScoreDataType.CATEGORICAL]
+            Literal[ScoreDataType.CATEGORICAL, ScoreDataType.TEXT]
         ] = ScoreDataType.CATEGORICAL,
         comment: Optional[str] = None,
         config_id: Optional[str] = None,
@@ -423,9 +423,9 @@ def score_trace(
 
         Args:
             name: Name of the score (e.g., "user_satisfaction", "overall_quality")
-            value: Score value (numeric for NUMERIC/BOOLEAN, string for CATEGORICAL)
+            value: Score value (numeric for NUMERIC/BOOLEAN, string for CATEGORICAL/TEXT)
             score_id: Optional custom ID for the score (auto-generated if not provided)
-            data_type: Type of score (NUMERIC, BOOLEAN, or CATEGORICAL)
+            data_type: Type of score (NUMERIC, BOOLEAN, CATEGORICAL, or TEXT)
             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)
@@ -451,7 +451,7 @@ def score_trace(
             value=cast(str, value),
             trace_id=self.trace_id,
             score_id=score_id,
-            data_type=cast(Literal["CATEGORICAL"], data_type),
+            data_type=cast(Literal["CATEGORICAL", "TEXT"], data_type),
             comment=comment,
             config_id=config_id,
             timestamp=timestamp,

langfuse/api/__init__.py

@@ -112,12 +112,16 @@
         ScoreV1_Boolean,
         ScoreV1_Categorical,
         ScoreV1_Numeric,
+        ScoreV1_Text,
         Score_Boolean,
         Score_Categorical,
         Score_Correction,
         Score_Numeric,
+        Score_Text,
         Session,
         SessionWithTraces,
+        TextScore,
+        TextScoreV1,
         Trace,
         TraceWithDetails,
         TraceWithFullDetails,
@@ -281,10 +285,12 @@
         GetScoresResponseDataCategorical,
         GetScoresResponseDataCorrection,
         GetScoresResponseDataNumeric,
+        GetScoresResponseDataText,
         GetScoresResponseData_Boolean,
         GetScoresResponseData_Categorical,
         GetScoresResponseData_Correction,
         GetScoresResponseData_Numeric,
+        GetScoresResponseData_Text,
         GetScoresResponseTraceData,
     )
     from .sessions import PaginatedSessions
@@ -377,10 +383,12 @@
     "GetScoresResponseDataCategorical": ".scores",
     "GetScoresResponseDataCorrection": ".scores",
     "GetScoresResponseDataNumeric": ".scores",
+    "GetScoresResponseDataText": ".scores",
     "GetScoresResponseData_Boolean": ".scores",
     "GetScoresResponseData_Categorical": ".scores",
     "GetScoresResponseData_Correction": ".scores",
     "GetScoresResponseData_Numeric": ".scores",
+    "GetScoresResponseData_Text": ".scores",
     "GetScoresResponseTraceData": ".scores",
     "HealthResponse": ".health",
     "IngestionError": ".ingestion",
@@ -489,10 +497,12 @@
     "ScoreV1_Boolean": ".commons",
     "ScoreV1_Categorical": ".commons",
     "ScoreV1_Numeric": ".commons",
+    "ScoreV1_Text": ".commons",
     "Score_Boolean": ".commons",
     "Score_Categorical": ".commons",
     "Score_Correction": ".commons",
     "Score_Numeric": ".commons",
+    "Score_Text": ".commons",
     "SdkLogBody": ".ingestion",
     "SdkLogEvent": ".ingestion",
     "ServiceProviderConfig": ".scim",
@@ -501,6 +511,8 @@
     "SessionWithTraces": ".commons",
     "Sort": ".trace",
     "TextPrompt": ".prompts",
+    "TextScore": ".commons",
+    "TextScoreV1": ".commons",
     "Trace": ".commons",
     "TraceBody": ".ingestion",
     "TraceEvent": ".ingestion",
@@ -664,10 +676,12 @@ def __dir__():
     "GetScoresResponseDataCategorical",
     "GetScoresResponseDataCorrection",
     "GetScoresResponseDataNumeric",
+    "GetScoresResponseDataText",
     "GetScoresResponseData_Boolean",
     "GetScoresResponseData_Categorical",
     "GetScoresResponseData_Correction",
     "GetScoresResponseData_Numeric",
+    "GetScoresResponseData_Text",
     "GetScoresResponseTraceData",
     "HealthResponse",
     "IngestionError",
@@ -776,10 +790,12 @@ def __dir__():
     "ScoreV1_Boolean",
     "ScoreV1_Categorical",
     "ScoreV1_Numeric",
+    "ScoreV1_Text",
     "Score_Boolean",
     "Score_Categorical",
     "Score_Correction",
     "Score_Numeric",
+    "Score_Text",
     "SdkLogBody",
     "SdkLogEvent",
     "ServiceProviderConfig",
@@ -788,6 +804,8 @@ def __dir__():
     "SessionWithTraces",
     "Sort",
     "TextPrompt",
+    "TextScore",
+    "TextScoreV1",
     "Trace",
     "TraceBody",
     "TraceEvent",

langfuse/api/commons/__init__.py

@@ -47,12 +47,16 @@
         ScoreV1_Boolean,
         ScoreV1_Categorical,
         ScoreV1_Numeric,
+        ScoreV1_Text,
         Score_Boolean,
         Score_Categorical,
         Score_Correction,
         Score_Numeric,
+        Score_Text,
         Session,
         SessionWithTraces,
+        TextScore,
+        TextScoreV1,
         Trace,
         TraceWithDetails,
         TraceWithFullDetails,
@@ -110,12 +114,16 @@
     "ScoreV1_Boolean": ".types",
     "ScoreV1_Categorical": ".types",
     "ScoreV1_Numeric": ".types",
+    "ScoreV1_Text": ".types",
     "Score_Boolean": ".types",
     "Score_Categorical": ".types",
     "Score_Correction": ".types",
     "Score_Numeric": ".types",
+    "Score_Text": ".types",
     "Session": ".types",
     "SessionWithTraces": ".types",
+    "TextScore": ".types",
+    "TextScoreV1": ".types",
     "Trace": ".types",
     "TraceWithDetails": ".types",
     "TraceWithFullDetails": ".types",
@@ -196,12 +204,16 @@ def __dir__():
     "ScoreV1_Boolean",
     "ScoreV1_Categorical",
     "ScoreV1_Numeric",
+    "ScoreV1_Text",
     "Score_Boolean",
     "Score_Categorical",
     "Score_Correction",
     "Score_Numeric",
+    "Score_Text",
     "Session",
     "SessionWithTraces",
+    "TextScore",
+    "TextScoreV1",
     "Trace",
     "TraceWithDetails",
     "TraceWithFullDetails",

langfuse/api/commons/types/__init__.py

@@ -43,14 +43,23 @@
         Score_Categorical,
         Score_Correction,
         Score_Numeric,
+        Score_Text,
     )
     from .score_config import ScoreConfig
     from .score_config_data_type import ScoreConfigDataType
     from .score_data_type import ScoreDataType
     from .score_source import ScoreSource
-    from .score_v1 import ScoreV1, ScoreV1_Boolean, ScoreV1_Categorical, ScoreV1_Numeric
+    from .score_v1 import (
+        ScoreV1,
+        ScoreV1_Boolean,
+        ScoreV1_Categorical,
+        ScoreV1_Numeric,
+        ScoreV1_Text,
+    )
     from .session import Session
     from .session_with_traces import SessionWithTraces
+    from .text_score import TextScore
+    from .text_score_v1 import TextScoreV1
     from .trace import Trace
     from .trace_with_details import TraceWithDetails
     from .trace_with_full_details import TraceWithFullDetails
@@ -96,12 +105,16 @@
     "ScoreV1_Boolean": ".score_v1",
     "ScoreV1_Categorical": ".score_v1",
     "ScoreV1_Numeric": ".score_v1",
+    "ScoreV1_Text": ".score_v1",
     "Score_Boolean": ".score",
     "Score_Categorical": ".score",
     "Score_Correction": ".score",
     "Score_Numeric": ".score",
+    "Score_Text": ".score",
     "Session": ".session",
     "SessionWithTraces": ".session_with_traces",
+    "TextScore": ".text_score",
+    "TextScoreV1": ".text_score_v1",
     "Trace": ".trace",
     "TraceWithDetails": ".trace_with_details",
     "TraceWithFullDetails": ".trace_with_full_details",
@@ -177,12 +190,16 @@ def __dir__():
     "ScoreV1_Boolean",
     "ScoreV1_Categorical",
     "ScoreV1_Numeric",
+    "ScoreV1_Text",
     "Score_Boolean",
     "Score_Categorical",
     "Score_Correction",
     "Score_Numeric",
+    "Score_Text",
     "Session",
     "SessionWithTraces",
+    "TextScore",
+    "TextScoreV1",
     "Trace",
     "TraceWithDetails",
     "TraceWithFullDetails",