@objectstack/spec 0.3.0 → 0.3.1

package/json-schema/ai/PredictiveModel.json

@@ -0,0 +1,445 @@
+{
+  "$ref": "#/definitions/PredictiveModel",
+  "definitions": {
+    "PredictiveModel": {
+      "type": "object",
+      "properties": {
+        "name": {
+          "type": "string",
+          "pattern": "^[a-z_][a-z0-9_]*$",
+          "description": "Model unique identifier (snake_case)"
+        },
+        "label": {
+          "type": "string",
+          "description": "Model display name"
+        },
+        "description": {
+          "type": "string"
+        },
+        "type": {
+          "type": "string",
+          "enum": [
+            "classification",
+            "regression",
+            "clustering",
+            "forecasting",
+            "anomaly_detection",
+            "recommendation",
+            "ranking"
+          ]
+        },
+        "algorithm": {
+          "type": "string",
+          "description": "Specific algorithm (e.g., \"random_forest\", \"xgboost\", \"lstm\")"
+        },
+        "objectName": {
+          "type": "string",
+          "description": "Target object for predictions"
+        },
+        "target": {
+          "type": "string",
+          "description": "Target field to predict"
+        },
+        "targetType": {
+          "type": "string",
+          "enum": [
+            "numeric",
+            "categorical",
+            "binary"
+          ],
+          "description": "Target field type"
+        },
+        "features": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "name": {
+                "type": "string",
+                "pattern": "^[a-z_][a-z0-9_]*$",
+                "description": "Feature name (snake_case)"
+              },
+              "label": {
+                "type": "string",
+                "description": "Human-readable label"
+              },
+              "field": {
+                "type": "string",
+                "description": "Source field name"
+              },
+              "object": {
+                "type": "string",
+                "description": "Source object (if different from target)"
+              },
+              "dataType": {
+                "type": "string",
+                "enum": [
+                  "numeric",
+                  "categorical",
+                  "text",
+                  "datetime",
+                  "boolean"
+                ],
+                "description": "Feature data type"
+              },
+              "transformation": {
+                "type": "string",
+                "enum": [
+                  "none",
+                  "normalize",
+                  "standardize",
+                  "one_hot_encode",
+                  "label_encode",
+                  "log_transform",
+                  "binning",
+                  "embedding"
+                ],
+                "default": "none"
+              },
+              "required": {
+                "type": "boolean",
+                "default": true
+              },
+              "defaultValue": {},
+              "description": {
+                "type": "string"
+              },
+              "importance": {
+                "type": "number",
+                "description": "Feature importance score (0-1)"
+              }
+            },
+            "required": [
+              "name",
+              "field",
+              "dataType"
+            ],
+            "additionalProperties": false
+          },
+          "description": "Input features for the model"
+        },
+        "hyperparameters": {
+          "type": "object",
+          "properties": {
+            "learningRate": {
+              "type": "number",
+              "description": "Learning rate for training"
+            },
+            "epochs": {
+              "type": "integer",
+              "description": "Number of training epochs"
+            },
+            "batchSize": {
+              "type": "integer",
+              "description": "Training batch size"
+            },
+            "maxDepth": {
+              "type": "integer",
+              "description": "Maximum tree depth"
+            },
+            "numTrees": {
+              "type": "integer",
+              "description": "Number of trees in ensemble"
+            },
+            "minSamplesSplit": {
+              "type": "integer",
+              "description": "Minimum samples to split node"
+            },
+            "minSamplesLeaf": {
+              "type": "integer",
+              "description": "Minimum samples in leaf node"
+            },
+            "hiddenLayers": {
+              "type": "array",
+              "items": {
+                "type": "integer"
+              },
+              "description": "Hidden layer sizes"
+            },
+            "activation": {
+              "type": "string",
+              "description": "Activation function"
+            },
+            "dropout": {
+              "type": "number",
+              "description": "Dropout rate"
+            },
+            "l1Regularization": {
+              "type": "number",
+              "description": "L1 regularization strength"
+            },
+            "l2Regularization": {
+              "type": "number",
+              "description": "L2 regularization strength"
+            },
+            "numClusters": {
+              "type": "integer",
+              "description": "Number of clusters (k-means, etc.)"
+            },
+            "seasonalPeriod": {
+              "type": "integer",
+              "description": "Seasonal period for time series"
+            },
+            "forecastHorizon": {
+              "type": "integer",
+              "description": "Number of periods to forecast"
+            },
+            "custom": {
+              "type": "object",
+              "additionalProperties": {},
+              "description": "Algorithm-specific parameters"
+            }
+          },
+          "additionalProperties": false
+        },
+        "training": {
+          "type": "object",
+          "properties": {
+            "trainingDataRatio": {
+              "type": "number",
+              "minimum": 0,
+              "maximum": 1,
+              "default": 0.8,
+              "description": "Proportion of data for training"
+            },
+            "validationDataRatio": {
+              "type": "number",
+              "minimum": 0,
+              "maximum": 1,
+              "default": 0.1,
+              "description": "Proportion for validation"
+            },
+            "testDataRatio": {
+              "type": "number",
+              "minimum": 0,
+              "maximum": 1,
+              "default": 0.1,
+              "description": "Proportion for testing"
+            },
+            "dataFilter": {
+              "type": "string",
+              "description": "Formula to filter training data"
+            },
+            "minRecords": {
+              "type": "integer",
+              "default": 100,
+              "description": "Minimum records required"
+            },
+            "maxRecords": {
+              "type": "integer",
+              "description": "Maximum records to use"
+            },
+            "strategy": {
+              "type": "string",
+              "enum": [
+                "full",
+                "incremental",
+                "online",
+                "transfer_learning"
+              ],
+              "default": "full"
+            },
+            "crossValidation": {
+              "type": "boolean",
+              "default": true
+            },
+            "folds": {
+              "type": "integer",
+              "minimum": 2,
+              "maximum": 10,
+              "default": 5,
+              "description": "Cross-validation folds"
+            },
+            "earlyStoppingEnabled": {
+              "type": "boolean",
+              "default": true
+            },
+            "earlyStoppingPatience": {
+              "type": "integer",
+              "default": 10,
+              "description": "Epochs without improvement before stopping"
+            },
+            "maxTrainingTime": {
+              "type": "number",
+              "description": "Maximum training time in seconds"
+            },
+            "gpuEnabled": {
+              "type": "boolean",
+              "default": false
+            },
+            "randomSeed": {
+              "type": "integer",
+              "description": "Random seed for reproducibility"
+            }
+          },
+          "additionalProperties": false
+        },
+        "metrics": {
+          "type": "object",
+          "properties": {
+            "accuracy": {
+              "type": "number"
+            },
+            "precision": {
+              "type": "number"
+            },
+            "recall": {
+              "type": "number"
+            },
+            "f1Score": {
+              "type": "number"
+            },
+            "auc": {
+              "type": "number",
+              "description": "Area Under ROC Curve"
+            },
+            "mse": {
+              "type": "number",
+              "description": "Mean Squared Error"
+            },
+            "rmse": {
+              "type": "number",
+              "description": "Root Mean Squared Error"
+            },
+            "mae": {
+              "type": "number",
+              "description": "Mean Absolute Error"
+            },
+            "r2Score": {
+              "type": "number",
+              "description": "R-squared score"
+            },
+            "silhouetteScore": {
+              "type": "number"
+            },
+            "daviesBouldinIndex": {
+              "type": "number"
+            },
+            "mape": {
+              "type": "number",
+              "description": "Mean Absolute Percentage Error"
+            },
+            "smape": {
+              "type": "number",
+              "description": "Symmetric MAPE"
+            },
+            "custom": {
+              "type": "object",
+              "additionalProperties": {
+                "type": "number"
+              }
+            }
+          },
+          "additionalProperties": false,
+          "description": "Evaluation metrics from last training"
+        },
+        "deploymentStatus": {
+          "type": "string",
+          "enum": [
+            "draft",
+            "training",
+            "trained",
+            "deployed",
+            "deprecated"
+          ],
+          "default": "draft"
+        },
+        "version": {
+          "type": "string",
+          "default": "1.0.0"
+        },
+        "predictionField": {
+          "type": "string",
+          "description": "Field to store predictions"
+        },
+        "confidenceField": {
+          "type": "string",
+          "description": "Field to store confidence scores"
+        },
+        "updateTrigger": {
+          "type": "string",
+          "enum": [
+            "on_create",
+            "on_update",
+            "manual",
+            "scheduled"
+          ],
+          "default": "on_create"
+        },
+        "autoRetrain": {
+          "type": "boolean",
+          "default": false
+        },
+        "retrainSchedule": {
+          "type": "string",
+          "description": "Cron expression for auto-retraining"
+        },
+        "retrainThreshold": {
+          "type": "number",
+          "description": "Performance threshold to trigger retraining"
+        },
+        "enableExplainability": {
+          "type": "boolean",
+          "default": false,
+          "description": "Generate feature importance & explanations"
+        },
+        "enableMonitoring": {
+          "type": "boolean",
+          "default": true
+        },
+        "alertOnDrift": {
+          "type": "boolean",
+          "default": true,
+          "description": "Alert when model drift is detected"
+        },
+        "active": {
+          "type": "boolean",
+          "default": true
+        },
+        "owner": {
+          "type": "string",
+          "description": "User ID of model owner"
+        },
+        "permissions": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "User/group IDs with access"
+        },
+        "tags": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "category": {
+          "type": "string",
+          "description": "Model category (e.g., \"sales\", \"marketing\", \"operations\")"
+        },
+        "lastTrainedAt": {
+          "type": "string",
+          "description": "ISO timestamp"
+        },
+        "createdAt": {
+          "type": "string",
+          "description": "ISO timestamp"
+        },
+        "updatedAt": {
+          "type": "string",
+          "description": "ISO timestamp"
+        }
+      },
+      "required": [
+        "name",
+        "label",
+        "type",
+        "objectName",
+        "target",
+        "features"
+      ],
+      "additionalProperties": false
+    }
+  },
+  "$schema": "http://json-schema.org/draft-07/schema#"
+}

package/json-schema/ai/PredictiveModelType.json

@@ -0,0 +1,18 @@
+{
+  "$ref": "#/definitions/PredictiveModelType",
+  "definitions": {
+    "PredictiveModelType": {
+      "type": "string",
+      "enum": [
+        "classification",
+        "regression",
+        "clustering",
+        "forecasting",
+        "anomaly_detection",
+        "recommendation",
+        "ranking"
+      ]
+    }
+  },
+  "$schema": "http://json-schema.org/draft-07/schema#"
+}

package/json-schema/ai/TokenBudgetConfig.json

@@ -0,0 +1,92 @@
+{
+  "$ref": "#/definitions/TokenBudgetConfig",
+  "definitions": {
+    "TokenBudgetConfig": {
+      "type": "object",
+      "properties": {
+        "maxTokens": {
+          "type": "integer",
+          "exclusiveMinimum": 0,
+          "description": "Maximum total tokens"
+        },
+        "maxPromptTokens": {
+          "type": "integer",
+          "exclusiveMinimum": 0,
+          "description": "Max tokens for prompt"
+        },
+        "maxCompletionTokens": {
+          "type": "integer",
+          "exclusiveMinimum": 0,
+          "description": "Max tokens for completion"
+        },
+        "reserveTokens": {
+          "type": "integer",
+          "minimum": 0,
+          "default": 500,
+          "description": "Reserve tokens for system messages"
+        },
+        "bufferPercentage": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1,
+          "default": 0.1,
+          "description": "Buffer percentage (0.1 = 10%)"
+        },
+        "strategy": {
+          "type": "string",
+          "enum": [
+            "fifo",
+            "importance",
+            "semantic",
+            "sliding_window",
+            "summary"
+          ],
+          "default": "sliding_window"
+        },
+        "slidingWindowSize": {
+          "type": "integer",
+          "exclusiveMinimum": 0,
+          "description": "Number of recent messages to keep"
+        },
+        "minImportanceScore": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1,
+          "description": "Minimum importance to keep"
+        },
+        "semanticThreshold": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1,
+          "description": "Semantic similarity threshold"
+        },
+        "enableSummarization": {
+          "type": "boolean",
+          "default": false,
+          "description": "Enable context summarization"
+        },
+        "summarizationThreshold": {
+          "type": "integer",
+          "exclusiveMinimum": 0,
+          "description": "Trigger summarization at N tokens"
+        },
+        "summaryModel": {
+          "type": "string",
+          "description": "Model ID for summarization"
+        },
+        "warnThreshold": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1,
+          "default": 0.8,
+          "description": "Warn at % of budget (0.8 = 80%)"
+        }
+      },
+      "required": [
+        "maxTokens"
+      ],
+      "additionalProperties": false
+    }
+  },
+  "$schema": "http://json-schema.org/draft-07/schema#"
+}

package/json-schema/ai/TokenBudgetStrategy.json

@@ -0,0 +1,16 @@
+{
+  "$ref": "#/definitions/TokenBudgetStrategy",
+  "definitions": {
+    "TokenBudgetStrategy": {
+      "type": "string",
+      "enum": [
+        "fifo",
+        "importance",
+        "semantic",
+        "sliding_window",
+        "summary"
+      ]
+    }
+  },
+  "$schema": "http://json-schema.org/draft-07/schema#"
+}

package/json-schema/ai/TokenUsageStats.json

@@ -0,0 +1,66 @@
+{
+  "$ref": "#/definitions/TokenUsageStats",
+  "definitions": {
+    "TokenUsageStats": {
+      "type": "object",
+      "properties": {
+        "promptTokens": {
+          "type": "integer",
+          "minimum": 0,
+          "default": 0
+        },
+        "completionTokens": {
+          "type": "integer",
+          "minimum": 0,
+          "default": 0
+        },
+        "totalTokens": {
+          "type": "integer",
+          "minimum": 0,
+          "default": 0
+        },
+        "budgetLimit": {
+          "type": "integer",
+          "exclusiveMinimum": 0
+        },
+        "budgetUsed": {
+          "type": "integer",
+          "minimum": 0,
+          "default": 0
+        },
+        "budgetRemaining": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "budgetPercentage": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1,
+          "description": "Usage as percentage of budget"
+        },
+        "messageCount": {
+          "type": "integer",
+          "minimum": 0,
+          "default": 0
+        },
+        "prunedMessageCount": {
+          "type": "integer",
+          "minimum": 0,
+          "default": 0
+        },
+        "summarizedMessageCount": {
+          "type": "integer",
+          "minimum": 0,
+          "default": 0
+        }
+      },
+      "required": [
+        "budgetLimit",
+        "budgetRemaining",
+        "budgetPercentage"
+      ],
+      "additionalProperties": false
+    }
+  },
+  "$schema": "http://json-schema.org/draft-07/schema#"
+}

package/json-schema/ai/ToolCall.json

@@ -0,0 +1,49 @@
+{
+  "$ref": "#/definitions/ToolCall",
+  "definitions": {
+    "ToolCall": {
+      "type": "object",
+      "properties": {
+        "id": {
+          "type": "string",
+          "description": "Tool call ID"
+        },
+        "type": {
+          "type": "string",
+          "enum": [
+            "function"
+          ],
+          "default": "function"
+        },
+        "function": {
+          "type": "object",
+          "properties": {
+            "name": {
+              "type": "string",
+              "description": "Function name"
+            },
+            "arguments": {
+              "type": "string",
+              "description": "JSON string of function arguments"
+            },
+            "result": {
+              "type": "string",
+              "description": "Function execution result"
+            }
+          },
+          "required": [
+            "name",
+            "arguments"
+          ],
+          "additionalProperties": false
+        }
+      },
+      "required": [
+        "id",
+        "function"
+      ],
+      "additionalProperties": false
+    }
+  },
+  "$schema": "http://json-schema.org/draft-07/schema#"
+}