Skip to main content

Grid Adapter

The Grid adapter enables distributed operation execution across the Covia network. Operations can run locally or on remote venues — the interface is the same either way.

Operations​

grid:run — Synchronous Execution​

Execute an operation and wait for the result.

{
  "operation": "grid:run",
  "input": {
    "operation": "v/ops/json/merge",
    "input": {
      "values": [{ "a": 1 }, { "b": 2 }]
    }
  }
}

Returns the operation's output directly.

Remote execution — specify a venue URL or DID:

{
  "operation": "grid:run",
  "input": {
    "operation": "v/ops/test/echo",
    "input": { "message": "hello" },
    "venue": "https://other-venue.covia.ai"
  }
}

grid:invoke — Asynchronous Execution​

Submit an operation and return immediately with a job ID.

{
  "operation": "grid:invoke",
  "input": {
    "operation": "v/ops/langchain/openai",
    "input": { "prompt": "Summarise this document..." }
  }
}

Response:

{
  "id": "0x1234...",
  "status": "PENDING",
  "created": 1712930400000
}

grid:jobStatus — Poll Job​

Check the current status of a previously submitted job.

{ "operation": "grid:jobStatus", "input": { "id": "0x1234..." } }

Response:

{
  "id": "0x1234...",
  "status": "COMPLETE",
  "created": 1712930400000,
  "updated": 1712930412000,
  "output": { "response": "The document describes..." }
}

grid:jobResult — Wait for Result​

Block until a job completes and return its output.

{ "operation": "grid:jobResult", "input": { "id": "0x1234..." } }

Returns the operation's output directly, or errors if the job failed.

Operations Reference​

OperationInputDescription
grid:runoperation, input?, venue?Execute synchronously, return result
grid:invokeoperation, input?, venue?Execute asynchronously, return job ID
grid:jobStatusid, venue?Poll job status
grid:jobResultid, venue?Wait for job completion, return result

Operation References​

The operation parameter accepts multiple formats:

FormatExampleDescription
Venue catalog pathv/ops/json/mergeOperation from the venue's catalog
User pino/my-pipelineNamed operation from your workspace
Asset ID0x7a8b9c0d...Content-addressed asset hash
DID URLdid:web:venue.com/v/ops/test/echoOperation on a specific remote venue

Patterns​

Fire and Forget​

grid:invoke → get job ID → continue other work → grid:jobResult when ready

Fan-Out / Fan-In​

Submit multiple operations in parallel, then collect results:

grid:invoke op-A → job-1
grid:invoke op-B → job-2
grid:invoke op-C → job-3
grid:jobResult job-1 → result-A
grid:jobResult job-2 → result-B
grid:jobResult job-3 → result-C

Cross-Venue Federation​

Execute an operation on a remote venue — caller identity is automatically propagated for audit and access control:

{
  "operation": "grid:run",
  "input": {
    "operation": "v/ops/covia/read",
    "input": { "path": "w/shared-data" },
    "venue": "did:web:partner-venue.example.com"
  }
}