feat(parity): close high-value SDK parity gaps

[kxzk]

TL;DR

Close the high-value Ruby SDK parity gaps against the local JS/Python SDKs while keeping the public API flat and dependency-light.

Why

langfuse-rb already had prompts, traces, scores, datasets, experiments, and Rails-friendly config, but it was missing several high-value surfaces that JS/Python expose: SDK identity headers, prompt deletion, media references, and thin read/admin APIs Rails apps need for operational workflows.

This PR follows the local sibling SDKs as evidence for behavior, not as a mandate to copy their generated manager shape. The committed matrix in docs/PARITY.md calls out what shipped, what belongs in separate issues, what is deferred, and what is not applicable to Ruby.

Checklist

• Has label
• Has linked issue: AAI-129
• Tests added for new behavior
• Docs updated (if user-facing)

What changed

• Added shared REST + OTLP SDK identity headers:
  • REST: X-Langfuse-Sdk-Name, X-Langfuse-Sdk-Version, X-Langfuse-Public-Key
  • OTLP: x-langfuse-sdk-name, x-langfuse-sdk-version, x-langfuse-public-key
• Added client.delete_prompt(name, version: nil, label: nil) with prompt-name-wide cache invalidation and nil return semantics for successful deletes.
• Added dependency-light Langfuse::Media / Langfuse::LangfuseMedia support:
  • bytes, file, and base64 data URI input
  • deterministic media IDs and reference strings
  • reference parsing and nested reference resolution
  • media get/upload-url/patch/upload helpers
  • provider-specific upload headers aligned with JS/Python for non-GCS vs GCS presigned URLs
• Added flat read/admin APIs for:
  • sessions
  • observations v2
  • scores v2
  • score configs
  • models
  • metrics v2
  • health
• Added docs for prompt deletion, media, read/admin APIs, cache invalidation behavior, changelog, and the committed JS/Python parity matrix.

Validation

Local focused behavior:

RBENV_VERSION=3.2.0 rbenv exec bundle _2.4.7_ exec rspec spec/langfuse/api_client_spec.rb spec/langfuse/media_spec.rb spec/langfuse/client_spec.rb spec/langfuse/otel_setup_spec.rb
# 377 examples, 0 failures
# Partial SimpleCov exits 2 because isolated coverage is 74.50%; expected for focused slices in this repo.

Full gates:

RBENV_VERSION=3.2.0 rbenv exec bundle _2.4.7_ exec rspec
# 1365 examples, 0 failures
# Line Coverage: 96.5% (2566 / 2659)

RBENV_VERSION=3.2.0 rbenv exec bundle _2.4.7_ exec rubocop --cache false
# 82 files inspected, no offenses detected

Langfuse CLI/API discovery:

npx --yes langfuse-cli api __schema --commands
# Resources include prompts, medias, sessions, observations, scores, score-configs, models, metrics, healths.

npx --yes langfuse-cli api prompts --help
npx --yes langfuse-cli api medias --help
npx --yes langfuse-cli api sessions --help
npx --yes langfuse-cli api observations --help
npx --yes langfuse-cli api scores --help
npx --yes langfuse-cli api score-configs --help
npx --yes langfuse-cli api models --help
npx --yes langfuse-cli api metrics list --help
npx --yes langfuse-cli api healths --help

Live platform verifier:

RBENV_VERSION=3.2.0 rbenv exec bundle _2.4.7_ exec ruby scratchpad/aai_129_parity_validate.rb

Result:

{
  "status": "passed",
  "prompt_deleted": "aai-129-parity-20260508095438-bdb115e6",
  "trace_id": "6ae2a195203043936a1466d990c54d2f",
  "session_id": "aai-129-session-bdb115e6",
  "media_id": "aoIqTxOv6aPUnUDNJmgxXC",
  "score_id": "6d03b0cd-a97c-48ca-a625-ab7472f376f2",
  "score_config_retained": "ed02f84b-f7f4-4d38-8579-fee57c76a357",
  "model_deleted": "cmowqo53q000ec807z7ut2new",
  "metrics_keys": ["unavailable"],
  "platform_caveats": [
    "observations-v2 unavailable on this Langfuse host: API request failed (501): v2 APIs are currently in beta and only available on Langfuse Cloud",
    "metrics-v2 unavailable on this Langfuse host: API request failed (501): v2 APIs are currently in beta and only available on Langfuse Cloud"
  ]
}

Cleanup notes:

• Prompt was deleted.
• Trace was deleted through CLI cleanup.
• Model was deleted.
• Score config is retained because this API surface exposes create/list/get/update but no delete endpoint in the current CLI/API surface.

Caveats

The current live Langfuse host is not Cloud for beta v2 observations/metrics. It returns 501 for those endpoints. This PR still ships the Ruby flat methods because JS/Python expose those endpoints and the CLI schema advertises them; request paths and query encoding are covered by WebMock specs. Scores-v2 readback did validate live on this host.