feat(api): update API spec from langfuse/langfuse 41f064c (#1492)

Co-authored-by: langfuse-bot <[email protected]>
Co-authored-by: Hassieb Pakzad <[email protected]>

Author: 3 people

langfuse/api/reference.md

@@ -3635,7 +3635,7 @@ Use the `fields` parameter to control which observation fields are returned:
 - `basic` - name, level, statusMessage, version, environment, bookmarked, public, userId, sessionId
 - `time` - completionStartTime, createdAt, updatedAt
 - `io` - input, output
-- `metadata` - metadata
+- `metadata` - metadata (truncated to 200 chars by default, use `expandMetadata` to get full values)
 - `model` - providedModelName, internalModelId, modelParameters
 - `usage` - usageDetails, costDetails, totalCost
 - `prompt` - promptId, promptName, promptVersion
@@ -3699,6 +3699,19 @@ Example: "basic,usage,model"
 <dl>
 <dd>
 
+**expand_metadata:** `typing.Optional[str]` 
+
+Comma-separated list of metadata keys to return non-truncated.
+By default, metadata values over 200 characters are truncated.
+Use this parameter to retrieve full values for specific keys.
+Example: "key1,key2"
+    
+</dd>
+</dl>
+
+<dl>
+<dd>
+
 **limit:** `typing.Optional[int]` — Number of items to return per page. Maximum 1000, default 50.
 
 </dd>

langfuse/api/resources/commons/types/base_score.py

@@ -11,15 +11,31 @@
 class BaseScore(pydantic_v1.BaseModel):
     id: str
     trace_id: typing.Optional[str] = pydantic_v1.Field(alias="traceId", default=None)
+    """
+    The trace ID associated with the score
+    """
+
     session_id: typing.Optional[str] = pydantic_v1.Field(
         alias="sessionId", default=None
     )
+    """
+    The session ID associated with the score
+    """
+
     observation_id: typing.Optional[str] = pydantic_v1.Field(
         alias="observationId", default=None
     )
+    """
+    The observation ID associated with the score
+    """
+
     dataset_run_id: typing.Optional[str] = pydantic_v1.Field(
         alias="datasetRunId", default=None
     )
+    """
+    The dataset run ID associated with the score
+    """
+
     name: str
     source: ScoreSource
     timestamp: dt.datetime
@@ -28,8 +44,20 @@ class BaseScore(pydantic_v1.BaseModel):
     author_user_id: typing.Optional[str] = pydantic_v1.Field(
         alias="authorUserId", default=None
     )
-    comment: typing.Optional[str] = None
-    metadata: typing.Optional[typing.Any] = None
+    """
+    The user ID of the author
+    """
+
+    comment: typing.Optional[str] = pydantic_v1.Field(default=None)
+    """
+    Comment on the score
+    """
+
+    metadata: typing.Any = pydantic_v1.Field()
+    """
+    Metadata associated with the score
+    """
+
     config_id: typing.Optional[str] = pydantic_v1.Field(alias="configId", default=None)
     """
     Reference a score config on a score. When set, config and score name must be equal and value must comply to optionally defined numerical range
@@ -40,7 +68,7 @@ class BaseScore(pydantic_v1.BaseModel):
     The annotation queue referenced by the score. Indicates if score was initially created while processing annotation queue.
     """
 
-    environment: typing.Optional[str] = pydantic_v1.Field(default=None)
+    environment: str = pydantic_v1.Field()
     """
     The environment from which this score originated. Can be any lowercase alphanumeric string with hyphens and underscores that does not start with 'langfuse'.
     """

langfuse/api/resources/commons/types/base_score_v_1.py

@@ -16,14 +16,30 @@ class BaseScoreV1(pydantic_v1.BaseModel):
     observation_id: typing.Optional[str] = pydantic_v1.Field(
         alias="observationId", default=None
     )
+    """
+    The observation ID associated with the score
+    """
+
     timestamp: dt.datetime
     created_at: dt.datetime = pydantic_v1.Field(alias="createdAt")
     updated_at: dt.datetime = pydantic_v1.Field(alias="updatedAt")
     author_user_id: typing.Optional[str] = pydantic_v1.Field(
         alias="authorUserId", default=None
     )
-    comment: typing.Optional[str] = None
-    metadata: typing.Optional[typing.Any] = None
+    """
+    The user ID of the author
+    """
+
+    comment: typing.Optional[str] = pydantic_v1.Field(default=None)
+    """
+    Comment on the score
+    """
+
+    metadata: typing.Any = pydantic_v1.Field()
+    """
+    Metadata associated with the score
+    """
+
     config_id: typing.Optional[str] = pydantic_v1.Field(alias="configId", default=None)
     """
     Reference a score config on a score. When set, config and score name must be equal and value must comply to optionally defined numerical range
@@ -34,7 +50,7 @@ class BaseScoreV1(pydantic_v1.BaseModel):
     The annotation queue referenced by the score. Indicates if score was initially created while processing annotation queue.
     """
 
-    environment: typing.Optional[str] = pydantic_v1.Field(default=None)
+    environment: str = pydantic_v1.Field()
     """
     The environment from which this score originated. Can be any lowercase alphanumeric string with hyphens and underscores that does not start with 'langfuse'.
     """

langfuse/api/resources/commons/types/comment.py

@@ -19,6 +19,9 @@ class Comment(pydantic_v1.BaseModel):
     author_user_id: typing.Optional[str] = pydantic_v1.Field(
         alias="authorUserId", default=None
     )
+    """
+    The user ID of the comment author
+    """
 
     def json(self, **kwargs: typing.Any) -> str:
         kwargs_with_defaults: typing.Any = {

langfuse/api/resources/commons/types/dataset.py

@@ -10,8 +10,16 @@
 class Dataset(pydantic_v1.BaseModel):
     id: str
     name: str
-    description: typing.Optional[str] = None
-    metadata: typing.Optional[typing.Any] = None
+    description: typing.Optional[str] = pydantic_v1.Field(default=None)
+    """
+    Description of the dataset
+    """
+
+    metadata: typing.Any = pydantic_v1.Field()
+    """
+    Metadata associated with the dataset
+    """
+
     input_schema: typing.Optional[typing.Any] = pydantic_v1.Field(
         alias="inputSchema", default=None
     )

langfuse/api/resources/commons/types/dataset_item.py

@@ -11,17 +11,35 @@
 class DatasetItem(pydantic_v1.BaseModel):
     id: str
     status: DatasetStatus
-    input: typing.Optional[typing.Any] = None
-    expected_output: typing.Optional[typing.Any] = pydantic_v1.Field(
-        alias="expectedOutput", default=None
-    )
-    metadata: typing.Optional[typing.Any] = None
+    input: typing.Any = pydantic_v1.Field()
+    """
+    Input data for the dataset item
+    """
+
+    expected_output: typing.Any = pydantic_v1.Field(alias="expectedOutput")
+    """
+    Expected output for the dataset item
+    """
+
+    metadata: typing.Any = pydantic_v1.Field()
+    """
+    Metadata associated with the dataset item
+    """
+
     source_trace_id: typing.Optional[str] = pydantic_v1.Field(
         alias="sourceTraceId", default=None
     )
+    """
+    The trace ID that sourced this dataset item
+    """
+
     source_observation_id: typing.Optional[str] = pydantic_v1.Field(
         alias="sourceObservationId", default=None
     )
+    """
+    The observation ID that sourced this dataset item
+    """
+
     dataset_id: str = pydantic_v1.Field(alias="datasetId")
     dataset_name: str = pydantic_v1.Field(alias="datasetName")
     created_at: dt.datetime = pydantic_v1.Field(alias="createdAt")

langfuse/api/resources/commons/types/dataset_run.py

@@ -23,7 +23,7 @@ class DatasetRun(pydantic_v1.BaseModel):
     Description of the run
     """
 
-    metadata: typing.Optional[typing.Any] = pydantic_v1.Field(default=None)
+    metadata: typing.Any = pydantic_v1.Field()
     """
     Metadata of the dataset run
     """

langfuse/api/resources/commons/types/dataset_run_item.py

@@ -16,6 +16,10 @@ class DatasetRunItem(pydantic_v1.BaseModel):
     observation_id: typing.Optional[str] = pydantic_v1.Field(
         alias="observationId", default=None
     )
+    """
+    The observation ID associated with this run item
+    """
+
     created_at: dt.datetime = pydantic_v1.Field(alias="createdAt")
     updated_at: dt.datetime = pydantic_v1.Field(alias="updatedAt")
 

langfuse/api/resources/commons/types/model.py

@@ -74,9 +74,7 @@ class Model(pydantic_v1.BaseModel):
     Optional. Tokenizer to be applied to observations which match to this model. See docs for more details.
     """
 
-    tokenizer_config: typing.Optional[typing.Any] = pydantic_v1.Field(
-        alias="tokenizerConfig", default=None
-    )
+    tokenizer_config: typing.Any = pydantic_v1.Field(alias="tokenizerConfig")
     """
     Optional. Configuration for the selected tokenizer. Needs to be JSON. See docs for more details.
     """

langfuse/api/resources/commons/types/observation.py

@@ -5,7 +5,6 @@
 
 from ....core.datetime_utils import serialize_datetime
 from ....core.pydantic_utilities import deep_union_pydantic_dicts, pydantic_v1
-from .map_value import MapValue
 from .observation_level import ObservationLevel
 from .usage import Usage
 
@@ -55,14 +54,12 @@ class Observation(pydantic_v1.BaseModel):
     The model used for the observation
     """
 
-    model_parameters: typing.Optional[typing.Dict[str, MapValue]] = pydantic_v1.Field(
-        alias="modelParameters", default=None
-    )
+    model_parameters: typing.Any = pydantic_v1.Field(alias="modelParameters")
     """
     The parameters of the model used for the observation
     """
 
-    input: typing.Optional[typing.Any] = pydantic_v1.Field(default=None)
+    input: typing.Any = pydantic_v1.Field()
     """
     The input data of the observation
     """
@@ -72,17 +69,17 @@ class Observation(pydantic_v1.BaseModel):
     The version of the observation
     """
 
-    metadata: typing.Optional[typing.Any] = pydantic_v1.Field(default=None)
+    metadata: typing.Any = pydantic_v1.Field()
     """
     Additional metadata of the observation
     """
 
-    output: typing.Optional[typing.Any] = pydantic_v1.Field(default=None)
+    output: typing.Any = pydantic_v1.Field()
     """
     The output data of the observation
     """
 
-    usage: typing.Optional[Usage] = pydantic_v1.Field(default=None)
+    usage: Usage = pydantic_v1.Field()
     """
     (Deprecated. Use usageDetails and costDetails instead.) The usage data of the observation
     """
@@ -111,21 +108,17 @@ class Observation(pydantic_v1.BaseModel):
     The prompt ID associated with the observation
     """
 
-    usage_details: typing.Optional[typing.Dict[str, int]] = pydantic_v1.Field(
-        alias="usageDetails", default=None
-    )
+    usage_details: typing.Dict[str, int] = pydantic_v1.Field(alias="usageDetails")
     """
     The usage details of the observation. Key is the name of the usage metric, value is the number of units consumed. The total key is the sum of all (non-total) usage metrics or the total value ingested.
     """
 
-    cost_details: typing.Optional[typing.Dict[str, float]] = pydantic_v1.Field(
-        alias="costDetails", default=None
-    )
+    cost_details: typing.Dict[str, float] = pydantic_v1.Field(alias="costDetails")
     """
     The cost details of the observation. Key is the name of the cost metric, value is the cost in USD. The total key is the sum of all (non-total) cost metrics or the total value ingested.
     """
 
-    environment: typing.Optional[str] = pydantic_v1.Field(default=None)
+    environment: str = pydantic_v1.Field()
     """
     The environment from which this observation originated. Can be any lowercase alphanumeric string with hyphens and underscores that does not start with 'langfuse'.
     """