Synapse.Orchestrator.AgentConfig (Synapse v0.1.1)

Normalized representation of a declarative agent configuration.

This module provides a strongly-typed struct backed by a NimbleOptions schema so configurations can be validated at compile- and boot-time before agents are spawned. The resulting struct is used by the orchestrator runtime to drive reconciliation and agent creation.

Summary

Types

agent_id()

Identifier used to reference an agent across the orchestrator runtime

agent_type()

Archetype supported by the orchestrator

custom_handler()

Callable invoked for custom agents

orchestration()

Orchestrator behaviour configuration

result_builder()

Callable used to build results from action outputs

signal_config()

Signal configuration normalised by the schema

signal_pattern()

Signal routing patterns

signal_roles()

Signal role mappings for orchestrators

signal_topic()

Canonical signal topics used by the router

spawn_specialists()

Spawn specialists list or strategy

t()

Complete validated configuration

Functions

new(config)

Validates and normalises a configuration map or keyword list into an %Synapse.Orchestrator.AgentConfig{} struct.

schema()

Returns the NimbleOptions schema used to validate agent configurations.

Types

agent_id()

@type agent_id() :: atom()

Identifier used to reference an agent across the orchestrator runtime

agent_type()

@type agent_type() :: :specialist | :orchestrator | :custom

Archetype supported by the orchestrator

custom_handler()

@type custom_handler() :: function() | {module(), atom(), [term()]}

Callable invoked for custom agents

orchestration()

@type orchestration() :: %{
  classify_fn: function() | {module(), atom(), [term()]},
  spawn_specialists: spawn_specialists(),
  aggregation_fn: function() | {module(), atom(), [term()]},
  fast_path_fn: function() | {module(), atom(), [term()]} | nil
}

Orchestrator behaviour configuration

result_builder()

@type result_builder() :: function() | {module(), atom(), [term()]}

Callable used to build results from action outputs

signal_config()

@type signal_config() :: %{
  subscribes: [signal_topic()],
  emits: [signal_topic()],
  roles: signal_roles() | nil
}

Signal configuration normalised by the schema

signal_pattern()

@type signal_pattern() :: String.t()

Signal routing patterns

signal_roles()

@type signal_roles() :: %{
  optional(:request) => signal_topic() | nil,
  optional(:result) => signal_topic() | nil,
  optional(:summary) => signal_topic() | nil
}

Signal role mappings for orchestrators

signal_topic()

@type signal_topic() :: Synapse.Signal.topic()

Canonical signal topics used by the router

spawn_specialists()

@type spawn_specialists() :: [agent_id()] | function() | {module(), atom(), [term()]}

Spawn specialists list or strategy

t()

@type t() :: %Synapse.Orchestrator.AgentConfig{
  actions: [module()],
  custom_handler: custom_handler() | nil,
  depends_on: [agent_id()],
  id: agent_id(),
  metadata: map(),
  orchestration: orchestration() | nil,
  registry: atom() | nil,
  result_builder: result_builder() | nil,
  signals: signal_config(),
  spawn_condition: (-> boolean()) | nil,
  state_schema: keyword() | nil,
  type: agent_type()
}

Complete validated configuration

Functions

new(config)

@spec new(map() | keyword()) ::
  {:ok, t()} | {:error, NimbleOptions.ValidationError.t()}

Validates and normalises a configuration map or keyword list into an %Synapse.Orchestrator.AgentConfig{} struct.

Returns {:ok, struct} on success or {:error, %NimbleOptions.ValidationError{}} on failure.

schema()

@spec schema() :: NimbleOptions.schema()

Returns the NimbleOptions schema used to validate agent configurations.