prompt_objects 0.1.0

data/lib/prompt_objects/llm/anthropic_adapter.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+module PromptObjects
+  module LLM
+    # Anthropic API adapter for LLM calls.
+    class AnthropicAdapter
+      DEFAULT_MODEL = "claude-haiku-4-5"
+      DEFAULT_MAX_TOKENS = 4096
+
+      def initialize(api_key: nil, model: nil, max_tokens: nil)
+        @api_key = api_key || ENV.fetch("ANTHROPIC_API_KEY") do
+          raise Error, "ANTHROPIC_API_KEY environment variable not set"
+        end
+        @model = model || DEFAULT_MODEL
+        @max_tokens = max_tokens || DEFAULT_MAX_TOKENS
+        @client = Anthropic::Client.new(api_key: @api_key)
+      end
+
+      # Make a chat completion request.
+      # @param system [String] System prompt
+      # @param messages [Array<Hash>] Conversation history
+      # @param tools [Array<Hash>] Tool descriptors (optional)
+      # @return [Response] Normalized response
+      def chat(system:, messages:, tools: [])
+        params = {
+          model: @model,
+          max_tokens: @max_tokens,
+          system: system,
+          messages: build_messages(messages)
+        }
+
+        # Only include tools if we have any
+        if tools.any?
+          params[:tools] = convert_tools(tools)
+        end
+
+        raw_response = @client.messages.create(**params)
+        parse_response(raw_response)
+      end
+
+      private
+
+      def build_messages(messages)
+        result = []
+
+        messages.each do |msg|
+          case msg[:role]
+          when :user
+            result << { role: "user", content: msg[:content] }
+          when :assistant
+            content_blocks = []
+
+            # Add text content if present
+            if msg[:content] && !msg[:content].empty?
+              content_blocks << { type: "text", text: msg[:content] }
+            end
+
+            # Add tool_use blocks if present
+            if msg[:tool_calls]
+              msg[:tool_calls].each do |tc|
+                # Handle both ToolCall objects and Hashes (from database)
+                tc_id = tc.respond_to?(:id) ? tc.id : (tc[:id] || tc["id"])
+                tc_name = tc.respond_to?(:name) ? tc.name : (tc[:name] || tc["name"])
+                tc_args = tc.respond_to?(:arguments) ? tc.arguments : (tc[:arguments] || tc["arguments"] || {})
+
+                content_blocks << {
+                  type: "tool_use",
+                  id: tc_id,
+                  name: tc_name,
+                  input: tc_args
+                }
+              end
+            end
+
+            result << { role: "assistant", content: content_blocks } if content_blocks.any?
+          when :tool
+            # Tool results in Anthropic are sent as user messages with tool_result content blocks
+            tool_result_blocks = msg[:results].map do |tool_result|
+              {
+                type: "tool_result",
+                tool_use_id: tool_result[:tool_call_id],
+                content: tool_result[:content].to_s
+              }
+            end
+            result << { role: "user", content: tool_result_blocks }
+          end
+        end
+
+        result
+      end
+
+      # Convert OpenAI-style tool definitions to Anthropic format
+      def convert_tools(tools)
+        tools.map do |tool|
+          if tool[:type] == "function"
+            # OpenAI format with function wrapper
+            func = tool[:function]
+            {
+              name: func[:name],
+              description: func[:description],
+              input_schema: func[:parameters] || { type: "object", properties: {} }
+            }
+          else
+            # Already in Anthropic format or simple format
+            {
+              name: tool[:name],
+              description: tool[:description],
+              input_schema: tool[:input_schema] || tool[:parameters] || { type: "object", properties: {} }
+            }
+          end
+        end
+      end
+
+      def parse_response(raw)
+        content = ""
+        tool_calls = []
+
+        # Raw response is an Anthropic::Message object with content array
+        # Note: SDK returns type as Symbol (:text, :tool_use), not String
+        raw.content.each do |block|
+          case block.type.to_sym
+          when :text
+            content += block.text
+          when :tool_use
+            tool_calls << ToolCall.new(
+              id: block.id,
+              name: block.name,
+              arguments: block.input.is_a?(Hash) ? block.input : block.input.to_h
+            )
+          end
+        end
+
+        Response.new(content: content, tool_calls: tool_calls, raw: raw)
+      end
+    end
+  end
+end

data/lib/prompt_objects/llm/factory.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module PromptObjects
+  module LLM
+    # Factory for creating LLM adapters based on provider name.
+    # Provides a unified interface for switching between OpenAI, Anthropic, and Gemini.
+    class Factory
+      PROVIDERS = {
+        "openai" => {
+          adapter: "OpenAIAdapter",
+          env_key: "OPENAI_API_KEY",
+          default_model: "gpt-5.2",
+          models: %w[gpt-5.2 gpt-4.1 gpt-4.1-mini gpt-4.5-preview o3-mini o1]
+        },
+        "anthropic" => {
+          adapter: "AnthropicAdapter",
+          env_key: "ANTHROPIC_API_KEY",
+          default_model: "claude-haiku-4-5",
+          models: %w[claude-haiku-4-5 claude-sonnet-4-5 claude-opus-4]
+        },
+        "gemini" => {
+          adapter: "GeminiAdapter",
+          env_key: "GEMINI_API_KEY",
+          default_model: "gemini-3-flash-preview",
+          models: %w[gemini-3-flash-preview gemini-2.5-pro gemini-2.5-flash]
+        }
+      }.freeze
+
+      DEFAULT_PROVIDER = "anthropic"
+
+      class << self
+        # Create an adapter for the given provider.
+        # @param provider [String] Provider name (openai, anthropic, gemini)
+        # @param model [String, nil] Optional model override
+        # @param api_key [String, nil] Optional API key override
+        # @return [OpenAIAdapter, AnthropicAdapter, GeminiAdapter]
+        def create(provider: nil, model: nil, api_key: nil)
+          provider_name = (provider || DEFAULT_PROVIDER).to_s.downcase
+          config = PROVIDERS[provider_name]
+
+          raise Error, "Unknown LLM provider: #{provider_name}" unless config
+
+          adapter_class = LLM.const_get(config[:adapter])
+          adapter_class.new(api_key: api_key, model: model)
+        end
+
+        # List available providers.
+        # @return [Array<String>]
+        def providers
+          PROVIDERS.keys
+        end
+
+        # Get info about a provider.
+        # @param provider [String] Provider name
+        # @return [Hash, nil]
+        def provider_info(provider)
+          PROVIDERS[provider.to_s.downcase]
+        end
+
+        # Check which providers have API keys configured.
+        # @return [Hash<String, Boolean>]
+        def available_providers
+          PROVIDERS.transform_values do |config|
+            ENV.key?(config[:env_key])
+          end
+        end
+
+        # Get the default model for a provider.
+        # @param provider [String] Provider name
+        # @return [String, nil]
+        def default_model(provider)
+          PROVIDERS.dig(provider.to_s.downcase, :default_model)
+        end
+
+        # Get available models for a provider.
+        # @param provider [String] Provider name
+        # @return [Array<String>]
+        def models_for(provider)
+          PROVIDERS.dig(provider.to_s.downcase, :models) || []
+        end
+      end
+    end
+  end
+end

data/lib/prompt_objects/llm/gemini_adapter.rb

@@ -0,0 +1,209 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "json"
+require "securerandom"
+
+module PromptObjects
+  module LLM
+    # Google Gemini API adapter for LLM calls.
+    # Uses direct HTTP calls to the Gemini REST API.
+    class GeminiAdapter
+      DEFAULT_MODEL = "gemini-3-flash-preview"
+      API_BASE_URL = "https://generativelanguage.googleapis.com/v1beta"
+
+      def initialize(api_key: nil, model: nil)
+        @api_key = api_key || ENV.fetch("GEMINI_API_KEY") do
+          raise Error, "GEMINI_API_KEY environment variable not set"
+        end
+        @model = model || DEFAULT_MODEL
+      end
+
+      # Make a chat completion request.
+      # @param system [String] System prompt
+      # @param messages [Array<Hash>] Conversation history
+      # @param tools [Array<Hash>] Tool descriptors (optional)
+      # @return [Response] Normalized response
+      def chat(system:, messages:, tools: [])
+        body = {
+          system_instruction: build_system_instruction(system),
+          contents: build_contents(messages)
+        }
+
+        # Only include tools if we have any
+        if tools.any?
+          body[:tools] = build_tools(tools)
+          body[:tool_config] = { function_calling_config: { mode: "AUTO" } }
+        end
+
+        raw_response = make_request(body)
+        parse_response(raw_response)
+      end
+
+      private
+
+      def build_system_instruction(system)
+        {
+          parts: [{ text: system }]
+        }
+      end
+
+      def build_contents(messages)
+        result = []
+        # Track tool calls from the last assistant message for name lookup
+        last_tool_calls = {}
+
+        messages.each do |msg|
+          case msg[:role]
+          when :user
+            result << {
+              role: "user",
+              parts: [{ text: msg[:content] }]
+            }
+          when :assistant
+            parts = []
+            parts << { text: msg[:content] } if msg[:content] && !msg[:content].empty?
+            if msg[:tool_calls]
+              # Store tool calls for potential name lookup in tool results
+              last_tool_calls = {}
+              msg[:tool_calls].each do |tc|
+                # Handle both ToolCall objects and Hashes (from database)
+                tc_id = tc.respond_to?(:id) ? tc.id : (tc[:id] || tc["id"])
+                tc_name = tc.respond_to?(:name) ? tc.name : (tc[:name] || tc["name"])
+                tc_args = tc.respond_to?(:arguments) ? tc.arguments : (tc[:arguments] || tc["arguments"] || {})
+
+                last_tool_calls[tc_id] = tc_name
+                parts << {
+                  functionCall: {
+                    name: tc_name,
+                    args: tc_args
+                  }
+                }
+              end
+            end
+            result << { role: "model", parts: parts } if parts.any?
+          when :tool
+            # Tool results go back as a user message with functionResponse parts
+            parts = msg[:results].map do |tool_result|
+              # Get name from result, or look it up from the previous assistant's tool_calls
+              name = tool_result[:name] || last_tool_calls[tool_result[:tool_call_id]] || "unknown"
+              {
+                functionResponse: {
+                  name: name,
+                  response: parse_tool_response_content(tool_result[:content])
+                }
+              }
+            end
+            result << { role: "user", parts: parts }
+          end
+        end
+
+        result
+      end
+
+      def parse_tool_response_content(content)
+        # Try to parse as JSON, otherwise wrap in a result object
+        if content.is_a?(String)
+          begin
+            JSON.parse(content)
+          rescue JSON::ParserError
+            { result: content }
+          end
+        else
+          content
+        end
+      end
+
+      def build_tools(tools)
+        # Convert OpenAI-style tool format to Gemini function declarations
+        function_declarations = tools.map do |tool|
+          func = tool[:function] || tool["function"]
+          {
+            name: func[:name] || func["name"],
+            description: func[:description] || func["description"],
+            parameters: convert_parameters(func[:parameters] || func["parameters"])
+          }
+        end
+
+        [{ functionDeclarations: function_declarations }]
+      end
+
+      def convert_parameters(params)
+        return {} unless params
+
+        # Gemini uses OpenAPI-style parameters, similar to OpenAI
+        # but we need to ensure proper structure
+        result = {
+          type: params[:type] || params["type"] || "object"
+        }
+
+        if params[:properties] || params["properties"]
+          result[:properties] = params[:properties] || params["properties"]
+        end
+
+        if params[:required] || params["required"]
+          result[:required] = params[:required] || params["required"]
+        end
+
+        result
+      end
+
+      def make_request(body)
+        uri = URI("#{API_BASE_URL}/models/#{@model}:generateContent?key=#{@api_key}")
+
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = true
+        http.read_timeout = 120
+        http.open_timeout = 30
+
+        request = Net::HTTP::Post.new(uri)
+        request["Content-Type"] = "application/json"
+        request.body = body.to_json
+
+        response = http.request(request)
+
+        unless response.is_a?(Net::HTTPSuccess)
+          error_body = begin
+            JSON.parse(response.body)
+          rescue StandardError
+            response.body
+          end
+          raise Error, "Gemini API error (#{response.code}): #{error_body}"
+        end
+
+        JSON.parse(response.body)
+      end
+
+      def parse_response(raw)
+        candidate = raw.dig("candidates", 0)
+        content_obj = candidate&.dig("content")
+
+        return Response.new(content: "", raw: raw) unless content_obj
+
+        text_content = ""
+        tool_calls = []
+
+        content_obj["parts"]&.each do |part|
+          if part["text"]
+            text_content += part["text"]
+          elsif part["functionCall"]
+            tool_calls << parse_function_call(part["functionCall"])
+          end
+        end
+
+        Response.new(content: text_content, tool_calls: tool_calls, raw: raw)
+      end
+
+      def parse_function_call(fc)
+        # Gemini doesn't use tool_call_id like OpenAI, so we generate one
+        # based on the function name and a random suffix
+        ToolCall.new(
+          id: "call_#{fc['name']}_#{SecureRandom.hex(8)}",
+          name: fc["name"],
+          arguments: fc["args"] || {}
+        )
+      end
+    end
+  end
+end

data/lib/prompt_objects/llm/openai_adapter.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module PromptObjects
+  module LLM
+    # OpenAI API adapter for LLM calls.
+    class OpenAIAdapter
+      DEFAULT_MODEL = "gpt-5.2"
+
+      def initialize(api_key: nil, model: nil)
+        @api_key = api_key || ENV.fetch("OPENAI_API_KEY") do
+          raise Error, "OPENAI_API_KEY environment variable not set"
+        end
+        @model = model || DEFAULT_MODEL
+        @client = OpenAI::Client.new(access_token: @api_key)
+      end
+
+      # Make a chat completion request.
+      # @param system [String] System prompt
+      # @param messages [Array<Hash>] Conversation history
+      # @param tools [Array<Hash>] Tool descriptors (optional)
+      # @return [Response] Normalized response
+      def chat(system:, messages:, tools: [])
+        params = {
+          model: @model,
+          messages: build_messages(system, messages)
+        }
+
+        # Only include tools if we have any
+        if tools.any?
+          params[:tools] = tools
+          params[:tool_choice] = "auto"
+        end
+
+        raw_response = @client.chat(parameters: params)
+        parse_response(raw_response)
+      end
+
+      private
+
+      def build_messages(system, messages)
+        result = [{ role: "system", content: system }]
+
+        messages.each do |msg|
+          case msg[:role]
+          when :user
+            result << { role: "user", content: msg[:content] }
+          when :assistant
+            assistant_msg = { role: "assistant" }
+            assistant_msg[:content] = msg[:content] if msg[:content]
+            if msg[:tool_calls]
+              assistant_msg[:tool_calls] = msg[:tool_calls].map do |tc|
+                # Handle both ToolCall objects and Hashes (from database)
+                tc_id = tc.respond_to?(:id) ? tc.id : (tc[:id] || tc["id"])
+                tc_name = tc.respond_to?(:name) ? tc.name : (tc[:name] || tc["name"])
+                tc_args = tc.respond_to?(:arguments) ? tc.arguments : (tc[:arguments] || tc["arguments"] || {})
+
+                {
+                  id: tc_id,
+                  type: "function",
+                  function: { name: tc_name, arguments: tc_args.to_json }
+                }
+              end
+            end
+            result << assistant_msg
+          when :tool
+            msg[:results].each do |tool_result|
+              result << {
+                role: "tool",
+                tool_call_id: tool_result[:tool_call_id],
+                content: tool_result[:content].to_s
+              }
+            end
+          end
+        end
+
+        result
+      end
+
+      def parse_response(raw)
+        choice = raw.dig("choices", 0)
+        message = choice&.dig("message")
+
+        return Response.new(content: "", raw: raw) unless message
+
+        content = message["content"] || ""
+        tool_calls = parse_tool_calls(message["tool_calls"])
+
+        Response.new(content: content, tool_calls: tool_calls, raw: raw)
+      end
+
+      def parse_tool_calls(raw_tool_calls)
+        return [] unless raw_tool_calls
+
+        raw_tool_calls.map do |tc|
+          ToolCall.new(
+            id: tc["id"],
+            name: tc.dig("function", "name"),
+            arguments: JSON.parse(tc.dig("function", "arguments") || "{}")
+          )
+        end
+      end
+    end
+  end
+end

data/lib/prompt_objects/llm/response.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module PromptObjects
+  module LLM
+    # Normalized response from an LLM API call.
+    # Wraps provider-specific responses into a common interface.
+    class Response
+      attr_reader :content, :tool_calls, :raw
+
+      def initialize(content:, tool_calls: [], raw: nil)
+        @content = content
+        @tool_calls = tool_calls
+        @raw = raw
+      end
+
+      # Check if the response includes tool calls.
+      # @return [Boolean]
+      def tool_calls?
+        !@tool_calls.empty?
+      end
+    end
+
+    # Represents a single tool call from the LLM.
+    # Supports both method access (.id) and hash access ([:id]) for compatibility
+    # with code that may receive either ToolCall objects or Hashes from the DB.
+    class ToolCall
+      attr_reader :id, :name, :arguments
+
+      def initialize(id:, name:, arguments:)
+        @id = id
+        @name = name
+        @arguments = arguments
+      end
+
+      # Allow hash-style access for compatibility with code expecting Hashes
+      def [](key)
+        case key.to_sym
+        when :id then @id
+        when :name then @name
+        when :arguments then @arguments
+        end
+      end
+
+      # Convert to a plain Hash (for serialization)
+      def to_h
+        { id: @id, name: @name, arguments: @arguments }
+      end
+
+      # Create a ToolCall from a Hash (for deserialization)
+      def self.from_hash(hash)
+        return hash if hash.is_a?(ToolCall)
+
+        new(
+          id: hash[:id] || hash["id"],
+          name: hash[:name] || hash["name"],
+          arguments: hash[:arguments] || hash["arguments"] || {}
+        )
+      end
+    end
+  end
+end

data/lib/prompt_objects/loader.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module PromptObjects
+  # Loads and parses prompt object markdown files.
+  # Extracts YAML frontmatter (config) and markdown body (soul).
+  class Loader
+    # Load a prompt object from a markdown file.
+    # @param path [String] Path to the .md file
+    # @return [Hash] Parsed data with :config, :body, and :path
+    def self.load(path)
+      raise Error, "File not found: #{path}" unless File.exist?(path)
+
+      content = File.read(path, encoding: "UTF-8")
+      parsed = FrontMatterParser::Parser.new(:md).call(content)
+
+      {
+        config: parsed.front_matter || {},
+        body: parsed.content.strip,
+        path: path
+      }
+    end
+
+    # Load all prompt objects from a directory.
+    # @param dir [String] Directory path
+    # @return [Array<Hash>] Array of parsed prompt objects
+    def self.load_all(dir)
+      raise Error, "Directory not found: #{dir}" unless Dir.exist?(dir)
+
+      Dir.glob(File.join(dir, "*.md")).map { |path| load(path) }
+    end
+  end
+end