Skip to content

πŸͺ’ Open source agent evals & observability: Trace, evaluate, and improve LLM applications with one open platform.

2.5 KB
Raw Blame

Score Interfaces

This directory contains all type definitions, schemas, and validation logic for Langfuse scores.

Structure

interfaces/
β”œβ”€β”€ api/              # API-specific schemas and validations
β”‚   β”œβ”€β”€ v1/           # Legacy API types (trace-focused)
β”‚   β”‚   β”œβ”€β”€ endpoints.ts # Endpoint types and schemas
β”‚   β”‚   β”œβ”€β”€ schemas.ts   # Type definitions
β”‚   β”‚   └── validation.ts  # Validation logic
β”‚   β”œβ”€β”€ v2/           # Current API types (supports traces, sessions)
β”‚   β”‚   β”œβ”€β”€ endpoints.ts # Endpoint types and schemas
β”‚   β”‚   β”œβ”€β”€ schemas.ts   # Type definitions
β”‚   β”‚   └── validation.ts  # Validation logic
β”‚   └── shared.ts     # Common schemas used across API versions
β”œβ”€β”€ application/      # Internal application logic
β”‚   └── validation.ts # Validation functions for application layers
β”œβ”€β”€ ingestion/        # Types for data ingestion
β”‚   └── validation.ts # Validation for ingestion endpoints
β”œβ”€β”€ ui/               # Simplified types for UI components
β”‚   └── types.ts      # UI-specific type definitions
└── index.ts          # Exports all interfaces

API Versioning

We have added a new v2 api and will continue to support the v1 api for the foreseeable future. POST and DELETE APIs will continue to support all score types (trace, session, dataset run) across v1 and v2.

For GET APIs:

  • V1 API: Requires traceId, ONLY supports trace-level scores
  • V2 API: Makes traceId optional, adds sessionId and datasetRunId support, supports all score types (trace, session, run)
  • Both versions maintain compatibility for existing clients

Usage Guide

When building API endpoints:

  • New endpoints: Use types from api/v2/schemas.ts
  • Legacy compatibility: Use types from api/v1/schemas.ts
  • Validation: Use validators from the corresponding validation.ts files

When building UI components:

Use the simplified types from ui/types.ts which are optimized for frontend use:

import { ScoreSimplified, LastUserScore } from "../interfaces/ui/types";

When working with internal application logic:

Use the validation functions from application/validation.ts:

import {
  validateDbScore,
  filterAndValidateDbScoreList,
} from "../interfaces/application/validation";

Type Flow

Client β†’ PostScoresBody β†’ Validation β†’ API response (APIScoreV2) β†’ UI (ScoreSimplified or ScoreDomain)