@defai.digital/contracts 13.0.3

package/src/routing/v1/decision.schema.json

@@ -0,0 +1,155 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://automatosx.dev/schemas/routing/v1/decision.schema.json",
+  "title": "Routing Decision Contract V1",
+  "description": "Defines the structure of routing decisions for model selection. Note: Cost-based routing is intentionally excluded by design.",
+  "type": "object",
+  "required": ["requestId", "input", "decision", "timestamp"],
+  "additionalProperties": false,
+  "properties": {
+    "requestId": {
+      "type": "string",
+      "format": "uuid",
+      "description": "Unique identifier for this routing request"
+    },
+    "input": {
+      "$ref": "#/$defs/RoutingInput",
+      "description": "Input context for the routing decision"
+    },
+    "decision": {
+      "$ref": "#/$defs/RoutingDecision",
+      "description": "The routing decision made"
+    },
+    "timestamp": {
+      "type": "string",
+      "format": "date-time",
+      "description": "When the decision was made"
+    },
+    "metadata": {
+      "type": "object",
+      "additionalProperties": true,
+      "description": "Optional metadata for the routing decision"
+    }
+  },
+  "$defs": {
+    "RoutingInput": {
+      "type": "object",
+      "required": ["taskType"],
+      "additionalProperties": false,
+      "properties": {
+        "taskType": {
+          "type": "string",
+          "enum": ["chat", "completion", "code", "analysis", "creative"],
+          "description": "Type of task to route"
+        },
+        "riskLevel": {
+          "type": "string",
+          "enum": ["low", "medium", "high"],
+          "default": "medium",
+          "description": "Risk tolerance level"
+        },
+        "requirements": {
+          "$ref": "#/$defs/ModelRequirements",
+          "description": "Specific model requirements"
+        },
+        "context": {
+          "type": "object",
+          "additionalProperties": true,
+          "description": "Additional context for routing"
+        }
+      }
+    },
+    "ModelRequirements": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "minContextLength": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Minimum context window required"
+        },
+        "maxLatencyMs": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Maximum acceptable latency in milliseconds"
+        },
+        "capabilities": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "enum": ["vision", "function_calling", "json_mode", "streaming"]
+          },
+          "description": "Required model capabilities"
+        },
+        "preferredProviders": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "List of preferred provider names"
+        },
+        "excludedModels": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Models to exclude from selection"
+        }
+      }
+    },
+    "RoutingConstraints": {
+      "type": "object",
+      "required": ["capabilitiesMet", "riskCompliant"],
+      "additionalProperties": false,
+      "properties": {
+        "capabilitiesMet": {
+          "type": "boolean",
+          "description": "Whether all required capabilities are met"
+        },
+        "riskCompliant": {
+          "type": "boolean",
+          "description": "Whether the selection complies with risk requirements"
+        }
+      }
+    },
+    "RoutingDecision": {
+      "type": "object",
+      "required": ["selectedModel", "provider", "reasoning", "fallbackModels", "constraints"],
+      "additionalProperties": false,
+      "properties": {
+        "selectedModel": {
+          "type": "string",
+          "minLength": 1,
+          "description": "The selected model identifier"
+        },
+        "provider": {
+          "type": "string",
+          "enum": ["anthropic", "openai", "google", "local"],
+          "description": "The provider for the selected model"
+        },
+        "isExperimental": {
+          "type": "boolean",
+          "default": false,
+          "description": "Whether the selected model is experimental"
+        },
+        "reasoning": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 512,
+          "description": "Human-readable explanation of the decision"
+        },
+        "fallbackModels": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Ordered list of fallback models if primary fails"
+        },
+        "constraints": {
+          "$ref": "#/$defs/RoutingConstraints",
+          "description": "Validation results for routing constraints"
+        }
+      }
+    }
+  }
+}

package/src/trace/v1/event.schema.json

@@ -0,0 +1,197 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://automatosx.dev/schemas/trace/v1/event.schema.json",
+  "title": "Trace Event Contract V1",
+  "description": "Defines the structure of trace events for execution tracing and replay",
+  "type": "object",
+  "required": ["traceId", "eventId", "type", "timestamp"],
+  "additionalProperties": false,
+  "properties": {
+    "traceId": {
+      "type": "string",
+      "format": "uuid",
+      "description": "Unique identifier for the trace (spans entire run)"
+    },
+    "eventId": {
+      "type": "string",
+      "format": "uuid",
+      "description": "Unique identifier for this event"
+    },
+    "parentEventId": {
+      "type": "string",
+      "format": "uuid",
+      "description": "ID of the parent event for hierarchical tracing"
+    },
+    "type": {
+      "type": "string",
+      "enum": [
+        "run.start",
+        "run.end",
+        "decision.routing",
+        "step.start",
+        "step.execute",
+        "step.end",
+        "tool.invoke",
+        "tool.result",
+        "memory.write",
+        "memory.read",
+        "error"
+      ],
+      "description": "Type of trace event"
+    },
+    "timestamp": {
+      "type": "string",
+      "format": "date-time",
+      "description": "When the event occurred"
+    },
+    "durationMs": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Duration of the operation in milliseconds"
+    },
+    "sequence": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Sequence number within the trace for ordering"
+    },
+    "payload": {
+      "type": "object",
+      "description": "Event-specific data"
+    },
+    "context": {
+      "$ref": "#/$defs/TraceContext",
+      "description": "Contextual information for the event"
+    },
+    "status": {
+      "type": "string",
+      "enum": ["pending", "running", "success", "failure", "skipped"],
+      "description": "Status of the traced operation"
+    }
+  },
+  "$defs": {
+    "TraceContext": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "workflowId": {
+          "type": "string",
+          "description": "ID of the workflow being executed"
+        },
+        "stepId": {
+          "type": "string",
+          "description": "ID of the current step"
+        },
+        "model": {
+          "type": "string",
+          "description": "Model being used"
+        },
+        "provider": {
+          "type": "string",
+          "description": "Provider for the model"
+        },
+        "userId": {
+          "type": "string",
+          "description": "User triggering the execution"
+        }
+      }
+    },
+    "RunStartPayload": {
+      "type": "object",
+      "required": ["workflowId"],
+      "additionalProperties": false,
+      "properties": {
+        "workflowId": {
+          "type": "string"
+        },
+        "workflowVersion": {
+          "type": "string"
+        },
+        "input": {
+          "type": "object"
+        }
+      }
+    },
+    "RunEndPayload": {
+      "type": "object",
+      "required": ["success"],
+      "additionalProperties": false,
+      "properties": {
+        "success": {
+          "type": "boolean"
+        },
+        "output": {
+          "type": "object"
+        },
+        "error": {
+          "type": "object"
+        },
+        "totalDurationMs": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "stepCount": {
+          "type": "integer",
+          "minimum": 0
+        }
+      }
+    },
+    "RoutingDecisionPayload": {
+      "type": "object",
+      "required": ["selectedModel", "provider", "reasoning"],
+      "additionalProperties": false,
+      "properties": {
+        "selectedModel": {
+          "type": "string"
+        },
+        "provider": {
+          "type": "string"
+        },
+        "reasoning": {
+          "type": "string"
+        }
+      }
+    },
+    "StepExecutePayload": {
+      "type": "object",
+      "required": ["stepId", "stepType"],
+      "additionalProperties": false,
+      "properties": {
+        "stepId": {
+          "type": "string"
+        },
+        "stepType": {
+          "type": "string"
+        },
+        "input": {
+          "type": "object"
+        },
+        "output": {
+          "type": "object"
+        },
+        "retryCount": {
+          "type": "integer",
+          "minimum": 0
+        }
+      }
+    },
+    "ErrorPayload": {
+      "type": "object",
+      "required": ["code", "message"],
+      "additionalProperties": false,
+      "properties": {
+        "code": {
+          "type": "string"
+        },
+        "message": {
+          "type": "string"
+        },
+        "stack": {
+          "type": "string"
+        },
+        "context": {
+          "type": "object"
+        }
+      }
+    }
+  }
+}

package/src/workflow/v1/workflow.schema.json

@@ -0,0 +1,142 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://automatosx.dev/schemas/workflow/v1/workflow.schema.json",
+  "title": "Workflow Contract V1",
+  "description": "Defines the structure of a workflow with steps, retry policies, and execution order",
+  "type": "object",
+  "required": ["workflowId", "version", "steps"],
+  "additionalProperties": false,
+  "properties": {
+    "workflowId": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]*$",
+      "minLength": 1,
+      "maxLength": 64,
+      "description": "Unique identifier for the workflow"
+    },
+    "version": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+$",
+      "description": "Semantic version of the workflow definition"
+    },
+    "name": {
+      "type": "string",
+      "maxLength": 128,
+      "description": "Human-readable name for the workflow"
+    },
+    "description": {
+      "type": "string",
+      "maxLength": 512,
+      "description": "Description of what this workflow accomplishes"
+    },
+    "steps": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "$ref": "#/$defs/WorkflowStep"
+      },
+      "description": "Ordered list of steps to execute"
+    },
+    "metadata": {
+      "type": "object",
+      "additionalProperties": true,
+      "description": "Optional metadata for the workflow"
+    }
+  },
+  "$defs": {
+    "WorkflowStep": {
+      "type": "object",
+      "required": ["stepId", "type"],
+      "additionalProperties": false,
+      "properties": {
+        "stepId": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9-]*$",
+          "minLength": 1,
+          "maxLength": 64,
+          "description": "Unique identifier for this step within the workflow"
+        },
+        "type": {
+          "type": "string",
+          "enum": ["prompt", "tool", "conditional", "loop", "parallel"],
+          "description": "Type of step execution"
+        },
+        "name": {
+          "type": "string",
+          "maxLength": 128,
+          "description": "Human-readable name for the step"
+        },
+        "inputSchema": {
+          "$ref": "#/$defs/SchemaReference",
+          "description": "JSON Schema reference for step input validation"
+        },
+        "outputSchema": {
+          "$ref": "#/$defs/SchemaReference",
+          "description": "JSON Schema reference for step output validation"
+        },
+        "retryPolicy": {
+          "$ref": "#/$defs/RetryPolicy",
+          "description": "Retry behavior for this step"
+        },
+        "timeout": {
+          "type": "integer",
+          "minimum": 1000,
+          "maximum": 3600000,
+          "description": "Timeout in milliseconds (1s to 1h)"
+        },
+        "config": {
+          "type": "object",
+          "additionalProperties": true,
+          "description": "Step-type-specific configuration"
+        }
+      }
+    },
+    "RetryPolicy": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "maxAttempts": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 10,
+          "default": 1,
+          "description": "Maximum number of retry attempts"
+        },
+        "backoffMs": {
+          "type": "integer",
+          "minimum": 100,
+          "maximum": 60000,
+          "default": 1000,
+          "description": "Initial backoff delay in milliseconds"
+        },
+        "backoffMultiplier": {
+          "type": "number",
+          "minimum": 1,
+          "maximum": 5,
+          "default": 2,
+          "description": "Multiplier for exponential backoff"
+        },
+        "retryOn": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "enum": ["timeout", "rate_limit", "server_error", "network_error"]
+          },
+          "description": "Error types that trigger retry"
+        }
+      }
+    },
+    "SchemaReference": {
+      "type": "object",
+      "required": ["$ref"],
+      "additionalProperties": false,
+      "properties": {
+        "$ref": {
+          "type": "string",
+          "format": "uri-reference",
+          "description": "URI reference to the schema"
+        }
+      }
+    }
+  }
+}