agent_runtime 0.2.0

data/lib/agent_runtime/fsm.rb

@@ -0,0 +1,213 @@
+# frozen_string_literal: true
+
+module AgentRuntime
+  # Formal Finite State Machine for agentic workflows.
+  #
+  # Implements the canonical agentic workflow FSM with 8 states:
+  # - INTAKE: Normalize input, initialize state
+  # - PLAN: Single-shot planning using /generate
+  # - DECIDE: Make bounded decision (continue vs stop)
+  # - EXECUTE: LLM proposes next actions using /chat (looping state)
+  # - OBSERVE: Execute tools, inject real-world results
+  # - LOOP_CHECK: Control continuation
+  # - FINALIZE: Produce terminal output (terminal state)
+  # - HALT: Abort safely (terminal state)
+  #
+  # Valid state transitions:
+  # - INTAKE → PLAN
+  # - PLAN → DECIDE | HALT
+  # - DECIDE → EXECUTE | FINALIZE | HALT
+  # - EXECUTE → OBSERVE | FINALIZE | HALT
+  # - OBSERVE → LOOP_CHECK
+  # - LOOP_CHECK → EXECUTE | FINALIZE | HALT
+  # - FINALIZE → (terminal)
+  # - HALT → (terminal)
+  #
+  # @example Initialize and use FSM
+  #   fsm = FSM.new(max_iterations: 100)
+  #   fsm.transition_to(FSM::STATES[:PLAN], reason: "Starting")
+  #   fsm.plan?  # => true
+  #
+  # @see AgentFSM
+  class FSM
+    # State constants mapping state names to integer values.
+    #
+    # @return [Hash<Symbol, Integer>] Hash of state names to integer values
+    STATES = {
+      INTAKE: 0,
+      PLAN: 1,
+      DECIDE: 2,
+      EXECUTE: 3,
+      OBSERVE: 4,
+      LOOP_CHECK: 5,
+      FINALIZE: 6,
+      HALT: 7
+    }.freeze
+
+    # Terminal states that cannot transition to other states.
+    #
+    # @return [Array<Integer>] Array of terminal state values
+    TERMINAL_STATES = [STATES[:FINALIZE], STATES[:HALT]].freeze
+
+    # Valid state transitions based on FSM specification.
+    #
+    # Maps each state to an array of valid next states.
+    #
+    # @return [Hash<Integer, Array<Integer>>] Hash mapping state values to arrays of valid next states
+    VALID_TRANSITIONS = {
+      STATES[:INTAKE] => [STATES[:PLAN]],
+      STATES[:PLAN] => [STATES[:DECIDE], STATES[:HALT]],
+      STATES[:DECIDE] => [STATES[:EXECUTE], STATES[:FINALIZE], STATES[:HALT]],
+      STATES[:EXECUTE] => [STATES[:OBSERVE], STATES[:FINALIZE], STATES[:HALT]],
+      STATES[:OBSERVE] => [STATES[:LOOP_CHECK]],
+      STATES[:LOOP_CHECK] => [STATES[:EXECUTE], STATES[:FINALIZE], STATES[:HALT]],
+      STATES[:FINALIZE] => [],
+      STATES[:HALT] => []
+    }.freeze
+
+    # Initialize a new FSM instance.
+    #
+    # @param max_iterations [Integer] Maximum number of iterations before raising an error (default: 50)
+    def initialize(max_iterations: 50)
+      @state = STATES[:INTAKE]
+      @max_iterations = max_iterations
+      @iteration_count = 0
+      @history = []
+    end
+
+    # @!attribute [r] state
+    #   @return [Integer] Current state value
+    # @!attribute [r] iteration_count
+    #   @return [Integer] Current iteration count
+    # @!attribute [r] history
+    #   @return [Array<Hash>] Array of transition history entries with :from, :to, :reason, :iteration
+    attr_reader :state, :iteration_count, :history
+
+    # Check if current state is INTAKE.
+    #
+    # @return [Boolean] True if in INTAKE state
+    def intake?
+      @state == STATES[:INTAKE]
+    end
+
+    # Check if current state is PLAN.
+    #
+    # @return [Boolean] True if in PLAN state
+    def plan?
+      @state == STATES[:PLAN]
+    end
+
+    # Check if current state is DECIDE.
+    #
+    # @return [Boolean] True if in DECIDE state
+    def decide?
+      @state == STATES[:DECIDE]
+    end
+
+    # Check if current state is EXECUTE.
+    #
+    # @return [Boolean] True if in EXECUTE state
+    def execute?
+      @state == STATES[:EXECUTE]
+    end
+
+    # Check if current state is OBSERVE.
+    #
+    # @return [Boolean] True if in OBSERVE state
+    def observe?
+      @state == STATES[:OBSERVE]
+    end
+
+    # Check if current state is LOOP_CHECK.
+    #
+    # @return [Boolean] True if in LOOP_CHECK state
+    def loop_check?
+      @state == STATES[:LOOP_CHECK]
+    end
+
+    # Check if current state is FINALIZE.
+    #
+    # @return [Boolean] True if in FINALIZE state
+    def finalize?
+      @state == STATES[:FINALIZE]
+    end
+
+    # Check if current state is HALT.
+    #
+    # @return [Boolean] True if in HALT state
+    def halt?
+      @state == STATES[:HALT]
+    end
+
+    # Check if current state is terminal (FINALIZE or HALT).
+    #
+    # @return [Boolean] True if in a terminal state
+    def terminal?
+      TERMINAL_STATES.include?(@state)
+    end
+
+    # Transition to a new state.
+    #
+    # Validates the transition and records it in history.
+    #
+    # @param new_state [Integer] The state value to transition to
+    # @param reason [String, nil] Optional reason for the transition (recorded in history)
+    # @return [void]
+    # @raise [ExecutionError] If the transition is invalid
+    #
+    # @example
+    #   fsm.transition_to(FSM::STATES[:PLAN], reason: "Input normalized")
+    def transition_to(new_state, reason: nil)
+      validate_transition(@state, new_state)
+      @history << { from: @state, to: new_state, reason: reason, iteration: @iteration_count }
+      @state = new_state
+    end
+
+    # Increment the iteration count.
+    #
+    # @return [void]
+    # @raise [MaxIterationsExceeded] If iteration count exceeds maximum
+    def increment_iteration
+      @iteration_count += 1
+      raise MaxIterationsExceeded, "Max iterations (#{@max_iterations}) exceeded" if @iteration_count > @max_iterations
+    end
+
+    # Reset the FSM to initial state.
+    #
+    # Resets state to INTAKE, clears iteration count and history.
+    #
+    # @return [void]
+    def reset
+      @state = STATES[:INTAKE]
+      @iteration_count = 0
+      @history = []
+    end
+
+    # Get the name of the current state.
+    #
+    # @return [Symbol, String] State name symbol or "UNKNOWN" if state value is invalid
+    def state_name
+      STATES.key(@state) || "UNKNOWN"
+    end
+
+    # Validate a state transition.
+    #
+    # @param from [Integer] The source state value
+    # @param to [Integer] The target state value
+    # @return [void]
+    # @raise [ExecutionError] If the transition is invalid
+    def validate_transition(from, to)
+      return if VALID_TRANSITIONS[from]&.include?(to)
+
+      raise ExecutionError, "Invalid transition from #{state_name_for(from)} to #{state_name_for(to)}"
+    end
+
+    # Get the name for a state value.
+    #
+    # @param state_value [Integer] The state value
+    # @return [Symbol, String] State name symbol or "UNKNOWN" if state value is invalid
+    def state_name_for(state_value)
+      STATES.key(state_value) || "UNKNOWN"
+    end
+  end
+end

data/lib/agent_runtime/planner.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module AgentRuntime
+  # LLM interface for planning and execution.
+  #
+  # Provides methods for interacting with the LLM client:
+  # - {#plan}: Single-shot planning using /generate endpoint
+  # - {#chat}: Chat-based execution returning content
+  # - {#chat_raw}: Chat-based execution returning full response with tool calls
+  #
+  # @example Initialize with schema and prompt builder
+  #   schema = { type: "object", properties: { action: { type: "string" } } }
+  #   builder = ->(input:, state:) { "Plan: #{input}" }
+  #   planner = Planner.new(client: ollama_client, schema: schema, prompt_builder: builder)
+  #
+  # @example Planning a decision
+  #   decision = planner.plan(input: "What should I do?", state: state.snapshot)
+  #   # => #<AgentRuntime::Decision action="search", params={...}>
+  class Planner
+    # Initialize a new Planner instance.
+    #
+    # @param client [#generate, #chat, #chat_raw] The LLM client (e.g., OllamaClient)
+    # @param schema [Hash, nil] Optional JSON schema for structured generation (required for #plan)
+    # @param prompt_builder [Proc, nil] Optional proc to build prompts (required for #plan).
+    #   Called as `prompt_builder.call(input: input, state: state)`
+    def initialize(client:, schema: nil, prompt_builder: nil)
+      @client = client
+      @schema = schema
+      @prompt_builder = prompt_builder
+    end
+
+    # PLAN state: Single-shot planning using /generate.
+    #
+    # Returns a structured {Decision} object based on the LLM's response.
+    # This method never loops and is used for one-shot planning decisions.
+    #
+    # @param input [String] The input prompt for planning
+    # @param state [Hash] The current state snapshot
+    # @return [Decision] A structured decision with action, params, and optional confidence
+    # @raise [ExecutionError] If schema or prompt_builder are not configured
+    #
+    # @example
+    #   decision = planner.plan(input: "What should I do next?", state: { step: 1 })
+    #   # => #<AgentRuntime::Decision action="search", params={query: "..."}, confidence=0.9>
+    def plan(input:, state:)
+      raise ExecutionError, "Planner requires schema and prompt_builder for plan" unless @schema && @prompt_builder
+
+      prompt = @prompt_builder.call(input: input, state: state)
+      raw = @client.generate(prompt: prompt, schema: @schema)
+
+      Decision.new(**raw.transform_keys(&:to_sym))
+    end
+
+    # EXECUTE state: Chat-based execution using /chat.
+    #
+    # Returns content by default (for simple responses without tool calls).
+    # Use this when you only need the text response from the LLM.
+    #
+    # Additional keyword arguments are passed through to the client.
+    #
+    # @param messages [Array<Hash>] Array of message hashes with :role and :content
+    # @param tools [Array<Hash>, nil] Optional array of tool definitions
+    # @return [String, Hash] The chat response content (format depends on client)
+    #
+    # @example
+    #   messages = [{ role: "user", content: "Hello" }]
+    #   response = planner.chat(messages: messages)
+    #   # => "Hello! How can I help you?"
+    def chat(messages:, tools: nil, **)
+      @client.chat(messages: messages, tools: tools, allow_chat: true, **)
+    end
+
+    # EXECUTE state: Chat with full response (for tool calling).
+    #
+    # Returns full response including tool_calls. Use this when you need
+    # to extract tool calls from the LLM's response.
+    #
+    # Additional keyword arguments are passed through to the client.
+    #
+    # @param messages [Array<Hash>] Array of message hashes with :role and :content
+    # @param tools [Array<Hash>, nil] Optional array of tool definitions
+    # @return [Hash] Full response hash including message and tool_calls
+    #
+    # @example
+    #   messages = [{ role: "user", content: "Search for weather" }]
+    #   tools = [{ type: "function", function: { name: "search", ... } }]
+    #   response = planner.chat_raw(messages: messages, tools: tools)
+    #   # => { message: { content: "...", tool_calls: [...] } }
+    def chat_raw(messages:, tools: nil, **)
+      @client.chat_raw(messages: messages, tools: tools, allow_chat: true, **)
+    end
+  end
+end

data/lib/agent_runtime/policy.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module AgentRuntime
+  # Validates agent decisions before execution.
+  #
+  # This class enforces policy constraints on decisions made by the planner.
+  # By default, it validates that:
+  # - The decision has an action
+  # - The confidence (if present) is at least 0.5
+  #
+  # Subclass this to implement custom validation logic.
+  #
+  # @example Basic usage
+  #   policy = Policy.new
+  #   policy.validate!(decision, state: state)
+  #
+  # @example Custom policy subclass
+  #   class CustomPolicy < Policy
+  #     def validate!(decision, state:)
+  #       super
+  #       raise PolicyViolation, "Action not allowed" if decision.action == "delete"
+  #     end
+  #   end
+  class Policy
+    # Validate a decision against policy constraints.
+    #
+    # @param decision [Decision] The decision to validate
+    # @param state [State, Hash, nil] The current state (unused in default implementation)
+    # @return [void]
+    # @raise [PolicyViolation] If the decision violates policy constraints:
+    #   - Missing action
+    #   - Confidence below 0.5 (if confidence is present)
+    #
+    # @example
+    #   policy.validate!(decision, state: state)
+    #   # => nil (raises PolicyViolation on failure)
+    def validate!(decision, state: nil) # rubocop:disable Lint/UnusedMethodArgument
+      raise PolicyViolation, "Missing action" unless decision.action
+      raise PolicyViolation, "Low confidence" if decision.confidence && decision.confidence < 0.5
+    end
+  end
+end

data/lib/agent_runtime/state.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module AgentRuntime
+  # Explicit, serializable state management with deep merge support.
+  #
+  # This class manages the agent's state throughout execution. State is stored
+  # as a hash and can be snapshotted for read-only access. Updates are applied
+  # using deep merge to preserve nested structures.
+  #
+  # @example Initialize with initial data
+  #   state = State.new({ step: 1, context: { user: "Alice" } })
+  #
+  # @example Take a snapshot
+  #   snapshot = state.snapshot
+  #   # => { step: 1, context: { user: "Alice" } }
+  #
+  # @example Apply updates
+  #   state.apply!({ step: 2, context: { task: "search" } })
+  #   state.snapshot
+  #   # => { step: 2, context: { user: "Alice", task: "search" } }
+  class State
+    # Initialize a new State instance.
+    #
+    # @param data [Hash] Initial state data (default: {})
+    def initialize(data = {})
+      @data = data
+    end
+
+    # Create a snapshot of the current state.
+    #
+    # Returns a shallow copy of the state data. Modifications to the snapshot
+    # will not affect the original state.
+    #
+    # @return [Hash] A copy of the current state data
+    #
+    # @example
+    #   snapshot = state.snapshot
+    #   snapshot[:new_key] = "value"  # Does not modify state
+    def snapshot
+      @data.dup
+    end
+
+    # Apply a result hash to the state using deep merge.
+    #
+    # Merges the result hash into the current state, preserving nested structures.
+    # If result is not a hash, this method does nothing.
+    #
+    # @param result [Hash, Object] The result to merge into state (must be a Hash to apply)
+    # @return [void]
+    #
+    # @example
+    #   state = State.new({ a: 1, nested: { x: 10 } })
+    #   state.apply!({ b: 2, nested: { y: 20 } })
+    #   state.snapshot
+    #   # => { a: 1, b: 2, nested: { x: 10, y: 20 } }
+    def apply!(result)
+      return unless result.is_a?(Hash)
+
+      deep_merge!(@data, result)
+    end
+
+    private
+
+    # Deep merge source hash into target hash.
+    #
+    # Recursively merges nested hashes, overwriting non-hash values.
+    #
+    # @param target [Hash] The target hash to merge into (modified in place)
+    # @param source [Hash] The source hash to merge from
+    # @return [void]
+    def deep_merge!(target, source)
+      source.each do |key, value|
+        if target[key].is_a?(Hash) && value.is_a?(Hash)
+          deep_merge!(target[key], value)
+        else
+          target[key] = value
+        end
+      end
+    end
+  end
+end

data/lib/agent_runtime/tool_registry.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module AgentRuntime
+  # Registry mapping tool names to Ruby callables.
+  #
+  # This class maintains a registry of available tools that can be called
+  # by the executor. Tools are registered as callable objects (procs, lambdas, or objects responding to #call).
+  #
+  # @example Initialize with tools
+  #   tools = {
+  #     "search" => ->(query:) { "Results for #{query}" },
+  #     "calculate" => Calculator.new
+  #   }
+  #   registry = ToolRegistry.new(tools)
+  #
+  # @example Call a tool
+  #   result = registry.call("search", { query: "weather" })
+  #   # => "Results for weather"
+  class ToolRegistry
+    # Initialize a new ToolRegistry instance.
+    #
+    # @param tools [Hash<String, #call>] Hash mapping tool names to callable objects
+    #
+    # @example
+    #   registry = ToolRegistry.new({
+    #     "search" => ->(query:) { search_api(query) },
+    #     "email" => EmailTool.new
+    #   })
+    def initialize(tools = {})
+      @tools = tools
+    end
+
+    # Call a tool by name with the given parameters.
+    #
+    # @param action [String, Symbol] The name of the tool to call
+    # @param params [Hash] Parameters to pass to the tool (will be keyword-argument expanded)
+    # @return [Object] The result of calling the tool
+    # @raise [ToolNotFound] If the tool is not registered
+    #
+    # @example
+    #   result = registry.call("search", { query: "weather", limit: 10 })
+    #   # Calls: search_tool.call(query: "weather", limit: 10)
+    def call(action, params)
+      tool = @tools[action]
+      raise ToolNotFound, "Tool not found: #{action}" unless tool
+
+      tool.call(**params)
+    end
+  end
+end

data/lib/agent_runtime/version.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module AgentRuntime
+  # Current version of the AgentRuntime gem.
+  #
+  # @return [String] Version string in semantic versioning format
+  VERSION = "0.2.0"
+end

data/lib/agent_runtime.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require "ollama_client"
+
+require_relative "agent_runtime/version"
+require_relative "agent_runtime/agent"
+require_relative "agent_runtime/agent_fsm"
+require_relative "agent_runtime/planner"
+require_relative "agent_runtime/policy"
+require_relative "agent_runtime/executor"
+require_relative "agent_runtime/state"
+require_relative "agent_runtime/decision"
+require_relative "agent_runtime/tool_registry"
+require_relative "agent_runtime/audit_log"
+require_relative "agent_runtime/errors"
+require_relative "agent_runtime/fsm"
+
+# AgentRuntime provides a deterministic, policy-driven runtime for building
+# tool-using LLM agents with explicit state, policy enforcement, and auditability.
+#
+# The library provides two main agent implementations:
+# - {Agent}: Simple step-by-step execution with multi-step loops
+# - {AgentFSM}: Formal finite state machine implementation following the canonical agentic workflow
+#
+# @example Basic usage with Agent
+#   planner = AgentRuntime::Planner.new(client: ollama_client, schema: schema, prompt_builder: builder)
+#   policy = AgentRuntime::Policy.new
+#   executor = AgentRuntime::Executor.new(tool_registry: tools)
+#   state = AgentRuntime::State.new
+#   agent = AgentRuntime::Agent.new(planner: planner, policy: policy, executor: executor, state: state)
+#   result = agent.run(initial_input: "What is the weather?")
+#
+# @example Using AgentFSM for formal workflows
+#   agent_fsm = AgentRuntime::AgentFSM.new(
+#     planner: planner,
+#     policy: policy,
+#     executor: executor,
+#     state: state,
+#     tool_registry: tools
+#   )
+#   result = agent_fsm.run(initial_input: "Analyze this data")
+#
+# @see Agent
+# @see AgentFSM
+# @see Planner
+# @see Policy
+# @see Executor
+# @see State
+# @see ToolRegistry
+module AgentRuntime
+end

metadata

@@ -0,0 +1,72 @@
+--- !ruby/object:Gem::Specification
+name: agent_runtime
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: ruby
+authors:
+- Shubham Taywade
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ollama-client
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+description: AgentRuntime provides a reusable control plane for building tool-using
+  LLM agents with explicit state, policy enforcement, and auditability.
+email:
+- shubhamtaywade82@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/agent_runtime.rb
+- lib/agent_runtime/agent.rb
+- lib/agent_runtime/agent_fsm.rb
+- lib/agent_runtime/audit_log.rb
+- lib/agent_runtime/decision.rb
+- lib/agent_runtime/errors.rb
+- lib/agent_runtime/executor.rb
+- lib/agent_runtime/fsm.rb
+- lib/agent_runtime/planner.rb
+- lib/agent_runtime/policy.rb
+- lib/agent_runtime/state.rb
+- lib/agent_runtime/tool_registry.rb
+- lib/agent_runtime/version.rb
+homepage: https://github.com/shubhamtaywade/agent-runtime
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.3
+specification_version: 4
+summary: Deterministic, policy-driven runtime for safe LLM agents
+test_files: []