terret-core 0.1.0 → 0.1.1

data/lib/terret/llm.rb

@@ -16,16 +16,89 @@ module Terret
     # Stream events yielded by adapters.
     TextDelta   = Data.define(:text)
     ToolCallEnd = Data.define(:tool_call)
+    Usage       = Data.define(:prompt_tokens, :completion_tokens, :cost)
+    StreamError = Data.define(:message, :code) # surfaced mid-stream, then raised
     MessageStop = Data.define(:stop_reason) # :end_turn | :tool_use
 
+    # Storage codec for message parts. Durable logs hold only these primitive,
+    # storage-named hashes ("text", never Terret::LLM::Text), so a class
+    # rename can never invalidate stored sessions. decode(encode(p)) == p.
+    module_function
+
+    def encode_part(part)
+      case part
+      when Text       then { type: "text", text: part.text }
+      when ToolCall   then { type: "tool_call", id: part.id, name: part.name, args: part.args }
+      when ToolResult then { type: "tool_result", id: part.id, content: part.content, error: part.error }
+      else raise ArgumentError, "cannot encode #{part.class} as a message part"
+      end
+    end
+
+    def decode_part(hash)
+      case hash[:type]
+      when "text"        then Text.new(text: hash[:text])
+      when "tool_call"   then ToolCall.new(id: hash[:id], name: hash[:name], args: hash[:args])
+      when "tool_result" then ToolResult.new(id: hash[:id], content: hash[:content], error: hash[:error])
+      else raise ArgumentError, "unknown part tag #{hash[:type].inspect}"
+      end
+    end
+
+    # Adapter failures. Retryable covers 429/overload/5xx and transport drops
+    # before any bytes streamed; everything else raises through immediately.
+    class AdapterError < StandardError
+      attr_reader :status, :body
+
+      def initialize(message, status: nil, body: nil)
+        super(message)
+        @status = status
+        @body = body
+      end
+    end
+
+    class RetryableError < AdapterError; end
+
+    # Shared behaviour for real adapters: jittered exponential backoff around
+    # anything raising RetryableError. Sleeper is injectable for tests.
+    class AdapterBase
+      def initialize(max_attempts: 4, base_delay: 0.5, sleeper: ->(s) { sleep(s) })
+        @max_attempts = max_attempts
+        @base_delay = base_delay
+        @sleeper = sleeper
+      end
+
+      def with_retries
+        attempt = 0
+        begin
+          yield
+        rescue RetryableError
+          attempt += 1
+          raise if attempt >= @max_attempts
+
+          # equal jitter: uniform over (half, full] of base * 2^n
+          cap = @base_delay * (2**(attempt - 1))
+          @sleeper.call(cap * (0.5 + rand * 0.5))
+          retry
+        end
+      end
+    end
+
     # ctx.llm — the adapter seam. `llm/stream` is a waterfall wrapping every
     # request: middleware may rewrite the request or replace the stream.
     class Service < Hames::Service
       service_key :llm
+      config_schema roles: { type: Hash, default: {},
+                             doc: "role => \"provider/model\" map; an open set of roles" }
 
       def start(_ctx)
         @adapters = {}
-        @roles    = config[:roles] || {} # :main => "fake/scripted"
+        @roles    = (config[:roles] || {}).dup # :main => "fake/scripted"
+      end
+
+      # The role map is the whole of this service's config, and layering
+      # replaces a row's config wholesale — so does this. Registered adapters
+      # are runtime state, not config, and survive untouched.
+      def reconfigure(config)
+        @roles = (config[:roles] || {}).dup
       end
 
       def register_adapter(name, adapter)
@@ -39,6 +112,20 @@ module Terret
         [@adapters.fetch(provider), model]
       end
 
+      # §9.2 set_model lands here: repoint a role at a "provider/model" spec
+      # on the live service. Takes effect at the next step's resolve.
+      def set_role(role, spec)
+        raise ArgumentError, "role must be a name, got #{role.inspect}" unless role.respond_to?(:to_sym)
+
+        provider, model = spec.to_s.split("/", 2)
+        if provider.nil? || provider.empty? || model.nil? || model.empty?
+          raise ArgumentError, "model spec must be provider/model, got #{spec.inspect}"
+        end
+
+        @adapters.fetch(provider) { raise ArgumentError, "unknown provider #{provider.inspect}" }
+        @roles[role.to_sym] = spec.to_s
+      end
+
       # Streams the request through the `llm/stream` waterfall; the base of
       # the waterfall invokes the resolved adapter. Yields StreamEvents,
       # returns the final assistant Message.
@@ -52,7 +139,7 @@ module Terret
     end
 
     # Deterministic scripted adapter for tests, demos, and record/replay.
-    # Script: array of hashes { text:, tool_calls: [ToolCall, ...] }.
+    # Script: array of hashes { text:, tool_calls: [ToolCall, ...], usage: }.
     class FakeAdapter
       def initialize(script)
         @script = script.dup
@@ -70,6 +157,7 @@ module Terret
           yield ToolCallEnd.new(tool_call: tc)
           parts << tc
         end
+        yield Usage.new(**step[:usage]) if step[:usage]
         yield MessageStop.new(stop_reason: calls.empty? ? :end_turn : :tool_use)
         Message.new(role: :assistant, parts: parts)
       end