From 2fb2ecbd360844cc0c27b2a4c64fc8cd6b9925a7 Mon Sep 17 00:00:00 2001 From: Agustin Ramiro Diaz Date: Thu, 30 Oct 2025 15:00:27 -0300 Subject: [PATCH 1/2] add openapi spec --- modules/implementation/openapi.yaml | 702 ++++++++++++++++++++++++++++ 1 file changed, 702 insertions(+) create mode 100644 modules/implementation/openapi.yaml diff --git a/modules/implementation/openapi.yaml b/modules/implementation/openapi.yaml new file mode 100644 index 00000000..f153611d --- /dev/null +++ b/modules/implementation/openapi.yaml @@ -0,0 +1,702 @@ +openapi: 3.0.3 +info: + title: GenVM Manager API + version: 1.0.0 + description: | + REST API for managing GenVM execution instances, modules, and configurations. + + The GenVM Manager is responsible for: + - Managing GenVM execution instances and their lifecycle + - Controlling LLM and Web modules + - Version detection and contract management + - Runtime configuration and monitoring + contact: + name: GenLayer + url: https://docs.genlayer.com + +servers: + - url: http://127.0.0.1:3999 + description: Default local server + +tags: + - name: Status + description: Service status and health checks + - name: Modules + description: Module lifecycle management (LLM, Web) + - name: GenVM + description: GenVM execution instance management + - name: Contracts + description: Contract deployment and version detection + - name: Configuration + description: Runtime configuration management + - name: LLM + description: LLM provider availability testing + +paths: + /status: + get: + tags: + - Status + summary: Get service status + description: Returns the current status of LLM and Web modules + operationId: getStatus + responses: + '200': + description: Service status retrieved successfully + content: + application/json: + schema: + type: object + properties: + llm_module: + $ref: '#/components/schemas/ModuleStatus' + web_module: + $ref: '#/components/schemas/ModuleStatus' + '500': + $ref: '#/components/responses/InternalServerError' + + /module/start: + post: + tags: + - Modules + summary: Start a module + description: Starts the specified module (LLM or Web) + operationId: startModule + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/StartModuleRequest' + responses: + '200': + description: Module started successfully + content: + application/json: + schema: + type: object + properties: + result: + type: string + example: "module_started" + '500': + $ref: '#/components/responses/InternalServerError' + + /module/stop: + post: + tags: + - Modules + summary: Stop a module + description: Stops the specified module (LLM or Web) + operationId: stopModule + requestBody: + required: true + content: + application/json: + schema: + type: object + required: + - module_type + properties: + module_type: + $ref: '#/components/schemas/ModuleType' + responses: + '200': + description: Module stop result + content: + application/json: + schema: + type: object + properties: + result: + type: string + enum: [module_stopped, module_not_running] + '500': + $ref: '#/components/responses/InternalServerError' + + /genvm/run: + post: + tags: + - GenVM + summary: Start a GenVM execution instance + description: Starts a new GenVM instance with the specified configuration + operationId: runGenVM + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/GenVMRunRequest' + responses: + '200': + description: GenVM instance started successfully + content: + application/json: + schema: + type: object + properties: + result: + type: string + example: "started" + id: + type: integer + format: int64 + description: Unique ID of the started GenVM instance + example: 42 + '500': + $ref: '#/components/responses/InternalServerError' + + /genvm/run/readonly: + post: + tags: + - GenVM + summary: Run GenVM in readonly mode + description: Executes contract code in readonly mode (not yet implemented) + operationId: runGenVMReadonly + parameters: + - name: Deployment-Timestamp + in: header + required: true + schema: + type: string + format: date-time + description: RFC3339 formatted deployment timestamp + example: "2024-01-01T00:00:00Z" + requestBody: + required: true + content: + application/octet-stream: + schema: + type: string + format: binary + description: Contract code bytes + responses: + '200': + description: Contract schema + content: + application/json: + schema: + type: object + properties: + schema: + type: string + '500': + $ref: '#/components/responses/InternalServerError' + + /genvm/{id}: + get: + tags: + - GenVM + summary: Get GenVM execution status + description: Retrieves the status of a GenVM execution instance and removes it from tracking + operationId: getGenVMStatus + parameters: + - name: id + in: path + required: true + schema: + type: integer + format: int64 + description: GenVM instance ID + responses: + '200': + description: GenVM status retrieved successfully + content: + application/json: + schema: + type: object + properties: + genvm_id: + type: integer + format: int64 + status: + $ref: '#/components/schemas/GenVMStatus' + '500': + $ref: '#/components/responses/InternalServerError' + + delete: + tags: + - GenVM + summary: Gracefully shutdown a GenVM instance + description: Sends SIGTERM to the GenVM process and waits for graceful shutdown, sends SIGKILL if timeout is exceeded + operationId: shutdownGenVM + parameters: + - name: id + in: path + required: true + schema: + type: integer + format: int64 + description: GenVM instance ID + - name: wait_timeout_ms + in: query + schema: + type: integer + format: int64 + default: 30000 + description: Maximum time to wait for graceful shutdown in milliseconds + responses: + '200': + description: Shutdown result + content: + application/json: + schema: + oneOf: + - type: object + properties: + result: + type: string + example: "shutdown_completed" + genvm_id: + type: integer + format: int64 + - type: object + properties: + error: + type: string + genvm_id: + type: integer + format: int64 + '500': + $ref: '#/components/responses/InternalServerError' + + /contract/detect-version: + post: + tags: + - Contracts + summary: Detect contract version + description: Analyzes contract code to detect the specified major version + operationId: detectContractVersion + parameters: + - name: Deployment-Timestamp + in: header + required: true + schema: + type: string + format: date-time + description: RFC3339 formatted deployment timestamp + example: "2024-01-01T00:00:00Z" + requestBody: + required: true + content: + application/octet-stream: + schema: + type: string + format: binary + description: Contract code bytes + responses: + '200': + description: Version detected successfully + content: + application/json: + schema: + type: object + properties: + specified_major: + type: integer + format: uint32 + description: Detected major version number + '500': + $ref: '#/components/responses/InternalServerError' + + /contract/pre-deploy-writes: + post: + tags: + - Contracts + summary: Generate pre-deployment storage writes + description: Generates the storage writes needed before deploying a contract + operationId: makeDeploymentStorageWrites + parameters: + - name: Deployment-Timestamp + in: header + required: true + schema: + type: string + format: date-time + description: RFC3339 formatted deployment timestamp + example: "2024-01-01T00:00:00Z" + requestBody: + required: true + content: + application/octet-stream: + schema: + type: string + format: binary + description: Contract code bytes + responses: + '200': + description: Storage writes generated successfully + content: + application/json: + schema: + type: object + properties: + writes: + type: array + items: + type: array + items: + oneOf: + - type: string + format: base64 + description: Storage key (36 bytes, base64 encoded) + - type: string + format: base64 + description: Storage value (base64 encoded) + '500': + $ref: '#/components/responses/InternalServerError' + + /log/level: + post: + tags: + - Configuration + summary: Set log level + description: Dynamically changes the logging level + operationId: setLogLevel + requestBody: + required: true + content: + application/json: + schema: + type: object + required: + - level + properties: + level: + type: string + enum: [error, warn, info, debug, trace] + description: New log level + responses: + '200': + description: Log level set successfully + content: + application/json: + schema: + type: object + properties: + result: + type: string + example: "log_level_set" + level: + type: string + example: "debug" + '500': + $ref: '#/components/responses/InternalServerError' + + /manifest/reload: + post: + tags: + - Configuration + summary: Reload version manifest + description: Reloads the executor version manifest from disk + operationId: reloadManifest + responses: + '200': + description: Manifest reloaded successfully + content: + application/json: + schema: + type: object + properties: + result: + type: string + example: "manifest_reloaded" + '500': + $ref: '#/components/responses/InternalServerError' + + /env: + post: + tags: + - Configuration + summary: Set environment variable + description: Sets an environment variable at runtime + operationId: setEnvironmentVariable + requestBody: + required: true + content: + application/json: + schema: + type: object + required: + - key + - value + properties: + key: + type: string + description: Environment variable name + example: "GENVM_DEBUG" + value: + type: string + description: Environment variable value + example: "true" + responses: + '200': + description: Environment variable set successfully + content: + application/json: + schema: + type: object + properties: + result: + type: string + example: "env_var_set" + key: + type: string + example: "GENVM_DEBUG" + '500': + $ref: '#/components/responses/InternalServerError' + + /permits: + get: + tags: + - Configuration + summary: Get concurrent execution permits + description: Returns the current number of concurrent GenVM execution permits + operationId: getPermits + responses: + '200': + description: Permits retrieved successfully + content: + application/json: + schema: + type: object + properties: + permits: + type: integer + format: uint + description: Current number of concurrent execution permits + '500': + $ref: '#/components/responses/InternalServerError' + + post: + tags: + - Configuration + summary: Set concurrent execution permits + description: Changes the number of concurrent GenVM execution permits (minimum 2) + operationId: setPermits + requestBody: + required: true + content: + application/json: + schema: + type: object + required: + - permits + properties: + permits: + type: integer + format: uint + minimum: 2 + description: New number of concurrent execution permits + responses: + '200': + description: Permits set successfully + content: + application/json: + schema: + type: object + properties: + result: + type: string + example: "permits_set" + permits: + type: integer + format: uint + description: Actual number of permits after the operation + '500': + $ref: '#/components/responses/InternalServerError' + + /llm/check: + post: + tags: + - LLM + summary: Check LLM provider availability + description: Tests multiple LLM provider configurations with test prompts + operationId: checkLLMAvailability + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/LLMCheckRequest' + responses: + '200': + description: LLM availability check results + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/LLMAvailabilityResult' + '500': + $ref: '#/components/responses/InternalServerError' + +components: + schemas: + ModuleType: + type: string + enum: [Llm, Web] + description: Type of module + + ModuleStatus: + type: object + nullable: true + description: Status of a module (null if not running) + additionalProperties: true + + StartModuleRequest: + type: object + required: + - module_type + properties: + module_type: + $ref: '#/components/schemas/ModuleType' + # Additional module-specific configuration fields + + GenVMRunRequest: + type: object + required: + - major + - message + - is_sync + - capture_output + - host_data + - timestamp + - host + properties: + major: + type: integer + format: uint32 + description: Major version of the executor to use + message: + type: object + description: Execution message/payload (JSON object) + is_sync: + type: boolean + description: Whether to run in synchronous mode (uses 1 permit instead of 2) + capture_output: + type: boolean + description: Whether to capture stdout/stderr + max_execution_minutes: + type: integer + format: uint64 + default: 50 + description: Maximum execution time in minutes + host_data: + type: string + description: Host-specific data (JSON string) + example: '{"tx_id": "0x123", "node_address": "0xabc"}' + timestamp: + type: string + format: date-time + description: Execution timestamp (RFC3339 format) + host: + type: string + description: Host identifier + extra_args: + type: array + items: + type: string + default: [] + description: Additional command-line arguments for the executor + + GenVMStatus: + type: object + nullable: true + description: GenVM execution status (null if still running) + properties: + finished_at: + type: integer + format: uint64 + description: Milliseconds elapsed since finish time + stdout: + type: string + description: Captured stdout (if capture_output was true) + stderr: + type: string + description: Captured stderr (if capture_output was true) + + LLMProvider: + type: string + enum: [OpenAI, Anthropic, Ollama, Heurist] + description: LLM provider type + + LLMCheckRequest: + type: object + required: + - configs + - test_prompts + properties: + configs: + type: array + description: List of LLM provider configurations to test + items: + type: object + required: + - host + - provider + - model + - key + properties: + host: + type: string + description: Provider API host URL + example: "https://api.openai.com/v1" + provider: + $ref: '#/components/schemas/LLMProvider' + model: + type: string + description: Model name/identifier + example: "gpt-4" + key: + type: string + description: API key for authentication + test_prompts: + type: array + description: Test prompts to execute against each configuration + items: + type: object + description: Internal prompt format + # The actual structure depends on llm::prompt::Internal + + LLMAvailabilityResult: + type: object + required: + - config_index + - prompt_index + - available + properties: + config_index: + type: integer + format: uint + description: Index of the tested configuration + prompt_index: + type: integer + format: uint + description: Index of the tested prompt + available: + type: boolean + description: Whether the LLM provider is available + error: + type: string + nullable: true + description: Error message if unavailable + response: + type: string + nullable: true + description: LLM response if available + + ErrorResponse: + type: object + properties: + error: + type: string + description: Error message + + responses: + InternalServerError: + description: Internal server error + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' From f9d2c2e5632e3a9ebbed70c576f24a552cd95b58 Mon Sep 17 00:00:00 2001 From: Agustin Ramiro Diaz Date: Thu, 6 Nov 2025 14:09:16 -0300 Subject: [PATCH 2/2] fix openapi stuff --- modules/implementation/openapi.yaml | 100 +++++++++++++++++++++++++++- 1 file changed, 98 insertions(+), 2 deletions(-) diff --git a/modules/implementation/openapi.yaml b/modules/implementation/openapi.yaml index f153611d..67131097 100644 --- a/modules/implementation/openapi.yaml +++ b/modules/implementation/openapi.yaml @@ -15,8 +15,17 @@ info: url: https://docs.genlayer.com servers: - - url: http://127.0.0.1:3999 - description: Default local server + - url: http://{host}:{port} + description: Local development server + variables: + host: + default: '127.0.0.1' + description: Server hostname or IP address + port: + default: '3999' + description: Server port number + - url: https://api.genlayer.com + description: Production server tags: - name: Status @@ -32,6 +41,10 @@ tags: - name: LLM description: LLM provider availability testing +security: + - ApiKeyAuth: [] + - {} # Allow unauthenticated access + paths: /status: get: @@ -79,6 +92,10 @@ paths: result: type: string example: "module_started" + '400': + $ref: '#/components/responses/BadRequest' + '422': + $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/InternalServerError' @@ -111,6 +128,10 @@ paths: result: type: string enum: [module_stopped, module_not_running] + '400': + $ref: '#/components/responses/BadRequest' + '422': + $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/InternalServerError' @@ -143,6 +164,10 @@ paths: format: int64 description: Unique ID of the started GenVM instance example: 42 + '400': + $ref: '#/components/responses/BadRequest' + '422': + $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/InternalServerError' @@ -153,6 +178,7 @@ paths: summary: Run GenVM in readonly mode description: Executes contract code in readonly mode (not yet implemented) operationId: runGenVMReadonly + x-status: experimental parameters: - name: Deployment-Timestamp in: header @@ -180,6 +206,10 @@ paths: properties: schema: type: string + '400': + $ref: '#/components/responses/BadRequest' + '422': + $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/InternalServerError' @@ -211,6 +241,8 @@ paths: format: int64 status: $ref: '#/components/schemas/GenVMStatus' + '404': + $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/InternalServerError' @@ -257,6 +289,8 @@ paths: genvm_id: type: integer format: int64 + '404': + $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/InternalServerError' @@ -296,6 +330,10 @@ paths: type: integer format: uint32 description: Detected major version number + '400': + $ref: '#/components/responses/BadRequest' + '422': + $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/InternalServerError' @@ -333,8 +371,13 @@ paths: properties: writes: type: array + maxItems: 1000 + description: List of storage key-value pairs items: type: array + maxItems: 2 + minItems: 2 + description: Key-value pair (tuple of two strings) items: oneOf: - type: string @@ -343,6 +386,10 @@ paths: - type: string format: base64 description: Storage value (base64 encoded) + '400': + $ref: '#/components/responses/BadRequest' + '422': + $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/InternalServerError' @@ -380,6 +427,10 @@ paths: level: type: string example: "debug" + '400': + $ref: '#/components/responses/BadRequest' + '422': + $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/InternalServerError' @@ -443,6 +494,10 @@ paths: key: type: string example: "GENVM_DEBUG" + '400': + $ref: '#/components/responses/BadRequest' + '422': + $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/InternalServerError' @@ -503,6 +558,10 @@ paths: type: integer format: uint description: Actual number of permits after the operation + '400': + $ref: '#/components/responses/BadRequest' + '422': + $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/InternalServerError' @@ -526,12 +585,25 @@ paths: application/json: schema: type: array + maxItems: 5000 + description: Results for each config-prompt combination items: $ref: '#/components/schemas/LLMAvailabilityResult' + '400': + $ref: '#/components/responses/BadRequest' + '422': + $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/InternalServerError' components: + securitySchemes: + ApiKeyAuth: + type: apiKey + in: header + name: X-API-Key + description: Optional API key for authentication + schemas: ModuleType: type: string @@ -595,6 +667,7 @@ components: description: Host identifier extra_args: type: array + maxItems: 100 items: type: string default: [] @@ -629,6 +702,7 @@ components: properties: configs: type: array + maxItems: 50 description: List of LLM provider configurations to test items: type: object @@ -653,6 +727,7 @@ components: description: API key for authentication test_prompts: type: array + maxItems: 100 description: Test prompts to execute against each configuration items: type: object @@ -694,6 +769,27 @@ components: description: Error message responses: + BadRequest: + description: Bad request - invalid input parameters + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + + NotFound: + description: Resource not found + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + + UnprocessableEntity: + description: Unprocessable entity - validation error + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + InternalServerError: description: Internal server error content: