🦙🤖 v0.1.16 Release! Multi-agent support

llama_bot_rails v0.1.16 — Release Notes

Date: 2025-08-14
Project: llama_bot_rails

TL;DR

This release enables per-subscription agent routing in LlamaBotRails::ChatChannel by accepting a new ActionCable parameter agent_state_builder_class. If omitted, behavior defaults to your configured state_builder_class (or the built‑in 'LlamaBotRails::AgentStateBuilder'). No breaking changes.

---

What changed

File: app/channels/llama_bot_rails/chat_channel.rb

• New: Read params[:agent_state_builder_class] at subscribe time and store it in @agent_state_builder_class.
• Defaulting logic: If the param is blank, fall back to LlamaBotRails.config.state_builder_class or 'LlamaBotRails::AgentStateBuilder'.
• Internal usage change: Replace hard-coded lookup of builder_class_name with the instance variable @agent_state_builder_class so the chosen builder is respected throughout the channel lifecycle.

Relevant diff (conceptual):

# before
builder_class_name = LlamaBotRails.config.state_builder_class || 'LlamaBotRails::AgentStateBuilder'

# after (set during subscription, then reused)
@agent_state_builder_class = params[:agent_state_builder_class]
@agent_state_builder_class ||= LlamaBotRails.config.state_builder_class || 'LlamaBotRails::AgentStateBuilder'
...
builder_class_name = @agent_state_builder_class

Why it matters

• Multi‑agent routing: You can now route a single websocket connection to different agent graphs/builders dynamically, per subscription. Useful for:

  • Multi‑tenant apps (per‑account agent behavior).
  • Feature flags/experiments (A/B different agent graphs).
  • Environment‑ or context‑specific agents (e.g., Support vs. Sales vs. Ops).

• Backwards compatible: Existing apps that rely on global configuration continue to work as-is.

How to use it

Pass the desired agent state builder class name (String) when creating the ActionCable subscription.

JavaScript (ActionCable consumer)

import consumer from "channels/consumer";

const subscription = consumer.subscriptions.create(
  {
    channel: "LlamaBotRails::ChatChannel",
    agent_state_builder_class: "MyApp::SalesAgentStateBuilder"
  },
  {
    received(data) {
      console.log("chat payload", data);
    }
  }
);

Stimulus / Rails UJS (example payload)

consumer.subscriptions.create({
  channel: "LlamaBotRails::ChatChannel",
  agent_state_builder_class: "MyApp::SupportAgentStateBuilder"
});

Ruby (global default remains supported)

# config/initializers/llama_bot_rails.rb
LlamaBotRails.configure do |c|
  c.state_builder_class = 'MyApp::DefaultAgentStateBuilder'
end

If you do not pass agent_state_builder_class in the subscription, the channel uses c.state_builder_class, or falls back to 'LlamaBotRails::AgentStateBuilder'.

Notes & compatibility

• Type: The parameter should be a String representing a constantized class (e.g., 'MyApp::SalesAgentStateBuilder'). Ensure the class is autoloadable in Rails so that constantization succeeds wherever the builder is instantiated.
• Lifecycle: The selection occurs at subscription time and is stored on the channel instance. If you need to switch agents, unsubscribe and create a new subscription with a different class.
• No breaking changes: Existing integrations using only the global config continue to work.

Security & safety guidance

Passing a class name via params is powerful. To avoid abuse:

• Whitelist allowed builder classes before constantizing. For example, map short tokens → class names you control.
• Validate the param (presence, namespace, or membership in your whitelist) prior to use.
• Least privilege: Keep each builder scoped to only the routes/actions it needs.

Example of a simple allow‑list:

ALLOWED_BUILDERS = {
  'support' => 'MyApp::SupportAgentStateBuilder',
  'sales'   => 'MyApp::SalesAgentStateBuilder'
}.freeze

requested = params[:agent_state_builder_class]
@agent_state_builder_class = ALLOWED_BUILDERS.fetch(requested) { 'MyApp::DefaultAgentStateBuilder' }

Testing checklist

1. Default path: Omit agent_state_builder_class; verify your app uses the configured default.
2. Custom class path: Provide a valid class; verify the correct agent graph executes.
3. Invalid class: Provide an invalid value; confirm your validation/whitelist prevents misuse.
4. Multi‑subscription: Open two subscriptions with different builders and verify isolated behavior.

Developer log reference

• 2025‑08‑07: “Add ability to route to multiple agents through the chat_channel.rb, by passing in a different parameter.”

Versioning

• Release: 0.1.16
• Impact: Minor (feature, backward compatible)

---

Summary (one‑liner)

ChatChannel now supports per‑subscription agent selection via agent_state_builder_class, enabling safe, flexible multi‑agent routing without breaking existing apps.

🦙🤖 v0.1.15

LlamaBot Rails Gem – v0.1.15 Release Notes (2025‑08‑01)

Overview

This patch release hardens WebSocket connectivity and formalizes version tracking. It requires no breaking changes for existing integrations.

✨ Key Changes

1. Robust WebSocket Scheme Normalization

   • ChatChannel now intelligently infers the correct scheme:

     • Keeps ws:// or wss:// if already correct.
     • Converts https:// → wss:// and http:// → ws://.
     • Defaults to ws:// in development and wss:// elsewhere when the URL is missing or unrecognized.

   • Ensures secure connections in production by default and prevents common misconfiguration errors when passing URLs from env vars or user input.

2. Environment Variable Support

   • Added note to dev logs to surface a dedicated .env entry for overriding the default WebSocket scheme when needed.

3. Version Bump

   • VERSION constant updated from 0.1.14 to 0.1.15.

🔒 Why It Matters

• Security – Guarantees encrypted wss:// connections in production, eliminating accidental plaintext traffic.
• Reliability – Accepts a wider range of URL formats, reducing deployment friction and “invalid URI scheme” errors.
• Developer Experience – Zero‑config behavior in dev (ws://) and prod (wss://) means fewer environment‑specific conditionals and quicker onboarding.

🛠 Upgrade Guide

bundle update llama_bot_rails

No other changes required. Verify that any environment variables supplying WebSocket endpoints include a valid host; the gem now handles the scheme for you.

📝 Internal Log

See docs/dev_logs/0.1.15 for the full developer log entry.

🦙🤖 0.1.14

Release 0.1.14 — “Solid Streams” (2025-07-31)
Primary themes: smoother streaming UX, bullet-proof WebSocket handling, smarter auth, and richer route introspection.

---

✨ Added

Area	Change	Why it matters
Streaming UX	AIMessageChunk support in chat_channel.rb & JS templates	Lets slow/offline models emit partial tokens in real-time → dramatically better perceived latency.
Error surfacing	Red “parse error” banner in chat.html.erb when a tool call fails to return valid JSON	Users instantly see why a response blew up instead of silent failure.
Route introspection	LlamaBotRails::RouteHelper (new) extracts verbs, paths, YARD docs & strong params to XML	Foundations for auto-scoping agent commands to safe Rails routes.
Auth v2	agent_auth_2.rb rewrites the concern to work in Controllers and ActiveJob, adds authenticate_user_or_agent!, gracefully dovetails with Devise	One unified guard no matter who’s calling—browser session or signed agent token.
Docs	docs/dev_logs/0.1.14 created	Captures the above in-repo for posterity.

---

🐛 Fixed

• Tool‑call JSON parsing crashes now surface visibly and stop at the offending chunk instead of killing the channel.

• Numerous spec flakiness issues by replacing WebMock stubs with instance_double + explicit Net::HTTP mocks; cleaner, faster tests.

---

🧪 Tests

• Re‑authored llama_bot_spec.rb to isolate network dependencies; covers success paths, concatenated/invalid JSON, HTTP errors, and minimal‑body edge cases.

• Added assertions for header correctness and SSL toggling.

---

⚠️ Heads‑up / Potential Breakers

• AgentAuth API changed: prefer authenticate_user_or_agent!. Existing authenticate_user! or authenticate_<scope>! still work but emit a deprecation warning.

• RouteHelper is independent; wiring it into your agent whitelist is up to the host app.

---

⬆️ Upgrade Notes

1. Bundle & migrate: no DB schema changes.

2. Restart any long‑running Action Cable workers—socket semantics changed.

3. If you override AgentAuth, diff against the new concern to keep custom logic intact.

4. For custom front‑ends: subscribe to "AIMessageChunk" events or keep using the final "ai" payloads.

---

This release tightens every bolt around streaming and connectivity. If your app streams tokens or runs on shaky networks, take the upgrade—your users will feel the difference.

🦥 v0.1.13 – Agent Auth & User Resolver System

🦥 LlamaBot Rails v0.1.13 – Agent Auth & User Resolver System

This release introduces a flexible agent authentication system that seamlessly bridges Devise sessions and agent token workflows. It enables secure, transparent agent execution inside Rails apps — with full override capability.

✨ New in v0.1.13

🔐 Pluggable user_resolver, current_user_resolver, and sign_in_method

Developers can now customize how user context is loaded and set for LlamaBot agent requests:

# config/initializers/llamabot.rb

# How to resolve a User from an agent token payload
LlamabotRails.user_resolver = ->(user_id) {
  User.find_by(id: user_id)
}

# How to resolve the current user from Rack env
LlamabotRails.current_user_resolver = ->(env) {
  env["warden"]&.user
}

# How to sign a user into the session manually
LlamabotRails.sign_in_method = ->(env, user) {
  env["warden"]&.set_user(user)
}

By default, the gem tries to auto-detect Devise and use its default_scope. If Devise is missing, it emits a helpful log message and returns nil, allowing you to override as needed.

---

🛡️ Unified Agent + User Auth Flow

Includes the new LlamaBotRails::AgentAuth module, which:

• Adds authenticate_user_or_agent! — guards both browser and agent flows
• Automatically aliases all Devise authenticate_#{scope}! methods to use the new flow
• Gracefully falls back if Devise isn't installed
• Rejects agent access to controller actions unless explicitly whitelisted via llama_bot_allow

class PagesController < ApplicationController
  include LlamaBotRails::AgentAuth

  llama_bot_allow :update  # safe opt-in to allow agents to use #update
end

This allows agents to securely call into Rails routes only if:

• They present a valid LlamaBot token, and
• The action is explicitly allowlisted

---

💡 Use Cases Enabled

• Custom authentication flows (e.g., JWT, API keys, session-less agents)
• Shared sessions between agent and browser users
• Safe development of agent endpoints without exposing the full app
• Drop-in Rails integrations for teams not using Devise

---

🧠 Upgrade Tip

This release deprecates direct use of authenticate_user! for agent-bound routes. All future versions will standardize on authenticate_user_or_agent!.

For Devise apps, this works automatically. For non-Devise apps, override the resolvers in your initializer.

🛡️🎉 0.1.12 - Secured with Principle of Least Priviledge

LlamaBot Rails – v0.1.12 (2025-07-13)

✨ Highlights

Theme	What changed	Why it matters
Principle of Least Privilege	New DSLllama_bot_allow :update, :preview …	You now expose only the controller actions you intend the agent to reach—nothing else.
Unified Guard	authenticate_user_or_agent! replaces scattered Devise filters when you include LlamaBotRails::AgentAuth.	• Browser requests still flow through your existing Devise scopes.• Agent calls must present a LlamaBot token and hit an allow-listed action.• Non-listed actions return 403 Forbidden (JSON message).
Header Scheme	Agent now sendsAuthorization: LlamaBot	Distinct scheme prevents accidental clashes with generic Bearer tokens.
Multi-scope Devise Support	All authenticate_! methods are auto-aliased to the new guard and emit a deprecation warning.	Works out-of-the-box whether you use :user, :admin, :account, etc.
Safer Defaults	Controllers that don’t opt-in remain untouched; “god-mode” still available behind enable_console_tool.	Ships secure by default while keeping the escape hatch for power users.
DX niceties	• Clear 403 JSON error when action not whitelisted.• Deprecation warnings guide devs to update skip lines.• Generator template updated to use authenticate_user_or_agent!.	Fewer surprises, smoother migrations.

---

🔒 Security / Authorization Details

• Token + Allow-list double-gate
  llama_bot_request? verifies the signed token → guard checks action_name against llama_bot_permitted_actions. Both must pass.

• Scoped to the controller
  Nothing changes unless you add

  include LlamaBotRails::ControllerExtensions
  include LlamaBotRails::AgentAuth
  

• Explicit public actions
  Skip the guard with

  skip_before_action :authenticate_user_or_agent!, only: [:show, :home]
  

---

🚚 Upgrade Path

1. Bump the gem

   bundle add llama_bot_rails --version "~> 0.1.12"
   

2. Update controllers that include AgentAuth

   • Replace any

     skip_before_action :authenticate_user!
     

     with

     skip_before_action :authenticate_user_or_agent!
     

   • Add llama_bot_allow for each action the agent must reach.

3. Update your agent client to send

   Authorization: LlamaBot <token>
   

4. Watch the logs for deprecation warnings—rename old skips at your convenience.

No breaking changes for controllers that do not include AgentAuth.

---

🛠 Internal / Dev Notes

• Added class_attribute :llama_bot_permitted_actions with per-controller storage.

• Unit & request specs cover happy-path, blocked-path, multi-scope Devise, and public skips.

• Deprecation helper uses ActiveSupport::Deprecation.__send__(:warn, …) for Rails 6/7 compatibility.

---

Enjoy a tighter, clearer, and safer integration—now shipping in v0.1.12!

🚀 Release v0.1.11 – “Full-Stack Agentic Rails Bundle”

✨ Overview

This release marks the first fully stable, end-to-end integration between all three core components of the LlamaPress AI platform:

• LlamaPress (Rails flagship app)

• llama_bot_rails (Rails Gem)

• LlamaBot (FastAPI/LangGraph/Python backend)

All components in v0.1.11 are designed, tested, and verified to work seamlessly together, delivering the smoothest developer experience yet for bringing AI agent capabilities into real Ruby on Rails applications.

---

🔗 Compatibility

LlamaPress | llama_bot_rails Gem | LlamaBot Backend -- | -- | -- v0.1.11 | v0.1.11 | v0.1.11

---

🎯 What’s New

• Stable Full-Stack Integration:
  End-to-end compatibility between Rails app, agentic Gem, and Python backend.

• Frictionless Developer Experience:

  • One-line setup: git clone, bash bin/init, docker-compose up

  • Automatic submodule & dependency management

  • Interactive prompt for OpenAI API key

• Seamless Local Development:

  • Docker-based workflow—no need for preinstalled Ruby, Rails, or Python

  • All major setup, DB, and environment tasks handled automatically

• Agentic Chatbot in Rails:

  • Instantly chat with LlamaBot inside your Rails app UI after launch

  • Real Rails models, controllers, and DBs—fully hackable and extensible

• Production-Ready Structure:

  • Locked, versioned dependencies for all major services

  • Clear compatibility between all components

---

🧑‍💻 Getting Started

git clone --recursive https://github.com/your-org/llamapress.git
bash bin/init   # Paste your OpenAI API key when prompted
docker-compose up
# Then visit http://localhost:3000/llama_bot

---

📝 Notes

• Make sure to use v0.1.11 for all three components for the best, stable experience.

• See README for further documentation, customization tips, and contribution guidelines.

---

🙏 Special Thanks

v0.1.8

🧩 llama_bot_rails – v0.1.8 – Developer Experience + Docker Support

This release is the first public OSS-ready version of the llama_bot_rails gem, built to integrate seamlessly with the LlamaBot backend and support full-stack LangGraph agents inside Rails apps.

🎯 What's Included:

🧠 Agent Chat UI: Adds /llama_bot/agent/chat route and controller to talk to your backend agent from within Rails

🧰 Install Generator: rails generate llama_bot:install adds:

llama_bot.rb initializer with api_base_url and allowed_routes DSL

Auto-injection of config.hosts << /host.docker.internal/ in development.rb (Docker-safe!)

🐳 Docker-Friendly Defaults: Built to work with the public Docker backend image:

docker run -e OPENAI_API_KEY=sk-... -p 8000:8000 kody06/llamabot-backend:v0.1.0

🛠 Prerequisites
Rails 6.1+

Compatible with any backend that speaks the LlamaBot HTTP spec

Uses http://host.docker.internal to connect Rails → FastAPI in dev

📈 What’s Next

🧩 Whitelisted Tool DSL: Configure exactly which routes and verbs the agent can access:

config.allowed_routes = {
"refund_user" => { verb: :post, path: "/agent/users/:id/refund" }
}

More scaffold generators (rails g llama_bot:action foo)

Fly.io one-click deploy support

Deeper multi-tenant awareness

📥 Feedback? Open an issue or ping us in Discord