phronomy 0.6.0 → 0.7.0

data/lib/phronomy/state_store/in_memory.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module StateStore
+    # Thread-safe in-process state store backed by a plain Ruby Hash.
+    #
+    # Used as the recommended default for single-process applications and tests.
+    # State does not survive process restart.
+    #
+    # @example
+    #   store = Phronomy::StateStore::InMemory.new
+    #   store.save("t1", { fields: { count: 1 }, phase: "__end__" })
+    #   store.load("t1")   # => { fields: { count: 1 }, phase: "__end__" }
+    #   store.delete("t1")
+    #   store.load("t1")   # => nil
+    class InMemory < Base
+      def initialize
+        @data = {}
+        @mutex = Mutex.new
+      end
+
+      # @param thread_id [String]
+      # @return [Hash, nil]
+      # @api public
+      def load(thread_id)
+        @mutex.synchronize do
+          snap = @data[thread_id]
+          snap ? deep_dup(snap) : nil
+        end
+      end
+
+      # @param thread_id [String]
+      # @param snapshot [Hash]
+      # @return [void]
+      # @api public
+      def save(thread_id, snapshot)
+        @mutex.synchronize { @data[thread_id] = deep_dup(snapshot) }
+        nil
+      end
+
+      # @param thread_id [String]
+      # @return [void]
+      # @api public
+      def delete(thread_id)
+        @mutex.synchronize { @data.delete(thread_id) }
+        nil
+      end
+
+      private
+
+      # Recursively deep-duplicates a plain-data value (Hash, Array, or scalar).
+      # Sufficient for snapshot data which consists of JSON-compatible types.
+      def deep_dup(val)
+        case val
+        when Hash then val.each_with_object({}) { |(k, v), h| h[k] = deep_dup(v) }
+        when Array then val.map { |v| deep_dup(v) }
+        else val.frozen? ? val : (val.dup rescue val) # rubocop:disable Style/RescueModifier
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/tool/agent_tool.rb

@@ -35,6 +35,7 @@ module Phronomy
         # @param description  [String, nil] description exposed to the LLM;
         #   defaults to "Delegates to <AgentClassName>"
         # @return [Class] an anonymous Phronomy::Tool::AgentTool subclass
+        # @api public
         def from_agent(agent_class, tool_name: nil, description: nil)
           raise ArgumentError, "agent_class must be a Class" unless agent_class.is_a?(Class)
 

data/lib/phronomy/tool/base.rb

@@ -33,44 +33,90 @@ module Phronomy
         # When omitted, RubyLLM's default conversion applies (e.g. WeatherTool → "weather").
         #
         # @param value [String, nil] the exact function name the LLM will see
+        # @api public
         def tool_name(value = nil)
           return @tool_name if value.nil?
 
           @tool_name = value.to_s
         end
 
-        # Extends RubyLLM::Tool.param with an optional +enum:+ keyword.
-        # The enum values are stored separately and injected into the JSON Schema
-        # produced by #params_schema.
+        # Extends RubyLLM::Tool.param with optional +enum:+ and +properties:+ keywords.
+        # - +enum:+       restricts allowed values; injected into the JSON Schema.
+        # - +properties:+ declares nested fields for :object type params.  Each
+        #   entry is a Hash mapping field name (Symbol) to a spec Hash with keys:
+        #   :type (Symbol, default :string), :required (Boolean, default false),
+        #   and optionally :properties (for further nesting).
         #
         # @param name [Symbol] parameter name
-        # @param enum [Array, nil] allowed values; when given, added as "enum" in JSON Schema
+        # @param enum [Array, nil] allowed values
+        # @param properties [Hash, nil] nested schema for :object params
         # @param options [Hash] forwarded to RubyLLM::Tool.param
-        def param(name, enum: nil, **options)
+        # @api public
+        def param(name, enum: nil, properties: nil, **options)
           super(name, **options)
           param_enums[name] = enum if enum
+          param_schemas[name] = normalize_nested_schema(properties) if properties
         end
 
         # Returns the enum constraints registered via .param.
         # @return [Hash{Symbol => Array}]
+        # @api public
         def param_enums
           @param_enums ||= {}
         end
 
+        # Returns nested schema definitions registered via .param(properties: ...).
+        # @return [Hash{Symbol => Hash}]
+        # @api public
+        def param_schemas
+          @param_schemas ||= {}
+        end
+
+        private
+
+        # Recursively normalises a properties hash so all keys are Symbols and
+        # each spec has a :type key.
+        def normalize_nested_schema(props)
+          props.transform_keys(&:to_sym).transform_values do |spec|
+            s = spec.transform_keys(&:to_sym)
+            s[:type] ||= :string
+            s[:properties] = normalize_nested_schema(s[:properties]) if s[:properties]
+            s
+          end
+        end
+
+        public
+
         # Sets the access scope for this tool (metadata; enforcement is the responsibility of
         # the Workflow/Guardrail layer).
         # @param value [Symbol] e.g. :read_only, :write, :admin
+        # @api public
         def scope(value = nil)
           return @scope if value.nil?
 
           @scope = value
         end
 
-        # Configures error-handling behavior.
-        # @param behavior [Symbol] :raise (default) or :return_empty
+        # Configures error-handling behavior when +execute+ raises an unexpected error.
+        #
+        # @param behavior [Symbol]
+        #   :raise        (default)  — re-raise as Phronomy::ToolError, stopping the agent.
+        #   :suppress                — suppress the error and return a descriptive string so
+        #                             the LLM can recover on the next turn.
+        #   :return_empty            — *deprecated* alias for +:suppress+; will be removed in a
+        #                             future major release.
+        # @api public
         def on_error(behavior = nil)
           return @on_error || :raise if behavior.nil?
 
+          if behavior == :return_empty
+            msg = "[Phronomy] on_error :return_empty is deprecated; use :suppress instead"
+            if Phronomy.configuration.logger
+              Phronomy.configuration.logger.warn(msg)
+            else
+              warn msg
+            end
+          end
           @on_error = behavior
         end
 
@@ -83,6 +129,7 @@ module Phronomy
         #   :raise                  — raise Phronomy::ToolError, stopping the agent loop.
         #   :coerce                 — attempt type coercion (e.g. "42" → 42 for :integer);
         #                             falls back to :return_error when coercion is not possible.
+        # @api public
         def on_schema_error(behavior = nil)
           return @on_schema_error || :return_error if behavior.nil?
 
@@ -91,6 +138,7 @@ module Phronomy
 
         # Configures whether human approval is required before executing this tool.
         # @param value [Boolean]
+        # @api public
         def requires_approval(value = nil)
           return @requires_approval || false if value.nil?
 
@@ -113,6 +161,7 @@ module Phronomy
         # @example
         #   retry_on Phronomy::ToolError, times: 3, wait: :exponential, base: 1.0
         #   retry_on Net::ReadTimeout, times: 2, wait: 0.5
+        # @api public
         def retry_on(*exception_classes, times: 1, wait: 0, base: 1.0)
           @retry_policies ||= []
           @retry_policies << {exceptions: exception_classes, times: times, wait: wait, base: base}
@@ -120,6 +169,7 @@ module Phronomy
 
         # Returns all retry policies registered on this tool class.
         # @return [Array<Hash>]
+        # @api public
         def retry_policies
           @retry_policies || []
         end
@@ -127,6 +177,7 @@ module Phronomy
         # Injectable sleep callable for testing.
         # Defaults to Kernel#sleep.
         # @return [#call]
+        # @api private
         def _sleep_proc
           @_sleep_proc || method(:sleep)
         end
@@ -147,24 +198,37 @@ module Phronomy
       # Injects "enum" entries for any param declared with enum: [...].
       def params_schema
         schema = super
-        return schema if schema.nil? || self.class.param_enums.empty?
+        return schema if schema.nil?
 
-        enums = self.class.param_enums
         properties = schema.dig("properties") || schema.dig(:properties)
         return schema unless properties
 
-        enums.each do |param_name, values|
+        # Inject enum values for params declared with enum: [...].
+        unless self.class.param_enums.empty?
+          enums = self.class.param_enums
+          enums.each do |param_name, values|
+            key = properties.key?(param_name.to_s) ? param_name.to_s : param_name.to_sym
+            next unless properties[key]
+
+            param_type = properties[key]["type"]
+            properties[key]["enum"] = values.map do |v|
+              case param_type
+              when "integer" then v.is_a?(Integer) ? v : Integer(v.to_s)
+              when "number" then v.is_a?(Numeric) ? v : Float(v.to_s)
+              else v.to_s
+              end
+            end
+          end
+        end
+
+        # Inject nested properties for :object params (issue #162).
+        # Without this the LLM sees only { "type": "object" } with no field
+        # definitions, making it unable to populate nested object params.
+        self.class.param_schemas.each do |param_name, nested|
           key = properties.key?(param_name.to_s) ? param_name.to_s : param_name.to_sym
           next unless properties[key]
 
-          param_type = properties[key]["type"]
-          properties[key]["enum"] = values.map do |v|
-            case param_type
-            when "integer" then v.is_a?(Integer) ? v : Integer(v.to_s)
-            when "number" then v.is_a?(Numeric) ? v : Float(v.to_s)
-            else v.to_s
-            end
-          end
+          properties[key]["properties"] = nested_schema_to_json_schema(nested)
         end
 
         schema
@@ -174,10 +238,18 @@ module Phronomy
       # the on_error policy, and wrap errors as ToolError.
       #
       # Execution order:
-      #   1. Schema validation (type + enum checks).
-      #   2. Call super(validated_args) inside a retry loop.
-      #   3. On persistent failure, apply on_error policy.
-      def call(args)
+      #   1. Early cancellation check (kwarg token takes precedence over thread-local).
+      #   2. Schema validation (type + enum checks).
+      #   3. Inject +cancellation_token:+ into args when +execute+ opts in.
+      #   4. Call super(validated_args) inside a retry loop.
+      #   5. On persistent failure, apply on_error policy.
+      #
+      # @param args               [Hash]
+      # @param cancellation_token [Phronomy::CancellationToken, nil] optional; takes precedence over the thread-local token
+      # @api public
+      def call(args, cancellation_token: nil)
+        ct = cancellation_token || Thread.current[:phronomy_cancellation_token]
+        ct&.raise_if_cancelled!
         validated_args, schema_error = validate_and_coerce(args)
         if schema_error
           case self.class.on_schema_error
@@ -188,13 +260,22 @@ module Phronomy
             return "Schema validation failed: #{schema_error}"
           end
         end
+        validated_args = validated_args.merge(cancellation_token: ct) if ct && execute_accepts_cancellation_token?
         with_tool_retry { super(validated_args) }
       rescue Phronomy::ToolError
         raise
+      rescue Phronomy::CancellationError
+        raise
       rescue => e
         case self.class.on_error
-        when :return_empty
-          []
+        when :return_empty, :suppress
+          msg = "[Phronomy] Tool #{self.class.name} suppressed error: #{e.class}: #{e.message}"
+          if Phronomy.configuration.logger
+            Phronomy.configuration.logger.warn(msg)
+          else
+            warn msg
+          end
+          "Tool error suppressed: #{e.message}"
         else
           raise Phronomy::ToolError, "#{self.class.name} execution failed: #{e.message}"
         end
@@ -226,12 +307,21 @@ module Phronomy
       #       WeatherService.fetch(location).to_s
       #     end
       #   end
+      # @api public
       def execute(**_args)
         raise NotImplementedError, "#{self.class}#execute is not implemented"
       end
 
       private
 
+      # Returns true when the #execute method declares a +cancellation_token:+
+      # keyword parameter, indicating it opts into cooperative cancellation.
+      def execute_accepts_cancellation_token?
+        method(:execute).parameters.any? do |type, name|
+          name == :cancellation_token && %i[key keyreq].include?(type)
+        end
+      end
+
       # Executes the given block inside a retry loop driven by the class-level
       # retry_policies. Each policy matches by exception class; the first matching
       # policy governs the wait and retry count. Raises immediately when no policy
@@ -261,6 +351,7 @@ module Phronomy
       # @param base     [Float]           base wait time in seconds
       # @param attempt  [Integer]         zero-based attempt index
       # @return [Float]
+      # @api public
       def compute_retry_wait(strategy, base, attempt)
         case strategy
         when :exponential
@@ -279,6 +370,7 @@ module Phronomy
       #
       # @param args [Hash] raw args passed to #call (string or symbol keys)
       # @return [Array(Hash, String|nil)] [possibly_coerced_args, error_message_or_nil]
+      # @api public
       def validate_and_coerce(args)
         return [args, nil] if self.class.parameters.empty?
 
@@ -304,6 +396,15 @@ module Phronomy
             return [nil, error] if error
           end
 
+          # Recursively validate nested object properties when declared.
+          if param.type.to_sym == :object
+            nested_schema = self.class.param_schemas[name]
+            if nested_schema
+              error = validate_nested_object(value, nested_schema, name.to_s)
+              return [nil, error] if error
+            end
+          end
+
           enum_vals = self.class.param_enums[name]
           if enum_vals && !enum_vals.map(&:to_s).include?(value.to_s)
             return [nil, "parameter '#{name}' must be one of: #{enum_vals.join(", ")} (got: #{value.inspect})"]
@@ -312,9 +413,69 @@ module Phronomy
           result[name] = value
         end
 
-        # Merge in any extra keys not covered by declared parameters (pass-through).
-        extra = normalized.reject { |k, _| self.class.parameters.key?(k) }
-        [result.merge(extra), nil]
+        # Reject any keys not covered by declared parameters to prevent silent
+        # parameter injection (e.g. via prompt injection).
+        extra = normalized.keys - self.class.parameters.keys
+        unless extra.empty?
+          return [nil, "unknown parameter(s): #{extra.inspect}"]
+        end
+
+        [result, nil]
+      end
+
+      # Converts the internal normalized nested schema (from param_schemas) to
+      # a JSON Schema +properties+ hash suitable for inclusion in the LLM tool
+      # definition (issue #162).
+      #
+      # @param nested [Hash{Symbol=>Hash}] normalized schema from param_schemas
+      # @return [Hash{String=>Hash}] JSON Schema properties
+      # @api public
+      def nested_schema_to_json_schema(nested)
+        nested.each_with_object({}) do |(prop_name, spec), acc|
+          entry = {"type" => spec[:type].to_s}
+          entry["description"] = spec[:desc] if spec[:desc]
+          entry["enum"] = spec[:enum] if spec[:enum]
+          entry["properties"] = nested_schema_to_json_schema(spec[:properties]) if spec[:properties]
+          acc[prop_name.to_s] = entry
+        end
+      end
+
+      # Recursively validates +value+ (a Hash) against a +properties+ schema.
+      # Returns an error message string or nil.
+      #
+      # @param value      [Hash]            the object value to validate
+      # @param properties [Hash{Symbol=>Hash}] nested schema from param_schemas
+      # @param path       [String]          dot-separated field path for error messages
+      # @api public
+      def validate_nested_object(value, properties, path)
+        return "field '#{path}' must be an object (Hash)" unless value.is_a?(Hash)
+
+        normalized = value.transform_keys(&:to_sym)
+
+        # Reject extra keys not declared in the schema (issue #166).
+        extra = normalized.keys - properties.keys
+        unless extra.empty?
+          return "nested field '#{path}' contains undeclared key(s): #{extra.inspect}"
+        end
+
+        properties.each do |fname, spec|
+          field_path = "#{path}.#{fname}"
+          field_value = normalized[fname]
+
+          if field_value.nil?
+            return "nested required field '#{field_path}' is missing" if spec[:required]
+            next
+          end
+
+          error = type_error(field_value, spec[:type])
+          return "nested field '#{field_path}': #{error}" if error
+
+          next unless spec[:type].to_sym == :object && spec[:properties]
+
+          error = validate_nested_object(field_value, spec[:properties], field_path)
+          return error if error
+        end
+        nil
       end
 
       # Returns a type-error message string if +value+ does not match +declared_type+,
@@ -322,6 +483,7 @@ module Phronomy
       #
       # @param value         [Object]
       # @param declared_type [Symbol, String]  e.g. :string, :integer, :number, :boolean, :array, :object
+      # @api public
       def type_error(value, declared_type)
         return nil if value.nil?
 

data/lib/phronomy/tool/mcp_tool.rb

@@ -5,6 +5,7 @@ require "net/http"
 require "open3"
 require "securerandom"
 require "shellwords"
+require "timeout"
 require "uri"
 
 module Phronomy
@@ -36,6 +37,7 @@ module Phronomy
         #   - "http://<url>" / "https://<url>" — connect to an HTTP/SSE server
         # @param tool_name [String] the tool name as registered in the MCP server
         # @return [McpTool] a configured subclass instance ready for use with an Agent
+        # @api public
         def from_server(server_uri, tool_name:)
           # Use a short-lived transport only to query the tool definition,
           # then close it.  Each McpTool instance creates its own transport
@@ -71,7 +73,10 @@ module Phronomy
           # Register description and params from the MCP tool definition.
           klass.description(tool_def[:description] || tool_name)
           (tool_def[:parameters] || []).each do |p|
-            klass.param(p[:name].to_sym, type: p[:type]&.to_sym || :string, desc: p[:description].to_s)
+            opts = {type: p[:type]&.to_sym || :string, desc: p[:description].to_s}
+            opts[:required] = p[:required] if p.key?(:required)
+            opts[:enum] = p[:enum] if p.key?(:enum)
+            klass.param(p[:name].to_sym, **opts)
           end
 
           # Each instance creates its own transport so concurrent agent threads
@@ -107,10 +112,27 @@ module Phronomy
       # so that session state (registered resources, tool context, etc.) is preserved
       # across multiple calls.
       class StdioTransport
-        def initialize(command)
+        # @param command         [String]  shell command to spawn the MCP server process
+        # @param read_timeout    [Integer] seconds to wait for the server's JSON-RPC response
+        #   before raising {Phronomy::ToolError}. Mirrors the +read_timeout+ option on
+        #   {HttpTransport}. Defaults to 30 seconds.
+        # @param env             [Hash, nil] environment variable overrides for the subprocess.
+        #   When provided, only these variables are added/overridden; the parent environment
+        #   is still inherited unless explicitly cleared via an empty string value.
+        # @param cwd             [String, nil] working directory for the subprocess.
+        #   Defaults to the current process's working directory.
+        # @param startup_timeout [Numeric, nil] seconds to wait for the server to
+        #   emit its first line on stdout before raising {Phronomy::ToolError}.
+        #   When nil (default), no startup check is performed.
+        # @api public
+        def initialize(command, read_timeout: 30, env: nil, cwd: nil, startup_timeout: nil)
           # Split the command string into an argv array so that Open3 executes
           # it directly without going through the shell, preventing injection.
           @command = Shellwords.split(command)
+          @read_timeout = read_timeout
+          @env = env
+          @cwd = cwd
+          @startup_timeout = startup_timeout
           @stdin = nil
           @stdout = nil
           @stderr = nil
@@ -137,15 +159,17 @@ module Phronomy
         # Retrieve the tool definition from the server using the MCP `tools/list` method.
         # @param tool_name [String]
         # @return [Hash] { description:, parameters: }
+        # @api public
         def fetch_tool(tool_name)
           response = rpc_call("tools/list", {})
           tools = response.dig("result", "tools") || []
           defn = tools.find { |t| t["name"] == tool_name }
           raise ArgumentError, "Tool #{tool_name.inspect} not found on MCP server #{@command.inspect}" unless defn
 
+          required_names = defn.dig("inputSchema", "required") || []
           {
             description: defn["description"],
-            parameters: parse_schema_params(defn.dig("inputSchema", "properties") || {})
+            parameters: parse_schema_params(defn.dig("inputSchema", "properties") || {}, required_names: required_names)
           }
         end
 
@@ -153,6 +177,7 @@ module Phronomy
         # @param tool_name [String]
         # @param args [Hash]
         # @return [Object] the tool result
+        # @api public
         def call_tool(tool_name, args)
           response = rpc_call("tools/call", {name: tool_name, arguments: args})
           if response["error"]
@@ -176,7 +201,11 @@ module Phronomy
         def ensure_started!
           return if @stdin && !@stdin.closed?
 
-          @stdin, @stdout, @stderr, @wait_thr = Open3.popen3(*@command)
+          popen3_opts = {}
+          popen3_opts[:chdir] = @cwd if @cwd
+
+          argv = @env ? [@env, *@command] : @command
+          @stdin, @stdout, @stderr, @wait_thr = Open3.popen3(*argv, **popen3_opts)
           # Drain stderr asynchronously to prevent the pipe buffer from filling
           # and deadlocking the child process. Errors inside the drain thread are
           # silently ignored since stderr content is diagnostics-only.
@@ -185,24 +214,38 @@ module Phronomy
           rescue
             nil
           end
+
+          if @startup_timeout
+            Timeout.timeout(@startup_timeout) { @stdout.gets.tap { |line| @stdout.ungetbyte(line) if line } }
+          end
+        rescue Timeout::Error
+          close
+          raise Phronomy::ToolError,
+            "MCP stdio server did not start within #{@startup_timeout} seconds"
         end
 
         def rpc_call(method, params)
           ensure_started!
           payload = JSON.generate(jsonrpc: "2.0", id: SecureRandom.uuid, method: method, params: params)
           @stdin.puts(payload)
-          raw = @stdout.gets
+          raw = Timeout.timeout(@read_timeout) { @stdout.gets }
           raise Phronomy::ToolError, "MCP server closed the connection unexpectedly" if raw.nil?
           JSON.parse(raw)
+        rescue Timeout::Error
+          raise Phronomy::ToolError,
+            "MCP stdio server did not respond within #{@read_timeout} seconds"
         end
 
-        def parse_schema_params(properties)
+        def parse_schema_params(properties, required_names: [])
           properties.map do |name, schema|
-            {
+            param = {
               name: name.to_s,
               type: schema["type"] || "string",
-              description: schema["description"].to_s
+              description: schema["description"].to_s,
+              required: required_names.include?(name.to_s)
             }
+            param[:enum] = schema["enum"] if schema["enum"]
+            param
           end
         end
       end
@@ -223,10 +266,15 @@ module Phronomy
         # @param base_url     [String]  full URL of the MCP endpoint, e.g. "http://localhost:8080/mcp"
         # @param open_timeout [Integer] TCP connection timeout in seconds (default: 5)
         # @param read_timeout [Integer] HTTP read timeout in seconds (default: 30)
-        def initialize(base_url, open_timeout: 5, read_timeout: 30)
+        # @param headers      [Hash]    additional HTTP request headers (e.g. Authorization).
+        #   Merged on top of the default Content-Type and Accept headers; caller-supplied
+        #   values override defaults when keys collide.
+        # @api public
+        def initialize(base_url, open_timeout: 5, read_timeout: 30, headers: {})
           @uri = URI.parse(base_url)
           @open_timeout = open_timeout
           @read_timeout = read_timeout
+          @extra_headers = headers
         end
 
         # HTTP connections are stateless; close is a no-op, defined so that
@@ -237,15 +285,17 @@ module Phronomy
         # Retrieve the tool definition from the server using MCP `tools/list`.
         # @param tool_name [String]
         # @return [Hash] { description:, parameters: }
+        # @api public
         def fetch_tool(tool_name)
           response = rpc_call("tools/list", {})
           tools = response.dig("result", "tools") || []
           defn = tools.find { |t| t["name"] == tool_name }
           raise ArgumentError, "Tool #{tool_name.inspect} not found on MCP server #{@uri}" unless defn
 
+          required_names = defn.dig("inputSchema", "required") || []
           {
             description: defn["description"],
-            parameters: parse_schema_params(defn.dig("inputSchema", "properties") || {})
+            parameters: parse_schema_params(defn.dig("inputSchema", "properties") || {}, required_names: required_names)
           }
         end
 
@@ -253,6 +303,7 @@ module Phronomy
         # @param tool_name [String]
         # @param args [Hash]
         # @return [Object] the tool result
+        # @api public
         def call_tool(tool_name, args)
           response = rpc_call("tools/call", {name: tool_name, arguments: args})
           if response["error"]
@@ -285,6 +336,7 @@ module Phronomy
           request = Net::HTTP::Post.new(path)
           request["Content-Type"] = "application/json"
           request["Accept"] = "application/json, text/event-stream"
+          @extra_headers.each { |k, v| request[k.to_s] = v.to_s }
           request.body = payload
 
           http_response = http.request(request)
@@ -323,13 +375,16 @@ module Phronomy
           result || raise(Phronomy::ToolError, "No valid JSON-RPC response found in SSE stream")
         end
 
-        def parse_schema_params(properties)
+        def parse_schema_params(properties, required_names: [])
           properties.map do |name, schema|
-            {
+            param = {
               name: name.to_s,
               type: schema["type"] || "string",
-              description: schema["description"].to_s
+              description: schema["description"].to_s,
+              required: required_names.include?(name.to_s)
             }
+            param[:enum] = schema["enum"] if schema["enum"]
+            param
           end
         end
       end

data/lib/phronomy/tracing/base.rb

@@ -23,6 +23,7 @@ module Phronomy
       # @param meta [Hash] additional metadata attached to the span
       # @yield [span] the active span object
       # @return [Object] the block's return value
+      # @api public
       def trace(name, input: nil, **meta)
         span = start_span(name, input: input, **meta)
         result, usage = yield span
@@ -38,6 +39,7 @@ module Phronomy
       # @param name [String]
       # @param attributes [Hash]
       # @return [Object] an opaque span handle
+      # @api public
       def start_span(name, **attributes)
         raise NotImplementedError, "#{self.class}#start_span is not implemented"
       end
@@ -48,6 +50,7 @@ module Phronomy
       # @param output [Object, nil] successful output value
       # @param usage [Phronomy::TokenUsage, nil] token usage for this span
       # @param error [Exception, nil] exception if the block raised
+      # @api public
       def finish_span(span, output: nil, usage: nil, error: nil)
         raise NotImplementedError, "#{self.class}#finish_span is not implemented"
       end

data/lib/phronomy/tracing/langfuse_tracer.rb

@@ -31,6 +31,7 @@ module Phronomy
       # @param public_key [String] Langfuse project public key
       # @param secret_key [String] Langfuse project secret key
       # @param host [String] Langfuse host URL (override for self-hosted instances)
+      # @api public
       def initialize(public_key:, secret_key:, host: DEFAULT_HOST)
         @public_key = public_key
         @secret_key = secret_key
@@ -41,6 +42,7 @@ module Phronomy
       # Returns a plain Hash that records the span start state.
       #
       # @return [Hash] an opaque span handle used by {#finish_span}
+      # @api public
       def start_span(name, input: nil, **meta)
         {
           id: SecureRandom.uuid,