agent_runtime 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d60d801b991450361a87cd0ae9ed9d254f58f836f3bfadeff35c52696f4ac38d
+  data.tar.gz: b8dbd1232137bd1b8746fb8772f27f2ab4664923dc3370e5be1c702875f0abf3
+SHA512:
+  metadata.gz: 87aeb7ede07631a7dc9bedf7db9549e7504a16dadc5d90818be64be67df1ddcd332fe2bf50889a7cfad5184da1f2a4a575d5f145f752b0a40eb770b7eb1ad4d8
+  data.tar.gz: b2b7fcf7d975a8faf5398fe17ba47d5682bf7fdec2a288497cf85497c9709f4eb2dbac9ac0d844777c897a032d175075c6741e57aaf2868aec7f2c554445db5c

data/CHANGELOG.md

@@ -0,0 +1,25 @@
+## [Unreleased]
+
+## [0.2.0] - 2026-01-XX
+
+### Fixed
+- FSM finalization now properly executes `handle_finalize` or `handle_halt` before returning
+- Agent#run now always returns the last tool result when terminating
+- Tool call argument parsing now handles JSON parse failures gracefully
+- Audit logging now handles nil decisions without crashing
+
+### Changed
+- Removed domain-specific code (DhanHQ helpers) from `lib/` directory
+- Planning contract for FSM is now documented and consistent
+- Tool calls are now enabled in FSM with basic tool definition conversion
+- State#apply! now performs deep merge of nested hashes
+- Removed hardcoded local paths from examples (now uses environment variables)
+
+### Documentation
+- Updated README to remove references to deleted console helpers
+- Fixed documentation to match actual behavior
+- Removed CONSOLE_TESTING.md (domain-specific content)
+
+## [0.1.0] - 2026-01-15
+
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Shubham Taywade
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,234 @@
+# AgentRuntime
+
+Deterministic, policy-driven runtime for tool-using LLM agents in Ruby.
+
+AgentRuntime is a control plane. It coordinates planning, policy validation,
+tool execution, and explicit state. It does not ship domain logic.
+
+## What this gem is
+- A small runtime to coordinate LLM decisions with Ruby tool execution.
+- A formal FSM workflow (`AgentFSM`) with explicit states and history.
+
+## What this gem is not
+- Not a domain toolkit (no broker APIs, HTTP clients, or storage).
+- Not a prompt library.
+- Not a memory system.
+
+## Strict usage rules (non-negotiable)
+- Use `/generate` only for planning/decision outputs (`Planner#plan`).
+- Use `/chat` only during execution/finalization (`Planner#chat_raw`, `Planner#chat`).
+- The LLM never executes tools. Tools are Ruby callables and run in `Executor`.
+- Tool results are injected as `role: "tool"` messages only after execution.
+- Only `EXECUTE` loops. All other states are single-shot.
+- Termination happens only on explicit signals:
+  `decision.action == "finish"`, `result[:done] == true`, or `MaxIterationsExceeded`.
+- This gem does not add retries or streaming. Retry/streaming policy lives in
+  `ollama-client`.
+
+If you violate any rule above, you are not using this gem correctly.
+
+## Narrative overview (kept here, kept strict)
+AgentRuntime is a domain-agnostic runtime that separates reasoning from
+authority:
+- LLM reasoning happens via `Planner` only.
+- Ruby owns policy and execution.
+- Tools are gated and executed outside the LLM.
+- State is explicit and inspectable.
+- Failures are visible via explicit errors and optional audit logs.
+
+Architecture (conceptual):
+Your application → AgentRuntime → `ollama-client` → Ollama server
+
+This overview is informative only. The strict rules above are the contract.
+
+## Core components (SRP map)
+- `Planner`: LLM interface (`generate`, `chat`, `chat_raw`). No tools. No side effects.
+- `Policy`: validates decisions before execution.
+- `Executor`: executes tools via `ToolRegistry` only.
+- `ToolRegistry`: maps tool names to Ruby callables.
+- `State`: explicit, serializable state.
+- `Agent`: simple decision loop using `Planner#plan` and tools.
+- `AgentFSM`: formal FSM with explicit states and transition history.
+- `AuditLog`: optional logging of decisions and results.
+
+## API mapping
+| Concern | Method | LLM endpoint | Where it belongs |
+| --- | --- | --- | --- |
+| Planning / decisions | `Planner#plan` | `/api/generate` | PLAN |
+| Execution / tool calls | `Planner#chat_raw` | `/api/chat` | EXECUTE |
+| Final response (optional) | `Planner#chat` | `/api/chat` | FINALIZE |
+
+`Executor` never calls the LLM.
+
+## Prerequisites
+`agent_runtime` depends on `ollama-client`. See `PREREQUISITES.md`.
+
+## Installation
+Add this line to your application's Gemfile:
+
+```ruby
+gem "agent_runtime"
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem install agent_runtime
+```
+
+## Usage
+
+### Single-step agent (`Agent#step`)
+Use this for one-shot decisions or when you control the loop externally.
+
+```ruby
+require "agent_runtime"
+require "ollama_client"
+
+tools = AgentRuntime::ToolRegistry.new({
+  "fetch" => ->(**args) { { data: "fetched", args: args } },
+  "execute" => ->(**args) { { result: "executed", args: args } }
+})
+
+client = Ollama::Client.new
+
+schema = {
+  "type" => "object",
+  "required" => ["action", "params", "confidence"],
+  "properties" => {
+    "action" => { "type" => "string", "enum" => ["fetch", "execute", "finish"] },
+    "params" => { "type" => "object", "additionalProperties" => true },
+    "confidence" => { "type" => "number", "minimum" => 0, "maximum" => 1 }
+  }
+}
+
+planner = AgentRuntime::Planner.new(
+  client: client,
+  schema: schema,
+  prompt_builder: ->(input:, state:) {
+    "User request: #{input}\nContext: #{state.to_json}"
+  }
+)
+
+agent = AgentRuntime::Agent.new(
+  planner: planner,
+  policy: AgentRuntime::Policy.new,
+  executor: AgentRuntime::Executor.new(tool_registry: tools),
+  state: AgentRuntime::State.new,
+  audit_log: AgentRuntime::AuditLog.new
+)
+
+result = agent.step(input: "Fetch market data for AAPL")
+puts result.inspect
+```
+
+### Multi-step loop (`Agent#run`)
+Use this when the agent should iterate until it emits `finish` or a tool marks
+`done: true`. This loop uses `/generate` only (no chat).
+
+```ruby
+result = agent.run(initial_input: "Find best PDF library for Ruby")
+```
+
+### Formal FSM workflow (`AgentFSM`)
+`AgentFSM` is the explicit FSM driver. It uses `/generate` for PLAN and
+`/chat` for EXECUTE. Tool execution happens only in OBSERVE.
+
+Tool calling in EXECUTE requires Ollama tool definitions. This gem does not
+auto-convert `ToolRegistry` entries to `Ollama::Tool` objects. If you need tool
+calling, subclass `AgentFSM` and return tool definitions from
+`build_tools_for_chat`.
+
+```ruby
+class MyAgentFSM < AgentRuntime::AgentFSM
+  def build_tools_for_chat
+    # Return Ollama::Tool definitions here
+    []
+  end
+end
+
+agent_fsm = MyAgentFSM.new(
+  planner: planner,
+  policy: AgentRuntime::Policy.new,
+  executor: AgentRuntime::Executor.new(tool_registry: tools),
+  state: AgentRuntime::State.new,
+  tool_registry: tools,
+  audit_log: AgentRuntime::AuditLog.new
+)
+
+result = agent_fsm.run(initial_input: "Research Ruby memory management")
+```
+
+## Tool safety model
+- Tools are Ruby callables registered in `ToolRegistry`.
+- LLM output never executes tools directly.
+- Tool execution happens only in `Executor`.
+- Tool results are recorded in state and (for FSM) injected as `role: "tool"`.
+
+## Examples
+
+### Quick Start
+**Start here**: `examples/complete_working_example.rb` - A complete, runnable example demonstrating all features.
+
+```bash
+# Make sure Ollama is running: ollama serve
+ruby examples/complete_working_example.rb
+```
+
+### Available Examples
+- `examples/complete_working_example.rb` ⭐ - **Complete working example** (recommended starting point)
+- `examples/fixed_console_example.rb` - Minimal example for console use
+- `examples/console_example.rb` - Basic console example
+- `examples/rails_example/` - Rails integration example
+- `examples/dhanhq_example.rb` - Domain-specific example (requires DhanHQ gem)
+
+See `examples/README.md` for detailed documentation on all examples.
+
+Examples are not part of the public API.
+
+## Documentation
+- `AGENTIC_WORKFLOWS.md`
+- `FSM_WORKFLOWS.md`
+- `SCHEMA_GUIDE.md`
+- `PREREQUISITES.md`
+
+## Development
+After checking out the repo, run:
+
+```bash
+bin/setup
+```
+
+To run tests:
+
+```bash
+rake spec
+# or
+bundle exec rspec
+```
+
+Test coverage reports are generated automatically. View the HTML report:
+```bash
+open coverage/index.html  # macOS
+xdg-open coverage/index.html  # Linux
+```
+
+See `TESTING.md` for detailed testing and coverage information.
+
+To run the console:
+
+```bash
+bin/console
+```
+
+## Contributing
+Bug reports and pull requests are welcome. Keep the API strict and small.
+
+## License
+The gem is available as open source under the terms of the MIT License.

data/lib/agent_runtime/agent.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+module AgentRuntime
+  # Simple agent implementation with step-by-step execution and multi-step loops.
+  #
+  # This class provides a straightforward agent implementation that executes
+  # planning, validation, and execution steps in a loop until termination.
+  # Use this for simpler workflows where you don't need the full FSM structure.
+  #
+  # @example Single step execution
+  #   agent = AgentRuntime::Agent.new(planner: planner, policy: policy, executor: executor, state: state)
+  #   result = agent.step(input: "What is 2+2?")
+  #
+  # @example Multi-step agentic workflow
+  #   agent = AgentRuntime::Agent.new(planner: planner, policy: policy, executor: executor, state: state)
+  #   result = agent.run(initial_input: "Find the weather and send an email")
+  class Agent
+    # Initialize a new Agent instance.
+    #
+    # @param planner [Planner] The planner responsible for generating decisions
+    # @param policy [Policy] The policy validator for decisions
+    # @param executor [Executor] The executor for tool calls
+    # @param state [State] The state manager for agent state
+    # @param audit_log [AuditLog, nil] Optional audit logger for recording decisions
+    # @param max_iterations [Integer] Maximum number of iterations before raising an error (default: 50)
+    def initialize(planner:, policy:, executor:, state:, audit_log: nil, max_iterations: 50)
+      @planner = planner
+      @policy = policy
+      @executor = executor
+      @state = state
+      @audit_log = audit_log
+      @max_iterations = max_iterations
+    end
+
+    # Single step execution (non-agentic).
+    #
+    # Use this for one-shot decisions or when you control the loop externally.
+    # This method performs a single planning, validation, execution, and state update cycle.
+    #
+    # @param input [String] The input prompt for this step
+    # @return [Hash] The execution result hash
+    # @raise [PolicyViolation] If the decision violates policy constraints
+    # @raise [ExecutionError] If execution fails
+    #
+    # @example
+    #   result = agent.step(input: "Calculate 5 * 10")
+    #   # => { result: 50 }
+    def step(input:)
+      decision = @planner.plan(
+        input: input,
+        state: @state.snapshot
+      )
+
+      @policy.validate!(decision, state: @state)
+
+      result = @executor.execute(decision, state: @state)
+
+      @state.apply!(result)
+
+      @audit_log&.record(
+        input: input,
+        decision: decision,
+        result: result
+      )
+
+      result
+    end
+
+    # Agentic workflow loop (runs until termination).
+    #
+    # Use this for multi-step workflows where the agent decides when to stop.
+    # The loop continues until:
+    # - The decision action is "finish"
+    # - The result contains `done: true`
+    # - Maximum iterations are exceeded
+    #
+    # @param initial_input [String] The initial input to start the workflow
+    # @param input_builder [Proc, nil] Optional proc to build next input from result and iteration.
+    #   Called as `input_builder.call(result, iteration)`. If nil, uses default builder.
+    # @return [Hash] Final result hash, always includes `done: true` and `iterations` count
+    # @raise [MaxIterationsExceeded] If maximum iterations are exceeded
+    # @raise [PolicyViolation] If any decision violates policy constraints
+    # @raise [ExecutionError] If execution fails
+    #
+    # @example
+    #   result = agent.run(initial_input: "Find weather and send email")
+    #   # => { done: true, iterations: 3, ... }
+    #
+    # @example With custom input builder
+    #   builder = ->(result, iteration) { "Iteration #{iteration}: #{result.inspect}" }
+    #   result = agent.run(initial_input: "Start", input_builder: builder)
+    def run(initial_input:, input_builder: nil)
+      iteration = 0
+      current_input = initial_input
+      final_result = nil
+
+      loop do
+        iteration += 1
+
+        raise MaxIterationsExceeded, "Max iterations (#{@max_iterations}) exceeded" if iteration > @max_iterations
+
+        decision = @planner.plan(
+          input: current_input,
+          state: @state.snapshot
+        )
+
+        @policy.validate!(decision, state: @state)
+
+        result = @executor.execute(decision, state: @state)
+
+        @state.apply!(result)
+
+        @audit_log&.record(
+          input: current_input,
+          decision: decision,
+          result: result
+        )
+
+        # Always set final_result before checking termination
+        final_result = result
+
+        break if terminated?(decision, result)
+
+        current_input = input_builder ? input_builder.call(result, iteration) : build_next_input(result, iteration)
+      end
+
+      final_result || { done: true, iterations: iteration }
+    end
+
+    private
+
+    # Check if the agent should terminate based on decision and result.
+    #
+    # @param decision [Decision] The current decision
+    # @param result [Hash] The execution result
+    # @return [Boolean] True if the agent should terminate
+    def terminated?(decision, result)
+      decision.action == "finish" || result[:done] == true
+    end
+
+    # Build the next input for the loop iteration.
+    #
+    # @param result [Hash] The previous execution result
+    # @param _iteration [Integer] The current iteration number (unused)
+    # @return [String] The next input string
+    def build_next_input(result, _iteration)
+      "Continue based on: #{result.inspect}"
+    end
+  end
+end