Struggling to get Custom Model Names working

[kanejamison]

Hi all. I'm 95% of the way towards finishing an installation with a custom namespace but struggling with the foreign key settings.

TLDR, I want to namespace the models into LLM::Chat, LLM::Message, and LLM::ToolCall, but when I create a chat I'm getting an Undefined Column error:

This command creates the Chat:

app-name(dev)> c = LLM::Chat.create
  TRANSACTION (0.3ms)  BEGIN /*application='AppName'*/
  LLM::Chat Create (3.6ms)  INSERT INTO "llm_chats" ("model_id", "created_at", "updated_at") VALUES (NULL, '2025-08-20 17:32:58.859777', '2025-08-20 17:32:58.859777') RETURNING "id" /*application='AppName'*/
  TRANSACTION (0.9ms)  COMMIT /*application='AppName'*/
=> #<LLM::Chat:0x000000012321fa10 id: 2, model_id: nil, created_at: "2025-08-20 17:32:58.859777000 +0000", updated_at: "2025-08-20 17:32:58.859777000 +0000">

This command creates the .ask and then fails on PG::UndefinedColumn: ERROR: column llm_tool_calls.message_id even though I have set the foreign key in the model.

app-name(dev)> c.ask "What is the best laptop for college students at Target right now?"
  TRANSACTION (0.2ms)  BEGIN /*application='AppName'*/
  LLM::Message Create (1.3ms)  INSERT INTO "llm_messages" ("llm_chat_id", "role", "content", "model_id", "input_tokens", "output_tokens", "llm_tool_call_id", "created_at", "updated_at") VALUES (2, 'user', 'What is the best laptop for college students at Target right now?', NULL, NULL, NULL, NULL, '2025-08-20 17:33:05.774244', '2025-08-20 17:33:05.774244') RETURNING "id" /*application='AppName'*/
  TRANSACTION (0.4ms)  COMMIT /*application='AppName'*/
  LLM::Message Load (2.0ms)  SELECT "llm_messages".* FROM "llm_messages" WHERE "llm_messages"."llm_chat_id" = 2 ORDER BY "llm_messages"."created_at" ASC /*application='AppName'*/
  LLM::ToolCall Load (0.8ms)  SELECT "llm_tool_calls".* FROM "llm_tool_calls" WHERE "llm_tool_calls"."message_id" = 2 /*application='AppName'*/
(app-name):3:in '<main>': PG::UndefinedColumn: ERROR:  column llm_tool_calls.message_id does not exist (ActiveRecord::StatementInvalid)
LINE 1: ...CT "llm_tool_calls".* FROM "llm_tool_calls" WHERE "llm_tool_...
                                                             ^

/Users/username/.rbenv/versions/3.4.5/lib/ruby/gems/3.4.0/gems/activerecord-8.0.2/lib/active_record/connection_adapters/postgresql/database_statements.rb:160:in 'PG::Connection#exec': ERROR:  column llm_tool_calls.message_id does not exist (PG::UndefinedColumn)
LINE 1: ...CT "llm_tool_calls".* FROM "llm_tool_calls" WHERE "llm_tool_...
                                                             ^

	from /Users/username/.rbenv/versions/3.4.5/lib/ruby/gems/3.4.0/gems/activerecord-8.0.2/lib/active_record/connection_adapters/postgresql/database_statements.rb:160:in 'ActiveRecord::ConnectionAdapters::PostgreSQL::DatabaseStatements#perform_query'

Migrations

Here are my migrations:

db/migrate/20250814055646_create_llm_chats.rb:

class CreateLLMChats < ActiveRecord::Migration[8.0]
  def change
    create_table :llm_chats do |t|
      t.string :model_id
      t.timestamps
    end
  end
end

db/migrate/20250814055647_create_llm_messages.rb:

class CreateLLMMessages < ActiveRecord::Migration[8.0]
  def change
    create_table :llm_messages do |t|
      t.references :llm_chat, null: false, foreign_key: true
      t.string :role
      t.text :content
      t.string :model_id
      t.integer :input_tokens
      t.integer :output_tokens
      t.references :llm_tool_call
      t.timestamps
    end
  end
end

db/migrate/20250814055648_create_llm_tool_calls.rb:

class CreateLLMToolCalls < ActiveRecord::Migration[8.0]
  def change
    create_table :llm_tool_calls do |t|
      t.references :llm_message, null: false, foreign_key: true
      t.string :tool_call_id, null: false
      t.string :name, null: false
      t.jsonb :arguments, default: {}
      t.timestamps
    end

    add_index :llm_tool_calls, :tool_call_id
  end
end

Models

And here are my Models:

app/models/llm/chat.rb:

class LLM::Chat < ApplicationRecord
  acts_as_chat message_class: "LLM::Message", tool_call_class: "LLM::ToolCall"
end

app/models/llm/message.rb:

class LLM::Message < ApplicationRecord
  acts_as_message chat_class: "LLM::Chat", tool_call_class: "LLM::ToolCall", chat_foreign_key: "llm_chat_id", tool_call_foreign_key: "llm_tool_call_id"
end

app/models/llm/tool_call.rb:

class LLM::ToolCall < ApplicationRecord
  acts_as_tool_call message_class: "LLM::Message", message_foreign_key: "llm_message_id"
end

Schema

Here's my schema as it's created. You can see llm_tool_calls.llm_message_id exists as a column, and above it is set as message_foreign_key: "llm_message_id", but doesn't seem to be getting used.

create_table "llm_chats", force: :cascade do |t|
    t.string "model_id"
    t.datetime "created_at", null: false
    t.datetime "updated_at", null: false
  end

  create_table "llm_messages", force: :cascade do |t|
    t.bigint "llm_chat_id", null: false
    t.string "role"
    t.text "content"
    t.string "model_id"
    t.integer "input_tokens"
    t.integer "output_tokens"
    t.bigint "llm_tool_call_id"
    t.datetime "created_at", null: false
    t.datetime "updated_at", null: false
    t.index ["llm_chat_id"], name: "index_llm_messages_on_llm_chat_id"
    t.index ["llm_tool_call_id"], name: "index_llm_messages_on_llm_tool_call_id"
  end

  create_table "llm_tool_calls", force: :cascade do |t|
    t.bigint "llm_message_id", null: false
    t.string "tool_call_id", null: false
    t.string "name", null: false
    t.jsonb "arguments", default: {}
    t.datetime "created_at", null: false
    t.datetime "updated_at", null: false
    t.index ["llm_message_id"], name: "index_llm_tool_calls_on_llm_message_id"
    t.index ["tool_call_id"], name: "index_llm_tool_calls_on_tool_call_id"
  end

[kanejamison]

I managed to get this working a different way, by leaving normal names on the references columns and defining the foreign_key instead:

class CreateLLMMessages < ActiveRecord::Migration[8.0]
  def change
    create_table :llm_messages do |t|
      t.references :chat, null: false, foreign_key: { to_table: :llm_chats }
      t.string :role
      t.text :content
      t.string :model_id
      t.integer :input_tokens
      t.integer :output_tokens
      t.references :tool_call
      t.timestamps
    end
  end
end

class CreateLLMMessages < ActiveRecord::Migration[8.0]
  def change
    create_table :llm_messages do |t|
      t.references :chat, null: false, foreign_key: { to_table: :llm_chats }
      t.string :role
      t.text :content
      t.string :model_id
      t.integer :input_tokens
      t.integer :output_tokens
      t.references :tool_call
      t.timestamps
    end
  end
end

Then removing the custom foreign_keys from the models:

class LLM::Chat < ApplicationRecord
  acts_as_chat message_class: "LLM::Message", tool_call_class: "LLM::ToolCall"
end

class LLM::Message < ApplicationRecord
  acts_as_message chat_class: "LLM::Chat", tool_call_class: "LLM::ToolCall"
end

class LLM::ToolCall < ApplicationRecord
  acts_as_tool_call message_class: "LLM::Message"
end

From there I'm able to successfully replicate the Weather tool example from https://rubyllm.com/tools/#what-are-tools :

I am able to run commands like LLM::Message.find(5).tool_results and LLM::Message.find(4).tool_calls and LLM::Message.find(4).tool_call? and I can see the resulting tool call from the tool_call_id reference, so that seems to work as well.

The setup still feels a little off to me since it doesn't really match the suggested results from https://rubyllm.com/rails/#customizing-models - would love to know which of these approaches feels like a better long-term match for RubyLLM?

[crmne]

Hey @kanejamison I don't really use namespaces for RubyLLM's ActiveRecord models. If you find any mistakes in the docs or the generators, could you please make a PR? Thanks :)