Package com.google.genkit.ai.middleware

Interface GenerationMiddlewareDesc

public interface GenerationMiddlewareDesc
A registered, self-describing, parameterized middleware factory.

This is the descriptor that gets stored in the registry's "middleware" value bucket and surfaced to the Genkit Dev UI via the reflection API. It mirrors the JS SDK's GenerateMiddleware descriptor (whose toJson() produces MiddlewareDesc) and the Go SDK's MiddlewareDesc.

Unlike a bare GenerationMiddleware (which is the runtime hooks bundle), a descriptor carries metadata for discovery and a configSchema() that lets the Dev UI render a parameters form. When the user selects a middleware in the Dev UI (optionally filling in parameters), the selection is sent back as a {name, config} reference and resolved via instantiate(JsonNode).

Build descriptors with GenerationMiddlewares.define(java.lang.String, java.lang.String, java.lang.Class<C>, java.util.function.Function<C, com.google.genkit.ai.middleware.GenerationMiddleware>). Plugins expose them via MiddlewarePlugin.

  • Method Summary

    Modifier and Type
    Method
    Description
    default Map<String,Object>
    configSchema()
    Returns the JSON Schema describing this middleware's configuration parameters, or null if the middleware takes no parameters.
    default String
    description()
    Returns a human-readable description, or null if none.
    GenerationMiddleware
    instantiate(com.fasterxml.jackson.databind.JsonNode config)
    Instantiates a fresh GenerationMiddleware (hooks bundle) bound to the given configuration.
    default Map<String,Object>
    metadata()
    Returns arbitrary metadata, or null if none.
    String
    name()
    Returns the middleware's unique name.
    default Map<String,Object>
    toJson()
    Serializes this descriptor to the JSON shape expected by the reflection API / Dev UI: {name, description?, configSchema?, metadata?} (null fields omitted).

  • Method Details

    • name

      String name()
      Returns the middleware's unique name. Must equal the key it is registered under.

    • description

      default String description()
      Returns a human-readable description, or null if none.

    • configSchema

      default Map<String,Object> configSchema()
      Returns the JSON Schema describing this middleware's configuration parameters, or null if the middleware takes no parameters. The Dev UI renders a form from this schema.

    • metadata

      default Map<String,Object> metadata()
      Returns arbitrary metadata, or null if none.

    • instantiate

      GenerationMiddleware instantiate(com.fasterxml.jackson.databind.JsonNode config) throws GenkitException
      Instantiates a fresh GenerationMiddleware (hooks bundle) bound to the given configuration.

      Mirrors the JS def.instantiate({config}) and Go buildFromJSON(configJSON). The config is applied opaquely — no server-side validation is performed; defaults live in the middleware/config type. A fresh instance is returned per call so per-invocation state is isolated.

      Parameters:
      config - the configuration as a JSON node (from the use[].config field), or null/JSON null when no configuration was supplied
      Returns:
      a fresh middleware instance
      Throws:
      GenkitException - if the configuration cannot be bound

    • toJson

      default Map<String,Object> toJson()
      Serializes this descriptor to the JSON shape expected by the reflection API / Dev UI: {name, description?, configSchema?, metadata?} (null fields omitted). Matches the JS/Go MiddlewareDesc wire shape.
      Returns:
      the serialized descriptor