module Riffer::Agent::Serializer

Turns a resolved agent into a self-contained, provider-neutral data hash and back into a runnable agent, behind the +Riffer::Agent#to_h+ / Riffer::Agent.from_h delegators.

hash    = Riffer::Agent::Serializer.to_h(agent: agent)
rebuilt = Riffer::Agent::Serializer.from_h(hash, context: {tenant: "acme"})

Constants

DEFAULT_TOOL_RESOLVER: The default tool_resolver: synthesizes a body-less tool shell from a descriptor. Its call raises — route shells through a remote runtime.
SCHEMA_VERSION: The wire format version, bumped only on an incompatible change to the hash shape; from_h refuses any other version.

Public Instance Methods

from_h (hash, context: nil, session: nil, tool_resolver: DEFAULT_TOOL_RESOLVER, tool_runtime: nil)

Source

# File lib/riffer/agent/serializer.rb, line 55
def from_h(hash, context: nil, session: nil, tool_resolver: DEFAULT_TOOL_RESOLVER, tool_runtime: nil)
  # Version -> decoder dispatch. Adding a +when 2+ arm (a backwards-compatible
  # decoder) is how a future breaking change keeps older hashes readable.
  case hash[:schema_version]
  when SCHEMA_VERSION
    decode_v1(hash, context: context, session: session, tool_resolver: tool_resolver, tool_runtime: tool_runtime)
  else
    raise VersionError, "Unsupported schema_version: #{hash[:schema_version].inspect} (this Riffer supports #{SCHEMA_VERSION})"
  end
end

Reconstructs a runnable agent from a wire hash. context is threaded into tool dispatch (not used to re-resolve the already-resolved config); session seeds conversation history (the hash carries the agent definition, not its history). Raises Riffer::Agent::Serializer::VersionError on an unsupported schema_version.

from_json (json, context: nil, session: nil, tool_resolver: DEFAULT_TOOL_RESOLVER, tool_runtime: nil)

Source

# File lib/riffer/agent/serializer.rb, line 77
def from_json(json, context: nil, session: nil, tool_resolver: DEFAULT_TOOL_RESOLVER, tool_runtime: nil)
  from_h(JSON.parse(json, symbolize_names: true), context: context, session: session, tool_resolver: tool_resolver, tool_runtime: tool_runtime)
end

Reconstructs a runnable agent from a JSON string produced by to_json. See from_h for the arguments.

to_h (agent:)

Source

# File lib/riffer/agent/serializer.rb, line 31
def to_h(agent:)
  config = agent.config
  {
    schema_version: SCHEMA_VERSION,
    riffer_version: Riffer::VERSION,
    identifier: config.identifier,
    model: "#{agent.provider_name}/#{agent.model_name}",
    instructions: agent.instruction_message&.content,
    model_options: config.model_options,
    provider_options: config.provider_options,
    max_steps: encode_max_steps(config.max_steps),
    structured_output: config.structured_output&.to_json_schema(strict: false),
    tools: agent.tools.map { |tool_class| tool_descriptor(tool_class) }
  }
end

Snapshots a resolved agent into a self-contained wire hash. Proc-based settings are already evaluated against the agent’s context, so the hash carries plain data, never Procs.

to_json (agent:)

Source

# File lib/riffer/agent/serializer.rb, line 69
def to_json(agent:)
  JSON.generate(to_h(agent: agent))
end

Snapshots a resolved agent to a JSON string.