@objectstack/spec 0.2.0 → 0.3.1

package/dist/ai/nlq.zod.d.ts.map

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

package/dist/ai/nlq.zod.js

@@ -0,0 +1,246 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.QueryTemplateSchema = exports.FieldSynonymConfigSchema = exports.NLQAnalyticsSchema = exports.NLQModelConfigSchema = exports.NLQTrainingExampleSchema = exports.NLQResponseSchema = exports.NLQRequestSchema = exports.NLQParseResultSchema = exports.QueryContextSchema = exports.NLQFieldMappingSchema = exports.TimeframeSchema = exports.EntitySchema = exports.QueryIntentSchema = void 0;
+const zod_1 = require("zod");
+/**
+ * Natural Language Query (NLQ) Protocol
+ *
+ * Transforms natural language queries into ObjectQL AST (Abstract Syntax Tree).
+ * Enables business users to query data using natural language instead of writing code.
+ */
+/**
+ * Query Intent Type
+ */
+exports.QueryIntentSchema = zod_1.z.enum([
+    'select', // Retrieve data (e.g., "show me all accounts")
+    'aggregate', // Aggregation (e.g., "total revenue by region")
+    'filter', // Filter data (e.g., "accounts created last month")
+    'sort', // Sort data (e.g., "top 10 opportunities by value")
+    'compare', // Compare values (e.g., "compare this quarter vs last quarter")
+    'trend', // Analyze trends (e.g., "sales trend over time")
+    'insight', // Generate insights (e.g., "what's unusual about this data")
+    'create', // Create record (e.g., "create a new task")
+    'update', // Update record (e.g., "mark this as complete")
+    'delete', // Delete record (e.g., "remove this contact")
+]);
+/**
+ * Entity Recognition
+ */
+exports.EntitySchema = zod_1.z.object({
+    type: zod_1.z.enum(['object', 'field', 'value', 'operator', 'function', 'timeframe']),
+    text: zod_1.z.string().describe('Original text from query'),
+    value: zod_1.z.any().describe('Normalized value'),
+    confidence: zod_1.z.number().min(0).max(1).describe('Confidence score'),
+    span: zod_1.z.tuple([zod_1.z.number(), zod_1.z.number()]).optional().describe('Character span in query'),
+});
+/**
+ * Timeframe Detection
+ */
+exports.TimeframeSchema = zod_1.z.object({
+    type: zod_1.z.enum(['absolute', 'relative']),
+    start: zod_1.z.string().optional().describe('Start date (ISO format)'),
+    end: zod_1.z.string().optional().describe('End date (ISO format)'),
+    relative: zod_1.z.object({
+        unit: zod_1.z.enum(['hour', 'day', 'week', 'month', 'quarter', 'year']),
+        value: zod_1.z.number().int(),
+        direction: zod_1.z.enum(['past', 'future', 'current']).default('past'),
+    }).optional(),
+    text: zod_1.z.string().describe('Original timeframe text'),
+});
+/**
+ * NLQ Field Mapping
+ * Maps natural language field names to actual object fields
+ */
+exports.NLQFieldMappingSchema = zod_1.z.object({
+    naturalLanguage: zod_1.z.string().describe('NL field name (e.g., "customer name")'),
+    objectField: zod_1.z.string().describe('Actual field name (e.g., "account.name")'),
+    object: zod_1.z.string().describe('Object name'),
+    field: zod_1.z.string().describe('Field name'),
+    confidence: zod_1.z.number().min(0).max(1),
+});
+/**
+ * Query Context
+ */
+exports.QueryContextSchema = zod_1.z.object({
+    /** User Information */
+    userId: zod_1.z.string().optional(),
+    userRole: zod_1.z.string().optional(),
+    /** Current Context */
+    currentObject: zod_1.z.string().optional().describe('Current object being viewed'),
+    currentRecordId: zod_1.z.string().optional().describe('Current record ID'),
+    /** Conversation History */
+    conversationHistory: zod_1.z.array(zod_1.z.object({
+        query: zod_1.z.string(),
+        timestamp: zod_1.z.string(),
+        intent: exports.QueryIntentSchema.optional(),
+    })).optional(),
+    /** Preferences */
+    defaultLimit: zod_1.z.number().int().default(100),
+    timezone: zod_1.z.string().default('UTC'),
+    locale: zod_1.z.string().default('en-US'),
+});
+/**
+ * NLQ Parse Result
+ */
+exports.NLQParseResultSchema = zod_1.z.object({
+    /** Original Query */
+    originalQuery: zod_1.z.string(),
+    /** Intent Detection */
+    intent: exports.QueryIntentSchema,
+    intentConfidence: zod_1.z.number().min(0).max(1),
+    /** Entity Recognition */
+    entities: zod_1.z.array(exports.EntitySchema),
+    /** Object & Field Resolution */
+    targetObject: zod_1.z.string().optional().describe('Primary object to query'),
+    fields: zod_1.z.array(exports.NLQFieldMappingSchema).optional(),
+    /** Temporal Information */
+    timeframe: exports.TimeframeSchema.optional(),
+    /** Query AST */
+    ast: zod_1.z.any().describe('Generated ObjectQL AST'),
+    /** Metadata */
+    confidence: zod_1.z.number().min(0).max(1).describe('Overall confidence'),
+    ambiguities: zod_1.z.array(zod_1.z.object({
+        type: zod_1.z.string(),
+        description: zod_1.z.string(),
+        suggestions: zod_1.z.array(zod_1.z.string()).optional(),
+    })).optional().describe('Detected ambiguities requiring clarification'),
+    /** Alternative Interpretations */
+    alternatives: zod_1.z.array(zod_1.z.object({
+        interpretation: zod_1.z.string(),
+        confidence: zod_1.z.number(),
+        ast: zod_1.z.any(),
+    })).optional(),
+});
+/**
+ * NLQ Request
+ */
+exports.NLQRequestSchema = zod_1.z.object({
+    /** Query */
+    query: zod_1.z.string().describe('Natural language query'),
+    /** Context */
+    context: exports.QueryContextSchema.optional(),
+    /** Options */
+    includeAlternatives: zod_1.z.boolean().default(false).describe('Include alternative interpretations'),
+    maxAlternatives: zod_1.z.number().int().default(3),
+    minConfidence: zod_1.z.number().min(0).max(1).default(0.5).describe('Minimum confidence threshold'),
+    /** Execution */
+    executeQuery: zod_1.z.boolean().default(false).describe('Execute query and return results'),
+    maxResults: zod_1.z.number().int().optional().describe('Maximum results to return'),
+});
+/**
+ * NLQ Response
+ */
+exports.NLQResponseSchema = zod_1.z.object({
+    /** Parse Result */
+    parseResult: exports.NLQParseResultSchema,
+    /** Query Results (if executeQuery = true) */
+    results: zod_1.z.array(zod_1.z.record(zod_1.z.any())).optional().describe('Query results'),
+    totalCount: zod_1.z.number().int().optional(),
+    /** Execution Metadata */
+    executionTime: zod_1.z.number().optional().describe('Execution time in milliseconds'),
+    needsClarification: zod_1.z.boolean().describe('Whether query needs clarification'),
+    /** Suggestions */
+    suggestions: zod_1.z.array(zod_1.z.string()).optional().describe('Query refinement suggestions'),
+});
+/**
+ * NLQ Training Example
+ */
+exports.NLQTrainingExampleSchema = zod_1.z.object({
+    /** Input */
+    query: zod_1.z.string().describe('Natural language query'),
+    context: exports.QueryContextSchema.optional(),
+    /** Expected Output */
+    expectedIntent: exports.QueryIntentSchema,
+    expectedObject: zod_1.z.string().optional(),
+    expectedAST: zod_1.z.any().describe('Expected ObjectQL AST'),
+    /** Metadata */
+    category: zod_1.z.string().optional().describe('Example category'),
+    tags: zod_1.z.array(zod_1.z.string()).optional(),
+    notes: zod_1.z.string().optional(),
+});
+/**
+ * NLQ Model Configuration
+ */
+exports.NLQModelConfigSchema = zod_1.z.object({
+    /** Model */
+    modelId: zod_1.z.string().describe('Model from registry'),
+    /** Prompt Engineering */
+    systemPrompt: zod_1.z.string().optional().describe('System prompt override'),
+    includeSchema: zod_1.z.boolean().default(true).describe('Include object schema in prompt'),
+    includeExamples: zod_1.z.boolean().default(true).describe('Include examples in prompt'),
+    /** Intent Detection */
+    enableIntentDetection: zod_1.z.boolean().default(true),
+    intentThreshold: zod_1.z.number().min(0).max(1).default(0.7),
+    /** Entity Recognition */
+    enableEntityRecognition: zod_1.z.boolean().default(true),
+    entityRecognitionModel: zod_1.z.string().optional(),
+    /** Field Resolution */
+    enableFuzzyMatching: zod_1.z.boolean().default(true).describe('Fuzzy match field names'),
+    fuzzyMatchThreshold: zod_1.z.number().min(0).max(1).default(0.8),
+    /** Temporal Processing */
+    enableTimeframeDetection: zod_1.z.boolean().default(true),
+    defaultTimeframe: zod_1.z.string().optional().describe('Default timeframe if not specified'),
+    /** Performance */
+    enableCaching: zod_1.z.boolean().default(true),
+    cacheTTL: zod_1.z.number().int().default(3600).describe('Cache TTL in seconds'),
+});
+/**
+ * NLQ Analytics
+ */
+exports.NLQAnalyticsSchema = zod_1.z.object({
+    /** Query Metrics */
+    totalQueries: zod_1.z.number().int(),
+    successfulQueries: zod_1.z.number().int(),
+    failedQueries: zod_1.z.number().int(),
+    averageConfidence: zod_1.z.number().min(0).max(1),
+    /** Intent Distribution */
+    intentDistribution: zod_1.z.record(zod_1.z.number().int()).describe('Count by intent type'),
+    /** Common Patterns */
+    topQueries: zod_1.z.array(zod_1.z.object({
+        query: zod_1.z.string(),
+        count: zod_1.z.number().int(),
+        averageConfidence: zod_1.z.number(),
+    })),
+    /** Performance */
+    averageParseTime: zod_1.z.number().describe('Average parse time in milliseconds'),
+    averageExecutionTime: zod_1.z.number().optional(),
+    /** Issues */
+    lowConfidenceQueries: zod_1.z.array(zod_1.z.object({
+        query: zod_1.z.string(),
+        confidence: zod_1.z.number(),
+        timestamp: zod_1.z.string(),
+    })),
+    /** Timeframe */
+    startDate: zod_1.z.string().describe('ISO timestamp'),
+    endDate: zod_1.z.string().describe('ISO timestamp'),
+});
+/**
+ * Field Synonym Configuration
+ */
+exports.FieldSynonymConfigSchema = zod_1.z.object({
+    object: zod_1.z.string().describe('Object name'),
+    field: zod_1.z.string().describe('Field name'),
+    synonyms: zod_1.z.array(zod_1.z.string()).describe('Natural language synonyms'),
+    examples: zod_1.z.array(zod_1.z.string()).optional().describe('Example queries using synonyms'),
+});
+/**
+ * Query Template
+ */
+exports.QueryTemplateSchema = zod_1.z.object({
+    id: zod_1.z.string(),
+    name: zod_1.z.string().regex(/^[a-z_][a-z0-9_]*$/).describe('Template name (snake_case)'),
+    label: zod_1.z.string(),
+    /** Template */
+    pattern: zod_1.z.string().describe('Query pattern with placeholders'),
+    variables: zod_1.z.array(zod_1.z.object({
+        name: zod_1.z.string(),
+        type: zod_1.z.enum(['object', 'field', 'value', 'timeframe']),
+        required: zod_1.z.boolean().default(false),
+    })),
+    /** Generated AST */
+    astTemplate: zod_1.z.any().describe('AST template with variable placeholders'),
+    /** Metadata */
+    category: zod_1.z.string().optional(),
+    examples: zod_1.z.array(zod_1.z.string()).optional(),
+    tags: zod_1.z.array(zod_1.z.string()).optional(),
+});