@agentmark-ai/api-types 0.3.0 → 0.5.0

package/dist/types.d.ts

@@ -99,6 +99,42 @@ export interface ModelStats {
 export interface ModelStatsResponse {
     models: ModelStats[];
 }
+/**
+ * Aggregates for one (promptName, commitSha) pair — the per-version metrics
+ * behind prompt-version trace linking. `commitSha` is `''` for spans ingested
+ * before version stamping (or from paths with no commit to stamp).
+ */
+export interface PromptVersionStats {
+    promptName: string;
+    commitSha: string;
+    requests: number;
+    errorCount: number;
+    errorRate: number;
+    cost: number;
+    tokens: number;
+    avgLatencyMs: number;
+    /** Average score across all scores attached to this version's traces; null when unscored. */
+    avgScore: number | null;
+    /** Number of score rows behind `avgScore`. */
+    scoreCount: number;
+}
+/**
+ * Parameters for the per-prompt-version stats query.
+ */
+export interface PromptVersionStatsParams {
+    /** Restrict to a single prompt name. Omit for all prompts. */
+    promptName?: string;
+    /** Max number of (prompt, version) rows returned. */
+    limit?: number;
+    /** Single-env scoping. Mirrors ScoresParams. Undefined = no env filter. */
+    env?: EnvironmentQueryScope;
+}
+/**
+ * Response for the per-prompt-version stats query.
+ */
+export interface PromptVersionStatsResponse {
+    versions: PromptVersionStats[];
+}
 /**
  * A single ranking item for dimension-grouped queries.
  * Used by getRankingData to return data grouped by any dimension
@@ -174,6 +210,16 @@ export interface SavedViewConfig {
         field: string;
         visible: boolean;
     }>;
+    /**
+     * Env-scoped saved filter (feature 054, FR-122..FR-125). An array of env
+     * *name* strings (NOT ids — FR-124: names are immutable and match the
+     * trace-tag mechanism). Multi-select so "prod OR staging" round-trips.
+     * The evaluator translates this to `Environment IN (...)`. A saved view
+     * naming a deleted/renamed env keeps working — it matches historical
+     * traces tagged with that name; the editor surfaces a non-blocking note
+     * (FR-125) but never invalidates or auto-edits the field.
+     */
+    environments?: string[];
 }
 /**
  * Type guard for v3 saved view configs.
@@ -213,6 +259,34 @@ export interface AggregateRequestsParams extends PaginationParams {
     startDate?: string;
     endDate?: string;
 }
+/**
+ * Environment scoping for analytics list queries (feature 054 — Environments
+ * & Promotion). `name` is the env tag stamped on `otel_traces.Environment` /
+ * `scores.Environment` by the gateway. `isDefault` drives the FR-051 legacy
+ * rule: rows with `Environment = ''` (pre-feature ingest) are included ONLY
+ * when scoping to the app's default env — for any non-default env those
+ * legacy rows are excluded.
+ */
+export interface EnvironmentScope {
+    name: string;
+    isDefault: boolean;
+}
+/**
+ * Combined env scope for analytics metric queries (feature 054, FR-126).
+ * Composes the single-env {@link EnvironmentScope} with the multi-env
+ * allow-list, mirroring the `environment` + `environments` field pair on
+ * {@link TracesParams} / {@link ScoresParams}. Used by the dashboard widget
+ * metric methods (`getMetrics`, `getModelStats`, `getRankingData`,
+ * `getPercentiles`) so a built-in or custom widget can be scoped to one env
+ * or — for cross-env comparison widgets — an env allow-list. Undefined on a
+ * call means "no env filter".
+ */
+export interface EnvironmentQueryScope {
+    /** Single-env scope (env-selector default / dashboard-view env). */
+    environment?: EnvironmentScope;
+    /** Multi-env allow-list — translates to `Environment IN (...)`. */
+    environments?: string[];
+}
 /**
  * Parameters for listing traces.
  */
@@ -230,6 +304,14 @@ export interface TracesParams extends PaginationParams {
     filters?: AnalyticsFilter[];
     sortBy?: string;
     sortOrder?: 'asc' | 'desc';
+    /** Single-env scoping per FR-031/FR-051. Undefined = no env filter. */
+    environment?: EnvironmentScope;
+    /**
+     * Env-name allow-list from a saved filter's `environments` JSONB field
+     * (FR-122..FR-124). When set, translates to `Environment IN (...)`. Takes
+     * precedence over the single-env `environment` scope when both are present.
+     */
+    environments?: string[];
 }
 /**
  * Summary of a trace for list views.
@@ -245,6 +327,10 @@ export interface TraceSummary {
     tokens: number;
     spanCount: number;
     tags?: string[];
+    /** Env tag (feature 054). `''` marks legacy/no-pin rows per FR-051. */
+    environment?: string;
+    /** Env version at ingest (feature 054). `0` marks legacy/no-pin rows. */
+    environmentVersion?: number;
 }
 /**
  * Paginated response for trace listing.
@@ -295,6 +381,13 @@ export interface SpanIO {
     output: string;
     outputObject: string | null;
     toolCalls: string | null;
+    /**
+     * Custom per-span metadata (raw map; reserved namespaces stripped at the API
+     * boundary). Optional on the internal type so existing producers/mocks need
+     * not be updated wholesale; the wire shapes (SpanIOSchema / SpanIOWire) keep
+     * it required and the gateway + CLI always populate it.
+     */
+    metadata?: Record<string, string>;
 }
 /**
  * Complete trace detail with all spans.
@@ -328,9 +421,18 @@ export interface SessionsParams extends PaginationParams {
     search?: string;
     sortBy?: string;
     sortOrder?: 'asc' | 'desc';
+    /** Single-env scoping per FR-031/FR-051. Undefined = no env filter. */
+    environment?: EnvironmentScope;
+    /** Env-name allow-list from a saved filter (FR-122..FR-124). */
+    environments?: string[];
 }
 /**
  * Summary of a session for list views.
+ *
+ * Feature 054 (FR-118..FR-120): a session is identified by the tuple
+ * `(SessionId, Environment)`, not `SessionId` alone. `id` is the SessionId;
+ * `environment` is the second half of the identity. The same SessionId
+ * appearing under two envs yields two distinct `SessionSummary` rows.
  */
 export interface SessionSummary {
     id: string;
@@ -342,6 +444,10 @@ export interface SessionSummary {
     totalTokens: number;
     latencyMs: number;
     tags?: string[];
+    /** Env half of the `(SessionId, Environment)` identity (FR-118). */
+    environment?: string;
+    /** Env version at ingest (feature 054). `0` marks legacy/no-pin rows. */
+    environmentVersion?: number;
 }
 /**
  * Paginated response for session listing.
@@ -476,6 +582,10 @@ export interface ExperimentParams extends Partial<PaginationParams> {
     endDate?: string;
     promptName?: string;
     datasetPath?: string;
+    /** Single-env scope — mirrors {@link TracesParams.environment} / {@link ScoresParams.environment}. */
+    environment?: EnvironmentScope;
+    /** Multi-env allow-list — mirrors {@link TracesParams.environments} / {@link ScoresParams.environments}. */
+    environments?: string[];
 }
 /**
  * Paginated response for experiments listing.
@@ -516,6 +626,10 @@ export interface ScoresParams extends Partial<PaginationParams> {
     sessionId?: string;
     startDate?: string;
     endDate?: string;
+    /** Single-env scoping per FR-031/FR-051/FR-109. Undefined = no env filter. */
+    environment?: EnvironmentScope;
+    /** Env-name allow-list from a saved filter (FR-122..FR-124). */
+    environments?: string[];
 }
 /**
  * Paginated response for scores listing.
@@ -761,24 +875,30 @@ export interface TraceFilterConfig {
  */
 export interface IAnalyticsService {
     checkConnectivity(): Promise<boolean>;
-    getMetrics(ctx: TenantContext, dateRange: DateRange, filters?: AnalyticsFilter[]): Promise<MetricsResponse>;
-    getExtendedMetrics(ctx: TenantContext, dateRange: DateRange): Promise<ExtendedMetricsResponse>;
-    getModelStats(ctx: TenantContext, dateRange: DateRange, limit?: number, filters?: AnalyticsFilter[]): Promise<ModelStatsResponse>;
+    getMetrics(ctx: TenantContext, dateRange: DateRange, filters?: AnalyticsFilter[], env?: EnvironmentQueryScope): Promise<MetricsResponse>;
+    getExtendedMetrics(ctx: TenantContext, dateRange: DateRange, env?: EnvironmentQueryScope): Promise<ExtendedMetricsResponse>;
+    getModelStats(ctx: TenantContext, dateRange: DateRange, limit?: number, filters?: AnalyticsFilter[], env?: EnvironmentQueryScope): Promise<ModelStatsResponse>;
+    /**
+     * Per (promptName, commitSha) aggregates — prompt-version trace linking.
+     * Optional so existing implementers (e.g. the CLI's local service) remain
+     * source-compatible; the cloud AnalyticsService implements it.
+     */
+    getPromptVersionStats?(ctx: TenantContext, dateRange: DateRange, params?: PromptVersionStatsParams): Promise<PromptVersionStatsResponse>;
     getTraces(ctx: TenantContext, params: TracesParams): Promise<TracesResponse>;
-    getTraceDetail(ctx: TenantContext, traceId: string): Promise<TraceDetail | null>;
-    getTraceDetailLightweight(ctx: TenantContext, traceId: string): Promise<TraceDetail | null>;
-    getSpanIO(ctx: TenantContext, traceId: string, spanId: string): Promise<SpanIO | null>;
+    getTraceDetail(ctx: TenantContext, traceId: string, env?: EnvironmentQueryScope): Promise<TraceDetail | null>;
+    getTraceDetailLightweight(ctx: TenantContext, traceId: string, env?: EnvironmentQueryScope): Promise<TraceDetail | null>;
+    getSpanIO(ctx: TenantContext, traceId: string, spanId: string, env?: EnvironmentQueryScope): Promise<SpanIO | null>;
     getSessions(ctx: TenantContext, params: SessionsParams): Promise<SessionsResponse>;
-    getSessionTraces(ctx: TenantContext, sessionId: string): Promise<TraceDetail[]>;
-    getPercentiles(ctx: TenantContext, params: PercentilesParams, filters?: AnalyticsFilter[]): Promise<PercentilesResponse>;
+    getSessionTraces(ctx: TenantContext, sessionId: string, env?: EnvironmentQueryScope): Promise<TraceDetail[]>;
+    getPercentiles(ctx: TenantContext, params: PercentilesParams, filters?: AnalyticsFilter[], env?: EnvironmentQueryScope): Promise<PercentilesResponse>;
     getDatasetRuns(ctx: TenantContext, params: DatasetRunParams): Promise<DatasetRunsResponse>;
     getDatasetRunDetail(ctx: TenantContext, runId: string): Promise<DatasetRunDetail | null>;
     getExperiments(ctx: TenantContext, params: ExperimentParams): Promise<ExperimentsResponse>;
-    getExperimentDetail(ctx: TenantContext, experimentId: string): Promise<ExperimentDetail | null>;
+    getExperimentDetail(ctx: TenantContext, experimentId: string, env?: EnvironmentQueryScope): Promise<ExperimentDetail | null>;
     getScores(ctx: TenantContext, params: ScoresParams): Promise<ScoresResponse>;
     getScoresBySpanIds(ctx: TenantContext, spanIds: string[]): Promise<Record<string, Score[]>>;
-    getScoreAggregations(ctx: TenantContext, dateRange: DateRange): Promise<ScoreAggregationsResponse>;
-    getDistinctScoreNames(ctx: TenantContext): Promise<ScoreNamesResponse>;
+    getScoreAggregations(ctx: TenantContext, dateRange: DateRange, env?: EnvironmentQueryScope): Promise<ScoreAggregationsResponse>;
+    getDistinctScoreNames(ctx: TenantContext, env?: EnvironmentQueryScope): Promise<ScoreNamesResponse>;
     detectScoreType(ctx: TenantContext, name: string): Promise<ScoreType>;
     getScoreHistogram(ctx: TenantContext, name: string, dateRange: DateRange, source?: string): Promise<ScoreHistogramResponse>;
     getScoreTrend(ctx: TenantContext, name: string, interval: ScoreTrendInterval, dateRange: DateRange, source?: string): Promise<ScoreTrendResponse>;
@@ -786,7 +906,7 @@ export interface IAnalyticsService {
     getScoreScatter(ctx: TenantContext, nameA: string, nameB: string, dateRange: DateRange, source?: string): Promise<ScoreScatterResponse>;
     getDistinctMetadataKeys(ctx: TenantContext): Promise<string[]>;
     getRequests(ctx: TenantContext, params: RequestsParams): Promise<RequestsResponse>;
-    getRankingData(ctx: TenantContext, dateRange: DateRange, dimension: string, limit?: number, filters?: AnalyticsFilter[]): Promise<RankingDataResponse>;
+    getRankingData(ctx: TenantContext, dateRange: DateRange, dimension: string, limit?: number, filters?: AnalyticsFilter[], env?: EnvironmentQueryScope): Promise<RankingDataResponse>;
     getAggregateRequests(ctx: TenantContext, params: AggregateRequestsParams): Promise<AggregateRequestsResponse>;
     getSpanKindBreakdown(ctx: TenantContext, dateRange: {
         startDate: string;
@@ -812,6 +932,10 @@ export interface RequestsParams extends PaginationParams {
     sortField?: string;
     sortOrder?: 'asc' | 'desc';
     filters?: AnalyticsFilter[];
+    /** Single-env scoping (FR-005). Mirrors ScoresParams. Undefined = no env filter. */
+    environment?: EnvironmentScope;
+    /** Env-name allow-list from a saved filter. Mirrors ScoresParams. */
+    environments?: string[];
 }
 /**
  * Request record (GENERATION-type trace with input/output).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentmark-ai/api-types",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Shared API contract types for AgentMark services",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -15,7 +15,7 @@
     "clean": "rm -rf dist"
   },
   "dependencies": {
-    "@agentmark-ai/api-schemas": "0.3.0"
+    "@agentmark-ai/api-schemas": "0.4.0"
   },
   "devDependencies": {
     "typescript": "^5.5.3"