Build a RAG App for Documentation Q&A using Rails

# Gemfile
gem "ruby_llm"

# Gemfile
gem "neighbor"

# config/initializers/ruby_llm.rb
require "ruby_llm"

RubyLLM.configure do |config|
  config.ollama_api_base = "http://localhost:11434/v1"
  config.default_model = "qwen2.5:7b-instruct"
  config.default_embedding_model = "nomic-embed-text"
  config.use_new_acts_as = true
end

# app/models/article_chunk.rb
class ArticleChunk < ApplicationRecord
  has_neighbors :embedding
end

# lib/tasks/ingest_blog.rake
namespace :blog do
  MAX_ARTICLES = 100

  desc "Fetch and store article chunks with embeddings (follows pagination, max #{MAX_ARTICLES} articles)"
  task ingest: :environment do
    require "ruby_llm"
    require "nokogiri"
    require "httparty"

    # NOTE: change this to your own blog URL if you want
    base_url = "https://prabinpoudel.com.np"

    # Collect article URLs from index + paginated pages. Skip /articles/page/N/ itself.
    article_urls = []
    page_num = 1

    loop do
      index_url =
        (
          if page_num == 1
            "#{base_url}/articles/"
          else
            "#{base_url}/articles/page/#{page_num}/"
          end
        )
      puts "Scanning index: #{index_url}"
      page = HTTParty.get(index_url)
      break unless page.success?

      doc = Nokogiri.HTML(page.body)
      links =
        doc
          .css("a")
          .map { |a| a["href"] }
          .compact
          .map { |href| URI.join(base_url, href).to_s }
          .uniq

      # Only links to actual articles: exclude index and pagination pages
      new_articles =
        links.select do |url|
          next false if url == "#{base_url}/articles"
          next false if url == "#{base_url}/articles/"
          next false if url.match?(%r{/articles/page/\d+/?\z})
          url.include?("/articles/")
        end

      new_articles.each do |url|
        article_urls << url unless article_urls.include?(url)
      end

      break if article_urls.size >= MAX_ARTICLES

      # Next page: try page_num + 1; stop if this page had no new article links
      has_next =
        links.any? { |u| u.match?(%r{/articles/page/#{page_num + 1}/?}) }
      break unless has_next

      page_num += 1
    end

    article_urls = article_urls.first(MAX_ARTICLES)
    puts "Found #{article_urls.size} article(s) to ingest"

    article_urls.each do |full_url|
      puts "Fetching #{full_url}"

      page = HTTParty.get(full_url)
      next unless page.success?

      page_doc = Nokogiri.HTML(page.body)
      article_node = page_doc.css("article").first
      next unless article_node

      source_title =
        article_node.css("h1, h2").first&.text&.strip.presence || full_url

      # Store full article HTML for display (code blocks, headings, etc.)
      full_html = article_node.inner_html
      fragment = Nokogiri::HTML.fragment(full_html)
      fragment
        .css("a[href]")
        .each do |a|
          href = a["href"].to_s.strip
          a["href"] = URI.join(full_url, href).to_s if href.start_with?("/")
        end
      Article.find_or_initialize_by(source_url: full_url).update!(
        title: source_title,
        content: fragment.to_html
      )

      # Extract text but preserve hyperlinks as "link text (url)" so references are stored
      content = []
      article_node.traverse do |node|
        if node.is_a?(Nokogiri::XML::Text)
          # Skip text inside <a> so we don't duplicate link text
          content << node.text if node.parent.name != "a"
        elsif node.name == "a" && node["href"].present?
          link_text = node.text.strip.presence || node["href"]
          href = node["href"].strip
          href = URI.join(full_url, href).to_s if href.start_with?("/")
          content << " #{link_text} (#{href}) "
        end
      end

      content = content.compact.join.gsub(/\s+/, " ").strip

      chunks = content.scan(/.{1,800}(?:\n|\z)/m)

      chunks.each do |chunk|
        embedding =
          RubyLLM.embed(chunk, provider: :ollama, assume_model_exists: true)

        ArticleChunk.create!(
          content: chunk,
          embedding: embedding.vectors,
          source_url: full_url,
          source_title: source_title
        )
      end
    end
  end
end

# config/routes.rb
Rails.application.routes.draw do
  root "articles#index"
  # ...
end

# app/controllers/articles_controller.rb
class ArticlesController < ApplicationController
  def index
    @articles = Article.all
    @selected_url = params[:article].presence

    return unless @selected_url.present?

    article = Article.find_by(source_url: @selected_url)
    @selected_article_title = article&.title.presence || @selected_url
    @selected_article_content = article&.content
  end
end

# app/helpers/application_helper.rb
module ApplicationHelper
  # Sanitizes stored article HTML (from Article) for safe display. Keeps structure, code blocks, links.
  def sanitize_article_html(html)
    return "" if html.blank?

    sanitize(
      html,
      tags: %w[
        p
        div
        span
        br
        h1
        h2
        h3
        h4
        h5
        h6
        a
        strong
        em
        b
        i
        code
        pre
        ul
        ol
        li
        blockquote
        hr
        img
        table
        thead
        tbody
        tr
        th
        td
      ],
      attributes: {
        "a" => %w[href target rel class],
        "img" => %w[src alt width height class],
        "code" => [ "class" ],
        "pre" => [ "class" ],
        "div" => [ "class" ],
        "span" => [ "class" ]
      }
    )
  end
end

# config/routes.rb
Rails.application.routes.draw do
  # ....
  post "search", to: "search#create", as: :search
  # ....
end

# app/controllers/search_controller.rb
class SearchController < ApplicationController
  def create
    question = (params[:q] || params[:query]).to_s.strip
    
    if question.blank?
      @error_message = "Query is required"

      respond_to { |format| format.turbo_stream }
      return
    end

    chat = Chat.create!(chat_attrs)
    rag_chat = chat.with_tool(BlogSearch).with_instructions(system_prompt)
    rag_chat.ask(question)

    assistant = chat.messages.where(role: "assistant").last
    @answer_html =
      Redcarpet::Markdown.new(
        Redcarpet::Render::HTML.new(filter_html: true),
        fenced_code_blocks: true,
        autolink: true
      ).render(assistant&.content.to_s)

    respond_to { |format| format.turbo_stream }
  rescue StandardError => e
    Rails.logger.error(
      "[Search] #{e.message}\n#{e.backtrace.first(5).join("\n")}"
    )
    @error_message = "Search failed. Please try again."

    respond_to { |format| format.turbo_stream }
  end

  private

  def chat_attrs
    {
      model: "qwen2.5:7b-instruct",
      provider: :ollama,
      assume_model_exists: true
    }
  end
end

# app/controllers/search_controller.rb
def system_prompt
  <<~PROMPT
    You are an assistant that answers questions ONLY using the author's blog.

    You MUST:
    1. Call the BlogSearch tool before answering.
    2. Read ONLY the content between BLOG_CONTEXT_START and BLOG_CONTEXT_END.
    3. If the context equals "NO_RELEVANT_BLOG_CONTENT", respond with: "I couldn't find anything about this in the blog."
    4. Always return the response in Markdown format.

    You are FORBIDDEN from using external knowledge.
  PROMPT
end

# app/tools/blog_search.rb
class BlogSearch < RubyLLM::Tool
  description "Searches the author's blog posts for relevant content only."
  param :query, desc: "User question about the blog"

  def execute(query:)
    result = search(query)

    { context: build_context(result) }.to_json
  end

  def search(query)
    q = query.to_s.strip

    return empty_result if q.blank?

    pre_limit = 10

    # Vector (semantic) search
    embedding =
      RubyLLM.embed(q, provider: :ollama, assume_model_exists: true).vectors
    vector_chunks =
      ArticleChunk
        .nearest_neighbors(:embedding, embedding, distance: "cosine")
        .limit(pre_limit)
        .to_a

    return empty_result if vector_chunks.empty?

    context_parts = []

    vector_chunks.each do |chunk|
      context_parts << <<~TEXT.strip
        #{chunk.content}
      TEXT
    end

    {
      context: context_parts.join("\n\n---\n\n")
    }
  end

  private

  def empty_result
    { context: "NO_RELEVANT_BLOG_CONTENT", sources: [] }
  end

  def build_context(result)
    <<~TEXT
      BLOG_CONTEXT_START
      #{result[:context]}
      BLOG_CONTEXT_END
    TEXT
  end
end

# app/tools/blog_search.rb

class BlogSearch < RubyLLM::Tool
  include Rails.application.routes.url_helpers

  description "Searches the author's blog posts for relevant content only."
  param :query, desc: "User question about the blog"

  def execute(query:)
    result = search(query)

    { context: build_context(result), sources: result[:sources] }.to_json
  end

  def search(query)
    q = query.to_s.strip

    return empty_result if q.blank?

    pre_limit = 8

    # Vector (semantic) search
    embedding =
      RubyLLM.embed(q, provider: :ollama, assume_model_exists: true).vectors
    vector_chunks =
      ArticleChunk
        .nearest_neighbors(:embedding, embedding, distance: "cosine")
        .limit(pre_limit)
        .to_a

    return empty_result if vector_chunks.empty?

    context_parts = []
    sources = []

    vector_chunks.each do |chunk|
      app_url =
        chunk.source_url.present? ? article_app_url(chunk.source_url) : nil
      source_line =
        if app_url.present?
          "[Source: #{chunk.source_title} | URL: #{app_url}]"
        else
          "[Source: #{chunk.source_title}]"
        end
      context_parts << <<~TEXT.strip
        #{source_line}
        #{chunk.content}
      TEXT

      sources << { title: chunk.source_title, url: app_url } if app_url
    end

    {
      context: context_parts.join("\n\n---\n\n"),
      sources: sources.uniq { |s| s[:url] }
    }
  end

  private

  def article_app_url(external_url)
    return nil if external_url.blank?

    root_url(article: external_url, host: "http://localhost:3000")
  end

  def empty_result
    { context: "NO_RELEVANT_BLOG_CONTENT", sources: [] }
  end

  def build_context(result)
    <<~TEXT
      BLOG_CONTEXT_START
      #{result[:context]}
      BLOG_CONTEXT_END
    TEXT
  end
end

# app/controllers/search_controller.rb
class SearchController < ApplicationController
  def create
    # ....
    assistant = chat.messages.where(role: "assistant").last
    @sources = extract_sources(chat)
    # ....
  end

  private

  # ....
  def extract_sources(chat)
    tool_msg = chat.messages.where(role: "tool").last
    return [] unless tool_msg

    payload = JSON.parse(tool_msg.content)
    payload["sources"] || []
  rescue StandardError
    []
  end
end

# app/controllers/search_controller.rb
def system_prompt
  <<~PROMPT
    You are an assistant that answers questions ONLY using the author's blog.

    ....
    .... existing_code ....
    ....

    You are FORBIDDEN from using external knowledge

    Response format:
    - Start with one or two short sentences summarizing the answer, then use <br /> to break the line.
    - Then give the detailed explanation. Use <br /> to break the line between each paragraph.
    - For lists: use Markdown bullets (- ) or numbers (1. 2. 3. ), with <br /> to break the line before the list and between list items if they are long.
    - Put code or commands in backticks. Use <br /> to break the line before and after code blocks if needed.
    - End with a link when relevant: "For more details, see [Post title](url)." Use only URLs from the context ([Source: ... | URL: ...]); never link to external sites.
    - Use two <br /> (a blank line) between sections so the response is easy to read. Do not output "Summary:" or "Answer:" - just the content.
  PROMPT
end

# db/migrate/xxxx_add_fulltext_to_article_chunks.rb
class AddFulltextToArticleChunks < ActiveRecord::Migration[8.1]
  def up
    execute <<-SQL.squish
      ALTER TABLE article_chunks
        ADD COLUMN content_tsv tsvector
        GENERATED ALWAYS AS (
          to_tsvector('english', coalesce(content, '') || ' ' || coalesce(source_title, ''))
        ) STORED;
    SQL
    add_index :article_chunks, :content_tsv, using: :gin
  end

  def down
    remove_index :article_chunks, :content_tsv, if_exists: true
    remove_column :article_chunks, :content_tsv
  end
end

# app/models/article_chunk.rb
def self.keyword_search(query, limit: 100)
  q = query.to_s.strip
  return none if q.blank?
  safe = connection.quote(q)
  where("content_tsv @@ plainto_tsquery('english', ?)", q)
    .order(Arel.sql("ts_rank_cd(content_tsv, plainto_tsquery('english', #{safe})) DESC"))
    .limit(limit)
end

# app/tools/blog_search.rb
class BlogSearch < RubyLLM::Tool
  # .... Other code ....

  def search(query)
    q = query.to_s.strip
    return empty_result if q.blank?

    pre_limit = 8
    post_limit = 3

    # Vector (semantic) search
    embedding = RubyLLM.embed(q, provider: :ollama, assume_model_exists: true).vectors
    vector_chunks = ArticleChunk.nearest_neighbors(:embedding, embedding, distance: "cosine").limit(pre_limit).to_a

    # Keyword (full-text) search
    keyword_chunks = ArticleChunk.keyword_search(q, limit: pre_limit).to_a

    # Hybrid: merge with Reciprocal Rank Fusion, then cap
    chunks = rrf_merge(vector_chunks, keyword_chunks).first(pre_limit)
    
    return empty_result if chunks.empty?

    chunks = chunks.first(post_limit)

    context_parts = []
    sources = []

    chunks.each do |chunk|
      app_url = chunk.source_url.present? ? article_app_url(chunk.source_url) : nil
      source_line =
        if app_url.present?
          "[Source: #{chunk.source_title} | URL: #{app_url}]"
        else
          "[Source: #{chunk.source_title}]"
        end
      context_parts << <<~TEXT.strip
        #{source_line}
        #{chunk.content}
      TEXT

      sources << { title: chunk.source_title, url: app_url } if app_url
    end

    {
      context: context_parts.join("\n\n---\n\n"),
      sources: sources.uniq { |s| s[:url] }
    }
  end

  private

  def rrf_merge(vector_list, keyword_list, k: 60)
    scores = Hash.new(0)
    vector_list.each_with_index { |c, i| scores[c.id] += 1.0 / (k + i + 1) }
    keyword_list.each_with_index { |c, i| scores[c.id] += 1.0 / (k + i + 1) }

    all_by_id = (vector_list + keyword_list).index_by(&:id)
    all_by_id.values.sort_by { |c| -scores[c.id] }.uniq(&:id)
  end

  # .... Other code ....
end

# app/tools/reranker.rb
# Reranks a list of ArticleChunk objects by relevance to a query using RubyLLM (Ollama).
# Used internally by BlogSearch; not a tool callable by the assistant.
class Reranker
  INSTRUCTIONS = <<~TEXT.strip.freeze
    You are a relevance judge. Given a query and numbered passages,#{' '}
    output only the passage numbers in order of relevance to the query,#{' '}
    one number per line. No explanation, no other text.
  TEXT

  # @param query [String] user question
  # @param chunks [Array<ArticleChunk>] chunks to rerank
  # @param keep_top [Integer] number of top chunks to return
  # @return [Array<ArticleChunk>] top keep_top chunks in relevance order
  def call(query, chunks, keep_top)
    return chunks.first(keep_top) if chunks.size <= keep_top

    prompt = build_prompt(query, chunks, keep_top)

    response =
      RubyLLM
        .chat(provider: :ollama, assume_model_exists: true)
        .with_model("qwen2.5:7b-instruct")
        .with_temperature(0) # deterministic ranking
        .with_instructions(INSTRUCTIONS)
        .ask(prompt)

    indices = parse_response(response.content, chunks.size, keep_top)

    if indices.blank?
      Rails.logger.warn(
        "[Reranker] LLM returned no valid indices. Returning top #{keep_top} by default."
      )
      return chunks.first(keep_top)
    end

    indices
      .first(keep_top)
      .filter_map { |i| chunks[i] if i.between?(0, chunks.size - 1) }
  rescue StandardError => e
    Rails.logger.warn(
      "[Reranker] Re-rank failed: #{e.message}. Returning top #{keep_top} chunks."
    )
    chunks.first(keep_top)
  end

  private

  def build_prompt(query, chunks, keep_top)
    passages =
      chunks
        .each_with_index
        .map { |c, i| "#{i + 1}. #{c.content.truncate(600)}" }
        .join("\n\n")

    <<~TEXT.strip
      Query: #{query}

      Passages:
      #{passages}

      Return only the numbers 1-#{chunks.size} of the top #{keep_top} most relevant passages,
      one number per line, most relevant first. No other text.
    TEXT
  end

  def parse_response(content, max_index, limit)
    return [] if content.blank?

    lines = content.strip.lines.map(&:strip).reject(&:blank?).first(limit)

    indices = []
    lines.each do |line|
      n = line.to_i
      indices << n - 1 if n.between?(1, max_index) && !indices.include?(n - 1)
    end
    indices
  end
end

# app/tools/blog_search.rb
class BlogSearch < RubyLLM::Tool
  # .... Other code ....
  def search(query)
    # .... Other code ....
    return empty_result if chunks.empty?

    if chunks.size > post_limit
      chunks = Reranker.new.call(q, chunks, post_limit)
    else
      chunks = chunks.first(post_limit)
    end
    # .... Other code ....
  end
end