llm-agent-rails 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9d1e3f9099b547fc6fa0e3373f0975cb6b3f8204d3684b9adac7d4c66610c265
-  data.tar.gz: a323962c8263652345699fd1ecdf7355e307328cbb196c2918206d0747a41fda
+  metadata.gz: b17fd27c8efed9b5925460bc0237bfc1b7513295782c7fb2da59f536b587fca5
+  data.tar.gz: aa1173ecce93936a742fcee83951f660b0ff3fe2737f332754a4876a5d9d558b
 SHA512:
-  metadata.gz: 6c623acb99a898b831280cb7fc02eaaa91382e752516e2763b6acf0ffad5c7dfc4dc5e7ac492798c13f21c830662ffb4cf6ab02350cf20ada2cfc237cdacdaad
-  data.tar.gz: 33acd6c6f4b1c1e717b24fe8fb768844679145991c6fcbde5f7543cd0f52c94f8963de99943591b1b4665647d5c2f35dcd3cd930f2227c83cca19fe83d9faf72
+  metadata.gz: f1db5d7833ab8b3d4a31fed0ec4eefd11f43df217bee17666c13e34ff59ac8ada56d8ff3fe9fb395edaf32085c75baddbb7fba2c5d6817b84196d037613faae2
+  data.tar.gz: ec7ceb50c3c3da4912bb8173e414be5a11771dfaf1d734f3270aa30c1ec5deda3ba80b8ffffe11efbc3fe790acefb54fdc8854eb2ce019231d35985bd1c252ed

data/README.md

@@ -1,111 +1,158 @@
 # llm-agent-rails
 
-Rails engine for **Llm-powered slot filling and tool orchestration**.  
-Mount an endpoint, register tools (JSON Schema + handler), and let an Llm collect missing fields and call your Ruby code safely.
+**Rails engine for LLM‑powered agents — slot filling, tool orchestration, and safe backend execution.**  
+Turn chat into validated function calls using JSON‑Schema, then run your Ruby handlers with idempotency.
+
+---
+
+## What this gem gives you
+
+- A mountable endpoint: `POST /llm/agent/step` that talks to an LLM.
+- **Slot filling**: the model asks for missing fields until a tool call is ready.
+- **Tool registry**: register functions (name+version+schema+handler) the LLM can call.
+- **Validation**: arguments are validated with `json_schemer` before your handler runs.
+- **Idempotency**: unique per‑thread keys for safe “create” operations.
+- **Adapter**: OpenAI adapter using the `openai ~> 0.21` Ruby SDK.
+- **Memory store**: persists tool results per `thread_id` (swap for Redis in prod).
+- **Generators**:
+  - `rails g llm:agent:install` (initializer + mount routes)
+  - `rails g llm:agent:tickets_demo` (optional demo tool + migration)
+
+---
 
 ## Install
 
 Add to your Gemfile:
+
 ```ruby
-gem "llm-agent-rails", github: "yourname/llm-agent-rails" # until published
+gem "llm-agent-rails", "~> 0.1"
 ```
 
-Bundle:
+Then:
+
 ```bash
 bundle install
+bin/rails g llm:agent:install
+# mounts the engine at /llm/agent and creates config/initializers/llm_agent.rb
 ```
 
-Run the installer:
+Optional demo (creates a Ticket model/tool so you can see tool-calling end‑to‑end):
+
 ```bash
-rails g llm:agent:install
+bin/rails g llm:agent:tickets_demo
+bin/rails db:migrate
 ```
-This will:
-- Create `config/initializers/llm_agent.rb`
-- Mount the engine at `/llm/agent`
 
-## Quick test (cURL)
+Configure your API key:
 
 ```bash
-curl -X POST http://localhost:3000/llm/agent/step   -H "Content-Type: application/json"   -d '{
-    "thread_id":"demo-thread",
-    "messages":[{"role":"user","content":"Open a ticket: Apple Pay checkout keeps failing on mobile."}]
-  }'
+export OPENAI_API_KEY=sk-...
 ```
 
-## Register a tool (example)
+Run the app:
 
-Create `app/llm_tools/tickets.rb`:
-```ruby
-module LlmTools
-  CREATE_TICKET_V1 = {
-    type: "object", additionalProperties: false,
-    properties: {
-      title:       { type: "string" },
-      description: { type: "string" },
-      priority:    { type: "string", enum: %w[low medium high] },
-      assignee_id: { type: "string" }
-    },
-    required: %w[title description priority]
-  }
-
-  def self.register!(registry)
-    registry.register!(
-      name: "create_ticket", version: "v1",
-      schema: CREATE_TICKET_V1,
-      description: "Create a support ticket.",
-      handler: ->(args, ctx) {
-        key = Llm::Agent::Rails::Idempotency.generate(thread_id: ctx[:thread_id])
-        ticket = Ticket.create!(
-          org_id: ctx[:tenant_id],
-          user_id: ctx[:actor_id],
-          idempotency_key: key,
-          title: args["title"],
-          description: args["description"],
-          priority: args["priority"],
-          assignee_id: args["assignee_id"]
-        )
-        { id: ticket.id, title: ticket.title, priority: ticket.priority, key: key }
-      }
-    )
-  end
-end
+```bash
+bin/rails s
 ```
 
-Register it in `config/initializers/llm_agent.rb`:
-```ruby
-# After Llm::Agent::Rails.configure block
-require Rails.root.join("app/llm_tools/tickets")
-LlmTools.register!(Llm::Agent::Rails.config[:registry])
+---
+
+## API — talk to the agent
+
+`POST /llm/agent/step`
+
+**Body**
+```json
+{
+  "thread_id": "demo-123",
+  "messages": [
+    { "role": "user", "content": "Open a ticket for checkout failing on Apple Pay" }
+  ]
+}
 ```
 
-## How it works
+- `thread_id` keeps tool state & idempotency consistent across turns.
+- `messages` is the chat transcript (array of `{role, content}`).
 
-- **Registry**: Define tools (name/version/schema/description/handler).
-- **Validators**: JSON Schema validation (`json_schemer`) before calling handlers.
-- **Idempotency**: Generate a per-thread key to prevent duplicate creates.
-- **Orchestrator**: Coordinates conversation, asks for missing fields, executes tools.
-- **Adapter**: OpenAI adapter (supports `openai ~> 0.21`, `chat.completions.create`).
-- **Store**: Memory store for tool-result messages (swap for Redis in prod).
+**Response**
 
-## Routes
+One of:
+```json
+{ "type": "assistant", "text": "a clarifying question or confirmation..." }
+```
+or
+```json
+{ "type": "tool_ran", "tool_name": "create_ticket", "result": { "id": 42, "title": "..." } }
+```
 
-The engine exposes:
+Errors look like:
+```json
+{ "error": "BadRequest", "message": "messages is required (array of {role, content})" }
 ```
-POST /llm/agent/step
+
+---
+
+## Example conversations
+
+### A. Client-managed transcript (simple)
+
+Send the **entire transcript each POST** with the same `thread_id`.
+
+```bash
+curl -X POST http://localhost:3000/llm/agent/step   -H "Content-Type: application/json"   -d '{
+    "thread_id": "demo-123",
+    "messages": [
+      { "role": "user", "content": "Open a ticket for checkout failing on Apple Pay" },
+      { "role": "assistant", "content": "I can help with that! What is the description?" },
+      { "role": "user", "content": "Description: iOS 17 checkout fails with tokenization error. Priority high." },
+      { "role": "assistant", "content": "Ill create a ticket with the following details:\n\n- **Title**: Checkout failing on Apple Pay\n- **Description**: iOS 17 checkout fails with tokenization error.\n- **Priority**: High\n\nIs there a specific category or team this ticket should be assigned to?"},
+      { "role": "user", "content": "Assign to the mobile team." }
+    ]
+  }'
 ```
-(If you change the mount point, this path changes accordingly.)
 
-## Config
+If you **haven’t registered a tool**, you’ll receive `{"type":"assistant","text":"..."}` — a helpful structured summary.
 
-Edit `config/initializers/llm_agent.rb`:
-```ruby
-Llm::Agent::Rails.configure do |c|
-  c[:model]       = "gpt-4o-mini"
-  c[:temperature] = 0
-  c[:store]       = Llm::Agent::Rails::Store::Memory.new
-  c[:registry]    = Llm::Agent::Rails::Registry.new
-end
+### B. With a tool registered (end‑to‑end create)
+
+1) Use the demo generator:
+
+```bash
+bin/rails g llm:agent:tickets_demo
+bin/rails db:migrate
 ```
 
+This adds `app/llm_tools/tickets.rb` and registers a `create_ticket_v1` tool with JSON Schema validation and idempotency.
+
+2) Try again. Once all required fields are collected, the response includes the tool result:
+
+```json
+{
+  "type": "tool_ran",
+  "tool_name": "create_ticket",
+  "result": { "id": 123, "title": "Checkout failing on Apple Pay", "priority": "high", "key": "chat-demo-123-7a3c9e" }
+}
+```
+
+---
+
+## How it works
+
+- **Orchestrator**: supplies tools to the model, loops until enough data is collected, then chooses exactly one tool to run.
+- **Registry**: your functions (name+version+schema+handler).
+- **Validators**: rejects bad inputs before your code runs.
+- **Idempotency**: generates `chat-<thread>-<hex>`, pass to your creates.
+- **Store**: remembers prior tool results by `thread_id` (swap to Redis).
+
+---
+
+## Environment
+
+- `OPENAI_API_KEY` must be set.
+- Ruby ≥ 3.1, Rails ≥ 7.0.
+
+---
+
 ## License
+
 MIT

data/lib/llm/agent/rails/version.rb

@@ -2,7 +2,7 @@
 module Llm
   module Agent
     module Rails
-      VERSION = "0.1.0"
+      VERSION = "0.1.2"
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: llm-agent-rails
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.2
 platform: ruby
 authors:
 - Phia Vang
@@ -81,7 +81,7 @@ licenses:
 - MIT
 metadata:
   allowed_push_host: https://rubygems.org
-  source_code_uri: https://github.com/yourname/llm-agent-rails
+  source_code_uri: https://github.com/pnvang/llm-agent-rails
 post_install_message:
 rdoc_options: []
 require_paths: