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

[niklassemmler]

What does this PR do?

Split out of #1943 (the bot sync from langfuse/langfuse 4e733d0), so that each upstream API definition change can be reviewed and merged on its own. Regenerated langfuse/api from the last synced spec (langfuse/langfuse 619dbe3) with only this upstream change applied, using the same post-processing as sdk-api-spec.yml.

Upstream: langfuse/langfuse#17357, langfuse/langfuse#18404. JS counterpart: langfuse/langfuse-js#989.

• Documents the is set / is not set metadata key presence operators in the filter docs of traces, observations (v1 and v2) and scores.
• Adds EvaluationRuleStringObjectFilterOperator (the string operators plus is set / is not set) and uses it for StringObjectEvaluationRuleFilter.operator and EvaluationRuleFilter_StringObject.operator.

Breaking changes

No breaking changes at runtime. The new enum is a superset of EvaluationRuleStringFilterOperator, so response validation only gets looser: before, a rule using is set would have failed to validate. Old enum values passed to the field are still accepted at runtime and compare equal. Type-level only:

• mypy flags passing EvaluationRuleStringFilterOperator to this field, and isinstance checks against the old enum now return False.
• operator.visit(...) now requires is_set / is_not_set handlers.

Both are unlikely in practice.

Type of change

• Documentation update
• New feature (new enum)

Verification

uv run --frozen ruff check .                      # pass
uv run --frozen ruff format --check .             # only tests/unit/test_media.py, same on main
uv run --frozen mypy langfuse --no-error-summary  # pass
uv run --frozen pytest -n auto --dist worksteal tests/unit   # 696 passed, 2 skipped, 18 errors; identical on unmodified main

The 18 errors are all in tests/unit/test_prompt.py (Langfuse client is not initialized) and reproduce identically on unmodified main locally, so they are environmental and not caused by this diff.

Skipped: tests/e2e and tests/live_provider, because no Langfuse server or provider credentials were available locally.

Generation was checked against the bot output: regenerating langfuse/langfuse 619dbe3 (the last synced spec, #1866) with the same steps as sdk-api-spec.yml reproduces main exactly, and regenerating 4e733d0 reproduces #1943 byte-for-byte. scripts/patch_generated_score_compat.py ran and is a no-op on this tree.

Checklist

• I self-reviewed the diff using code_review.md.
• I added or updated tests for behavior changes. (generated client only)
• I updated docs, examples, or .env.template if needed. (n/a)
• I did not hand-edit generated files; if generated files changed, I used the upstream regeneration path.
• I did not commit secrets or credentials.

Release info

Bump level: patch (ships in the current 4.x major).

🤖 Generated with Claude Code
🤖 Written by Claude (an AI agent) on behalf of Niklas

Confidence Score: 5/5

The PR appears safe to merge, with no actionable issues found.

What we checked:

• New enum imports resolve: Each package points to the next package or the defining module, and the class name matches.

Summary

Adds EvaluationRuleStringObjectFilterOperator with is set and is not set, uses it in both string-object filter models, and exports it through the public API packages.

• Updates filter docs for traces, observations v1/v2, and scores.
• No actionable issues were found.
• niklassemmler explicitly acknowledged changes to old-enum type checks and the extra visit handlers. These were not reported because they are known compatibility changes.

_{Reviews (1) · Last reviewed commit: "docs(api): document metadata is set / is..." · Reviewed by Greptile}

[github-actions]

@claude review

[claude]

Claude Code Review

No review was started: this request came from a bot account. Manual reviews can only be requested by someone with write access to this repository. Ask a maintainer to comment @claude review, or have your automation post the comment from a user account with write access.

_{Tip: disable this comment in your organization's Code Review settings.}

[claude]

LGTM — straightforward generated-client update. Checked the new EvaluationRuleStringObjectFilterOperator enum, its wiring into the three dynamic-import tables (consistent TYPE_CHECKING import, _dynamic_imports entry, all entry across langfuse/api/init.py, evaluation_commons/init.py, types/init.py), and the two model fields (EvaluationRuleFilter_StringObject.operator, StringObjectEvaluationRuleFilter.operator) now typed with it, plus matching docstring updates.

Extended reasoning...

Diff is an auto-generated Fern API client update: adds one new StrEnum (evaluation_rule_string_object_filter_operator.py), wires it into three init.py dynamic-import tables, retypes two operator fields from the generic string enum to the new superset enum, and updates docstrings/comments in several other generated clients to mention the new is-set/is-not-set operators. No hand-written logic, no auth/crypto/injection surface, and the wiring follows the existing repeated pattern correctly and consistently; PR author notes no runtime breaking changes since the new enum is a superset. No open third-party objections in the timeline.