rails_ai_kit 0.1.6 → 0.1.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e0ed50b48e8ada5fcbdee2169fbcb5e3bd427a66cc609a3b2794a0202372c9a3
-  data.tar.gz: ef0472f6a40a0f31768a814e5115d0da43c07623f194f2d9ff58c004aab7571c
+  metadata.gz: be63d7b9ec9ef2a7c943cdb80fded8941102df5dd5c410698eda80f56fc65cc5
+  data.tar.gz: 6848aba88723727d242aa35b156757d860e91fefb6f9e28d92902d8d6c2dc587
 SHA512:
-  metadata.gz: 1d34a020030a1d8391b18d32c68374af6b918ab03f5edb51d56acc205e3a0c4f05a4bddbcb158b5bd9c0ac027bc8a5e60d5007f11fcf0135b6695716f25e3c96
-  data.tar.gz: b9a3e6a229716e9a28cee18ba85febb98c5ade412077c5e215cb4823a9bf0bb53bc495ba8f10109370368ab944571eab9ef50007023e232190dd189bf6ad204b
+  metadata.gz: a3b21a2cb175fc0ad89248bda65d812fe458ee31b68b3083d704ada7cea7b8adb2fe3b75781ee8c29c7a925966f4185dcb870db80f2753518fda7bc5f4dfc266
+  data.tar.gz: c3aa3961a3e430ba1ffdbd63b2390d2515c6eb8b896e32b1e26c5797bd492f859aa6882728c9037b97968bb762566e8fcf138ff8f4c87a268283e240e6a7c37a

data/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## [Unreleased]
 
+### Added
+
+- **Guardrails (LLM-as-judge)** – Generate then validate with safety checks (no vectors). `RailsAiKit.guard(prompt:, model:, checks: [:toxicity, :pii, :hallucination], threshold: 0.8)` returns `GuardResult` with `output`, `safe?`, `scores`, `action`.
+- **Guards** – Toxicity, PII, Hallucination, Prompt injection (each uses LLM to score 0–1).
+- **LLM providers** – OpenAI, Anthropic (Claude), Google (Gemini), Groq, and custom URL + key (OpenAI-compatible). Single config: `llm_provider`, `llm_api_keys`, optional `llm_url`/`llm_key` for custom.
+- **ai_generate macro** – `ai_generate :summary, from: :content, guards: [...], threshold: 0.85` → `record.ai_summary` (generate + guardrails).
+- **Eval** – `RailsAiKit.eval(dataset: "path.json", model:)` returns accuracy, hallucination rate, toxicity failures, and per-item details.
+- **AI Traces** – Table `rails_ai_traces` (prompt, response, model, tokens, guard_scores, latency, action). Optional dashboard at `/ai_traces` via `rails g rails_ai_kit:dashboard`.
+- Install generator now creates both `rails_ai_kit_labels` and `rails_ai_traces` in one migration.
+
 ## [0.1.3] - 2026-03-07
 
 ### Fixed

data/README.md

@@ -4,219 +4,236 @@
 
 # Rails AI Kit
 
-**AI-first toolkit for Rails** — embeddings, vector search, and classification without running your own ML or calling LLMs on every request.
-
-> Rails gem for vector-based text classification (pgvector), embeddings (OpenAI, Cohere), similarity search, and generators. Train labels with examples; classify on save or in batch.
+**AI-first toolkit for Rails** — two core features today, more on the way.
 
 [![Ruby](https://img.shields.io/badge/Ruby-3.0+-red.svg)](https://rubygems.org/gems/rails_ai_kit)
 [![Rails](https://img.shields.io/badge/Rails-6.0+-blue.svg)](https://rubyonrails.org/)
 [![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
 
+**[Source code](https://github.com/imrrohitt/rails_ai_kit)** · **[RubyGems](https://rubygems.org/gems/rails_ai_kit)**
+
 ---
 
-### Overview
+## Two main features
 
-| | |
-|:---|:---|
-| **Rails-native** | Generators, ActiveRecord integration, single config file |
-| **Vector-ready** | [pgvector](https://github.com/pgvector/pgvector) with OpenAI or Cohere embeddings |
-| **Modular** | Use only the features you need; add more as the gem evolves |
+Rails AI Kit currently provides **two independent feature sets**. Use one, both, or add more as the gem evolves.
 
-**[Source code](https://github.com/imrrohitt/rails_ai_kit)** · **[RubyGems](https://rubygems.org/gems/rails_ai_kit)**
+| Feature | What it does | Use when |
+|--------|----------------|----------|
+| **1. Guardrails** | Run LLM generation through safety checks (toxicity, PII, hallucination, prompt injection). Generate → validate → score → allow/block. | You call an LLM and want to block unsafe outputs or toxic user inputs. |
+| **2. Vector classification** | Classify text using embeddings + pgvector. Train labels with examples; auto-classify on save or in batch. No ML training, no LLM per request. | You need categories (e.g. support tickets, content tags, document routing). |
+
+*More features (evals, tool use, etc.) are planned — the gem is actively developed.*
 
 ---
 
-## Features
+## Feature 1: Guardrails
 
-Rails AI Kit is organized around **features**. Each is optional and self-contained.
+Guardrails wrap LLM calls with **safety checks**. You get a generated response plus scores; you decide allow/block by threshold. Checks run on both the **model output** and the **user prompt** (so toxic or injection-style inputs are detected even if the model refuses to comply).
 
-### Classifier
+### What you get
 
-Vector-based text classification: route support tickets, moderate content, tag articles, or categorize documents. No ML training — you provide example texts per label; classification is nearest-neighbor in PostgreSQL.
+- **`RailsAiKit.guard(prompt:, model:, checks:, threshold:)`** — One call: generate + run checks. Returns `GuardResult` with `output`, `safe?`, `scores`, `action` (`:allow` / `:block`).
+- **Guards:** toxicity, PII, hallucination, prompt injection (each uses an LLM-as-judge or keyword rules).
+- **Prompt + output:** Toxicity and prompt-injection also evaluate the **user prompt**; final toxicity = max(prompt_toxicity, output_toxicity). Keyword safety net for obvious offensive language.
+- **Rails macro:** `ai_generate :summary, from: :content, guards: [...]` → `article.ai_summary` (generate then guard).
+- **Eval:** `RailsAiKit.eval(dataset: "eval.json", model:)` → accuracy, hallucination rate, toxicity failures.
+- **AI Traces:** Optional `rails_ai_traces` table + `/ai_traces` dashboard to inspect prompts, responses, scores, and latency.
 
-- Train labels with examples → one vector per label  
-- Auto-classify on save (embed + compare → `label`, `confidence_score`)  
-- Similarity search: `Model.similar_to("query", limit: 5)`  
-- Batch classify for backfills or background jobs  
+### LLM providers
 
-*Requires pgvector, an embedding API (OpenAI/Cohere), and the install + vector_columns generators.*
+One config, same API: **OpenAI**, **Anthropic (Claude)**, **Google (Gemini)**, **Groq**, or **custom** (any OpenAI-compatible endpoint via `llm_url` + `llm_key`).
 
----
+### Quick example (Guardrails)
 
-## Requirements
+```ruby
+result = RailsAiKit.guard(
+  prompt: "What is the capital of France?",
+  model: "gpt-4o-mini",
+  checks: [:toxicity, :hallucination],
+  threshold: 0.8
+)
 
-- Rails 6+
-- PostgreSQL with [pgvector](https://github.com/pgvector/pgvector) (for Classifier and vector features)
-- An embedding API key (OpenAI or Cohere) for features that use embeddings
+result.output   # => "The capital of France is Paris."
+result.safe?    # => true
+result.scores   # => { "toxicity" => 0.0, "hallucination" => 0.0, "label" => "factual" }
+result.action   # => :allow
+```
+
+Toxic or injection-style prompts are scored (including a keyword safety net); if any score exceeds `threshold`, `action` is `:block`.
 
 ---
 
-## Installation
+## Feature 2: Vector classification
 
-Add to your Gemfile:
+Vector classification uses **embeddings + pgvector** to assign labels to text. You train each label with example phrases; the gem embeds them, stores one vector per label, and classifies new content by nearest-neighbor (cosine distance). No ML training and no LLM call per classification — only an embedding API (OpenAI or Cohere).
+
+### What you get
+
+- **Train labels:** `RailsAiKit.classifier("Article").train("sports", examples: ["football match", "cricket"])` → one vector per label in `rails_ai_kit_labels`.
+- **Auto-classify on save:** Add `vector_classify :content, labels: ["sports", "politics", "tech"]` to your model. On save, the gem embeds `content`, stores it, compares to label vectors, and sets `label` and `confidence_score`.
+- **Classify without saving:** `RailsAiKit.classifier("Article").classify("India won the cricket match")` → `{ label: "sports", confidence: 0.91 }`.
+- **Batch classify:** `RailsAiKit.classifier("Article").batch_classify(records, text_attribute: :content)`.
+- **Similarity search:** `Article.similar_to("new iPhone launch", limit: 5)`.
+- **Filtering:** `Article.where(label: "sports")`, `Article.where("confidence_score >= ?", 0.8)`.
+
+### Quick example (Vector classification)
 
 ```ruby
-gem "rails_ai_kit"
-```
+# 1. Train labels once
+c = RailsAiKit.classifier("Article")
+c.train("sports", examples: ["football match", "cricket tournament"])
+c.train("technology", examples: ["new iPhone launch", "AI update"])
 
-Then:
+# 2. Model
+class Article < ApplicationRecord
+  vector_classify :content, labels: ["sports", "politics", "technology"]
+end
 
-```bash
-bundle install
+# 3. Create record → auto-classified
+article = Article.create!(content: "Apple released a new iPhone")
+article.label            # => "technology"
+article.confidence_score # => 0.91
 ```
 
-### 1. Install (pgvector + labels table)
+---
+
+## Requirements
+
+- **Rails 6+**
+- **PostgreSQL** with [pgvector](https://github.com/pgvector/pgvector) (for vector classification only)
+- **Embedding API** (OpenAI or Cohere) for vector classification
+- **LLM API** (OpenAI, Anthropic, Google, Groq, or custom) for Guardrails / `ai_generate` / Eval
+
+---
+
+## Installation
 
-For the **Classifier** feature, the gem needs pgvector and one internal table for label embeddings:
+```ruby
+# Gemfile
+gem "rails_ai_kit"
+```
 
 ```bash
+bundle install
 rails g rails_ai_kit:install
 rails db:migrate
 ```
 
-### 2. Configure
+The install generator adds:
+
+- **pgvector** and tables: `rails_ai_kit_labels` (for vector classification), `rails_ai_traces` (for Guardrails tracing)
+- **Initializer:** `config/initializers/rails_ai_kit.rb`
+
+### Configuration
 
-In `config/initializers/rails_ai_kit.rb` (create the file):
+Edit `config/initializers/rails_ai_kit.rb`:
 
 ```ruby
 RailsAiKit.configure do |config|
-  config.embedding_provider = :openai   # or :cohere
-  config.embedding_dimensions = 1536   # 1536 for OpenAI text-embedding-3-small
-
+  # ----- Vector classification (embeddings) -----
+  config.embedding_provider = :openai
+  config.embedding_dimensions = 1536
   config.api_keys = {
     openai: ENV["OPENAI_API_KEY"],
     cohere: ENV["COHERE_API_KEY"]
   }
-
   config.default_classifier_name = "default"
+
+  # ----- Guardrails (LLM) -----
+  config.llm_provider = :openai
+  config.default_llm_model = "gpt-4o-mini"
+  config.llm_api_keys = {
+    openai: ENV["OPENAI_API_KEY"],
+    anthropic: ENV["ANTHROPIC_API_KEY"],
+    google: ENV["GOOGLE_AI_API_KEY"],
+    groq: ENV["GROQ_API_KEY"]
+  }
+  # Custom endpoint:
+  # config.llm_provider = :custom
+  # config.llm_url = "https://your-llm.example.com/v1"
+  # config.llm_key = ENV["CUSTOM_LLM_KEY"]
+
+  config.trace_llm_calls = true
 end
 ```
 
-Use environment variables or Rails credentials; do not commit raw API keys.
+Use env vars or Rails credentials; do not commit API keys.
 
-### 3. Add vector columns (for Classifier)
+### Add vector columns (for vector classification only)
 
-For models you want to classify (e.g. `articles` with a `content` column):
+For models you want to classify:
 
 ```bash
 rails g rails_ai_kit:vector_columns Article content
 rails db:migrate
 ```
 
-This adds `embedding` (vector), `label` (string), and `confidence_score` (float).
+Adds `embedding`, `label`, `confidence_score` to the table.
 
 ---
 
-## Usage
+## Usage in detail
 
-### Embeddings (general)
+### Guardrails
 
-Use embeddings anywhere in your app:
-
-```ruby
-RailsAiKit.embed("some text")                    # => array of floats
-RailsAiKit.embedding.embed("text")               # same
-RailsAiKit.embedding.embed_batch(["a", "b"])     # batch
-```
+| Method | Description |
+|--------|-------------|
+| `RailsAiKit.guard(prompt:, model:, checks: [:toxicity, :hallucination], threshold: 0.8)` | Generate + run checks; returns `GuardResult` |
+| `result.output`, `result.safe?`, `result.scores`, `result.action` | Response text, safe flag, scores hash, `:allow` / `:block` |
+| `RailsAiKit.eval(dataset: "path.json", model:)` | Run eval dataset; returns accuracy, hallucination rate, toxicity failures |
+| `rails g rails_ai_kit:dashboard` | Add `/ai_traces` dashboard |
 
-### Classifier feature
-
-#### Declare classification on a model
+**ai_generate macro (Guardrails):**
 
 ```ruby
 class Article < ApplicationRecord
-  vector_classify :content,
-    labels: ["sports", "politics", "technology"]
+  ai_generate :summary,
+    from: :content,
+    prompt_template: "Summarize in 2–3 sentences:\n\n%{text}",
+    guards: [:toxicity, :hallucination],
+    threshold: 0.85
 end
+article.ai_summary  # => generated summary or nil if blocked
 ```
 
-On save, the gem will:
-
-1. Generate an embedding for `content`
-2. Store it in `embedding`
-3. Compare to trained label vectors and set `label` and `confidence_score`
-
-#### Train labels first
-
-Before classifying, train each label with example texts:
-
-```ruby
-c = RailsAiKit.classifier("Article")
-
-c.train("sports", examples: [
-  "football match",
-  "cricket tournament",
-  "Olympic gold medal"
-])
-c.train("politics", examples: ["election results", "parliament debate"])
-c.train("technology", examples: ["new iPhone launch", "AI software update"])
-```
-
-#### Create records
-
-```ruby
-article = Article.create!(content: "Apple released a new iPhone")
-article.label            # => "technology"
-article.confidence_score # => 0.91
-```
-
-#### Classify without saving
+### Vector classification
 
-```ruby
-RailsAiKit.classifier("Article").classify("India won the cricket match")
-# => { label: "sports", confidence: 0.91, distance: 0.09 }
-
-RailsAiKit.classifier("Article").classify_by_embedding(article.embedding)
-# => { label: "technology", confidence: 0.91, distance: 0.09 }
-```
+| Method | Description |
+|--------|-------------|
+| `RailsAiKit.classifier("Article").train("label", examples: ["...", "..."])` | Train a label with example texts |
+| `RailsAiKit.classifier("Article").classify("some text")` | Classify without saving → `{ label:, confidence:, distance: }` |
+| `RailsAiKit.classifier("Article").batch_classify(records, text_attribute: :content)` | Batch classify, set `label` and `confidence_score` on records |
+| `Article.similar_to("query", limit: 5)` | Similarity search (nearest neighbors by embedding) |
+| `Article.where(label: "sports")` | Filter by predicted label |
 
-#### Batch classification
+**vector_classify macro:**
 
 ```ruby
-records = Article.where(label: nil).limit(100)
-RailsAiKit.classifier("Article").batch_classify(records,
-  text_attribute: :content,
-  label_attribute: :label,
-  confidence_attribute: :confidence_score
-)
-# Optionally: records.each(&:save!)
-```
-
-#### Similarity search
-
-```ruby
-Article.similar_to("new iPhone launch", limit: 5)
+class Article < ApplicationRecord
+  vector_classify :content,
+    labels: ["sports", "politics", "technology"],
+    classifier_name: "Article"
+end
+# On save: embed content → store embedding → set label & confidence_score
 ```
 
-#### Filtering
+### Embeddings (shared)
 
 ```ruby
-Article.where(label: "sports")
-Article.where("confidence_score >= ?", 0.8)
+RailsAiKit.embed("some text")
+RailsAiKit.embedding.embed_batch(["a", "b"])
 ```
 
 ---
 
-## Example: Support ticket routing
-
-```ruby
-# app/models/support_ticket.rb
-class SupportTicket < ApplicationRecord
-  vector_classify :message,
-    labels: ["billing", "technical", "account"],
-    classifier_name: "SupportTicket"
-end
-
-# Train once
-c = RailsAiKit.classifier("SupportTicket")
-c.train("billing", examples: ["My payment failed", "Refund request", "Invoice issue"])
-c.train("technical", examples: ["App crashed", "Login not working", "Error message"])
-c.train("account", examples: ["Change email", "Close my account", "Password reset"])
+## Generators
 
-# Incoming ticket
-ticket = SupportTicket.create!(message: "My payment failed last night")
-ticket.label  # => "billing" → route to billing queue
-```
+| Generator | Purpose |
+|-----------|---------|
+| `rails g rails_ai_kit:install` | pgvector + `rails_ai_kit_labels` + `rails_ai_traces` + initializer |
+| `rails g rails_ai_kit:vector_columns ModelName content_column` | Add embedding, label, confidence_score to a table (vector classification) |
+| `rails g rails_ai_kit:dashboard` | Add AI Traces dashboard at `/ai_traces` (Guardrails) |
 
 ---
 
@@ -224,34 +241,43 @@ ticket.label  # => "billing" → route to billing queue
 
 | Option | Description | Default |
 |--------|-------------|---------|
+| **Embeddings (vector classification)** | | |
 | `embedding_provider` | `:openai` or `:cohere` | `:openai` |
-| `embedding_dimensions` | Vector size (must match provider) | `1536` |
-| `api_keys` | Hash of provider => API key | `{}` |
-| `default_classifier_name` | Classifier name when none given | `"default"` |
+| `embedding_dimensions` | Vector size | `1536` |
+| `api_keys` | Embedding API keys | `{}` |
+| `default_classifier_name` | Classifier name when not specified | `"default"` |
+| **LLM (Guardrails)** | | |
+| `llm_provider` | `:openai`, `:anthropic`, `:google`, `:groq`, `:custom` | `:openai` |
+| `llm_api_keys` | LLM API keys | `{}` |
+| `llm_url`, `llm_key` | Custom LLM endpoint | `nil` |
+| `default_llm_model` | Default model for guard / ai_generate | `nil` |
+| `trace_llm_calls` | Log guard calls to `rails_ai_traces` | `true` |
 
 ---
 
-## Generators
+## How it works
 
-| Generator | Purpose |
-|-----------|---------|
-| `rails g rails_ai_kit:install` | Enable pgvector + create `rails_ai_kit_labels` (for Classifier) |
-| `rails g rails_ai_kit:vector_columns ModelName content_column` | Add `embedding`, `label`, `confidence_score` to a table |
+### Guardrails
 
----
+1. You call `RailsAiKit.guard(prompt:, model:, checks:, threshold:)`.
+2. The gem generates a response with the configured LLM.
+3. It runs the requested checks (toxicity, PII, hallucination, prompt injection) on the **output** and, for toxicity/prompt_injection, on the **user prompt** (in parallel where possible). Keyword rules backstop obvious offensive prompts.
+4. It merges scores and sets `action` to `:block` if any score exceeds `threshold`.
+5. Optionally it records the run in `rails_ai_traces`.
 
-## How Classifier works
+### Vector classification
 
-1. **Label vectors** – Each label is a vector (average of example embeddings), stored in `rails_ai_kit_labels`.
-2. **Classification** – New content is embedded and compared to label vectors (cosine distance). Nearest label wins; confidence = `1 - distance`.
-3. **Storage** – Your table holds content, embedding, predicted label, and confidence. The gem adds one table for label vectors only.
+1. You train labels with example texts; the gem embeds them and stores one vector per label in `rails_ai_kit_labels`.
+2. When you save a record with `vector_classify`, the gem embeds the source column, stores the vector, and finds the nearest label (cosine distance). It sets `label` and `confidence_score`.
+3. Similarity search uses the same embedding column and pgvector nearest-neighbor.
 
 ---
 
 ## Roadmap
 
-- **Classifier:** hierarchical labels, confidence threshold, hybrid search, incremental learning
-- **More features** – additional AI capabilities as the gem evolves
+- **Guardrails:** More guards, configurable keyword lists, retry/fallback behavior.
+- **Vector classification:** Hierarchical labels, confidence threshold, hybrid search, incremental learning.
+- **More features:** Additional AI capabilities as the gem evolves.
 
 ---
 
@@ -262,8 +288,6 @@ bundle install
 bundle exec rake install
 ```
 
-Run tests (when added) with `bundle exec rspec` or `bundle exec rake test`.
-
 ---
 
 ## License
@@ -272,18 +296,15 @@ MIT.
 
 ---
 
-## How it’s built
+## Related
 
-- **Configuration** – Embedding provider, dimensions, API keys.
-- **Embedding providers** – Base + OpenAI and Cohere (`embed`, `embed_batch`).
-- **EmbeddingService** – `RailsAiKit.embedding` / `RailsAiKit.embed(text)`.
-- **Classifier** – Label training, `classify`, `classify_by_embedding`, `batch_classify`; uses `rails_ai_kit_labels` + Neighbor for similarity.
-- **VectorClassify** – ActiveRecord concern: `vector_classify` macro, `similar_to` scope.
-- **Generators** – Install (labels table), vector_columns (embedding/label/confidence on a model).
+- [pgvector](https://github.com/pgvector/pgvector) – Vector similarity search for Postgres
+- [Neighbor](https://github.com/ankane/neighbor) – Nearest neighbor search for Rails (used for vector classification)
 
 ---
 
-## Related
+## Creator
 
-- [pgvector](https://github.com/pgvector/pgvector) – Vector similarity search for Postgres
-- [Neighbor](https://github.com/ankane/neighbor) – Nearest neighbor search for Rails (used by this gem)
+**Rohit Kushwaha** — *AI Engineer*
+
+[![LinkedIn](https://img.shields.io/badge/LinkedIn-Rohit%20Kushwaha-0A66C2?style=flat&logo=linkedin)](https://www.linkedin.com/in/rohit-kushwaha-6915b7197/)

data/lib/generators/rails_ai_kit/dashboard/templates/index.html.erb

@@ -0,0 +1,38 @@
+<div class="rails_ai_kit traces">
+  <h1>AI Traces</h1>
+
+  <% if defined?(@stats) && @stats %>
+    <div class="stats">
+      <span>Total: <%= @stats[:total] %></span>
+      <span>Blocked: <%= @stats[:blocked] %></span>
+      <span>Models: <%= @stats[:models]&.join(", ") %></span>
+    </div>
+  <% end %>
+
+  <table>
+    <thead>
+      <tr>
+        <th>Time</th>
+        <th>Model</th>
+        <th>Prompt</th>
+        <th>Response</th>
+        <th>Guard scores</th>
+        <th>Latency (ms)</th>
+        <th>Action</th>
+      </tr>
+    </thead>
+    <tbody>
+      <% @traces.each do |trace| %>
+        <tr class="<%= trace.action %>">
+          <td><%= trace.created_at&.strftime("%Y-%m-%d %H:%M") %></td>
+          <td><%= trace.model %></td>
+          <td><%= truncate(trace.prompt, length: 80) %></td>
+          <td><%= truncate(trace.response, length: 80) %></td>
+          <td><%= trace.guard_scores.is_a?(Hash) ? trace.guard_scores.to_json : trace.guard_scores %></td>
+          <td><%= trace.latency_ms %></td>
+          <td><%= trace.action %></td>
+        </tr>
+      <% end %>
+    </tbody>
+  </table>
+</div>

data/lib/generators/rails_ai_kit/dashboard/templates/traces_controller.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module RailsAiKit
+  class TracesController < ActionController::Base
+    layout "application"
+    before_action :set_traces
+
+    def index
+      @traces = @traces.recent.limit(100)
+      @traces = @traces.by_model(params[:model]) if params[:model].present?
+      @traces = @traces.blocked if params[:blocked] == "1"
+      @stats = {
+        total: RailsAiKit::Trace.count,
+        blocked: RailsAiKit::Trace.blocked.count,
+        models: RailsAiKit::Trace.distinct.pluck(:model).compact
+      }
+    end
+
+    private
+
+    def set_traces
+      @traces = RailsAiKit::Trace.all
+    end
+  end
+end

data/lib/generators/rails_ai_kit/dashboard_generator.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module RailsAiKit
+  module Generators
+    class DashboardGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Adds AI Traces dashboard (controller + view + route) at /ai_traces"
+
+      def create_controller
+        copy_file "traces_controller.rb", "app/controllers/rails_ai_kit/traces_controller.rb"
+      end
+
+      def create_view
+        copy_file "index.html.erb", "app/views/rails_ai_kit/traces/index.html.erb"
+      end
+
+      def add_route
+        route 'get "/ai_traces", to: "rails_ai_kit/traces#index", as: :ai_traces'
+      end
+    end
+  end
+end

data/lib/generators/rails_ai_kit/install/templates/create_rails_ai_kit_tables.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+class CreateRailsAiKitTables < ActiveRecord::Migration[<%= Rails::VERSION::MAJOR %>.<%= Rails::VERSION::MINOR %>]
+  def change
+    enable_extension "vector" unless extension_enabled?("vector")
+
+    create_table :rails_ai_kit_labels do |t|
+      t.string :classifier_name, null: false
+      t.string :label_name, null: false
+      t.vector :embedding, limit: <%= (defined?(RailsAiKit) && RailsAiKit.configuration.embedding_dimensions) || 1536 %>, null: false
+      t.timestamps
+    end
+    add_index :rails_ai_kit_labels, [:classifier_name, :label_name], unique: true
+
+    create_table :rails_ai_traces do |t|
+      t.text :prompt, null: false
+      t.text :response
+      t.string :model
+      t.integer :prompt_tokens
+      t.integer :completion_tokens
+      t.jsonb :guard_scores, default: {}
+      t.decimal :latency_ms, precision: 10, scale: 2
+      t.string :action, default: "allow"
+      t.timestamps
+    end
+    add_index :rails_ai_traces, :created_at
+    add_index :rails_ai_traces, :model
+    add_index :rails_ai_traces, :action
+  end
+end

data/lib/generators/rails_ai_kit/install/templates/create_rails_ai_traces.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+class CreateRailsAiTraces < ActiveRecord::Migration[<%= Rails::VERSION::MAJOR %>.<%= Rails::VERSION::MINOR %>]
+  def change
+    create_table :rails_ai_traces do |t|
+      t.text :prompt, null: false
+      t.text :response
+      t.string :model
+      t.integer :prompt_tokens
+      t.integer :completion_tokens
+      t.jsonb :guard_scores, default: {}
+      t.decimal :latency_ms, precision: 10, scale: 2
+      t.string :action, default: "allow"
+      t.timestamps
+    end
+
+    add_index :rails_ai_traces, :created_at
+    add_index :rails_ai_traces, :model
+    add_index :rails_ai_traces, :action
+  end
+end