tessl/maven-com-langfuse--langfuse-java

Java client for the Langfuse API providing access to observability and analytics features for LLM applications

Overview

Eval results

Files

Common Types

Name: tessl/maven-com-langfuse--langfuse-java
Author: tessl

The Langfuse Java client provides a rich set of common types shared across multiple API areas. These types are located in the com.langfuse.client.resources.commons.types package.

import java.time.OffsetDateTime;

Core Domain Objects

Trace Types

Trace

Basic trace object representing a complete workflow or request.

/**
 * Basic trace object
 */
public final class Trace {
    String getId();
    OffsetDateTime getTimestamp();
    Optional<String> getName();
    Optional<String> getUserId();
    Optional<Object> getMetadata();
    Optional<String> getRelease();
    Optional<String> getVersion();
    Optional<String> getProjectId();
    Optional<Boolean> getPublic();
    Optional<Boolean> getBookmarked();
    Optional<List<String>> getTags();
    Optional<Object> getInput();
    Optional<Object> getOutput();
    Optional<String> getSessionId();

    static Builder builder();
}

TraceWithDetails

Trace with its observations.

/**
 * Trace with observations
 */
public final class TraceWithDetails extends Trace {
    List<Observation> getObservations();

    static Builder builder();
}

TraceWithFullDetails

Trace with observations and scores (full detail).

/**
 * Trace with observations and scores
 */
public final class TraceWithFullDetails extends Trace {
    List<Observation> getObservations();
    List<ScoreV1> getScores();

    static Builder builder();
}

Observation Types

Observation

Core observation object (span, event, or generation).

/**
 * Observation within a trace
 * Can be a span, event, or generation
 */
public final class Observation {
    String getId();
    String getTraceId();
    Optional<ObservationType> getType();        // SPAN, EVENT, GENERATION
    Optional<String> getParentObservationId();
    Optional<String> getName();
    Optional<Object> getMetadata();
    Optional<String> getModel();
    Optional<Object> getModelParameters();
    OffsetDateTime getStartTime();
    Optional<OffsetDateTime> getEndTime();
    Optional<OffsetDateTime> getCompletionStartTime();
    Optional<Object> getInput();
    Optional<Object> getOutput();
    Optional<Usage> getUsage();
    Optional<ObservationLevel> getLevel();      // DEBUG, DEFAULT, WARNING, ERROR
    Optional<String> getStatusMessage();
    Optional<String> getVersion();

    static Builder builder();
}

ObservationsView

Observation with additional computed fields (costs, latency).

/**
 * Observation view with computed fields
 */
public final class ObservationsView extends Observation {
    Optional<String> getPromptId();
    Optional<String> getPromptName();
    Optional<Integer> getPromptVersion();
    Optional<String> getEnvironment();
    Optional<ModelPrice> getModelPrice();
    Optional<Double> getTotalCost();      // Computed cost
    Optional<Double> getLatency();        // Computed latency in seconds

    static Builder builder();
}

Session Types

Session

Session object grouping related traces.

/**
 * Session grouping related traces
 */
public final class Session {
    String getId();
    OffsetDateTime getCreatedAt();
    Optional<String> getBookmarked();
    Optional<Boolean> getPublic();
    List<String> getUserIds();
    int getTraceCount();
    Optional<Double> getTotalCost();
    Optional<String> getEnvironment();

    static Builder builder();
}

SessionWithTraces

Session with all its traces.

/**
 * Session with all traces (not paginated)
 */
public final class SessionWithTraces extends Session {
    List<Trace> getTraces();

    static Builder builder();
}

Score Types

Score Variants

Score

Union type for different score variants.

/**
 * Union type for scores
 * Discriminated by value type
 */
public final class Score {
    static Score base(BaseScore value);
    static Score boolean_(BooleanScore value);
    static Score categorical(CategoricalScore value);
    static Score numeric(NumericScore value);

    <T> T visit(Visitor<T> visitor);
}

BaseScore

Base score with generic value.

/**
 * Base score type
 */
public final class BaseScore {
    String getId();
    OffsetDateTime getTimestamp();
    OffsetDateTime getCreatedAt();
    OffsetDateTime getUpdatedAt();
    String getProjectId();
    String getName();
    Object getValue();                  // Generic value
    ScoreSource getSource();            // API, EVAL, ANNOTATION
    Optional<String> getComment();
    Optional<String> getTraceId();
    Optional<String> getObservationId();
    Optional<ScoreDataType> getDataType(); // NUMERIC, CATEGORICAL, BOOLEAN
    Optional<String> getConfigId();
    Optional<String> getQueueId();

    static Builder builder();
}

BooleanScore

Boolean-valued score.

/**
 * Boolean score
 */
public final class BooleanScore extends BaseScore {
    boolean getValue();

    static Builder builder();
}

CategoricalScore

Categorical score with string value.

/**
 * Categorical score
 */
public final class CategoricalScore extends BaseScore {
    String getValue();

    static Builder builder();
}

NumericScore

Numeric score with double value.

/**
 * Numeric score
 */
public final class NumericScore extends BaseScore {
    double getValue();

    static Builder builder();
}

Score Configuration

ScoreConfig

Score configuration/template.

/**
 * Score configuration template
 */
public final class ScoreConfig {
    String getId();
    String getName();
    ScoreDataType getDataType();
    Optional<Boolean> getIsArchived();
    Optional<List<ConfigCategory>> getCategories();
    Optional<Double> getMinValue();
    Optional<Double> getMaxValue();
    Optional<String> getDescription();
    OffsetDateTime getCreatedAt();
    OffsetDateTime getUpdatedAt();

    static Builder builder();
}

ConfigCategory

Category definition for categorical scores.

/**
 * Category for categorical scores
 */
public final class ConfigCategory {
    String getValue();
    Optional<String> getLabel();

    static Builder builder();
}

Dataset Types

Dataset

Dataset definition for evaluation.

/**
 * Dataset for evaluation
 */
public final class Dataset {
    String getId();
    String getName();
    Optional<String> getDescription();
    Optional<Object> getMetadata();
    String getProjectId();
    OffsetDateTime getCreatedAt();
    OffsetDateTime getUpdatedAt();
    int getItems();                     // Number of items

    static Builder builder();
}

DatasetItem

Single item in a dataset (test case).

/**
 * Dataset item (test case)
 */
public final class DatasetItem {
    String getId();
    DatasetStatus getStatus();          // ACTIVE, ARCHIVED
    Object getInput();
    Optional<Object> getExpectedOutput();
    Optional<Object> getMetadata();
    Optional<String> getSourceTraceId();
    Optional<String> getSourceObservationId();
    String getDatasetId();
    String getDatasetName();
    OffsetDateTime getCreatedAt();
    OffsetDateTime getUpdatedAt();

    static Builder builder();
}

DatasetRun

Dataset run (evaluation run).

/**
 * Dataset run
 */
public final class DatasetRun {
    String getId();
    String getName();
    Optional<String> getDescription();
    Optional<Object> getMetadata();
    String getDatasetId();
    String getDatasetName();
    OffsetDateTime getCreatedAt();
    OffsetDateTime getUpdatedAt();

    static Builder builder();
}

DatasetRunItem

Dataset run item (links test case to result).

/**
 * Dataset run item
 */
public final class DatasetRunItem {
    String getId();
    String getDatasetRunId();
    String getDatasetRunName();
    String getDatasetItemId();
    Optional<String> getTraceId();
    Optional<String> getObservationId();
    OffsetDateTime getCreatedAt();
    OffsetDateTime getUpdatedAt();

    static Builder builder();
}

DatasetRunWithItems

Dataset run with all its items.

/**
 * Dataset run with items
 */
public final class DatasetRunWithItems extends DatasetRun {
    List<DatasetRunItem> getDatasetRunItems();

    static Builder builder();
}

Model Types

Model

LLM model definition with pricing.

/**
 * LLM model with pricing
 */
public final class Model {
    String getId();
    String getModelName();
    String getMatchPattern();           // Regex for matching
    Optional<OffsetDateTime> getStartDate();
    Optional<ModelPrice> getInputPrice();
    Optional<ModelPrice> getOutputPrice();
    Optional<ModelPrice> getTotalPrice();
    ModelUsageUnit getUnit();           // TOKENS, CHARACTERS, etc.
    Optional<String> getTokenizerId();
    Optional<Object> getTokenizerConfig();

    static Builder builder();
}

ModelPrice

Pricing information for a model.

/**
 * Model pricing
 */
public final class ModelPrice {
    double getPrice();
    String getCurrency();               // e.g., "USD"

    static Builder builder();
}

Usage

Token usage information.

/**
 * Token usage
 */
public final class Usage {
    Optional<Integer> getInput();
    Optional<Integer> getOutput();
    Optional<Integer> getTotal();
    Optional<ModelUsageUnit> getUnit();
    Optional<Double> getInputCost();
    Optional<Double> getOutputCost();
    Optional<Double> getTotalCost();

    static Builder builder();
}

Comment Types

Comment

Comment on an object.

/**
 * Comment on a trace, observation, session, or prompt
 */
public final class Comment {
    String getId();
    String getContent();
    CommentObjectType getObjectType();  // TRACE, OBSERVATION, SESSION, PROMPT
    String getObjectId();
    String getAuthorUserId();
    OffsetDateTime getCreatedAt();
    OffsetDateTime getUpdatedAt();

    static Builder builder();
}

Utility Types

MapValue

Union type for map values.

/**
 * Union type for map values
 * Supports various primitive and complex types
 */
public final class MapValue {
    static MapValue string(String value);
    static MapValue integer(int value);
    static MapValue _double(double value);
    static MapValue boolean_(boolean value);
    static MapValue list(List<MapValue> value);
    static MapValue map(Map<String, MapValue> value);

    <T> T visit(Visitor<T> visitor);
}

Enums

ObservationType

/**
 * Type of observation
 */
public enum ObservationType {
    SPAN,       // Operation or sub-process
    EVENT,      // Point-in-time occurrence
    GENERATION  // LLM generation call
}

ObservationLevel

/**
 * Log level for observations
 */
public enum ObservationLevel {
    DEBUG,
    DEFAULT,
    WARNING,
    ERROR
}

ScoreDataType

/**
 * Data type for scores
 */
public enum ScoreDataType {
    NUMERIC,      // Double value
    CATEGORICAL,  // String value
    BOOLEAN       // Boolean value
}

ScoreSource

/**
 * Source of the score
 */
public enum ScoreSource {
    ANNOTATION,  // Created by annotation
    API,         // Created via API
    EVAL         // Created by evaluation
}

DatasetStatus

/**
 * Status of dataset item
 */
public enum DatasetStatus {
    ACTIVE,     // Active, included in evaluations
    ARCHIVED    // Archived, excluded
}

ModelUsageUnit

/**
 * Unit for usage measurement
 */
public enum ModelUsageUnit {
    CHARACTERS,
    TOKENS,
    REQUESTS,
    IMAGES,
    SECONDS
}

CommentObjectType

/**
 * Object types that can have comments
 */
public enum CommentObjectType {
    TRACE,
    OBSERVATION,
    SESSION,
    PROMPT
}

Interfaces

ITrace

Interface for trace properties.

/**
 * Interface for trace properties
 */
public interface ITrace {
    String getId();
    OffsetDateTime getTimestamp();
    Optional<String> getName();
    Optional<String> getUserId();
    Optional<Object> getMetadata();
    // ... other trace properties
}

IObservation

Interface for observation properties.

/**
 * Interface for observation properties
 */
public interface IObservation {
    String getId();
    String getTraceId();
    Optional<ObservationType> getType();
    Optional<String> getName();
    OffsetDateTime getStartTime();
    Optional<OffsetDateTime> getEndTime();
    // ... other observation properties
}

ISession

Interface for session properties.

/**
 * Interface for session properties
 */
public interface ISession {
    String getId();
    OffsetDateTime getCreatedAt();
    List<String> getUserIds();
    // ... other session properties
}

IBaseScore

Interface for base score properties.

/**
 * Interface for score properties
 */
public interface IBaseScore {
    String getId();
    OffsetDateTime getTimestamp();
    OffsetDateTime getCreatedAt();
    OffsetDateTime getUpdatedAt();
    String getName();
    Object getValue();
    ScoreSource getSource();
    // ... other score properties
}

IDatasetRun

Interface for dataset run properties.

/**
 * Interface for dataset run properties
 */
public interface IDatasetRun {
    String getId();
    String getName();
    Optional<String> getDescription();
    Optional<Object> getMetadata();
    String getDatasetId();
    String getDatasetName();
    // ... other dataset run properties
}

Type Usage Examples

Working with Scores

// Score is a union type - use visitor pattern
Score score = client.scoreV2().getById("score-123");

score.visit(new Score.Visitor<Void>() {
    @Override
    public Void visitNumeric(NumericScore numeric) {
        System.out.println("Numeric: " + numeric.getValue());
        return null;
    }

    @Override
    public Void visitCategorical(CategoricalScore categorical) {
        System.out.println("Categorical: " + categorical.getValue());
        return null;
    }

    @Override
    public Void visitBoolean(BooleanScore bool) {
        System.out.println("Boolean: " + bool.getValue());
        return null;
    }

    @Override
    public Void visitBase(BaseScore base) {
        System.out.println("Base: " + base.getValue());
        return null;
    }

    @Override
    public Void visitUnknown(String unknownType) {
        return null;
    }
});

Working with Observations

Observation observation = ...;

// Check observation type
if (observation.getType().isPresent()) {
    switch (observation.getType().get()) {
        case SPAN:
            System.out.println("This is a span");
            break;
        case EVENT:
            System.out.println("This is an event");
            break;
        case GENERATION:
            System.out.println("This is a generation");
            if (observation.getModel().isPresent()) {
                System.out.println("Model: " + observation.getModel().get());
            }
            break;
    }
}

// Check observation level
if (observation.getLevel().isPresent() &&
    observation.getLevel().get() == ObservationLevel.ERROR) {
    System.err.println("Error in observation: " +
        observation.getStatusMessage().orElse("no message"));
}

Working with Usage Information

ObservationsView view = client.observations().get("obs-123");

if (view.getUsage().isPresent()) {
    Usage usage = view.getUsage().get();

    System.out.println("Input tokens: " + usage.getInput().orElse(0));
    System.out.println("Output tokens: " + usage.getOutput().orElse(0));
    System.out.println("Total tokens: " + usage.getTotal().orElse(0));

    if (usage.getTotalCost().isPresent()) {
        System.out.println("Cost: $" + usage.getTotalCost().get());
    }
}

Type Relationships

Trace
├── TraceWithDetails (adds observations)
└── TraceWithFullDetails (adds observations + scores)

Observation
└── ObservationsView (adds computed fields)

Session
└── SessionWithTraces (adds traces)

DatasetRun
└── DatasetRunWithItems (adds items)

Score (union)
├── BaseScore
├── BooleanScore
├── CategoricalScore
└── NumericScore