Module: Riffer::Agent::Serializer

Extended by:
Serializer
Included in:
Riffer, Serializer
Defined in:
lib/riffer/agent/serializer.rb

Overview

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"})

Defined Under Namespace

Classes: VersionError

Constant Summary collapse

SCHEMA_VERSION =

The wire format version, bumped only on an incompatible change to the hash shape; from_h refuses any other version.

1
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.

->(descriptor) { build_tool_shell(descriptor) }

Instance Method Summary collapse

Instance Method Details

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

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.

--

Signature:

  • (Hash[Symbol, untyped], ?context: Hash[Symbol, untyped]?, ?session: Riffer::Agent::Session?, ?tool_resolver: ^(Hash[Symbol, untyped]) -> singleton(Riffer::Tool), ?tool_runtime: (singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc)?) -> Riffer::Agent



55
56
57
58
59
60
61
62
63
64
 
# 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

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

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

Signature:

  • (String, ?context: Hash[Symbol, untyped]?, ?session: Riffer::Agent::Session?, ?tool_resolver: ^(Hash[Symbol, untyped]) -> singleton(Riffer::Tool), ?tool_runtime: (singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc)?) -> Riffer::Agent



77
78
79
 
# 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

#to_h(agent:) ⇒ Object

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.

Signature:

  • (agent: Riffer::Agent) -> Hash[Symbol, untyped]



31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
 
# 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

#to_json(agent:) ⇒ Object

Snapshots a resolved agent to a JSON string.

Signature:

  • (agent: Riffer::Agent) -> String



69
70
71
 
# File 'lib/riffer/agent/serializer.rb', line 69

def to_json(agent:)
  JSON.generate(to_h(agent: agent))
end