@agentmark-ai/api-types 0.4.0 → 0.6.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
@@ -265,7 +301,11 @@ export interface TracesParams extends PaginationParams {
     name?: string;
     tags?: string[];
     commitSha?: string;
-    filters?: AnalyticsFilter[];
+    /**
+     * AND of leaves and one-level OR-groups (see {@link AnalyticsFilterNode}).
+     * Plain `AnalyticsFilter[]` callers keep working unchanged.
+     */
+    filters?: AnalyticsFilterNode[];
     sortBy?: string;
     sortOrder?: 'asc' | 'desc';
     /** Single-env scoping per FR-031/FR-051. Undefined = no env filter. */
@@ -728,6 +768,24 @@ export interface AnalyticsFilter {
     operator: string;
     value: string | string[];
 }
+/**
+ * Disjunction of leaf predicates — matches rows satisfying ANY member.
+ * One level deep by design: a filter list is an AND of leaves and OR-groups
+ * (conjunctive normal form); members are always leaves, never nested groups.
+ */
+export interface AnalyticsFilterOrGroup {
+    or: AnalyticsFilter[];
+}
+/**
+ * One element of a filter list: a leaf predicate or an OR-group.
+ * `AnalyticsFilter[]` stays assignable wherever `AnalyticsFilterNode[]` is
+ * accepted, so existing AND-only callers are unaffected.
+ */
+export type AnalyticsFilterNode = AnalyticsFilter | AnalyticsFilterOrGroup;
+/**
+ * Type guard for OR-group nodes in a filter list.
+ */
+export declare function isAnalyticsFilterOrGroup(node: AnalyticsFilterNode): node is AnalyticsFilterOrGroup;
 /**
  * Supported filter fields for metrics queries.
  */
@@ -842,6 +900,12 @@ export interface IAnalyticsService {
     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, env?: EnvironmentQueryScope): Promise<TraceDetail | null>;
     getTraceDetailLightweight(ctx: TenantContext, traceId: string, env?: EnvironmentQueryScope): Promise<TraceDetail | null>;

package/dist/types.js

@@ -9,6 +9,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.isFilterConfigV2 = isFilterConfigV2;
 exports.isViewConfigV3 = isViewConfigV3;
+exports.isAnalyticsFilterOrGroup = isAnalyticsFilterOrGroup;
 /**
  * Type guard for v2 saved filter configs.
  */
@@ -21,3 +22,9 @@ function isFilterConfigV2(config) {
 function isViewConfigV3(config) {
     return 'version' in config && config.version === 3;
 }
+/**
+ * Type guard for OR-group nodes in a filter list.
+ */
+function isAnalyticsFilterOrGroup(node) {
+    return typeof node === 'object' && node !== null && Array.isArray(node.or);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentmark-ai/api-types",
-  "version": "0.4.0",
+  "version": "0.6.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.4.0"
+    "@agentmark-ai/api-schemas": "0.5.0"
   },
   "devDependencies": {
     "typescript": "^5.5.3"