@objectstack/spec 0.3.0 → 0.3.1

package/json-schema/ai/CostReport.json

@@ -0,0 +1,964 @@
+{
+  "$ref": "#/definitions/CostReport",
+  "definitions": {
+    "CostReport": {
+      "type": "object",
+      "properties": {
+        "id": {
+          "type": "string"
+        },
+        "name": {
+          "type": "string"
+        },
+        "generatedAt": {
+          "type": "string",
+          "description": "ISO 8601 timestamp"
+        },
+        "periodStart": {
+          "type": "string",
+          "description": "ISO 8601 timestamp"
+        },
+        "periodEnd": {
+          "type": "string",
+          "description": "ISO 8601 timestamp"
+        },
+        "period": {
+          "type": "string",
+          "enum": [
+            "hourly",
+            "daily",
+            "weekly",
+            "monthly",
+            "quarterly",
+            "yearly",
+            "custom"
+          ]
+        },
+        "analytics": {
+          "type": "object",
+          "properties": {
+            "periodStart": {
+              "type": "string",
+              "description": "ISO 8601 timestamp"
+            },
+            "periodEnd": {
+              "type": "string",
+              "description": "ISO 8601 timestamp"
+            },
+            "totalCost": {
+              "type": "number",
+              "minimum": 0
+            },
+            "totalRequests": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "totalTokens": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "currency": {
+              "type": "string",
+              "default": "USD"
+            },
+            "averageCostPerRequest": {
+              "type": "number",
+              "minimum": 0
+            },
+            "averageCostPerToken": {
+              "type": "number",
+              "minimum": 0
+            },
+            "averageRequestsPerDay": {
+              "type": "number",
+              "minimum": 0
+            },
+            "costTrend": {
+              "type": "string",
+              "enum": [
+                "increasing",
+                "decreasing",
+                "stable"
+              ]
+            },
+            "trendPercentage": {
+              "type": "number",
+              "description": "% change vs previous period"
+            },
+            "byModel": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "properties": {
+                  "dimension": {
+                    "type": "string",
+                    "enum": [
+                      "model",
+                      "provider",
+                      "user",
+                      "agent",
+                      "object",
+                      "operation",
+                      "date",
+                      "hour",
+                      "tag"
+                    ]
+                  },
+                  "value": {
+                    "type": "string",
+                    "description": "Dimension value (e.g., model ID, user ID)"
+                  },
+                  "totalCost": {
+                    "type": "number",
+                    "minimum": 0
+                  },
+                  "requestCount": {
+                    "type": "integer",
+                    "minimum": 0
+                  },
+                  "totalTokens": {
+                    "type": "integer",
+                    "minimum": 0
+                  },
+                  "percentageOfTotal": {
+                    "type": "number",
+                    "minimum": 0,
+                    "maximum": 1
+                  },
+                  "periodStart": {
+                    "type": "string"
+                  },
+                  "periodEnd": {
+                    "type": "string"
+                  }
+                },
+                "required": [
+                  "dimension",
+                  "value",
+                  "totalCost",
+                  "requestCount",
+                  "percentageOfTotal"
+                ],
+                "additionalProperties": false
+              }
+            },
+            "byProvider": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "properties": {
+                  "dimension": {
+                    "type": "string",
+                    "enum": [
+                      "model",
+                      "provider",
+                      "user",
+                      "agent",
+                      "object",
+                      "operation",
+                      "date",
+                      "hour",
+                      "tag"
+                    ]
+                  },
+                  "value": {
+                    "type": "string",
+                    "description": "Dimension value (e.g., model ID, user ID)"
+                  },
+                  "totalCost": {
+                    "type": "number",
+                    "minimum": 0
+                  },
+                  "requestCount": {
+                    "type": "integer",
+                    "minimum": 0
+                  },
+                  "totalTokens": {
+                    "type": "integer",
+                    "minimum": 0
+                  },
+                  "percentageOfTotal": {
+                    "type": "number",
+                    "minimum": 0,
+                    "maximum": 1
+                  },
+                  "periodStart": {
+                    "type": "string"
+                  },
+                  "periodEnd": {
+                    "type": "string"
+                  }
+                },
+                "required": [
+                  "dimension",
+                  "value",
+                  "totalCost",
+                  "requestCount",
+                  "percentageOfTotal"
+                ],
+                "additionalProperties": false
+              }
+            },
+            "byUser": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "properties": {
+                  "dimension": {
+                    "type": "string",
+                    "enum": [
+                      "model",
+                      "provider",
+                      "user",
+                      "agent",
+                      "object",
+                      "operation",
+                      "date",
+                      "hour",
+                      "tag"
+                    ]
+                  },
+                  "value": {
+                    "type": "string",
+                    "description": "Dimension value (e.g., model ID, user ID)"
+                  },
+                  "totalCost": {
+                    "type": "number",
+                    "minimum": 0
+                  },
+                  "requestCount": {
+                    "type": "integer",
+                    "minimum": 0
+                  },
+                  "totalTokens": {
+                    "type": "integer",
+                    "minimum": 0
+                  },
+                  "percentageOfTotal": {
+                    "type": "number",
+                    "minimum": 0,
+                    "maximum": 1
+                  },
+                  "periodStart": {
+                    "type": "string"
+                  },
+                  "periodEnd": {
+                    "type": "string"
+                  }
+                },
+                "required": [
+                  "dimension",
+                  "value",
+                  "totalCost",
+                  "requestCount",
+                  "percentageOfTotal"
+                ],
+                "additionalProperties": false
+              }
+            },
+            "byAgent": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "properties": {
+                  "dimension": {
+                    "type": "string",
+                    "enum": [
+                      "model",
+                      "provider",
+                      "user",
+                      "agent",
+                      "object",
+                      "operation",
+                      "date",
+                      "hour",
+                      "tag"
+                    ]
+                  },
+                  "value": {
+                    "type": "string",
+                    "description": "Dimension value (e.g., model ID, user ID)"
+                  },
+                  "totalCost": {
+                    "type": "number",
+                    "minimum": 0
+                  },
+                  "requestCount": {
+                    "type": "integer",
+                    "minimum": 0
+                  },
+                  "totalTokens": {
+                    "type": "integer",
+                    "minimum": 0
+                  },
+                  "percentageOfTotal": {
+                    "type": "number",
+                    "minimum": 0,
+                    "maximum": 1
+                  },
+                  "periodStart": {
+                    "type": "string"
+                  },
+                  "periodEnd": {
+                    "type": "string"
+                  }
+                },
+                "required": [
+                  "dimension",
+                  "value",
+                  "totalCost",
+                  "requestCount",
+                  "percentageOfTotal"
+                ],
+                "additionalProperties": false
+              }
+            },
+            "byOperation": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "properties": {
+                  "dimension": {
+                    "type": "string",
+                    "enum": [
+                      "model",
+                      "provider",
+                      "user",
+                      "agent",
+                      "object",
+                      "operation",
+                      "date",
+                      "hour",
+                      "tag"
+                    ]
+                  },
+                  "value": {
+                    "type": "string",
+                    "description": "Dimension value (e.g., model ID, user ID)"
+                  },
+                  "totalCost": {
+                    "type": "number",
+                    "minimum": 0
+                  },
+                  "requestCount": {
+                    "type": "integer",
+                    "minimum": 0
+                  },
+                  "totalTokens": {
+                    "type": "integer",
+                    "minimum": 0
+                  },
+                  "percentageOfTotal": {
+                    "type": "number",
+                    "minimum": 0,
+                    "maximum": 1
+                  },
+                  "periodStart": {
+                    "type": "string"
+                  },
+                  "periodEnd": {
+                    "type": "string"
+                  }
+                },
+                "required": [
+                  "dimension",
+                  "value",
+                  "totalCost",
+                  "requestCount",
+                  "percentageOfTotal"
+                ],
+                "additionalProperties": false
+              }
+            },
+            "byDate": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "properties": {
+                  "dimension": {
+                    "type": "string",
+                    "enum": [
+                      "model",
+                      "provider",
+                      "user",
+                      "agent",
+                      "object",
+                      "operation",
+                      "date",
+                      "hour",
+                      "tag"
+                    ]
+                  },
+                  "value": {
+                    "type": "string",
+                    "description": "Dimension value (e.g., model ID, user ID)"
+                  },
+                  "totalCost": {
+                    "type": "number",
+                    "minimum": 0
+                  },
+                  "requestCount": {
+                    "type": "integer",
+                    "minimum": 0
+                  },
+                  "totalTokens": {
+                    "type": "integer",
+                    "minimum": 0
+                  },
+                  "percentageOfTotal": {
+                    "type": "number",
+                    "minimum": 0,
+                    "maximum": 1
+                  },
+                  "periodStart": {
+                    "type": "string"
+                  },
+                  "periodEnd": {
+                    "type": "string"
+                  }
+                },
+                "required": [
+                  "dimension",
+                  "value",
+                  "totalCost",
+                  "requestCount",
+                  "percentageOfTotal"
+                ],
+                "additionalProperties": false
+              }
+            },
+            "topModels": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "properties": {
+                  "dimension": {
+                    "type": "string",
+                    "enum": [
+                      "model",
+                      "provider",
+                      "user",
+                      "agent",
+                      "object",
+                      "operation",
+                      "date",
+                      "hour",
+                      "tag"
+                    ]
+                  },
+                  "value": {
+                    "type": "string",
+                    "description": "Dimension value (e.g., model ID, user ID)"
+                  },
+                  "totalCost": {
+                    "type": "number",
+                    "minimum": 0
+                  },
+                  "requestCount": {
+                    "type": "integer",
+                    "minimum": 0
+                  },
+                  "totalTokens": {
+                    "type": "integer",
+                    "minimum": 0
+                  },
+                  "percentageOfTotal": {
+                    "type": "number",
+                    "minimum": 0,
+                    "maximum": 1
+                  },
+                  "periodStart": {
+                    "type": "string"
+                  },
+                  "periodEnd": {
+                    "type": "string"
+                  }
+                },
+                "required": [
+                  "dimension",
+                  "value",
+                  "totalCost",
+                  "requestCount",
+                  "percentageOfTotal"
+                ],
+                "additionalProperties": false
+              }
+            },
+            "topUsers": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "properties": {
+                  "dimension": {
+                    "type": "string",
+                    "enum": [
+                      "model",
+                      "provider",
+                      "user",
+                      "agent",
+                      "object",
+                      "operation",
+                      "date",
+                      "hour",
+                      "tag"
+                    ]
+                  },
+                  "value": {
+                    "type": "string",
+                    "description": "Dimension value (e.g., model ID, user ID)"
+                  },
+                  "totalCost": {
+                    "type": "number",
+                    "minimum": 0
+                  },
+                  "requestCount": {
+                    "type": "integer",
+                    "minimum": 0
+                  },
+                  "totalTokens": {
+                    "type": "integer",
+                    "minimum": 0
+                  },
+                  "percentageOfTotal": {
+                    "type": "number",
+                    "minimum": 0,
+                    "maximum": 1
+                  },
+                  "periodStart": {
+                    "type": "string"
+                  },
+                  "periodEnd": {
+                    "type": "string"
+                  }
+                },
+                "required": [
+                  "dimension",
+                  "value",
+                  "totalCost",
+                  "requestCount",
+                  "percentageOfTotal"
+                ],
+                "additionalProperties": false
+              }
+            },
+            "topAgents": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "properties": {
+                  "dimension": {
+                    "type": "string",
+                    "enum": [
+                      "model",
+                      "provider",
+                      "user",
+                      "agent",
+                      "object",
+                      "operation",
+                      "date",
+                      "hour",
+                      "tag"
+                    ]
+                  },
+                  "value": {
+                    "type": "string",
+                    "description": "Dimension value (e.g., model ID, user ID)"
+                  },
+                  "totalCost": {
+                    "type": "number",
+                    "minimum": 0
+                  },
+                  "requestCount": {
+                    "type": "integer",
+                    "minimum": 0
+                  },
+                  "totalTokens": {
+                    "type": "integer",
+                    "minimum": 0
+                  },
+                  "percentageOfTotal": {
+                    "type": "number",
+                    "minimum": 0,
+                    "maximum": 1
+                  },
+                  "periodStart": {
+                    "type": "string"
+                  },
+                  "periodEnd": {
+                    "type": "string"
+                  }
+                },
+                "required": [
+                  "dimension",
+                  "value",
+                  "totalCost",
+                  "requestCount",
+                  "percentageOfTotal"
+                ],
+                "additionalProperties": false
+              }
+            },
+            "tokensPerDollar": {
+              "type": "number",
+              "minimum": 0
+            },
+            "requestsPerDollar": {
+              "type": "number",
+              "minimum": 0
+            }
+          },
+          "required": [
+            "periodStart",
+            "periodEnd",
+            "totalCost",
+            "totalRequests",
+            "averageCostPerRequest",
+            "averageRequestsPerDay"
+          ],
+          "additionalProperties": false
+        },
+        "budgets": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "budgetId": {
+                "type": "string"
+              },
+              "type": {
+                "type": "string",
+                "enum": [
+                  "global",
+                  "user",
+                  "agent",
+                  "object",
+                  "project",
+                  "department"
+                ]
+              },
+              "scope": {
+                "type": "string"
+              },
+              "periodStart": {
+                "type": "string",
+                "description": "ISO 8601 timestamp"
+              },
+              "periodEnd": {
+                "type": "string",
+                "description": "ISO 8601 timestamp"
+              },
+              "currentCost": {
+                "type": "number",
+                "minimum": 0,
+                "default": 0
+              },
+              "maxCost": {
+                "type": "number",
+                "minimum": 0
+              },
+              "currency": {
+                "type": "string",
+                "default": "USD"
+              },
+              "percentageUsed": {
+                "type": "number",
+                "minimum": 0,
+                "description": "Usage as percentage (can exceed 1.0 if over budget)"
+              },
+              "remainingCost": {
+                "type": "number",
+                "description": "Remaining budget (can be negative if exceeded)"
+              },
+              "isExceeded": {
+                "type": "boolean",
+                "default": false
+              },
+              "isWarning": {
+                "type": "boolean",
+                "default": false
+              },
+              "projectedCost": {
+                "type": "number",
+                "minimum": 0,
+                "description": "Projected cost for period"
+              },
+              "projectedOverage": {
+                "type": "number",
+                "minimum": 0,
+                "description": "Projected overage"
+              },
+              "lastUpdated": {
+                "type": "string",
+                "description": "ISO 8601 timestamp"
+              }
+            },
+            "required": [
+              "budgetId",
+              "type",
+              "periodStart",
+              "periodEnd",
+              "maxCost",
+              "percentageUsed",
+              "remainingCost",
+              "lastUpdated"
+            ],
+            "additionalProperties": false
+          }
+        },
+        "alerts": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "id": {
+                "type": "string"
+              },
+              "timestamp": {
+                "type": "string",
+                "description": "ISO 8601 timestamp"
+              },
+              "type": {
+                "type": "string",
+                "enum": [
+                  "threshold_warning",
+                  "threshold_critical",
+                  "limit_exceeded",
+                  "anomaly_detected",
+                  "projection_exceeded"
+                ]
+              },
+              "severity": {
+                "type": "string",
+                "enum": [
+                  "info",
+                  "warning",
+                  "critical"
+                ]
+              },
+              "budgetId": {
+                "type": "string"
+              },
+              "budgetType": {
+                "type": "string",
+                "enum": [
+                  "global",
+                  "user",
+                  "agent",
+                  "object",
+                  "project",
+                  "department"
+                ]
+              },
+              "scope": {
+                "type": "string"
+              },
+              "message": {
+                "type": "string",
+                "description": "Alert message"
+              },
+              "currentCost": {
+                "type": "number",
+                "minimum": 0
+              },
+              "maxCost": {
+                "type": "number",
+                "minimum": 0
+              },
+              "threshold": {
+                "type": "number",
+                "minimum": 0,
+                "maximum": 1
+              },
+              "currency": {
+                "type": "string",
+                "default": "USD"
+              },
+              "recommendations": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "acknowledged": {
+                "type": "boolean",
+                "default": false
+              },
+              "acknowledgedBy": {
+                "type": "string"
+              },
+              "acknowledgedAt": {
+                "type": "string"
+              },
+              "resolved": {
+                "type": "boolean",
+                "default": false
+              },
+              "metadata": {
+                "type": "object",
+                "additionalProperties": {}
+              }
+            },
+            "required": [
+              "id",
+              "timestamp",
+              "type",
+              "severity",
+              "message",
+              "currentCost"
+            ],
+            "additionalProperties": false
+          }
+        },
+        "activeAlertCount": {
+          "type": "integer",
+          "minimum": 0,
+          "default": 0
+        },
+        "recommendations": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "id": {
+                "type": "string"
+              },
+              "type": {
+                "type": "string",
+                "enum": [
+                  "switch_model",
+                  "reduce_tokens",
+                  "batch_requests",
+                  "cache_results",
+                  "adjust_parameters",
+                  "limit_usage"
+                ]
+              },
+              "title": {
+                "type": "string"
+              },
+              "description": {
+                "type": "string"
+              },
+              "estimatedSavings": {
+                "type": "number",
+                "minimum": 0
+              },
+              "savingsPercentage": {
+                "type": "number",
+                "minimum": 0,
+                "maximum": 1
+              },
+              "priority": {
+                "type": "string",
+                "enum": [
+                  "low",
+                  "medium",
+                  "high"
+                ]
+              },
+              "effort": {
+                "type": "string",
+                "enum": [
+                  "low",
+                  "medium",
+                  "high"
+                ]
+              },
+              "actionable": {
+                "type": "boolean",
+                "default": true
+              },
+              "actionSteps": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "targetModel": {
+                "type": "string"
+              },
+              "alternativeModel": {
+                "type": "string"
+              },
+              "affectedUsers": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "status": {
+                "type": "string",
+                "enum": [
+                  "pending",
+                  "accepted",
+                  "rejected",
+                  "implemented"
+                ],
+                "default": "pending"
+              },
+              "implementedAt": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "id",
+              "type",
+              "title",
+              "description",
+              "priority",
+              "effort"
+            ],
+            "additionalProperties": false
+          }
+        },
+        "previousPeriodCost": {
+          "type": "number",
+          "minimum": 0
+        },
+        "costChange": {
+          "type": "number",
+          "description": "Change vs previous period"
+        },
+        "costChangePercentage": {
+          "type": "number"
+        },
+        "forecastedCost": {
+          "type": "number",
+          "minimum": 0
+        },
+        "forecastedBudgetStatus": {
+          "type": "string",
+          "enum": [
+            "under",
+            "at",
+            "over"
+          ]
+        },
+        "format": {
+          "type": "string",
+          "enum": [
+            "summary",
+            "detailed",
+            "executive"
+          ],
+          "default": "summary"
+        },
+        "currency": {
+          "type": "string",
+          "default": "USD"
+        }
+      },
+      "required": [
+        "id",
+        "name",
+        "generatedAt",
+        "periodStart",
+        "periodEnd",
+        "period",
+        "analytics"
+      ],
+      "additionalProperties": false
+    }
+  },
+  "$schema": "http://json-schema.org/draft-07/schema#"
+}