docs(api): document metadata is set / is not set filter operators

langfuse/api/__init__.py

@@ -187,6 +187,7 @@
         EvaluationRuleReadFilterBase,
         EvaluationRuleReadFilterWithKey,
         EvaluationRuleStringFilterOperator,
+        EvaluationRuleStringObjectFilterOperator,
         EvaluatorOutputDefinition,
         EvaluatorOutputDefinitionBase,
         EvaluatorOutputDefinition_Boolean,
@@ -607,6 +608,7 @@
     "EvaluationRuleReadFilterBase": ".evaluation_commons",
     "EvaluationRuleReadFilterWithKey": ".evaluation_commons",
     "EvaluationRuleStringFilterOperator": ".evaluation_commons",
+    "EvaluationRuleStringObjectFilterOperator": ".evaluation_commons",
     "EvaluationRulesPage": ".evaluation_rules",
     "EvaluationUnauthorizedError": ".evaluation_errors",
     "Evaluator": ".evaluators",
@@ -1062,6 +1064,7 @@ def __dir__():
     "EvaluationRuleReadFilterBase",
     "EvaluationRuleReadFilterWithKey",
     "EvaluationRuleStringFilterOperator",
+    "EvaluationRuleStringObjectFilterOperator",
     "EvaluationRulesPage",
     "EvaluationUnauthorizedError",
     "Evaluator",

langfuse/api/evaluation_commons/__init__.py

@@ -32,6 +32,7 @@
         EvaluationRuleReadFilterBase,
         EvaluationRuleReadFilterWithKey,
         EvaluationRuleStringFilterOperator,
+        EvaluationRuleStringObjectFilterOperator,
         EvaluatorOutputDefinition,
         EvaluatorOutputDefinitionBase,
         EvaluatorOutputDefinition_Boolean,
@@ -85,6 +86,7 @@
     "EvaluationRuleReadFilterBase": ".types",
     "EvaluationRuleReadFilterWithKey": ".types",
     "EvaluationRuleStringFilterOperator": ".types",
+    "EvaluationRuleStringObjectFilterOperator": ".types",
     "EvaluatorOutputDefinition": ".types",
     "EvaluatorOutputDefinitionBase": ".types",
     "EvaluatorOutputDefinition_Boolean": ".types",
@@ -167,6 +169,7 @@ def __dir__():
     "EvaluationRuleReadFilterBase",
     "EvaluationRuleReadFilterWithKey",
     "EvaluationRuleStringFilterOperator",
+    "EvaluationRuleStringObjectFilterOperator",
     "EvaluatorOutputDefinition",
     "EvaluatorOutputDefinitionBase",
     "EvaluatorOutputDefinition_Boolean",

langfuse/api/evaluation_commons/types/__init__.py

@@ -45,6 +45,9 @@
     from .evaluation_rule_string_filter_operator import (
         EvaluationRuleStringFilterOperator,
     )
+    from .evaluation_rule_string_object_filter_operator import (
+        EvaluationRuleStringObjectFilterOperator,
+    )
     from .evaluator_output_definition import (
         EvaluatorOutputDefinition,
         EvaluatorOutputDefinition_Boolean,
@@ -101,6 +104,7 @@
     "EvaluationRuleReadFilterBase": ".evaluation_rule_read_filter_base",
     "EvaluationRuleReadFilterWithKey": ".evaluation_rule_read_filter_with_key",
     "EvaluationRuleStringFilterOperator": ".evaluation_rule_string_filter_operator",
+    "EvaluationRuleStringObjectFilterOperator": ".evaluation_rule_string_object_filter_operator",
     "EvaluatorOutputDefinition": ".evaluator_output_definition",
     "EvaluatorOutputDefinitionBase": ".evaluator_output_definition_base",
     "EvaluatorOutputDefinition_Boolean": ".evaluator_output_definition",
@@ -183,6 +187,7 @@ def __dir__():
     "EvaluationRuleReadFilterBase",
     "EvaluationRuleReadFilterWithKey",
     "EvaluationRuleStringFilterOperator",
+    "EvaluationRuleStringObjectFilterOperator",
     "EvaluatorOutputDefinition",
     "EvaluatorOutputDefinitionBase",
     "EvaluatorOutputDefinition_Boolean",

langfuse/api/evaluation_commons/types/evaluation_rule_filter.py

@@ -16,6 +16,9 @@
 from .evaluation_rule_number_filter_operator import EvaluationRuleNumberFilterOperator
 from .evaluation_rule_options_filter_operator import EvaluationRuleOptionsFilterOperator
 from .evaluation_rule_string_filter_operator import EvaluationRuleStringFilterOperator
+from .evaluation_rule_string_object_filter_operator import (
+    EvaluationRuleStringObjectFilterOperator,
+)
 
 
 class EvaluationRuleFilter_Datetime(UniversalBaseModel):
@@ -34,7 +37,7 @@ class EvaluationRuleFilter_Datetime(UniversalBaseModel):
     - `datetime`: `"="`, `">"`, `"<"`, `">="`, `"<="`
     - `stringOptions`: `any of`, `none of`
     - `arrayOptions`: `any of`, `none of`, `all of`
-    - `stringObject`: same operators as `string`
+    - `stringObject`: `"="`, `contains`, `does not contain`, `starts with`, `ends with`, `is set`, `is not set` (use `is set` / `is not set` for key presence; an empty value for `contains`, `starts with`, or `ends with` is treated as `is set`)
     - `boolean`: `"="`, `"<>"`
     - `null`: `is null`, `is not null`
 
@@ -97,7 +100,7 @@ class EvaluationRuleFilter_String(UniversalBaseModel):
     - `datetime`: `"="`, `">"`, `"<"`, `">="`, `"<="`
     - `stringOptions`: `any of`, `none of`
     - `arrayOptions`: `any of`, `none of`, `all of`
-    - `stringObject`: same operators as `string`
+    - `stringObject`: `"="`, `contains`, `does not contain`, `starts with`, `ends with`, `is set`, `is not set` (use `is set` / `is not set` for key presence; an empty value for `contains`, `starts with`, or `ends with` is treated as `is set`)
     - `boolean`: `"="`, `"<>"`
     - `null`: `is null`, `is not null`
 
@@ -160,7 +163,7 @@ class EvaluationRuleFilter_Number(UniversalBaseModel):
     - `datetime`: `"="`, `">"`, `"<"`, `">="`, `"<="`
     - `stringOptions`: `any of`, `none of`
     - `arrayOptions`: `any of`, `none of`, `all of`
-    - `stringObject`: same operators as `string`
+    - `stringObject`: `"="`, `contains`, `does not contain`, `starts with`, `ends with`, `is set`, `is not set` (use `is set` / `is not set` for key presence; an empty value for `contains`, `starts with`, or `ends with` is treated as `is set`)
     - `boolean`: `"="`, `"<>"`
     - `null`: `is null`, `is not null`
 
@@ -223,7 +226,7 @@ class EvaluationRuleFilter_StringOptions(UniversalBaseModel):
     - `datetime`: `"="`, `">"`, `"<"`, `">="`, `"<="`
     - `stringOptions`: `any of`, `none of`
     - `arrayOptions`: `any of`, `none of`, `all of`
-    - `stringObject`: same operators as `string`
+    - `stringObject`: `"="`, `contains`, `does not contain`, `starts with`, `ends with`, `is set`, `is not set` (use `is set` / `is not set` for key presence; an empty value for `contains`, `starts with`, or `ends with` is treated as `is set`)
     - `boolean`: `"="`, `"<>"`
     - `null`: `is null`, `is not null`
 
@@ -286,7 +289,7 @@ class EvaluationRuleFilter_CategoryOptions(UniversalBaseModel):
     - `datetime`: `"="`, `">"`, `"<"`, `">="`, `"<="`
     - `stringOptions`: `any of`, `none of`
     - `arrayOptions`: `any of`, `none of`, `all of`
-    - `stringObject`: same operators as `string`
+    - `stringObject`: `"="`, `contains`, `does not contain`, `starts with`, `ends with`, `is set`, `is not set` (use `is set` / `is not set` for key presence; an empty value for `contains`, `starts with`, or `ends with` is treated as `is set`)
     - `boolean`: `"="`, `"<>"`
     - `null`: `is null`, `is not null`
 
@@ -350,7 +353,7 @@ class EvaluationRuleFilter_ArrayOptions(UniversalBaseModel):
     - `datetime`: `"="`, `">"`, `"<"`, `">="`, `"<="`
     - `stringOptions`: `any of`, `none of`
     - `arrayOptions`: `any of`, `none of`, `all of`
-    - `stringObject`: same operators as `string`
+    - `stringObject`: `"="`, `contains`, `does not contain`, `starts with`, `ends with`, `is set`, `is not set` (use `is set` / `is not set` for key presence; an empty value for `contains`, `starts with`, or `ends with` is treated as `is set`)
     - `boolean`: `"="`, `"<>"`
     - `null`: `is null`, `is not null`
 
@@ -413,7 +416,7 @@ class EvaluationRuleFilter_StringObject(UniversalBaseModel):
     - `datetime`: `"="`, `">"`, `"<"`, `">="`, `"<="`
     - `stringOptions`: `any of`, `none of`
     - `arrayOptions`: `any of`, `none of`, `all of`
-    - `stringObject`: same operators as `string`
+    - `stringObject`: `"="`, `contains`, `does not contain`, `starts with`, `ends with`, `is set`, `is not set` (use `is set` / `is not set` for key presence; an empty value for `contains`, `starts with`, or `ends with` is treated as `is set`)
     - `boolean`: `"="`, `"<>"`
     - `null`: `is null`, `is not null`
 
@@ -453,7 +456,7 @@ class EvaluationRuleFilter_StringObject(UniversalBaseModel):
     type: typing.Literal["stringObject"] = "stringObject"
     column: str
     key: str
-    operator: EvaluationRuleStringFilterOperator
+    operator: EvaluationRuleStringObjectFilterOperator
     value: str
 
     model_config: typing.ClassVar[pydantic.ConfigDict] = pydantic.ConfigDict(
@@ -477,7 +480,7 @@ class EvaluationRuleFilter_NumberObject(UniversalBaseModel):
     - `datetime`: `"="`, `">"`, `"<"`, `">="`, `"<="`
     - `stringOptions`: `any of`, `none of`
     - `arrayOptions`: `any of`, `none of`, `all of`
-    - `stringObject`: same operators as `string`
+    - `stringObject`: `"="`, `contains`, `does not contain`, `starts with`, `ends with`, `is set`, `is not set` (use `is set` / `is not set` for key presence; an empty value for `contains`, `starts with`, or `ends with` is treated as `is set`)
     - `boolean`: `"="`, `"<>"`
     - `null`: `is null`, `is not null`
 
@@ -541,7 +544,7 @@ class EvaluationRuleFilter_Boolean(UniversalBaseModel):
     - `datetime`: `"="`, `">"`, `"<"`, `">="`, `"<="`
     - `stringOptions`: `any of`, `none of`
     - `arrayOptions`: `any of`, `none of`, `all of`
-    - `stringObject`: same operators as `string`
+    - `stringObject`: `"="`, `contains`, `does not contain`, `starts with`, `ends with`, `is set`, `is not set` (use `is set` / `is not set` for key presence; an empty value for `contains`, `starts with`, or `ends with` is treated as `is set`)
     - `boolean`: `"="`, `"<>"`
     - `null`: `is null`, `is not null`
 
@@ -604,7 +607,7 @@ class EvaluationRuleFilter_Null(UniversalBaseModel):
     - `datetime`: `"="`, `">"`, `"<"`, `">="`, `"<="`
     - `stringOptions`: `any of`, `none of`
     - `arrayOptions`: `any of`, `none of`, `all of`
-    - `stringObject`: same operators as `string`
+    - `stringObject`: `"="`, `contains`, `does not contain`, `starts with`, `ends with`, `is set`, `is not set` (use `is set` / `is not set` for key presence; an empty value for `contains`, `starts with`, or `ends with` is treated as `is set`)
     - `boolean`: `"="`, `"<>"`
     - `null`: `is null`, `is not null`
 

langfuse/api/evaluation_commons/types/evaluation_rule_string_object_filter_operator.py

@@ -0,0 +1,42 @@
+# This file was auto-generated by Fern from our API Definition.
+
+import typing
+
+from ...core import enum
+
+T_Result = typing.TypeVar("T_Result")
+
+
+class EvaluationRuleStringObjectFilterOperator(enum.StrEnum):
+    EQUALS = "="
+    CONTAINS = "contains"
+    DOES_NOT_CONTAIN = "does not contain"
+    STARTS_WITH = "starts with"
+    ENDS_WITH = "ends with"
+    IS_SET = "is set"
+    IS_NOT_SET = "is not set"
+
+    def visit(
+        self,
+        equals: typing.Callable[[], T_Result],
+        contains: typing.Callable[[], T_Result],
+        does_not_contain: typing.Callable[[], T_Result],
+        starts_with: typing.Callable[[], T_Result],
+        ends_with: typing.Callable[[], T_Result],
+        is_set: typing.Callable[[], T_Result],
+        is_not_set: typing.Callable[[], T_Result],
+    ) -> T_Result:
+        if self is EvaluationRuleStringObjectFilterOperator.EQUALS:
+            return equals()
+        if self is EvaluationRuleStringObjectFilterOperator.CONTAINS:
+            return contains()
+        if self is EvaluationRuleStringObjectFilterOperator.DOES_NOT_CONTAIN:
+            return does_not_contain()
+        if self is EvaluationRuleStringObjectFilterOperator.STARTS_WITH:
+            return starts_with()
+        if self is EvaluationRuleStringObjectFilterOperator.ENDS_WITH:
+            return ends_with()
+        if self is EvaluationRuleStringObjectFilterOperator.IS_SET:
+            return is_set()
+        if self is EvaluationRuleStringObjectFilterOperator.IS_NOT_SET:
+            return is_not_set()

langfuse/api/evaluation_commons/types/string_object_evaluation_rule_filter.py

@@ -4,7 +4,9 @@
 
 import pydantic
 from ...core.pydantic_utilities import UniversalBaseModel
-from .evaluation_rule_string_filter_operator import EvaluationRuleStringFilterOperator
+from .evaluation_rule_string_object_filter_operator import (
+    EvaluationRuleStringObjectFilterOperator,
+)
 
 
 class StringObjectEvaluationRuleFilter(UniversalBaseModel):
@@ -18,8 +20,15 @@ class StringObjectEvaluationRuleFilter(UniversalBaseModel):
     Top-level key inside the object-valued column to filter on.
     """
 
-    operator: EvaluationRuleStringFilterOperator
-    value: str
+    operator: EvaluationRuleStringObjectFilterOperator = pydantic.Field()
+    """
+    Use `is set` / `is not set` to filter on key presence.
+    """
+
+    value: str = pydantic.Field()
+    """
+    Value to compare against. Ignored for `is set` / `is not set`; send `""`.
+    """
 
     model_config: typing.ClassVar[pydantic.ConfigDict] = pydantic.ConfigDict(
         extra="allow", frozen=True

langfuse/api/legacy/observations_v1/client.py

@@ -150,7 +150,7 @@ def get_many(
                                           // - categoryOptions: "any of", "none of"
                                           // - arrayOptions: "any of", "none of", "all of"
                                           // - number: "=", ">", "<", ">=", "<="
-                                          // - stringObject: "=", "contains", "does not contain", "starts with", "ends with"
+                                          // - stringObject: "=", "contains", "does not contain", "starts with", "ends with", "is set", "is not set"
                                           // - numberObject: "=", ">", "<", ">=", "<="
                                           // - boolean: "=", "<>"
                                           // - null: "is null", "is not null"
@@ -414,7 +414,7 @@ async def get_many(
                                           // - categoryOptions: "any of", "none of"
                                           // - arrayOptions: "any of", "none of", "all of"
                                           // - number: "=", ">", "<", ">=", "<="
-                                          // - stringObject: "=", "contains", "does not contain", "starts with", "ends with"
+                                          // - stringObject: "=", "contains", "does not contain", "starts with", "ends with", "is set", "is not set"
                                           // - numberObject: "=", ">", "<", ">=", "<="
                                           // - boolean: "=", "<>"
                                           // - null: "is null", "is not null"

langfuse/api/legacy/observations_v1/raw_client.py

@@ -211,7 +211,7 @@ def get_many(
                                           // - categoryOptions: "any of", "none of"
                                           // - arrayOptions: "any of", "none of", "all of"
                                           // - number: "=", ">", "<", ">=", "<="
-                                          // - stringObject: "=", "contains", "does not contain", "starts with", "ends with"
+                                          // - stringObject: "=", "contains", "does not contain", "starts with", "ends with", "is set", "is not set"
                                           // - numberObject: "=", ">", "<", ">=", "<="
                                           // - boolean: "=", "<>"
                                           // - null: "is null", "is not null"
@@ -588,7 +588,7 @@ async def get_many(
                                           // - categoryOptions: "any of", "none of"
                                           // - arrayOptions: "any of", "none of", "all of"
                                           // - number: "=", ">", "<", ">=", "<="
-                                          // - stringObject: "=", "contains", "does not contain", "starts with", "ends with"
+                                          // - stringObject: "=", "contains", "does not contain", "starts with", "ends with", "is set", "is not set"
                                           // - numberObject: "=", ">", "<", ">=", "<="
                                           // - boolean: "=", "<>"
                                           // - null: "is null", "is not null"

langfuse/api/observations/client.py

@@ -153,7 +153,7 @@ def get_many(
                                           // - categoryOptions: "any of", "none of"
                                           // - arrayOptions: "any of", "none of", "all of"
                                           // - number: "=", ">", "<", ">=", "<="
-                                          // - stringObject: "=", "contains", "does not contain", "starts with", "ends with", "matches"
+                                          // - stringObject: "=", "contains", "does not contain", "starts with", "ends with", "matches", "is set", "is not set"
                                           // - numberObject: "=", ">", "<", ">=", "<="
                                           // - boolean: "=", "<>"
                                           // - null: "is null", "is not null"
@@ -437,7 +437,7 @@ async def get_many(
                                           // - categoryOptions: "any of", "none of"
                                           // - arrayOptions: "any of", "none of", "all of"
                                           // - number: "=", ">", "<", ">=", "<="
-                                          // - stringObject: "=", "contains", "does not contain", "starts with", "ends with", "matches"
+                                          // - stringObject: "=", "contains", "does not contain", "starts with", "ends with", "matches", "is set", "is not set"
                                           // - numberObject: "=", ">", "<", ">=", "<="
                                           // - boolean: "=", "<>"
                                           // - null: "is null", "is not null"

langfuse/api/observations/raw_client.py

@@ -151,7 +151,7 @@ def get_many(
                                           // - categoryOptions: "any of", "none of"
                                           // - arrayOptions: "any of", "none of", "all of"
                                           // - number: "=", ">", "<", ">=", "<="
-                                          // - stringObject: "=", "contains", "does not contain", "starts with", "ends with", "matches"
+                                          // - stringObject: "=", "contains", "does not contain", "starts with", "ends with", "matches", "is set", "is not set"
                                           // - numberObject: "=", ">", "<", ">=", "<="
                                           // - boolean: "=", "<>"
                                           // - null: "is null", "is not null"
@@ -494,7 +494,7 @@ async def get_many(
                                           // - categoryOptions: "any of", "none of"
                                           // - arrayOptions: "any of", "none of", "all of"
                                           // - number: "=", ">", "<", ">=", "<="
-                                          // - stringObject: "=", "contains", "does not contain", "starts with", "ends with", "matches"
+                                          // - stringObject: "=", "contains", "does not contain", "starts with", "ends with", "matches", "is set", "is not set"
                                           // - numberObject: "=", ">", "<", ">=", "<="
                                           // - boolean: "=", "<>"
                                           // - null: "is null", "is not null"