hexel-sdk 0.1.0

package/generator/overrides.json

@@ -0,0 +1,66 @@
+{
+  "services": {
+    "sandbox": {
+      "description": "Isolated execution environments",
+      "endpoints": {
+        "POST /compute/v1/vms/allocate": "create",
+        "GET /compute/v1/vms": "list",
+        "GET /compute/v1/vms/{id}": "get",
+        "DELETE /compute/v1/vms/{id}": "delete",
+        "POST /compute/v1/vms/{id}/release": "release",
+        "POST /compute/v1/vms/{id}/renew": "renew",
+        "POST /compute/v1/vms/{id}/execute": "execute"
+      }
+    },
+    "agent": {
+      "description": "Agent registry — register and manage agent images",
+      "endpoints": {
+        "POST /registry/v1/agents": "register",
+        "GET /registry/v1/agents": "list",
+        "GET /registry/v1/agents/{id}": "get",
+        "PUT /registry/v1/agents/{id}": "update",
+        "DELETE /registry/v1/agents/{id}": "delete",
+        "GET /registry/v1/agents/search": "search"
+      }
+    },
+    "instance": {
+      "description": "Agent deployments — deploy agents and manage instances",
+      "endpoints": {
+        "POST /compute/v1/agents/{agent_id}/deploy": "deploy",
+        "GET /compute/v1/deployments": "list",
+        "GET /compute/v1/deployments/{deployment_id}": "get",
+        "DELETE /compute/v1/deployments/{deployment_id}": "delete",
+        "POST /compute/v1/deployments/{deployment_id}/stop": "stop",
+        "POST /compute/v1/deployments/{deployment_id}/redeploy": "redeploy"
+      }
+    }
+  },
+  "exclude_paths": [
+    "/internal/",
+    "/compute/v1/pool/",
+    "/compute/v1/access/",
+    "/compute/v1/skills",
+    "/compute/v1/usage",
+    "/compute/v1/vms/{id}/r/",
+    "/compute/v1/vms/{id}/endpoint"
+  ],
+  "type_renames": {
+    "models.AllocateRequest": "CreateSandboxRequest",
+    "models.AllocateResponse": "SandboxResponse",
+    "models.AgentVM": "SandboxInfo",
+    "models.Agent": "InstanceInfo",
+    "models.ReleaseRequest": "ReleaseRequest",
+    "models.RenewRequest": "RenewRequest",
+    "registryclient.Agent": "AgentInfo"
+  },
+  "websocket": {
+    "sandbox": {
+      "url_field": "ws_url",
+      "methods": {
+        "execute": {"type": "execute", "fields": ["code", "language"]},
+        "command": {"type": "command", "fields": ["command"]}
+      },
+      "terminal_events": ["done", "execution_complete", "error"]
+    }
+  }
+}

package/generator/parser.py

@@ -0,0 +1,180 @@
+"""
+Spec parser — reads OpenAPI specs + overrides → produces IR (intermediate representation).
+
+The IR is a clean, normalized model that the code generator reads.
+"""
+import json
+import re
+from pathlib import Path
+
+
+def load_spec(path: str) -> dict:
+    with open(path) as f:
+        return json.load(f)
+
+
+def resolve_ref(spec: dict, ref: str) -> dict:
+    """Resolve a $ref like #/components/schemas/models.Agent"""
+    parts = ref.lstrip("#/").split("/")
+    node = spec
+    for p in parts:
+        node = node.get(p, {})
+    return node
+
+
+def extract_schema_fields(spec: dict, schema: dict) -> list[dict]:
+    """Extract fields from a schema, resolving $ref."""
+    if "$ref" in schema:
+        schema = resolve_ref(spec, schema["$ref"])
+    props = schema.get("properties", {})
+    required = set(schema.get("required", []))
+    fields = []
+    for name, prop in props.items():
+        typ = prop.get("type", "any")
+        if "$ref" in prop:
+            typ = prop["$ref"].split("/")[-1]
+        if typ == "array" and "items" in prop:
+            item_type = prop["items"].get("type", "any")
+            if "$ref" in prop["items"]:
+                item_type = prop["items"]["$ref"].split("/")[-1]
+            typ = f"list[{item_type}]"
+        if prop.get("additionalProperties") and isinstance(prop["additionalProperties"], dict):
+            val_type = prop["additionalProperties"].get("type", "any")
+            typ = f"dict[str, {val_type}]"
+        elif prop.get("additionalProperties") is True:
+            typ = "dict"
+        fields.append({
+            "name": name,
+            "type": typ,
+            "required": name in required,
+            "description": prop.get("description", ""),
+        })
+    return fields
+
+
+def parse_path_params(path: str) -> list[str]:
+    """Extract path parameters like {id}, {agent_id}."""
+    return re.findall(r"\{(\w+)\}", path)
+
+
+def build_ir(specs: dict[str, dict], overrides: dict) -> dict:
+    """
+    Build IR from multiple OpenAPI specs + overrides.
+
+    specs: {"compute": spec_dict, "registry": spec_dict, "agentd": spec_dict}
+    overrides: the overrides.json content
+    """
+    ir = {
+        "services": {},
+        "types": {},
+    }
+
+    # Collect all schemas from all specs
+    for spec_name, spec in specs.items():
+        for schema_name, schema_def in spec.get("components", {}).get("schemas", {}).items():
+            type_name = overrides.get("type_renames", {}).get(schema_name, schema_name)
+            # Clean up Go-style names
+            type_name = type_name.replace("models.", "").replace("iamclient.", "").replace("registryclient.", "")
+            ir["types"][type_name] = {
+                "original": schema_name,
+                "fields": extract_schema_fields(spec, schema_def),
+            }
+
+    # Build services from overrides
+    exclude = overrides.get("exclude_paths", [])
+    for service_name, service_def in overrides.get("services", {}).items():
+        methods = {}
+        for endpoint_key, method_name in service_def.get("endpoints", {}).items():
+            # Parse "POST /compute/v1/vms/allocate"
+            parts = endpoint_key.split(" ", 1)
+            http_method = parts[0]
+            path = parts[1]
+
+            # Find this endpoint in any spec
+            endpoint_spec = None
+            source_spec = None
+            for spec_name, spec in specs.items():
+                if path in spec.get("paths", {}):
+                    ep = spec["paths"][path].get(http_method.lower(), {})
+                    if ep:
+                        endpoint_spec = ep
+                        source_spec = spec
+                        break
+
+            if not endpoint_spec:
+                continue
+
+            # Extract request/response types
+            request_type = None
+            request_body = endpoint_spec.get("requestBody", {})
+            if request_body:
+                content = request_body.get("content", {}).get("application/json", {})
+                schema = content.get("schema", {})
+                if "$ref" in schema:
+                    request_type = schema["$ref"].split("/")[-1]
+                    request_type = overrides.get("type_renames", {}).get(request_type, request_type)
+                    request_type = request_type.replace("models.", "")
+
+            response_type = None
+            resp_200 = endpoint_spec.get("responses", {}).get("200", endpoint_spec.get("responses", {}).get("201", {}))
+            if resp_200:
+                content = resp_200.get("content", {}).get("application/json", {})
+                schema = content.get("schema", {})
+                if "$ref" in schema:
+                    response_type = schema["$ref"].split("/")[-1]
+                    response_type = overrides.get("type_renames", {}).get(response_type, response_type)
+                    response_type = response_type.replace("models.", "")
+                elif schema.get("type") == "array":
+                    items = schema.get("items", {})
+                    if "$ref" in items:
+                        item_type = items["$ref"].split("/")[-1].replace("models.", "")
+                        response_type = f"list[{item_type}]"
+
+            path_params = parse_path_params(path)
+
+            methods[method_name] = {
+                "http_method": http_method,
+                "path": path,
+                "path_params": path_params,
+                "request_type": request_type,
+                "response_type": response_type,
+                "description": endpoint_spec.get("description", endpoint_spec.get("summary", "")),
+                "tags": endpoint_spec.get("tags", []),
+            }
+
+        ir["services"][service_name] = {
+            "description": service_def.get("description", ""),
+            "methods": methods,
+        }
+
+    # Add WebSocket info
+    ir["websocket"] = overrides.get("websocket", {})
+
+    return ir
+
+
+def build_from_files(specs_dir: str, overrides_path: str) -> dict:
+    """Convenience: load specs from directory + overrides file → IR."""
+    specs_dir = Path(specs_dir)
+    specs = {}
+
+    spec_map = {
+        "compute-api.json": "compute",
+        "agent-registry-api.json": "registry",
+        "agentd-api.json": "agentd",
+    }
+
+    for filename, key in spec_map.items():
+        path = specs_dir / filename
+        if path.exists():
+            specs[key] = load_spec(str(path))
+
+    with open(overrides_path) as f:
+        overrides = json.load(f)
+
+    return build_ir(specs, overrides)
+
+
+if __name__ == "__main__":
+    ir = build_from_files("specs", "generator/overrides.json")
+    print(json.dumps(ir, indent=2))

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "hexel-sdk",
+  "version": "0.1.0",
+  "description": "Hexel SDK — deploy and run AI agents",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "generate": "npx ts-node generator/generate.ts",
+    "check": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "keywords": ["ai", "agents", "compute", "hexel", "sandbox"],
+  "license": "MIT",
+  "dependencies": {},
+  "devDependencies": {
+    "typescript": "^5.5.0",
+    "ts-node": "^10.9.0",
+    "@types/node": "^20.0.0"
+  }
+}

package/specs/agent-registry-api.json

@@ -0,0 +1 @@
+{"components":{"schemas":{"models.Agent":{"properties":{"allowed_org_ids":{"items":{"type":"string"},"type":"array"},"author":{"type":"string"},"capabilities":{"items":{"type":"string"},"type":"array"},"created_at":{"type":"string"},"description":{"type":"string"},"endpoint":{"type":"string"},"id":{"type":"string"},"image":{"type":"string"},"image_pull_secret":{"$ref":"#/components/schemas/models.ImagePullSecret"},"manifest":{"$ref":"#/components/schemas/models.AgentManifest"},"metadata":{"additionalProperties":{"type":"string"},"type":"object"},"name":{"type":"string"},"org_id":{"type":"string"},"public_key":{"type":"string"},"state":{"description":"registered, deploying, running, active, idle, sleeping, stopped, failed","type":"string"},"updated_at":{"type":"string"},"version":{"type":"string"},"visibility":{"description":"private, public","type":"string"}},"type":"object"},"models.AgentManifest":{"properties":{"authentication":{"additionalProperties":true,"type":"object"},"capabilities":{"additionalProperties":true,"type":"object"},"description":{"type":"string"},"input_schema":{"additionalProperties":true,"type":"object"},"name":{"type":"string"},"output_schema":{"additionalProperties":true,"type":"object"},"runtime":{"additionalProperties":true,"type":"object"},"skills":{"items":{"$ref":"#/components/schemas/models.ManifestSkill"},"type":"array"},"url":{"type":"string"},"version":{"type":"string"}},"type":"object"},"models.AgentResponse":{"properties":{"agent":{"$ref":"#/components/schemas/models.Agent"}},"type":"object"},"models.AgentsListResponse":{"properties":{"agents":{"items":{"$ref":"#/components/schemas/models.Agent"},"type":"array"},"total":{"type":"integer"}},"type":"object"},"models.CreateAgentRequest":{"properties":{"author":{"type":"string"},"capabilities":{"items":{"type":"string"},"type":"array"},"description":{"type":"string"},"endpoint":{"type":"string"},"image":{"type":"string"},"image_pull_secret":{"$ref":"#/components/schemas/models.ImagePullSecret"},"manifest":{"$ref":"#/components/schemas/models.AgentManifest"},"metadata":{"additionalProperties":{"type":"string"},"type":"object"},"name":{"type":"string"},"org_id":{"type":"string"},"version":{"type":"string"}},"required":["image","name","org_id"],"type":"object"},"models.CreateToolRequest":{"properties":{"category":{"type":"string"},"description":{"type":"string"},"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"type":"object"},"models.ErrorResponse":{"properties":{"error":{"type":"string"},"message":{"type":"string"}},"type":"object"},"models.ImagePullSecret":{"properties":{"password":{"type":"string"},"registry":{"type":"string"},"username":{"type":"string"}},"type":"object"},"models.ManifestSkill":{"properties":{"id":{"type":"string"},"inputModes":{"items":{"type":"string"},"type":"array"},"outputModes":{"items":{"type":"string"},"type":"array"}},"type":"object"},"models.Tool":{"properties":{"category":{"type":"string"},"created_at":{"type":"string"},"description":{"type":"string"},"id":{"type":"string"},"name":{"type":"string"}},"type":"object"},"models.ToolResponse":{"properties":{"tool":{"$ref":"#/components/schemas/models.Tool"}},"type":"object"},"models.ToolsListResponse":{"properties":{"tools":{"items":{"$ref":"#/components/schemas/models.Tool"},"type":"array"},"total":{"type":"integer"}},"type":"object"},"models.UpdateAgentRequest":{"properties":{"capabilities":{"items":{"type":"string"},"type":"array"},"description":{"type":"string"},"endpoint":{"type":"string"},"image":{"type":"string"},"manifest":{"$ref":"#/components/schemas/models.AgentManifest"},"metadata":{"additionalProperties":{"type":"string"},"type":"object"},"name":{"type":"string"},"public_key":{"type":"string"},"state":{"type":"string"},"version":{"type":"string"}},"type":"object"}},"securitySchemes":{"BearerAuth":{"in":"header","name":"Authorization","type":"apiKey"}}},"info":{"contact":{},"description":"Independent agent catalog service for Compute and Orchestrator platforms","title":"Agent Registry API","version":"1.0"},"openapi":"3.0.1","paths":{"/registry/v1/agents":{"get":{"description":"List agents with optional filters","parameters":[{"description":"Filter by author","in":"query","name":"author","schema":{"type":"string"}},{"description":"Filter by status","in":"query","name":"status","schema":{"type":"string"}},{"description":"Limit","in":"query","name":"limit","schema":{"default":20,"type":"integer"}},{"description":"Offset","in":"query","name":"offset","schema":{"default":0,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.AgentsListResponse"}}},"description":"OK"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorResponse"}}},"description":"Internal Server Error"}},"summary":"List agents","tags":["agents"]},"post":{"description":"Register a new agent in the catalog","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.CreateAgentRequest"}}},"description":"Agent details","required":true,"x-originalParamName":"request"},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.AgentResponse"}}},"description":"Created"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorResponse"}}},"description":"Bad Request"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorResponse"}}},"description":"Conflict"}},"summary":"Create agent","tags":["agents"]}},"/registry/v1/agents/search":{"get":{"description":"Find agents matching given capabilities","parameters":[{"description":"Comma-separated capabilities","in":"query","name":"capabilities","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.AgentsListResponse"}}},"description":"OK"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorResponse"}}},"description":"Bad Request"}},"summary":"Search agents by capabilities","tags":["agents"]}},"/registry/v1/agents/{id}":{"delete":{"description":"Delete agent by ID","parameters":[{"description":"Agent ID","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"No Content"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorResponse"}}},"description":"Not Found"}},"summary":"Delete agent","tags":["agents"]},"get":{"description":"Get agent by ID","parameters":[{"description":"Agent ID","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.AgentResponse"}}},"description":"OK"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorResponse"}}},"description":"Not Found"}},"summary":"Get agent","tags":["agents"]},"put":{"description":"Update agent fields","parameters":[{"description":"Agent ID","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.UpdateAgentRequest"}}},"description":"Fields to update","required":true,"x-originalParamName":"request"},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.AgentResponse"}}},"description":"OK"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorResponse"}}},"description":"Not Found"}},"summary":"Update agent","tags":["agents"]}},"/registry/v1/agents/{id}/public-key":{"get":{"description":"Returns the Ed25519 public key for A2A signature verification","parameters":[{"description":"Agent ID","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"additionalProperties":{"type":"string"},"type":"object"}}},"description":"OK"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorResponse"}}},"description":"Not Found"}},"summary":"Get agent public key","tags":["agents"]}},"/registry/v1/tools":{"get":{"description":"List all tools with optional category filter","parameters":[{"description":"Filter by category","in":"query","name":"category","schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ToolsListResponse"}}},"description":"OK"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorResponse"}}},"description":"Internal Server Error"}},"summary":"List tools","tags":["tools"]},"post":{"description":"Register a new tool in the catalog","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.CreateToolRequest"}}},"description":"Tool details","required":true,"x-originalParamName":"request"},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ToolResponse"}}},"description":"Created"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorResponse"}}},"description":"Bad Request"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorResponse"}}},"description":"Conflict"}},"summary":"Create tool","tags":["tools"]}},"/registry/v1/tools/{id}":{"get":{"description":"Get tool by ID","parameters":[{"description":"Tool ID","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ToolResponse"}}},"description":"OK"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorResponse"}}},"description":"Not Found"}},"summary":"Get tool","tags":["tools"]}}},"servers":[{"url":"https://api.hexelstudio.com/"}]}