llm-fillin 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1167e6d823abb66aaa8e4cfd2f0a5ba2cb969dfe2ebc88f5a9931e5cf641b846
+  data.tar.gz: 1419c96c1c60df093cf8175cb1fa0e4098460f5528e3ed43097effd7426f4b1a
+SHA512:
+  metadata.gz: cd888ae3ec1245f5201c5509b3d08ce234927c5b91e61a46b10fd52739d4bfb314657a289da336b4d01fedebdeb3166ec4c036e75fb67d48e7b40be21f336e92
+  data.tar.gz: 4cdb05933e2f97aae0bf296f44f11abf2ac77612a57d8784c959fe184e8038caae4348c009d4ca1979c2294c2bffba9c0909333a0e345518be955049ebc5e425

data/LICENSE

@@ -0,0 +1,3 @@
+MIT License
+
+Copyright (c) ...

data/README.md

@@ -0,0 +1,32 @@
+# llm-fillin
+
+**LLM-powered slot filling + tool orchestration for Ruby.**  
+Register JSON-schema tools, let an LLM ask for missing fields, then call your handlers safely.
+
+## Install
+```bash
+bundle install
+```
+
+## Configure
+Set your OpenAI API key:
+```bash
+export OPENAI_API_KEY=sk-...
+```
+
+## Run the demo
+```bash
+ruby examples/run_create_toy.rb
+```
+
+Try:
+```
+I want a red race car toy for $12
+```
+
+The assistant will ask for any missing fields (like category) and then “create” the toy.
+
+## Use in your app
+- Register tools (schemas + handlers)
+- Call the Orchestrator with your message list
+- Validate server-side; enforce tenant/RBAC; generate idempotency for creates

data/bin/console

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+require "bundler/setup"
+require "llm/fillin"
+require "pry"
+Pry.start

data/examples/run_create_toy.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+
+require "llm/fillin"
+require "llm/fillin/toys"
+
+registry = LLM::Fillin::Registry.new
+LLM::Fillin.register_toy_tools!(registry)
+
+adapter = LLM::Fillin::OpenAIAdapter.new(
+  api_key: ENV.fetch("OPENAI_API_KEY"),
+  model: "gpt-4.1-mini",
+  temperature: 0
+)
+store = LLM::Fillin::StoreMemory.new
+orch  = LLM::Fillin::Orchestrator.new(adapter: adapter, registry: registry, store: store)
+
+thread_id = "demo-123"
+tenant_id = "org_123"
+actor_id  = "user_42"
+
+messages = [
+  { role: "user", content: "I want a red race car toy for $12" }
+]
+
+loop do
+  outcome = orch.step(thread_id: thread_id, tenant_id: tenant_id, actor_id: actor_id, messages: messages)
+
+  case outcome[:type]
+  when :assistant
+    puts "AI: #{outcome[:text]}"
+    print "YOU: "
+    input = STDIN.gets&.strip
+    break unless input
+    messages << { role: "user", content: input }
+  when :tool_ran
+    toy = outcome[:result]
+    puts "✅ Toy created: #{toy[:name]} (#{toy[:category]}, #{toy[:color]}) - $#{toy[:price_minor].to_i/100.0} | ID #{toy[:id]}"
+    break
+  end
+end

data/lib/llm/fillin/adapters/openai_adapter.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+require "openai"
+require "json"
+
+module LLM
+  module Fillin
+    class OpenAIAdapter
+      def initialize(api_key:, model:, temperature: 0)
+        @client = OpenAI::Client.new(access_token: api_key)
+        @model = model
+        @temperature = temperature
+      end
+
+      def step(system_prompt:, messages:, tools:, tool_results: [])
+        resp = @client.chat(parameters: {
+          model: @model,
+          temperature: @temperature,
+          tools: tools,
+          tool_choice: "auto",
+          messages: [{ role: "system", content: system_prompt }] +
+                    messages +
+                    tool_results
+        })
+        msg = resp.dig("choices", 0, "message")
+        { tool_calls: msg["tool_calls"], content: msg["content"] }
+      end
+
+      def tool_result_message(tool_call_id:, name:, content:)
+        { role: "tool", tool_call_id:, name:, content: content.to_json }
+      end
+    end
+  end
+end

data/lib/llm/fillin/adapters/store_memory.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+module LLM
+  module Fillin
+    class StoreMemory
+      def initialize
+        @tool_msgs_by_thread = Hash.new { |h,k| h[k] = [] }
+      end
+      def fetch_tool_messages(thread_id) = @tool_msgs_by_thread[thread_id]
+      def push_tool_message(thread_id, msg) = @tool_msgs_by_thread[thread_id] << msg
+    end
+  end
+end

data/lib/llm/fillin/idempotency.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+require "securerandom"
+
+module LLM
+  module Fillin
+    module Idempotency
+      def self.generate(thread_id:)
+        "chat-#{thread_id}-#{SecureRandom.hex(6)}"
+      end
+    end
+  end
+end

data/lib/llm/fillin/orchestrator.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+require "json"
+
+module LLM
+  module Fillin
+    class Orchestrator
+      POLICY = <<~SYS
+        You are a task-oriented assistant. Identify intent, extract entities,
+        ask for missing required fields one at a time, and call exactly one function when ready.
+        Keep replies concise and friendly.
+      SYS
+
+      def initialize(adapter:, registry:, store:)
+        @adapter, @registry, @store = adapter, registry, store
+      end
+
+      # messages: [{role:"user", content:"..."}]
+      def step(thread_id:, tenant_id:, actor_id:, messages:)
+        prior_tool_msgs = @store.fetch_tool_messages(thread_id)
+        res = @adapter.step(
+          system_prompt: POLICY,
+          messages: messages,
+          tools: @registry.tools_for_llm,
+          tool_results: prior_tool_msgs
+        )
+
+        if (calls = res[:tool_calls]).is_a?(Array) && calls.any?
+          call = calls.first
+          name, version = call.dig("function", "name").split(/_v/i)
+          args = JSON.parse(call.dig("function", "arguments") || "{}")
+
+          tool = @registry.tool(name, version: "v1")
+          Validators.validate!(tool.schema, args)
+
+          ctx = { tenant_id:, actor_id:, thread_id: }
+          result = tool.handler.call(args, ctx)
+
+          tool_msg = @adapter.tool_result_message(
+            tool_call_id: call["id"],
+            name: "#{name}_v1",
+            content: result
+          )
+          @store.push_tool_message(thread_id, tool_msg)
+
+          { type: :tool_ran, tool_name: name, result: result }
+        else
+          { type: :assistant, text: res[:content].to_s }
+        end
+      end
+    end
+  end
+end

data/lib/llm/fillin/registry.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+module LLM
+  module Fillin
+    Tool = Struct.new(:name, :version, :schema, :description, :handler, keyword_init: true)
+
+    class Registry
+      def initialize
+        @tools = {}
+      end
+
+      def register!(name:, version:, schema:, description:, handler:)
+        @tools[key_for(name, version)] = Tool.new(name:, version:, schema:, description:, handler:)
+      end
+
+      def tool(name, version: "v1")
+        @tools.fetch(key_for(name, version))
+      end
+
+      def tools_for_llm
+        @tools.values.map do |t|
+          {
+            type: "function",
+            function: {
+              name: "#{t.name}_#{t.version}",
+              description: t.description,
+              parameters: t.schema
+            }
+          }
+        end
+      end
+
+      private
+
+      def key_for(name, version) = "#{name}:#{version}"
+    end
+  end
+end

data/lib/llm/fillin/toys.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+require "securerandom"
+
+module LLM
+  module Fillin
+    CREATE_TOY_V1 = {
+      type: "object", additionalProperties: false,
+      properties: {
+        name: { type: "string", description: "Toy name" },
+        category: { type: "string", enum: %w[plush puzzle doll car lego other] },
+        price_minor: { type: "integer", minimum: 0, description: "Price in cents" },
+        color: { type: "string", description: "Primary color" }
+      },
+      required: %w[name category price_minor]
+    }
+
+    def self.register_toy_tools!(registry)
+      registry.register!(
+        name: "create_toy", version: "v1",
+        schema: CREATE_TOY_V1,
+        description: "Create a toy with name, category, price (in cents), and optional color.",
+        handler: ->(args, ctx) {
+          key = Idempotency.generate(thread_id: ctx[:thread_id])
+          {
+            id: "TOY-#{SecureRandom.hex(3).upcase}",
+            name: args["name"],
+            category: args["category"],
+            price_minor: args["price_minor"],
+            color: args["color"] || "unspecified",
+            created_by: ctx[:actor_id],
+            tenant: ctx[:tenant_id],
+            idempotency_key: key
+          }
+        }
+      )
+    end
+  end
+end

data/lib/llm/fillin/validators.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+require "json_schemer"
+
+module LLM
+  module Fillin
+    class Validators
+      def self.validate!(schema, args)
+        schemer = JSONSchemer.schema(schema)
+        errors = schemer.validate(args).to_a
+        raise ArgumentError, "Schema validation failed: #{errors}" if errors.any?
+      end
+    end
+  end
+end

data/lib/llm/fillin/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+module LLM
+  module Fillin
+    VERSION = "0.1.0"
+  end
+end

data/lib/llm/fillin.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+require_relative "fillin/version"
+require_relative "fillin/registry"
+require_relative "fillin/orchestrator"
+require_relative "fillin/validators"
+require_relative "fillin/idempotency"
+require_relative "fillin/adapters/openai_adapter"
+require_relative "fillin/adapters/store_memory"

metadata

@@ -0,0 +1,86 @@
+--- !ruby/object:Gem::Specification
+name: llm-fillin
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Phia Vang
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2025-09-03 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: openai
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.21'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.21'
+- !ruby/object:Gem::Dependency
+  name: json_schemer
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.3'
+description: Register JSON-schema tools and let an LLM handle intent, slot-filling,
+  and tool calls safely.
+email:
+- pnvang@gmail.com
+executables:
+- console
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- bin/console
+- examples/run_create_toy.rb
+- lib/llm/fillin.rb
+- lib/llm/fillin/adapters/openai_adapter.rb
+- lib/llm/fillin/adapters/store_memory.rb
+- lib/llm/fillin/idempotency.rb
+- lib/llm/fillin/orchestrator.rb
+- lib/llm/fillin/registry.rb
+- lib/llm/fillin/toys.rb
+- lib/llm/fillin/validators.rb
+- lib/llm/fillin/version.rb
+homepage: https://github.com/pnvang/llm-fillin
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.3
+signing_key:
+specification_version: 4
+summary: LLM-powered slot filling and tool orchestration for Ruby.
+test_files: []