fix(experiments): await future and custom awaitable results

[Bortlesboat]

What does this PR do?

Experiments now resolve Future, Task and custom awaitable results before recording task output or evaluating scores. Previously, task output could contain the awaitable object itself, and evaluator scores could be dropped, even though the callback protocols allow Awaitable results.

Direct values and coroutines retain their existing behavior. Item evaluators and run evaluators both use the corrected result handling.

Type of change

• Bug fix

Verification

python -m pytest tests/unit/test_experiment.py -q
python -m pytest tests/unit -q
python -m ruff check .
python -m ruff format --check langfuse/experiment.py tests/unit/test_experiment.py
python -m mypy langfuse --no-error-summary

All 30 experiment tests pass on Python 3.13, including ten public run_experiment cases covering values, coroutines, pending Futures, Tasks and custom awaitables. Six cases fail before the fix. Ruff and mypy pass; the changed files pass formatting.

The full unit suite produced 677 passes, 2 skips, 3 failures and 18 fixture errors on native Windows. The untouched base produced 667 passes with the same failures/errors: two prompt atexit subprocess tests, a Windows path assertion, and prompt-client initialization fixtures. Whole-tree format checking also reports an existing discrepancy in test_media.py. Server and live-provider suites were not run; these cases use the existing in-memory fixture.

Checklist

• I self-reviewed the diff using code_review.md.
• I added tests for behavior changes.
• I checked docs, examples and .env.template; callback protocols already document awaitable results.
• I did not hand-edit generated files.
• I did not commit secrets or credentials.

No service deployment or new monitoring is needed for this SDK result-handling fix.

Agent-assisted: Codex prepared the patch and ran the local checks listed above.

---

Greptile Summary

This PR broadens experiment callback result handling from coroutine-only detection to all Python awaitables.

• Resolves Futures, Tasks, and custom awaitables returned by experiment tasks.
• Applies the same handling to item and run evaluators.
• Adds parameterized unit coverage for direct values, coroutines, Futures, Tasks, and custom awaitables.
• Leaves the separate composite-evaluator path using coroutine-only detection.

Confidence Score: 4/5

The PR is not yet safe to merge because composite evaluators can still silently lose valid Future, Task, and custom-awaitable results.

Item and run evaluator results are now resolved correctly, but the third supported experiment evaluation layer bypasses the corrected helper and retains the same coroutine-only behavior this PR is intended to fix.

Files Needing Attention: langfuse/experiment.py and langfuse/_client/client.py

Prompt To Fix All With AI

### Issue 1
langfuse/experiment.py:1010
**Composite awaitables remain unresolved**

The new awaitable handling only covers item and run evaluators. Composite evaluators use a separate coroutine-only check, so a composite evaluator returning a Future, Task, or custom awaitable allowed by its callback protocol passes the unresolved object to normalization. The result is silently discarded, and its composite evaluation and score are missing.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

_{Reviews (1): Last reviewed commit: "fix(experiments): await future and custo..." | Re-trigger Greptile}

Greptile also left 1 inline comment on this PR.

Context used:

• Knowledge Base — Experiments and batch evaluation

[claude]

Claude Code Review

This pull request is from a fork — automated review is disabled. A repository maintainer can comment @claude review to run a one-time review.

[CLAassistant]

All committers have signed the CLA.