vgi.invocation

Module overview

Response types for the VGI protocol.

This module defines response dataclasses and the FunctionType enum:

• FunctionType: Enum for scalar, table, and aggregate function types.
• BindResponse: Result of bind phase with output schema.
• BaseInitResponse: Base class for init responses.
• GlobalInitResponse: Result of init phase with max_workers.

Request types (BindRequest, InitRequest) are in vgi.protocol.

class BaseInitResponse

source

Bases: ArrowSerializableDataclass

Description

The result of calling init() on a function.

Attributes

attribute execution_id

bytes

A unique id for the function execution.

attribute opaque_data

Annotated[bytes | None, ArrowType(pa.binary())]

Serialized data that is opaque to the caller that must be passed to any init() invocations.

class BindResponse

source

Bases: ArrowSerializableDataclass

Description

The result of calling bind() on a function.

The bind result is created by calling bind() and importantly contains the function’s output characteristics. It is serialized and sent to the client before any data processing begins.

When lookup_secret_types is non-empty, this is a secret scope request rather than a normal bind response. C++ resolves the requested secrets and retries bind with resolved_secrets_provided=True. The developer never constructs scope requests directly — the framework generates them when SecretsAccessor has pending lookups after on_bind() returns.

Attributes

attribute output_schema

Annotated[pa.Schema, ArrowType(pa.binary())]

Arrow schema describing the structure of output batches.

attribute opaque_data

Annotated[bytes | None, ArrowType(pa.binary())]

Serialized data that is opaque to the caller that must be passed to any init() invocations.

attribute lookup_secret_types

list[str]

Secret types for scoped lookup requests (empty = normal response).

attribute lookup_scopes

list[str]

Scopes for scoped lookup requests (parallel to lookup_secret_types).

attribute lookup_names

list[str]

Names for scoped lookup requests (parallel to lookup_secret_types).

attribute is_secret_scope_request

bool

True if this is a secret scope request, not a normal bind response.

Methods

method secret_scope_request

source

secret_scope_request(entries: list[SecretLookupEntry]) -> BindResponse

Create a secret scope request from lookup entries.

The framework calls this when SecretsAccessor has pending lookups. C++ detects the non-empty lookup_secret_types and resolves them.

method secret_scope_entries

source

secret_scope_entries() -> list[SecretLookupEntry]

Convert lookup fields back to SecretLookupEntry objects.

class FunctionType

source

Bases: Enum

Description

Type of function being invoked.

Used in BindRequest to indicate which function category is being bound, allowing the worker to apply appropriate validation and processing.

Attributes

attribute AGGREGATE

attribute SCALAR

attribute TABLE

attribute TABLE_BUFFERING

class GlobalInitResponse

source

Bases: BaseInitResponse

Description

The result of calling init() on a function.

Attributes

attribute max_workers

int

The maximum number of worker processes that may be used for this function execution. This allows the function to control parallelism.

Inherited members (2)

• execution_id attribute · from BaseInitResponse
• opaque_data attribute · from BaseInitResponse