João Gilberto Saraiva (EN)

Polished Ruby Programming: A book about fundamentals that landed right in my AI work

2026-08-13T00:00:00+00:00

A few weeks ago, someone from Packt reached out to me on LinkedIn. They had just released the second edition of Polished Ruby Programming and offered to send me a copy if I was willing to share my thoughts on it. You know I enjoy good tech books and work heavily with Ruby, so here we are. When the ebook arrived, I started skimming through it, expecting a solid, standard refresher on best practices.

It turned out to be much more than that—and in a direction I completely didn’t expect.

What’s inside

The scope is massive. Across 428 pages, Jeremy Evans covers core classes, variable and method design, error handling, code formatting, library and plugin architecture, metaprogramming, DSLs, testing, refactoring, deprecation, design patterns, concurrency, static versus duck typing, and optimization.

Evans is a Ruby committer and the maintainer of Roda and Sequel, so his opinions come with receipts. What I appreciated most is that almost nothing is handed down as an absolute rule. Even the SOLID principles arrive with a warning against applying them dogmatically. Every technique—a plugin system, a DSL, method_missing, static types—is presented as a trade-off. You are expected to decide for yourself, but you get a clear description of what each choice will cost you later. That’s a rarity in programming books.

A lot of the content is highly valuable on its own. But two chapters genuinely stopped me in my tracks because they answered questions I’d been wrestling with all year while building AI features into production Rails apps.

Here are my two highlights.

First highlight: Breaking circuits

This one hit close to home.

Chapter 5 is all about error handling: return values versus exceptions, designing APIs that are hard to misuse, fail-open versus fail-closed, retrying transient errors with backoff, and shaping exception hierarchies. Deep in the chapter, Evans builds a small circuit breaker from scratch: if a service fails three times in a minute, you stop calling it for a while, preventing every request from queuing up behind a provider that’s already down.

Then he closes the section with the exact kind of pragmatic advice I wish more books gave:

“If you need a circuit breaker for production code, you should probably use one of the many circuit breaker gems for Ruby instead of trying to implement a circuit breaker yourself, unless you have specific requirements not handled by an existing gem.”

That is the exact conclusion I reached last year when writing Building a Resilient AI Client in Ruby with Stoplight and ruby_llm for the JetRockets blog. The goal was to detect when a model provider is failing, trip the circuit, fail over to a backup model, and keep the conversation history intact. I went with Stoplight rather than rolling my own, for the exact reason Evans points out.

Still, reading the from-scratch implementation was incredibly useful. You end up understanding exactly what the gem handles for you, and more importantly, what it doesn’t. This chapter also gave me an insight my own article was missing: separating permanent from transient errors is a structural decision that belongs in your exception hierarchy, not in a rescue clause bolted on later. A rate limit and a malformed request are fundamentally different failures, and only one of them deserves a retry. Until now, I’d been treating both simply as “the provider is having a bad day.”

Second highlight: Only mock what you cannot control

The testing chapter drops this rule:

“If you must mock, only mock what you cannot control, such as calls to external APIs.”

For standard HTTP clients, most of us just nod and move on. But try applying that to a feature built around a Large Language Model, and it becomes the definitive answer to a testing problem I’d been circling for weeks.

An AI model isn’t a normal dependency. It’s slow, it costs money on every call, and—the part that really wrecks a test suite—it’s non-deterministic. Same input, different output. This usually leaves you with two bad options. Option A: Mock the entire pipeline, turning your tests into pure theater. They pass forever, asserting only that your own stubs were called, while real regressions walk straight through to production. Option B: Mock nothing, leaving you with a test suite that is flaky, painfully slow, and bills you on every CI run.

Evans’ rule puts the boundary exactly where it belongs. The model provider API is the only thing I cannot control, so it is the only thing I stub. Everything else runs for real: prompt assembly, the batching loop over long content, the context management that keeps terminology consistent across chunks, the state machine of the background job, and saving the final result. If I break the batching logic, a test fails. That’s exactly what tests are for.

I also learned two hard lessons by getting this wrong initially. First, stubbing the client isn’t enough—you also have to pin the exact payload it hands back. Otherwise, the non-determinism just moves one layer down and your assertions start drifting. Second, this testing style severely punishes heavy inline setup. Once I moved the sample AI context into fixtures, the specs became readable and just as fast as any other model test in our suite.

The same chapter states the trade-off plainly, and it’s a quote I’d gladly put on my wall:

“Slower, reliable tests are better than fast tests that break without reason (false positives) and don’t catch actual breakage (false negatives).”

“Zero” hits

Out of curiosity, I eventually ran a search across the entire ebook for the terms “LLM”, “AI”, and “ChatGPT”.

I found exactly one hit: a passing sentence about how users search for library documentation. As a guide for building AI features? Zero hits.

And that is the part I keep coming back to. This isn’t a book about AI, and that is precisely why it helped so much. A model provider is slow, occasionally unavailable, rate-limited, non-deterministic, and entirely outside your control. We already have decades of solid engineering practices for handling dependencies that behave exactly like that.

The only genuinely new thing is that AI failures are more convincing. A broken API simply returns a 503. A broken model returns a fluent, confident, and nicely formatted wrong answer.

The architectural boundary is exactly where it always was. It just matters a lot more now.

Who should read it

Intermediate and senior Ruby developers, without hesitation. If you’re still learning the syntax, learn it somewhere else first—this book assumes you already write Ruby and want to write it better.

And if you maintain any long-lived applications, Chapter 12 earns the read all on its own. Evans argues that features should be treated as liabilities rather than assets, since every single one of them carries a permanent maintenance cost. Therefore, removing a feature is a net gain. It’s the exact same conviction I wrote about a while back regarding removing legacy code, just stated much more sharply than I managed at the time.

Disclosure: Packt sent me a review copy of the book. The opinions here are entirely my own.

Image: “Pas(t)imes in the Computer Lab”, Hanna Barakat & Cambridge Diversity Fund. Better Images of AI, Creative Commons 4.0

Five resources and one strategy for Claude Certification

2026-07-06T00:00:00+00:00

For the past month, I’ve been preparing for the Claude Architect Foundations certification. The exam validates your knowledge of the Claude AI model, its architecture, and the best practices for building robust applications. Since any company aiming to complete the Claude Partner Network program needs a minimum number of certified architects, my team at JetRockets and I are preparing to take it soon. The exam is not free, so the goal is to pass on the first attempt.

The exam consists of 60 multiple-choice questions with a 120-minute limit. The syllabus is divided into five main areas: Agentic Architecture & Orchestration (27%), Tool Design & MCP Integration (18%), Claude Code Configuration & Workflows (20%), Prompt Engineering & Structured Output (20%), and Context Management & Reliability (15%). It tests both theoretical knowledge and practical skills — meaning hands-on experience with Claude and its ecosystem is essential.

Anthropic provides a study guide with recommended resources, including the official documentation and sample questions. Additionally, there are several online courses breaking down the objectives. I did some research, exchanged materials with colleagues also studying for the exam, and here are the resources I found most useful:

Official Antrophic courses: video, texts, and quizzes organized into specific learning paths, plus free courses on Claude and AI in general.
Claude Architect Foundations Study Guide: the official reference for example questions, in and out-of-scope topics, and exam preparation details.
Claude Certification Guide: a non-official website that I’m using to test my knowledge with mock exams and community discussions.
Claude Certified Architect - Foundations by freeCodeCamp.org: an excellent crash course video to complement the official materials and help you prepare for the exam.
Claude Certified Architect Study Guide (paullarionov): an open-source GitHub repository with a curated guide and additional study materials.

To prepare for the exam, I am not following a rigid, linear plan. Instead, I am dynamically alternating between the four required official courses, reading external articles, and practicing with mock questions. This flexible strategy is very similar to the one I used to pass the Google Associate Cloud Engineer certification some time ago.

That being said, there is a distinct difference between these two exams. The Google Cloud certification is extremely broad — it covers a massive landscape of services, expecting you to understand many topics without necessarily deep-diving into all of them. The Anthropic exam is the opposite. It has fewer main themes, but it requires you to go much deeper into concepts like agentic architecture, prompt engineering, and context management.

Despite this contrast, both exams share the same core philosophy: they are highly contextual. You won’t see questions asking for simple definitions. Instead, they give you a real-world problem and ask for the most appropriate solution.

For example, a typical question for the Anthropic exam looks something like this:

Example Question: You are designing a customer support agent using Claude that needs to check order statuses from a secure internal database. Which approach is the best way to handle this while maintaining security and efficiency?

A) Provide the database credentials in the system prompt so Claude can write and execute SQL queries directly. B) Provide a massive CSV export of the database in the context window. C) Create a Model Context Protocol (MCP) server that exposes a specific get_order_status tool, passing only the necessary parameters. D) Use a generic web-search tool to scrape the internal dashboard.

(The correct answer is C, because it uses the proper architectural pattern for tools and keeps credentials secure outside the model).

This means that simply reading the docs is not enough. You really need to think about the situation and understand why you are choosing a specific architectural pattern.

In the end, preparing for the Claude Architect Foundations is less about cramming documentation and more about adopting an agentic mindset — putting yourself in the shoes of an AI architect who is constantly balancing efficiency, security, and context limits to solve real-world constraints.

Image: Weaving Wires 1 by Hanna Barakat / AIxDESIGN / Better Images of AI, Creative-Commons License.

From Backend to MLOps: a runner’s road to business rules, deployments and monitoring

2026-06-06T00:00:00+00:00

By the end of last semester, I was preparing for a deep dive into deployments, monitoring, maintenance, and the operational crossroads where Backend meets DevOps. My goal was to bridge my previous cloud experience—especially with GCP—with the modern stack we rely on at JetRockets, such as Kamal, AppSignal, DigitalOcean, and Cloudflare. When the syllabus dropped for my second semester in the Artificial Intelligence program at UFRN, I was thrilled to spot MLOps (Machine Learning Operations) on the list. While the name might sound niche, MLOps is essentially the application of strict software engineering and DevOps principles to machine learning, ensuring models aren’t just local experiments, but are effectively deployed, monitored, and maintained in production.

Going in, I fully expected we’d immediately dive into server clusters, CI/CD pipelines, and configuration files. I’m glad I was wrong. The course actually kicked off with Design Thinking. It forced us to step back from the terminal and discuss the importance of understanding the business problem, the user, and the real-world context before throwing infrastructure at a problem.

To bring these concepts out of the classroom and into reality, I needed a concrete project. I chose running analysis—a domain I know deeply after nine years in the sport. While I already had the core math mapped out in an open-source gem, I wanted to build a complete system to test these operational practices in the wild. The ultimate result of this effort is Calcpace. Recently shipped to production, it is a fully-fledged web application offering running conversions, VO2 max estimates, race calendars, and pace predictions in 15 different languages. Under the hood, it serves as the perfect sandbox for merging backend and ML operations, powered by Ruby on Rails, PostgreSQL, Redis, Sidekiq, Kamal, AppSignal, DigitalOcean, and Cloudflare.

Here are some highlights of how the MLOps principles we studied mapped directly onto this project:

Design Thinking and the Cost of an Error: In ML, optimizing a mathematical metric means nothing if it doesn’t solve a user’s problem. For Calcpace, this meant studying existing market solutions and identifying exactly where runners struggle with pace and VO2 max calculations. It echoed the principles of Domain-Driven Design, by Eric Evans—you have to align your software architecture with the business reality. In a running app, a ‘bad prediction’ isn’t just a UI bug; it could mean an athlete pacing a marathon entirely wrong and hitting the wall.
TDD as a Pipeline Foundation: We revisited Test-Driven Development not just as a coding habit, but as a critical safeguard. Automated testing is the backbone of both standard software engineering and MLOps. In ML, you don’t just test if the code compiles; you test if the data schema is valid and if the model’s baseline performance holds. Solidifying the test suite for Calcpace was essential to ensure the core math remained completely reliable as new features were added.
The “Last Mile” of Model Serving with Rails: Ruby on Rails might not be the default choice for training models, but it is an exceptional tool for the “last mile”—delivering ML insights to the end user. My focus here isn’t on the mathematical training itself, but on building a robust, containerized environment using Kamal. By treating the complex logic (currently encapsulated in the Ruby Gem) as a decoupled service within a Rails/Docker stack, I’m ensuring that when we swap a heuristic for a complex predictive model, the infrastructure won’t blink. Furthermore, managing the latency of serving these predictions within the standard Rails request-response cycle is the real engineering challenge that separates a simple script from a production-ready system.

CI/CD and Workflow Automation: Continuous Integration and Deployment are non-negotiable. While the course explored ML-specific tracking tools like Weights & Biases alongside GitHub Actions, I focused on mastering the latter for workflow automation. Every time a new version is released, GitHub Actions runs the test suite and seamlessly triggers a Kamal deployment. It’s a closed loop that ensures the live application is always perfectly synced with the repository.
Beyond Uptime (Monitoring Data Sanity): The course introduced the LGTM stack (Looker, Grafana, Tempo, Mimir) for deep observability, which is standard for tracking infrastructure and data drift in ML. For the Calcpace ecosystem, AppSignal paired with Cloudflare serves as our equivalent. It provides fantastic out-of-the-box APM, tracking request latency and error rates. But an MLOps mindset demands more: we must monitor data sanity. If a runner’s VO2 Max prediction suddenly spikes to 99 due to a malformed input, our APM and strict validations help us catch that “silent failure” before it ruins the user’s trust.
Lean Infrastructure and Domain Management: We zoomed out to look at infrastructure as a whole—managing VMs, securing CI/CD secrets, and configuring scalable storage. In practice, this also became an exercise in cost efficiency. By leveraging Kamal’s container orchestration, I managed to pack the entire production stack—the Rails app, PostgreSQL database, and Sidekiq for async jobs—into a single $6/month DigitalOcean droplet without sacrificing the ability to scale later. Furthermore, establishing the production environment meant handling the custom .app domain registration and managing DNS and strict SSL configurations through Cloudflare, alongside setting up Cloudflare R2 for cost-effective, S3-compatible object storage.
DevOps in an AI-Scraped World: Finally, exposing an API or web app today means dealing with a massive influx of automated traffic. I configured custom WAF (Web Application Firewall) rules to block malicious actors while ensuring the site remains fully accessible to legitimate crawlers. This balance is vital for SEO and for ensuring the content is properly indexed by modern AI search bots.

Ultimately, the final deliverable for this discipline isn’t just a static repository; it’s a living, breathing product. By building Calcpace — and seeing its core open-source gem cross the 10,000 downloads milestone — it reinforced my conviction that a real challenge of a production-ready system lies in reliability, deployment pipelines, and operational monitoring.

Migrating Rails views to Jet UI: a guide with ViewComponent and Tailwind v4

2026-05-06T00:00:00+00:00

Last week, I wrote an article about migrating Calcpace views to use jet_ui to JetRockets blog. Here is the full article:

Maintaining a consistent UI in a growing Rails application is a classic challenge. We often start with the best intentions, clean HTML and utility classes, but as the app scales, we inevitably fall into “UI boilerplate fatigue.” Whether it’s copy-pasting the same “Avatar with initials” logic across dozens of views or reinventing the wheel for every animated toast, this duplication slowly erodes our development velocity.

To solve this, I recently migrated Calcpace, a running and cycling tracker built with Rails 8, to jet_ui, JetRockets’ component library. In this article, I’ll show you how we used Calcpace as a real-world playground to standardize our interface, leverage Tailwind CSS v4, and solve the production “gotchas” that often come with gem-based assets.

The Problem: Copy-Paste Debt

Before the migration, our UI was functional but repetitive. Handling profile pictures required manual conditional logic for avatars and initials in every view:

<%# Before: UI logic leaking into views %>
<% if current_profile.avatar.attached? %>
  <%= image_tag current_profile.avatar.variant(resize_to_fill: [24, 24]), class: "w-6 h-6 rounded-full" %>
<% else %>
  <div class="w-6 h-6 rounded-full bg-gray-200 flex items-center justify-center text-xs">
    <%= current_profile.initials %>
  </div>
<% end %>

This “inline Tailwind” approach lacks a single source of truth. Changing a border radius meant a tedious search-and-replace across the entire codebase.

The Strategy: Incremental Migration

One of the biggest concerns when adopting a component library is the “big bang” rewrite. Do you have to change every view at once? Absolutely not.

jet_ui is designed for incremental adoption. In Calcpace, we didn’t touch our legacy views initially. We started by replacing the most “noisy” elements—flashes and avatars—and then moved to complex data tables. You can have a page powered entirely by jet_ui components sitting right next to a legacy ERB view using plain Tailwind utility classes. They coexist perfectly because jet_ui respects your existing Tailwind configuration while providing the structure of ViewComponent. This removes the psychological barrier of migration: you can improve your app one component at a time.

Requirements and Plugging in Jet UI

jet_ui is built on ViewComponent and Tailwind CSS v4. It follows a “Rails-native” philosophy, leveraging the latest tools in the ecosystem:

Ruby >= 3.0 and Rails >= 7.0 (Calcpace runs on Rails 8.1).
Tailwind CSS v4 (via tailwindcss-rails >= 4.x).
Stimulus and Turbo (standard in modern Rails).

In your Gemfile:

gem "view_component"
gem "jet_ui"

The Power of Generators

One of jet_ui’s standout features is its suite of generators. They don’t just copy files; they wire up your entire application.

`jet_ui:install`

This sets up the library in your application (CSS + JS). It is safe to re-run after gem upgrades, as already-configured steps are automatically skipped:

rails generate jet_ui:install

`jet_ui:eject`

If you need to customize a component beyond standard options, you can “eject” it. This copies the Ruby class, ERB template, and Stimulus controller directly into your app/components/jet_ui/ folder. The ejected files take precedence automatically.

You can eject multiple components at once and use flags to keep your codebase lean:

# Eject button, card, and flash
rails generate jet_ui:eject btn card flash

# Skip specific files if you only want to customize the template
rails generate jet_ui:eject btn --skip-test --skip-preview
rails generate jet_ui:eject flash --skip-javascript

Production Readiness: The Vendoring Strategy

While the install generator works perfectly for local development by pointing to the gem’s path, production environments like Docker or CI require a more portable approach. To ensure a deterministic build and clean logs, we adopt a Vendoring strategy. Instead of relying on absolute filesystem paths that change between environments, we copy the CSS directly into the repository but place it outside the standard Rails asset search path to avoid duplicate serving.

Vendor the assets programmatically:

mkdir -p vendor/stylesheets
cp -r $(bundle show jet_ui)/app/assets/stylesheets/* vendor/stylesheets/

Update your Tailwind source file:

/* app/assets/tailwind/application.css */
@import "tailwindcss";
@import "../../../vendor/stylesheets/jet_ui.css";

Why this approach?

Portability: The build works in Docker, CI, and any developer’s machine without modifications.
Clean Logs: By placing files in vendor/stylesheets (which Propshaft ignores by default), the asset pipeline won’t try to serve individual component files (like popover.css). This prevents the “404 Not Found” noise in production logs for files already bundled into your main CSS.

Customizing the Theme with Tailwind v4

jet_ui uses modern CSS variables. Instead of overriding thousands of utility classes, you update the theme variables in your CSS source:

@theme {
  --accent-hue: 163;      /* Calcpace Emerald */
  --accent-chroma: 0.2;
  --accent-lightness: 0.52;
}

Every component, from buttons to focus rings, will now use your custom palette.

Replacing the Noise: Real-World Examples

Interactive Form Groups

We used jet_ui.group to standardize selectors. For our activity unit toggle (KM/MI), the component handles the styling and layout, leaving us with a clean DSL:

<%= jet_ui.group do %>
  <%= form.radio_button :unit, "km", checked: true %>
  <%= form.radio_button :unit, "mi" %>
<% end %>

Advanced Composition: Tables and Tabs

The World Records page was our “stress test” for displaying dense data. By composing tabs, card, and table, we reduced a complex view to a readable DSL:

<%= jet_ui.tabs do %>
  <%= jet_ui.tabs_item "KM", href: records_path(unit: "km"), active: @unit == "km" %>
  <%= jet_ui.tabs_item "MI", href: records_path(unit: "mi"), active: @unit == "mi" %>
<% end %>

<%= jet_ui.card class: "overflow-hidden" do %>
  <%= jet_ui.table hovered: true do %>
    <%= jet_ui.table_thead do %>
      <%= jet_ui.table_tr do %>
        <%= jet_ui.table_th { "Event" } %>
        <%# ... %>
      <% end %>
    <% end %>
  <% end %>
<% end %>

This composition proves the architectural leverage: we get a professional data grid with integrated navigation, all following the same design system with zero manual CSS.

Why jet_ui? (The Alternatives)

You might ask: “Why not just use Flowbite, shadcn-rails, or RailsUI?”

While those are great tools, they occupy different niches. Flowbite is fantastic for Tailwind-first projects but isn’t built as a first-class ViewComponent library, often requiring you to wrap their HTML yourself. shadcn-rails follows the “copy-paste” philosophy which is great for total control, but lacks a clean, gem-based upgrade path for those who want their design system managed as a dependency. RailsUI is a premium, template-oriented solution that is excellent for rapid prototyping but might feel too opinionated for existing apps.

jet_ui sits in the “Goldilocks” zone: it’s ViewComponent-native, Tailwind v4-native, and gem-distributed with an “eject-on-demand” safety valve. You get the maintenance benefits of a gem with the flexibility of local code when you need it.

Conclusion: Architectural Leverage

Migration isn’t just about “fancy” code. It’s about reducing cognitive load. Developers can focus on building features using high-level components rather than wrestling with low-level utility classes in every single view. If you’re building a modern Rails app, jet_ui is the bridge between the flexibility of Tailwind and the structure of a professional design system.

Calcpace: open beta, maps, bot protection and a growing gem

2026-04-06T00:00:00+00:00

Calcpace.app is now open to anyone — no invite code needed. This post covers what changed since the closed beta: new gem modules, GPS tracking with maps, bot protection, the infrastructure decisions behind each feature, and a few lessons learned the hard way.

The calcpace gem is a pure Ruby library — no I/O, no Rails, no external dependencies. Every formula lives in its own module, included into the main Calcpace class. The site consumes it as a regular gem dependency; when a new module ships, the site updates the Gemfile and builds on top of it. Since v1.8, three modules were added.

CameronPredictor — an exponential race prediction formula that runs alongside the existing Riegel predictor (T2 = T1 × (D2/D1)^1.06). Cameron tends to be more conservative than Riegel for shorter base distances, which matters when you’re predicting a marathon from a 5K time. Having both lets you compare and pick the more realistic estimate for your training context.

TrackCalculator — GPS math: Haversine distance between coordinate pairs, cumulative elevation gain, and per-km splits from an array of raw trackpoints. Pure calculation — no map rendering, no file parsing. The module receives coordinates and returns numbers; the site handles everything else.

Vo2maxEstimator — Daniels & Gilbert formula. Given a race time and distance, returns an estimated VO2max and a fitness classification (from “Poor” to “Elite”). The gem API convention applies here: inputs use symbols (:km, :mi), outputs are always strings — never symbols.

The GPS flow on the site: when a user uploads a GPX file, Active Storage saves it to Cloudflare R2 and enqueues GpxParseJob to Sidekiq. The job runs GpxParser, which extracts trackpoints (lat, lon, elevation, time), then calls TrackCalculator from the gem to compute distance, elevation gain, and splits. Trackpoints are persisted and the activity is updated with the computed stats. The map renders with Leaflet.js and OpenStreetMap tiles — no API key, no vendor lock-in, no usage limits.

Moving from invite-only to open registration meant adding real bot protection. The approach: Cloudflare Turnstile on the registration form, Rack::Attack for rate limiting at the Rails level. Turnstile was straightforward to integrate, with two gotchas that cost more time than expected. The widget script URL uses /v0/, not /v1/ — the docs aren’t always consistent about this. And the form param is cf-turnstile-response (hyphens), not cf_turnstile_response (underscores) — Rails’ params hash keeps hyphens, so the usual convention doesn’t apply. There’s also a pending issue: when the registration form reloads after a validation error, Turbo replaces the DOM but doesn’t re-initialize the widget, so the next submission fails silently. The fix is re-initializing after a Turbo render — still pending.

For file storage, Active Storage with Cloudflare R2 as the backend handles avatars, activity photos, and GPX files. S3-compatible, free egress within Cloudflare’s network, no CDN configuration needed.

Rails 8 ships generates_token_for as a first-class model API for signed, expiring tokens. The email verification flow uses it: on registration a token is generated with 48h expiry, the verification email includes a signed URL, and unverified accounts are blocked from logging in with a resend option shown. The verification email is HTML now — styled with a button and a copyable fallback link. Before this it was plain text, which looked unfinished for an open product. Transactional emails go through Resend API; the password reset flow was already using it and verification plugged into the same setup.

Every user gets a public profile at calcpace.app/:username — avatar, bio, city, country, and activity feed. Each activity has an individual public boolean: toggle it on the activity form and it appears or disappears from the public feed immediately. Activities can also have a photo attached. Your profile page only shows what you choose to share.

The clearest architectural decision in this project: the gem does pure calculation, the site does I/O. No file parsing in the gem, no HTTP, no database. This makes the gem testable in isolation (Minitest, no Rails required) and keeps the site thin — controllers call gem methods and persist results, nothing more. The delivery sequence is always: implement module in gem → write tests → publish new version → update Gemfile in site → build the UI on top. GitHub Actions publishes to RubyGems automatically on version bump in lib/calcpace/version.rb.

What’s next: internationalization first — the app is English-only for now, but the i18n infrastructure is already in place. Adding PT-BR, Spanish, German, and French means auditing hardcoded strings, migrating GpxParser error messages to i18n keys, and translating the emails. Then content pages: pace conversion tables, race equivalent tables, Boston qualifying times, world records. Mile splits in the activity view are also coming — the gem already supports it via track_splits(points, 1.609), the UI just needs a toggle. Strava and Garmin direct connection is planned — GPX import already works for the manual export flow, the next step is OAuth2 for automatic sync.

Image: “BP Running Track @ Glasgow Airport” by JCDecaux Creative Solutions. Open Verse, Creative Commons BY-NC-ND 2.0

Calcpace Web: the calculator now in the browser

2026-03-26T00:00:00+00:00

The calcpace gem just hit 7,000 downloads, so I celebrated the best way I know how: I ran a 5k and finally built calcpace.app to bring those calculations to everyone, no Ruby console required.

The core logic for this project has actually been brewing in my head for about five years. Combining my daily routine as a runner with the logic I apply professionally when building delivery and routing systems, it just made perfect sense to model pace, distance, and time mathematically. I eventually sat down and started writing the core Ruby code four years ago, which evolved into the open-source gem.

When the gem crossed the 7k mark, I realized it was time to make it accessible to non-programmers.

The app provides a suite of free running tools: pace, speed, finish time, split breakdowns, and a race predictor using both the Riegel and Cameron formulas. The converter covers 30 combinations across distance, speed, and pace—km, mi, meters, yards, feet, knots—all easily switchable between metric and imperial systems.

I didn’t want it to be just another “enter your numbers” calculator. There are dedicated guide pages explaining the math behind each formula. For instance, you can read about why the Cameron predictor tends to be more conservative than Riegel for shorter base distances, and what that actually means for your training blocks.

From planning to writing the code and setting up the infrastructure, the web version took me about four days. I used this as an opportunity to build with a modern, pragmatic stack:

Ruby on Rails 8: The foundation of the app. It provides a solid structure and allows me to practice “dogfooding” by consuming my own gem in a production environment. The gem does all the heavy lifting for the calculations, keeping the Rails controllers incredibly clean.
The Basecamp Way: I treated this project as a playground to strictly follow 37signals’ design principles. That means pushing the logic down to rich models, keeping controllers thin, and leveraging Current attributes to handle global state cleanly.
Tailwind CSS: To keep my focus on the backend and infrastructure, I used Tailwind to rapidly build a clean, responsive interface without writing custom CSS files.
Testing & CI/CD: Since this serves as a live environment for the gem, reliability is key. The app is fully tested with Minitest, and GitHub Actions runs the CI/CD pipeline on every push to main.
Kamal & VPS: I wanted to step away from traditional, expensive PaaS solutions. I deployed the application using Kamal, which packages the Rails app into Docker containers and handles zero-downtime deployments directly to a DigitalOcean Virtual Private Server (VPS).

Take it for a spin

While the personal activity tracker (run/ride logging) is technically in closed testing, I built a sandbox and share with some friends so they can explore the UI and see the gem working in a real database environment.

To keep things tidy, a GuestResetJob runs via sidekiq-cron to wipe the guest activities and recreate the sample profile every Monday at 3 AM.

What’s Next

The engine is running smoothly, but there’s more to come. I am currently working on adding VO2max, VDOT, and training zone calculations—these will be introduced as new modules in the gem and will get their own guide pages on the site.

Links:

Building Semantic Search with AI and Vector Embedding in Rails

2026-02-26T00:00:00+00:00

This month, I wrote an article on building semantic search with vector embeddings in Ruby using the ruby_llm gem and PostgreSQL’s pgvector extension to JetRockets blog. Here is the full article:

Traditional keyword search is fundamentally limited—it can only match exact words or their basic variations. Search for “customer pain points” and you’ll miss documents titled “User Frustrations” or “Client Challenges,” even though they’re semantically identical. This limitation becomes critical when managing large document repositories where users need to find information based on meaning, not memorized keywords. The solution is semantic search using vector embeddings, which represent text as mathematical vectors that capture conceptual similarity. In previous articles, we explored how ruby_llm simplifies working with AI providers for function calling and resilient architectures. Now we’ll leverage ruby_llm’s embedding capabilities to build semantic search with PostgreSQL’s pgvector extension—creating a system that finds “churn analysis” when users search for “why customers leave.”

What Are Vector Embeddings?

Think of vector embeddings as a way to translate text into the language of mathematics—or as some describe it, “searching by vibes” rather than exact keywords. Each piece of text becomes an array of numbers (a “vector”) where similar meanings produce similar numbers. The embedding model has learned, through training on billions of texts, that certain concepts cluster together in this mathematical space.

We’ll use OpenAI’s text-embedding-3-small (1,536 dimensions) for its solid performance-to-cost ratio, but ruby_llm also supports other models: Gemini’s text-embedding-004 (768 dimensions), Voyage AI’s models, or even local alternatives like all-MiniLM-L6-v2 via Ollama for privacy-sensitive applications. The choice depends on your budget, latency requirements, and whether you prefer cloud or self-hosted solutions.

For example:

“customer churn analysis” → [0.234, -0.891, 0.456, ...]
“user retention study” → [0.221, -0.883, 0.449, ...] (very close!)
“quarterly revenue report” → [-0.678, 0.234, -0.123, ...] (very different)

When a user searches for “why are customers leaving”, the system converts this query into a vector and finds documents with similar vectors—automatically surfacing reports about “churn factors” and “cancellation reasons” without requiring exact keyword matches.

Setting Up ruby_llm for Embeddings

Just as we used ruby_llm for function calling in our previous article, we can use it for embeddings too. The gem provides a unified interface with consistent error handling and automatic retries:

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

RubyLLM.configure do |config|
  config.openai_api_key = Rails.application.credentials.dig(:openai, :api_key)
end

# Create a reusable client instance
LLM_CLIENT = RubyLLM

Now create a wrapper that handles the embedding API calls:

# app/services/embedding_service.rb
class EmbeddingService
  MODEL = "text-embedding-3-small"
  DIMENSIONS = 1536

  def self.embed(texts)
    texts = Array(texts)
    return [] if texts.empty?

    # ruby_llm handles the API call automatically
    result = LLM_CLIENT.embed(texts, model: MODEL, dimensions: DIMENSIONS)
    result.vectors
  end
end

That’s it! Using ruby_llm gives us the same benefits we saw in the function calling article: provider abstraction, automatic error handling, and consistent behavior across different AI services.

Setting Up pgvector for Storage

Why pgvector? If you’re already running PostgreSQL (and many Rails apps are), pgvector lets you store and search vectors without adding new infrastructure. No separate vector database to maintain, no data synchronization issues, and transactions work normally—your embeddings live right next to your application data. The pgvector extension adds specialized vector types and HNSW indexing for sub-100ms similarity searches across millions of vectors.

Before storing embeddings, enable the extension:

# db/migrate/create_documents.rb
class CreateDocuments < ActiveRecord::Migration[8.0]
  def change
    enable_extension "vector"

    create_table :documents do |t|
      t.string :title, null: false
      t.text :content, null: false
      t.references :user, null: false, foreign_key: true
      t.timestamps
    end

    create_table :document_chunks do |t|
      t.references :document, null: false, foreign_key: true
      t.integer :chunk_index, null: false
      t.text :content, null: false
      t.vector :embedding, limit: 1536
      t.timestamps
    end

    # HNSW index for fast nearest-neighbor search
    add_index :document_chunks, :embedding, using: :hnsw, opclass: :vector_l2_ops
  end
end

The HNSW (Hierarchical Navigable Small World) index creates a graph structure that allows fast approximate nearest-neighbor search—essential for sub-100ms queries across thousands of vectors.

Basic Pattern: Chunking Documents

Here’s the challenge: documents can be very long, but embedding models work best on focused text segments (500-2000 characters). Embed an entire 50-page document and you’ll get a diluted embedding that doesn’t capture nuances. The solution is chunking with overlap. The overlap (typically 10-20%) prevents losing context at boundaries:

# app/models/document.rb
class Document < ApplicationRecord
  CHUNK_SIZE = 1_000
  OVERLAP_SIZE = 200

  has_many :document_chunks, dependent: :destroy

  def generate_chunks!
    step = CHUNK_SIZE - OVERLAP_SIZE
    chunks = []

    # Split content into overlapping chunks
    0.step(content.length - 1, step) do |offset|
      chunk = content[offset, CHUNK_SIZE]
      chunks << chunk if chunk.present?
    end

    return if chunks.empty?

    # Generate embeddings for all chunks in one call
    embeddings = EmbeddingService.embed(chunks)

    ActiveRecord::Base.transaction do
      document_chunks.destroy_all

      chunks.zip(embeddings).each_with_index do |(chunk, embedding), index|
        document_chunks.create!(
          chunk_index: index,
          content: chunk,
          embedding: embedding
        )
      end
    end
  end
end

Notice how we generate embeddings for all chunks in a single call. Instead of making 50 separate API requests for a 50-chunk document, we make just one. The ruby_llm gem handles the batching automatically, just like it does with function calling.

The character-based approach above works, but cutting mid-sentence degrades semantic meaning. A better strategy splits on sentence boundaries using text.scan(/[^.!?]+[.!?](?:\s+|$)/), accumulating sentences until reaching the size limit. This preserves complete thoughts while maintaining consistent chunk sizes—particularly valuable for technical documentation where sentence context matters.

Advanced Pattern: Hybrid Scoring (Semantic + Temporal)

Pure semantic search has a problem: outdated documents with perfect semantic matches outrank recent documents with good matches. When users search for “current market size”, they might get a 2023 report instead of the fresh 2025 one. The solution is hybrid scoring—combine semantic similarity (70%) with recency (30%):

# app/models/document_chunk.rb
class DocumentChunk < ApplicationRecord
  belongs_to :document
  has_neighbors :embedding, dimensions: 1536

  attr_accessor :search_score

  def self.search_by_semantics(query, user:, limit: 20, threshold: 0.8)
    # Convert query to embedding using ruby_llm
    query_embedding = EmbeddingService.embed(query).first

    # Get more candidates than needed for scoring
    neighbors = joins(:document)
                  .where(documents: { user: user })
                  .nearest_neighbors(:embedding, query_embedding, distance: "cosine")
                  .limit(limit * 5)

    # Calculate hybrid scores
    scored_neighbors = neighbors.map do |chunk|
      semantic_similarity = 1 - (chunk.neighbor_distance / 2.0)
      recency_score = calculate_recency_score(chunk.created_at)

      # 70% semantic, 30% recency
      chunk.search_score = (semantic_similarity * 0.7) + (recency_score * 0.3)
      chunk
    end

    # Filter and return top results
    scored_neighbors
      .select { |c| c.neighbor_distance < threshold }
      .sort_by { |c| -c.search_score }
      .first(limit)
  end

  def self.calculate_recency_score(created_at)
    age_in_days = (Time.current - created_at) / 1.day
    return 1.0 if age_in_days <= 30  # Recent: full score
    return 0.7 if age_in_days > 365  # Old: 30% penalty
    1.0 - ((age_in_days - 30) / 335.0) * 0.3  # Linear decay
  end
end

The key insight: we fetch limit * 5 candidates first, then score and filter. Why? A chunk might be the 50th-best semantic match but jump into the top 5 after adding recency. By casting a wider net initially, we don’t miss valuable recent documents.

Putting It All Together

Now let’s see the complete flow from upload to search:

class DocumentsController < ApplicationController
  def create
    document = current_user.documents.create!(
      title: params[:title],
      content: params[:content]  # or extract from uploaded file
    )

    # Generate chunks and embeddings asynchronously
    GenerateEmbeddingsJob.perform_later(document.id)

    render json: { id: document.id, status: "processing" }
  end

  def search
    results = DocumentChunk.search_by_semantics(
      params[:query],
      user: current_user,
      limit: 10,
      threshold: 0.75
    )

    render json: {
      query: params[:query],
      results: results.map do |chunk|
        {
          document_title: chunk.document.title,
          excerpt: chunk.content[0..300],
          relevance_score: chunk.search_score.round(2)
        }
      end
    }
  end
end

The architecture is completely asynchronous where it matters. Document uploads don’t block waiting for embeddings—users get immediate feedback, and embeddings are generated in the background. Meanwhile, searches are fast (typically under 100ms) because pgvector’s HNSW index does the heavy lifting.

Advantages of This Approach

The benefits go far beyond “better search.” The system demonstrates semantic understanding—users can search for “why customers switch providers” and find reports titled “Competitive Migration Patterns,” even though those exact words don’t appear in the query.

From an engineering perspective, the architecture is production-ready: context preservation through overlapping chunks means no information is lost at boundaries, temporal awareness via hybrid scoring ensures recent insights aren’t buried, and ruby_llm provides the same advantages we explored in previous articles—automatic retry logic, consistent error handling, and clean abstractions for AI interactions.

When to Use Semantic Search

Semantic search shines when users need to find documents by meaning rather than exact keywords—scenarios like customer support knowledge bases, research archives, or legal document discovery where synonyms and conceptual similarity matter. It’s especially valuable powering AI features: chatbots citing documents, assistants surfacing relevant research, or agents (using ruby_llm’s function calling) that search intelligently.

However, skip it for small document sets (<100 documents) with well-structured content, cases requiring exact phrase matching (legal contracts), or real-time updated content where the 1-2 second embedding latency is problematic. Traditional keyword search with proper indexing often suffices for simpler use cases.

Best Practices

Through implementing semantic search systems, several best practices have emerged:

Always Use Overlapping Chunks: The 200-character overlap prevents context loss at boundaries. Resist the temptation to eliminate overlap to save on storage—it’s a false economy that degrades search quality.

Batch Your Embeddings: Generate embeddings for all chunks in a single call to EmbeddingService.embed(chunks). Process 20-chunk documents with one request instead of 20, reducing latency by 95% and API costs proportionally.

Tune Thresholds Per Use Case: The 0.8 default threshold works for most cases, but use 0.85 for mission-critical searches (where precision matters) and 0.75 for exploratory searches (where recall matters). Monitor your analytics and adjust accordingly.

Async Everything That Can Be Async: Never block user requests waiting for embeddings. Generate them in background jobs and show a “processing” indicator. Users can continue working while documents are indexed.

Conclusion

Transitioning from keyword-based to semantic search transforms how users interact with your data, and as we’ve seen, it doesn’t require adopting entirely new infrastructure. By keeping our architecture resilient with PostgreSQL and pgvector, we avoided the overhead of maintaining a separate vector database. We then used ruby_llm to abstract the complexity of interacting with AI providers, ensuring our API calls are batched and fault-tolerant.

Finally, we solved the real-world UX challenges of AI search by implementing overlapping text chunks to preserve context, and hybrid scoring to balance semantic accuracy with temporal relevance. The magic of modern AI tools in the Rails ecosystem is that they allow us to build highly sophisticated features—like “searching by vibes”—while relying on the same pragmatic, robust engineering principles we use every day.

Additional Resources

📄 Embeddings: What they are and why they matter by Simon Willison
📄 What are embeddings? by Vicki Boykis
📁 pgvector GitHub Repository
📁 neighbor gem for Rails
📁 ruby_llm gem on GitHub

Image: “Word Search” by Morgan Frederick. Open Verse, Creative Commons 2.0

A City Called Christmas

2025-12-24T00:00:00+00:00

Tomorrow will be Christmas in many parts of the world, but there is a city where it has been Christmas every day since 1599. This is Natal, my hometown, a name that means exactly “Christmas” in Portuguese.

It boasts beautiful beaches, dunes, wind, marvelous food, and a strategic position as one of the closest points in the Americas to Africa and Europe. The area was originally inhabited by the Potiguar indigenous people. Then, during the Age of Discovery, the Portuguese established a fort and a city. After some decades, it passed into Dutch hands before returning to the Portuguese until Brazil’s independence. During World War II, this was considered one of the four most strategic places in the world, hosting the largest airbase for the Allies. However, today is not a day to talk about wars.

Over time, this city has embraced diverse Christmas traditions. The end of the year is the height of Summer in South America, so forget winter clothes and snow; imagine beaches and parties with happy people. But some traditions remain. Natal has a Christmas tree made of light that is 20 meters taller than the Statue of Liberty in New York. It illuminates the night with dynamic, ever-changing colors in a city that has been Christmas every day for the last four centuries.

Cat vs. Dog: A Machine Learning Experiment

2025-12-07T00:00:00+00:00

“Cat vs. Dog” is the “Hello World” of Computer Vision. But solving it is one thing; understanding the mathematical and statistical foundations behind the solution is another.

For my final project in IMD3002 - Supervised Machine Learning at Artificial Intelligence program at UFRN, instructed by Prof. João Carlos Xavier Junior, I didn’t just trained models. We build a complete, rigorous scientific framework to test the fundamentals of Machine Learning.

Here is how I broke down the workflow into a series of sequential experiments.

The Objective

The goal was to classify images of specific breeds (Miniature Pinscher/English Setter vs. Birman/Ragdoll) by exercising every fundamental stage of a classic ML pipeline: from raw pixels to statistical validation.

Step 1: Feature Extraction (Beyond Pixels)

Raw images are noisy and high-dimensional. To make them digestible for classical algorithms, I implemented two distinct visual descriptors:

HOG (Histogram of Oriented Gradients): To capture the shape and edge structures.
LBP (Local Binary Patterns): To capture the texture of the fur.

Step 2: Dimensionality Reduction

With high-dimensional feature vectors, the “Curse of Dimensionality” becomes a real threat. I applied PCA (Principal Component Analysis) to project the data into a lower-dimensional space, balancing computational efficiency with information retention.

Step 3: Model Training & Tuning

I implemented and compared five distinct classes of algorithms to see how they handled the visual data:

k-NN: Instance-based learning.
Naive Bayes: Probabilistic modeling.
Decision Trees: Rule-based learning.
MLP (Multi-Layer Perceptron): Neural Networks.
Ensembles: Random Forest, AdaBoost, Voting, and Stacking.

Each model underwent rigorous hyperparameter tuning (GridSearch) to ensure we were comparing the best versions of each.

Step 4: Statistical Evaluation

This is where many projects stop, but scientific rigor requires more than just comparing average accuracy. I applied the Friedman Test to determine if the differences in performance were statistically significant and the Nemenyi Post-hoc Test to pinpoint exactly which models outperformed the others.

The Verdict

The statistical analysis revealed that for this specific dataset, an MLP combined with LBP features offered the best trade-off between predictive power and computational cost, significantly outperforming shape-based approaches (HOG).

You can explore the full step-by-step workflow, organized in sequential Jupyter Notebooks, on my GitHub: https://github.com/0jonjo/cat_dog_ml

Image: “Ai is… Banner”, Rick Payne and Team. Better Images of AI, Creative Commons 4.0

Building Robust AI Agents with Ruby_LLM

2025-11-15T00:00:00+00:00

I’ve been busy writing this month and wanted to share two new technical posts I published over on the JetRockets blog. Both are focused on building more capable and reliable AI applications in Ruby, and they complement each other well.

First up: Building Intelligent AI Agents with Function Calling in Ruby

This post dives into one of the most exciting features of modern LLMs: Function Calling (also known as Tool Calling). This is what elevates a model from a simple text generator into an intelligent agent that can interact with real-world data and services.

In the article, I explore how you can use the ruby_llm gem to give your AI “tools” it can use to:

Access real-time, external data (like calling a live weather API).

Enforce your own internal business logic (like checking a user’s membership status before granting access).

Extract structured JSON data directly from a user’s request (for example, turning “a 3-day trip to Tokyo” into a structured itinerary).

If you’re looking to build an AI that can do things rather than just talk, this post is for you.

Check it out here: https://jetrockets.com/blog/building-intelligent-ai-agents-with-function-calling-in-ruby

Next: Building a Resilient AI Client in Ruby with Stoplight and ruby_llm

Calling external AI services is powerful, but what happens when those services are slow, return errors, or go down completely? This post is all about building a resilient client that can handle these inevitable failures gracefully.

I introduce the Circuit Breaker pattern and show how to implement it using the stoplight gem. The core idea is to build a system that can:

Detect when a specific AI provider (like GPT-4o) is failing.

“Trip a circuit” to temporarily stop sending requests to that failing service.

Automatically and seamlessly failover to a backup model (like Gemini or a different GPT model), preserving the conversation history.

This one is all about ensuring your application remains stable and fault-tolerant, even when its external dependencies are having a bad day.

You can read the full post here: https://jetrockets.com/blog/building-a-resilient-ai-client-in-ruby-with-stoplight-and-ruby_llm

Together, these two articles provide a solid foundation for building AI applications in Ruby that are not only intelligent but also robust and reliable. I hope you find them useful!

Image: “Weaving Wires 2 by Hanna Barakat & Archival Images of AI + AIxDESIGN”. Better Images of AI, Creative Commons 4.0

Immersing in AI: Notes from a Developer Studying Machine Learning, Ethics and Data

2025-09-22T00:00:00+00:00

This semester, I chose Supervised Machine Learning and Ethics and Data as my first courses in the Artificial Intelligence program at UFRN. The first deals with algorithms that learn from examples, covering everything from data collection, systematization, and adjustments to the construction of decision trees and artificial neural networks. The goal is that, by the end of the semester, we’ll be able to build predictive models from real datasets. For example, a machine could receive a patient’s exam data and predict whether or not they have a predisposition to a certain disease. The second course, on the other hand, covers the historical, philosophical, and legal dimensions of using data and algorithms, including topics like bias, privacy, transparency, and responsibility.

In these first few months of the program, I’ve drawn several connections to the backend work I’ve been doing over the last few years, especially with the AI projects I’m working on at JetRockets. Some of these connections relate to mathematical questions; others, to methods for adjusting data sent to and received from AI models; and some deal directly with ethics and privacy.

Here are the main connections I’ve observed:

Communicating with external systems and models: A common aspect of large backend projects is integration with various third-party systems via queues, APIs, and webhooks. Beyond the purely technical details, this communication requires developing abstractions that can produce and consume information designed for other business rules—for example, payment gateways, ERP systems, and CRMs. The combination, smoothing, and transformation of data from different sources is a constant challenge.

In Machine Learning, during the training that gives rise to models, we study and practice how to interpret and prepare data from various sources for use in training and testing. It’s necessary to understand the format, structure, and meaning of the data, as well as to identify and handle potential problems like missing values, inconsistencies, and noise.

Something similar occurs when communicating with AI models via API (like Claude, OpenAI, and Gemini): you need to interpret and prepare the input and output data to ensure it’s in the correct format and meets the model’s requirements. In both cases, a thorough understanding of the data and system needs is essential for effective communication.

Understanding vectorization: In AI projects, vectorization is the process of transforming data into numerical vectors so it can be processed by machine learning algorithms. This is especially important when working with unstructured data like text and images. Vectorization allows algorithms to extract relevant features and facilitates analysis and decision-making.

In backend projects, vectorization can also optimize data storage and querying, particularly when working with large volumes of information. Understanding its concepts and techniques has been fundamental in the projects I’m involved in; studying and practicing them has been an important part of my AI learning journey.

Normalizing data: Various data merging, comparison, and transformation processes involve normalization—adjusting values to a common scale without distorting differences in value ranges. This ensures data is handled consistently, especially in scale-sensitive algorithms.

In Machine Learning, normalization is a crucial data preprocessing step that improves the performance and convergence of algorithms. In AI projects, steps like preparing data for RAG (Retrieval-Augmented Generation) also involve normalization to meet model requirements. For this reason, it has been useful to revisit concepts like mean, median, mode, variance, and standard deviation, applying them in both my coursework and the AI projects I’m developing.

Understanding and Controlling Bias in Data and Algorithms: bias refers to the political, social, or gender inclinations present in data sources. They can have historical and cultural roots or be a product of conscious or unconscious human decisions. They influence everything from the improper selection of data to the unequal representation of different groups.

In Machine Learning, controlling bias is a constant concern, as it can lead to unfair or inaccurate results, especially when working with sensitive data. Bias control also appears in the preparation of prompts for AI models, where it’s necessary to ensure the model’s response is appropriate for the query, often by mitigating undesirable biases. I’ve been studying techniques and strategies to identify, mitigate, and control biases, ensuring fairer, more transparent, and responsible models.

Managing Private Data: when dealing with personal and sensitive information, ensuring data privacy and security is essential. This involves adopting practices and technologies to protect against unauthorized access, leaks, and misuse.

In the relationship with AI models, managing private data is a constant concern. It is also critical to ensure compliance with privacy laws and regulations, such as the LGPD in Brazil. I have been studying legislation and best practices, adopting techniques and strategies to protect data privacy with secure and responsible approaches.

Image: “Mergulho” de Anderson Freire. Open Verse, Creative Commons 2.0

The Potters of the Unknown

2025-08-26T00:00:00+00:00

Sensations and memories are sometimes unexpected and welcome guests, like the taste of a dish that brings back the shiver on your skin from contact with the sea water, or a song that escapes from a random window in the middle of the night and takes you back to a beloved place. These days, because just started the courses of the Associate’s degree in Artificial Intelligence (UFRN) with Supervised Machine Learning. I’ve returned to the Python programming language. Well, the first time I wrote something in this language was a years ago, back when I was just starting to learn how to program. So, these past few days, I’ve been working on small programs like someone trying to draw with a pen long forgotten at the bottom of a drawer. I’ve gone back to the path of the apprentice.

Between tests and searches for the exercises, I remembered how everything seemed hazy back then. Today, even though I don’t master the language, I have a more solid foundation and can grasp the basics of what to do in each situation. Before, as is typical of someone just starting out, the challenge was often not just making something work, but understanding why it worked or didn’t. Between one line of code and the next, I’d risk a new option and get a red error on the screen. Then I’d ask more experienced friends or search online for a solution and adapt the varied answers to what I intended to do. Key concepts for understanding the context and how everything worked were still forming, so every step was uncertain.

Learning is the challenge of shaping the unknown, like a potter making a jar from clay. Depending on your age, you might be thinking of that classic scene from the movie Ghost (1990) with the couple making a crooked clay pot together, but I’m serious. Learning isn’t simply accumulating theoretical and practical knowledge in a shopping bag; it’s refining the technique through which we organize and use what we know. And it’s certain that there’s no stopping point in this art of learning; there’s always something new to discover and test. Not to stray from the topic, it’s worth remembering an anecdote about Pablo Picasso. When he was older, he visited potters in the small French town of Vallauris. The painter was so captivated by the clay, the potter’s wheel, and the colors on the ceramics that he lived in the town for seven years and produced thousands of pieces over twenty years. In two decades, his hands as a painter and draftsman gained the strength and skill of refined potters who pull forms from clay that previously only existed in the world of ideas. For that to happen, of course, there was an uncountable number of vases, plates, sculptures, and other pieces that his hands distorted, clumps of clay that were ruined as he learned or invented new forms.

Among the first courses I took, Python for Zombies by the competent and good-humored professor Fernando Masanori caught my attention. The focus is on introducing new people to the world of programming, which was exactly what I was looking for at the time. Throughout the videos, in various situations of a screen error after a command, he’d let out one of his mantras: “I am happy; I will learn more.” Beyond the discontent we all feel when we make a mistake, Masanori points out that getting it wrong gives us the opportunity to expand our knowledge. His perspective is that of someone who knows what learning is all about, of someone who seeks to understand the mistake to get around it, refining their technique and adjusting their course. The joy with which he says this might sound naive and unrealistic at first. At the time, I myself looked at the screen and weighed my situation: thirty years old, eleven years studying History, just a few months away from becoming a father, over 300 students’ exams to correct, and this guy tells me to be happy for making a mistake. Honestly, I must have thought a bad word and maybe moved the mouse pointer to close the window. But something there captured me; the page stayed open.

Months passed, I finished that introductory course, then another, and I kept changing technologies as I was introduced to them. I continued to share what I was learning with people close to me, also on social media and in blog posts. One of my friends, Brenno, asked me at some point what it was like to explore something totally outside of what I knew. I don’t know exactly what words I said at the time, but the feeling was a mix of satisfaction and curiosity that we get with new discoveries. With several years of teaching and various degrees stored in a folder, I was once again experiencing the joy of not knowing, of being able to make mistakes freely and gradually discovering the world. Of being hit by the comprehension of a concept while taking a shower, of waking up early to work on a solution to problem X at my fingertips, of discovering something and commenting to myself: “Wow, that was there the whole time.” Going back to the Python exercises reminded me of the happiness of the apprentice that I experienced a few years before, that the sparkle in our eyes from discoveries is not just a right for children and teenagers, but for all those willing to learn.

Image: “Free person making handmade pottery”. Open Verse, Creative Commons 1.0

Updating Calcpace with Gemini CLI

2025-07-05T00:00:00+00:00

A few weeks ago, the first public releases of Gemini CLI were launched. I was curious to try out Google’s solution for generative AI in the command line, similar to Claude Code or OpenAI CLI. I wanted to see it in action with a real project, so I decided to work on the next update of my gem Calcpace with it. It’s a project about calculations and conversions of distance, time and velocity that has more than 3,400 downloads on RubyGems.

Installing Gemini CLI in Ubuntu is straightforward - just follow the instructions in the README. After that, you can use the gemini command to interact with the Gemini AI model. When using it for the first time, you need to authenticate with your Google account and set some simple configurations like theme. Currently, the CLI is free, but the model utilized is the powerful Gemini 2.5 Pro, which is the same one used in other Google paid products.

I did all work inside my Calcpace project directory, and my initial good impression was that it automatically and quickly read all the project files and directories. As suggested in the documentation, I asked the AI to summarize the project, and it returned the main features, version, and license of the gem in a short and accurate summary. After that, I asked for a more detailed analysis of the codebase, and it provided a good overview of the main classes and methods. Then I requested it to identify potential improvements in the code, and it suggested some refactoring opportunities, such as quick wins to improve the project. Gemini CLI suggested improving the error handling that was already on my to-do list, and it also pointed out handling edge cases that I hadn’t considered yet, like user input in “XX:XX” format, which is not currently supported by the gem (only “XX:XX:XX” format). This was a great insight, as I hadn’t thought about this case before.

Instead of just following the instructions, I prompted it to write a plan - in a Markdown file - on how to implement these improvements, and it provided a clear and concise plan with steps to follow. Then I asked it to follow the instructions of each part of the plan. Whenever Gemini CLI has to make a change in a file or run a command in the terminal, it asks for confirmation before proceeding, which is a good safety feature. I found this very useful, as it prevents accidental changes to the codebase and allows you to review the changes both before and after they are made.

Another interesting aspect is that when Gemini CLI experiences some delay in answering or executing a command, it automatically switches the model to Gemini 2.5 Flash, which is faster to respond and execute commands, though with a slightly lower quality. In general, the quality of changes and suggestions made by Gemini CLI is very good. I also used it to make minor changes in my pipeline, update the README, and modify the file with specifications of the gem to upload to RubyGems. The AI was able to understand the context of the project and provide relevant suggestions and changes.

This is the Pull Request I created with the changes made using the Gemini CLI: [57] Improvements in calculation conversion and how handle errors

Here is a summary of the main features of Gemini CLI that I found useful:

Project Analysis: It quickly reads and summarizes the project files, providing an overview of the main features, version, and license of the gem.
Code Review: It identifies potential improvements in the code, suggesting refactoring opportunities and enhancements to error handling.
Plan Generation: It can create a clear and concise plan for implementing improvements, breaking down the steps needed to achieve the desired changes.
Confirmation Prompts: Before making any changes, it asks for confirmation, allowing you to review the changes before they are applied.
Model Switching: It automatically switches to a faster model (Gemini 2.5 Flash) when there are delays in responses or command execution, ensuring a smoother experience.

One aspect I particularly do not like in Gemini CLI is that you cannot see it using your existing terminal, or suggest it to use your terminal to run commands like tests or start the server. You cannot directly interact with the terminal like you can with Copilot, which allows you to write code directly in the editor.

In general: ~~sorry Sarah Connor, Gemini CLI is my best friend now.~~ I found Gemini CLI faster and more efficient than Github Copilot with Claude Sonnet 3.7 or 4.0. After this initial experience, I started to use both tools together: using Gemini CLI for project analysis and planning, and then leveraging Copilot for specific code changes, tests, and enhancements. This is my current strategy to learn more about both tools and how they can complement each other.

Image: Meme of Sarah Connor (Linda Hamilton), from The Exterminator.

Five attitudes for the learner

2025-06-25T00:00:00+00:00

I just completed my first month as a software developer at JetRockets, a really cool place. It’s been thirty days of connecting with people from different countries, understanding how things work, studying new topics, business rules, and tackling my first tasks and features. Since day one, I’ve been reflecting on my experiences over the past few years regarding starting in a new place and how to learn effectively

It’s not uncommon, while idly staring into space with a cup of coffee in hand, to find ourselves reflecting on an idea, attitude, or piece of information that would have made all the difference if only we’d known it sooner. “It would have been great to understand that back then…” “If only I’d been like this ten years ago…” The endless “what ifs” that haunt us now and then, or always. Examining this through the microscope of reason reveals that who we are and what we know today is precisely the result of the challenges we’ve overcome. There’s no way we could possess this knowledge and these perspectives without the experiences that forged them. It’s even comforting to think this way, but there’s no bulletproof vest for that sudden urge to go back in time with the perfect attitude or comeback on the tip of our tongue. The past is a living thing; you can’t simply archive it in a forgotten folder on your memory drive. No AI or organic intelligence exists without continuously processing its own repository of information.

I found myself pondering this when, in the same week, two young individuals asked me about the skills and knowledge needed to embark on a journey of learning and work. The first, a former elementary school student of mine, is starting a History degree. The second is a programming student eager to take their first steps into the job market. I wondered what useful advice I could offer to a teenage João Gilberto learning to play musical instruments, and to the same individual as he was about to enter university and his first job. Also, to the postgraduate professor writing his first lines of code. I combined these thoughts with my experience of learning and teaching various subjects and synthesized a few key points:

Cultivate genuine curiosity: learning becomes a true torment if we’re not genuinely interested in the topic or can’t even grasp the point of studying it. Of course, not every subject will be a deep passion that profoundly excites us. Still, the bricks of disinterest and the cement of laziness often form an insurmountable wall.
Be coachable (or mentor-friendly): being open to learning from diverse people and in various contexts is crucial. Far beyond the formal classroom setting, life is rich with situations where we can absorb knowledge. Being open to this, with ears and ego prepared, is a small price to pay for the significant gains you can achieve.
Know how to ask questions: questions drive humanity forward. It’s a cliché, but a true one, as evidenced by the success of internet search engines – the largest one processes around 3.5 billion queries daily. Knowing how to ask means contextualizing your query, defining the scope of what you want to know, and genuinely considering the responses before launching a new question. This applies whether you’re questioning a classmate, a forum, or even a generative AI.
learn how to learn: there isn’t a one-size-fits-all formula through which everyone effectively learns a particular subject. What does exist are various learning strategies, some more or less effective depending on the context. In another post, I explored this very aspect, from choosing the right materials to understanding your optimal learning style. It’s worth reflecting on past experiences: when did you successfully learn something, and when did it go wrong? And most importantly, why?
Practice: the other day, while discussing the importance of practice in learning, I recalled a saying I believe is of Dutch origin: “There has never been, nor will there ever be, a good book on how to ride a bicycle.” The point isn’t to diminish books — anyone who knows me understands my love for them — but rather to underscore the importance of constant practice. Theory is dead letter if it doesn’t ground action. Good musicians helped me realize that to truly learn, the best approach is to calmly start with simple exercises and gradually increase speed and complexity. There’s a virtuous cycle of encountering knowledge (whether by reading, watching, listening, etc.), attempting to do it (through exercises, personal projects, conversations, etc.), and repeating this process while adjusting your strategies at each step.

Here is the Portuguese version of this post.

Image: “High five”, Martin Fisch. From: Open Verse, Creative Commons 2.0

In Clouds - getting certified as Associate Cloud Engineer

2025-05-27T00:00:00+00:00

After three months of classes, exercises, and practical labs, I’m excited to announce that I passed the exam and am now certified as an Associate Cloud Engineer by Google Cloud!

A few months ago, I enrolled in the Get Certified 2025 program. It’s an excellent program that offers free credits for Qwiklabs, live synchronous classes, study groups, and practical exercises, all designed to prepare you for the certification exam. The instructors are incredibly knowledgeable, and the content is well-structured. Special shout-out to Arki1, their partner responsible for support, who specializes in cloud computing training.

I particularly enjoyed the blend of theory and hands-on practice. All exercises used real tools in Google Cloud accounts with costs fully covered by Google. This was a fantastic opportunity to learn and practice cloud computing concepts in a truly hands-on way, especially for me with Kubernetes, deployments, load balancing, and networking.

If you’re interested in cloud technology and considering getting certified, I highly recommend checking out the Get Certified program. It’s a superb way to learn and prepare for the certification exam (FOR FREE!), with the added benefit of experienced instructors and a supportive community of learners.

Tropical on Rails 2025 - What an incredible event!

2025-04-15T00:00:00+00:00

I had the pleasure of attending the Tropical on Rails 2025 conference in São Paulo, Brazil, on April 03 and 04, 2025. It was a fantastic experience! The event was organized by Cirdes Henrique and his team, who did an amazing job bringing together a diverse group of speakers and attendees from around the world.

Two full days of keynotes, talks, and in-depth discussions on the key technical and business challenges facing the Ruby on Rails ecosystem and the wider tech industry. Topics included LLM integration, cloud costs and deployment, asynchronous job testing, and more.

Great to connect and learn from experts and major players from Brazil, the USA, Canada, Mexico, Georgia, Spain, and beyond.

Impeccable organization in every detail. Thanks to Cirdes and everyone who made these two days a fantastic experience for networking, learning, and even some enjoyment!

In the next weeks the videos of the talks will be available on the YouTube channel of the event. I highly recommend checking them out!

A Quick Guide to PostgreSQL with Docker

2025-02-23T00:00:00+00:00

A month ago, my Ubuntu 24.04.2 LTS system had a problem during a system update and wouldn’t boot. While troubleshooting in recovery mode, I discovered the issue was with PostgreSQL. I removed PostgreSQL, performed some updates and upgrades, and the system was working again. However, I encountered some problems when trying to reinstall PostgreSQL. It was a Monday morning, and I had a lot of work to do. While considering my options, I remembered Docker.

Using a PostgreSQL database in a container is an easy way to run tests and development environments. I primarily use it for running automated tests, experimenting with changes in the console, running APIs locally to test code modifications, and so on. Here are the steps to use a local PostgreSQL database in a container:

Install Docker if you haven’t already. Follow the instructions on the Docker website.
Choose the PostgreSQL image you want to use. You can find the images on Docker Hub. Pay attention to the version you select, ensuring it’s compatible with your project. Also, consider if you need any specific extensions like PostGIS, pg_trgm, pgcrypto etc.
Prepare the command to run the container with the image. Be sure to set the necessary environment variables, such as the password, the port you want to use, and so on. You can find the environment variables on Docker Hub as well. Frameworks like Django or Ruby on Rails typically have a configuration file for database settings. Double-check that you’re using the correct configuration in both the Docker command and the configuration file.

Here is an example of a command to run a PostgreSQL container with the PostGIS extension:

docker run -d --hostname localhost -e POSTGRES_PASSWORD=postgres -p 5432:5432 postgis/postgis:16-3.5

In the example above, the container will run in the background (-d). The password is postgres, and the port is 5432 (both in the container and on the host). The hostname is localhost, and the image is postgis/postgis:16-3.5.

You can use the docker ps command (or docker container list) to see the running containers. You’ll see something like this:

CONTAINER ID   IMAGE                    COMMAND                  CREATED         STATUS         PORTS                                       NAMES
d8f6f57868cb   postgis/postgis:16-3.5   "docker-entrypoint.s…"   2 seconds ago   Up 2 seconds   0.0.0.0:5432->5432/tcp, :::5432->5432/tcp   objective_turtle

Now it’s time to use the container. Try some commands to create a database, a table, insert some data, etc. You can use commands from your framework to access the database. In Django, you can use python manage.py dbshell command to access the database. In Ruby on Rails, you can use rails db command to access the database. You can also use the psql command. To access the database from within the container, you can use docker exec -it <container_name> bash to enter in the container and then use psql.

When you’re finished, you can stop the container with docker stop <container_name> command. You can remove the container with the docker rm <container_name> command. You can remove the container with docker rm <container_name> and the image with docker rmi <image_name>.

Here the list of useful commands:

docker ps or docker container list: list the running containers
docker stop <container_name>: stop the container
docker rm <container_name>: remove the container
docker rmi <image_name>: remove the image
docker exec -it <container_name> bash: enter in the container
psql: access the database

And that’s it! It’s easy and fast and you can follow the same steps to use other databases like MySQL, MariaDB, etc. Have fun!

Image: Container City ~ Explore #15 14-03-2022. Source: OpenVerse - license Creative Commons 2.0.

The Art of Onboarding

2025-01-17T00:00:00+00:00

Walking into a new room and feeling everyone’s eyes on you can be nerve-wracking. That initial awkwardness of being the new person eventually fades as you become integrated into the team. When joining a new company or project, there’s always an adjustment period where you’re absorbing information about people, processes, and products. This period, commonly known as onboarding, is crucial for new team members to get up to speed and start contributing effectively.

Every company and team has its own onboarding process, varying in duration and intensity. It’s often a period of both anxiety for the new hire and mutual discovery. A friend who has experienced onboarding from both sides of the table says it takes at least three months for someone to reach full capacity in a new role.

I’ve been actively involved in onboarding new hires and have learned from my former technical lead, Nilson Júnior, that providing comprehensive support is essential. This includes granting necessary access, explaining company ceremonies, addressing technical questions, and fostering a welcoming environment. Having entered the tech industry in my 30s with experience in other fields, I’ve developed strategies to accelerate my own onboarding and that of others.

The goal of onboarding is to help new hires quickly find their footing and become productive members of the team. Here are five key strategies:

The Detective’s Questions: When entering a new environment with unfamiliar people, it’s natural to have many questions. Historians, doctors, detectives, and researchers from various fields share a common approach based on the scientific method: a simple set of questions that can be counted on one hand – What? When? Where? How? Why? By jotting down answers and new questions as you encounter them, you can better understand the information and identify knowledge gaps.
The Rules of the Game: While the detective’s questions provide a solid foundation, understanding the business is also crucial. Every software application serves a specific purpose. Ask questions like: Who is the end-user? What value does the product deliver? What are the current initiatives and challenges? Why were these initiatives chosen? How does this app differentiate itself from competitors? What are the industry’s jargon and terminology?
Expectations and People: Joining a new team comes with a set of expectations. Beyond the initial anxiety and first impressions, there are also projections from leaders, colleagues, and clients. Relationships are the heart of any workplace. Understanding each person’s role, their daily tasks, and their working style is crucial. Similarly, it’s important to clarify what is expected of you. Are you replacing someone? Filling a skills gap? Leading a team? Having a clear understanding of expectations helps you align your skills with the role’s requirements.
Charting Your Course: Once you have a basic understanding of the business, technology, people, and expectations, it’s time to set goals. Perhaps you’ve identified a knowledge gap in a particular technology or business area. Or maybe you see an opportunity to contribute using your existing skills. The key is to identify areas for improvement and create a plan to address them. This could involve taking a course, joining a study group, or seeking mentorship.
Individual Action, Collective Process: While onboarding is primarily the responsibility of the new hire, it’s also a collective process involving management, technical leads, and the entire team. A welcoming and supportive environment can significantly speed up the onboarding process. If you’ve been through onboarding before, reflect on your experience. What worked well? What could have been improved? Sharing your insights with others can be beneficial.

In conclusion, onboarding is a journey of discovery that can be both exciting and challenging. It’s an opportunity to learn new skills and contribute to a new team. By actively seeking information, building relationships, and setting clear goals, you can make the most of this experience.

Image: Apollo 11 moments before landing on the Moon. Source: OpenVerse - license Creative Commons 2.0.

This is a translation of a post in portuguese. The original text can be found here: A arte do onboarding

1000 Tage lernen

2024-11-28T00:00:00+00:00

Learning something on your own is both a challenge and a self-discovery experience. I recently passed the mark of one year studying German daily on Duolingo - hence the 1000 days of learning in the title - a good milestone to reflect a little on learning and self-teaching.

One point is how to deal with the infinite paths that the Internet offers. On the one hand, the freedom to follow the direction you want and to be able to change course at any time. But at the same time, how to know if you’re going in the right direction, or measure how much you’ve actually learned. I read about this a couple of years in William Oliveira’s book and I agree with the author. If you know nothing about the subject you want to study, it’s worth researching paths, maps, videos, course syllabi and the like that are introductory to that topic. There will probably be online courses, books, websites, etc. that are repeated in these recommendations, a good sign of where to start. However, in this sea of information there must also be posts, lives, reviews and the like that are actually advertising to buy certain material, it’s up to you to differentiate what is a genuine suggestion from what is marketing.

It’s important to keep in mind that each person has their own affinities for a certain type of content, I personally prefer texts to videos to learn something. In addition, there are materials of various levels, it is useful to look for those that are compatible with your current knowledge. If I were to learn Chinese today, I would have to find content for those who know nothing, not an advanced course for someone who is going to live in China next semester. In this screening of materials it is pertinent to test: leaf through, watch, listen, use the app or whatever it is. See if you liked that approach, the content, etc., if you felt confident and interested to move forward in that direction. There is no one-size-fits-all recipe, each person will have their app, book or website that they found most suitable and comfortable to learn.

Once the route is chosen, it’s time to walk, because just having the best study material in the world saved on your phone or in your closet won’t make you learn anything. How many plans have we all made one day that were never put into practice? Learning something requires repetition: reading, practicing, summarizing, acting, rereading and so on in a daily circle. This is the step that is both simple and difficult, going beyond the initial excitement and building a habit.

This is a translation of a post in portuguese. The original text can be found here: https://0jonjo.github.io/blog/2023/400-dias/

Calcpace 1.4.0 released

2024-09-16T00:00:00+00:00

I’ve released version 1.4.0 of Calcpace!

This version introduces new possibilities for distance and speed calculations, including average speed, pace, total time, and predicted distance. It also features a conversion tool with options for international, nautical, and imperial standards.

You can calculate using three kinds of methods:

Without checks: Fastest, using float or integers.
With checks: Fast, using float/integers and clocktime (HH:MM:SS).
With clocktime return: Slowest.

Calcpace supports different check methods for each calculation and offers 26 types of conversions between distances and speeds. See the table below for the new conversion options:

Conversion Unit	Description
`:km_to_mi`	Kilometers to Miles
`:mi_to_km`	Miles to Kilometers
`:nautical_mi_to_km`	Nautical Miles to Kilometers
`:km_to_nautical_mi`	Kilometers to Nautical Miles
`:meters_to_km`	Meters to Kilometers
`:km_to_meters`	Kilometers to Meters
`:meters_to_mi`	Meters to Miles
`:mi_to_meters`	Miles to Meters
`:meters_to_feet`	Meters to Feet
`:feet_to_meters`	Feet to Meters
`:meters_to_yards`	Meters to Yards
`:yards_to_meters`	Yards to Meters
`:meters_to_inches`	Meters to Inches
`:inches_to_meters`	Inches to Meters
`:m_s_to_km_h`	Meters per Second to Kilometers per Hour
`:km_h_to_m_s`	Kilometers per Hour to Meters per Second
`:m_s_to_mi_h`	Meters per Second to Miles per Hour
`:mi_h_to_m_s`	Miles per Hour to Meters per Second
`:m_s_to_nautical_mi_h`	Meters per Second to Nautical Miles per Hour
`:nautical_mi_h_to_m_s`	Nautical Miles per Hour to Meters per Second
`:m_s_to_feet_s`	Meters per Second to Feet per Second
`:feet_s_to_m_s`	Feet per Second to Meters per Second
`:m_s_to_knots`	Meters per Second to Knots
`:knots_to_m_s`	Knots to Meters per Second
`:km_h_to_mi_h`	Kilometers per Hour to Miles per Hour
`:mi_h_to_km_h`	Miles per Hour to Kilometers per Hour

The documentation has been revamped with examples of how to use the new features.

RubyGems: https://rubygems.org/gems/calcpace

For more information on how to use Calcpace, visit the GitHub repository: https://github.com/0jonjo/calcpace

Image: “Map preparation, quick and sloppy, Johan G”. Open Verse, Creative Commons 2.0