Coder Legion - Recent posts tagged elixir

I built a Pix library for Elixir (and one cent proved it works)

Tue, 29 Sep 2026 00:34:58 +0000

Over the last few months I became a bit of a compulsive open source contributor. Translating Linux kernel documentation into Portuguese, a merged PR in uutils/coreutils, a few fixes in Elixir libraries I had used before. Always the same routine: find a problem in someone else's project, understand it, fix it, wait for review.

Then a different itch showed up: instead of fixing other people's libraries, build my own.

This post is about that. How I built pix_brcode, a Pix library for Elixir, over a weekend, tested it with real money (R$ 0.01, don't judge me) and published it on Hex. And about the bug that only showed up once a real bank got involved.

What is Pix, and why a library for it

If you're not from Brazil, you've probably never heard of Pix. It's the instant payment system created by Brazil's Central Bank in 2020, and it took over the country: it's free for individuals, settles in seconds, works 24/7, and today it's how Brazilians pay for everything from coffee to rent.

Most Pix payments start with a QR code, or with its text version, the "copia e cola" (copy and paste) code: a long string starting with 000201 that you paste into your bank app. Everyone uses it every day, and almost nobody knows what's inside it.

In the JavaScript world this is a solved problem: pix-utils on npm generates and parses Pix codes and gets over 60k downloads a month. I went looking for the equivalent on Hex, Elixir's package manager, and couldn't find a maintained one.

So I put the two things together: a big, mature library to use as a reference, and an empty spot in the ecosystem I wanted to fill. I decided to build a "pix-utils" for Hex, or, as I preferred to call it, pix_brcode.

What's inside a Pix code

That string is a BR Code: an international payment QR code standard (EMVCo's QR Code Specification, Merchant-Presented Mode) with Pix-specific fields.

The structure is simpler than it looks. Everything is TLV: a 2-digit ID, a 2-digit length, then the value.

00 02 01                       → payload format: "01"
26 58 0014br.gov.bcb.pix0136…  → Pix account (with subfields inside!)
52 04 0000                     → merchant category
53 03 986                      → currency: Brazilian real
54 04 0.01                     → amount
58 02 BR                       → country
59 04 Igor                     → receiver name
60 09 Sao Paulo                → city
62 07 0503***                  → txid (transaction id)
63 04 F6CE                     → CRC16

Look at field 26: its value is another TLV, holding the Pix identifier (br.gov.bcb.pix) and the key. TLV inside TLV.

And the last field, 63, is a CRC16: a checksum over everything before it. If someone copies the code missing one character, the CRC doesn't match and the bank app rejects it.

(Important side note: a CRC is not security. It catches accidental errors, not fraud. Anyone can recompute it.)

The decisions that made the weekend worth it

Zero dependencies

Installing pix_brcode pulls in nothing else. That had a cost: Erlang only ships CRC32, so the CRC16 was written by hand in about 20 lines, using Elixir's binary pattern matching:

defp crc(<<byte, rest::binary>>, acc) do
  acc = Enum.reduce(1..8, bxor(acc, byte <<< 8), fn _, acc -> shift(acc <<< 1) end)
  crc(rest, acc)
end

defp crc(<<>>, acc), do: acc

Adding a dependency for 20 lines would be trading a small problem for a permanent one.

Money is never a float

pix-utils takes the amount as a JavaScript number, which is a float. And floats with money are how you end up seeing 0.1 + 0.2 = 0.30000000000000004 on someone's bill.

In pix_brcode, the amount is either an integer in cents (1050 becomes "10.50") or an exact string ("10.50"). The conversion is done on text, with no division at all.

Strict in what you send, liberal in what you accept

When generating, the library is strict: a name longer than 25 characters is an error instead of being silently truncated (imagine the payer's bank app showing the wrong name). When parsing, it accepts whitespace and line breaks around the code, because real copy-and-paste comes dirty from WhatsApp.

That principle has a name, Postel's law. And it was about to be tested sooner than I expected.

The moment of truth: real money

Tests passing, Credo clean, docs generated. Only one test left that really matters: a bank app accepting the code.

The first try failed in all three banks I tested. Itaú, Nubank and Mercado Pago: "Invalid QR Code".

For a minute I thought the weekend was wasted. It wasn't: I had used a made-up Pix key. When you paste a static Pix code, the app looks the key up in the Central Bank's directory. Unknown key, rejected code. The test was wrong, not the library.

I generated it again with my real Itaú random key and an amount of one cent:

PixBrcode.encode(%{key: "my-real-key", amount: 1,
                   merchant_name: "Igor", merchant_city: "Sao Paulo"})

Pasted it into Nubank. My name showed up, R$ 0.01. Paid. It landed in my Itaú account instantly.

The best-invested cent of my life.

The bug no test caught

The reverse path was still missing: generate a code in the bank app and parse it with the library. Pix > Receive on Nubank, copy, paste into the terminal:

iex> PixBrcode.decode("00020126580014BR.GOV.BCB.PIX0136…")
{:error, :invalid_gui}

BR.GOV.BCB.PIX. In uppercase.

The Central Bank's manual writes br.gov.bcb.pix in lowercase, and the library compared the exact text. Nubank sends it uppercase. So does Itaú. All my tests passed because they all followed the manual to the letter, and the banks don't.

The fix was one line: compare case-insensitively when parsing, and keep generating lowercase, as the manual says. Postel again: strict in what you send, liberal in what you accept.

The real codes showed other differences too: Nubank includes the postal code (field 61) and puts part of the account holder's tax ID in the receiver name; Itaú doesn't. The library's tests now use payloads with the same layout as the real ones, but with fake data. (Your partial tax ID in a public repo is not a great idea, and I learned that before making the mistake.)

The lesson: the spec is the minimum. Real systems have variations that only show up with real data.

A second opinion before publishing

Before pushing to Hex, I had an AI agent do an independent code review: a fresh session, with no context from the development, reading everything from scratch. Nothing blocked the release, but it came back with four good findings:

the amount field didn't enforce the spec's 13-character limit;
decode(nil) raised an exception, while the README promised always {:ok, _} or {:error, _};
text with invalid bytes also crashed the library;
emoji in the name got through, and since each emoji takes several bytes, the length declared in the TLV was wrong for other parsers.

All four were fixed before v0.1.0. Name, city and description must now be ASCII after removing accents (São João becomes Sao Joao, and ☕ is an error).

What's next

v0.1.0 generates and parses static and dynamic Pix codes, validates keys (tax IDs, phone, e-mail, random key) and runs CI on three Elixir versions. Next on the list: typespecs, more tolerant key parsing and a CHANGELOG. And there's another idea in the queue: Brazilian boleto bank slips, which also have no package on Hex.

If you work with Elixir and Pix, try the library and tell me what breaks. Issues and PRs are very welcome:

Fixing other people's libraries taught me to read code. Building my own taught me that the manual is only the start of the conversation.

This post was originally published in Portuguese on Coisa de Dev.

Multi-Agent Metacognition and Causal Consensus via PON

Fri, 11 Sep 2026 13:20:25 +0000

Multi-Agent Metacognition and Causal Consensus via PON

Keywords: RAG, AI, architecture, backend, multi-agent systems, PON, causal consensus, metacognition

Abstract

As AI systems evolve from isolated single agents into multi-agent ecosystems, traditional architectures face a critical bottleneck: dependence on centralized orchestrators such as rigid state graphs, sequential pipelines, or master routing nodes.

In a centralized orchestrator, every agent must report to a coordinator that evaluates global state, polls subprocesses, and decides the next API call. The result is predictable:

Latency cascades: final response time becomes the linear sum of all agent executions plus the orchestrator’s serialization overhead.
State contention: the central node becomes a memory and CPU bottleneck.
Operational rigidity: failure of a master node interrupts the entire reasoning chain.

In nature, complex systems — from insect swarms to cortical neural networks — do not rely on a central controlling node. Consensus emerges from reactive interaction among autonomous parts that notify their immediate neighbors of state changes.

To build scalable multi-agent ecosystems, we must move from procedural orchestration to Causal Consensus based on the Notification-Oriented Paradigm (PON).

1. Theory of Mind in Distributed Agents

Theory of Mind is the cognitive ability to infer and represent the mental states, intentions, and knowledge of other individuals. In a distributed AI system, this means an agent should understand the context and capabilities of its peers without having to send explicit query messages such as “Are you free?” or “What do you know about X?”

In the PON kernel, each agent’s state is mapped directly into global/replicated state attributes:

┌────────────────────────────────────────────────────────────────────────┐
│               PON State Registry (In-Memory Attributes)               │
│                                                                        │
│  [Research_Agent]  ──► Status: Busy   │ Load: 85% │ Specialty: RAG     │
│  [Validator_Agent] ──► Status: Free   │ Load: 10% │ Specialty: Bacen   │
│  [Synthesis_Agent] ──► Status: Idle   │ Load: 0%  │ Specialty: LLM     │
└───────────────────────────────────┬────────────────────────────────────┘
                                    │
                         (Notification Propagation)
                                    │
                                    ▼
┌────────────────────────────────────────────────────────────────────────┐
│                        Direct Causal Notification                      │
│  Research_Agent updates its state ──► Notifies ONLY those that depend  │
│  on 'Status' and 'Specialty' without lookup requests (Zero Polling).   │
└────────────────────────────────────────────────────────────────────────┘

Instead of sending a prompt to query Agent B’s availability, Agent A reads the notified in-memory attribute at runtime with O(1) complexity. Theory of Mind stops being a heavy message exchange between LLMs and becomes a matrix of reactively notified states.

2. Causal Consensus and Latency Negotiation Without Locks

When multiple autonomous agents work on the same problem — for example, a vector RAG agent, a graph-search agent, and a regulatory validation agent — they often diverge or compete for execution time.

In the traditional model, synchronization locks or synchronous consensus algorithms such as adapted Paxos/Raft are used. These block threads until all participants respond.

With PON, consensus is strictly causal and reactive.

A. Consensus Rule Networks (Rule-Nets)

Convergence rules live inside the kernel itself. When the RAG_Agent changes the Partial_Response_V1 attribute, the consensus rule node is notified. If the rule requires N confirmations or a confidence threshold ≥ 0.85, the node evaluates the condition instantly:

Consensus_Rule:
IF (RAG_Score >= 0.85 AND Regulatory_Status == :approved)
THEN Trigger(Synthesis_Agent)

B. Dynamic Latency Negotiation (Window Shrinking)

If the Graph Search Agent realizes it will take 800 ms to complete its traversal, it updates its Estimated_Latency attribute.

This change instantly notifies the consensus rule node, which adaptively shrinks the waiting window and forces the system to decide with the evidence available at that moment, eliminating timeout overruns.

3. Reactive Conflict Resolution Without Blocking Loops

In scenarios where two agents generate contradictory hypotheses — for example, Agent A suggests “Approve Credit” while Agent B suggests “Reject Credit” — resolution occurs through causal notification propagation:

┌──────────────────────────────┐            ┌──────────────────────────────┐
│ Agent A: Hypothesis (Approve) │            │ Agent B: Hypothesis (Reject) │
└──────────────┬───────────────┘            └──────────────┬───────────────┘
               │                                           │
         (Updates State)                             (Updates State)
               │                                           │
               └─────────────────────┬─────────────────────┘
                                     │
                                     ▼
                      ┌──────────────────────────────┐
                      │   Conflict Node (Rule-Net)   │
                      │   - Evaluates DIVERGENCE     │
                      └──────────────┬───────────────┘
                                     │
                     (Notifies Metacognitive Subsystem)
                                     │
                                     ▼
                      ┌──────────────────────────────┐
                      │    Arbitration by Reasoning  │
                      │      System 2 (Slow Path)    │
                      └──────────────────────────────┘

The presence of contradictory values in the attributes triggers the Conflict Rule-Net.

This rule does not trap agents in while(true) loops; it generates an arbitration notification. The notification escalates the decision asynchronously to System 2 (Slow Path), while edge agents remain free to process other events from the queue.

4. Comparative Table: Centralized Multi-Agent vs. Causal Consensus via PON

Dimension	Centralized Orchestration (Graphs/Master)	Causal Consensus via PON
Architecture	Hierarchical / master routing node	Distributed / notification-based
Theory of Mind	Prompt/message exchange between nodes	Shared state attributes in O(1)
Conflict Resolution	Blocks the pipeline until resolved	Reactive: triggers asynchronous arbitration node
Adding Agents	Requires updating orchestrator logic	Agent simply subscribes to notifications of interest
CPU/Memory Bottleneck	High at the coordinator node	Distributed via atomic O(k) complexity
Latency	Sum of agent execution + serialization overhead	Event-driven, parallel, no central serialization

5. Conclusion: Emergence over Control

Trying to control complex AI networks through rigid centralized orchestrators repeats the mistakes of 1990s distributed computing.

True multi-agent metacognition requires an infrastructure where communication is as cheap as a state change itself. By integrating the Notification-Oriented Paradigm (PON) as the communication backbone between autonomous agents, we eliminate orchestration overhead and allow emergent consensus to happen at the speed of memory.

Getting Started with Elixir: Understanding Erlang, BEAM, and Your First Mix Project

Thu, 22 Jan 2026 23:35:11 +0000

Introduction

In the previous article, we covered how to set up the development environment to start working with Elixir.
Now it’s time to talk about the language itself and write our first real code.

If you are coming from languages like JavaScript, Ruby, or Python, some concepts may feel unfamiliar at first — and that’s totally normal.

Let’s start by understanding why we had to install both Elixir and Erlang.

Elixir vs Erlang

Erlang is a programming language created decades ago to solve problems related to telecommunication systems, such as reliability, concurrency, and fault tolerance.

It is extremely powerful, but its syntax is considered quite complex for many developers.

This is where Elixir comes in.

Elixir provides a modern and friendly syntax, while still running on top of the same runtime as Erlang.
In practice, your Elixir code is compiled to Erlang bytecode and executed by the same virtual machine.

What is BEAM?

BEAM stands for Bogdan/Björn’s Erlang Abstract Machine, named after its original creators.

It is the virtual machine responsible for running Erlang and Elixir code, similar to how the JVM runs Java and Kotlin.

BEAM is famous for:

Lightweight processes
Massive concurrency
Fault-tolerant design

This is one of the main reasons Elixir is used in systems that require high availability.

Creating Your First Project with Mix

The best way to learn a programming language is by building something.

Reading documentation and watching tutorials helps, but real learning happens when you actually write code.

In Elixir, we use Mix, the built-in build tool and project manager.

Mix is responsible for:

Creating projects
Compiling code
Managing dependencies
Running tasks and tests

Let’s create a new project.

In your terminal, run:

mix new basics

You should see an output similar to:

* creating README.md
* creating .formatter.exs
* creating .gitignore
* creating mix.exs
* creating lib
* creating lib/basics.ex
* creating test
* creating test/test_helper.exs
* creating test/basics_test.exs

Now enter the project directory:

cd basics

Modules and Functions

Inside the lib directory, you will find the file basics.ex with the following content:

defmodule Basics do
end

In Elixir, almost all code lives inside modules.

A module is simply a collection of functions.

Let’s add our first function:

defmodule Basics do
  def create_list do
    [1, 2, 3, "little indians"]
  end
end

We use def to define a function inside the Basics module.

Running the Project with IEx

To run and test our code, we use IEx (Interactive Elixir Shell).

It works like Python’s REPL or Ruby’s IRB, allowing you to run Elixir code interactively.

From the project directory, run:

iex -S mix

Now test the function:

Basics.create_list()

You should get:

[1, 2, 3, "little indians"]

Notice that the last expression is automatically returned.
This is called implicit return, which is common in functional programming.

Object-Oriented vs Functional Programming

In object-oriented languages, you usually create objects and call methods on them.

In functional programming, functions return values directly without relying on object instances.

In Elixir:

There are no classes
Modules are not objects
Functions return data

A module is just a namespace for functions, nothing more.

Understanding Arity

In Elixir, functions are identified not only by their name, but also by the number of arguments they receive.

This is called arity.

Let’s create a new function:

def shuffle(list) do
end

Now recompile inside IEx:

recompile

And try calling:

Basics.shuffle()

You will see an error similar to:

function Basics.shuffle/0 is undefined. Did you mean shuffle/1?

That means the function expects one argument.

Example:

defmodule Basics do
  def hello(), do: "Hello World"            # hello/0
  def hello(name), do: "Hello, #{name}"    # hello/1
  def hello(a, b), do: "#{a} and #{b}"      # hello/2
end

These are considered different functions because of their arity.

Arity is written as:

function_name/number_of_arguments

It becomes very important later when working with pattern matching and function clauses.

More about functions and arity:
https://elixirschool.com/en/lessons/basics/functions/

Conclusion

In this article we covered:

The relationship between Elixir and Erlang
What BEAM is and why it matters
How to create projects with Mix
How modules and functions work
What function arity means

In the next article, we’ll continue improving this project and exploring more Elixir features.

See you soon!

Elixir Setup Guide: Installing Erlang, Elixir, and Livebook with ASDF

Mon, 12 Jan 2026 20:42:17 +0000

Introduction

This article is part of a beginner series where I document my personal journey learning Elixir and taking my first real steps in its ecosystem.

I recently came from Node.js, where setting up a development environment is usually very simple: install Node, get npm, add some VS Code extensions, and you're ready to go.

With Elixir, the process is not hard, but I had a tough time finding a clear step-by-step guide. I ended up skipping important steps, which later caused a lot of unnecessary problems to fix.

So in this guide, I’ll walk you through how to set up your Elixir environment from scratch using ASDF.

Note: I’m using Linux Mint, but the same process applies to most Linux distributions with small adjustments.

What Is ASDF and Why Use It?

The first thing we’ll install is a small but very powerful tool called ASDF.

[ASDF][1] is a version manager that allows you to install and manage multiple versions of languages and runtimes — including Erlang and Elixir — on the same machine.

That means:

You can easily switch between versions
Projects can define their own required versions
Your global system stays clean

Grab some coffee ☕ and let’s start.

Step 1: Installing ASDF

First, go to the official website:
https://asdf-vm.com/

Click on Get Started and check the installation method for your operating system.

On Linux Mint (and Ubuntu-based distros), make sure you have curl and git installed:

sudo apt install curl git

Now clone the ASDF repository:

git clone https://github.com/asdf-vm/asdf.git ~/.asdf --branch v0.9.0

Shell Integration (Very Important)

This step is critical so your terminal can recognize the asdf command.

If you use Oh My Zsh

Follow the plugin instructions from:
https://github.com/ohmyzsh/ohmyzsh/tree/master/plugins/asdf

Basically, add this line to your ~/.zshrc file:

plugins=(git asdf)

Then close and reopen your terminal.

If you use Bash

Add these two lines to your ~/.bashrc file:

. $HOME/.asdf/asdf.sh
. $HOME/.asdf/completions/asdf.bash

Restart the terminal.

Verify Installation

Run:

asdf --version

You should see something similar to:

v0.9.0-9ee24a3

Step 2: Installing the Erlang Plugin

With ASDF installed, we can now install plugins. Let’s start with Erlang.

asdf plugin-add erlang

Installing System Dependencies

Before compiling Erlang, we must install some required packages.

For Linux Mint / Ubuntu 20-based systems:

sudo apt-get -y install build-essential autoconf m4 libncurses5-dev libwxgtk3.0-gtk3-dev libgl1-mesa-dev libglu1-mesa-dev libpng-dev libssh-dev unixodbc-dev xsltproc fop libxml2-utils libncurses-dev openjdk-11-jdk

These dependencies are listed in the official ASDF Erlang plugin repository:
https://github.com/asdf-vm/asdf-erlang

Step 3: Installing Erlang

List all available Erlang versions:

asdf list-all erlang

Install the latest stable version at the time of writing:

asdf install erlang 24.2.1

Tip: This step takes time and may look frozen. That’s normal. Be patient.

Set Erlang as Global Version

asdf global erlang 24.2.1

Test Erlang

erl

If you see the Erlang shell, everything is working.
Exit with Ctrl + C twice.

Step 4: Installing Elixir with ASDF

Now let’s install the Elixir plugin:

asdf plugin-add elixir

List available versions:

asdf list-all elixir

Since we installed Erlang OTP 24, we must install an Elixir version built for OTP 24.

At the time of writing:

asdf install elixir 1.13.3-otp-24

Set it globally:

asdf global elixir 1.13.3-otp-24

Test Elixir

Start IEx:

iex

You should see the Elixir interactive shell.

Hello World

Inside IEx:

IO.puts("Hello World")

Welcome to Elixir

Step 5: Using Livebook for Experiments and Notes

Livebook is similar to Jupyter Notebook for Python.

It allows you to:

Write executable Elixir code
Document your learning
Save notebooks as Markdown

Installing Livebook

Go to the official repository:
https://github.com/livebook-dev/livebook

Since Elixir is already installed globally, run:

mix escript.install hex livebook

Confirm installation when prompted.

Because we’re using ASDF, we must refresh shims:

asdf reshim

Start Livebook:

livebook server

Now open your browser and go to:

http://localhost:8080

Conclusion

In this article, we covered how to:

Install ASDF
Install Erlang
Install Elixir
Set up Livebook locally

This setup gives you a solid and flexible environment to start learning and building with Elixir.

In the next articles of this series, we’ll finally start writing real Elixir code.

See you in the next post ⚡