{"openapi":"3.1.0","info":{"title":"EdgeAIStack Agent Tools API","description":"Tools for designing edge AI camera deployments — platform recommendation, capacity analysis, storage, bandwidth, power, and stream calculation.","version":"1.0.0","contact":{"name":"EdgeAI Stack","url":"https://edgeaistack.ai"}},"servers":[{"url":"https://api.edgeaistack.ai","description":"Production"}],"paths":{"/api/v1/tools/design_system":{"post":{"operationId":"design_system","summary":"design system","description":"Design a complete edge AI camera deployment. Given a model and camera count, returns platform recommendation, capacity analysis, storage, bandwidth, power estimates, alternatives, and risks. This is the flagship tool — use it when the user wants a full system design.","tags":["Agent Tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"model":{"type":"string","description":"ML model name (e.g. \"yolov8n\", \"yolo11s\", \"mobilenet_v2\")"},"camera_count":{"type":"integer","minimum":1,"maximum":256,"description":"Number of cameras (alternative to camera_groups)"},"camera_groups":{"type":"array","description":"Camera groups with per-group resolution/fps (alternative to camera_count)","items":{"type":"object","properties":{"count":{"type":"integer","minimum":1,"description":"Number of cameras in this group"},"resolution":{"type":"string","enum":["480p","720p","1080p","1440p","4k"],"description":"Resolution for this group"},"fps":{"type":"integer","minimum":1,"maximum":120,"description":"FPS for this group"}},"required":["count"]}},"resolution":{"type":"string","enum":["480p","720p","1080p","1440p","4k"],"default":"1080p","description":"Default resolution (overridden by camera_groups)"},"fps":{"type":"integer","minimum":1,"maximum":120,"default":15,"description":"Frames per second"},"task":{"type":"string","default":"detection","description":"Vision task type (detection, classification, segmentation, pose)"},"precision":{"type":"string","enum":["fp32","fp16","int8","fp4"],"default":"int8","description":"Model precision"},"codec":{"type":"string","enum":["h264","h265"],"default":"h264","description":"Video codec"},"retention_days":{"type":"integer","minimum":1,"maximum":365,"default":30,"description":"Days of video retention"},"recording_mode":{"type":"string","enum":["continuous","event_based"],"default":"continuous","description":"Recording mode"},"power_infrastructure":{"type":"string","enum":["poe","ac_adapter","dc","mixed"],"default":"poe","description":"Power infrastructure type"},"environment":{"type":"string","enum":["indoor_controlled","indoor_unconditioned","outdoor_enclosed","vehicle_mobile","industrial"],"default":"indoor_controlled","description":"Deployment environment"},"optimize_for":{"type":"string","enum":["lowest_cost","balanced","max_headroom","lowest_power","maximum_performance","fastest_deployment","future_headroom"],"default":"balanced","description":"Optimization priority"},"preferred_platform_family":{"type":"string","enum":["jetson","hailo","coral","any"],"default":"any","description":"Preferred hardware family"},"tracking":{"type":"boolean","default":false,"description":"Enable object tracking"},"runtime":{"type":"string","description":"Inference runtime (e.g. \"tensorrt\", \"onnx\")"},"include_alternatives":{"type":"boolean","default":true,"description":"Include alternative platform recommendations"}},"required":["model"],"oneOf":[{"required":["camera_count"]},{"required":["camera_groups"]}]},"example":{"model":"yolov8n","camera_count":8,"resolution":"1080p","fps":15}}}},"responses":{"200":{"description":"Successful tool response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolSuccess"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolError"}}}},"401":{"description":"Unauthorized — missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolError"}}}},"429":{"description":"Rate limit exceeded (50 req/hr)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolError"}}}}},"security":[{"apiKey":[]}]}},"/api/v1/tools/recommend_platform":{"post":{"operationId":"recommend_platform","summary":"recommend platform","description":"Recommend the best edge AI platform for a given camera workload. Returns the top recommendation with confidence score, plus alternatives and risks. Lighter than design_system — use when you only need a platform pick.","tags":["Agent Tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"resolution":{"type":"string","enum":["480p","720p","1080p","2k","4k"],"description":"Camera resolution"},"camera_count":{"type":"integer","minimum":1,"maximum":256,"description":"Number of cameras (alternative to cameras)"},"cameras":{"type":"integer","minimum":1,"maximum":256,"description":"Number of cameras (alternative to camera_count)"},"fps":{"type":"integer","minimum":1,"maximum":120,"default":15,"description":"Frames per second"},"retention_days":{"type":"integer","minimum":1,"maximum":365,"default":30,"description":"Days of retention"},"task":{"type":"string","default":"detection","description":"Vision task type"},"model_complexity":{"type":"string","default":"balanced","description":"Model complexity (lightweight, balanced, heavy)"},"precision":{"type":"string","default":"int8","description":"Model precision"},"power_source":{"type":"string","description":"Power source type"},"optimize_for":{"type":"string","default":"cost","description":"Optimization priority"}},"required":["resolution"],"oneOf":[{"required":["camera_count"]},{"required":["cameras"]}]},"example":{"resolution":"1080p","camera_count":4,"fps":15}}}},"responses":{"200":{"description":"Successful tool response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolSuccess"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolError"}}}},"401":{"description":"Unauthorized — missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolError"}}}},"429":{"description":"Rate limit exceeded (50 req/hr)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolError"}}}}},"security":[{"apiKey":[]}]}},"/api/v1/tools/estimate_storage":{"post":{"operationId":"estimate_storage","summary":"estimate storage","description":"Estimate storage requirements for a camera deployment. Returns required TB, daily write rate, drive lifespan, and feasibility assessment.","tags":["Agent Tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"retention_days":{"type":"integer","minimum":1,"maximum":365,"description":"Days of video retention"},"camera_count":{"type":"integer","minimum":1,"maximum":256,"description":"Number of cameras (alternative to cameras)"},"cameras":{"type":"integer","minimum":1,"maximum":256,"description":"Number of cameras (alternative to camera_count)"},"resolution":{"type":"string","enum":["480p","720p","1080p","2k","4k"],"description":"Camera resolution"},"fps":{"type":"integer","minimum":1,"maximum":120,"default":15,"description":"Frames per second"},"codec":{"type":"string","default":"h264","description":"Video codec (h264, h265)"},"drive":{"type":"string","default":"nvme_2tb","description":"Storage drive type"}},"required":["retention_days","resolution"],"oneOf":[{"required":["camera_count"]},{"required":["cameras"]}]},"example":{"retention_days":30,"camera_count":8,"resolution":"1080p"}}}},"responses":{"200":{"description":"Successful tool response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolSuccess"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolError"}}}},"401":{"description":"Unauthorized — missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolError"}}}},"429":{"description":"Rate limit exceeded (50 req/hr)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolError"}}}}},"security":[{"apiKey":[]}]}},"/api/v1/tools/estimate_bandwidth":{"post":{"operationId":"estimate_bandwidth","summary":"estimate bandwidth","description":"Estimate network bandwidth requirements for camera streams. Returns per-stream and total Mbps, utilization, and feasibility.","tags":["Agent Tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"camera_count":{"type":"integer","minimum":1,"maximum":256,"description":"Number of cameras (alternative to cameras)"},"cameras":{"type":"integer","minimum":1,"maximum":256,"description":"Number of cameras (alternative to camera_count)"},"resolution":{"type":"string","enum":["480p","720p","1080p","2k","4k"],"description":"Camera resolution"},"fps":{"type":"integer","minimum":1,"maximum":120,"default":15,"description":"Frames per second"},"codec":{"type":"string","default":"h264","description":"Video codec (h264, h265)"}},"required":["resolution"],"oneOf":[{"required":["camera_count"]},{"required":["cameras"]}]},"example":{"camera_count":16,"resolution":"1080p","fps":15}}}},"responses":{"200":{"description":"Successful tool response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolSuccess"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolError"}}}},"401":{"description":"Unauthorized — missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolError"}}}},"429":{"description":"Rate limit exceeded (50 req/hr)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolError"}}}}},"security":[{"apiKey":[]}]}},"/api/v1/tools/estimate_power":{"post":{"operationId":"estimate_power","summary":"estimate power","description":"Estimate power consumption for an edge AI deployment. Returns platform load, camera PoE draw, total system watts, PSU recommendation, and PoE switch recommendation.","tags":["Agent Tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string","description":"Platform identifier (e.g. \"jetson_orin_nano_8gb\")"},"poe":{"type":"string","description":"PoE standard (e.g. \"at_30w\", \"bt_60w\")"},"count":{"type":"integer","minimum":1,"maximum":100,"default":1,"description":"Number of cameras"},"ups":{"type":"string","default":"none","description":"UPS type"},"cooling":{"type":"string","default":"passive","description":"Cooling method"}},"required":["platform","poe"]},"example":{"platform":"jetson_orin_nano_8gb","poe":"at_30w","count":4}}}},"responses":{"200":{"description":"Successful tool response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolSuccess"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolError"}}}},"401":{"description":"Unauthorized — missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolError"}}}},"429":{"description":"Rate limit exceeded (50 req/hr)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolError"}}}}},"security":[{"apiKey":[]}]}},"/api/v1/tools/calculate_streams":{"post":{"operationId":"calculate_streams","summary":"calculate streams","description":"Calculate how many concurrent inference streams a platform can handle for a specific model configuration. Returns baseline FPS, max streams at various FPS targets, utilization, and feasibility.","tags":["Agent Tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string","description":"Platform identifier (e.g. \"jetson_orin_nano_8gb\")"},"model_family":{"type":"string","description":"Model family (e.g. \"yolov8\")"},"variant":{"type":"string","description":"Model variant (e.g. \"n\", \"s\", \"m\")"},"precision":{"type":"string","enum":["fp32","fp16","int8","fp4"],"description":"Model precision"},"resolution":{"type":"string","description":"Resolution as WxH or shorthand (e.g. \"1920x1080\" or \"1080p\")"},"runtime":{"type":"string","description":"Inference runtime (e.g. \"tensorrt\", \"onnx\")"},"target_fps":{"type":"integer","minimum":1,"maximum":120,"description":"Target FPS per stream"},"desired_streams":{"type":"integer","minimum":1,"maximum":256,"default":4,"description":"Desired number of concurrent streams"}},"required":["platform","model_family","variant","precision","resolution","runtime","target_fps"]},"example":{"platform":"jetson_orin_nano_8gb","model_family":"yolov8","variant":"n","precision":"fp16","resolution":"1080p","runtime":"tensorrt","target_fps":15}}}},"responses":{"200":{"description":"Successful tool response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolSuccess"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolError"}}}},"401":{"description":"Unauthorized — missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolError"}}}},"429":{"description":"Rate limit exceeded (50 req/hr)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolError"}}}}},"security":[{"apiKey":[]}]}}},"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"X-API-Key","description":"API key for agent tool access"}},"schemas":{"ToolSuccess":{"type":"object","properties":{"status":{"type":"string","enum":["ok"]},"tool":{"type":"string"}},"required":["status","tool"],"additionalProperties":true,"description":"Successful tool response. Additional fields vary by tool."},"ToolError":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"tool":{"type":"string"},"error_code":{"type":"string"},"message":{"type":"string"}},"required":["status","tool","error_code","message"]}}},"security":[{"apiKey":[]}]}