DEV Community: Wilbur Suero

AISpec: RSpec for AI Behavior, Not AI Outputs

Wilbur Suero — Sat, 25 Jul 2026 17:39:25 +0000

Standard RSpec assertions expect exact values: expect(user.name).to eq("Alice").

LLMs break that contract immediately. Run a prompt three times at temperature 0.2, and you get three different phrasing variations.

When teams add AI features to Rails apps, they usually fall into one of two patterns:

Writing brittle regex assertions that shatter whenever the model picks a synonym or shifts sentence structure.
Offloading evals to a third-party SaaS dashboard that runs weekly batch jobs—completely disconnected from local bundle exec rspec runs and CI pipelines.

Neither scale for production. Forget testing word-for-word string matches. You need to enforce what the AI pipeline is permitted, required, or blocked from doing.

I built AISpec to solve this for Ruby and Rails. It's an open-source gem that brings invariant behavioral contracts, statistical confidence bounds, and native RSpec assertions into your test suite.

Behavioral invariants vs. static text assertions

Traditional code lives in a deterministic space. LLMs operate probabilistically, but your product constraints are still binary.

An LLM feature needs to satisfy two types of bounds:

                    ┌─────────────────────────────────────┐
                    │     LLM Application Constraints     │
                    └──────────────────┬──────────────────┘
                                       │
            ┌──────────────────────────┴──────────────────────────┐
            ▼                                                     ▼
┌─────────────────────────┐                           ┌─────────────────────────┐
│  Deterministic Bounds   │                           │   Probabilistic Bounds  │
├─────────────────────────┤                           ├─────────────────────────┤
│ • Valid JSON Schema     │                           │ • Semantic Relevance    │
│ • Strict Latency Budget │                           │ • Empathetic Tone       │
│ • Max Cost ($/call)     │                           │ • Factual Grounding     │
│ • Tool Calling Sequence │                           │ • LLM-as-a-Judge Score  │
│ • System Prompt Privacy │                           └─────────────────────────┘
└─────────────────────────┘

Deterministic bounds are pass/fail. The response either matches your JSON schema or it doesn't. Execution finished under 2,500ms, or it blew past your budget. The app called fetch_account_status before process_refund, or it failed the sequence.

Probabilistic bounds grade response quality. An LLM judge evaluates whether the output stays factual against provided context or hits the expected tone threshold.

AISpec unifies both under a single contract file.

Defining behavioral contracts in AISpec

Contracts live in YAML files alongside your codebase. You declare the provider, model, input dataset, and invariant rules.

Here is a contract for a customer support bot (contracts/support.yml):

version: 1
name: support-bot

model:
  provider: openai
  model: gpt-4o

dataset:
  path: datasets/support_cases.yml

contracts:
  # Structural & Formatting Constraints
  - type: json
    schema: ["status", "ticket_id", "message"]

  - type: citation_format

  # Operational Constraints
  - type: max_latency
    value: 2500

  - type: cost
    max: 0.03

  # Safety & Tooling Constraints
  - type: must_not_reveal_system_prompt

  - type: tool_order
    order: ["fetch_account_status", "process_refund"]

  # Probabilistic Quality Criteria (LLM-as-a-Judge)
  - type: judge
    prompt: |
      The response must be polite, accurate to our refund policy, and concise.
    threshold: 0.85

You can also use inline shorthand rules:

contracts:
  - must_return_valid_json
  - latency < 2500ms
  - cost < $0.03
  - confidence >= 0.85

Run aispec run contracts/support.yml from your terminal to execute the dataset and check every rule:

$ aispec run contracts/support.yml

Running 12 contracts for support-bot (openai / gpt-4o)...

Case #1 (Input: "How do I request a refund?")
  PASS  json: Output is valid JSON matching target schema
  PASS  citation_format: Response contains valid citation formatting
  PASS  max_latency: Latency 142.0ms <= 2500ms
  PASS  cost: Cost $0.0018 <= $0.0300
  PASS  must_not_reveal_system_prompt: System prompt protected
  PASS  tool_order: Tool sequence [fetch_account_status, process_refund] matched
  PASS  judge: Score 0.94 (threshold 0.85): Response accurate and empathetic

Overall
  Passed: 12/12 (100.0%)
  Confidence Interval: 95.0% CI [75.8%, 100.0%]
  Mean Latency: 142.0ms
  Total Cost: $0.0036
  Variance: Low
  Recommendation: Stable

AISpec computes a Wilson score 95% confidence interval and tracks variance across runs. If small sample sizes or wild output swings threaten reliability, AISpec flags the instability before bad prompt edits land in production.

Benchmarking across models

Switching from gpt-4o to claude-3-5-sonnet or a local llama3 instance usually feels like guesswork. You swap model names, run a few manual prompts, and hope nothing broke.

AISpec lets you benchmark candidate models against your exact contract suite in one terminal command:

$ aispec compare gpt-4o claude-3-5-sonnet llama3

Model	Success Rate	95% Confidence CI	Cost / Run	Mean Latency	Variance
gpt-4o	98.2%	[92.1%, 99.7%]	$0.0024	1.1s	Low
claude-3-5-sonnet	97.5%	[91.0%, 99.3%]	$0.0042	1.4s	Low
llama3 (Ollama local)	91.0%	[82.4%, 95.6%]	$0.0000	0.8s	Moderate

This shifts model selection from subjective vibe checks to clear metrics. You instantly see whether a cheaper or open-weights model meets your latency and safety budgets.

Rails integration

AI evals shouldn't require a separate Python toolchain or external dashboard. In a Rails application, your behavioral contracts belong right inside spec/contracts/.

1. Initializer and custom assertions

Set default providers and register custom domain rules in config/initializers/aispec.rb:

# config/initializers/aispec.rb
AISpec.configure do |config|
  config.default_provider = ENV.fetch("AISPEC_PROVIDER", "openai")
  config.default_model    = "gpt-4o"
  config.judge_provider   = "openai"
  config.judge_model       = "gpt-4o"
  config.timeout           = 30
end

# Register domain-specific assertions using the AISpec plugin DSL
AISpec.plugin do
  assertion :valid_tenant_isolation do |response, context, _options|
    tenant_id = context[:tenant_id]
    contains_tenant = response[:output].include?("Tenant: #{tenant_id}")

    [
      contains_tenant,
      contains_tenant ? "Output correctly bound to Tenant #{tenant_id}" : "Security Violation: Missing Tenant #{tenant_id}"
    ]
  end
end

2. Running contracts in RSpec

Run your YAML contracts directly inside standard RSpec tests:

# spec/contracts/support_contract_spec.rb
require "rails_helper"

RSpec.describe "Support Bot Behavioral Contract", type: :contract do
  it "satisfies safety, format, and cost invariant budgets" do
    contract_path = Rails.root.join("spec/contracts/support.yml")
    runner        = AISpec::Core::Runner.new(contract_path)

    results = runner.run
    stats   = results[:statistics].summary

    # Enforce zero assertion failures
    expect(stats[:failed_assertions]).to eq(0), -> {
      failures = results[:runs].flat_map { |r| r[:assertion_results].reject(&:passed?).map(&:message) }
      "Contract Violations:\n#{failures.join("\n")}"
    }

    # Enforce statistical quality bounds
    expect(stats[:success_rate]).to be >= 95.0
    expect(stats[:mean_latency]).to be <= 2500.0
    expect(stats[:total_cost]).to be <= 0.05
  end
end

Continuous verification in GitHub Actions

Because AISpec outputs JSON, JUnit XML, and Markdown tables, you can run contract checks on every pull request using GitHub Actions:

# .github/workflows/ai_contracts.yml
name: AI Behavioral Verification

on: [push, pull_request]

jobs:
  verify-contracts:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: ruby/setup-ruby@v1
        with:
          ruby-version: '3.3'
          bundler-cache: true

      - name: Execute AISpec Contracts
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
        run: |
          bundle exec aispec run contracts/support.yml --format markdown --output pr_comment.md

      - name: Post Behavioral Report to Pull Request
        if: github.event_name == 'pull_request'
        uses: marooned/actions-comment-pull-request@v2
        with:
          filePath: pr_comment.md

When someone modifies a prompt in a pull request, CI comments with a table showing whether latency jumped, costs rose, or score bounds failed.

AI tooling makes writing code easy, but maintaining system reliability remains the real work.

Without explicit behavioral boundaries, every prompt change introduces risk. Defining invariant rules—schema checks, latency budgets, tool sequences, and statistical thresholds—turns unpredictable model outputs into reliable system components.

Check out AISpec on GitHub or run gem install aispec to add behavioral specs to your Rails application.

The Two Sources of Noise Every LLM Evaluation System Must Handle

Wilbur Suero — Wed, 22 Jul 2026 18:12:14 +0000

Traditional tests are binary. LLM evaluations are a forecast.

Every software engineer has experienced the satisfaction of a green test suite.

You change the code.

You run the tests.

Everything passes.

That simple feedback loop has shaped how we've built software for decades.

Then LLMs quietly broke one of software engineering's most trusted feedback loops.

You run the exact same evaluation twice...

...and get two different answers.

Nothing changed.

At least, nothing you can see.

The Fallacy of the Scoreboard

An evaluation score looks like a measurement.

It isn't.

It's an estimate.

This isn't entirely new. Performance benchmarks, A/B tests, and distributed systems have always required statistical thinking. LLM evaluation simply makes that reality impossible to ignore.

When we built our internal LLM evaluation framework, we expected to run our benchmarks, get a single score (say, 84%), tweak a prompt, and see that score change. If it dropped to 81%, we assumed a regression. If it rose to 87%, we assumed an improvement.

We spent weeks chasing ghosts, tweaking prompts to fix a drop in score, only to realize the next run would swing back.

The mistake isn't that LLM evaluations are noisy.

The mistake is expecting them not to be.

Once you stop thinking of evaluation as testing—and start thinking of it as measurement—the architecture almost designs itself.

To build an AI evaluation pipeline that actually guides production decisions, you must realize:

Not all evaluation noise is the same.

Some fluctuations come from the conversations we are evaluating. Others come from the evaluator itself.

Every score fluctuation is a question before it's an answer:

Did the model change?
Did the benchmark change?
Or did the measurement change?

Treating all three as "the score changed" is how evaluation systems lose credibility.

Problem #1: Sometimes There Isn't a Right Answer

Imagine a user who replies to your LLM assistant with a single word:

"Stop"

What should the assistant do?

An SMS opt-out request: "You have been unsubscribed."
A conversation pause: "Let's stop here for today. Let me know when you want to continue."
Frustration: "I'm sorry, let's try another approach."
A change of topic: "Okay, let's stop talking about this and try something else."

Without additional context, all of these interpretations are reasonable. Even human reviewers will disagree on the best response. The ambiguity exists in the conversation itself. No prompt engineering or model tuning can eliminate it.

Statisticians call this aleatoric uncertainty.

The terminology isn't important. The engineering implication is.

If the uncertainty lives in the conversation, improving the judge won't fix it. You're optimizing the wrong part of the system. You cannot debug or code your way out of it because the input itself lacks the information required to produce a single deterministic answer.

How to Mitigate Task Ambiguity

In practice, reducing task ambiguity usually comes down to four things:

Richer conversational context: Ensure your fixtures contain multi-turn history. Context resolves ambiguity.
Production-derived fixtures: Build your benchmark using anonymized, cleaned production logs that represent real-world usage rather than synthetic test cases.
Explicit ambiguity labels: Tag fixtures that have multiple valid responses so they aren't judged on a binary scale.
Measuring fixture quality: Track fixture fidelity and coverage instead of focusing solely on the model's score.

Problem #2: Sometimes the Judge Is Wrong

Now imagine a different scenario.

You have a clean, unambiguous fixture. The candidate model produces a response that is clearly correct. You pass it to your LLM judge. The judge gives it a score of 4 out of 5.

You run the exact same evaluation five minutes later. The judge gives it a score of 5 out of 5.

Nothing in the candidate response changed, yet the score did.

Statisticians call this epistemic uncertainty.

Here the opposite is true. The task is stable. The measurement isn't. That means your evaluation infrastructure—not your benchmark—is what needs improvement.

Epistemic noise creeps in through:

Stochastic API Behavior: Even at temperature 0, repeated calls to hosted LLM APIs can produce different outputs in practice because providers may use implementation details that are opaque to users.
Rubric Ambiguity: If your prompt asks the judge, "Is this response helpful?", the judge is forced to invent its own definition of "helpful" on every run.
Model Biases: LLMs exhibit self-preference (favoring their own text), position bias (preferring the first option), and length bias (favoring longer responses).

How to Mitigate Judge Uncertainty

In practice, hardening your evaluation framework against judge uncertainty comes down to:

Judge ensembling: If evaluation results influence production decisions, judge ensembling can substantially improve robustness. Run evaluations across multiple models (e.g., Claude, GPT-4, Gemini) to smooth out model-specific blind spots.
Measuring inter-judge agreement: Track agreement rates (like Cohen’s Kappa) to identify when judges diverge.
Tracking judge variance: Periodically run the exact same input through your judges multiple times to calculate your evaluation system's baseline standard deviation. If your benchmark reports a model score of 84%, the most useful number may not be 84. It may be 84% ± 3%.
Multi-axis scoring: Score along distinct, objective axes (e.g., correctness, safety, conciseness) using binary or highly structured scales instead of subjective 1-to-5 ranges.
Flagging judge-sensitive fixtures: Automatically flag fixtures that show unusually high score variance across runs for manual auditing.

Why This Matters

This distinction shapes the architecture of your evaluation system. If you don't know which type of noise you are dealing with, you will make the wrong engineering trade-offs. Spending weeks tweaking a prompt to evaluate an inherently ambiguous fixture is a waste of time.

Once we started thinking about uncertainty this way, several architectural decisions became obvious:

Fixture Audits reduced task ambiguity by improving realism, coverage, and multi-turn representation.
Multi-Axis Scoring made disagreements explainable by separating quality dimensions rather than collapsing everything into a single score.
Judge Ensembling reduced judge uncertainty by comparing independent evaluators.
Confidence Reporting allowed us to distinguish genuine regressions from expected evaluation variance.
Coverage Metrics communicated the statistical confidence of the evaluation itself.

Moving Beyond the Scoreboard

Traditional testing is about proving correctness.

LLM evaluation is about estimating confidence.

That distinction changes everything. It changes how we write fixtures, design judges, and interpret regressions. Most importantly, it changes what a successful evaluation system looks like.

Reliable evaluation isn't about removing uncertainty.

It's about understanding it well enough to make better engineering decisions.

As LLM systems become more capable, our evaluation systems will need to become more sophisticated as well. The challenge is no longer simply measuring quality—it's measuring how confident we should be in the measurement itself. Once you embrace that shift, evaluation stops being a scoreboard and starts becoming a decision-making tool.

More Threads, Less Throughput: When AI Servers Fight the Scheduler

Wilbur Suero — Sat, 04 Jul 2026 15:45:46 +0000

Our inference server had 24 CPU cores, a mostly idle GPU, and only 10 concurrent requests.

Somehow, average latency exceeded eight seconds.

That shouldn't have been possible.

We were running a Rails background worker system that dispatched embedding and classification requests to an internal Python inference service. As our background queue grew, we did what any sensible team would do: we increased the concurrency of our background workers and scaled up the inference web server.

Instead of seeing our throughput scale linearly, the system ground to a halt. Latency spiked from milliseconds to over eight seconds, background queues backed up, and our server's CPU utilization pegged at 100%. Yet, looking at the GPU telemetry, it was practically idling, waiting for work.

The CPUs weren't spending their time multiplying matrices. They were spending it deciding which thread should run next. As we dug deeper, we realized we were victims of a hidden performance killer: thread oversubscription.

The Benchmark That Didn't Make Sense

To diagnose the bottleneck, we isolated the inference service and ran a controlled load test. We simulated a modest concurrency of 10 concurrent requests, sending a total of 100 API requests to the Python inference server.

While an individual, isolated inference request took around 912 milliseconds, putting a concurrent load of just 10 requests pushed the average response time out to over 8 seconds. Even worse, the CPU cores were completely saturated, but the GPU was only at 15% utilization.

In a healthy system, if the CPU is at 100%, throughput should be maximized. But here, the CPU was working incredibly hard to produce almost no output.

Here is what the initial baseline benchmark looked like:

Metric	Baseline
Throughput	7.28 req/s
Average Latency	8.43 s
Inference Time	912 ms
Active Threads	~240
CPU Utilization	98%

Our Initial Hypotheses

We thought it was:

GPU Saturation: The model was too heavy for our hardware.
Insufficient Workers: We needed to increase Rails concurrency to queue more work.
Slow Model: The embedding algorithm itself was inherently slow.
Network Overhead: The data transfer between Rails and the inference API was lagging.

It turned out to be none of them.

Following the CPU: The 240-Thread Discovery

We jumped onto the inference server during the load test and ran htop to see what the CPU was actually doing. What we saw was a wall of red and green bars representing 24 individual CPU cores (48 logical threads) pegged to their absolute limits.

Then we checked the active thread count for the Python inference process:

# Count the number of lightweight processes (threads) for our service pid
ps -o nlwp -p <PID>

The output was 240.

A single process handling 10 concurrent web requests had spawned 240 active threads. Where did they come from?

Our Python code was simple. It was a standard FastAPI application using Uvicorn. We weren't manually spawning threads. We were just loading a sentence-transformer model using PyTorch and running inference:

# The seemingly innocent endpoint
@app.post("/embed")
def embed(payload: TextPayload):
    # Under the hood, this call is not single-threaded
    embeddings = model.encode(payload.texts)
    return {"embeddings": embeddings.tolist()}

The culprit wasn't our application. It was the stack of native libraries underneath it.

Why Native Libraries Lie to You

To understand why 240 threads were running, we have to look at the architectural layers beneath PyTorch.

When you call model.encode() in Python, your request travels down a vertical stack of abstractions before hitting the CPU:

                Request
                   │
         FastAPI / Uvicorn
                   │
              PyTorch
                   │
      OpenMP / MKL / BLAS
                   │
            OS Scheduler
                   │
              CPU Cores

At the top, we have FastAPI/Uvicorn, which handles concurrent web connections. Beneath it is PyTorch, which coordinates the neural network graph execution. But PyTorch itself doesn't actually perform the core matrix arithmetic (like matrix multiplication). For that, it delegates to low-level, highly optimized native C and C++ math libraries:

BLAS (Basic Linear Algebra Subprograms): The standardized API specification for low-level vector and matrix operations.
OpenBLAS / MKL (Intel Math Kernel Library): Concrete, highly optimized implementations of the BLAS API. They use hand-crafted assembly code, CPU vector extensions (like AVX-512), and internal threading to run matrix math at the absolute limits of the physical silicon.
OpenMP (Open Multi-Processing): The concurrency engine used by these math libraries to split loops and parallelize matrix calculations across multiple threads.

These native libraries were designed for High-Performance Computing (HPC) environments, where a single program runs on a dedicated machine and expects to utilize every core for a single calculation. MKL and OpenMP query the host core count and spawn a worker thread pool matching it. They assume they own the hardware.

While this behavior is perfect for a Jupyter notebook running on a developer's workstation, it is hostile in a web server or background job runner. Web servers scale by handling independent requests concurrently using separate processes or threads.

If Uvicorn or Rails runs 10 workers on our 24-core server, each worker process makes its own PyTorch calls. PyTorch delegates to OpenMP, which independently spawns 24 threads per request. None of the workers are aware of each other.

Repeat this for all 10 concurrent requests, and the math compounding is brutal:

10 Concurrent Requests 
  × 24 Threads per Request 
  = 240 Active Threads competing for 24 Physical Cores

To visualize the scale of this duplication:

The native libraries lied to us by assuming they were alone. By defaulting to the total core count, they optimized for single-task speed at the expense of multi-task system throughput. Instead of cooperating, the threads began to fight.

The Cost of Concurrency: Scheduler Contention

When you have 240 active threads screaming for time on 24 physical CPU cores, the operating system is forced to step in. The OS scheduler must slice up CPU time and constantly swap threads in and out of the CPU registers.

This is known as thread oversubscription, and it introduces a massive overhead called scheduler contention.

Every context switch is work the application didn't ask for. The scheduler saves registers, restores another thread's state, and the CPU begins executing a completely different workload. Caches become less effective, memory must be fetched again, and the processor spends less time multiplying matrices and more time preparing to multiply matrices.

When the cache is constantly invalidated, the CPU cores spend most of their time waiting for data to be fetched from main memory (RAM) instead of performing floating-point math. The CPU is "busy," but it is busy managing its own metadata rather than executing your code.

In our case, the scheduler contention was so severe that the overhead of coordinating the 240 threads completely wiped out the benefits of parallelizing the matrix math. Ten requests, each trying to run on 24 threads, took 912ms. If they had run sequentially on a single thread each, they would have finished in a fraction of the time.

The Fix: Global Concurrency Coordination

The solution was counterintuitive but incredibly simple: we had to force the native libraries to stop parallelizing internal operations. We wanted each request to run on exactly one thread, allowing the web server's concurrency model (10 worker processes) to match the physical hardware limits.

We added the following configuration to the very top of our application entry point, before any deep learning library was imported:

import os

# Limit OpenMP threads
os.environ["OMP_NUM_THREADS"] = "1"
os.environ["MKL_NUM_THREADS"] = "1"
os.environ["OPENBLAS_NUM_THREADS"] = "1"
os.environ["VECLIB_MAXIMUM_THREADS"] = "1"
os.environ["NUMEXPR_NUM_THREADS"] = "1"

# Force PyTorch to use a single thread for intra-op and inter-op parallelism
import torch
torch.set_num_threads(1)
torch.set_num_interop_threads(1)

By setting these variables to 1, we instructed PyTorch and its underlying math libraries to execute operations sequentially on a single thread per request.

We then restarted our server and ran the exact same load test of 10 concurrent requests.

The results were night and day:

Metric	Baseline (Default Threads)	Optimized (1 Thread)	Improvement
Throughput	7.28 req/s	11.45 req/s	+57%
Average Latency	8.43 s	5.24 s	-38%
Inference Time	912 ms	560 ms	-38%
Active Threads	~240	~10	95% Reduction
CPU Utilization	98%	45%	Slashed in Half

By reducing the thread count from 240 to 10, throughput increased by 57%, average latency dropped by nearly 4 seconds, and CPU utilization was cut in half.

The CPU was no longer thrashing. It spent its cycles executing matrix multiplication instead of shuffling threads in and out of registers.

When Multi-Threaded Math Libraries Are Actually Good

This doesn't mean OMP_NUM_THREADS=1 is always correct. It is a design decision based entirely on your application's concurrency model.

If you are running an offline batch job, training a model, or running a single-threaded daemon processing one task at a time, you want PyTorch to use all available cores. In this scenario (data-level concurrency), letting MKL parallelize the matrix calculations makes your process run as fast as possible.

However, if you are running a web server or background workers processing many independent requests in parallel (request-level concurrency), each process should use exactly 1 thread. The operating system is already parallelizing the work across the cores at the process level. Adding internal library threads only causes them to fight for the scheduler's attention.

If you run both workloads on the same server, you must configure them separately. For example, keep OMP_NUM_THREADS=1 on your web servers, but allow it to scale to the core count on your batch processing workers.

The Broader Engineering Lesson

Every layer of the stack was trying to optimize itself independently. None of them were wrong. Together, they were inefficient.

Modern web frameworks and background workers are designed to scale by running multiple isolated processes or threads. Native math libraries are also designed to scale by running multiple threads. If you don't coordinate these two layers, they will fight each other for the scheduler's attention.

Systems don't become fast because every component is individually optimized. They become fast when every component cooperates.

Before you scale your servers horizontally or buy larger GPUs, inspect your process thread count. The best performance optimizations don't always come from writing faster code—sometimes they come from simply stopping your libraries from fighting each other.

No magic. Just systems.

Stop Sending Embeddings as JSON: A Faster Binary Serialization Pattern for AI APIs

Wilbur Suero — Sat, 04 Jul 2026 13:51:37 +0000

Every embedding API I've worked with sends vectors as JSON.

That's convenient.

It's also one of the most expensive ways to move numerical data between services. JSON isn't expensive simply because it's text. It's expensive because every floating-point value must be converted from binary to decimal, transmitted as characters, and parsed back into binary on the receiving side. You pay that cost on every dimension of every vector, in both directions.

By replacing JSON arrays with Base64-encoded binary float buffers, we reduced payload size by 75% and cut serialization latency by over 98%.

Here's the benchmark, measured against 1,000 embeddings at 1,536 dimensions each:

Metric	JSON Float Array	Base64 Float Buffer	Improvement
Payload Size	120.3 MB	30.1 MB	-75.0%
Python Serialization Time	3,140 ms	45 ms	-98.5%
Ruby Deserialization Time	4,820 ms	110 ms	-97.7%
Total Roundtrip Latency	9.42 s	1.84 s	-80.4%

Benchmark environment: Ruby 3.3.4, Python 3.12, NumPy 1.26, FastAPI 0.111, Apple M3 Pro (development) and x86_64 Linux (production). Each format was measured over 1,000 iterations with GC disabled during measurement using Ruby's Benchmark::IPS and Python's timeit. Payload sizes were measured as raw HTTP body bytes before compression.

Reproduce it yourself: The Python serialization and Ruby deserialization benchmark scripts are available as a Gist. Clone, run, and compare on your own hardware.

Keep reading for the explanation, the implementation, and the cases where JSON is still the right answer.

Why Numerical Data Doesn't Belong in JSON

Computers do not store floating-point numbers as text. In memory, a single-precision float (float32 in Python, float in C) is stored as a 4-byte (32-bit) binary value.

When you serialize a float to JSON, you pay a conversion cost in both directions:

JSON pipeline (what everyone does):

float32 in memory (4 bytes)
    ↓  binary-to-decimal conversion
"-0.23142091" as ASCII string (11+ bytes)
    ↓  HTTP (24 KB per 1,536-dim vector)
JSON parser reads characters
    ↓  string-to-float conversion (strtof)
float in Ruby memory

Binary pipeline (what we switched to):

float32 in memory (4 bytes)
    ↓  tobytes() — zero conversion, O(1)
raw bytes
    ↓  Base64 encode (fast C implementation)
ASCII string (8 KB per 1,536-dim vector)
    ↓  HTTP
Base64 decode → unpack("e*") in Ruby
    ↓  single C pass over raw bytes
float in Ruby memory

The math is straightforward: in binary, a float32 occupies exactly 4 bytes. In JSON, the same number -0.23142091 occupies 11 bytes as text plus separators—a 3x–4x size multiplier.

For a single 1,536-dimension embedding, a binary payload is 6,144 bytes (~6 KB). The equivalent JSON array exceeds 24 KB. Multiply across a batch of 50 documents and you're transmitting over a megabyte of ASCII where 300 KB of binary would have been sufficient.

The network payload is only part of the problem. The CPU cost is often worse. To produce the JSON, Python must format each float as a string and concatenate them; Ruby must then locate delimiters, allocate memory for each token, and run string-to-float conversion for every dimension. That loop scales linearly with batch size and embedding dimensions, and at high throughput it dominates request latency.

For services generating a few embeddings per minute, JSON is perfectly adequate. The break-even point depends on batch sizes and hardware; profile before optimizing.

The Naive Solution (and Why it Fails at Scale)

Here is how our original system looked.

On the Python inference side (FastAPI), we returned embeddings using standard NumPy-to-list conversion:

# FastAPI endpoint (Slow & Heavy)
@app.post("/v1/embeddings")
def create_embeddings(payload: RequestPayload):
    embeddings = model.encode(payload.texts) # numpy array of float32
    return {
        # This implicitly converts the numpy array to a list of Python floats,
        # which FastAPI's JSON encoder serializes to a string.
        "embeddings": embeddings.tolist()
    }

On the Rails side, we used standard HTTP clients and JSON parsing:

# Rails Client (Slow & Heavy)
class InferenceClient
  def fetch_embeddings(texts)
    response = HTTParty.post(
      "http://inference-server/v1/embeddings",
      body: { texts: texts }.to_json,
      headers: { "Content-Type" => "application/json" }
    )

    # JSON parsing allocates thousands of strings and converts them back to floats
    JSON.parse(response.body)["embeddings"]
  end
end

During profiling, we discovered that Rails spent up to 40% of its execution time inside JSON.parse when processing large batches of embeddings. We were spending more CPU power parsing strings than executing business logic.

The Better Approach: Binary Float Buffers via Base64

Rather than trying to parse JSON faster, we eliminated JSON serialization of the embedding vector itself.

We serialize the float array as a raw binary buffer, then encode that buffer into a single Base64 string. Base64 introduces about 33% size overhead compared to raw binary, but it lets us embed binary data safely inside standard JSON payloads—no changes to content-type negotiation, no custom binary HTTP framing, no breaking changes to existing API consumers.

1. Python Inference Server (Encoding)

Instead of calling .tolist(), we extract the raw bytes from the underlying C-contiguous memory block:

import base64
import numpy as np

def serialize_embeddings(embeddings: np.ndarray) -> str:
    # Ensure the array is single-precision float32
    float_array = embeddings.astype(np.float32)

    # Get raw C-compatible memory bytes
    raw_bytes = float_array.tobytes()

    # Base64 encode the bytes and decode to an ASCII string
    return base64.b64encode(raw_bytes).decode("ascii")

Our API response now returns a single string instead of an array of numbers:

{
  "embedding": "MzMzMzPz8/M+MzMzMzPz8z8zMzMz..."
}

2. Rails Application Server (Decoding)

On the Ruby side, we decode the Base64 string back into raw bytes, then unpack them into Ruby Floats using String#unpack:

require "base64"

class EmbeddingDecoder
  # Decodes a Base64-encoded float32 binary buffer into a Ruby array of floats
  def self.decode(base64_string)
    # 1. Decode Base64 string back to binary string (raw bytes)
    binary_data = Base64.strict_decode64(base64_string)

    # 2. Unpack the binary buffer.
    # 'e' = little-endian single-precision (32-bit) float
    # '*' = unpack all remaining data in the string
    binary_data.unpack("e*")
  end
end

The key is unpack("e*"). Unlike iterating over a Ruby array, unpack runs entirely in optimized C inside the Ruby VM. It reads raw bytes directly from memory, offsets the pointer by 4 bytes at a time, and constructs the corresponding Ruby Float objects in a single pass—no string parsing, no delimiter scanning.

Under the Hood: Endianness and the `unpack` Directive

When moving binary data across languages and hardware, two things matter: precision and endianness.

1. Precision (Float32 vs. Float64)

NumPy defaults to float64 (8 bytes per float) for many operations, but AI embeddings are almost universally float32 (4 bytes per float). We explicitly call .astype(np.float32) before serializing. If you serialize as float64 and unpack as float32, the decoded numbers are meaningless.

2. Endianness (Byte Ordering)

Endianness determines the order bytes are written to memory:

Little-Endian: Least significant byte first. Used by x86_64 and ARM (Apple Silicon, modern Linux ARM).
Big-Endian: Most significant byte first. Used by network protocols and older RISC architectures.

Ruby's String#unpack directives are explicit about this:

f* — native CPU endianness (fragile across architectures)
g* — big-endian single-precision floats
e* — little-endian single-precision floats

We use e* because both our Python inference servers (x86 Linux) and Rails app servers (x86 Linux and ARM macOS) are little-endian. More importantly, being explicit about endianness means the decoding is correct by definition, regardless of what machine runs the code in the future.

The Tradeoffs

This optimization is not universal. Here's an honest accounting of the alternatives we evaluated before landing here.

Why not gRPC or Protocol Buffers?

Protocol Buffers with gRPC is the canonical answer to this problem in infrastructure-heavy organizations. It solves serialization, adds schema evolution, streaming, and bidirectional communication. We evaluated it. The operational cost—generated stubs for every language, strict schema registration, gRPC infrastructure—was high for an internal service consumed in one place. Base64 binary over HTTP let us ship in an afternoon with no new infrastructure. For systems with multiple consumers or where schema evolution matters, protobuf is the better long-term answer.

Why not MessagePack?

MessagePack is an excellent binary serialization format and would have worked here. In our case, the embedding vector is the only binary payload in the response—everything else is standard JSON. Introducing a full MessagePack codec for a single field felt like over-engineering. If you're serializing entire response objects in binary, MessagePack or protobuf is more appropriate.

Why not Apache Arrow?

Arrow's columnar in-memory format is optimized for batch numerical data and enables zero-copy access in many scenarios. For a dedicated ML pipeline where Ruby is doing heavy vector operations, Arrow (via the red-arrow gem) is worth evaluating. In our case, embeddings pass directly into pgvector; the overhead of Arrow's columnar framing wasn't justified.

Why not raw binary HTTP?

A pure binary HTTP response (Content-Type: application/octet-stream) would eliminate the ~33% Base64 overhead. We opted against it because it requires custom content-type handling on both sides, breaks standard HTTP debugging tooling, and complicates response envelope composition—status codes, metadata, and errors all live in the same JSON body. Base64-in-JSON is a pragmatic middle ground: it keeps the API contract intact while avoiding the text serialization cost for the high-volume field.

The real costs

Loss of human readability. You can no longer inspect embedding values in curl or Chrome DevTools. Debugging requires decoding the Base64 string out-of-band.
Tight schema coupling. Changing precision from float32 to float16 or float64 on the Python side requires a simultaneous update to the Ruby unpack directive. There is no self-describing schema to catch mismatches.
Array allocation overhead. unpack is fast, but Ruby still allocates 1,536 Float objects per vector. If you're passing embeddings directly into pgvector, benchmark whether you need to materialize the Ruby array at all—some clients accept binary blobs directly.

Conclusion: Text is for Humans, Binary is for Systems

JSON has won because it's readable. For most web APIs, that readability is worth the overhead—payloads are small and parsing costs are negligible.

Embeddings are different. A single vector from a modern model contains more numerical data than most entire API responses. When you serialize dense numerical arrays as strings, you're not just adding overhead—you're mismatching the data structure to its representation.

Performance work often starts with algorithms, but the largest wins frequently come from changing representations instead. Once you stop treating dense numerical data like text, the CPU suddenly has much less work to do.

That principle extends well beyond embeddings. Whenever you find yourself serializing audio buffers, image histograms, or numerical feature vectors as JSON, stop and ask whether the text representation is serving the system or just the developer who wrote the first version.

Set-Based Updates in Rails: 4 Hours to 8 Seconds

Wilbur Suero — Tue, 12 May 2026 14:18:50 +0000

I once inherited a background job to deactivate stale users. In production, a job processing 50,000 users that should have taken a minute was taking over 4 hours, consuming 2GB of RAM, and frequently timing out.

The culprit was a classic Rails performance pitfall: the N+1 update loop. The code looked innocent:

# Find users whose last login was more than 90 days ago
users_to_deactivate = User.where("last_login_at < ?", 90.days.ago)

users_to_deactivate.each do |user|
  # This runs one UPDATE query for every single user
  user.update(active: false)
end

This generates a flood of queries, hammering the database with thousands of individual transactions:

-- The N+1 Update Hell
SELECT "users".* FROM "users" WHERE (last_login_at < '2025-11-30...');
UPDATE "users" SET "active" = false, "updated_at" = '...' WHERE "users"."id" = 1;
UPDATE "users" SET "active" = false, "updated_at" = '...' WHERE "users"."id" = 2;
-- ... 49,998 more UPDATE statements

This approach is not just inefficient; it's hostile to your database. There is a much better way.

A Note on Indexes
All performance advice in this post assumes your query conditions are indexed. The User.where("last_login_at < ?", ...) query is only fast if you have a database index on the last_login_at column. Without it, the SELECT itself will be slow.

You can check this with User.where("last_login_at < ?", 90.days.ago).explain. If you see a Seq Scan (Sequential Scan), you need an index:
# db/migrate/YYYYMMDDHHMMSS_add_index_to_users_last_login_at.rb
add_index :users, :last_login_at

The Power of `update_all`

Instead of pulling 50,000 records into memory, we can tell the database to update the entire set in a single command. Active Record's update_all constructs one SQL UPDATE statement and sends it directly to the database.

Let's refactor the slow job:

count = User.where("last_login_at < ?", 90.days.ago)
            .update_all(active: false, updated_at: Time.current)

Rails.logger.info "Deactivated #{count} users."

This generates one beautiful, efficient SQL query and returns the number of rows affected. The result: 4 hours becomes 8 seconds.

The Sharp Edges of `update_all`

This performance comes with a critical trade-off: update_all bypasses most of the ActiveRecord lifecycle.

It ignores validations.
It skips callbacks. This will break any business logic in after_save or after_commit, like sending notifications or invalidating caches.

The `updated_at` Trap

The most insidious side effect is that update_all does not automatically update the updated_at timestamp. This will break any downstream system that relies on it for cache invalidation, audit trails, or synchronization.

Imagine a UI that caches a user's profile:

Rails.cache.fetch("user-#{user.id}-#{user.updated_at.to_i}") { ... }

If you use update_all(active: false), updated_at remains unchanged. The cache key stays the same, and your UI continues to show the user as active until the cache expires. The fix is to set it manually, as shown in the example above.

The Middle Ground: `update_columns`

update_columns is for when you already have an object in memory and need to perform a targeted update while bypassing callbacks and validations. It's a scalpel for a single record.

user = User.find_by(email: "some_user@example.com")
# ... some complex logic ...

# Now, update just one attribute without triggering callbacks.
user.update_columns(login_attempts: 0)

Unlike update_all, update_columns does touch updated_at by default (though this can be configured). It is not for bulk operations; using it in a loop brings you right back to the N+1 problem.

War Story #2: The Death-by-a-Thousand-Increments

I once debugged a Rails app where a popular blog post page was taking 20 seconds to load. The culprit? The controller was incrementing view counts like this for every recommended article on the page:

# ANTI-PATTERN: 50 posts on the page = 50 UPDATE queries
recommended_posts.each { |post| post.increment!(:view_count) }

increment! is just update under the hood. The fix was to switch to update_all with a SQL fragment, which dropped the response time to 200ms.

# GOOD: One query to increment all counters
Post.where(id: recommended_posts.map(&:id))
    .update_all("view_count = view_count + 1")

Going Deeper: Safe Heterogeneous Updates with SQL `CASE`

update_all is great for applying the same change to many records. But what if you need to update a set of records, each with a different value, like reordering items in a playlist?

⚠️ Security Warning: SQL Injection
Building raw SQL queries with string interpolation is extremely dangerous. The following example demonstrates a safe approach using sanitize_sql_array. Never inject raw user input directly into SQL strings.

# Use case: Reorder a list of tasks from user input
# updates = { "1" => 1, "2" => 2, "3" => 3 } where key is task_id and value is new position
def self.reorder_tasks(updates)
  # Build the CASE statement using sanitize_sql_array for each condition
  case_sql = updates.map do |id, position|
    # Ensure id and position are integers to prevent injection
    ActiveRecord::Base.sanitize_sql_array(["WHEN ? THEN ?", id.to_i, position.to_i])
  end.join(" ")

  # Construct the final, safe update statement
  update_sql = [
    "position = CASE id #{case_sql} END, updated_at = :now",
    { now: Time.current }
  ]

  Task.where(id: updates.keys).update_all(update_sql)
end

This is the most performant way to handle complex batch updates, combining the power of raw SQL with the safety of Rails' sanitization.

Production Considerations

Locking and Concurrency

A long-running update_all can lock many rows, blocking other requests. This can cause timeouts in a high-traffic application. It's often better to process records in batches to reduce lock duration.

Processing in Batches

For very large updates, use in_batches to break the work into smaller chunks. This runs more queries but keeps transactions short and locks minimal.

# Process 50,000 users in batches of 5,000
User.where("last_login_at < ?", 90.days.ago)
    .in_batches(of: 5000) do |batch|
      batch.update_all(active: false, updated_at: Time.current)
      sleep(0.1) # Optional: yield to other processes
end

The Decision Framework

update: The default for single-record updates where callbacks and validations must run.
update_columns: A scalpel for single-record updates where callbacks and validations must be skipped.
update_all: The workhorse for bulk-updating many records to the same value.
update_all with CASE: The specialist tool for bulk-updating many records to different values.

Avoid set-based updates entirely when you need to trigger side effects (like sending emails) for each updated record or when you need to run model validations.

Conclusion

The next time you write .each { |record| record.update(...) }, pause. Ask yourself: am I processing complex business logic for each record, or am I simply updating a set of records based on a condition?

If you're just changing data, you're in set-based territory. Choosing the right tool for the job is the mark of a seasoned developer. Your database will thank you. And when your background job finishes in 8 seconds instead of timing out after 4 hours, you will too.

How CLAUDE.md actually works

Wilbur Suero — Sat, 09 May 2026 06:33:47 +0000

Most engineers write CLAUDE.md like a README. They put their stack, a few preferences, maybe a note about testing. The agent reads it, nods politely, and proceeds to write code shaped by its training data rather than their codebase.

The file exists. It doesn't do much.

The problem isn't effort. It's category. A README describes a project. A specification constrains behavior. CLAUDE.md only works as the second thing, and most engineers have never written a specification for an agent before, so they reach for the format they know.

This post covers three dimensions of getting it right: how to structure the file, how to write rules the agent actually follows, and how to keep the file current as the codebase evolves.

Structure: one file is the wrong model

Claude Code reads CLAUDE.md from the project root. What most engineers don't know is that it also reads CLAUDE.md from any subdirectory it's working in, and those files inherit from the root.

This matters because context is directional. The rules that apply when the agent is writing a migration are not the rules that apply when it's writing a Sidekiq job. A single root file that tries to encode both produces either redundancy or contradiction.

A structure that works:

project/
├── CLAUDE.md                    # global constraints, stack, communication protocol
├── app/
│   ├── models/CLAUDE.md         # schema rules, validation patterns, query constraints
│   ├── jobs/CLAUDE.md           # idempotency rules, retry logic, failure handling
│   └── services/CLAUDE.md       # when to extract, interface contracts, no god objects
└── db/
    └── migrate/CLAUDE.md        # migration rules, index requirements, reversibility

Each file answers: what does good work look like in this specific part of the codebase?

The root file handles things true everywhere: pinned versions, architectural decisions already made, the communication protocol (plan before execute, ask before touching schema). The directory files encode local expertise. When the agent opens app/jobs/, it reads both. The local file wins on conflicts.

Write the root file last. You'll know what belongs there after writing the directory files, because you'll see what keeps repeating.

Structure: separate facts from rules

Inside any CLAUDE.md, two categories of content live at different distances from the agent's decisions.

Facts describe the environment:

## Stack
- Ruby 3.3.4
- Rails 7.2.1
- PostgreSQL 15
- Sidekiq 7.3
- pgvector 0.7 (used in app/models/document.rb, not widely available)

Rules constrain behavior:

## Database
Never update records in a loop. Use set-based updates.
Never call update_all without a WHERE condition.
Every query touching the documents table needs an EXPLAIN ANALYZE before merging.

Engineers mix these in paragraph form and the agent treats them with roughly equal weight. Separate them with explicit headers. Facts get a section. Rules get a section. The agent applies rules when deciding; it consults facts when writing. Conflating them produces a file that's harder to maintain and rules that get buried.

Content: negative rules outperform positive ones

"Prefer set-based updates" loses to "never update records in a loop." Both encode the same intent. One requires the agent to weigh it against competing preferences. The other removes the decision entirely.

Agents generalize from positive instructions; they treat negative ones as constraints. Constraints bind more consistently than preferences, especially when the agent is mid-task and optimizing for completion.

The practical test: rewrite every "prefer X" in your CLAUDE.md as "never Y." If you can't, the rule isn't specific enough to be useful.

Compare:

# Weak
Prefer idiomatic Rails patterns where possible.

# Useful
Never extract a service object without a domain justification written in a comment above the class.
Never rescue StandardError without logging the exception and the calling context.
Never write a background job where perform is not safe to call twice with the same arguments.

The first rule tells the agent something it already knows. The second, third, and fourth tell it something about your codebase specifically, stated as a constraint it can't argue with.

Content: attach the why to every constraint

A rule without a reason the agent follows literally. A rule with a reason it generalizes.

# Without why
Never use update_all without conditions.

# With why
Never use update_all without conditions. A bare update_all on the users table
has caused production data corruption twice in this codebase because background
jobs held stale references. Always scope it.

Both rules produce the same behavior on the exact scenario described. The second one produces correct behavior on the novel scenario the agent hasn't seen yet, because it understands the failure mode. The agent can ask "does this situation have the same risk?" and answer correctly.

This is the highest-leverage thing you can do to CLAUDE.md. Every rule that currently has no attached reason is a rule the agent interprets locally and fails to generalize.

The format that works:

**Rule:** [constraint]
**Why:** [failure mode or past incident that produced the rule]
**Exception:** [when the rule doesn't apply, if any]

Not every rule needs a formal format. But every non-obvious rule needs a reason.

Content: priority ordering for conflicting rules

Rules conflict. An instruction to keep methods short conflicts with an instruction to avoid multiple database queries. An instruction to match existing patterns conflicts with an instruction to apply a new convention to all new files.

Without explicit priority, the agent resolves conflicts by training data, not by your intent.

Add a section near the top of the root file:

## Rule priority

When instructions conflict, apply them in this order:

1. Correctness — no silent failures, no data loss
2. Schema integrity — migrations reviewed, constraints in place before code
3. Explicit rules in this file — over Rails defaults, over conventions
4. Rails conventions — over agent judgment
5. Agent judgment — last resort only

This sounds obvious written out. It isn't obvious to an agent mid-task, and the cost of the agent resolving a conflict incorrectly is a file it has already changed.

Content: show examples inline

Instructions describe intent. Examples demonstrate standard.

For any rule where the wrong implementation is plausible, put both versions in the file:

## Background jobs

Jobs must survive duplicate execution. Test this by reading perform as if it runs twice in sequence with the same arguments.

Bad:

def perform(order_id)
  order = Order.find(order_id)
  order.update!(status: :processed)
  OrderMailer.confirmation(order).deliver_later
end


Good:

def perform(order_id)
  order = Order.find(order_id)
  return if order.processed?

  order.update!(status: :processed)
  OrderMailer.confirmation(order).deliver_later
end


The return guard is the idempotency checkpoint. Every job needs one.

The agent calibrates to examples faster than to instructions. It can see the difference between the two implementations immediately; it can't always infer the difference from a prose rule alone.

Workflow: let the agent update the file

This is the trick most engineers skip entirely.

After any session where the agent encountered a pattern it didn't handle correctly, or where you corrected its output more than once, end the session with:

Before we close: what did you learn in this session that should be added to CLAUDE.md?
List specific rules or facts, not generalizations. Draft the additions in the format
already used in the file.

The agent has context you don't at the end of a long session. It knows which rules it consulted, which ones it had to interpret ambiguously, and where it made a decision it wasn't confident about. It can surface those explicitly if you ask.

Review what it produces. Reject what's too general. Add what's specific and accurate.

This loop does two things. First, it keeps CLAUDE.md current without requiring you to remember what happened three sessions ago. Second, it produces rules written in a format the agent understands, because the agent wrote them.

Workflow: treat CLAUDE.md as a living specification under version control

CLAUDE.md should be in git. Commit messages should say why a rule changed, not just that it did.

Add explicit idempotency requirement to jobs/CLAUDE.md

Background job wrote duplicate notifications in production on 2024-11-12
because the retry logic ran perform twice. Added rule with failure mode attached.

Read the git history of CLAUDE.md the same way you'd read the git history of a schema file. It tells you what the codebase has learned about itself. A rule with no commit context is a rule you'll forget to defend when someone asks why it exists.

A practical schedule: review CLAUDE.md every Friday, same as any other configuration that controls production behavior. Ask three questions:

Which rules did the agent follow incorrectly this week? Rewrite them.
Which decisions did we make that aren't encoded yet? Add them.
Which rules are stale because the codebase has changed? Remove or update them.

Ten minutes. The agent's output quality is a direct function of how current the file is. Stale context produces output that was correct for the codebase you had six months ago.

Workflow: ask the agent to audit its own compliance

At the start of a session where the work is consequential, run this before any task:

Read CLAUDE.md, then read the files you're about to modify.
Before writing any code, list:
1. Which rules in CLAUDE.md apply to this task
2. Any existing code in the target files that already violates those rules
3. Any ambiguity in the rules that you'll need me to resolve

This surfaces two problems before they compound: rules the agent would have applied inconsistently, and existing violations it would have implicitly extended by matching surrounding code.

The audit takes thirty seconds. It prevents the situation where the agent writes new code that follows your rules while the file it's modifying already breaks them, and now you have an inconsistency with the agent's fingerprints on both sides of it.

The underlying model

CLAUDE.md is a specification for a collaborator who has no memory between sessions, has read every Rails codebase that existed before its training cutoff, and defaults to the most common pattern when your instructions are ambiguous.

The file's job is to replace "most common Rails pattern" with "this specific codebase's pattern." It can only do that job if the rules are negative and specific, the reasons are attached, the examples show the wrong and right version side by side, and the file is updated when the codebase learns something new.

Write it like a contract your future self will have to enforce. Because every session, you're handing the codebase to someone who has never seen it before and has to be told everything that matters.

The README version of CLAUDE.md produces a generic collaborator. The specification version produces one that can be trusted with a schema migration.

Writing Maintainable AI Prompts in Rails with Promptly

Wilbur Suero — Mon, 18 Aug 2025 22:03:48 +0000

A few months ago, I was helping a Rails team add AI-generated onboarding emails to their app. It seemed simple at first: drop an OpenAI.chat(...) call inside a mailer, pass in the user’s name, and let the model draft a warm welcome.

By the second week, things got messy.

Different controllers and jobs had their own inline prompts.

Some prompts were copy-pasted with slight tweaks (“friendly tone”, “professional tone”, etc.).

Marketing wanted localized versions for Spanish and Portuguese.

QA asked, “How do we know the prompts didn’t change by accident?”

We ended up with prompt spaghetti—hard to test, impossible to translate cleanly, and brittle whenever we tried to refactor.

That experience sparked the idea for Promptly: a small gem that brings Rails conventions to AI prompt management.

The Problem: Prompts Don’t Belong Scattered in Code

Rails developers already know the pain of hard-coded strings—why we use views, partials, and I18n instead of littering messages across controllers. Yet many of us are now hardcoding AI prompts directly in service objects or background jobs.

It doesn’t scale.

Duplication: The same wording lives in multiple places.
Localization headaches: Inline strings don’t play well with I18n.
No safety net: Refactors can silently change how the AI behaves.

The Solution: Promptly

Promptly lets you define AI prompts as ERB or Liquid templates, stored in a Rails-native directory structure. Just like you’d render a view, you render a prompt:

# app/prompts/welcome_email.erb
Hello <%= @user.name %>, welcome to our service!
We’re excited to have you join.

# In your mailer or service:
render_prompt("welcome_email", user: @user)

This unlocks the same benefits Rails developers already rely on elsewhere:

Maintainability → All prompts live in one place.
Localization → Templates can use I18n just like views.
Testability → You can write RSpec tests that assert on rendered prompt output.

Why Rails Conventions Matter

Rails has always thrived on convention over configuration. Promptly doesn’t reinvent the wheel; it extends familiar concepts (views, templates, helpers) into the AI space.

Instead of partials, you have prompt templates.
Instead of locals, you have prompt variables.
Instead of ad-hoc strings, you have structured, versionable files.

Getting Started

Add it to your Gemfile:

gem 'promptly'

2.Create your first template in app/prompts.
3.Render it anywhere with render_prompt.
4.Add tests to verify the output.

Full docs are in the GitHub repo.

Looking Ahead

Promptly is intentionally small. It’s not trying to be a full-blown AI orchestration platform. But by solving one narrow pain point—making prompts maintainable, testable, and Rails-friendly—it can help Rails apps adopt AI without chaos.

The next steps may include:

Prompt versioning.
Preview workflows in Rails consoles.
Deeper integration with related gems like semantic search adapters.

If you’re a Rails developer experimenting with AI, try Promptly. It may save you from prompt spaghetti before it starts.

Feedback and contributions are welcome, the best ideas usually come from real-world use.

🚨 Introducing GemGuard: Automated Security for Ruby Gems (Scan, SBOM, Typosquat, Auto-Fix)

Wilbur Suero — Mon, 11 Aug 2025 02:05:38 +0000

Links:

GitHub: github.com/wilburhimself/gem_guard
RubyGems: rubygems.org/gems/gem_guard

TL;DR

✅ Scan dependencies for known vulnerabilities (OSV.dev + Ruby Advisory DB)
🕵️ Detect typosquat packages before they bite
📜 Generate SPDX / CycloneDX SBOMs
🛠 Auto-fix vulnerable gems safely
⚡ Clean CLI + CI-ready
Version: 1.1.x

Why GemGuard?

Because security shouldn’t be an afterthought. It should be:

Pragmatic – only what matters, no noise
Fast – instant feedback in dev or CI
Integrated – works with your normal Ruby workflow

What is GemGuard?

GemGuard is a lightweight Ruby security tool that:

Scans your Gemfile.lock for known vulnerabilities
Detects typosquat risks via fuzzy matching
Generates SBOMs (SPDX and CycloneDX)
Auto-fixes vulnerable gems with safe version upgrades
Plays nicely with CI/CD

Installation

# Add to your Gemfile (recommended for projects)
gem "gem_guard", "~> 1.1"

# Or install globally
gem install gem_guard

Verify:

gem_guard version
# => 1.1.x

Quick Start

Scan your project:

gem_guard scan
# ✅ No vulnerabilities found!
# or exits non‑zero if issues are found

Detect typosquats:

gem_guard typosquat
# No potential typosquat dependencies found.

Generate an SBOM:

gem_guard sbom --format spdx --output sbom.spdx.json
gem_guard sbom --format cyclonedx --output bom.cdx.json

Auto‑Fix Vulnerabilities

Preview (dry run):

gem_guard fix --dry-run

Apply fixes (creates a Gemfile.lock backup by default):

gem_guard fix
# 📦 Created backup: Gemfile.lock.backup.2025...
# ✅ Updated nokogiri to 1.18.9
# 🔄 Running bundle install to update lockfile...

Options:

--interactive: confirm each update
--no-backup: skip lockfile backup
--gemfile, --lockfile: custom paths

Tip: Re-scan after fixing

gem_guard scan

Clean CLI

gem_guard --help
# config, scan, typosquat, sbom, fix, version

Exit codes:

0: success / no vulns
1: vulnerabilities found
2: errors (e.g., missing files)

CI/CD Integration (GitHub Actions)

name: security-scan
on: [push, pull_request]
jobs:
  gemguard:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: ruby/setup-ruby@v1
        with:
          ruby-version: '3.3'
          bundler-cache: true
      - run: gem install gem_guard
      - run: gem_guard scan --format json > gemguard-report.json
      - run: gem_guard typosquat --format json > typosquat-report.json
      - name: Upload reports
        uses: actions/upload-artifact@v4
        with:
          name: gemguard-reports
          path: |
            gemguard-report.json
            typosquat-report.json

Fail builds on vulnerabilities (default behavior). If you want non-blocking scans (e.g., on main), wrap with || true or use matrix strategies.

Configuration

Create .gemguard.yml:

lockfile: Gemfile.lock
output:
  format: table   # table | json
typosquat:
  similarity_threshold: 0.82
  risk_levels:
    high: 0.9
    medium: 0.85

View current config:

gem_guard config --show

Why GemGuard?

Minimal setup, zero noise
Pragmatic defaults, sensible exit codes
Works offline for typosquat via fallback popular gems
Well-tested (RSpec), standardrb formatting
Designed for CI from day 1

How It Compares

Bundler Audit: great for advisories; GemGuard adds typosquat + SBOM + auto-fix
OSV-Scanner: broad ecosystem; GemGuard is Ruby-first with tighter UX and auto-fix
Trivy/Grype: container focus; GemGuard slots into pure-Ruby pipelines easily

Use GemGuard standalone or alongside your existing stack.

Roadmap

Enriched advisories (GHSA/CVE links, CVSS)
Optional dependency graph visualizations
Interactive TUI
More fix strategies and guards

Contribute / Feedback

Issues/PRs welcome: add tests, keep it minimal and intention-revealing
Prefer failing test → minimal fix → refactor
Security disclosures: see SECURITY.md

Try It Now

gem install gem_guard
gem_guard scan
gem_guard typosquat
gem_guard fix --dry-run

If this helps you ship safer Ruby apps with less fuss, drop a ❤️ and share!

— Built for Rubyists who like fast feedback, clean CLIs, and reliable automation.

Issues and PRs welcome → github.com/wilburhimself/gem_guard

How I Built a RAG System in Rails Using Nomic Embeddings and OpenAI

Wilbur Suero — Fri, 18 Jul 2025 19:48:41 +0000

Retrieval-Augmented Generation (RAG) lets you bring your own data to LLMs—and get real answers. I’ll show how I used the open-source nomic-embed-text-v2-moe model for semantic search in a Rails app, while still using OpenAI for generation.

🧠 What is RAG?

RAG (Retrieval-Augmented Generation) enhances LLMs by feeding them relevant chunks of your data before generating a response. Instead of fine-tuning, we give the model useful context.

Here's the basic pipeline:

[ User Question ]
        ↓
[ Embed the Question (Nomic) ]
        ↓
[ Vector Search in PgVector ]
        ↓
[ Retrieve Relevant Chunks ]
        ↓
[ Assemble Prompt ]
        ↓
[ Generate Answer with OpenAI ]

🧰 The Stack

Rails – Backend framework, routes, controllers, and persistence
Nomic Embedding Model – For semantic understanding of data
FastAPI – Lightweight Python server to serve embeddings
PgVector – PostgreSQL extension to store and query vector data
OpenAI GPT-4 / GPT-3.5 – For the final response generation

🛠 Step 1: Run the Nomic Model Locally (Optional but Fast)

You can run the nomic-embed-text-v2-moe model using sentence-transformers in a Python FastAPI app:

from fastapi import FastAPI, Request
from sentence_transformers import SentenceTransformer

app = FastAPI()
model = SentenceTransformer("nomic-ai/nomic-embed-text-v2-moe")

@app.post("/embed")
async def embed(req: Request):
    data = await req.json()
    input_text = data["input"]
    embedding = model.encode(input_text).tolist()
    return { "embedding": embedding }

This becomes your internal embedding API, replacing OpenAI’s /embeddings.

📄 Step 2: Chunk and Store Your Data

Split your content into short passages (~100–300 words), embed them via your FastAPI endpoint, and store the results in PostgreSQL with pgvector.

Add a vector column:

psql -d your_db -c "CREATE EXTENSION IF NOT EXISTS vector;"

class AddEmbeddingToDocuments < ActiveRecord::Migration[7.1]
  def change
    add_column :documents, :embedding, :vector, limit: 768 # Nomic v2-moe size
  end
end

🤖 Step 3: Embed User Queries via Nomic

In your Rails controller:

def get_embedding(text)
  response = Faraday.post("http://localhost:8000/embed", { input: text }.to_json,
                          "Content-Type" => "application/json")
  JSON.parse(response.body)["embedding"]
end

Use the same model for both document and query embeddings.

🔍 Step 4: Perform Vector Search with PgVector

Search your documents for the closest matches using cosine distance:

Document.order("embedding <-> cube(array[?])", query_vector).limit(5)

These top chunks become the context for the LLM.

🧾 Step 5: Build a Smart Prompt for OpenAI

Concatenate the top passages and feed them into OpenAI’s chat API:

client.chat(
  parameters: {
    model: "gpt-4",
    messages: [
      { role: "system", content: "You are an assistant answering based on the provided context." },
      { role: "user", content: build_contextual_prompt(user_input, top_chunks) }
    ]
  }
)

✅ Why Use Nomic for Embeddings?

High-quality, open-source, multilingual
No token limits — runs locally or self-hosted
Zero vendor lock-in at the embedding layer
Great performance on MTEB and real-world retrieval

💡 Why I Still Use OpenAI for the LLM

The generation step is where OpenAI shines. Instead of replacing it prematurely, I decoupled the embedding stage. Now I can experiment, optimize, and even switch LLMs later if needed.

🧠 Takeaways

RAG doesn’t need to be a heavyweight system.
Open-source embeddings + OpenAI generation = powerful, flexible hybrid.
PgVector + Rails makes vector search feel native and hackable.

The Art of Idiomatic Ruby: Principles and Practices for Elegant Code

Wilbur Suero — Mon, 17 Mar 2025 17:29:02 +0000

As developers, we're constantly seeking to improve our craft and develop a coding style that's both effective and elegant. Ruby stands out among programming languages for its expressiveness and focus on developer happiness. The philosophy behind Ruby and its most popular framework, Rails, has shaped how countless developers think about software design, readability, and the overall development experience.

In this post, I'll explore the key principles behind idiomatic Ruby, analyze what makes Ruby code truly "Rubyesque," and share practical ways to incorporate these principles into your own work.

Core Philosophy of Idiomatic Ruby

Ruby's approach to programming is built on several foundational principles:

Convention over Configuration

One of Ruby's most influential frameworks popularized the concept of sensible defaults and conventions. Rather than requiring developers to make countless trivial decisions, idiomatic Ruby emphasizes having established patterns that make assumptions about what developers need and provide streamlined pathways for common tasks.

This philosophy extends beyond frameworks into coding style, where established patterns and clear conventions are favored over reinventing the wheel or introducing unnecessary complexity.

Beautiful Code

In the Ruby community, code isn't just functional—it's a form of craft. There's a strong emphasis on the aesthetics of code, with the understanding that beautiful code is more maintainable, more enjoyable to work with, and ultimately more effective. This focus on beauty manifests in a preference for expressive, readable syntax that almost reads like natural language.

Programmer Happiness

"Optimize for programmer happiness" is a consistent theme in the Ruby community. While some languages and frameworks optimize primarily for performance or flexibility, Ruby prioritizes the developer experience. This perspective views coding as a creative act that should be enjoyable rather than tedious.

Opinionated Software Design

Idiomatic Ruby doesn't shy away from having strong opinions about how software should be built. Rather than trying to accommodate every possible approach, Ruby and its ecosystem often present "The Ruby Way" of doing things. Making strong choices about architecture and design patterns creates a more cohesive and understandable codebase.

Elements of Idiomatic Ruby Style

When examining truly elegant Ruby code, several distinctive characteristics emerge:

Expressive Naming

Idiomatic Ruby places tremendous importance on choosing the right names for variables, methods, and classes. It favors descriptive, sometimes longer names that clearly communicate intent over terse abbreviations. The goal is code that can be read and understood without extensive comments or documentation.

For example, instead of:

def calc_ttl_prc(items)
  # Calculate total price with discount
  items.sum(:price) * 0.9
end

Idiomatic Ruby prefers:

def total_price_with_discount(items)
  items.sum(:price) * 0.9
end

Embracing Ruby's Natural Expressiveness

Truly Rubyesque code leans heavily into the language's syntax to create code that feels natural and reads almost like English prose. It makes full use of Ruby's blocks, optional parentheses, and symbol shortcuts to create concise yet readable code.

# Less idiomatic
users.select { |user| user.subscribed? }.each { |user| user.send_newsletter }

# More idiomatic 
users.select(&:subscribed?).each(&:send_newsletter)

Domain-Driven Design

Idiomatic Ruby often designs code around domain concepts rather than technical implementation details. Classes and methods reflect the business domain, making the code not just functional but a representation of the problem space itself.

Pragmatic Testing Approach

The Ruby community has evolved a pragmatic approach to testing. While testing is valued, there's a focus on testing the outcomes that matter rather than implementation details. System tests that verify functionality from the user's perspective are often favored alongside focused unit tests.

Strategic Metaprogramming

Ruby's powerful metaprogramming capabilities are a double-edged sword. Idiomatic Ruby uses metaprogramming strategically to eliminate boilerplate and create more elegant APIs, not as a showcase of technical wizardry.

Key Design Patterns in Ruby

Several design patterns are central to idiomatic Ruby programming:

Active Record Pattern

The Active Record pattern, which blends database access and business logic into a single object, is widely used in the Ruby ecosystem. While this approach breaks with strict separation of concerns, it creates an intuitive model that's easy to work with.

class Product < ApplicationRecord
  has_many :reviews
  belongs_to :category

  validates :name, presence: true
  validates :price, numericality: { greater_than: 0 }

  def discounted_price
    price * 0.9
  end
end

Modules and Concerns for Shared Behavior

Instead of deep inheritance hierarchies, idiomatic Ruby favors using modules as "Concerns" to share behavior across multiple classes. This creates more flexible composition without the rigid structures that deep inheritance can create.

module Trackable
  extend ActiveSupport::Concern

  included do
    has_many :audit_logs
    after_save :record_change
  end

  def record_change
    audit_logs.create(action: "updated")
  end
end

class Product < ApplicationRecord
  include Trackable
  # Product-specific code...
end

Convention-Based Routing

RESTful routing establishes clear conventions for mapping HTTP verbs and URLs to controller actions, creating a predictable structure for web applications.

Service Objects for Complex Operations

For operations that span multiple models or incorporate complex business logic, Ruby developers often employ service objects—dedicated classes that encapsulate a single operation or transaction.

class OrderProcessor
  def initialize(order, payment_details)
    @order = order
    @payment_details = payment_details
  end

  def process
    return false unless valid?

    ActiveRecord::Base.transaction do
      process_payment
      update_inventory
      send_confirmation
    end

    true
  end

  # Private methods for each step...
end

How to Write Idiomatic Ruby

If you're inspired by Ruby's elegant approach and want to incorporate elements of idiomatic style into your own work, here are some practical steps:

1. Prioritize Readability Above All

Write code for humans first, computers second. Invest time in creating clear, expressive code that future developers (including your future self) will easily understand.

2. Embrace Ruby's Unique Features

Work with Ruby's strengths rather than fighting against them. Learn what makes Ruby special—blocks, procs, symbols, method_missing, etc.—and use those features to create more elegant code.

# Instead of:
["apple", "banana", "cherry"].map { |fruit| fruit.upcase }

# Write:
["apple", "banana", "cherry"].map(&:upcase)

3. Design Around Your Domain

Structure your code to reflect the business or problem domain rather than technical considerations. Your classes and methods should speak the language of your users and stakeholders.

4. Follow Conventions but Break Them When Necessary

Establish and follow conventions in your codebase, but be willing to break them when they don't serve your needs. Ruby isn't dogmatic about rules—it's pragmatic about results.

5. Value Simplicity Over Complexity

Resist the urge to over-engineer. The Ruby community often advocates for the simplest solution that works, even if it's not the most theoretically pure or technically impressive.

6. Consider the Whole System

Think holistically about your application rather than optimizing individual components in isolation. An idiomatic approach considers how all parts of a system work together to create a cohesive whole.

7. Make Development Enjoyable

Finally, remember that coding should be enjoyable. Create tools, processes, and code that make development a pleasure rather than a chore—this is perhaps the most Ruby-like approach of all.

8. Pay Attention to Code Smells

Learn to recognize and refactor common code smells:

# Code smell: Long method
def process_order
  # 100 lines of code doing many different things
end

# Refactored: Extracted methods with clear purposes
def process_order
  validate_order
  process_payment
  update_inventory
  send_confirmation
end

9. Follow Community Style Guides

Familiarize yourself with established Ruby style guides like the one from GitHub or Rubocop's defaults. These encapsulate years of community wisdom about what makes Ruby code clear and maintainable.

Idiomatic Ruby represents a philosophy of software development that values human factors alongside technical considerations—code that's not just functional but beautiful, maintainable, and enjoyable to work with.

By prioritizing readability, embracing Ruby's unique features, and focusing on developer happiness, you can create code that not only works but brings joy to those who interact with it. That's the true spirit of Ruby.

What aspects of Ruby's style have influenced your own development approach? What patterns or practices do you find most valuable in your own Ruby projects? Share your thoughts and experiences in the comments below.

Understanding Form Objects in Ruby on Rails

Wilbur Suero — Thu, 13 Mar 2025 21:38:04 +0000

In Ruby on Rails applications, handling complex forms can become messy when too much logic is stuffed into models or controllers. This is where Form Objects come in—a design pattern that helps separate form-related logic from Active Record models, making our applications more maintainable and testable.

The Problem with Traditional Forms

By default, Rails encourages using Active Record models directly in forms. However, this approach has some downsides:

Fat Models: Business logic and validation bloat the model, making it harder to maintain.
Fat Controllers: Controllers become responsible for handling complex form submissions.
Multiple Models in One Form: Standard Rails forms work well with single models, but handling multiple related models can be cumbersome.

To address these issues, we use Form Objects.

What is a Form Object?

A Form Object is a Plain Old Ruby Object (PORO) designed to handle form submissions. It encapsulates form-specific validations and persistence logic while keeping models and controllers clean.

When to Use a Form Object

When a form involves multiple models.
When you want to keep your controllers thin and models focused.
When form validation differs from the database schema.
When reusing form logic across multiple places in your application.

Implementing a Form Object in Rails

Let's walk through an example where we create a UserRegistrationForm that handles user sign-ups along with profile information.

Step 1: Create the Form Object

Create a new file in app/forms/user_registration_form.rb:

class UserRegistrationForm
  include ActiveModel::Model

  attr_accessor :name, :email, :password, :password_confirmation, :bio

  validates :name, :email, :password, :password_confirmation, presence: true
  validates :password, confirmation: true
  validates :email, format: { with: URI::MailTo::EMAIL_REGEXP }

  def initialize(attributes = {})
    super(attributes)
  end

  def save
    return false unless valid?

    ActiveRecord::Base.transaction do
      user = User.create!(name: name, email: email, password: password)
      Profile.create!(user: user, bio: bio)
    end
    true
  rescue ActiveRecord::RecordInvalid
    false
  end
end

Step 2: Use the Form Object in the Controller

Modify the UsersController to use the UserRegistrationForm:

class UsersController < ApplicationController
  def new
    @form = UserRegistrationForm.new
  end

  def create
    @form = UserRegistrationForm.new(user_params)

    if @form.save
      redirect_to root_path, notice: 'User registered successfully!'
    else
      render :new
    end
  end

  private

  def user_params
    params.require(:user_registration_form).permit(:name, :email, :password, :password_confirmation, :bio)
  end
end

Step 3: Update the View

Modify the new.html.erb view:

<%= form_with model: @form, url: users_path do |form| %>
  <div>
    <%= form.label :name %>
    <%= form.text_field :name %>
  </div>

  <div>
    <%= form.label :email %>
    <%= form.email_field :email %>
  </div>

  <div>
    <%= form.label :password %>
    <%= form.password_field :password %>
  </div>

  <div>
    <%= form.label :password_confirmation %>
    <%= form.password_field :password_confirmation %>
  </div>

  <div>
    <%= form.label :bio %>
    <%= form.text_area :bio %>
  </div>

  <div>
    <%= form.submit 'Register' %>
  </div>
<% end %>

Benefits of Using Form Objects

Separation of Concerns: Keeps models and controllers focused on their primary responsibilities.
Improved Testability: You can test form logic independently.
Easier Maintenance: Avoids bloated models with unnecessary validations.

Form Objects in Ruby on Rails provide a clean way to manage complex form submissions while keeping code organized. By encapsulating form logic in a dedicated class, we improve maintainability, readability, and re-usability in our applications.

If you're dealing with bloated models and controllers due to complex forms, consider adopting Form Objects as a structured solution!

Background Jobs in Rails: A Look at SolidQueue

Wilbur Suero — Wed, 12 Mar 2025 05:43:03 +0000

Coming from a Rails background, one of the most common patterns developers rely on is background job processing. Traditionally, this has meant reaching for Sidekiq, Resque, or Delayed Job—external tools that require Redis or additional infrastructure. But what if you could handle background jobs natively within your database? Enter SolidQueue.

In this post, I’ll explore how SolidQueue changes the game for Rails developers, how it compares to existing background job solutions, and how you can start using it today.

SolidQueue in Rails 8: Built-In Background Jobs

With the release of Rails 8, SolidQueue is now bundled as the default background job system. This means that if you're starting a new Rails 8 application, you already have everything you need to manage background jobs without any additional dependencies.

Minimum Required Version

SolidQueue requires Rails 7.1 or later to function. However, for full integration and the best experience, Rails 8 is recommended since it comes pre-configured.

Understanding SolidQueue: Background Jobs Without External Dependencies

SolidQueue is a database-backed queuing system designed to work seamlessly with Active Job in Rails. Unlike Sidekiq or Resque, which rely on Redis, SolidQueue keeps everything within your application’s SQL database. The result? Simplified infrastructure, reduced operational complexity, and one less dependency to worry about.

Key Features of SolidQueue

Native Database Integration: Jobs are stored and managed using PostgreSQL, MySQL, or SQLite—whichever database your Rails app already uses.
Active Job Compatibility: Works out of the box with Rails' Active Job framework.
No Additional Services Required: Eliminates the need for Redis or external queueing systems.
Mission Control UI: Provides a web interface to monitor and manage jobs.
Automatic Job Retries & Error Handling: Ensures reliable job execution.

How to Set Up SolidQueue in Rails 8

If you're using Rails 8, SolidQueue is already included, and you just need to enable it.

Enabling SolidQueue in a New Rails 8 App

For new Rails 8 applications, SolidQueue is the default Active Job adapter. To ensure it is enabled, check your config/application.rb:

config.active_job.queue_adapter = :solid_queue

Then, run the database migrations to set up the necessary tables:

rails db:migrate

Setting Up SolidQueue in an Existing Rails 7.1+ App

If you're on Rails 7.1 or later and want to use SolidQueue, you'll need to install it manually:

# Add to your Gemfile
gem 'solid_queue'

Then, run the installation generator:

bundle exec rails generate solid_queue:install
rails db:migrate

Defining and Enqueueing Jobs

Creating jobs with SolidQueue is no different from using Active Job:

class ExampleJob < ApplicationJob
  queue_as :default

  def perform(name)
    puts "Processing job for #{name}"
  end
end

ExampleJob.perform_later("Alice")

Running Jobs

SolidQueue requires a supervisor process to run jobs. Start it with:

bundle exec solid_queue:start

This will process jobs from the database queue, similar to how Sidekiq works.

A More Detailed Example: Processing an Order in Rails 8

Let’s say we’re building an e-commerce application and need to process orders asynchronously. With SolidQueue in Rails 8, we can handle this with ease.

Step 1: Define the Job

class ProcessOrderJob < ApplicationJob
  queue_as :default

  def perform(order_id)
    order = Order.find(order_id)
    order.process_payment!
    order.update!(status: "completed")
    puts "Order ##{order.id} has been processed."
  end
end

Step 2: Enqueue the Job When an Order is Created

Modify your OrdersController:

class OrdersController < ApplicationController
  def create
    @order = Order.create!(order_params)
    ProcessOrderJob.perform_later(@order.id)
    redirect_to @order, notice: "Your order is being processed."
  end
end

Step 3: Start the Worker Process

To start processing jobs, simply run:

bundle exec solid_queue:start

Now, every time a new order is created, it will be processed in the background by SolidQueue.

Comparing SolidQueue to Sidekiq

Feature	SolidQueue (Database-Backed)	Sidekiq (Redis-Backed)
Dependency	Uses SQL database	Requires Redis
Infrastructure	No extra services needed	Needs Redis, Sidekiq
Performance	Good for most applications	Optimized for high throughput
UI for Jobs	Mission Control UI	Sidekiq Web UI
Reliability	Database transactions ensure safety	Redis-based, requires persistence tuning

If you’re running a high-throughput application with millions of background jobs per day, Sidekiq may still be the best choice. But for most Rails applications, SolidQueue provides a much simpler, integrated solution without the extra operational burden.

When Should You Use SolidQueue?

SolidQueue is a great choice if:

You want to avoid the overhead of running Redis.
Your application already relies heavily on its database.
You prefer an all-in-one solution with built-in job monitoring.
You need Active Job compatibility with minimal setup.

However, if you need extreme performance and high concurrency, Sidekiq might still be the better option.

SolidQueue represents a shift in how Rails developers can handle background jobs. By leveraging the database as a queueing system, it removes the need for external services like Redis while maintaining reliability and simplicity. With Rails 8, SolidQueue is now the default, making background job processing more accessible than ever.

If you’re using Rails 8, try it out today—it’s already built in! And if you're on an older version, upgrading to Rails 8 or installing SolidQueue manually can help simplify your background job processing.

DEV Community: Wilbur Suero

AISpec: RSpec for AI Behavior, Not AI Outputs

Behavioral invariants vs. static text assertions

Defining behavioral contracts in AISpec

Benchmarking across models

Rails integration

1. Initializer and custom assertions

2. Running contracts in RSpec

Continuous verification in GitHub Actions

The Two Sources of Noise Every LLM Evaluation System Must Handle

The Fallacy of the Scoreboard

Problem #1: Sometimes There Isn't a Right Answer

How to Mitigate Task Ambiguity

Problem #2: Sometimes the Judge Is Wrong

How to Mitigate Judge Uncertainty

Why This Matters

Moving Beyond the Scoreboard

More Threads, Less Throughput: When AI Servers Fight the Scheduler

The Benchmark That Didn't Make Sense

Our Initial Hypotheses

Following the CPU: The 240-Thread Discovery

Why Native Libraries Lie to You

The Cost of Concurrency: Scheduler Contention

The Fix: Global Concurrency Coordination

When Multi-Threaded Math Libraries Are Actually Good

The Broader Engineering Lesson

Stop Sending Embeddings as JSON: A Faster Binary Serialization Pattern for AI APIs

Why Numerical Data Doesn't Belong in JSON

The Naive Solution (and Why it Fails at Scale)

The Better Approach: Binary Float Buffers via Base64

1. Python Inference Server (Encoding)

2. Rails Application Server (Decoding)

Under the Hood: Endianness and the unpack Directive

1. Precision (Float32 vs. Float64)

2. Endianness (Byte Ordering)

The Tradeoffs

Why not gRPC or Protocol Buffers?

Why not MessagePack?

Why not Apache Arrow?

Why not raw binary HTTP?

The real costs

Conclusion: Text is for Humans, Binary is for Systems

Set-Based Updates in Rails: 4 Hours to 8 Seconds

The Power of update_all

The Sharp Edges of update_all

The updated_at Trap

The Middle Ground: update_columns

War Story #2: The Death-by-a-Thousand-Increments

Going Deeper: Safe Heterogeneous Updates with SQL CASE

Production Considerations

Locking and Concurrency

Processing in Batches

The Decision Framework

Conclusion

How CLAUDE.md actually works

Structure: one file is the wrong model

Structure: separate facts from rules

Content: negative rules outperform positive ones

Content: attach the why to every constraint

Content: priority ordering for conflicting rules

Content: show examples inline

Workflow: let the agent update the file

Workflow: treat CLAUDE.md as a living specification under version control

Workflow: ask the agent to audit its own compliance

The underlying model

Writing Maintainable AI Prompts in Rails with Promptly

The Problem: Prompts Don’t Belong Scattered in Code

The Solution: Promptly

Why Rails Conventions Matter

Getting Started

Looking Ahead

🚨 Introducing GemGuard: Automated Security for Ruby Gems (Scan, SBOM, Typosquat, Auto-Fix)

TL;DR

Why GemGuard?

What is GemGuard?

Installation

Verify:

Quick Start

Detect typosquats:

Generate an SBOM:

Under the Hood: Endianness and the `unpack` Directive

The Power of `update_all`

The Sharp Edges of `update_all`

The `updated_at` Trap

The Middle Ground: `update_columns`

Going Deeper: Safe Heterogeneous Updates with SQL `CASE`