DEV Community: Alexander Shagov

How Jev decision models work (and how to build your own on MLX)

Alexander Shagov — Mon, 12 Oct 2026 15:24:48 +0000

The web is bloated with Jev posts. The thing is a few weeks old, and my feeds are already full of it.. benchmarks, hot takes, threads about decision models being the future of agents. Jev, if you've managed to avoid the hype, is TypeSafe AI's hosted decision API where you send a situation and a few typed questions, it returns the answer with a probability for every option.

Two spoilers, because I like roads with signposts. Classical ML never left the chat, and the newest tool in the box still doesn't answer the oldest question, whether you actually need it in the first place.

At some point I stopped skimming news and got really curious about the machinery underneath. How does a model decide instead of write? What is actually different in there?

The short answer turned into a project, and the project turned into a story about building a thing and then discovering, layer by layer (sorry), that most of it already existed. It's called take-my-layer.

Init

I'll be honest, I never thought I'd invented something. I knew reading probabilities off logits was a thing and the Jev posts themselves hint at it. But knowing a trick exists and holding it in your own hands are different things, and what I didn't know was how far it stretches. I took a 4-bit Qwen model on a laptop, no training, no labels, questions made up on the spot. That part was worth testing.

So I went scouting before building anything serious. Kind of following my own advice from a post about fog of war as a mental model. The fog doesn't mean the territory is missing, it just means you haven't been there yet. Reading papers is scouting. Building a small proof of concept is scouting. I expected to find maybe one or two adjacent things.

Well.. the territory I found was huuuge :D

The trick is from 2021

First stop. Reading answer probabilities instead of generating answer text. This is how the whole evaluation world has scored decoder-only models for years.. it's the loglikelihood default in lm-evaluation-harness. The prompting version has names (verbalizers, pattern-verbalizer pairs, cloze-style prompting). PET (Schick & Schütze, EACL 2021) and "Small Language Models Are Also Few-Shot Learners" (NAACL 2021) are the classics, LM-BFF (ACL 2021) even automates the label-word search.

What I'd been calling "reading the logits" has a standard name, a literature, a codified abstraction, and several thousand citations. The trick predates ChatGPT (obvious for people who are not the first day on the ML street).

The bugs are from 2021 too

The naive version has a bug called position bias. Ask "A, B, C or D?" and the model leans toward whichever option is listed first, regardless of the options. I found that myself the fun way when the raw read on my coding data predicted bash for 74 of 120 states. A bash magnet kind of. Its 0.57 accuracy was roughly bash's base rate in the data.

Essentially every bug I hit someone had already hit:

Calibrate Before Use (Zhao et al., ICML 2021): content-free priors to correct the model's answer skew.
Order sensitivity of option lists (Pezeshkpour & Hruschka, 2023).
Fantastically Ordered Prompts (Lu et al., ACL 2022): same disease, few-shot demonstrations.
PriDe (ICLR 2024): the cheap permutation-plus-prior combination, which is more or less the cheaper cousin of my scheme.
Batch Calibration (ICLR 2024): the unified view of all of the above.

My own fix (arrived at independently and with more cursing), was to list the options in several rotated orders, ask once per order, average. That's called permutation marginalization, and it is worth +4.7 points of agreement with the reference over the naive single-prompt read (5 answers flip toward the reference, 0 away). All of that was known. Standing on shoulders of giants, etc.

Leaving early

The next piece was speed. A full forward pass over a 4B model for a one-word answer is wasteful, and it turns out the decision signal sits pretty early. (Qwen3.5-4B has 32 blocks; layer selection kept picking 16 and 19, before the last full-attention blocks. The interesting states live in the linear-attention trunk.)

The literature here is CALM (NeurIPS 2022), early exit per token by confidence. In my case it's a fixed half-depth exit for one fitted head, the layer-pruning family. Fine again, keep standing on the shoulders!

In MLX land there is exactly one static precedent that I could find: NeoJev, a 27B 4-bit (~15 GB) that keeps 56 of 64 layers with a self-distilled head, 0.727 mean accuracy at 310 ms p50 on an M5 Pro. One detail I genuinely enjoyed is that a plain logit lens at their layer 56 reads 0.663. Same head-over-raw gap I measured on my own side, so kind of proving I'm moving in the right direction.

A practical note for anyone following this route: mlx-lm exposes no intermediate-layer hooks (issue #1053, still open as of date of this blog post), so a hand-rolled block loop is the only way in. Mine matches the stock forward to a max logit difference of about 0.037.

A warning from the probing people

Fitting a tiny linear head on hidden states is also a literature: called probing. Hewitt & Liang (2019) and Belinkov's survey (2022) are the standard references, and their criticism is aimed at claims. A probe is weak evidence about what a model "understands". I took that as a warning about wording but not about architecture. A production head is judged by held-out task accuracy on the served artifact (ours reads 0.826 on its holdout), not by what it supposedly reveals. Linear (as the probing people say) is the defensible capacity choice.

And finally products

The method hunt was humbling, in that almost everything was already there before. The product hunt was even more humbling.

Jev you've already met. Cloudflare's Clef ships fine-tuned decision models with open Apache-2.0 weights (209 ms median, 38.8 ms for the flash variant). Unsloth has a train-your-own recipe: LoRA plus a Clef-design head, their 0.8B reads 36% on typed-decisions before training and 73% after. Around those there's a whole cluster: Mini-Jev, mlx-decision, laya-mlx. Even the routing people are adjacent, though RouteLLM and friends put a separate model in front of the LLM, whereas I wanted the served model's own distribution to be the classifier.

(!) And then the one that mattered to me: AnyJev, Nokia Applied Research's open method and library (technical report). Essentially I've taken AnyJev's method, deployed on the Mac.

What's actually mine

An honest ledger, because I care about this part. The repo's docs have a section literally titled "honest lineage", and it says explicitly that I did not invent the trick. What's original though:

The missing MLX backend for AnyJev's toolbox (an original implementation of their documented backend contract; they never shipped one).
The small-memory end: a 4-bit 4B, about 3 GB resident, versus NeoJev's 15.
Zero-training deployment: the frozen model works the moment it downloads. No dataset, no training run, no labels.
The observe() loop: while a shadow proxy watches real agent traffic, it quietly banks "what I predicted" next to "what actually happened", and one command refits a head from that bank. As far as I could find, nobody ships fit-on-your-traffic heads.
And the measurements of course.

None of that is a new mechanism. It's just glue and a scorecard. BTW! I wrote about taste a while ago and there (TLDR) I say that when production becomes abundant, judgment becomes scarce. The judgment here was mostly deciding what not to claim.

Benchmarks

The repo holds itself to wording rules that I want to keep in this post too: fidelity claims say "aligned with the reference", never "more correct"; accuracy claims name the arena and the model size. So, with that:

what was measured	result
Agreement with the real Jev API, 300 non-coding questions	4B 75.7%, 9B 82.0%; Jev agrees with itself 98.7%, which is the ceiling
Readout vs greedy decoding of the same model, same 300 questions	+4.7 (4B), +6.3 (9B), McNemar p = 0.003; on long inputs greedy Choice answers collapse (46% vs 85% agreement)
BANKING77, 10 intents, gold labels	87.5% (4B), 91.25% (9B), Jev 95.5%: a trained model wins on its home turf
typed-decisions, zero training	61.6% (4B), 60.4% (9B), vs 73-78% for models fine-tuned on it
Latency, long input, 5 questions in one request	22.2 s down to 3.7 s mean (the state is read once); the coding head answers in ~0.2 s

The losses are the point, in a way. A trained model beats a zero-training readout whenever labels and a fixed label set exist. Train a classifier! This is for questions and options you cannot enumerate ahead of time, on a machine where the data cannot leave.

Here's one real exchange on my M5:

curl -s localhost:8095/v1/systemone -d '{"state": "Ticket #4821 from Dana (Pro plan, customer for 14 months): \"Since this morning every export to CSV fails with a 502. We run payroll from those exports at 3pm today.\" Status page: all green.",
 "questions": {
   "route": {"type": "Choice", "instructions": "Which team should take this first?", "options": ["billing", "platform-oncall", "account-management", "docs"]},
   "escalate_now": {"type": "Noul", "instructions": "Does this need the on-call engineer right now?"},
   "urgency": {"type": "Score", "instructions": "How urgent is this ticket?", "levels": ["low", "medium", "high", "critical"]}}}'

-> {"model": "mlx-community/Qwen3.5-4B-MLX-4bit",
    "answers": {
      "route": {"answer": "platform-oncall", "confidence": 0.8516, "probabilities": {"billing": 0.0744, "platform-oncall": 0.8516, "account-management": 0.0579, "docs": 0.0161}},
      "escalate_now": {"answer": true, "confidence": 0.637, "probabilities": {"Yes": 0.637, "No": 0.363}},
      "urgency": {"answer": "critical", "confidence": 0.6651, "probabilities": {"low": 0.0051, "medium": 0.0156, "high": 0.3142, "critical": 0.6651}}}}

Status: research prototype, and the docs are blunt about it. The Jev-agreement numbers use LLM-authored questions with no human labels. The one fitted head that ships cannot be reproduced from the repo, because its training seed is withheld. If you have a fixed label set and training data, train a classifier instead. All of it is written down in a LIMITATIONS.md.

The boring lesson

This field is moving embarrassingly fast.
But the lesson I'd actually keep from these weeks is a boring one: classical ML never left. Every number in the table above says so. Wherever a fixed label set and training data exist, something trained the old way wins. Jev's 95.5% on BANKING77 against my 87.5%, the fine-tuned 2B sitting 16 points above my zero-training readout on typed-decisions. Reading logits doesn't replace training. It covers the corner cases training can't reach e.g. questions you can't enumerate ahead of time, no labels to collect, data that isn't allowed to leave the machine etc.

So before throwing this at a task, the checklist is the one classical ML wrote decades ago. Fixed labels and enough data? Train a classifier, it's still unbeatable there. Data that can't leave the machine, or questions that change per request? That's where reading the model's own probabilities earns its keep. In between, renting a hosted API is probably a fine deal.

Oh right, the question

Ah, I actually never answered the "how does a model decide instead of write" part from the beginning. Short version, and experienced ML people will roll their eyes at how obvious it is: the decision seems to form well before the end of the network. My tiny head reads block 16 of 32 and still answers the "what next" question at 0.826 accuracy. AnyJev's own measurements found a middle block to be a better feature space than the final one, since the last blocks are busy converting the answer into token space. And NeoJev keeps 56 of 64 layers, which suggests there is slack even higher up. So roughly: the deciding happens in the first half to two thirds of the layers, and the rest is more like the writing department.

Am I even right here? Probably, for these models, by my measurements. That's as far as I'd push it.

That's it.

Home Manager: never set up a laptop twice

Alexander Shagov — Wed, 29 Jul 2026 14:54:55 +0000

How I restore my entire Mac user environment from one Git repo with a single command

I wrote earlier about why I use Nix on macOS. This is the follow-up: the same idea, applied to the whole machine instead of one project.

My entire user environment lives in a single Git repo. Packages, shell config, aliases, git, tmux, the editor. Everything I care about, basically. When I get a new Mac, I clone it, run one command, and I'm back.

The recipe is short:

Install Nix (the Determinate installer, more on that in a sec).
Clone the config repo into ~/.config/home-manager.
Run home-manager switch.

# flakes on by default
curl -fsSL https://install.determinate.systems/nix | sh -s -- install

git clone https://github.com/you/your-config ~/.config/home-manager
cd ~/.config/home-manager

home-manager switch

That last line does the real work. It builds the whole environment from flake.nix and home.nix and installs it. If I nuke the machine and start over, I just pull the repo, run the command, and end up on the exact same setup, because flake.lock pins every input to a fixed version.

Here's the config I actually run. The flake just declares inputs and points at home.nix:

{
  description = "Home Manager configuration of alexlaptop";

  inputs = {
    nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
    home-manager = {
      url = "github:nix-community/home-manager";
      inputs.nixpkgs.follows = "nixpkgs";
    };
  };

  outputs = { nixpkgs, home-manager, ... }:
    let
      system = "x86_64-darwin";
      pkgs = nixpkgs.legacyPackages.${system};
    in {
      homeConfigurations."alexlaptop" = home-manager.lib.homeManagerConfiguration {
        inherit pkgs;
        modules = [ ./home.nix ];
      };
    };
}

And home.nix is where everything I want lives: packages, aliases, shell, tools:

{ config, pkgs, ... }:

let
  shellAliases = {
    gs = "git status";
    gcm = "git checkout main && git pull";
    gc  = "git checkout";
    be  = "bundle exec";
    bi  = "bundle install";
  };
in
{
  home.username = "alexlaptop";
  home.homeDirectory = "/Users/alexlaptop";
  home.stateVersion = "26.05";

  home.packages = with pkgs; [
    ripgrep fd fzf bat tree jq htop
    direnv tmux
    ffmpeg_6 poppler-utils exiftool
    emacs-pgtk
    # ai
    claude-code
  ];

  home.shellAliases = shellAliases;
  home.sessionVariables = { EDITOR = "emacs"; };

  programs.home-manager.enable = true;

  programs.zsh = {
    enable = true;
    inherit shellAliases;
    initContent = ''
      autoload -Uz vcs_info
      precmd() { vcs_info; }
      zstyle ':vcs_info:*' enable git
      zstyle ':vcs_info:*' formats ' (%b)'
      setopt prompt_subst
      PROMPT='%~''${vcs_info_msg_0_} %# '
    '';
  };

  programs.direnv = {
    enable = true;
    nix-direnv.enable = true;
  };

  programs.fzf = {
    enable = true;
    enableZshIntegration = true;
  };

  programs.tmux = {
    enable = true;
    extraConfig = ''
      unbind C-b
      set -g prefix C-z
      bind C-z send-prefix
    '';
  };
}

One thing worth saying is that I don't use nix-darwin. Home Manager looks after my user environment (the tools, the shell, the dotfiles). It doesn't touch macOS itself. Which is fine by me, honestly, because the things that drift between machines and eat my afternoon are exactly the things Home Manager already handles. If I ever want the system layer on top of that, nix-darwin is the obvious next step. Or the full NixOS, on a separate Linux laptop.. I just never felt the need.

A quick word on the installer, because it matters more than I expected. I use Determinate Systems' one rather than the stock Nix installer.

The main reason is flakes. Determinate turns on flakes and nix-command out of the box. By 2026 flakes are just how Nix works (every real project uses them), even though upstream still slaps the "experimental" label on them. That label's been sitting there since 2021 and at this point it's mostly inertia.

The other two are practical. Stock Nix had a nasty habit of breaking after a major macOS update. Determinate runs its own daemon, and I haven't had a dead /nix since I switched. And if I ever want out, every change is logged to /nix/receipt.json, so sudo /nix/nix-installer uninstall reverses the whole configuration cleanly.

Is it worth it? Well.. I'll be honest here, the Nix language is genuinely weird. The error messages are rough, and option names get renamed between releases, which is annoying. But still it is worth it. I don't think I'll ever spend an afternoon setting up a laptop again. Packages, dotfiles, the whole setup, exactly where I left them, from one repo and one command.

If you're interested, check the first steps article, understand the vocabulary before jumping into the configs, it's easy to get lost even though it boils down to few commands and files eventually.

You might also visit my personal blog for more topics (not only nix-related).

Thanks!

How LLM users accidentally do TDD without realizing it

Alexander Shagov — Sat, 10 May 2025 07:24:54 +0000

Most developers using LLM tools today are unknowingly following a loose version of test-driven development (TDD).

1. TDD and LLM prompting work surprisingly similar

a) Start with failure

TDD: You define an interface and write a failing test first. Now you know what needs fixing.
LLMs: You write a vague prompt, get bad results, and think "I need to explain this better." Same basic concept.

b) Make it work

TDD: You write code until the test passes.
LLMs: You tweak the prompt, add details, and retry until you get good output. Same iterative approach.

c) Clean it up

TDD: "Okay, now let's clean this up."
LLMs: "This works but looks messy - needs polishing." Same final step.

2. Why developers end up doing TDD-like work with LLMs

Many developers claim to hate TDD ("too much overhead!") but end up doing something similar because:

They have to think through requirements first (or the AI won't help)
They iterate repeatedly (just with prompts instead of tests)
They refine the AI's output (which is rarely perfect on first try)

3. LLMs reveal who actually understands coding

Beginners: Ask AI → Copy → Paste → Breaks → Gets stuck
Experienced devs: Plan → Experiment → Debug → Verify results

This mirrors TDD:

Weak developers write tests that don't actually help
Strong developers write tests that improve code and serve as documentation

The irony

If you avoid TDD but use LLMs... surprise! You're basically doing TDD-ish style of work without calling it that.

TDD is structured (test → fail → code → refine)
LLM prompting is more ad-hoc (ask → adjust → accept → maybe improve later)

What this shows us

Skilled developers use LLMs like TDD - they plan, test, and refine.
Junior developers use LLMs like supercharged Stack Overflow - copy, paste, and pray.

In the end, any tool just amplifies your existing thought process.

Configuring your own deep research tool (Using Nix Flakes)

Alexander Shagov — Mon, 28 Apr 2025 15:48:44 +0000

So, you've come across deep search tools and are wondering if you can build your own. Well, you certainly can! Building one yourself might involve tasks like scraping web URLs, implementing your own RAG (Retrieval-Augmented Generation) system to find relevant information, and then summarizing it using an agent loop.

Luckily, the open-source community has already created tools that handle many of these steps. The purpose of this article is to demonstrate how easily we can spin up the necessary environment for such a tool using Nix. We'll focus not only on running the service, but also on development environment setup, making it easy to modify the tool if needed.

For demonstration purposes, I'll be using the gpt-researcher tool.
Github link: https://github.com/assafelovic/gpt-researcher

The basic setup for almost any Python project often feels trivial: install Python, install requirements.txt, and you're good to go. However, if you manage tens of these projects on your machine, you'll quickly realize you not only need to isolate your project environments (which .venv solves) but ideally also isolate the Python installations themselves.

Welcome Nix flakes!

Why Use Nix for Your Development Environment?

Nix is a powerful package manager that helps ensure your development environment is reproducible and isolated. By defining your dependencies (like Python and other tools) in a Nix flake, anyone (including your future self!) can recreate the exact same environment with a single command, avoiding "it works on my machine" problems.

To get a better grasp of what Nix is, you can check out my beginner's article.

Nix flake

Once you pulled the repo, the only thing you need to do (besides .env configuration with your own API keys), is to setup the dev environment using a nix flake. Here's what my file looks like:

{
  inputs = {
    nixpkgs.url = "nixpkgs";
    flake-utils.url = "github:numtide/flake-utils";
  };

  outputs = { self, nixpkgs, flake-utils }:
    flake-utils.lib.eachDefaultSystem (system:
      let
        pkgs = import nixpkgs {
          inherit system;
          config.allowUnfree = true;
        };
      in {
        devShells.default = pkgs.mkShell {
          buildInputs = with pkgs; [
            git

            python311
            python311Packages.pip
            python311Packages.virtualenv
          ];

          shellHook = ''
            # Create and activate virtual environment if it doesn't exist
            VENV=.venv
            REQUIREMENTS_HASH=".venv/.requirements.hash"

            # Calculate new hash of requirements file
            NEW_HASH=""
            if [ -f "requirements.txt" ]; then
              NEW_HASH=$(sha256sum requirements.txt)
            fi

            if [ ! -d "$VENV" ]; then
              echo "Creating virtual environment..."
              python -m venv "$VENV"
              source "$VENV/bin/activate"

              # Initial pip upgrade and requirements installation
              pip install --upgrade pip
              if [ -f "requirements.txt" ]; then
                echo "Installing requirements from requirements.txt..."
                pip install -r requirements.txt
                echo "$NEW_HASH" > "$REQUIREMENTS_HASH"
              fi
              echo "Virtual environment setup complete!"
            else
              source "$VENV/bin/activate"

              # Check if requirements have changed
              if [ -f "requirements.txt" ]; then
                if [ ! -f "$REQUIREMENTS_HASH" ] || [ "$NEW_HASH" != "$(cat $REQUIREMENTS_HASH)" ]; then
                  echo "Requirements have changed. Updating..."
                  pip install --upgrade pip
                  pip install -r requirements.txt
                  echo "$NEW_HASH" > "$REQUIREMENTS_HASH"
                fi
              fi
            fi

            # Print Python version
            echo "Using Python: $(python --version)"
          '';
        };
      });
}

Using the Environment

Once you have the flake.nix file in your project's root directory (assuming Nix with flakes is installed), the only command you need to run is nix develop. Running this command will drop you into an isolated development shell.

Within this shell, you'll have access to the tools defined in the flake, such as the specific Python version requested. Additionally, the custom shellHook I included in the flake automates the management of your Python dependencies. This hook automatically creates and activates a standard Python virtual environment (.venv). More importantly, it checks your requirements.txt file and automatically installs or updates your Python packages using pip whenever the contents of requirements.txt change. And everything isolated for this specific repo without any leakeges to the outside world!

The result is a fully prepared, self-contained development environment that keeps your project dependencies neatly isolated from the rest of your system, and also isolates the core tools like the Python interpreter itself – a key advantage over managing global installations or relying solely on .venv.

Why not docker?

Now, why not Docker? While Docker is awesome for deploying things, for active development where you're constantly tweaking code, it can feel a bit heavyweight. Jumping in and out of container builds or dealing with bind mounts just isn't as immediate as simply entering an interactive shell. That's it.

Bonus: Comparing Perplexity vs. local tool reports

So, I put a short summary request for "LLM history, roots, most impactful studies (scan all starting with 20th century)" to both Perplexity and the local tool we've been discussing. My goal was to show that for basic deep research, you don't necessarily need to pay for a service; you can configure your own using free tiers like Gemini for LLM tasks and a free search API like Serper, which the local tool utilises to scrape the web.

To get an unbiased comparison of the results, I asked a third LLM to analyze the style and substance of the two reports. Here's a summary of its findings:

While Article 2 (Perplexity) is more concise and its table of "Most Impactful Studies" is a valuable quick reference, Article 1 (Local tool) provides a richer, more detailed, and better-structured historical account that allows for a deeper understanding of the evolution of LLMs.

And you know what?:

You can always tweak the local tool implementation per your own needs! (e.g. I've adjusted it specifically for my needs to narrow down the set of resources I want it to look into). I mean, it's programming, you do whatever you want! And using nix preparing your dev setup as simple as running just 1 command, nix develop!

Ruby on Rails: Your Service Layer is a Lie

Alexander Shagov — Wed, 15 Jan 2025 10:00:57 +0000

If you're a Rails developer, you've probably seen (or written) code that looks like this:

class UserService
  def self.create(params)
    user = User.new(params)
    if user.save
      UserMailer.welcome_email(user).deliver_later
      user
    else
      false
    end
  end
end

# In your controller
def create
  @user = UserService.create(user_params)
  if @user
    redirect_to @user, notice: 'User was successfully created.'
  else
    render :new
  end
end

Look familiar? We've all been there. We've all written these service objects because "that's what good Rails developers do." But let me ask you something: What value did that service layer actually add?

We've been told that service layers:

Separate business logic from models
Make code more testable
Keep controllers thin
Follow single responsibility principle

When Your Service is Just Extra Typing

Many Rails codebases are littered with service objects that do nothing but proxy method calls to ActiveRecord models. Let's look at a real-world example:

class CommentService
  def self.create_for_post(post, user, content)
    Comment.create(
      post: post,
      user: user,
      content: content
    )
  end
end

What did we gain here? Nothing except an extra file to maintain and an additional layer to jump through while debugging. The service is literally just passing through parameters to Comment.create. Even worse, we've actually lost functionality compared to working with the model directly - we no longer have access to ActiveRecord's rich API for handling validation errors and callbacks.

When You Actually Need a Service Layer

Let's be clear: Service objects aren't always bad. (In fact I've written a separate article on rethinking service objects: https://dev.to/alexander_shagov/ruby-on-rails-rethinking-service-objects-4l0b)

1. Orchestrating Complex Operations

module Orders
  class ProcessingWorkflow
    include Dry::Transaction

    step :start_processing
    step :process_payment
    step :allocate_inventory
    step :create_shipping_label
    step :send_confirmation
    step :complete_processing

    private

    def start_processing(input)
      order = input[:order]
      order.update!(status: 'processing')
      Success(input)
    rescue => e
      Failure([:processing_failed, e.message])
    end

    def process_payment(input)
      order = input[:order]
      payment = Payments::Gateway.new.charge(
        amount: order.total,
        token: order.payment_token
      )
      Success(input.merge(payment: payment))
    rescue => e
      Failure([:payment_failed, e.message])
    end

    def allocate_inventory(input)
        # ...
    end

    def create_shipping_label(input)
        # ...
    end

    def send_confirmation(input)
      OrderMailer.confirmation(input[:order]).deliver_later
      Success(input)
    rescue => e
      Failure([:notification_failed, e.message])
    end

    def complete_processing(input)
      order = input[:order]
      order.update!(status: 'processed')
      Success(input)
    rescue => e
      Failure([:completion_failed, e.message])
    end
  end
end

2. Handling External Services

module Subscriptions
  class StripeWorkflow
    include Dry::Transaction

    step :validate_subscription
    step :create_stripe_customer
    step :create_stripe_subscription
    step :update_user_records

    private

    def validate_subscription(input)
      contract = Subscriptions::ValidationContract.new
      result = contract.call(input)
      result.success? ? Success(input) : Failure([:validation_failed, result.errors])
    end

    def create_stripe_customer(input)
        # ... stripe code
    end

    def create_stripe_subscription(input)
        # ... stripe code
    end

    def update_user_records(input)
      user = input[:user]
      user.update!(
        stripe_customer_id: input[:customer].id,
        stripe_subscription_id: input[:subscription].id,
        subscription_status: input[:subscription].status
      )
      Success(input)
    rescue => e
      Failure([:record_update_failed, e.message])
    end
  end
end

3. Complex Business Rules

module Loans
  class ApplicationProcess
    include Dry::Transaction

    step :validate_application
    step :check_credit_score
    step :evaluate_debt_ratio
    step :calculate_risk_score
    step :determine_approval
    step :process_result

    private

    def validate_application(input)
      contract = Loans::ApplicationContract.new
      result = contract.call(input)
      result.success? ? Success(input) : Failure([:validation_failed, result.errors])
    end

    def check_credit_score(input)
      application = input[:application]
      if application.credit_score < 600
        Failure([:credit_score_too_low, "Credit score below minimum requirement"])
      else
        Success(input)
      end
    end

    def evaluate_debt_ratio(input)
      calculator = Loans::DebtRatioCalculator.new(input[:application])
      ratio = calculator.compute

      if ratio > 0.43
        Failure([:debt_ratio_too_high, "Debt-to-income ratio exceeds maximum"])
      else
        Success(input.merge(debt_ratio: ratio))
      end
    end

    def calculate_risk_score(input)
        # ...
    end

    def determine_approval(input)
        # ...
    end

    def process_result(input)
      application = input[:application]

      if input[:approved]
        rate_calculator = Loans::InterestRateCalculator.new(
          application: application,
          risk_score: input[:risk_score]
        )

        application.update!(
          status: 'approved',
          interest_rate: rate_calculator.compute,
          approval_date: Time.current
        )
        LoanMailer.approval_notice(application).deliver_later
      else
        application.update!(status: 'rejected')
        LoanMailer.rejection_notice(application).deliver_later
      end

      Success(input)
    rescue => e
      Failure([:processing_failed, e.message])
    end
  end
end

The examples above represent what I consider valid uses of a service layer - or more accurately, business processes. They demonstrate clear cases where abstraction adds real value: complex workflows, external service integration, and domain-rich business rules and etc.
But the key takeaway isn't just about when to use these patterns - it's about questioning our default approaches to architecture. Too often, we reach for service objects because "that's how it's done" or because we've read that "fat models are bad." Instead, we should:

Start simple - directly in models and controllers
Let complexity guide abstraction - not the other way around
Think in terms of processes and workflows rather than generic "services"
Question established patterns - just because everyone's doing it doesn't make it right for your specific case

! More importantly, if you're part of a large team, establish and agree on a unified approach first. Having half your codebase using traditional service objects and the other half using process-oriented workflows will likely create more problems than it solves. Architectural decisions should be team decisions, backed by clear conventions and documentation.
Remember: Every layer of abstraction is a trade-off. Make sure you're getting enough value to justify the complexity cost.

Why Use Nix package manager, Even on macOS?

Alexander Shagov — Mon, 23 Sep 2024 07:55:20 +0000

Some time ago I wrote a short article on nix first steps (https://dev.to/alexander_shagov/nix-first-steps-4066). However, I realized that I need one more to quickly explain why generally prefer nix over non-nix setups. So here it is.

As a macOS user, you might wonder why you should consider using Nix (package manager) when you already have package managers like Homebrew.

⭐️ One of the most significant advantages of Nix is its ability to create reproducible environments. This means you can:

Easily share your exact development setup with teammates.
Recreate your entire system setup on a new machine with minimal effort.

⭐️ With Nix (especially when using Home Manager), you define your entire system configuration in code. This approach offers several benefits:

Your system setup becomes version-controlled.
You can review and roll back changes easily.
No more conflicts between different versions of the same library.
Easy testing of different software versions without affecting your system.

⭐️ Nix, especially with flakes, allows you to define project-specific environments:

Each project can have its own set of tools and dependencies.
No need to globally install project-specific tools, reducing system clutter.
If a local dependency update breaks something, you can easily roll back to a previous state (e.g. roll back node.js to the previous version in 1 click).

As a macOS user, I initially hesitated to adopt Nix, comfortable with my Homebrew + Ruby version manager + Node version manager + Docker setup.
However, after experiencing the reproducibility and declarative nature of Nix, I've found it invaluable. It's particularly useful for managing multiple development environments and ensuring consistency across my personal and work machines.

While the learning curve can be steep, the long-term benefits in terms of system management and development workflow have been worth the initial investment.

Diving into the Nix world might be overwhelming at first. Check out the 'First Steps' article (https://dev.to/alexander_shagov/nix-first-steps-4066), which helps define the important vocabulary.

Balancing Authenticity and Self-Promotion in the Tech Industry

Alexander Shagov — Mon, 23 Sep 2024 07:40:40 +0000

Picture this: You're a software developer at MegaCorp, writing code day in and day out. Your contributions, while necessary, often feel like drops in a vast ocean. Then comes the time to update your resume or LinkedIn profile. Suddenly, you're faced with a choice: do you stick to the unpolished truth, or do you make it sound big?

Welcome to the modern developer's dilemma.

In today's hyper-competitive GPT-powered tech industry, the pressure to stand out is immense. We're told to "build our personal brand," "showcase our achievements," and "sell ourselves" to potential employers. But what happens when the reality of our day-to-day work doesn't quite match up to these expectations?

Let's be honest - not every developer is working on revolutionary AI algorithms or building the next unicorn startup. Many of us are maintaining legacy systems, squashing bugs, or implementing small features that, while important, hardly set the world on fire. Yet, scroll through LinkedIn, and you'd think every developer was single-handedly revolutionizing their industry.

This gap between reality and marketing creates tension. On one side, there's the pull towards honesty and being real. On the other, there's the practical need to compete in a job market that seems to reward those who can write the most impressive-sounding bullet points.
And... it often works. HR teams and recruiters, often not knowing the technical details of our work, can be swayed by well-written stories of impact and achievement. A basic task reframed as a "critical initiative" might just be the difference between getting an interview or being lost in the resume pile.

And the situation is getting worse with GPT-powered systems checking GPT-generated CVs..

But at what cost?

Original: "Maintained backend systems."
Polished: "Architected and implemented mission-critical backend infrastructure, resulting in 99.99% uptime and 30% improvement in system efficiency."

Comment below with your experiences navigating authenticity in the tech industry. How do you balance self-promotion with genuine representation of your work?

The "IO to the Boundary" principle

Alexander Shagov — Tue, 10 Sep 2024 14:59:13 +0000

In software architecture, many principles and patterns have emerged over time. However, a lot of these can be boiled down to a single idea: the "IO to the Boundary" principle. This principle suggests that all input/output operations, like database queries, API calls, or file system interactions, should be pushed to the edges (or boundaries) of your application.

Let's look at what some other ideas tell us:

Functional Core, Imperative Shell: This principle suggests keeping the core of your application pure and functional, while handling side effects (IO) in an outer layer. This is basically another way of saying "IO to the Boundary."
Clean Architecture: Proposed by Robert C. Martin, this architecture emphasizes separating concerns and having dependencies point inwards, which fits with keeping IO at the edges.
Command Query Responsibility Segregation (CQRS): While not mainly about IO boundaries, CQRS often leads to separating read and write operations. This separation can support the "IO to the Boundary" principle by making it easier to isolate and manage IO operations at the system's edges.

Example

The Client Code interacts with both WeatherAPI (to create an object instance) and WeatherReport (to generate a report).
WeatherReport uses WeatherAPI internally to fetch temperature data.
WeatherAPI encapsulates the IO operations, making the actual HTTP request to the External Weather API.

This structure keeps the core application logic (WeatherReport) free from direct IO concerns, pushing those responsibilities to the edges (WeatherAPI and beyond).

Client Code       WeatherReport       WeatherAPI         External Weather API
     |                   |                   |                  |
     |                   |                   |                  |
     |  new WeatherAPI()                     |                  |
     |--------------------------------------->                  |
     |                   |                   |                  |
     |  new WeatherReport(weather_api)       |                  |
     |------------------>|                   |                  |
     |                   |                   |                  |
     |  generate_report('New York')          |                  |
     |------------------>|                   |                  |
     |                   |                   |                  |
     |                   | get_temperature('New York')          |
     |                   |------------------>|                  |
     |                   |                   |                  |
     |                   |                   | HTTP GET request |
     |                   |                   |----------------->|
     |                   |                   |                  |
     |                   |                   | JSON response    |
     |                   |                   |<-----------------|
     |                   |                   |                  |
     |                   |     temperature   |                  |
     |                   |<------------------|                  |
     |                   |                   |                  |
     |  formatted report |                   |                  |
     |<------------------|                   |                  |
     |                   |                   |                  |

    [Application Boundary]              [IO Boundary]

Note on oversimplification

From my perspective, the key to effective architecture is finding the right balance between simplification and necessary complexity (sounds vague but that's true..). It's becoming clear that most mid-sized projects don't need the level of complexity they often include. But some do. While I recognize that the real world is more complex, with evolving projects, changing teams, and loss of knowledge when an organization changes, it's crucial to remember that sometimes the best abstraction is no abstraction at all.

Code samples

Let's consider "good" and "bad" examples (I'll be using Ruby and Ruby on Rails to convey the ideas)

Bad example

# app/controllers/weather_controller.rb
class WeatherController < ApplicationController
  def report
    city = params[:city]
    api_key = ENV['WEATHER_API_KEY']

    response = HTTP.get("https://api.weather.com/v1/temperature?city=#{city}&key=#{api_key}")
    data = JSON.parse(response.body)

    temperature = data['temperature']
    feels_like = data['feels_like']

    report = "Weather Report for #{city}:\n"
    report += "Temperature: #{temperature}°C\n"
    report += "Feels like: #{feels_like}°C\n"

    if temperature > 30
      report += "It's hot outside! Stay hydrated."
    elsif temperature < 10
      report += "It's cold! Bundle up."
    else
      report += "The weather is mild. Enjoy your day!"
    end

    render plain: report
  end
end

It's evident that the code smells:

Mixing IO operations (API call) with business logic in the controller.
Directly parsing and manipulating data in the controller.
Generating the report text within the controller action.

Good example

# app/controllers/weather_controller.rb
class WeatherController < ApplicationController
  def report
    result = WeatherReport::Generate.new.call(city: params[:city])

    if result.success?
      render plain: result.value!
    else
      render plain: "Error: #{result.failure}", status: :unprocessable_entity
    end
  end
end

# app/business_processess/weather_report/generate.rb
require 'dry/transaction'

module WeatherReport
  class Generate
    include Dry::Transaction

    step :validate_input
    step :fetch_weather_data
    step :generate_report

    private

    def validate_input(city:)
      schema = Dry::Schema.Params do
        required(:city).filled(:string)
      end

      result = schema.call(city: city)
      result.success? ? Success(city: result[:city]) : Failure(result.errors.to_h)
    end

    def fetch_weather_data(city:)
      result = WeatherGateway.new.fetch(city)
      result.success? ? Success(city: city, weather: result.value!) : Failure(result.failure)
    end

    def generate_report(city:, weather:)
      report = WeatherReport.new(city, weather).compose
      Success(report)
    end
  end
end

# app/business_processess/weather_report/weather_gateway.rb
class WeatherGateway
  include Dry::Monads[:result]

  def fetch(city)
    response = HTTP.get("https://api.weather.com/v1/temperature?city=#{city}&key=#{ENV['WEATHER_API_KEY']}")
    data = JSON.parse(response.body)

    Success(temperature: data['temperature'], feels_like: data['feels_like'])
  rescue StandardError => e
    Failure("Failed to fetch weather data: #{e.message}")
  end
end

# app/business_processess/weather_report/weather_report.rb
class WeatherReport
  def initialize(city, weather)
    @city = city
    @weather = weather
  end

  def compose
    # ...
  end
end

What has changed:

Separating concerns: The controller only handles HTTP-related tasks.
Using dry-transaction to create a clear flow of operations, with each step having a single responsibility.
Pushing IO operations (API calls) to the boundary in the WeatherAPI service.

Note on complexity

We should be realistic though, if we're talking about a simple 1-pager app generating the weather reports, well, who cares? It just works and we definitely do not want to introduce any additional layers.
However, if we care about the future extendability, thinking about these kind of things is crucial.

Final note

Many of the architectural principles and patterns we encounter today are not entirely new concepts, but rather evolved or repackaged ideas from the past. I hope that you see now that the "IO to the Boundary" principle is one such idea that has been expressed in various forms over the years.

Comments / suggestions appreciated! 🙏

Ruby on Rails: Rethinking Service Objects

Alexander Shagov — Wed, 04 Sep 2024 13:03:36 +0000

(!) I've updated the article. You might read the updated version on my personal blog.

In the Ruby on Rails community, service objects have gained popularity as a way to encapsulate business logic and keep controllers and models lean. However, there's a growing trend of misusing service objects, particularly those with "-er" or "-or" suffixes. This article aims to shed light on poorly implemented service objects and provide guidance on creating more effective, domain-focused alternatives.

Many developers tend to name their service objects with suffixes like -er or -or, such as ArticleCreator or UserAuthenticator. While this naming convention may seem intuitive, it often leads to a procedural style of programming rather than embracing the object-oriented nature of Ruby.

It's becoming evident that service objects the way we often see them are not actually "objects", but just a procedures.. or better to say, processess.

Let's take a look at the real-world example of a codebase powering the dev.to community: https://github.com/forem/forem/blob/main/app/services/articles/creator.rb.
The class seems okay at first glance; at least the code is organized and lives in its own space. It could be workable. However, we're just hiding the problem in the long term.

# The code structure is taken from https://github.com/forem/forem/blob/main/app/services/articles/creator.rb

class ArticleCreator
  def initialize(user, article_params)
    @user = user
    @article_params = article_params
  end

  def call
    rate_limit!
    create_article
    subscribe_author
    refresh_auto_audience_segments if @article.published?
    @article
  end

  private

  def rate_limit!
    # Rate limiting logic
  end

  def create_article
    @article = Article.create(@article_params.merge(user_id: @user.id))
  end

  def subscribe_author
    NotificationSubscription.create(user: @user, notifiable: @article, config: "all_comments")
  end

  def refresh_auto_audience_segments
    @user.refresh_auto_audience_segments
  end
end

A Domain-Centric Approach

Instead of focusing solely on actions (creating, updating, deleting), we should model our service objects around domain concepts and processes. Hence my suggestion: let's stop pretending service objects are objects and start calling them processess instead.
NOTE: I'm not talking about DDD (Domain-Driven design) since it's a whole separate topic, however, we can be inspired by some of the concepts.

I'll be using dry-* libraries to demonstrate how a process might have looked like:

module Articles
  class PublishingProcess
    include Dry::Transaction

    step :validate
    step :rate_limit
    step :create_article
    step :subscribe_author
    step :refresh_auto_audience_segments
    step :notify_subscribers

    private

    def validate(input)
      contract = Articles::ValidationContract.new
      result = contract.call(input)
      result.success? ? Success(input) : Failure(result.errors)
    end

    def rate_limit(input)
      limiter = Articles::PublishingQuota.new(input[:user])
      limiter.within_limit? ? Success(input) : Failure(:rate_limited)
    end

    def create_article(input)
      repository = Articles::Repository.new
      article = repository.create(input[:user], input[:params])
      Success(input.merge(article: article))
    end

    def subscribe_author(input)
      subscription = Articles::AuthorSubscription.new(input[:user], input[:article])
      subscription.create
      Success(input)
    end

    def refresh_auto_audience_segments(input)
      # NOTE: the naming might not be the best one for this case since I'm not aware about the actual business logic behind
      audience = Articles::Audience.new(input[:user])
      audience.refresh_segments
      Success(input)
    end

    def notify_subscribers(input)
      publication = Articles::SubscriberNotification.new(input[:article])
      publication.dispatch
      Success(input)
    end
  end
end

See, not only the business process is very well defined, but it also deals with domain-centric objects: Articles::ValidationContract, Articles::PublishingQuota, Articles::Repository, Articles::AuthorSubscription and etc.

⭐ Thanks to having a clear separation between Processes and Domain objects we'll stop pretending that we play in OOP game when dealing with service objects.

Let's imagine an ideal world where each app consisted of Process-like implementations. As a result, our app might look like a set of business processes. One process might start another as an async job, or some processes might be executed in the background on scheduled basis. Yet, it doesn't change the fact that an app consists of a set of business processes.

# Hotel Booking Process
module Bookings
  class HotelReservationProcess
    include Dry::Transaction

    step :check_room_availability
    step :calculate_total_cost
    step :process_deposit
    step :create_reservation
    step :send_confirmation
    step :schedule_reminders
  end
end

# User Registration Process
module Users
  class RegistrationProcess
    include Dry::Transaction

    step :validate_user_data
    step :check_unique_email
    step :create_user
    step :send_verification_email
    step :assign_default_roles
  end
end

I think it goes without saying that having a clear separation of processes and a set of domain-centric objects powering these processes is a cleaner way to write business logic. However, I understand that the "ideal" world and the "real" world are sometimes completely different pictures. It always boils down to engineering contracts established in a particular team or the whole organization, and sometimes it's not that easy to change habits, especially when we're talking about legacy production applications.

Nevertheless, what we can do is refine our mental models to try to perceive "business processes" instead of "some" objects, and incorporate the business language into the domain language of our system.

Nix first steps

Alexander Shagov — Wed, 04 Sep 2024 08:33:10 +0000

It might be overwhelming to dive into the Nix world, but this little glossary should help refine your understanding of the tools you might encounter when starting your journey.

UPD: I wrote one more short article to articulate why I prefer nix over non-nix setups in general: https://dev.to/alexander_shagov/why-use-nix-even-on-macos-786

Nix Package Manager – The core tool that allows declarative and reproducible package management.

NixOS – A Linux distribution built entirely on the Nix package manager. It's better to start with nix package manager alone before switching to NixOS completely.

Home Manager – Manages user packages, dotfiles, environment variables, shell configurations, and more. Allows for portable user environments across different machines.

Flakes – Provides a standardized structure for Nix projects, improving reproducibility and composability. It's worth noting that while Flakes are still technically experimental, they have been widely adopted by the Nix community due to their benefits. Many newer Nix configurations and projects are built using Flakes.

Old flow vs New flow

When you start searching for actual commands, you might encounter that some of them have different syntax (e.g., 'nix build' vs 'nix-build').

https://nixos-and-flakes.thiscute.world/nixos-with-flakes/introduction-to-flakes

Based on the article, there are two "flows" or approaches to using Nix: the old (or classic) flow and the new flow using flakes.

New Flow (Flakes and New CLI):

Introduces flake.nix and flake.lock files.
Uses new CLI commands that start with "nix" (e.g., nix develop, nix shell, nix build).
Replaces channels with explicit inputs in flake.nix.
Aims for improved reproducibility and composability.

Old Flow (Classic Nix):

Used commands like nix-channel, nix-env, nix-shell, and nix-build.
Relied on channels for package management.
Less standardized structure for Nix projects.
Could lead to less reproducible builds in some cases.

The new flow is essentially an evolution of Nix, addressing some limitations of the classic approach and borrowing ideas from other modern package managers (like npm, Cargo, etc.).

Assuming you're not using NixOS itself but, let's say, macOS, your flow of working with your development environment might look like this:

1) Use home-manager (preferably with flakes) to manage user-specific packages, tools, and configurations. This includes system-wide tools like Emacs, as well as dotfiles and environment settings.

2) For each project you're working on, create a flake.nix file to define the project-specific development environment and dependencies.

The aim of the article was to provide a good starting point and set up the mental model for further readings. Even though I didn't set a goal to share specific code snippets, here's the example of a home-manager (home.nix) file defining the global configuration on my MacOS. This configuration defines the global state of my system. Any project-related pieces live a in separate flake.nix files in their own namespaces. NOTE: I'm not using brew anyhow!


{ config, pkgs, ... }:

{
  home.username = "<username>";
  home.homeDirectory = "<homeDirectory>";

  home.stateVersion = "24.05";

  home.packages = with pkgs; [
    direnv
    ripgrep
    htop
    inetutils
    jq
    emacs29
    emacsPackages.vterm
  ];

  home.shellAliases = {
    # ============ git aliases =====================
    gs = "git status";
    gcm = "git checkout main && git pull";
    gc = "git checkout";
  };

  home.sessionVariables = {
    EDITOR = "emacs";
  };

  # ======== Zsh configuration ============

  programs.zsh = {
    enable = true; # Enable managing the Zsh configuration

    initExtra = ''

      # Private ENV vars configuration
      if [ -f ~/.bashrc_private ]; then
        . ~/.bashrc_private
      fi    

      # ========= Prompt with a branch ========
      function git_branch_name() {
           git rev-parse --abbrev-ref HEAD 2>/dev/null || echo '='
      }
      autoload -Uz colors && colors
      setopt prompt_subst
      prompt='%F{yellow}%~/%f [%F{green}$(git_branch_name)%f] > '

    '';
  };

  programs.direnv = {
    enable = true;
    # enableBashIntegration = true; # see note on other shells below
    nix-direnv.enable = true;
  };

  # Let Home Manager install and manage itself.
  programs.home-manager.enable = true;
}

Any time I need to add/remove system-wide package, or adjust, let's say, zsh configuration, it just boils down to editing the home.nix file and running the home-manager switch to apply the change (or home-manager build to see if a build compiles correctly).

Where to look for packages

Given you want to install htop. Just use the search.nixos.org and put the package name into your home.nix file. Run home-manager switch and you'll have your htop configured automatically (e.g. /Users/<username>/.nix-profile/bin/htop)

How to install a specific version of a package?

If you want to install a specific version of a package (not the latest one by default), you can search at nixhub.io. There, you'll see a specific Nixpkgs Reference you should use in your home.nix file to point to a specific version you're interested in.

Useful links for further reading

Introduction to Flakes: https://nixos-and-flakes.thiscute.world/nixos-with-flakes/introduction-to-flakes
Nix flakes syntax basics: https://serokell.io/blog/practical-nix-flakes
Official nix package manager step-by-step guide: https://nixos.org/guides/nix-pills/01-why-you-should-give-it-a-try
A good article where a person shows how they cleaned up their $HOME with nix: https://juliu.is/tidying-your-home-with-nix/

⭐ Comments and more useful articles for nix beginners appreciated!