Let users configure other parameters when creating scores

[codemonium]

TL;DR

This change lets users set an explicit score ID, and configure the session ID and environment when creating scores.

Why

The Langfuse API supports setting a score ID, session ID, and environment when creating a score. These properties help to filter score data in more granular systems.

Checklist

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

[greptile-apps]

Greptile Overview

Greptile Summary

This PR extends the score creation API to support three additional parameters: explicit score ID, session ID, and environment. These additions align with the Langfuse API capabilities and enable more granular filtering of score data.

Key changes:

• Added id parameter to allow explicit score ID instead of auto-generated UUID
• Added session_id parameter as an alternative way to associate scores (besides trace_id)
• Added environment parameter for environment-specific score tracking
• Updated documentation with proper YARD comments across all three method layers (Langfuse.create_score, Client#create_score, ScoreClient#create)
• Comprehensive test coverage for all new parameters with proper API field name mapping

Issue found:

• Documentation states that trace_id, session_id, and dataset_run_id are mutually exclusive, but no validation enforces this constraint

Confidence Score: 4/5

• This PR is safe to merge with one logical issue that should be addressed
• The implementation is clean with proper documentation, parameter threading, and comprehensive tests. The score is 4 instead of 5 due to missing validation for mutually exclusive parameters (trace_id, session_id, dataset_run_id) which could cause API errors
• Pay attention to lib/langfuse/score_client.rb which needs validation logic for mutually exclusive parameters

Important Files Changed

Filename	Overview
lib/langfuse/client.rb	Added id, session_id, and environment parameters with documentation, but lacks validation for mutually exclusive parameters
lib/langfuse/score_client.rb	Implemented core logic for new parameters including id, session_id, and environment in event building, but missing validation for parameter constraints

Sequence Diagram

sequenceDiagram
    participant User
    participant Langfuse Module
    participant Client
    participant ScoreClient
    participant Queue
    participant API

    User->>Langfuse Module: create_score(name, value, id, session_id, environment, ...)
    Langfuse Module->>Client: create_score(name, value, id, session_id, environment, ...)
    Client->>ScoreClient: create(name, value, id, session_id, environment, ...)
    ScoreClient->>ScoreClient: validate_name(name)
    ScoreClient->>ScoreClient: normalize_value(value, data_type)
    ScoreClient->>ScoreClient: build_score_event(...)
    Note over ScoreClient: Generates UUID if id not provided
    Note over ScoreClient: Conditionally includes sessionId, environment
    ScoreClient->>Queue: << event
    alt Batch size reached
        ScoreClient->>API: send_batch(events)
    end

Loading

[greptile-apps]

_{5 files reviewed, 1 comment}

_{Edit Code Review Agent Settings | Greptile}

[greptile-apps]

Missing validation for mutually exclusive parameters. The documentation in lib/langfuse/client.rb:286 states that only one of trace_id, session_id, or dataset_run_id should be provided, but there's no code enforcing this constraint.

Suggested change

	def create(name:, value:, id: nil, trace_id: nil, session_id: nil, observation_id: nil, comment: nil,
	metadata: nil, environment: nil, data_type: :numeric, dataset_run_id: nil, config_id: nil)
	def create(name:, value:, id: nil, trace_id: nil, session_id: nil, observation_id: nil, comment: nil,
	metadata: nil, environment: nil, data_type: :numeric, dataset_run_id: nil, config_id: nil)
	validate_name(name)
	validate_score_identifiers(trace_id: trace_id, session_id: session_id, observation_id: observation_id, dataset_run_id: dataset_run_id)

_{Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!}