chore: ensure backwards compatibility for old server versions

[marliessophie]

Important

Adds backward compatibility for older server versions by retrying dataset run item creation without datasetVersion if unrecognized, with logging enhancements.

• Backward Compatibility:
  • Adds _is_unrecognized_field_error() in client.py to check for unrecognized fields in API errors.
  • In _process_experiment_item(), retries dataset run item creation without datasetVersion if unrecognized by server.
• Logging:
  • Logs a warning if datasetVersion is unrecognized and retries without it.
  • Logs errors for failed dataset run item creation attempts.

^{This description was created by for f7eb55c. You can customize this summary. It will automatically update as commits are pushed.}

Disclaimer: Experimental PR review

Greptile Summary

This PR adds backward compatibility for the datasetVersion field in the experiment runner. When the SDK sends a CreateDatasetRunItemRequest with datasetVersion to an older Langfuse server that doesn't recognize the field, the client now catches the "unrecognized field" error and retries the request without datasetVersion.

• Adds a new module-level helper _is_unrecognized_field_error() that inspects the API error body to detect unrecognized field errors
• Wraps the existing dataset run item creation call with a retry mechanism that omits datasetVersion if the server doesn't support it
• Error handling for non-datasetVersion errors remains unchanged (logged and execution continues)
• No tests were added for the new retry logic

Confidence Score: 4/5

• This PR is safe to merge — it adds a defensive retry mechanism with no changes to the happy path.
• The changes are well-scoped: a single helper function and a retry block in one location. The retry only triggers for a specific error condition and falls through to the original behavior otherwise. The error handling is defensive with broad except clauses. No breaking changes to existing behavior.
• No files require special attention beyond langfuse/_client/client.py.

Important Files Changed

Filename	Overview
langfuse/_client/client.py	Adds backward-compatible retry logic for datasetVersion field in dataset run item creation; new helper _is_unrecognized_field_error defensively parses API error bodies. No bugs found, one optimization opportunity.

Sequence Diagram

sequenceDiagram
    participant ER as Experiment Runner
    participant API as Langfuse API (old server)

    ER->>API: Create dataset run item (with datasetVersion)
    API-->>ER: 400 Error: unrecognized field "datasetVersion"
    Note over ER: _is_unrecognized_field_error() returns True
    ER->>API: Retry: Create dataset run item (without datasetVersion)
    API-->>ER: 200 OK (DatasetRunItem)

Loading

_{Last reviewed commit: f7eb55c}

[greptile-apps]

_{1 file reviewed, no comments}

_{Edit Code Review Agent Settings | Greptile}

[hassiebp]

@marliessophie Adding a field such as datasetVersion should've been backward compatible, why are old server versions complaining?

[marliessophie]

@marliessophie Adding a field such as datasetVersion should've been backward compatible, why are old server versions complaining?

I don't believe so, no. We enforce the zod validation for POST /dataset-run-items as strict. We apply the same logic to most API routes. Therefore, if the datasetVersion param is passed to an outdated server version it will throw a 400. In this error case and this error case only, the SDK retries the request, omitting the datasetVersion param. Do you have any concerns with this approach?