openrouter: trace alpha.extractions.create as extraction spans (1.3.106+) #1043

Summary

openrouter (Python SDK) 1.3.106 adds an alpha Extractions endpoint: client.alpha.extractions.create(...) / create_async(...) → POST /api/alpha/extractions. It isn't traced. braintrust-spec recently defined a dedicated extraction span type (spec commit), so this is a well-specified addition.

Found while reviewing the weekly dependency bump in #1037 (openrouter 1.3.79 → 1.3.106).

Upstream API (openrouter 1.3.106)

• Module: openrouter/extractions.py, class Extractions, methods create and create_async. It's reached through openrouter/alpha.py (Alpha.extractions). Upstream marks it "Alpha: the shape is not stable."
• Request:
  • required: fields (map of field name → typed field spec), model, state (text);
  • optional: assets (images), reference_date, provider, session_id, trace, user, plus HTTP/retry options.
• Response: components.ExtractionsResponse with:
  • answers: Dict[str, ExtractionsResponseAnswers], model, usage: ExtractionsUsage;
  • optional id, provider, state_text, truncated.
• Usage: ExtractionsUsage has input_tokens, output_tokens, and optional cost, image_tokens, passes, schema_tokens, state_tokens.

Our code

• Patchers: patchers.py only covers Chat.send[_async], Embeddings.generate[_async], Responses.send[_async] and BetaResponses.send[_async]. They're registered in integration.py.
• Patterns to copy:
  • sync/async wrapper pairs, such as _embeddings_generate_wrapper / _embeddings_generate_async_wrapper (L619);
  • usage parsing in _parse_openrouter_metrics_from_usage.
• Span payload: follow the spec rather than inventing a shape:
  • span_attributes.type: "extraction", one span per call, not per field;
  • input = {state, fields: [...]}, converting the fields map into an array with id = key and preserving order, plus images / reference_date / allowlisted options;
  • output.answers as an array keyed by id;
  • metadata.provider / metadata.model taken from the response model, falling back to the request;
  • canonical token/cost metrics. The spec has notes on input-only usage, and says not to invent metrics for schema_tokens / state_tokens; put those in metadata.
• Precedent: integrations/question.py handles decision spans. Check whether extraction span shaping should live in a similar shared helper so other providers can reuse it.

Testing

1. Add VCR tests to test_openrouter.py for sync and async alpha.extractions.create, recorded with the local OPENROUTER_API_KEY. Pick an extraction-capable model.
2. Gate on openrouter.extractions existing: the 0.6.0 matrix pin doesn't have it.
3. Run cd py && nox -s "test_openrouter(latest)" and "test_openrouter(0.6.0)".
4. The endpoint is alpha, so keep the wrapper defensive about missing or renamed fields.