Forem

测试文章1DEV.to专属

ContextSpace — Sat, 18 Apr 2026 10:49:16 +0000

测试文章1DEV.to专属这篇文章将只发布到DEV.to平台## 内容特点- 针对DEV.to社区的技术文章- 使用直接内容模式- 包含代码示例

javascriptconsole.log('Hello DEV.to!');

适合开发者阅读的技术内容

Memorix: Give Your AI Coding Agents Shared, Persistent Project Memory

leho — Sat, 18 Apr 2026 10:48:37 +0000

TL;DR: Every coding agent forgets between sessions. Memorix is an open-source MCP memory layer that gives Cursor, Claude Code, Windsurf, and 7 other agents shared, persistent project memory — with Git truth and reasoning built in. npm install -g memorix and you're running.

The problem nobody talks about

You're working in Cursor. You tell it about a tricky database migration pattern. Next session? Gone. You switch to Claude Code to continue. It has no idea what Cursor just learned.

This isn't a bug — it's the default. Every AI coding agent is stateless between sessions. Each one lives in its own silo.

Some agents have started adding memory features, but they're all agent-specific. Cursor's memory doesn't help Claude Code. Claude Code's memory doesn't help Windsurf. And none of them know what actually happened in your git history.

What would "done right" look like?

I kept running into this problem across projects, so I built something to fix it properly. Here's what I think a cross-agent memory layer needs:

Shared, not siloed — Any agent can read and write to the same local memory base
Git is ground truth — Your commit history is the most reliable record of what actually happened. It should be searchable memory, not just log output
Reasoning, not just facts — "We chose PostgreSQL over MongoDB because of X" is more valuable than "database config changed"
Quality control — Without retention, deduplication, and formation, memory degrades into noise
Local and private — No cloud dependency. Your project memory stays on your machine

Memorix: a memory layer for coding agents

Memorix is an open-source MCP server that does all of the above. It runs locally, connects to your agents via the Model Context Protocol, and gives them a shared memory layer that persists across sessions and IDEs.

npm install -g memorix
memorix init
memorix serve

That's it. Your agent now has persistent project memory.

What it stores

Memorix has three memory layers:

Observation Memory — what changed, how something works, gotchas, problem-solution notes
Reasoning Memory — why a decision was made, alternatives considered, trade-offs, risks
Git Memory — immutable engineering facts derived from your commit history, with noise filtering

How agents use it

Once Memorix is connected via MCP, your agents can:

memorix_store — save a decision, gotcha, or observation
memorix_search — find relevant past context
memorix_detail — get the full story behind a result
memorix_timeline — see the chronological context around a memory
memorix_store_reasoning — record why a choice was made, not just what changed

And you don't have to manually trigger these — Memorix's hooks can auto-capture git commits, and the memory formation pipeline automatically deduplicates, merges, and scores incoming memories.

The Git memory angle

This is the part I'm most excited about. Install the post-commit hook:

memorix git-hook --force

Now every commit becomes searchable engineering memory — with noise filtering that skips lockfile bumps, merge commits, and typo fixes. When you ask your agent "what changed in the auth module last week?", it can answer from actual git history, not just what someone bothered to write down.

Cross-agent in practice

Here's a real workflow:

Cursor identifies a tricky caching bug and stores the root cause
Claude Code picks up the same project next session, searches memory, finds the bug context
Windsurf fixes the bug and stores the reasoning behind the fix
Next week, Copilot encounters a similar pattern and finds the prior reasoning

No copy-pasting context. No repeating explanations. The memory is just there.

10 agents, one memory

Memorix currently supports:

Tier	Clients
★ Core	Claude Code, Cursor, Windsurf
◆ Extended	GitHub Copilot, Kiro, Codex
○ Community	Gemini CLI, OpenCode, Antigravity, Trae

If a client can speak MCP and launch a local command or HTTP endpoint, it can usually connect even if it's not listed.

How this differs from other memory tools

Most MCP memory servers focus on one thing: storing and retrieving text snippets. Memorix takes a different approach:

Git-grounded, not just user-stored — Your commit history is the most reliable record of what actually happened in a project. Memorix turns it into searchable memory automatically, instead of relying entirely on what agents or users manually save
Reasoning, not just facts — Storing "database config changed" is easy. Storing "we chose PostgreSQL over MongoDB because of X, Y, Z" is what actually helps future decisions
Cross-agent by design, not by accident — The memory layer is shared across all connected agents from day one, not bolted on as an afterthought
Quality pipeline, not just storage — Without dedup, compaction, and retention, memory degrades into noise over time. Memorix handles this automatically

What's running under the hood

SQLite as the single source of truth — observations, mini-skills, sessions, and archives all share one DB handle
Orama for fast full-text and semantic search
Memory formation pipeline — formation, compaction, retention, and source-aware retrieval work together
Team identity — agent registration, heartbeat, task board, handoff artifacts for multi-agent coordination
HTTP control plane — memorix background start gives you a dashboard + shared HTTP endpoint for multiple agents

Try it

npm install -g memorix
memorix init
memorix serve

Add to your MCP client config:

{
  "mcpServers": {
    "memorix": {
      "command": "memorix",
      "args": ["serve"]
    }
  }
}

Links:

GitHub: https://github.com/AVIDS2/memorix
npm: https://www.npmjs.com/package/memorix
Docs: https://github.com/AVIDS2/memorix/tree/main/docs

Memorix is Apache 2.0. If you're using multiple coding agents and tired of them forgetting everything, I'd love your feedback.

Tags: #ai #coding #mcp #developer-tools #opensource

Self-Hosted VPN: Benefits, Trade-Offs, and When It Makes Sense

CacheGuard Technologies — Sat, 18 Apr 2026 10:47:24 +0000

A self-hosted VPN is not about replacing commercial services.

It is about control and understanding your network.

🧪 Benefits

🔒 Control

You define encryption, authentication, and access rules.

🌍 Privacy

No third-party provider processes your traffic.

🧑‍💻 Learning

You gain real-world networking experience:

VPN protocols
Network design
Security models

⚠️ Trade-Offs

Maintenance

Updates required
Security responsibility is yours

Performance

Limited by home internet bandwidth

Risk

Misconfiguration can expose services

🧠 When It Makes Sense

Home labs
Self-hosted infrastructure
Networking learning
Remote access setups

🚀 Final Thought

A self-hosted VPN is not just a tool.

It is a way to understand how the internet actually works.

How to Set Up Diction: The Self-Hosted Speech-to-Text Alternative to Wispr Flow

Ondrej Machala — Sat, 18 Apr 2026 10:44:08 +0000

This article is about getting your own private speech-to-text on your iPhone. Tap a key, speak, watch the words land in whatever app you're in. No cloud in the middle, no subscription, no company on the other end reading what you said. The keyboard is Diction. This post is the full setup, start to finish, blank machine to working dictation in under thirty minutes.

I built the server side for myself. I talk to my AI agents all day. Claude in the terminal, my Telegram bot OpenClaw, a handful of others. Voice for everything. Long prompts, half-formed plans, emails I want rewritten, code I want reviewed. Every word used to pass through someone else's transcription cloud before my own agents ever heard it. Not anymore.

A small Docker stack on a box at home now handles the transcription. An optional cleanup step scrubs filler words and fixes punctuation using any LLM you want: OpenAI, Groq, a local Ollama model, anything OpenAI-compatible.

Every command is below.

What You'll End Up With

A box at home running the speech model, 24/7
Your iPhone sending audio to it over your home WiFi
Optional: an LLM of your choice for cleaning up filler words and fixing punctuation (OpenAI, Groq, Anthropic, a local Ollama model, anything with an OpenAI-compatible API)
Total running cost with cleanup on: depends on the LLM you pick. Roughly a cent per hour of dictation on gpt-4o-mini, zero if you run a local model.

The speech part is free forever. The cleanup part costs whatever your LLM provider charges. Use a local model and pay nothing. More on that at the end.

What You Need

Any machine that can run Docker: Mac mini, an old laptop, a home server in a closet, a NUC, a home lab box. Apple Silicon or any modern x86 works fine. Raspberry Pi is a stretch for the speech part. Anything newer is comfortable.
An iPhone running iOS 17 or newer
Both on the same WiFi network
Optional: an API key for any OpenAI-compatible LLM (OpenAI, Groq, Together, Anthropic via a proxy, Ollama running locally, etc.) if you want AI cleanup

I'll assume you know what Docker is and how to open a terminal. That's it.

Step 1: Install Docker

You need Docker Engine plus Docker Compose. Both come bundled in Docker Desktop on Mac and Windows. On Linux you install them separately (they're both free and open source).

macOS (Intel or Apple Silicon): Download Docker Desktop, open the .dmg, drag the whale icon to Applications, launch it. The first run asks for admin credentials (it needs to install a helper tool and set up networking). When the whale icon in the menu bar stops animating and says "Docker Desktop is running", you're ready.

Windows: Download Docker Desktop. The installer will enable WSL2 if it's not already on - this is required, and needs a reboot. After the reboot, launch Docker Desktop. Same whale icon in the system tray tells you when it's ready.

Linux: Either install Docker Desktop (same download page) or go with the native packages:

# Ubuntu / Debian
sudo apt update
sudo apt install docker.io docker-compose-plugin

# Fedora / RHEL
sudo dnf install docker docker-compose-plugin

# Arch
sudo pacman -S docker docker-compose

Start the service and add your user to the docker group so you don't need sudo every time:

sudo systemctl enable --now docker
sudo usermod -aG docker "$USER"

Log out and back in (or reboot) so the group change takes effect. Yes, you really need to log out. Running newgrp docker works too but only in the current shell.

Verify it's all working:

docker --version
docker compose version
docker run --rm hello-world

The last command pulls a tiny test image and prints a greeting. If it fails with "permission denied" on Linux, you skipped the log-out-and-back-in step.

Apple Silicon users, one extra thing: open Docker Desktop → Settings → General and make sure "Use Rosetta for x86/amd64 emulation" is enabled. This is the default on recent Docker Desktop builds. The Diction gateway image is built for amd64 (multi-arch is on the roadmap), so Docker needs Rosetta to run it on your M1/M2/M3/M4. Performance impact is negligible - the speech model image is multi-arch and runs natively on arm64, so Rosetta is only handling the small Go binary in front of it.

While you're in Settings, also check Resources → Memory. The default Docker Desktop VM ships with 2 GB, which is tight for medium (~2.1 GB) and will OOM silently. Bump to 4 GB if you're running anything above small.

Step 2: Create a Project Folder

Pick a home for the compose file and any supporting config. Anywhere works. I use ~/diction:

mkdir -p ~/diction && cd ~/diction

Everything in the rest of this article assumes you're sitting in that folder. Docker Compose looks for docker-compose.yml in the current directory, so all the docker compose commands Just Work as long as you cd ~/diction first.

If you're setting this up on a remote server (Linux box in a closet, NUC, etc.), SSH in and run the same command there. Where you edit the file is up to you: nano docker-compose.yml on the server, VSCode Remote-SSH, or editing locally and scp-ing the file over. All fine.

Step 3: Write the Compose File

Here's what we're about to spin up. Two containers working together:

Diction Gateway. The open-source Go service at the front of the stack. On the outside it speaks the standard OpenAI transcription API (POST /v1/audio/transcriptions), which is what the Diction iPhone app talks to. On the inside it routes your audio to whichever speech model you've loaded, and optionally passes the transcript through an LLM for cleanup. The source is on GitHub, MIT licensed. Small, boring Go. Read it, fork it, bend it to your needs.
A voice model. The engine that actually turns audio into text. For this starter stack we're using faster-whisper - a compact, battle-tested open-source model that ships in sizes tiny, base, small, medium, large-v3, and large-v3-turbo. Bigger means more accurate and slower. We'll run small. It's the sweet spot for CPU-only machines: accurate enough for real dictation, transcribes a 5-second clip in 1 to 2 seconds on a modern Mac mini or NUC.

If you've got an NVIDIA GPU sitting in the machine, you can skip small and run something far better (Parakeet or large-v3-turbo). Jump to the "Got an NVIDIA GPU Sitting Idle?" section below before you paste the compose file. Otherwise continue here.

Paste this into ~/diction/docker-compose.yml:

services:
  whisper-small:
    image: fedirz/faster-whisper-server:latest-cpu
    container_name: diction-whisper-small
    restart: unless-stopped
    volumes:
      - whisper-models:/root/.cache/huggingface
    environment:
      WHISPER__MODEL: Systran/faster-whisper-small
      WHISPER__INFERENCE_DEVICE: cpu

  gateway:
    image: ghcr.io/omachala/diction-gateway:latest
    platform: linux/amd64
    container_name: diction-gateway
    restart: unless-stopped
    ports:
      - "8080:8080"
    depends_on:
      - whisper-small
    environment:
      DEFAULT_MODEL: small

volumes:
  whisper-models:

What each line does

Quick tour so you know what you're pasting.

whisper-small service:

image: fedirz/faster-whisper-server:latest-cpu. The voice model engine. faster-whisper is a C++/CTranslate2 reimplementation of the original open-source voice model from OpenAI, running 4x faster with less memory. fedirz/faster-whisper-server wraps it in a small Python server that speaks the OpenAI transcription API. The -cpu tag is the CPU build. There's also a -cuda tag for NVIDIA users (see the GPU section below).
container_name: diction-whisper-small. Just a friendly name so docker ps shows something readable instead of a random string.
restart: unless-stopped. If the container crashes or the host reboots, Docker brings it back. The only thing that stops it is you explicitly running docker compose down.
volumes: - whisper-models:/root/.cache/huggingface. The model weights are downloaded on first start (about 500MB for small). This volume persists them across container rebuilds, so you don't re-download every time you pull a newer image.
WHISPER__MODEL: Systran/faster-whisper-small. The specific voice model to load. It's a HuggingFace repo ID. You can swap this for any CT2-compatible voice model.
WHISPER__INFERENCE_DEVICE: cpu. Tells it to run on CPU. Swap to cuda if you've got an NVIDIA card (full example in the GPU section below).

gateway service:

image: ghcr.io/omachala/diction-gateway:latest. The Diction gateway from GitHub Container Registry.
platform: linux/amd64. The current published image is amd64-only. On Apple Silicon, Docker will run it under Rosetta transparently. Drop this line on a native x86 host if you want the error message to be slightly tidier on docker compose config.
ports: - "8080:8080". Maps port 8080 on the host to 8080 in the container. This is the one your iPhone will talk to. If 8080 is already in use on your machine, change the left side: "18080:8080" and use http://your-ip:18080 from the phone.
depends_on: - whisper-small. Docker starts the whisper container first so the gateway doesn't throw connection-refused on startup. Not strictly required (the gateway retries), but makes logs cleaner.
DEFAULT_MODEL: small. The model the gateway routes to when the iPhone sends a request without specifying one. The gateway has a built-in mapping of short names (small, medium, large-v3-turbo, parakeet-v3) to backend service URLs. Setting DEFAULT_MODEL: small makes it expect a service named whisper-small on port 8000. This is why the first service is named whisper-small and not whisper.

volumes: block at the bottom: declares the named volume Docker uses for the model cache. Named volumes are managed by Docker itself and survive container rebuilds.

Model sizes and what to pick

small is the starter. It's accurate enough for everyday dictation and fits comfortably on any modern laptop or NUC. If you want something else, swap WHISPER__MODEL in the compose file:

Model	Parameters	RAM	CPU latency (5s clip)	Notes
`Systran/faster-whisper-tiny`	39M	~350 MB	1-2s	Fast, lower accuracy
`Systran/faster-whisper-small`	244M	~850 MB	3-4s	Sweet spot for CPU
`Systran/faster-whisper-medium`	769M	~2.1 GB	8-12s	More accurate, slow on CPU
`deepdml/faster-whisper-large-v3-turbo-ct2`	809M	~2.3 GB	<2s on GPU	Best with NVIDIA

The latency numbers are from my own homelab (AMD Ryzen 9 7940HS, CPU-only). Apple Silicon is in the same ballpark: fast enough for small to feel instant, slow enough that medium will make you wait.

Two rules when switching models:

Also change DEFAULT_MODEL on the gateway to match one of: tiny, small, medium, large-v3-turbo.
Rename the service to the one the gateway expects: whisper-tiny, whisper-small, whisper-medium, or whisper-large-turbo. The gateway looks up its backend by service hostname.

Skip either and the gateway will give you a 404 when the app asks for a model.

One caveat for Mac mini / Apple Silicon users

Docker on macOS runs everything inside a Linux VM. That VM can't reach Apple's GPU or Neural Engine. Containers are CPU-only regardless of how nice your M4's GPU is. Sounds bad on paper, but for dictation workloads you won't feel it: the small voice model handles a short sentence well under five seconds on an M-series CPU. Longer dictations scale linearly. If you want GPU speed, either (a) run a Linux box with an NVIDIA card and keep the Mac as a client, or (b) use Diction's on-device mode on the iPhone itself (Core ML on the Neural Engine).

Step 4: Start Everything

Make sure you're in the project folder, then:

docker compose up -d

The -d flag runs the containers in the background (detached mode).

On the first run this takes a minute or two. Docker pulls two images from their registries:

fedirz/faster-whisper-server:latest-cpu - about 1.7 GB, includes the Python runtime and CTranslate2 binaries
ghcr.io/omachala/diction-gateway:latest - about 210 MB, a compiled Go binary plus ffmpeg for audio conversion

After the pulls finish, the voice model container does one more thing on first boot: it downloads the model weights from HuggingFace into the whisper-models volume (~500 MB for small). Subsequent restarts skip this step - the volume is persistent. That's why there's a volumes: block in the compose file.

Check everything is healthy

docker compose ps

You should see both services:

NAME                     STATUS
diction-gateway          Up 30 seconds
diction-whisper-small    Up 30 seconds (health: starting)

health: starting on the whisper container is normal for the first couple of minutes. It's loading the model into RAM. Once that's done, the status will flip to Up (healthy) or just Up.

Watching logs

If something looks wrong, look at the logs:

docker compose logs -f

-f follows them in real time. Ctrl+C to detach.

You can also tail a single service:

docker compose logs -f gateway
docker compose logs -f whisper-small

What healthy logs look like (abbreviated):

Gateway:

{"level":"info","msg":"gateway starting","port":"8080"}
{"level":"info","msg":"backend registered","name":"small","url":"http://whisper-small:8000"}

Whisper:

INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8000

Common early errors:

pull access denied on the gateway image. A stale GitHub Container Registry token is cached in your Docker config (on macOS, usually in the login keychain from a past docker login). Run docker logout ghcr.io - yes, even if you don't think you're logged in - and try again.
exec format error on Apple Silicon. Rosetta isn't enabled. Go back to Docker Desktop → Settings → General and flip the Rosetta option on.
The voice model container stuck on health: starting for more than 3 minutes. Usually means it's still downloading weights on a slow connection. Check docker compose logs -f whisper-small to see the download progress.

Stopping and restarting

docker compose stop        # stop containers, keep their state
docker compose start       # start them again
docker compose down        # stop and remove containers (volumes survive)
docker compose down -v     # stop, remove containers AND volumes (re-downloads weights)
docker compose pull        # get newer images
docker compose up -d       # apply pulls / config changes

The model cache in the whisper-models volume is shared across rebuilds, so docker compose pull && docker compose up -d to upgrade is a ~30-second operation.

Step 5: Test It

Before you go anywhere near the iPhone, prove the server itself works. A broken stack is easier to debug from a terminal than from a keyboard extension.

Get an audio file

The quickest path: use your phone's built-in Voice Memos app. Record yourself saying "Hello from my home server." Hit stop. Share → Save to Files, or AirDrop to your Mac, or email it to yourself. You want the .m4a file on the same machine that's running the containers.

On Linux without a phone handy, record with arecord or sox:

# 5 seconds of 16-bit mono WAV at 16 kHz - whisper's native format
arecord -f S16_LE -r 16000 -c 1 -d 5 voice-memo.wav

On macOS, skip recording altogether and let the system generate a clip with say:

say -o voice-memo.aiff "Hello from my home server"

That gives you an .aiff the gateway accepts directly. Handy for scripted testing where you don't feel like holding a microphone.

No microphone and no speech synth? Grab any short speech clip you have lying around. MP3, WAV, M4A, AIFF, FLAC, Ogg - they all work. The voice model handles re-encoding internally.

Hit the gateway

curl -X POST http://localhost:8080/v1/audio/transcriptions \
  -F "file=@voice-memo.m4a" \
  -F "model=small"

You'll get back something like:

{"text":"Hello from my home server."}

That's the whole speech pipeline. Running on your hardware. Your audio never left the box.

Ask for different response formats

The same endpoint supports response_format=text if you'd rather have a plain string (useful if you're piping it into a shell):

curl -X POST http://localhost:8080/v1/audio/transcriptions \
  -F "file=@voice-memo.m4a" \
  -F "model=small" \
  -F "response_format=text"
# → Hello from my home server.

Check the response headers

The gateway adds timing info to the response headers - useful for benchmarking without reading logs:

curl -sS -D - -o /dev/null -X POST \
  http://localhost:8080/v1/audio/transcriptions \
  -F "file=@voice-memo.m4a" -F "model=small"

Look for:

X-Diction-Whisper-Ms - how many milliseconds the speech model took
X-Diction-LLM-Ms - appears only if you've enabled the cleanup step in Step 7

Talk to it from Python

Since the gateway speaks the OpenAI transcription API, the official openai Python SDK works against it directly. Useful if you want to script transcriptions from a laptop:

from openai import OpenAI

client = OpenAI(
    base_url="http://192.168.1.42:8080/v1",
    api_key="anything",   # the gateway doesn't check this by default
)

with open("voice-memo.m4a", "rb") as f:
    result = client.audio.transcriptions.create(
        file=f,
        model="small",
        response_format="text",
    )

print(result)

Same story with the Node SDK, LangChain, or any other tool that expects OpenAI's speech API. Diction becomes a drop-in local replacement for api.openai.com/v1/audio/transcriptions.

If the test fails

Connection refused. The gateway container isn't running. docker compose ps to confirm.
504 Gateway Timeout. The whisper container is still starting (model loading into RAM). Give it another 60 seconds.
400 Bad Request: "invalid audio file". Your file is corrupted or in a format whisper doesn't understand. Try a freshly recorded clip.
404 Not Found. You probably have a typo in the URL. The path is exactly /v1/audio/transcriptions - plural, with /v1/ prefix.
Empty response / hang. The voice model container crashed out of memory mid-transcription. Check docker compose logs whisper-small. small should be fine on any machine with 2GB of free RAM; if you upgraded to medium and the host doesn't have 3GB free, it'll OOM.

Step 6: Find Your Server's LAN IP

Your iPhone needs an address to reach this. Your server probably has two kinds: a public IP (facing the internet, you don't want to use that) and a private LAN IP (on your home WiFi, that's the one).

macOS:

ipconfig getifaddr en0

en0 is usually Wi-Fi on laptops and the built-in Ethernet on desktops. If it prints nothing (you're wired via a USB-C dongle, or on a Mac mini with Wi-Fi off), the right interface is somewhere else - try en1, en4, en5. Quickest catch-all:

ifconfig | grep 'inet ' | grep -v 127.0.0.1

Pick the 192.168.x.x or 10.x.x.x address. Ignore anything starting with 100. - that's Tailscale, not your LAN.

Linux:

hostname -I | awk '{print $1}'

Or, if you want a specific interface:

ip -4 addr show wlan0 | grep inet

Windows:

ipconfig | findstr IPv4

You'll get something like 192.168.1.42. Write it down. This is what you'll paste into the Diction app in Step 8.

Pin it so it doesn't drift

Your router hands out IPs via DHCP, which means the one you just wrote down might change next time the server reboots (or when the lease expires). Two ways to keep it stable:

DHCP reservation. Log into your router's admin page (usually 192.168.1.1, 192.168.0.1, or 10.0.0.1). Find the DHCP client list, locate your server by hostname or MAC address, and click the "reserve" / "static" option. From then on, your router will always hand out that same IP to that machine.
Static IP on the machine. On Linux, edit /etc/netplan/ or use your distro's network manager. On macOS, System Settings → Network → Wi-Fi → Details → TCP/IP → Configure IPv4 → Using DHCP with manual address. More work, more fragile. The router method is better.

If you'd rather not deal with IPs at all and your setup is more portable (laptop moving between networks, for example), skip ahead to the "Reach It From Anywhere" section. Tailscale gives every machine a stable private address that follows it around.

Step 7: Add AI Cleanup (Optional but Nice)

Skip this step and your dictation still works. You'll get raw transcription, which is usually 95% right. The remaining 5% is filler words ("um", "like"), missing commas, misheard homophones ("their" vs "there"), and sometimes a full sentence with no punctuation. AI cleanup fixes all of that before your agent ever sees it.

What it does

You say:

so um basically the meeting went well and uh they agreed to the timeline

The gateway hands that to the LLM, which returns:

The meeting went well. They agreed to the timeline.

That's the whole feature. Any OpenAI-compatible LLM works - OpenAI's own models, Groq, Anthropic (via a compatibility proxy), Together, Fireworks, a local Ollama install, anything that speaks POST /chat/completions.

The flow

iPhone → gateway → voice model → raw transcript
                              ↓
                    your LLM (chat/completions)
                              ↓
                    cleaned text → back to the iPhone

The iPhone sends ?enhance=true on the request when the app's AI Companion toggle is on. The gateway hits {LLM_BASE_URL}/chat/completions with your system prompt + the transcript. Whatever comes back gets sent to the iPhone instead of the raw transcript. If the LLM errors out or times out, the gateway falls back to raw - your dictation doesn't break because of a downstream hiccup.

Config reference

Four environment variables on the gateway:

Variable	Required	What it is
`LLM_BASE_URL`	yes	OpenAI-compatible endpoint, e.g. `https://api.openai.com/v1`
`LLM_MODEL`	yes	Model identifier, e.g. `gpt-4o-mini`
`LLM_API_KEY`	no	Bearer token (your provider's API key). Not needed for local Ollama.
`LLM_PROMPT`	no	System prompt. Literal string, or a file path starting with `/` if you want a longer one mounted as a volume.

Both LLM_BASE_URL and LLM_MODEL must be set for cleanup to turn on. Miss either one and the feature silently stays off.

Option A: OpenAI (or any OpenAI-compatible provider)

Easiest first step. Get a key at platform.openai.com/api-keys and add $5 of credit. For cleanup that's hundreds of hours of dictation.

Create ~/diction/.env:

echo "OPENAI_API_KEY=sk-your-key-here" > ~/diction/.env

Update the gateway service in docker-compose.yml:

  gateway:
    image: ghcr.io/omachala/diction-gateway:latest
    platform: linux/amd64
    container_name: diction-gateway
    restart: unless-stopped
    ports:
      - "8080:8080"
    depends_on:
      - whisper-small
    environment:
      DEFAULT_MODEL: small
      LLM_BASE_URL: "https://api.openai.com/v1"
      LLM_API_KEY: "${OPENAI_API_KEY}"
      LLM_MODEL: "gpt-4o-mini"
      LLM_PROMPT: "Clean up this voice transcription. Remove filler words (um, uh, like). Fix punctuation and capitalization. Return only the cleaned text, nothing else."

Docker Compose reads ${OPENAI_API_KEY} from the .env file in the same folder automatically. No extra flags needed.

Not tied to OpenAI. Every major LLM provider exposes the same OpenAI-compatible /chat/completions endpoint. Swap the three LLM_* URLs and keys and you're done. A few that work out of the box:

Anthropic - Claude models via the OpenAI SDK
Groq - fastest inference on the market, generous free tier
Together AI - broad open-model catalog
Fireworks - tuned Llama and Mixtral hosting
DeepInfra - pay-per-token open models
OpenRouter - one key, hundreds of models from every provider
Mistral - native OpenAI-compatible endpoint

Pick one, drop its LLM_BASE_URL and LLM_MODEL into the compose file, same shape.

Option B: Local with Ollama (zero cost, fully private)

If you've got enough RAM and want nothing leaving your house - not even the transcribed text - run the LLM locally.

Add a third service to your compose file:

  ollama:
    image: ollama/ollama:latest
    container_name: diction-ollama
    restart: unless-stopped
    ports:
      - "11434:11434"
    volumes:
      - ollama-models:/root/.ollama

And update the gateway service:

  gateway:
    image: ghcr.io/omachala/diction-gateway:latest
    platform: linux/amd64
    container_name: diction-gateway
    restart: unless-stopped
    ports:
      - "8080:8080"
    depends_on:
      - whisper-small
      - ollama
    environment:
      DEFAULT_MODEL: small
      LLM_BASE_URL: "http://ollama:11434/v1"
      LLM_MODEL: "gemma2:9b"
      LLM_PROMPT: "Clean up this voice transcription. Remove filler words. Fix punctuation and capitalization. Return only the cleaned text, nothing else."

Add the Ollama volume to the bottom of the file:

volumes:
  whisper-models:
  ollama-models:

Bring it up and pull a model:

docker compose up -d
docker exec diction-ollama ollama pull gemma2:9b

LLM_API_KEY isn't needed - Ollama doesn't check it.

Which Ollama model?

Sizes below are memory footprint - system RAM if you run Ollama on CPU, VRAM if you pass a GPU through to the container. Either way the number is the same.

Model	Params	Memory	Notes
`gemma2:9b`	9B	~6 GB	Best editing quality at this size. My pick.
`qwen2.5:7b`	7B	~5 GB	Strong at following cleanup instructions.
`llama3.1:8b`	8B	~5 GB	Most popular, well-tested.
`gemma3:4b`	4B	~3 GB	For tighter machines. Still OK for basic cleanup.

Under 7B tends to fail in a specific, annoying way: the model treats your transcript as a question and tries to answer it, instead of cleaning it up. Stick to 7B+ if you can spare the memory.

If you have an NVIDIA GPU, pass it through to the Ollama container (same reservation block as the voice model GPU example further down) and you'll get 5-10x faster cleanup.

Apply the changes

Once your compose file has the LLM_* variables set, restart the gateway so it picks them up:

docker compose up -d

Docker Compose detects the env change and recreates only the gateway container. The voice model container (and its loaded model) keeps running.

Test the cleanup

Same voice memo as before, with ?enhance=true appended:

curl -X POST "http://localhost:8080/v1/audio/transcriptions?enhance=true" \
  -F "file=@voice-memo.m4a" \
  -F "model=small"

Without ?enhance=true you get the raw transcription. With it, the gateway sends the transcript through the LLM before returning. Quickest sanity check: record yourself saying some filler words ("um, this is uh a test like") and watch them disappear.

To confirm the LLM is actually running (and wasn't silently disabled because of a missing env var), check the response headers for X-Diction-LLM-Ms:

curl -sS -D - -o /dev/null -X POST \
  "http://localhost:8080/v1/audio/transcriptions?enhance=true" \
  -F "file=@voice-memo.m4a" -F "model=small" | grep -i diction

You should see both X-Diction-Whisper-Ms and X-Diction-LLM-Ms in the output.

Dialing in the prompt

The default prompt above is fine for generic cleanup. Adjust it to your taste. Some real prompts I've tried:

Conservative cleaner (preserves your voice, just fixes obvious errors):

Clean up this voice transcription. Fix punctuation and obvious typos only.
Do not rephrase or change word choice. Return only the cleaned text.

Email-ready rewriter (turns rambling into something you could actually send):

Rewrite this voice note as a short professional email. Keep the meaning intact.
Return only the rewritten text, no greeting or sign-off.

Bullet-pointer (for dumping meeting notes):

Convert this voice note into a bulleted list of the key points.
One bullet per idea. Return only the list.

Translator (I dictate in English, send in German):

Translate this English voice note into natural German. Return only the translation.

Long prompts via a file

If your prompt is more than a one-liner, mount it as a file. Create ~/diction/cleanup-prompt.txt:

You are a transcript cleaner.

Rules:
- Remove filler words (um, uh, er, like, you know).
- Fix grammar and punctuation.
- Preserve the speaker's voice and meaning.
- Common speech-to-text errors: "there / their / they're", "affect / effect".
- Do not add a preamble.
- Return only the cleaned text.

Mount it into the container and point LLM_PROMPT at the file path:

  gateway:
    image: ghcr.io/omachala/diction-gateway:latest
    # ... rest of config
    volumes:
      - ./cleanup-prompt.txt:/config/cleanup-prompt.txt:ro
    environment:
      LLM_BASE_URL: "https://api.openai.com/v1"
      LLM_API_KEY: "${OPENAI_API_KEY}"
      LLM_MODEL: "gpt-4o-mini"
      LLM_PROMPT: "/config/cleanup-prompt.txt"

If LLM_PROMPT starts with /, the gateway reads it as a file path. Otherwise it uses the string directly.

Why gpt-4o-mini or a 7B local model instead of something bigger

Cleanup is a simple task. The LLM only needs to polish, not reason. A frontier-tier model is overkill and slower. gpt-4o-mini (cloud) or gemma2:9b (local) hit the sweet spot for this workload. Save the expensive models for your actual conversations with the agent downstream.

Step 8: Install Diction and Point It at Your Server

Server's ready. Time to put the keyboard in front of it.

Install the app

On your iPhone, open the App Store and install Diction. It's free to download, and the modes you need for self-hosting (the entire point of this article) are free forever.

First run

Open the app. It walks you through three things:

Add the keyboard. iOS requires you to manually add any third-party keyboard. The app sends you to Settings → General → Keyboard → Keyboards → Add New Keyboard → Diction. Tap "Diction", then go back.
Allow Full Access. Back in Keyboards, tap "Diction" in the list and flip "Allow Full Access" on. iOS will show a scary-sounding warning. It's required for any keyboard that makes network requests, which Diction has to do (it sends audio to your server). Diction has no QWERTY input, no text logging, and no analytics - there's nothing to capture even if it wanted to. Only the mic audio leaves the phone, and only to the endpoint you configure below. The source for the gateway is on GitHub, so you can audit exactly what the server does with the audio.
Grant microphone access. Back in the app, it asks for mic permission. Yes.

Point it at your server

Inside the Diction app:

Go to Settings (gear icon, top right).
Tap Mode. Choose Self-Hosted.
Tap Endpoint. Enter http://192.168.1.42:8080 (substituting your server's IP from Step 6).
Scroll down. If you configured AI cleanup in Step 7, toggle AI Companion on.
Tap Test connection. You should see a green check within a second or two. If not, see the troubleshooting below.

Take it for a spin

Open any app that accepts text - Telegram, Messages, Notes, Mail, the Safari address bar, whatever. Tap to bring up the keyboard. Long-press the globe icon (bottom-left of the default keyboard) to switch keyboards. Pick Diction.

You'll see one big mic button. Tap it, talk, release. The audio streams to your server. The transcription arrives back in about as much time as it takes for you to take your finger off the button.

On a local network, end-to-end latency for a short sentence is typically under a second. Good enough that you stop thinking about it.

If it doesn't connect

Server not running? docker compose ps on the server.
iPhone not on the same WiFi as the server.
IP address typo - re-check what Step 6 returned.
Firewall blocking port 8080. On Linux with ufw: sudo ufw allow from 192.168.0.0/16 to any port 8080. On macOS, System Settings → Network → Firewall. Docker Desktop adds itself to the allow list on install, so inbound on published ports normally works - but if you've previously clicked "Deny" on a firewall prompt for Docker, that choice sticks. Flip it back under "Options…", or temporarily turn the firewall off to confirm that's the cause.

Quickest sanity check: open Safari on the iPhone and try http://192.168.1.42:8080/health. If the browser can't reach it, the app can't either.

Now dictate into your agent

Open Telegram. Tap your agent's chat. Tap the globe to switch to the Diction keyboard. Tap the mic. Talk. Release. Your server transcribes, the LLM cleans it up, and the message lands in the composer ready to send. Hit send. Your agent replies. Loop.

That's the whole point of the exercise.

Reach It From Anywhere (Not Just Home WiFi)

Right now your dictation only works on your home network. The moment you walk out the door, the iPhone can't reach 192.168.1.42 anymore. Three clean ways to fix this.

Tailscale (my pick)

Tailscale builds a private mesh network between your devices over WireGuard. Install it on the server and on the iPhone, sign in to the same account on both, and your phone gets a stable 100.x.x.x address it can use to reach the server from anywhere - cellular, coffee shop WiFi, a plane with WiFi, wherever.

Server side (Linux):

curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscale up

On macOS, download the app and run it.

iPhone side: install the Tailscale app from the App Store, sign in.

On the server, grab the tailnet IP:

tailscale ip -4
# → 100.64.1.42

Back in the Diction app, change the Endpoint from http://192.168.1.42:8080 to http://100.64.1.42:8080. Your dictation now works wherever you've got signal. Free for personal use (up to 100 devices).

Cloudflare Tunnel (public URL, no port forwarding)

If you'd rather have a pretty URL and don't want to install anything on the phone, Cloudflare Tunnel gives you an outbound tunnel from your server to Cloudflare's edge. No router config, no exposed ports.

Add this service to your compose file:

  cloudflared:
    image: cloudflare/cloudflared:latest
    container_name: diction-cloudflared
    restart: unless-stopped
    command: tunnel --no-autoupdate run
    environment:
      TUNNEL_TOKEN: "${CLOUDFLARE_TUNNEL_TOKEN}"

Create the tunnel in the Cloudflare Zero Trust dashboard, grab the token, paste it into your .env, set the public hostname to route to http://gateway:8080. Done. Dictate over https://dictation.yourdomain.com.

Free tier. Works great. Only caveat: your transcriptions pass through Cloudflare's network on the way. That's not plaintext (HTTPS all the way), but if "no third party in the path" is the whole reason you set this up, stick to Tailscale.

ngrok (testing / temporary)

For quick testing, ngrok gives you a public URL in one command:

ngrok http 8080

It prints a https://xxx.ngrok-free.app URL. Paste that into the Diction app. Good for a demo or a five-minute test. Free tier URLs change every restart, which is annoying for permanent use. Also adds latency because your audio makes a round trip through ngrok's edge.

Which one?

Personal use, only you reach it: Tailscale. Fast, private, no external hostnames.
Family / small team reaches the same server: Cloudflare Tunnel. Pretty URL, TLS, one password.
Just testing: ngrok.

Already Have a Voice Model Server?

If you've already got a voice model server running somewhere - a self-hosted faster-whisper-server, a colleague's LocalAI instance, your employer's internal speech API - keep it. You don't need the voice model container from Step 3.

What you still need is the Diction Gateway. The iPhone app talks to it for WebSocket streaming and the end-to-end encryption handshake - neither of which a plain OpenAI-compatible transcription server exposes. Point the gateway at your existing server with CUSTOM_BACKEND_URL:

services:
  gateway:
    image: ghcr.io/omachala/diction-gateway:latest
    platform: linux/amd64
    container_name: diction-gateway
    restart: unless-stopped
    ports:
      - "8080:8080"
    environment:
      CUSTOM_BACKEND_URL: http://your-existing-server:8000
      CUSTOM_BACKEND_MODEL: Systran/faster-whisper-small
      # Optional LLM cleanup (Step 7):
      LLM_BASE_URL: "https://api.openai.com/v1"
      LLM_API_KEY: "${OPENAI_API_KEY}"
      LLM_MODEL: "gpt-4o-mini"
      LLM_PROMPT: "Clean up this voice transcription..."

Two extra knobs the CUSTOM_BACKEND_* path supports if you need them:

CUSTOM_BACKEND_AUTH: "Bearer sk-whatever". Sent as the Authorization header to your backend. For instances you've put an auth proxy in front of, or anything hosted that requires a token.
CUSTOM_BACKEND_NEEDS_WAV: "true". Some backends (Canary, Parakeet) only accept WAV. The gateway transparently converts incoming audio with ffmpeg before forwarding.

Point the iPhone at the gateway (http://your-server:8080), leave your existing voice model server where it is, and get streaming plus LLM cleanup on top.

Swap the Speech Model

The starter compose file runs small. That's a choice, not a commitment. Swapping to a different voice model size is two lines in your compose file plus a docker compose up -d. The gateway has a short name for each model it knows how to route to:

Short name (`DEFAULT_MODEL`)	Service hostname	Full model ID
`tiny`	`whisper-tiny`	`Systran/faster-whisper-tiny`
`small`	`whisper-small`	`Systran/faster-whisper-small`
`medium`	`whisper-medium`	`Systran/faster-whisper-medium`
`large-v3-turbo`	`whisper-large-turbo`	`deepdml/faster-whisper-large-v3-turbo-ct2`
`parakeet-v3`	`parakeet`	`nvidia/parakeet-tdt-0.6b-v3`

To swap from small to medium, rewrite your compose file so the whisper service is named whisper-medium, uses WHISPER__MODEL: Systran/faster-whisper-medium, and the gateway's DEFAULT_MODEL is medium.

If the service name doesn't match the short name the gateway expects, you'll see 404 model not found on every request. That's the #1 reason people get stuck when upgrading.

Running multiple models at once? Add more services (whisper-small + whisper-medium side by side) and the app can switch between them per-request by setting the model field in the request body. DEFAULT_MODEL only applies when the request doesn't specify one.

What This Actually Cost Me

The machine: whatever you already have idling at home
Electricity: the speech model at idle is effectively zero. Spikes briefly when you dictate.
OpenAI: gpt-4o-mini is the cheap model. An hour of dictation costs roughly a cent. Five dollars of credit lasts months.

Got an NVIDIA GPU Sitting Idle?

If the box you're setting this up on has an NVIDIA card in it, you can skip the small model and run something that's genuinely state of the art. CPU-only is fine for dictation. GPU unlocks the models that the paid services are running - often faster than those services, because there's no network round trip.

Two options. Pick one.

	Parakeet TDT 0.6B v3	large-v3-turbo
Best at	Speed + accuracy on European languages	Multilingual breadth (99 languages)
WER (English)	~6.3%	~7.4%
Latency	Sub-second	Under 2s on consumer GPU
VRAM (INT8)	~2 GB	~2.3 GB
Languages	25 European	99
Audio format	WAV only (gateway converts)	Anything (voice model handles it)

Option A: Parakeet (fastest, 25 European languages)

NVIDIA's Parakeet TDT 0.6B v3. On a recent consumer GPU (think RTX 3060 or better) it transcribes a 5-second clip in well under a second. Accuracy on clean English audio beats the large-v3 voice model on most benchmarks, at a fraction of the size and latency.

Supported languages: English, Bulgarian, Croatian, Czech, Danish, Dutch, Estonian, Finnish, French, German, Greek, Hungarian, Italian, Latvian, Lithuanian, Maltese, Polish, Portuguese, Romanian, Slovak, Slovenian, Spanish, Swedish, Russian, Ukrainian. If you dictate in any of these, Parakeet is the better engine.

If you dictate in Japanese, Mandarin, Arabic, Korean, or anything outside that list, use Option B.

Replace the whisper-small service in docker-compose.yml with this:

services:
  parakeet:
    image: ghcr.io/achetronic/parakeet:latest-int8
    container_name: diction-parakeet
    restart: unless-stopped
    ports:
      - "5092:5092"
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 1
              capabilities: [gpu]

  gateway:
    image: ghcr.io/omachala/diction-gateway:latest
    platform: linux/amd64
    container_name: diction-gateway
    restart: unless-stopped
    ports:
      - "8080:8080"
    depends_on:
      - parakeet
    environment:
      DEFAULT_MODEL: parakeet-v3

The gateway already knows how to speak to a service named parakeet on port 5092. No extra wiring needed. Test it exactly the same way as before.

You'll need the NVIDIA Container Toolkit installed on the host so Docker can pass the GPU through. One-line install if you haven't done it yet.

Option B: large-v3-turbo voice model (multilingual, frontier-tier)

The biggest model in this family, GPU-accelerated. This is what the paid cloud transcription services charge real money for. Runs great on any GPU with 6GB+ of VRAM.

services:
  whisper-large:
    image: fedirz/faster-whisper-server:latest-cuda
    container_name: diction-whisper-large
    restart: unless-stopped
    volumes:
      - whisper-models:/root/.cache/huggingface
    environment:
      WHISPER__MODEL: Systran/faster-whisper-large-v3-turbo
      WHISPER__INFERENCE_DEVICE: cuda
      WHISPER__COMPUTE_TYPE: float16
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 1
              capabilities: [gpu]

  gateway:
    image: ghcr.io/omachala/diction-gateway:latest
    platform: linux/amd64
    container_name: diction-gateway
    restart: unless-stopped
    ports:
      - "8080:8080"
    depends_on:
      - whisper-large
    environment:
      DEFAULT_MODEL: large-v3-turbo

volumes:
  whisper-models:

First boot pulls about 1.6GB of model weights. After that it's warm and fast.

What About NVIDIA Canary 1B?

If you've been reading up on speech models recently, you've probably seen Canary 1B at the top of the accuracy benchmarks. Yes, it's better than both options above on paper. The catch: NVIDIA ships it through NeMo, not as a turnkey OpenAI-compatible container. Getting it wrapped in the API the gateway expects is real work. You'll end up writing a small serving layer yourself. I run one of those internally for the Diction cloud, but I'm not going to pretend you can copy-paste a compose block for it. If you're willing to build that wrapper, point the gateway at it via CUSTOM_BACKEND_URL (see the next section) and you're set.

For everyone else: Parakeet or large-v3-turbo is already better than what most cloud services give you.

The OpenAI-Compatible API You Just Installed

The gateway speaks the OpenAI audio transcription API. That means anything that knows how to talk to api.openai.com/v1/audio/transcriptions also knows how to talk to your server. You spun up the iPhone keyboard client of this API, but you can also point laptops, scripts, or other services at the same URL.

Quick Python example using the official OpenAI SDK:

from openai import OpenAI

client = OpenAI(
    base_url="http://192.168.1.42:8080/v1",
    api_key="anything",   # not checked by default
)

with open("meeting.m4a", "rb") as f:
    text = client.audio.transcriptions.create(
        file=f,
        model="small",
        response_format="text",
    )

print(text)

Same thing works for the Node SDK, LangChain, Flowise, n8n, anything. Treat it as a local stand-in for OpenAI's hosted API.

What's supported

POST /v1/audio/transcriptions with file, model, language, prompt, response_format=json|text
GET /v1/models - lists the speech engines and models the gateway can route to. Response shape is Diction's own ({"providers": [{"id": "whisper", "models": [...]}, ...]}), not OpenAI's flat data array, so OpenAI SDK .models.list() calls won't parse it cleanly. Hit it directly with curl if you want to see what's available.
Multiple short-name aliases: small, medium, large-v3-turbo, parakeet-v3
HuggingFace-style IDs: Systran/faster-whisper-small, nvidia/parakeet-tdt-0.6b-v3, etc.

What's not supported

Text-to-speech (/v1/audio/speech). This is transcription only.
response_format=verbose_json | srt | vtt. No word-level timestamps.
Server-Sent Events streaming on the REST endpoint. Use the WebSocket /v1/audio/stream for streaming.
OpenAI's Realtime API (/v1/realtime).

Authentication

By default the gateway has AUTH_ENABLED=false. Pass any non-empty string as the API key - nothing's checked. If you want to lock it down (e.g. exposing via Cloudflare Tunnel), set AUTH_ENABLED=true and configure the token in your gateway env. The server/docker-compose.yml in the public repo has a more elaborate example if you want to see it.

Caveat: error response shape

Diction's gateway returns errors as {"error":"message"}, not OpenAI's nested {"error":{"message":"...","type":"..."}}. Most SDKs surface these as a raw HTTPError rather than a parsed APIError. Catch both if you're writing something defensive.

Privacy: What Actually Happens to Your Audio

The whole reason most people set this up is not paying a random SaaS to process their voice. Worth being precise about what this stack does and doesn't do:

What leaves your iPhone: raw audio, encoded as Opus (over WebSocket stream) or WAV (over REST), heading to the server endpoint you configured.

In transit: HTTP by default. Plain text audio over your LAN. That's fine on a trusted home network. If you expose the gateway over the internet (Cloudflare Tunnel, ngrok, your own reverse proxy), put TLS in front of it. Tailscale wraps everything in WireGuard so you don't need to think about TLS at all - that's part of why I prefer it.

What your server does with the audio: feeds it to the voice model container. The voice model transcribes. Returns text. Audio gets thrown away - neither the gateway nor faster-whisper-server persists audio anywhere. docker compose logs contains request metadata (latency, model used, text length) but not the audio or the transcript. You can verify yourself: docker exec diction-whisper-small ls -la /tmp is essentially empty between requests.

If cleanup is enabled: the transcript (plain text, no audio) gets sent to your configured LLM endpoint. That's the only point where data leaves your server. If you pick a local Ollama, nothing leaves the house at all. If you pick OpenAI/Groq/whatever, the transcript passes through their infrastructure. Their data policies apply to that leg - read them if it matters.

What the Diction app does with your audio: nothing. The keyboard's only job is to stream to your endpoint and insert the response. No analytics, no tracking, no background uploads. The app has no QWERTY input, so there's literally nothing to log even if it wanted to. Source for the server-side code is on GitHub (the iOS app itself isn't open source, but the data flow on the wire is straightforward: one POST per dictation, to the endpoint you configured).

Full Access permission: iOS requires this for any keyboard that touches the network. It's a coarse switch that also grants things like pasteboard access. Diction uses the network part and nothing else - again, no typed input, no pasteboard monitoring. If you'd rather not trust that claim, run the setup from this article and point Wireshark at the gateway's port. You'll see exactly one connection per dictation, to your endpoint.

One Small Thing About "AI Companion"

If you dig around the Diction app's settings you'll find an "AI Companion" toggle with its own prompt field. Worth knowing how that interacts with what you just built.

The toggle is what tells the app to ask for cleanup (?enhance=true in the request). It's the on/off switch. But the actual prompt the LLM sees is whatever you put in LLM_PROMPT in your compose file. The in-app prompt field is used by the hosted Diction Cloud setup. On your own server, your env var wins. Every time.

So: flip AI Companion on in the app if you want cleanup to run. Tune the prompt by editing docker-compose.yml and running docker compose up -d again. Nothing else to configure.

It's Open Source. Go Wild.

The gateway is on GitHub at omachala/diction under an open-source license. If there's a behavior you want that it doesn't have, fork it. If you hit a bug or add something other people would benefit from, I'd love a pull request. The codebase is small and deliberately boring Go. You don't need to be an expert to find your way around.

Some things I know people want and haven't built yet: per-app routing (different models for different apps), a richer context API, swappable post-processing pipelines. If any of those scratch your itch, the code's right there.

Heard of Speaches?

Speaches is the nearest neighbor - an OpenAI-compatible self-hosted speech server with transcription, TTS, and a realtime API. Good project for a general-purpose endpoint. It won't drive the Diction keyboard, though: the app opens a WebSocket at /v1/audio/stream and does an X25519 + AES-GCM handshake on every request, and Speaches streams transcription over SSE on the REST endpoint with no knowledge of that handshake. That's why I wrote Diction Gateway - the keyboard's protocol baked in, end-to-end encrypted transcripts by default, BYO LLM cleanup in a single env var, and a thin wrapper mode (CUSTOM_BACKEND_URL) so you can put it in front of any existing speech server. Even outside the keyboard use case, if you want a minimal OpenAI-compatible speech gateway with an LLM cleanup step wired in, reach for this one.

Where to Go Next

Some directions once the base setup is working:

Ditch the cloud LLM for a local model. You already saw the Ollama option in Step 7. Uncomment it in your compose file, ollama pull gemma2:9b, done. Nothing leaves your house. I've got a full walkthrough of the Ollama side here.
Move off home WiFi. Tailscale (Reach It From Anywhere section above) is the easy answer. Five minutes to set up, dictation works at the café.
Upgrade the speech model. Start with small, move to medium once you notice misheard words, jump to large-v3-turbo if you've got a GPU. Model accuracy climbs noticeably between each tier.
Dictate in another language. The voice model autodetects, so you don't have to do anything. If you're mostly in a European language and have a GPU, switch to Parakeet - it's meaningfully more accurate for those.
Tune the cleanup prompt. The default prompt fixes filler words and punctuation. Try the email-ready rewriter, the bullet-pointer, or your own variant. See the prompt library in Step 7.
Add a second gateway. Run one on your home server (high quality, slow connection over VPN) and one on a dev laptop (lower quality, instant local). Switch per-network.
Plug the gateway into other things. It's an OpenAI-compatible speech endpoint. Any transcription workflow - meeting notes, voice memos pipeline, automatic subtitling - can point at it instead of OpenAI.
Contribute. If you build something useful on top of this, PR it to omachala/diction. Better prompts, better docs, new backends, whatever.

The keyboard is in the App Store. You can self-host, use the Diction Cloud, or both. The app lets you switch per-app - self-host your Telegram dictation, use the cloud when you're offline from your tailnet, on-device only mode for the really sensitive stuff. Mix and match.

Closing the Thread

What I like about this setup: I can talk to OpenClaw and the rest of my agents without worrying about who else is listening on the way in. The keyboard's as fast as the built-in one. Short dictations land in under a second. The only thing I pay is whatever my cleanup LLM costs - pennies on OpenAI, zero on local Ollama. The rest stays on my hardware.

The project is still quite new, but the feedback from people using it daily has been genuinely amazing. I'm adding features almost every week and making the whole thing more rock solid with each release. If there's something missing for your workflow, say so - good chance it's on its way or can be.

If you found this useful, a GitHub star on omachala/diction would be a lovely token of appreciation - it's the easiest way to tell me this stuff is worth building more of. Try the app, tell someone else who'd find it useful, and if you hit something that's broken or confusing in this walkthrough, ping me. I'll fix it.

Happy dictating.

Visualizing the Invisible: Seeing the Shape of AI Code Debt

Peng Cao — Sat, 18 Apr 2026 10:43:54 +0000

When we talk about technical debt, we usually talk about lists. A linter report with 450 warnings. A backlog with 32 "refactoring" tickets. A SonarQube dashboard showing 15% duplication.

But for AI-generated code, lists are deceiving. "15 duplicates" sounds manageable—until you realize they are all slight variations of your core authentication logic spread across five different micro-frontends.

Text-based metrics fail to convey structural complexity. They tell you what is wrong, but not where it fits in the bigger picture. In the age of "vibe coding," where code is generated faster than it can be read, we need a new way to understand our systems. We need to see the shape of our debt.

The Solution: Introducing the AIReady Visualizer

To tackle this, we've built the AIReady Visualizer. It's not just another static dependency chart; it’s an interactive, force-directed graph that maps file dependencies and semantic relationships in real-time.

By analyzing import statements and semantic similarity (using vector embeddings), we render your codebase as a living organism. When you see your code as a graph, the "invisible" structural problems of AI code debt suddenly become obvious visual patterns.

The Shape of Debt: 3 Visual Patterns

When we run the visualizer on "vibe-coded" projects, three distinct patterns emerge—each signaling a different kind of risk.

1. The Hairball (Tightly Coupled Modules)

What it looks like: A dense, tangled mess of nodes where everything imports everything else. There are no clear layers or boundaries.

The Problem: This pattern kills AI context windows. When an AI agent tries to modify one file in a "Hairball," it often needs to understand the entire tangle to avoid breaking things. Pulling one file into context pulls the whole graph, leading to token limit exhaustion or hallucinated dependencies.

The Fix: You need to refactor by breaking cycles and enforcing strict module boundaries. The visualizer helps identify the "knot" that holds the hairball together.

2. The Orphans (Islands of Dead Code)

What it looks like: Small clusters or individual nodes floating completely separate from the main application graph.

The Problem: These are often fossils of abandoned AI experiments—features that were generated, tested, and forgotten, but never deleted. They bloat the repo size and confuse developers ("What is this legacy-auth-v2 folder doing?"). More dangerously, they can be "hallucinated" back to life if an AI agent mistakenly imports them.

The Fix: If it's not connected to the entry point, delete it. The visualizer makes finding these islands trivial.

3. The Butterflies (High Fan-In/Fan-Out)

What it looks like: A single node with massive connections radiating out (high fan-out) or pointing in (high fan-in). Often seen in files named utils/index.ts or types/common.ts.

The Problem: These files are bottlenecks and context bloat.

High Fan-In: Changing this file breaks everything. AI agents struggle to predict the blast radius of changes here.
High Fan-Out: Importing this file brings in a massive tree of unnecessary dependencies, polluting the AI's context window with irrelevant code.

The Fix: Split these "god objects" into smaller, deeper modules.

How It Works

Under the hood, the AIReady Visualizer combines two powerful tools:

@aiready/graph: Our analysis engine that parses TypeScript/JavaScript ASTs to build a precise dependency graph. It creates a weighted network of files based on import strength and semantic similarity.
D3.js: We use D3's force simulation to render this network. Files that are tightly coupled naturally pull together, while unrelated modules drift apart, physically revealing the architecture (or lack thereof).

Use Case: Bridging the "Vibe" Gap

We're seeing a growing divide in engineering teams:

The "Vibe Coders": Junior devs or founders using AI to ship features at breakneck speed. Their focus is output.
The Engineering Managers: Seniors trying to maintain stability and scalability. Their focus is structure.

The visualizer bridges this gap. It's hard to explain abstract architectural principles to a junior dev who just wants to "ship it." It's much easier to show them a giant, tangled "Hairball" and say, "See this knot? This is why your build takes 15 minutes and why the AI keeps getting confused."

Visuals turn abstract "best practices" into concrete, observable reality.

See Your Own Codebase

Don't let your codebase become a black box. You can visualize your own project's shape today.

Run the analysis on your repository:

npx aiready visualise

Stop guessing where the debt is. Start seeing it.

Read the full series:

Part 1: The AI Code Debt Tsunami is Here (And We're Not Ready)

Part 2: Why Your Codebase is Invisible to AI
Part 3: AI Code Quality Metrics That Actually Matter
Part 4: Deep Dive: Semantic Duplicate Detection
Part 5: The Hidden Cost of Import Chains
Part 6: Visualizing the Invisible ← You are here

PHP to Go: The Mental Model Shift Nobody Warns You About

Gabriel Anhaia — Sat, 18 Apr 2026 10:36:13 +0000

Book: Observability for LLM Applications · Ebook from Apr 22
Also by me: Thinking in Go (2-book series) — Complete Guide to Go Programming + Hexagonal Architecture in Go
My project: Hermes IDE | GitHub — an IDE for developers who ship with Claude Code and other AI coding tools
Me: xgabriel.com | GitHub

The Laravel container. Eloquent. Facades. Magic methods. Thirty years of PHP have taught you that the framework does the composition for you. You type User::find(1) and something, somewhere, boots an ORM, resolves a connection, hydrates a model, and hands it back. You never had to ask who wired what.

Go hands the composition back. Every dependency is a parameter. Every request is a goroutine. There is no container that calls new on your behalf, no __construct metadata, no framework that reads your route annotations at boot.

This is the part of the move that actually hurts. Not the syntax. The syntax is small. The mental model is the thing. Here is what that looks like in practice, feature by feature, for a PHP developer who already ships.

flowchart LR
    subgraph PHP["PHP / PHP-FPM"]
        R1[Request] --> W1[Spawn worker]
        W1 --> P1[Boot framework<br/>Load config]
        P1 --> H1[Handle request]
        H1 --> D1[Die]
    end
    subgraph GO["Go / net/http"]
        R2[Request] --> G2[Go routine]
        G2 --> H2[Handle request]
        H2 --> F2[Return<br/>routine freed]
    end

The request lifecycle stops dying

In PHP-FPM, every request is a short-lived process. It boots the framework, handles one HTTP call, and dies. State does not survive. Caches need Redis. Background work needs a queue worker. You never had to think about a request that outlives its handler because nothing ever did.

A Go server is one long-lived process. Every request is a goroutine — roughly 2 KB of stack, scheduled on top of a small pool of OS threads by the Go runtime. The process boots once. Globals survive. In-memory caches work. The http.Server you start in main runs until you SIGTERM it.

package main

import (
    "log"
    "net/http"
)

func main() {
    mux := http.NewServeMux()
    mux.HandleFunc("/hello", func(w http.ResponseWriter, r *http.Request) {
        w.Write([]byte("hello"))
    })
    log.Fatal(http.ListenAndServe(":8080", mux))
}

That is the whole server. No index.php, no public/ directory, no .htaccess. The Laravel equivalent has a router, a kernel, middleware pipeline, service providers, and PHP-FPM in front of it. Go skips all of that because it doesn't need to reboot every request.

RoadRunner and FrankenPHP narrow the gap on the PHP side. They keep the worker alive between requests. But the default PHP model is still die-on-response, and most Laravel code is written as if that's true — globals are suspect, singletons need ->singleton() bindings, and memory leaks "don't exist" because the process gets flushed. In Go, none of that applies. A leaked goroutine will still be there at 3 a.m.

Eloquent vs `database/sql` + `sqlc`

This is the habit that breaks hardest. Eloquent and Doctrine let you write:

$users = User::where('active', true)
    ->with('orders')
    ->orderBy('created_at', 'desc')
    ->limit(20)
    ->get();

And you mostly stop thinking about the SQL. The ORM lazy-loads, eager-loads, and builds the query for you.

Go has ORMs (GORM, ent, Bun). Most production Go code does not use them. The pattern most teams coming from Laravel converge on is sqlc — write SQL by hand, generate typed Go functions from it, call the functions.

-- queries.sql
-- name: ListActiveUsersWithOrders :many
SELECT u.id, u.email, u.created_at
FROM users u
WHERE u.active = true
ORDER BY u.created_at DESC
LIMIT $1;

// generated by sqlc — you do not write this file
users, err := q.ListActiveUsersWithOrders(ctx, 20)
if err != nil {
    return err
}
for _, u := range users {
    // u.ID is int64, u.Email is string, u.CreatedAt is time.Time
}

The SQL lives in a file. The types live in generated Go. You can grep for every query in the codebase. No lazy loading, no N+1 hidden behind a property access, no tap and dd to inspect what the ORM did — the query is literally the file you opened.

If you've been fighting Eloquent for years over whereHas generating awful joins, this feels like leaving a loud room.

Dependency injection: the container is gone

Laravel's service container is one of its best ideas. You bind an interface, type-hint a constructor, and the framework resolves the graph for you. It feels like magic because it reads reflection metadata at runtime.

Go has no reflection-based container in the standard library. You wire your graph by hand, in main, and pass dependencies down as arguments.

func main() {
    db, err := sql.Open("postgres", os.Getenv("DATABASE_URL"))
    if err != nil {
        log.Fatal(err)
    }
    defer db.Close()

    queries := sqlc.New(db)
    mailer := smtp.NewMailer(os.Getenv("SMTP_URL"))

    userSvc := user.NewService(queries, mailer)
    handler := httpapi.NewHandler(userSvc)

    log.Fatal(http.ListenAndServe(":8080", handler))
}

That main is your composition root. Every dependency is visible. Nothing is auto-wired. If you want to swap the mailer for a test fake, you pass a different mailer into user.NewService.

Laravel devs usually hate this for a week and then find it restful. You stop grepping for ->bind() calls in twelve different service providers. You stop wondering whether a test is getting the real Mailer or a spy. The graph is the code in main.

Tools like wire exist to generate this wiring at compile time when the graph gets big, but the generated output is still plain func main() code you can read.

Middleware: `http.Handler` is the whole pattern

Laravel middleware looks like this:

public function handle(Request $request, Closure $next): Response
{
    if (!$request->user()) {
        return redirect('/login');
    }
    return $next($request);
}

Go's http.Handler is the same idea with one less layer of abstraction. A middleware is a function that takes a handler and returns a handler.

func RequireUser(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        uid := r.Header.Get("X-User-ID")
        if uid == "" {
            http.Error(w, "unauthorized", http.StatusUnauthorized)
            return
        }
        ctx := context.WithValue(r.Context(), userKey, uid)
        next.ServeHTTP(w, r.WithContext(ctx))
    })
}

// wire the chain
handler := RequireUser(Logging(apiHandler))

No $kernel->pushMiddleware(...), no priority ordering, no group names. The chain is function composition. You can read the whole pipeline in the file where you build it.

The tradeoff: Laravel's named middleware groups and route-level middleware declarations are genuinely more ergonomic for a team of 20 people who all need to add auth to a new route. Go needs a router like chi or echo before you get that back.

Concurrency: goroutines are not workers

PHP's async story is fragmented. Fibers landed in PHP 8.1. Amphp and ReactPHP exist. Swoole and OpenSwoole give you coroutines. Most production PHP apps still dispatch long work to a queue and let Horizon or a custom worker eat it.

In Go, concurrency is a language feature. You write:

func fetchAll(ctx context.Context, urls []string) ([]string, error) {
    results := make([]string, len(urls))
    errs := make(chan error, len(urls))
    var wg sync.WaitGroup

    for i, u := range urls {
        wg.Add(1)
        go func(i int, u string) {
            defer wg.Done()
            body, err := fetch(ctx, u)
            if err != nil {
                errs <- err
                return
            }
            results[i] = body
        }(i, u)
    }
    wg.Wait()
    close(errs)

    for err := range errs {
        if err != nil {
            return nil, err
        }
    }
    return results, nil
}

No queue. No worker. No serialization. Twelve HTTP calls fan out, run concurrently on the Go scheduler, and come back.

This is the capability PHP genuinely cannot match without bolt-ons. If your current Laravel code dispatches 12 jobs and polls for completion, the Go version is one function.

The warning: go somefunc() with no coordination is how Go services leak goroutines and eat memory. Every goroutine needs a way to finish — usually a context.Context with a deadline, or a channel close, or a sync.WaitGroup. "Just spawn a goroutine" is the Go equivalent of "just fire and forget a queue job" and it causes similar classes of bugs.

Typing: PHP 8.4 is close, but not the same thing

PHP 8.4 has declare(strict_types=1), typed properties, union types, readonly classes, and asymmetric visibility. You can write PHP that looks a lot like TypeScript.

Go's type system is cruder but fully static and fully compiled. No strings to int coercion, no array as both list and map, no variadic arrays of whatever. A []User is a slice of User. A map[string]int is a map from string to int. The compiler refuses to build if the types don't fit.

What PHP has that Go doesn't: named arguments, default parameter values, optional arguments. In Go, you build a struct.

type CreateUserParams struct {
    Email    string
    Password string
    Role     string // defaults to "member" if empty
}

func CreateUser(ctx context.Context, p CreateUserParams) (*User, error) {
    if p.Role == "" {
        p.Role = "member"
    }
    // ...
}

// call site
u, err := CreateUser(ctx, CreateUserParams{
    Email: "a@b.com",
    Password: "hunter2",
})

Verbose compared to createUser(email: 'a@b.com', password: 'hunter2') in PHP. You get used to it. The payoff is that refactoring a function signature across a 200-file codebase is a compiler job, not a grep job.

Testing: the stdlib is enough

PHPUnit and Pest are mature, opinionated, and do a lot for you — data providers, mocking, snapshot testing, beautiful output. Pest in particular reads nicely.

Go's testing package is deliberately plain. No framework. No mocking library in the stdlib. Table tests are the idiom.

func TestNormalizeEmail(t *testing.T) {
    cases := []struct {
        in, want string
    }{
        {"A@B.com", "a@b.com"},
        {"  x@y.io  ", "x@y.io"},
        {"", ""},
    }
    for _, c := range cases {
        got := NormalizeEmail(c.in)
        if got != c.want {
            t.Errorf("NormalizeEmail(%q) = %q, want %q", c.in, got, c.want)
        }
    }
}

Run with go test ./.... No config file. The test is a function. Subtests, benchmarks, fuzzing, race detection, coverage — all in the stdlib or one flag away.

Teams coming from Pest usually miss the expressiveness for the first month. Then they stop noticing.

Five pitfalls PHP devs hit in their first Go week

Ignoring errors. In PHP you throw and catch. In Go, every call that can fail returns an error, and the compiler lets you drop it with _. Do not drop it. A _ = json.Unmarshal(...) is a silent data bug waiting to ship.
Sharing a struct across goroutines without a mutex. Every PHP request gets its own process. Shared state was Redis, period. A Go handler runs concurrently with every other handler, and a map you read without a lock will eventually panic under load.
Treating nil like null. A typed nil inside an interface is not equal to a plain nil. var err *MyError = nil; var e error = err; e == nil is false. This trips every PHP dev once.
Over-using packages. Laravel encourages small service classes. Go packages are heavier — each is a compilation unit and an import. A PHP app with 200 classes in 40 namespaces maps to maybe 6 Go packages, not 40.
Building a container. Someone on the team, by week two, will try to port Laravel's container to Go using reflection. Do not. Pass dependencies as arguments. The one-time refactor pain saves a year of debugging "which binding did the container resolve at 3 a.m."

What Laravel still does better

Be honest about this. Laravel has things Go will not give you back:

Artisan. php artisan make:controller, make:migration, tinker. Go has go run, go generate, and whatever CLI you build yourself. There is no REPL you can fire up to poke production data.
Eloquent for CRUD apps. If you are building an admin panel and 80% of your code is Model::where(...)->update(...), Eloquent is faster to write than any Go ORM.
Blade. Go's html/template is safe and decent. It is not Blade.
The ecosystem. Laravel Nova, Filament, Livewire, Inertia, Horizon, Forge, Vapor. The Go ecosystem has nothing like the batteries-included admin and deploy story.
Conventions. A new Laravel dev can find the UserController in any app because it is always in the same place. Go projects disagree about project layout — there is one community proposal and plenty of teams who reject it.

What Go does that PHP genuinely cannot

The list is shorter but load-bearing:

A single static binary. go build produces one file. Ship it. No PHP version, no extensions, no FPM pool config, no Composer install on the server.
Real concurrency. See the fan-out example above.
Predictable memory and GC. A Go service at 200 RPS uses 80 MB and stays there. A Laravel FPM pool at the same load needs to fork workers and eats multiples of that.
The compile step. Most of the "what does this function take" questions are answered before runtime. This is the thing that scales a codebase past 20 engineers.
Standard tooling. go fmt is not negotiable. go vet, go test -race, go test -cover are all stdlib. PHP has PHP-CS-Fixer, PHPStan, Psalm, Rector, PHPUnit, Xdebug, Pest — pick your stack and argue about it for a year.

The honest summary for a PHP dev eyeing Go

You are not learning a better PHP. You are learning a language designed by people who wanted to delete most of what PHP gives you for free, because at a certain scale the magic costs more than it saves.

The first week hurts. You will type User::find(1) into an empty file and stare at it. You will write twelve lines of explicit wiring where Laravel would have written zero. You will forget to check an error and spend 40 minutes debugging silent data.

The second week, something clicks. The wiring you wrote by hand is the wiring. The function signature is the contract. The test is a function. The server is one process. And when you push to prod, one binary goes with it.

If you want the long version of this — the full "write a production Go service from scratch" arc, with the patterns Laravel devs specifically need unlearned and the Go idioms that replace them — the Thinking in Go series is written for exactly this reader.

flowchart TD
    subgraph Laravel["Laravel container"]
        Bind[service bindings] --> Reflect[Reflection resolves<br/>dependencies]
        Reflect --> Magic[auto-wired Controller]
    end
    subgraph GoMain["Go main.go"]
        Cfg[load config] --> DB[open DB]
        DB --> Repo[NewUserRepo]
        Repo --> Svc[NewUserService]
        Svc --> Handler[NewUserHandler]
    end

If this was useful

Thinking in Go is the 2-book series built for developers coming to Go from a framework-heavy background. The Complete Guide to Go Programming walks through the language end to end — the one you want when Eloquent habits keep showing up in your Go code. Hexagonal Architecture in Go is the follow-up for when you need a real project layout.

Observability for LLM Applications is the other book, for engineers running LLM features in production (many of those services are written in Go).

Thinking in Go (series): Complete Guide to Go Programming · Hexagonal Architecture in Go
Observability for LLM Applications: Amazon · Ebook from Apr 22
Hermes IDE: hermes-ide.com — an IDE for developers shipping with Claude Code and other AI coding tools
Me: xgabriel.com | GitHub

Data Validation Using Early Return in Python

Mee Mee Alainmar — Sat, 18 Apr 2026 10:36:13 +0000

While working with data, I find validation logic tends to get messy faster than expected.

It usually starts simple then a few more checks get added, and suddenly everything is wrapped in nested if statements.
That pattern works, but it doesn’t feel great to read or maintain.

That's how I learned Early return (or guard clause) pattern.

Note: In programming, return means sending a value back from a function to wherever that function was called and stopping the function’s execution right there. Meaning return acts as a checkpoint.

Think of it like saying, “I’m done; here’s my answer.”

So I tried a different approach, combining:

early return
rules defined as simple dictionaries

The result turned out surprisingly clean.

The Problem

Let's say a validation task might involve checks like:

age should be at least 18
email should contain @
user_id should be an integer

The usual way often ends up looking like this:

id="a1k29d"

if "age" in record:
    if record["age"] >= 18:
        ...

It works, but the structure quickly becomes hard to follow as more rules are added.

The Pattern

Instead of hardcoding each condition, the rules can be defined as data:

id="ab123"
rules = [
    {"field": "user_id", "type": "type", "value": int},
    {"field": "age", "type": "min", "value": 18},
    {"field": "email", "type": "contains", "value": "@"},
]

Then a single function applies these rules.


id="ab123"
def validate_record(record: dict, rules: list) -> dict:
    for rule in rules:
        field = rule["field"]

        # early return: missing field
        if field not in record:
            return {
                "status": "ERROR",
                "field": field,
                "issue": "Missing field"
            }

        value = record[field]

        # type check
        if rule["type"] == "type":
            if not isinstance(value, rule["value"]):
                return {
                    "status": "FAIL",
                    "field": field,
                    "issue": f"Expected {rule['value'].__name__}"
                }

        # minimum value
        elif rule["type"] == "min":
            if value < rule["value"]:
                return {
                    "status": "FAIL",
                    "field": field,
                    "issue": f"Must be >= {rule['value']}"
                }

        # contains (for strings)
        elif rule["type"] == "contains":
            if rule["value"] not in value:
                return {
                    "status": "FAIL",
                    "field": field,
                    "issue": f"Must contain '{rule['value']}'"
                }

    return {"status": "OK"}

Example

id="d4hf80"
record = {
    "user_id": 1,
    "age": 16,
    "email": "testemail.com"
}

result = validate_record(record, rules)
print(result)

Output:

id="d4hf80"
{
    "status": "FAIL",
    "field": "age",
    "issue": "Must be >= 18"
}

Diagram

 ┌─────────────┐
 │   Function  │
 └──────┬──────┘
        │
        ▼
 ┌─────────────┐
 │ Validate    │
 │ Input       │
 └──────┬──────┘
        │Invalid?
        ├── Yes → Return Error
        │
        ▼
 ┌─────────────┐
 │ Check Pre-  │
 │ conditions  │
 └──────┬──────┘
        │Fail?
        ├── Yes → Return Early
        │
        ▼
 ┌─────────────┐
 │ Main Logic  │
 │ Execution   │
 └──────┬──────┘
        │
        ▼
 ┌─────────────┐
 │ Return      │
 │ Success     │
 └─────────────┘

What is better about this

You can see a few things stood out after using this pattern:

The logic stays flat, no deep nesting
Rules are easy to scan and update
Adding a new validation doesn’t require touching the core function
Early return keeps the flow straightforward

It feels closer to describing what to validate instead of how to validate it step by step.

This example shows the pattern scales nicely. Running this pattern across a dataset and turning the results into a table would be a natural next step. In a way, it feels like a tiny version of larger data validation tools, just stripped down to the core idea.

For Schema Validation, Pydantic is the best no doubt for this. It ensures that the data entering the system is the right shape, type, and format. Meanwhile, Early Return pattern is to handle edge cases or invalid states immediately, preventing deeply nested if/else blocks.

Microlearning for developers: learn new concepts in 15 minutes

Tdvh yfdg — Sat, 18 Apr 2026 10:29:56 +0000

Developers are expected to keep up with an industry that never slows down. New frameworks, languages, and tools appear every few months, and falling behind even slightly can feel overwhelming. The good news is that you don't need to block out entire evenings to stay current. Platforms like SmartyMe are built around the idea that focused, short learning sessions fit naturally into a developer's lifestyle and actually produce better results than marathon study sessions.

The developer's learning problem

Technology moves fast. Every year brings new libraries, updated best practices, cloud services to explore, and paradigms to understand. What was relevant three years ago may already be considered outdated today. Keeping pace is not optional if you want to stay competitive in the job market or grow within your current role.

The bigger challenge, though, is time and energy. After a full day of writing code, debugging, attending standups, and reviewing pull requests, most developers simply don't have the mental bandwidth for a two-hour course. You open a video lecture with the best intentions, but by minute 20, you've lost focus entirely.

This pattern repeats constantly: we enroll in courses, make it through the first few modules, and then quietly abandon them when a deadline hits. According to data from online learning platforms, course completion rates often sit below 15%. That's not a motivation problem, it's a format problem.

The format of traditional online education is simply not built for developers who are already cognitively loaded. Long-form content demands sustained attention that most working professionals can't reliably offer. What the industry needs is a smarter approach to continuous education, one that respects limited time and works with human cognitive patterns rather than against them.

Why microlearning works for technical minds

Developers already think in modules. Breaking a complex problem into smaller, manageable pieces is literally a core skill of the job. So it makes complete sense that microlearning developers aligns naturally with the way technical minds are already trained to operate.

A 15-minute learning session delivers exactly one focused concept. That constraint actually helps. When the scope is defined, it's easier to stay engaged, process the material, and walk away with something concrete. There's no vague endpoint where your attention starts drifting.

The science backs this up. Research in cognitive psychology, including studies related to what's known as the "spacing effect," confirms that information absorbed in smaller chunks over repeated sessions is retained far better than material consumed in long, single sittings. Hermann Ebbinghaus's research on memory showed that spaced repetition can improve retention by up to 200%. Short sessions spaced over days are more effective than a single long session.

For developers, the accumulation adds up quickly:

5 days a week x 15 minutes = 75 minutes of focused learning
In a month, that's roughly 5-6 hours of quality study time
Each session builds on the last, reinforcing what you already know
Over a year, you can cover multiple entirely new skill areas

The key is consistency, not intensity. One concept a day, five days a week, compounds into serious expertise over time.

Beyond coding: skills developers often overlook

Strong technical skills will get you hired, but they won't always get you promoted or help you build something independently. Learning coding fundamentals is essential, but it's only part of what makes a developer genuinely effective in real-world environments.

Communication is one of the most underrated skills in tech. Can you explain a complex architectural decision to a non-technical stakeholder? Can you write documentation that another developer can actually follow? The ability to communicate clearly, both in writing and in conversation, directly affects your impact on a team.

Critical thinking shapes how you approach problems beyond syntax and logic. It's about evaluating tradeoffs, questioning assumptions, and making decisions under uncertainty. Developers who think critically write better code and make fewer costly architectural mistakes.

Here's what well-rounded developers typically invest in beyond technical knowledge:

Communication: Clearer code reviews, better documentation, smoother collaboration
Critical thinking: Better decisions during architecture planning and debugging
Logic: Understanding cognitive biases helps in UX decisions and team dynamics
Finance basics: Essential if you're considering freelance work or launching your own product
Personal productivity: Time management and focus skills directly improve output quality

Developers who invest in these areas become more than just coders. They become people their teams rely on for judgment, clarity, and leadership. That shift in value is significant, and it doesn't require a degree in business or psychology. A consistent microlearning habit covering these topics gets you there gradually and without overwhelm.

How to fit learning into a developer's day

Finding time for learning isn't about having free time. It's about using the time you already have more intentionally. Most developers have several natural gaps in their day that work perfectly for a 15-minute session.

Morning is one of the most effective windows. Before your inbox fills up and your brain is pulled in six directions, a single focused lesson with your coffee sets a productive tone. Many developers find that morning learning sticks better because the mind is fresh and there are fewer interruptions.

The lunch break is another overlooked opportunity. Scrolling social media during lunch is a default habit for many, but swapping just part of that time for a lesson is an easy upgrade. You're already stepping away from work, so the mental context switch is natural.

For those who commute, audio-based learning formats are a practical fit. Listening to a lesson on the way to the office means you arrive already having learned something, before the workday even begins. After work, lighter topics like art or finance can serve as a natural wind-down that still feels productive.

Time of day	Format that works best	Duration
Morning (pre-work)	Text or video lesson	15 min
Lunch break	Short interactive module	10-15 min
Commute	Audio lesson	15-20 min
Evening	Light reading or review	10-15 min

The trick is to anchor your learning to an existing habit. Attach the lesson to something you already do every day, and it becomes automatic rather than a decision you have to make.

Building a learning habit that survives deadlines

The most common reason developers stop learning mid-streak is a crunch period at work. When a project is on fire, learning is the first casualty. This is where the format of microlearning genuinely outperforms traditional courses.

It's hard to justify skipping a 2-hour course when you're exhausted. It's much harder to justify skipping 15 minutes. That small size is the feature, not a limitation. Even during the most intense sprint weeks, a single short lesson is almost always possible.

Streaks and progress tracking serve as powerful motivators. When you can see a visible chain of completed days, breaking it feels costly. Many learners report that the desire to maintain a streak keeps them coming back even on days when motivation is low.

The "never miss twice" rule is a practical tool for managing guilt and maintaining momentum:

Miss one day? That's fine. Life happens.
Miss two in a row? The habit starts to dissolve.
One missed day is a pause. Two is the beginning of quitting.
Resuming after a skip matters more than the skip itself.

Letting go of perfectionism around the habit is part of making it sustainable. You don't need a flawless record, you need a resilient one.

What to learn first: practical recommendations

Starting is often the hardest part, especially when the options seem endless. A useful framework is to begin with skills that immediately improve your day-to-day work, then layer in broader knowledge over time.

For most developers, logic and critical thinking offer the fastest return. These skills directly improve how you approach debugging, system design, and code review. Communication skills follow closely, since they affect how your work is perceived by others and how effectively you collaborate.

Here's a suggested learning order based on practical impact:

Logic and critical thinking - Immediately useful in problem-solving and design decisions
Communication skills - Improves code reviews, documentation, and meetings
Personal development - Helps build self-awareness and reduce cognitive biases in decision-making
Finance - Essential groundwork for freelancing or building a product
Art and History - Broader perspective that improves creative thinking and problem framing

This sequence isn't rigid. If you're already planning a freelance move, finance might belong at the top. The goal is to learn in a direction that's relevant to where you are and where you want to go.

Start small, stay consistent

You don't need to overhaul your schedule or commit to hours of study every week. What you need is 15 minutes a day and the decision to start. One lesson is one step forward, and those steps build into something real over months.

Developers understand the value of incremental progress better than most. A feature isn't built in a single commit. A codebase isn't refactored overnight. The same principle applies to skills: slow, steady progress done consistently always beats occasional bursts of effort. Start today, keep it small, and let the habit do the work.

I Built a Circle QR Code Generator — Yes, With Curved Border Text

monkeymore studio — Sat, 18 Apr 2026 10:23:52 +0000

Standard square QR codes are everywhere. But what if you want something that stands out? I built a circle QR code generator that wraps your brand message around the QR code itself—completely client-side, no server required.

Why Circle QR Codes?

A circle QR code isn't just a different shape. It's a complete visual reimagining. The circular frame with curved text creates something that looks less like a tech utility and more like a designed brand asset.

Think about where QR codes are actually used: product packaging, business cards, event posters, restaurant menus. A circle QR with "Call now" or "Visit our site" curved along the border does what a plain square code can't—it communicates while staying scannable.

The best part? It's still a real, scannable QR code. The underlying data encodes exactly like a standard QR. Only the visual presentation changed.

How the Circle QR Code Generator Works

The flow is similar to the square version, but with some interesting additions for circular rendering:

Base QR Generation with Circle Shape

The library handles the circular module pattern:

const qrCode = new QRCodeStyling({
  width: size,
  height: size,
  type: "canvas",
  shape: "circle",  // The key difference from square
  data,
  image: imageUrl,
  dotsOptions: {
    color: dotColor,
    type: "square",  // Inner modules stay square for reliability
  },
  imageOptions: {
    crossOrigin: "anonymous",
    margin: 10,
    hideBackgroundDots: true,
    imageSize: Math.max(0.01, Math.min(1, logoSize / 100)),
  },
});

This generates the QR with circular data modules—the dots themselves are arranged in rings rather than a square grid. It's a visual effect, but the encoding remains standard QR.

Circle Masking

After generating the QR, we apply a circular clip to ensure clean edges:

export function makeCircleFromCanvas(source: HTMLCanvasElement, bgColor?: string): HTMLCanvasElement {
  const size = source.width;
  const canvas = document.createElement("canvas");
  canvas.width = size;
  canvas.height = size;
  const ctx = canvas.getContext("2d")!;

  // Draw circular background if color is set
  if (bgColor && bgColor !== "transparent") {
    ctx.beginPath();
    ctx.arc(size / 2, size / 2, size / 2, 0, Math.PI * 2);
    ctx.closePath();
    ctx.fillStyle = bgColor;
    ctx.fill();
  }

  // Clip to circle
  ctx.beginPath();
  ctx.arc(size / 2, size / 2, size / 2, 0, Math.PI * 2);
  ctx.closePath();
  ctx.clip();

  // Draw source inside the circle
  ctx.drawImage(source, 0, 0, size, size);
  return canvas;
}

The function creates a new canvas, optionally fills a circle background, then clips and draws the QR inside. Simple, but produces that clean circular badge look.

Curved Border Text — The Interesting Part

This is where it gets creative. Drawing text along a curve isn't built into canvas—here's how it's done:

export function addCircularTextToCanvas(
  canvas: HTMLCanvasElement,
  topText: string,
  bottomText: string,
  color: string,
  fontSize: number,
  bgColor?: string,
  contentScale = 0.85
): HTMLCanvasElement {
  const padding = Math.ceil(fontSize * 1.5);
  const qrSize = canvas.width;
  const newSize = qrSize + padding * 2;
  const newCanvas = document.createElement("canvas");
  newCanvas.width = newSize;
  newCanvas.height = newSize;
  const ctx = newCanvas.getContext("2d")!;

  // Clear background
  ctx.clearRect(0, 0, newSize, newSize);

  // Draw circular background
  if (bgColor && bgColor !== "transparent") {
    ctx.beginPath();
    ctx.arc(newSize / 2, newSize / 2, newSize / 2, 0, Math.PI * 2);
    ctx.closePath();
    ctx.fillStyle = bgColor;
    ctx.fill();
  }

  // Clip to circle
  ctx.beginPath();
  ctx.arc(newSize / 2, newSize / 2, newSize / 2, 0, Math.PI * 2);
  ctx.closePath();
  ctx.clip();

  // Scale QR to fit inside with room for text
  const scaledQrSize = qrSize * contentScale;
  const offset = (newSize - scaledQrSize) / 2;
  ctx.drawImage(canvas, offset, offset, scaledQrSize, scaledQrSize);

  // Draw curved text
  ctx.save();
  ctx.translate(newSize / 2, newSize / 2);
  ctx.font = `bold ${fontSize}px sans-serif`;
  ctx.fillStyle = color;

  const radius = scaledQrSize / 2 + fontSize * 0.8;

  if (topText) {
    drawArcText(ctx, topText, radius, -Math.PI / 2, false);  // Top text reads left-to-right
  }
  if (bottomText) {
    drawArcText(ctx, bottomText, radius, Math.PI / 2, true);  // Bottom text inverted
  }

  ctx.restore();
  return newCanvas;
}

The algorithm:

Create a larger canvas with padding for text
Draw the circular background and clip to it
Scale the QR code down slightly to make room
Calculate a text radius (slightly outside the QR)
Draw top text counterclockwise, bottom text clockwise

The Arc Text Math

This is the core curved text algorithm:

function drawArcText(
  ctx: CanvasRenderingContext2D,
  text: string,
  radius: number,
  centerAngle: number,
  invert: boolean
) {
  ctx.save();
  ctx.textAlign = "center";
  ctx.textBaseline = "middle";

  // Split and measure each character
  const chars = text.split("");
  const widths = chars.map((c) => ctx.measureText(c).width);
  const totalWidth = widths.reduce((a, b) => a + b, 0);

  // Calculate starting angle based on text width
  const direction = invert ? -1 : 1;
  let currentAngle = centerAngle - direction * (totalWidth / 2) / radius;

  // Draw each character rotated to follow the arc
  for (let i = 0; i < chars.length; i++) {
    const w = widths[i];
    const angle = currentAngle + direction * (w / 2) / radius;

    ctx.save();
    ctx.translate(Math.cos(angle) * radius, Math.sin(angle) * radius);
    ctx.rotate(angle + (invert ? -Math.PI / 2 : Math.PI / 2));
    ctx.fillText(chars[i], 0, 0);
    ctx.restore();

    currentAngle += direction * (w / radius);
  }

  ctx.restore();
}

The key insight: instead of trying to draw curved text directly, rotate each character individually to follow the arc. For a character at angle θ on a circle of radius r, the rotation needed is θ + π/2 (for top) or θ - π/2 (for bottom).

User Controls

Similar to square QR, but with border text options:

// Circle border text inputs
const [circleBorderTopText, setCircleBorderTopText] = useState("");
const [circleBorderBottomText, setCircleBorderBottomText] = useState("");
const [circleBorderTextColor, setCircleBorderTextColor] = useState("#000000");
const [circleBorderTextSize, setCircleBorderTextSize] = useState(16);

Users can specify text for the top and bottom of the circle, customize color and size. Typical use cases:

Top: brand name or promo ("SCAN ME")
Bottom: website or phone ("example.com")

Real-World Usage

This tool shines in practical scenarios:

Use Case	Top Text	Bottom Text
Restaurant menu	"MENU"	"Scan to order"
Business card	"CALL NOW"	"+1-555-0123"
Product packaging	"VIDEO"	"Watch demo"
Event flyer	"REGISTER"	"example.com/events"

Batch Processing

Like the square version, supports multiple URLs at once:

const handleDownloadAll = async () => {
  const zip = new JSZip();
  qrCodes.forEach(({ url, name }) => {
    const base64Data = url.replace(/^data:image\/png;base64,/, "");
    zip.file(`${name}.png`, base64Data, { base64: true });
  });
  const content = await zip.generateAsync({ type: "blob" });
  saveAs(content, "qrcodes.zip");
};

Perfect for printing shops or marketing teams generating dozens of QR codes at once.

Try It Yourself

Check out the live generator at Circle QR code generator. Upload your logo, add some border text, pick your colors—generates instantly in your browser.

Your content never goes to a server. What's entered stays on your device, processed entirely locally.

Where Do Interfaces Live? IVP Answers What SOLID Cannot

Yannick Loth — Sat, 18 Apr 2026 10:23:51 +0000

If you know a software architect, a professor who teaches SOLID, or anyone who takes design principles seriously — I'd appreciate you sharing this with them.

Two companion papers established the structural biconditional between ISP and per-client DIP (paper 1) and proved that Martin's packaging principles are jointly unsatisfiable for the resulting configuration — specifically, CCP and REP cannot both be satisfied (paper 2).

This third paper applies the Independent Variation Principle (IVP) to the same five-element setup and obtains two results from a single application.

Result 1: DIP → ISP, formalized in IVP terms

The first companion paper proved the structural biconditional: ISP ↔ per-client DIP. This paper formalizes the forward direction (DIP implies ISP) in IVP terms. Each interface slice shares its client's change-driver assignment. The IVP biconditional (elements co-reside iff they share driver assignments) closes the proof: the slices are disjoint because the clients belong to different modules. IVP adds formalism to one direction of a valid structural biconditional; it is useful here but not indispensable.

Result 2: A unique modularization

This is where IVP is essential.

Five elements: provider A, clients B and C, interface slices I_B and I_C. Three distinct driver assignments: {γ_ord} for B and I_B, {γ_rep} for C and I_C, {γ_ord, γ_rep, γ_impl} for A.

IVP-3 (elements with different driver assignments cannot co-reside) and IVP-4 (elements with identical driver assignments must co-reside) together admit exactly one partition:

Module B: B and I_B (both driven by γ_ord)
Module C: C and I_C (both driven by γ_rep)
Module A: A alone (composite: γ_ord, γ_rep, γ_impl)

Each interface slice lives with its client — not as a design preference, but as a consequence of the axioms applied to the causal structure of change.

What this settles

The packaging paper showed that eight principles — DIP, ISP, and six packaging principles (REP, CCP, CRP, ADP, SDP, SAP) — give three incompatible answers (with client, with provider, own module) and no meta-criterion for choosing. IVP eliminates two of the three by deriving the answer from Γ.

If two engineers disagree about where I_B belongs, the disagreement traces to a disagreement about Γ — about what can cause I_B to require modification. That is an epistemic question about the system, not a design preference. IVP converts a judgment call into a falsifiable claim.

What IVP's placement produces

The paper verifies that the unique IVP partition delivers:

Change isolation: a change to γ_ord modifies Module B (containing B and I_B) and nothing else. Module C is untouched.
No shotgun surgery: the pathology that scattered interface placement creates is eliminated by construction.
Acyclic dependencies in the provider–client subgraph: A depends on Module B and Module C (for the interface specifications it implements). Neither client module depends on A. No cycle exists in this subgraph.
Independent deployability: each module can be released independently.

The paper

"The Interface Segregation Principle Is a Corollary of the Dependency Inversion Principle --- A Formal Proof via the Independent Variation Principle"

Paper: https://zenodo.org/records/19641242
Companion 1 (ISP = DIP, structural): https://zenodo.org/records/19633560
Companion 2 (packaging unsatisfiability): https://zenodo.org/records/19636635

Companion 1 dev.to article: SOLID: ISP Is Just DIP Applied Twice
Companion 2 dev.to article: SOLID's Packaging Principles Are Jointly Unsatisfiable

The first paper showed ISP and DIP produce the same structure. The second showed SOLID's principles can't agree on where to put it. This one shows IVP can.

If you think the unique partition is wrong — that I_B belongs somewhere other than with B — I'd like to hear the argument. What change driver does I_B respond to, if not B's?

Claude + Groq Hybrid LLM — AI University Memory Agent

kanta13jp1 — Sat, 18 Apr 2026 10:22:32 +0000

Claude + Groq Hybrid LLM — AI University Memory Agent

After each learning session in AI University, a Memory Agent automatically builds a structured learner profile — weak providers, strong providers, preferred learning style. Next session, quizzes are personalized based on that profile.

The trick: two models, two jobs — Claude Sonnet for deep profile extraction, Groq Llama for real-time quiz scoring.

Architecture

Session ends
  → learner.update_profile (Edge Function)
    → Claude Sonnet → structured JSON profile
      → UPSERT into ai_university_learner_profiles

Quiz answer submitted
  → quiz.evaluate (Edge Function)
    → Groq Llama 3.3 70B → JSON score {result, confidence}
    → fallback: string match

Memory Agent — Claude Extracts the Profile

// supabase/functions/ai-hub — learner.update_profile
const prompt = `Extract a structured learner profile from this session data.
Session summary: ${sessionSummary}
Score data: ${JSON.stringify(scores).slice(0, 2000)}
Return JSON: {"weak_providers":["..."],"strong_providers":["..."],"preferred_style":"visual|text|voice","insights":"..."}`;

const claudeResp = await fetch("https://api.anthropic.com/v1/messages", {
  body: JSON.stringify({
    model: "claude-sonnet-4-6",
    max_tokens: 512,
    messages: [{ role: "user", content: prompt }],
  }),
});

// Strip code fences before parsing
const rawText  = claudeData.content[0].text;
const profile  = JSON.parse(rawText.replace(/```
{% endraw %}
json\n?|\n?
{% raw %}
```/g, "").trim());

Save to Supabase:

await admin.from("ai_university_learner_profiles").upsert({
  user_id,
  weak_providers:  profile.weak_providers  ?? [],
  strong_providers: profile.strong_providers ?? [],
  preferred_style: profile.preferred_style  ?? "text",
  profile_json:    profile,
  total_sessions:  (existing?.total_sessions ?? 0) + 1,
}, { onConflict: "user_id" });

Quiz Evaluator — Groq Scores Answers Fast

// quiz.evaluate — Groq Llama 3.3 70B, JSON mode
const groqResp = await fetch("https://api.groq.com/openai/v1/chat/completions", {
  body: JSON.stringify({
    model: "llama-3.3-70b-versatile",
    max_tokens: 100,
    temperature: 0,
    response_format: { type: "json_object" },  // guaranteed JSON
    messages: [{
      role: "user",
      content: `Question: ${question}\nExpected: ${correctAnswer}\nUser: ${userAnswer}
Score: {"result":"correct|incorrect|partial","confidence":0-100}`,
    }],
  }),
}).catch(() => null);

// Groq failure → fallback to exact string match
if (!groqResp || !groqResp.ok) {
  const match = userAnswer.trim().toLowerCase() === correctAnswer.trim().toLowerCase();
  return json({ result: match ? "correct" : "incorrect", confidence: 100, fallback: true });
}

Why Two Models?

Task	Model	Reason
Learner profile extraction	Claude Sonnet 4.6	Complex reasoning, structured JSON quality
Quiz scoring	Groq Llama 3.3 70B	Low latency, high volume, free tier

Claude runs once at session end. Groq runs on every quiz answer. Matching the model to the task cuts costs without sacrificing quality.

DB Schema

CREATE TABLE ai_university_learner_profiles (
  user_id          uuid PRIMARY KEY REFERENCES auth.users,
  weak_providers   text[] DEFAULT '{}',
  strong_providers text[] DEFAULT '{}',
  preferred_style  text   DEFAULT 'text',
  profile_json     jsonb  DEFAULT '{}',
  total_sessions   int    DEFAULT 0,
  updated_at       timestamptz DEFAULT now()
);

Key Takeaways

Assign models by strength — Claude for deep analysis, Groq for speed
response_format: json_object — eliminates JSON parse errors from Groq
Strip code fences — Claude wraps JSON in json → strip before JSON.parse
Always fallback — Groq outage shouldn't break quiz scoring

Building in public: https://my-web-app-b67f4.web.app/

FlutterWeb #Supabase #buildinpublic #LLM #FlutterTips

ServiceKit V2 — The Async Service Locator for Unity

Paul Stamp — Sat, 18 Apr 2026 10:21:06 +0000

I just shipped V2 of ServiceKit, my lightweight dependency management package for Unity. Before I get into what's new, I want to address the thing some of you are already typing into the comments: yes, ServiceKit is a service locator. On purpose. I think that's the right shape for Unity, and V2 is where I've stopped hedging about it.

Why a service locator, not a "proper" DI framework

The "service locator is an anti-pattern" mantra largely comes from enterprise .NET, where you control object construction, processes are long-lived, and writing an installer for two hundred services is routine. Unity isn't that world. Unity instantiates your components for you, so something has to do late-binding resolution regardless of what you call it. The heavyweight DI frameworks respond to that by adding more ceremony, not less. Contexts, scopes, installers, factories, binding chains. Adopting Zenject is a lifestyle decision. You don't use Zenject so much as restructure your project around it.

Service locators are the opposite trade. Low friction, no framework imposed on the rest of your codebase, incremental. You can drop ServiceKit in to solve one pain point without rewriting everything around it.

The two classic critiques of service locators are hidden dependencies and async timing. V2 is where I've tried to put both to bed.

Hidden dependencies, un-hidden

[InjectService] on fields surfaces the dependency graph at the class level. It's not quite a constructor signature, but it's visible to code review, tooling, and the new Roslyn analyzers. That covers most of the "you can't see what a class needs" complaint.

[Service(typeof(IPlayerController))]
public class PlayerController : ServiceKitBehaviour, IPlayerController
{
    [InjectService] private IPlayerService _playerService;
    [InjectService] private IAudioService  _audioService;

    protected override void InitializeService()
    {
        _playerService.LoadPlayer();
    }
}

Two compile-time analyzers ship in V2:

SK003 flags [Service(typeof(IFoo))] attributes on classes that don't actually implement IFoo.
SK005 catches ServiceKitBehaviour subclasses that forget base.Awake(). Both catch the kind of bug that's annoying to hunt down at runtime.

Async resolution, the real headache fixed

This is the one I'm most pleased with. The traditional service locator's real failure mode in Unity isn't philosophical, it's the timing problem. You ask for IAudioService in Awake on the wrong GameObject, it isn't registered yet, you get null, and you're debugging initialisation order for three hours.

V2 resolves this cleanly. Field injection is a single await:

// V1
await _serviceKit.Inject(this)
    .WithErrorHandling()
    .WithTimeout()
    .ExecuteWithCancellationAsync(token);

// V2
await _serviceKit.InjectAsync(this, destroyCancellationToken);

And under the hood there's a new atomic 3-state resolution primitive that performs registration and readiness checks inside a single lock:

var status = locator.TryResolveService(typeof(IMyService), out var service);
// ServiceResolutionStatus.Ready
// ServiceResolutionStatus.RegisteredNotReady
// ServiceResolutionStatus.NotRegistered

Previously, consumers had to check registration, then readiness, then fetch, giving the world three chances to change between steps. V2 closes that window.

Alongside that: task forwarding in GetServiceAsync now happens inside locks, double-registration is blocked with Interlocked operations, and circular-dependency detection uses types rather than string comparison. Less likely to bite you in production.

Generics out, attributes in

The other big ergonomic change. V1 asked you to inherit from ServiceKitBehaviour<T>, which got painful fast when your own classes needed generics too. V2 replaces that with a plain base class and an explicit attribute:

// V1
public class AudioManager : ServiceKitBehaviour<IAudioService>, IAudioService { }

// V2
[Service(typeof(IAudioService))]
public class AudioManager : ServiceKitBehaviour, IAudioService { }

Registration intent is declarative instead of tangled in type parameters, and abstract base classes can keep their own generics without fighting ServiceKit's.

Migrating from V1

Mostly mechanical: drop the generic parameter on ServiceKitBehaviour, add [Service(typeof(IYourInterface))], and replace builder chains with InjectAsync(this, token). The README has the full migration guide, including how to handle abstract base classes that mix ServiceKit generics with their own.

Try it

Install via Package Manager → Add package from git URL:

https://www.pkglnk.dev/servicekit.git

Repo and docs: github.com/PaulNonatomic/ServiceKit

MIT licensed. Issues and PRs welcome. If you think I'm wrong about the locator vs DI trade-off, I want to hear it. V2 is the foundation I want to build on, so I'm happy to argue about it.