observability-toolkit 2.0.0 → 2.1.1

package/dist/lib/core/shared-schemas.d.ts

@@ -0,0 +1,301 @@
+/**
+ * Shared Zod schemas for common tool parameters
+ * Reduces token usage by centralizing repeated definitions
+ *
+ * ## Overriding Schema Properties
+ *
+ * To customize a shared schema for a specific tool, spread the schema and override:
+ *
+ * @example
+ * ```typescript
+ * // Override limit default and description
+ * const myToolSchema = z.object({
+ *   ...paginationSchema,
+ *   limit: z.number().max(500).default(25).describe('Custom limit (max 500)'),
+ * });
+ *
+ * // Add extra validation to a field
+ * const strictSessionSchema = z.object({
+ *   ...sessionSchema,
+ *   sessionId: z.string().max(64).regex(/^[a-zA-Z0-9-]+$/).optional(),
+ * });
+ * ```
+ *
+ * Later properties in the spread override earlier ones, so tool-specific
+ * schemas always take precedence over shared defaults.
+ */
+import { z } from 'zod';
+import { BITS } from './units.js';
+export declare const METRICS_DEFAULT_LIMIT = 100;
+export declare const scoreUnitSchema: z.ZodString;
+/**
+ * OTel gen_ai.evaluation.score.value — double, finite, unbounded.
+ * Bounds (0-1, 0-100) are evaluator-defined; use scoreUnit to interpret.
+ */
+export declare const scoreValueSchema: z.ZodNumber;
+/** Bounded 0–1 score (precision, recall, F1, confidence, thresholds). */
+export declare const normalizedScoreSchema: z.ZodNumber;
+export type NormalizedScore = z.infer<typeof normalizedScoreSchema>;
+/** Severity schema for stored data — normalizes aliases and casing at parse time. */
+export declare const severitySchema: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+/** Severity schema for query inputs — uppercases for case-insensitive matching. */
+export declare const severityQuerySchema: z.ZodString;
+/** OTel span kind — resolved string name for stored/queried data. */
+export declare const spanKindSchema: z.ZodEnum<{
+    INTERNAL: "INTERNAL";
+    SERVER: "SERVER";
+    CLIENT: "CLIENT";
+    PRODUCER: "PRODUCER";
+    CONSUMER: "CONSUMER";
+}>;
+export type SpanKind = z.infer<typeof spanKindSchema>;
+/** OTel span kind — OTLP numeric wire value (0=UNSPECIFIED, 1=INTERNAL .. 5=CONSUMER). */
+export declare const spanKindNumericSchema: z.ZodInt;
+export declare const evaluatorTypeSchema: z.ZodEnum<{
+    llm: "llm";
+    human: "human";
+    rule: "rule";
+    classifier: "classifier";
+    seed: "seed";
+    canary: "canary";
+}>;
+export type EvaluatorType = z.infer<typeof evaluatorTypeSchema>;
+export declare const genAIOperationNameSchema: z.ZodEnum<{
+    chat: "chat";
+    embeddings: "embeddings";
+    invoke_agent: "invoke_agent";
+    execute_tool: "execute_tool";
+    text_completion: "text_completion";
+    generate_content: "generate_content";
+    retrieval: "retrieval";
+    create_agent: "create_agent";
+    invoke_workflow: "invoke_workflow";
+}>;
+export type GenAIOperationName = z.infer<typeof genAIOperationNameSchema>;
+export declare const genAIOutputTypeSchema: z.ZodEnum<{
+    json: "json";
+    text: "text";
+    image: "image";
+    speech: "speech";
+}>;
+export type GenAIOutputType = z.infer<typeof genAIOutputTypeSchema>;
+export declare const evaluationAggregationSchema: z.ZodEnum<{
+    avg: "avg";
+    min: "min";
+    max: "max";
+    count: "count";
+    p50: "p50";
+    p95: "p95";
+    p99: "p99";
+}>;
+export type EvaluationAggregation = z.infer<typeof evaluationAggregationSchema>;
+export declare const evaluationGroupByFieldSchema: z.ZodEnum<{
+    evaluationName: "evaluationName";
+    scoreLabel: "scoreLabel";
+    evaluator: "evaluator";
+}>;
+export type EvaluationGroupByField = z.infer<typeof evaluationGroupByFieldSchema>;
+export declare const metricAggregationSchema: z.ZodEnum<{
+    avg: "avg";
+    min: "min";
+    max: "max";
+    count: "count";
+    p50: "p50";
+    p95: "p95";
+    p99: "p99";
+    sum: "sum";
+    rate: "rate";
+}>;
+export type MetricAggregation = z.infer<typeof metricAggregationSchema>;
+export declare const TraceIdSchema: z.ZodString;
+export type TraceId = z.infer<typeof TraceIdSchema>;
+export declare const SpanIdSchema: z.ZodString;
+export type SpanId = z.infer<typeof SpanIdSchema>;
+/**
+ * gen_ai.request.model / gen_ai.response.model identifier.
+ * Covers observed vendor naming patterns (RFC: no format constraint defined).
+ * Watch: widen regex if a provider ships IDs with @, whitespace, or non-ASCII.
+ */
+export declare const modelIdSchema: z.ZodString;
+export type ModelId = z.infer<typeof modelIdSchema>;
+export declare const dateRangeSchema: {
+    startDate: z.ZodOptional<z.ZodISODate>;
+    endDate: z.ZodOptional<z.ZodISODate>;
+};
+/**
+ * Common pagination parameters
+ */
+export declare const paginationSchema: {
+    limit: z.ZodDefault<z.ZodNumber>;
+};
+/**
+ * Pagination with higher default for metrics
+ */
+export declare const metricsPaginationSchema: {
+    limit: z.ZodDefault<z.ZodNumber>;
+};
+/**
+ * Backend selection parameter
+ */
+export declare const backendSchema: {
+    backend: z.ZodDefault<z.ZodEnum<{
+        cloud: "cloud";
+        local: "local";
+    }>>;
+};
+/** Maximum length for trace ID */
+export declare const MAX_TRACE_ID_LENGTH = 64;
+export declare const MAX_SPAN_NAME_LENGTH = 512;
+export declare const MAX_ATTR_KEY_LENGTH = 100;
+export declare const OTEL_ATTR_PATH_REGEX: RegExp;
+export declare const OTEL_ATTR_PATH_MSG = "Attribute path must contain only alphanumeric, dot, or underscore characters";
+export declare const MAX_ATTR_VALUE_LENGTH = 500;
+export declare const MAX_ATTR_FILTERS = 20;
+export declare const MAX_PROVIDER_LENGTH = 100;
+export declare const MAX_DATASET_LIST_LIMIT = 500;
+export declare const MAX_DATASET_ID_LENGTH = BITS.B128;
+export declare const MAX_EXPLANATION_LENGTH = 10240;
+export declare const SessionIdSchema: z.ZodString;
+export type SessionId = z.infer<typeof SessionIdSchema>;
+export declare const ResponseIdSchema: z.ZodString;
+export type ResponseId = z.infer<typeof ResponseIdSchema>;
+export declare const AgentIdSchema: z.ZodString;
+export type AgentId = z.infer<typeof AgentIdSchema>;
+export declare const IpAddressSchema: z.ZodUnion<readonly [z.ZodIPv4, z.ZodIPv6]>;
+export type IpAddress = z.infer<typeof IpAddressSchema>;
+export declare const sessionSchema: {
+    sessionId: z.ZodOptional<z.ZodString>;
+};
+export declare const traceIdSchema: {
+    traceId: z.ZodOptional<z.ZodString>;
+};
+/** ISO 8601 datetime range (start and end as UTC datetime strings). */
+export declare const timeRangeSchema: z.ZodObject<{
+    start: z.ZodISODateTime;
+    end: z.ZodISODateTime;
+}, z.core.$strip>;
+export type TimeRange = z.infer<typeof timeRangeSchema>;
+/** Shared correlation ID fields used in evaluation result and webhook payload schemas. */
+export declare const correlationIdsSchema: {
+    responseId: z.ZodOptional<z.ZodString>;
+    traceId: z.ZodOptional<z.ZodString>;
+    sessionId: z.ZodOptional<z.ZodString>;
+    agentId: z.ZodOptional<z.ZodString>;
+};
+export declare const commonQuerySchema: {
+    limit: z.ZodDefault<z.ZodNumber>;
+    startDate: z.ZodOptional<z.ZodISODate>;
+    endDate: z.ZodOptional<z.ZodISODate>;
+    sessionId: z.ZodOptional<z.ZodString>;
+    backend: z.ZodDefault<z.ZodEnum<{
+        cloud: "cloud";
+        local: "local";
+    }>>;
+};
+export declare const exportFilterSchema: {
+    startDate: z.ZodOptional<z.ZodISODate>;
+    endDate: z.ZodOptional<z.ZodISODate>;
+    sessionId: z.ZodOptional<z.ZodString>;
+    traceId: z.ZodOptional<z.ZodString>;
+    evaluationName: z.ZodOptional<z.ZodString>;
+    scoreMin: z.ZodOptional<z.ZodNumber>;
+    scoreMax: z.ZodOptional<z.ZodNumber>;
+    scoreLabel: z.ZodOptional<z.ZodString>;
+    evaluatorType: z.ZodOptional<z.ZodEnum<{
+        llm: "llm";
+        human: "human";
+        rule: "rule";
+        classifier: "classifier";
+        seed: "seed";
+        canary: "canary";
+    }>>;
+    datasetId: z.ZodOptional<z.ZodString>;
+};
+/**
+ * Common export options (limit, batchSize, dryRun)
+ */
+export declare const exportOptionsSchema: {
+    limit: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    batchSize: z.ZodOptional<z.ZodNumber>;
+    dryRun: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+};
+/**
+ * OTel GenAI operation name enum
+ */
+export declare const operationNameSchema: {
+    operationName: z.ZodOptional<z.ZodEnum<{
+        chat: "chat";
+        embeddings: "embeddings";
+        invoke_agent: "invoke_agent";
+        execute_tool: "execute_tool";
+        text_completion: "text_completion";
+        generate_content: "generate_content";
+        retrieval: "retrieval";
+        create_agent: "create_agent";
+        invoke_workflow: "invoke_workflow";
+    }>>;
+};
+/**
+ * Build a complete query schema from common parameters.
+ * Use this to create tool input schemas that include standard filtering.
+ *
+ * @example
+ * ```typescript
+ * const myToolSchema = z.object({
+ *   ...queryComposerSchema(),
+ *   customField: z.string(),
+ * });
+ * ```
+ */
+export declare function queryComposerSchema(overrides?: {
+    pagination?: typeof paginationSchema;
+    dateRange?: typeof dateRangeSchema;
+    backend?: typeof backendSchema;
+    session?: typeof sessionSchema;
+}): {
+    limit: z.ZodDefault<z.ZodNumber>;
+    startDate: z.ZodOptional<z.ZodISODate>;
+    endDate: z.ZodOptional<z.ZodISODate>;
+    sessionId: z.ZodOptional<z.ZodString>;
+    backend: z.ZodDefault<z.ZodEnum<{
+        cloud: "cloud";
+        local: "local";
+    }>>;
+};
+/**
+ * Build an export schema from common filter and option parameters.
+ *
+ * @example
+ * ```typescript
+ * const myExportSchema = z.object({
+ *   ...exportComposerSchema(),
+ *   platformSpecificField: z.string(),
+ * });
+ * ```
+ */
+export declare function exportComposerSchema(overrides?: {
+    filters?: typeof exportFilterSchema;
+    options?: typeof exportOptionsSchema;
+}): {
+    limit: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    batchSize: z.ZodOptional<z.ZodNumber>;
+    dryRun: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    startDate: z.ZodOptional<z.ZodISODate>;
+    endDate: z.ZodOptional<z.ZodISODate>;
+    sessionId: z.ZodOptional<z.ZodString>;
+    traceId: z.ZodOptional<z.ZodString>;
+    evaluationName: z.ZodOptional<z.ZodString>;
+    scoreMin: z.ZodOptional<z.ZodNumber>;
+    scoreMax: z.ZodOptional<z.ZodNumber>;
+    scoreLabel: z.ZodOptional<z.ZodString>;
+    evaluatorType: z.ZodOptional<z.ZodEnum<{
+        llm: "llm";
+        human: "human";
+        rule: "rule";
+        classifier: "classifier";
+        seed: "seed";
+        canary: "canary";
+    }>>;
+    datasetId: z.ZodOptional<z.ZodString>;
+};
+//# sourceMappingURL=shared-schemas.d.ts.map

package/dist/lib/core/shared-schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared-schemas.d.ts","sourceRoot":"","sources":["../../../src/lib/core/shared-schemas.ts"],"names":[],"mappings":"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"}

package/dist/lib/core/shared-schemas.js

@@ -0,0 +1,222 @@
+/**
+ * Shared Zod schemas for common tool parameters
+ * Reduces token usage by centralizing repeated definitions
+ *
+ * ## Overriding Schema Properties
+ *
+ * To customize a shared schema for a specific tool, spread the schema and override:
+ *
+ * @example
+ * ```typescript
+ * // Override limit default and description
+ * const myToolSchema = z.object({
+ *   ...paginationSchema,
+ *   limit: z.number().max(500).default(25).describe('Custom limit (max 500)'),
+ * });
+ *
+ * // Add extra validation to a field
+ * const strictSessionSchema = z.object({
+ *   ...sessionSchema,
+ *   sessionId: z.string().max(64).regex(/^[a-zA-Z0-9-]+$/).optional(),
+ * });
+ * ```
+ *
+ * Later properties in the spread override earlier ones, so tool-specific
+ * schemas always take precedence over shared defaults.
+ */
+import { z } from 'zod';
+import { DEFAULT_LIMIT } from './input-validator.js';
+import { BITS } from './units.js';
+import { normalizeOtelLogSeverity, SPAN_KIND } from './constants-otel.js';
+import { MAX_EXPORT_LIMIT, MAX_QUERY_LIMIT, MAX_SESSION_ID_LENGTH, MAX_SHORT_ID_LENGTH, OTLP_SPAN_ID_LENGTH, OTLP_TRACE_ID_LENGTH, } from './constants.js';
+export const METRICS_DEFAULT_LIMIT = 100;
+export const scoreUnitSchema = z.string().toLowerCase().trim();
+/**
+ * OTel gen_ai.evaluation.score.value — double, finite, unbounded.
+ * Bounds (0-1, 0-100) are evaluator-defined; use scoreUnit to interpret.
+ */
+export const scoreValueSchema = z.number().finite();
+/** Bounded 0–1 score (precision, recall, F1, confidence, thresholds). */
+export const normalizedScoreSchema = z.number().min(0).max(1);
+/** Severity schema for stored data — normalizes aliases and casing at parse time. */
+export const severitySchema = z.string().transform(v => normalizeOtelLogSeverity(v) ?? v);
+/** Severity schema for query inputs — uppercases for case-insensitive matching. */
+export const severityQuerySchema = z.string().min(1).toUpperCase();
+/** OTel span kind — resolved string name for stored/queried data. */
+export const spanKindSchema = z.enum(['INTERNAL', 'SERVER', 'CLIENT', 'PRODUCER', 'CONSUMER']);
+/** OTel span kind — OTLP numeric wire value (0=UNSPECIFIED, 1=INTERNAL .. 5=CONSUMER). */
+export const spanKindNumericSchema = z.int().min(SPAN_KIND.UNSPECIFIED).max(SPAN_KIND.CONSUMER);
+export const evaluatorTypeSchema = z.enum(['llm', 'human', 'rule', 'classifier', 'seed', 'canary']);
+export const genAIOperationNameSchema = z.enum([
+    'chat',
+    'embeddings',
+    'invoke_agent',
+    'execute_tool',
+    'text_completion',
+    'generate_content',
+    'retrieval',
+    'create_agent',
+    'invoke_workflow',
+]);
+export const genAIOutputTypeSchema = z.enum(['text', 'json', 'image', 'speech']);
+export const evaluationAggregationSchema = z.enum(['avg', 'min', 'max', 'count', 'p50', 'p95', 'p99']);
+export const evaluationGroupByFieldSchema = z.enum(['evaluationName', 'scoreLabel', 'evaluator']);
+export const metricAggregationSchema = z.enum(['sum', 'avg', 'min', 'max', 'count', 'p50', 'p95', 'p99', 'rate']);
+export const TraceIdSchema = z
+    .string()
+    .length(OTLP_TRACE_ID_LENGTH, `Trace ID must be ${OTLP_TRACE_ID_LENGTH} characters`)
+    .regex(/^[0-9a-f]+$/, 'Trace ID must be lowercase hexadecimal')
+    .refine((val) => !(/^0+$/.test(val)), 'Cannot be zero');
+export const SpanIdSchema = z
+    .string()
+    .length(OTLP_SPAN_ID_LENGTH, `Span ID must be ${OTLP_SPAN_ID_LENGTH} characters`)
+    .regex(/^[0-9a-f]+$/, 'Span ID must be lowercase hexadecimal')
+    .refine((val) => !(/^0+$/.test(val)), 'Cannot be zero');
+/**
+ * gen_ai.request.model / gen_ai.response.model identifier.
+ * Covers observed vendor naming patterns (RFC: no format constraint defined).
+ * Watch: widen regex if a provider ships IDs with @, whitespace, or non-ASCII.
+ */
+export const modelIdSchema = z
+    .string()
+    .regex(/^[a-zA-Z0-9._:/-]+$/, 'Invalid model identifier format');
+export const dateRangeSchema = {
+    startDate: z.iso.date().optional().describe('Start (YYYY-MM-DD)'),
+    endDate: z.iso.date().optional().describe('End (YYYY-MM-DD)'),
+};
+/**
+ * Common pagination parameters
+ */
+export const paginationSchema = {
+    limit: z.number().min(1).max(MAX_QUERY_LIMIT).default(DEFAULT_LIMIT).describe('Max results'),
+};
+/**
+ * Pagination with higher default for metrics
+ */
+export const metricsPaginationSchema = {
+    limit: z.number().min(1).max(MAX_QUERY_LIMIT).default(METRICS_DEFAULT_LIMIT).describe('Max results'),
+};
+/**
+ * Backend selection parameter
+ */
+export const backendSchema = {
+    backend: z.enum(['local', 'cloud']).default('cloud').describe('Backend (default: cloud)'),
+};
+/** Maximum length for trace ID */
+export const MAX_TRACE_ID_LENGTH = 64;
+// These are MCP tool input validation bounds (user-supplied query filters),
+// intentionally more conservative than OTel spec limits (128/1024).
+// OTel spec attribute truncation limits live in instrumentation.ts as OTEL_MAX_ATTR_*.
+export const MAX_SPAN_NAME_LENGTH = 512;
+export const MAX_ATTR_KEY_LENGTH = 100;
+export const OTEL_ATTR_PATH_REGEX = /^[a-zA-Z0-9_.]+$/;
+export const OTEL_ATTR_PATH_MSG = 'Attribute path must contain only alphanumeric, dot, or underscore characters';
+export const MAX_ATTR_VALUE_LENGTH = 500;
+export const MAX_ATTR_FILTERS = 20;
+export const MAX_PROVIDER_LENGTH = 100;
+export const MAX_DATASET_LIST_LIMIT = 500;
+export const MAX_DATASET_ID_LENGTH = BITS.B128;
+export const MAX_EXPLANATION_LENGTH = 10240;
+export const SessionIdSchema = z
+    .string()
+    .min(1)
+    .max(MAX_SESSION_ID_LENGTH);
+export const ResponseIdSchema = z
+    .string()
+    .min(1)
+    .max(MAX_SHORT_ID_LENGTH);
+export const AgentIdSchema = z
+    .string()
+    .min(1)
+    .max(MAX_SHORT_ID_LENGTH);
+export const IpAddressSchema = z.union([z.ipv4(), z.ipv6()]);
+export const sessionSchema = {
+    sessionId: SessionIdSchema.optional().describe('Session ID'),
+};
+export const traceIdSchema = {
+    traceId: TraceIdSchema.optional().describe('Trace ID'),
+};
+/** ISO 8601 datetime range (start and end as UTC datetime strings). */
+export const timeRangeSchema = z.object({
+    start: z.iso.datetime(),
+    end: z.iso.datetime(),
+});
+/** Shared correlation ID fields used in evaluation result and webhook payload schemas. */
+export const correlationIdsSchema = {
+    responseId: ResponseIdSchema.optional(),
+    traceId: TraceIdSchema.optional(),
+    sessionId: SessionIdSchema.optional(),
+    agentId: AgentIdSchema.optional(),
+};
+export const commonQuerySchema = {
+    ...backendSchema,
+    ...sessionSchema,
+    ...dateRangeSchema,
+    ...paginationSchema,
+};
+export const exportFilterSchema = {
+    evaluationName: z.string().optional().describe('Evaluation name (substring)'),
+    scoreMin: z.number().optional().describe('Min score threshold'),
+    scoreMax: z.number().optional().describe('Max score threshold'),
+    scoreLabel: z.string().optional().describe('Score label (exact)'),
+    evaluatorType: evaluatorTypeSchema.optional().describe('Evaluator type'),
+    datasetId: z.string().max(MAX_DATASET_ID_LENGTH).optional().describe('Export only evaluations belonging to this dataset'),
+    ...traceIdSchema,
+    ...sessionSchema,
+    ...dateRangeSchema,
+};
+/**
+ * Common export options (limit, batchSize, dryRun)
+ */
+export const exportOptionsSchema = {
+    limit: z.number().min(1).max(MAX_EXPORT_LIMIT).optional().default(MAX_QUERY_LIMIT).describe('Max evaluations to export (max 10000)'),
+    batchSize: z.number().min(1).max(MAX_QUERY_LIMIT).optional().describe('Batch size for export (default 100)'),
+    dryRun: z.boolean().optional().default(false).describe('Preview export without sending'),
+};
+/**
+ * OTel GenAI operation name enum
+ */
+export const operationNameSchema = {
+    operationName: genAIOperationNameSchema.optional().describe('GenAI operation'),
+};
+// ============================================================================
+// Composed Schema Builders
+// ============================================================================
+/**
+ * Build a complete query schema from common parameters.
+ * Use this to create tool input schemas that include standard filtering.
+ *
+ * @example
+ * ```typescript
+ * const myToolSchema = z.object({
+ *   ...queryComposerSchema(),
+ *   customField: z.string(),
+ * });
+ * ```
+ */
+export function queryComposerSchema(overrides) {
+    return {
+        ...(overrides?.backend ?? backendSchema),
+        ...(overrides?.session ?? sessionSchema),
+        ...(overrides?.dateRange ?? dateRangeSchema),
+        ...(overrides?.pagination ?? paginationSchema),
+    };
+}
+/**
+ * Build an export schema from common filter and option parameters.
+ *
+ * @example
+ * ```typescript
+ * const myExportSchema = z.object({
+ *   ...exportComposerSchema(),
+ *   platformSpecificField: z.string(),
+ * });
+ * ```
+ */
+export function exportComposerSchema(overrides) {
+    return {
+        ...(overrides?.filters ?? exportFilterSchema),
+        ...(overrides?.options ?? exportOptionsSchema),
+    };
+}
+//# sourceMappingURL=shared-schemas.js.map

package/dist/lib/core/shared-schemas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared-schemas.js","sourceRoot":"","sources":["../../../src/lib/core/shared-schemas.ts"],"names":[],"mappings":"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"}

package/dist/lib/core/shared-schemas.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared-schemas.test.d.ts","sourceRoot":"","sources":["../../../src/lib/core/shared-schemas.test.ts"],"names":[],"mappings":"AAAA;;GAEG"}