@objectstack/spec 0.1.2 → 0.3.0

package/json-schema/ModelSelectionCriteria.json

@@ -0,0 +1,50 @@
+{
+  "$ref": "#/definitions/ModelSelectionCriteria",
+  "definitions": {
+    "ModelSelectionCriteria": {
+      "type": "object",
+      "properties": {
+        "capabilities": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Required capabilities"
+        },
+        "maxCostPer1kTokens": {
+          "type": "number",
+          "description": "Maximum acceptable cost"
+        },
+        "minContextWindow": {
+          "type": "number",
+          "description": "Minimum context window size"
+        },
+        "provider": {
+          "type": "string",
+          "enum": [
+            "openai",
+            "azure_openai",
+            "anthropic",
+            "google",
+            "cohere",
+            "huggingface",
+            "local",
+            "custom"
+          ]
+        },
+        "tags": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "excludeDeprecated": {
+          "type": "boolean",
+          "default": true
+        }
+      },
+      "additionalProperties": false
+    }
+  },
+  "$schema": "http://json-schema.org/draft-07/schema#"
+}

package/json-schema/NLQAnalytics.json

@@ -0,0 +1,106 @@
+{
+  "$ref": "#/definitions/NLQAnalytics",
+  "definitions": {
+    "NLQAnalytics": {
+      "type": "object",
+      "properties": {
+        "totalQueries": {
+          "type": "integer"
+        },
+        "successfulQueries": {
+          "type": "integer"
+        },
+        "failedQueries": {
+          "type": "integer"
+        },
+        "averageConfidence": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1
+        },
+        "intentDistribution": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "integer"
+          },
+          "description": "Count by intent type"
+        },
+        "topQueries": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "query": {
+                "type": "string"
+              },
+              "count": {
+                "type": "integer"
+              },
+              "averageConfidence": {
+                "type": "number"
+              }
+            },
+            "required": [
+              "query",
+              "count",
+              "averageConfidence"
+            ],
+            "additionalProperties": false
+          }
+        },
+        "averageParseTime": {
+          "type": "number",
+          "description": "Average parse time in milliseconds"
+        },
+        "averageExecutionTime": {
+          "type": "number"
+        },
+        "lowConfidenceQueries": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "query": {
+                "type": "string"
+              },
+              "confidence": {
+                "type": "number"
+              },
+              "timestamp": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "query",
+              "confidence",
+              "timestamp"
+            ],
+            "additionalProperties": false
+          }
+        },
+        "startDate": {
+          "type": "string",
+          "description": "ISO timestamp"
+        },
+        "endDate": {
+          "type": "string",
+          "description": "ISO timestamp"
+        }
+      },
+      "required": [
+        "totalQueries",
+        "successfulQueries",
+        "failedQueries",
+        "averageConfidence",
+        "intentDistribution",
+        "topQueries",
+        "averageParseTime",
+        "lowConfidenceQueries",
+        "startDate",
+        "endDate"
+      ],
+      "additionalProperties": false
+    }
+  },
+  "$schema": "http://json-schema.org/draft-07/schema#"
+}

package/json-schema/NLQFieldMapping.json

@@ -0,0 +1,40 @@
+{
+  "$ref": "#/definitions/NLQFieldMapping",
+  "definitions": {
+    "NLQFieldMapping": {
+      "type": "object",
+      "properties": {
+        "naturalLanguage": {
+          "type": "string",
+          "description": "NL field name (e.g., \"customer name\")"
+        },
+        "objectField": {
+          "type": "string",
+          "description": "Actual field name (e.g., \"account.name\")"
+        },
+        "object": {
+          "type": "string",
+          "description": "Object name"
+        },
+        "field": {
+          "type": "string",
+          "description": "Field name"
+        },
+        "confidence": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1
+        }
+      },
+      "required": [
+        "naturalLanguage",
+        "objectField",
+        "object",
+        "field",
+        "confidence"
+      ],
+      "additionalProperties": false
+    }
+  },
+  "$schema": "http://json-schema.org/draft-07/schema#"
+}

package/json-schema/NLQModelConfig.json

@@ -0,0 +1,78 @@
+{
+  "$ref": "#/definitions/NLQModelConfig",
+  "definitions": {
+    "NLQModelConfig": {
+      "type": "object",
+      "properties": {
+        "modelId": {
+          "type": "string",
+          "description": "Model from registry"
+        },
+        "systemPrompt": {
+          "type": "string",
+          "description": "System prompt override"
+        },
+        "includeSchema": {
+          "type": "boolean",
+          "default": true,
+          "description": "Include object schema in prompt"
+        },
+        "includeExamples": {
+          "type": "boolean",
+          "default": true,
+          "description": "Include examples in prompt"
+        },
+        "enableIntentDetection": {
+          "type": "boolean",
+          "default": true
+        },
+        "intentThreshold": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1,
+          "default": 0.7
+        },
+        "enableEntityRecognition": {
+          "type": "boolean",
+          "default": true
+        },
+        "entityRecognitionModel": {
+          "type": "string"
+        },
+        "enableFuzzyMatching": {
+          "type": "boolean",
+          "default": true,
+          "description": "Fuzzy match field names"
+        },
+        "fuzzyMatchThreshold": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1,
+          "default": 0.8
+        },
+        "enableTimeframeDetection": {
+          "type": "boolean",
+          "default": true
+        },
+        "defaultTimeframe": {
+          "type": "string",
+          "description": "Default timeframe if not specified"
+        },
+        "enableCaching": {
+          "type": "boolean",
+          "default": true
+        },
+        "cacheTTL": {
+          "type": "integer",
+          "default": 3600,
+          "description": "Cache TTL in seconds"
+        }
+      },
+      "required": [
+        "modelId"
+      ],
+      "additionalProperties": false
+    }
+  },
+  "$schema": "http://json-schema.org/draft-07/schema#"
+}

package/json-schema/NLQParseResult.json

@@ -0,0 +1,252 @@
+{
+  "$ref": "#/definitions/NLQParseResult",
+  "definitions": {
+    "NLQParseResult": {
+      "type": "object",
+      "properties": {
+        "originalQuery": {
+          "type": "string"
+        },
+        "intent": {
+          "type": "string",
+          "enum": [
+            "select",
+            "aggregate",
+            "filter",
+            "sort",
+            "compare",
+            "trend",
+            "insight",
+            "create",
+            "update",
+            "delete"
+          ]
+        },
+        "intentConfidence": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1
+        },
+        "entities": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "type": {
+                "type": "string",
+                "enum": [
+                  "object",
+                  "field",
+                  "value",
+                  "operator",
+                  "function",
+                  "timeframe"
+                ]
+              },
+              "text": {
+                "type": "string",
+                "description": "Original text from query"
+              },
+              "value": {
+                "description": "Normalized value"
+              },
+              "confidence": {
+                "type": "number",
+                "minimum": 0,
+                "maximum": 1,
+                "description": "Confidence score"
+              },
+              "span": {
+                "type": "array",
+                "minItems": 2,
+                "maxItems": 2,
+                "items": [
+                  {
+                    "type": "number"
+                  },
+                  {
+                    "type": "number"
+                  }
+                ],
+                "description": "Character span in query"
+              }
+            },
+            "required": [
+              "type",
+              "text",
+              "confidence"
+            ],
+            "additionalProperties": false
+          }
+        },
+        "targetObject": {
+          "type": "string",
+          "description": "Primary object to query"
+        },
+        "fields": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "naturalLanguage": {
+                "type": "string",
+                "description": "NL field name (e.g., \"customer name\")"
+              },
+              "objectField": {
+                "type": "string",
+                "description": "Actual field name (e.g., \"account.name\")"
+              },
+              "object": {
+                "type": "string",
+                "description": "Object name"
+              },
+              "field": {
+                "type": "string",
+                "description": "Field name"
+              },
+              "confidence": {
+                "type": "number",
+                "minimum": 0,
+                "maximum": 1
+              }
+            },
+            "required": [
+              "naturalLanguage",
+              "objectField",
+              "object",
+              "field",
+              "confidence"
+            ],
+            "additionalProperties": false
+          }
+        },
+        "timeframe": {
+          "type": "object",
+          "properties": {
+            "type": {
+              "type": "string",
+              "enum": [
+                "absolute",
+                "relative"
+              ]
+            },
+            "start": {
+              "type": "string",
+              "description": "Start date (ISO format)"
+            },
+            "end": {
+              "type": "string",
+              "description": "End date (ISO format)"
+            },
+            "relative": {
+              "type": "object",
+              "properties": {
+                "unit": {
+                  "type": "string",
+                  "enum": [
+                    "hour",
+                    "day",
+                    "week",
+                    "month",
+                    "quarter",
+                    "year"
+                  ]
+                },
+                "value": {
+                  "type": "integer"
+                },
+                "direction": {
+                  "type": "string",
+                  "enum": [
+                    "past",
+                    "future",
+                    "current"
+                  ],
+                  "default": "past"
+                }
+              },
+              "required": [
+                "unit",
+                "value"
+              ],
+              "additionalProperties": false
+            },
+            "text": {
+              "type": "string",
+              "description": "Original timeframe text"
+            }
+          },
+          "required": [
+            "type",
+            "text"
+          ],
+          "additionalProperties": false
+        },
+        "ast": {
+          "description": "Generated ObjectQL AST"
+        },
+        "confidence": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1,
+          "description": "Overall confidence"
+        },
+        "ambiguities": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "type": {
+                "type": "string"
+              },
+              "description": {
+                "type": "string"
+              },
+              "suggestions": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              }
+            },
+            "required": [
+              "type",
+              "description"
+            ],
+            "additionalProperties": false
+          },
+          "description": "Detected ambiguities requiring clarification"
+        },
+        "alternatives": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "interpretation": {
+                "type": "string"
+              },
+              "confidence": {
+                "type": "number"
+              },
+              "ast": {}
+            },
+            "required": [
+              "interpretation",
+              "confidence"
+            ],
+            "additionalProperties": false
+          }
+        }
+      },
+      "required": [
+        "originalQuery",
+        "intent",
+        "intentConfidence",
+        "entities",
+        "confidence"
+      ],
+      "additionalProperties": false
+    }
+  },
+  "$schema": "http://json-schema.org/draft-07/schema#"
+}

package/json-schema/NLQRequest.json

@@ -0,0 +1,110 @@
+{
+  "$ref": "#/definitions/NLQRequest",
+  "definitions": {
+    "NLQRequest": {
+      "type": "object",
+      "properties": {
+        "query": {
+          "type": "string",
+          "description": "Natural language query"
+        },
+        "context": {
+          "type": "object",
+          "properties": {
+            "userId": {
+              "type": "string"
+            },
+            "userRole": {
+              "type": "string"
+            },
+            "currentObject": {
+              "type": "string",
+              "description": "Current object being viewed"
+            },
+            "currentRecordId": {
+              "type": "string",
+              "description": "Current record ID"
+            },
+            "conversationHistory": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "properties": {
+                  "query": {
+                    "type": "string"
+                  },
+                  "timestamp": {
+                    "type": "string"
+                  },
+                  "intent": {
+                    "type": "string",
+                    "enum": [
+                      "select",
+                      "aggregate",
+                      "filter",
+                      "sort",
+                      "compare",
+                      "trend",
+                      "insight",
+                      "create",
+                      "update",
+                      "delete"
+                    ]
+                  }
+                },
+                "required": [
+                  "query",
+                  "timestamp"
+                ],
+                "additionalProperties": false
+              }
+            },
+            "defaultLimit": {
+              "type": "integer",
+              "default": 100
+            },
+            "timezone": {
+              "type": "string",
+              "default": "UTC"
+            },
+            "locale": {
+              "type": "string",
+              "default": "en-US"
+            }
+          },
+          "additionalProperties": false
+        },
+        "includeAlternatives": {
+          "type": "boolean",
+          "default": false,
+          "description": "Include alternative interpretations"
+        },
+        "maxAlternatives": {
+          "type": "integer",
+          "default": 3
+        },
+        "minConfidence": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1,
+          "default": 0.5,
+          "description": "Minimum confidence threshold"
+        },
+        "executeQuery": {
+          "type": "boolean",
+          "default": false,
+          "description": "Execute query and return results"
+        },
+        "maxResults": {
+          "type": "integer",
+          "description": "Maximum results to return"
+        }
+      },
+      "required": [
+        "query"
+      ],
+      "additionalProperties": false
+    }
+  },
+  "$schema": "http://json-schema.org/draft-07/schema#"
+}