DEV Community: Harish Kotra (he/him)

Building Self-Healing LLM Agents with Agno and Streamlit

Harish Kotra (he/him) — Thu, 11 Jun 2026 18:32:57 +0000

LLM agents are powerful, but they make mistakes — especially when calling tools with misformatted parameters. What if we could make them self-healing? In this post, I'll walk through building a production-grade Streamlit application with 14 real-world scenarios where agents detect, diagnose, and correct their own errors automatically.

The Problem

When an LLM calls a tool with invalid parameters — a float instead of an integer, "tomorrow" instead of a date, "California" instead of "CA" — most systems simply fail. The user sees an error and has to start over. This breaks the illusion of autonomy and frustrates users.

The Solution: `RetryAgentRun`

The Agno framework provides a built-in mechanism: RetryAgentRun. When a tool raises this exception with a descriptive error message, the agent:

Receives the error
Reads the correction hint
Re-thinks the parameters
Retries the tool call automatically

This loop costs at most one extra LLM round-trip per failure, which is far better than a human having to debug and re-prompt.

Architecture Overview

User Prompt → Agno Agent → Tool Call (may be wrong)
                           ↓
                    Tool validates parameters
                           ↓
              Invalid? → Raise RetryAgentRun → Agent corrects → Retry
              Valid?   → Return result        → Done

Key Implementation Lessons

1. Use `Any` Type Annotations

This was the biggest gotcha. Pydantic validates annotated parameters before the function body runs. If you write:

def process_payment(amount: Annotated[int, ...], currency: str):
    ...

And the LLM passes 100.5 (a float), Pydantic raises a ValidationError before your function ever executes. The RetryAgentRun never fires.

The fix: use Any for all parameters and validate inside the function body:

from typing import Any

def process_payment(amount: Any, currency: str):
    if not isinstance(amount, int):
        raise RetryAgentRun(
            f"amount must be an int, got {type(amount).__name__} '{amount}'. "
            f"Convert floats to integers (e.g. {int(amount)})."
        )
    ...

2. Force the Agent to Make Mistakes

Self-healing only works if there's something to heal. The agent preamble instructs the model to pass exact user-provided values on the first call:

CRITICAL: Call the tool with the EXACT parameter values the user provides — 
do NOT convert, transform, or reformat them yourself. The tool will validate 
and return a detailed error message if anything needs to be fixed.

Without this, powerful models like GPT-4 or Llama 3 will pre-correct values themselves, and you never see the healing cycle in action.

3. Timeout Safety

Not all models support function/tool calling. A 60-second thread-pool timeout prevents the app from hanging:

with concurrent.futures.ThreadPoolExecutor(max_workers=1) as executor:
    future = executor.submit(agent.run, prompt)
    result = future.result(timeout=60)

4. Parsing the Timeline

Agno's Message objects include a tool_call_error boolean. By scanning messages and extracting tool call arguments, error messages, and results, we build a structured timeline that visualises the entire self-healing cycle — tool call → retry error → corrected retry → success.

14 Real-World Scenarios

The application covers 6 categories with 14 concrete use cases:

Category	Use Cases	What Heals
💰 Financial	Payment processing, Credit card validation	Float→int, formatted card numbers
📅 Scheduling	Appointment booking, Timezone conversion	Relative dates, ambiguous timezone codes
🖥️ DevOps	Server provisioning, URL health check	Port types, missing URL schemes
📧 Communication	Email validation, Phone formatting	Invalid emails, unformatted phones
📊 Data	Database queries, Data import, Address validation	Wrong tables, missing fields, state codes
🌍 Others	Inventory, Unit conversion, Sanitisation, Geocoding	SKU lookups, incompatible units, XSS content

Results & Metrics

The app tracks run history with per-use-case metrics:

Tool calls: total invocations per run
Self-heals: how many RetryAgentRun events were triggered and resolved
Success rate: percentage of runs that completed successfully

Interactive Plotly charts show trends over time and breakdowns by scenario.

Running It Yourself

pip install streamlit pandas plotly agno openai httpx pydantic
streamlit run app.py

Configure your provider in the sidebar — Ollama, OpenAI, or any OpenAI-compatible endpoint. The Test Connection button verifies reachability before you start.

Self-healing agents transform fragile LLM tool calls into robust, autonomous workflows. The combination of Agno's RetryAgentRun, careful type annotation strategy, and thoughtful prompt engineering creates a system that can detect and fix its own mistakes — automatically, in real time.

The full source code is available with 14 ready-to-run scenarios. Try it with your favourite model and watch the agent heal itself.

Code & more: https://www.dailybuild.xyz/project/160-self-healing-agent

Same Prompt, Multiple Local Models — Round 2: Static Site Generator

Harish Kotra (he/him) — Wed, 10 Jun 2026 15:10:52 +0000

Day before, I ran an experiment: give several local LLMs the exact same prompt (build a terminal-based roguelike game in Python 3) and compare what comes out. The goal was never to declare a winner — it was to see how architectural choices, edge-case handling, and failure modes diverge when the input is held perfectly constant.

The results were more interesting than I expected. Surface compliance was common; correct state management was not. Presentation polish sometimes masked mechanical defects. Failed generations were still useful data points.

So I did it again. Same methodology, different domain. This time: a static site generator.

The Experiment

Prompt

The models were given this prompt verbatim:

Act as an expert software engineer. Build a complete, single-file, production-ready
Python 3 static site generator (SSG). The program must run entirely from the command
line with zero external dependencies (standard library only).

You must implement the entire program in a single shot. Do not use placeholders,
TODOs, or truncated code.

The full prompt specified Markdown parsing (headings, bold, italic, lists, code blocks, links, horizontal rules, paragraphs), front matter support (title, date, description), HTML5 output with embedded CSS, auto-generated index page with working links, deterministic output, a --clean flag, proper error handling for missing directories and unreadable files, and an object-oriented architecture with distinct parsing/rendering/file-management responsibilities.

Models

Model	Output	Lines
Big Pickle	`ssg.py`	410
DeepSeek V4 Flash	`ssg.py`	583
Mimo 2.5	`ssg.py`	566
Nemotron Ultra	(empty)	0

Methodology

All folders preserved as raw, unedited artifacts.
Analysis based on source inspection, syntax parsing (python3 -m py_compile), and functional testing with sample Markdown content.
No edits were made to any model output.
Empty folders are treated as completion/reliability failures, not implementation comparisons.

Results: The Baseline

All three successful models passed syntax checks and produced valid HTML output on functional tests. Every model met the core prompt requirements:

✅ Markdown→HTML conversion (headings, bold, italic, unordered lists, ordered lists, inline code, fenced code blocks, hyperlinks, horizontal rules, paragraphs)
✅ Front matter parsing (title, date, description) with body stripping
✅ Complete HTML5 documents with <!DOCTYPE html>, <head>, <body>
✅ Embedded CSS stylesheet (no external resources)
✅ Auto-generated index.html listing all pages
✅ --clean flag for output directory reset
✅ Error handling for missing source directories
✅ Graceful handling of files with no .md content
✅ Per-file error logging without aborting the build
✅ Deterministic output (identical input → identical output)
✅ Object-oriented architecture with separated responsibilities

This baseline was important to establish. All three models did what the prompt asked. The interesting observations are in the divergences.

Divergence #1: The index.md Collision Problem

The prompt explicitly called out a subtle edge case:

If a file is named index.md, it should be rendered as a page (not replace the generated index).

Three models read this and produced three different solutions:

Big Pickle renamed the output file:

def output_path_for(self, source_path):
    name = source_path.stem
    if name == 'index':
        name = 'index-page'       # rename to avoid collision
    return self.output / f'{name}.html'

DeepSeek V4 Flash routed it to a subdirectory:

if md_file.stem == "index":
    relative_url = "pages/index.html"
else:
    relative_url = md_file.stem + ".html"

Mimo 2.5 did not handle it at all. An index.md source file would be written to output/index.html, silently overwriting the auto-generated site index. Same prompt, same warning — but the edge case was either missed or deemed unimportant.

This is a recurring pattern from the game experiment too, where the "exactly 3 choices" requirement was met differently by every model. Prompt edge cases are interpreted differently even when explicitly called out.

Divergence #2: Configurable Output Directory

The prompt says:

Each .md file must be converted to a corresponding .html file in an output/ directory (created if it doesn't exist).

Is output/ a hard requirement or a default? The models disagreed:

Big Pickle: Hardcoded to output/. No configuration option.
DeepSeek V4 Flash: Hardcoded to output/. No configuration option.
Mimo 2.5: Configurable via --output/-o flag, defaults to output/.

Only one model added customization. The other two treated "output/" as fixed. This is a small detail, but it reflects how models handle "configuration" hints in prompts — some stay literal, others extrapolate to flexibility.

Divergence #3: HTML Escaping (Security)

This is the most important quality gap in the experiment.

Big Pickle and DeepSeek V4 Flash both correctly escape HTML special characters before applying inline Markdown formatting:

# From Big Pickle's MarkdownParser
def _parse_inline(self, text):
    text = self._escape(text)  # &, <, >, " escaped first

    # Inline code — first to protect content from further parsing
    text = re.sub(r'`([^`]+)`', r'<code>\1</code>', text)
    text = re.sub(r'\*\*(.+?)\*\*', r'<strong>\1</strong>', text)
    # ...etc

Mimo 2.5 applies regex substitutions to raw text without prior escaping:

def _parse_inline(self, text):
    text = self.bold_pattern.sub(r'<strong>\1</strong>', text)
    text = self.italic_pattern.sub(r'<em>\1</em>', text)
    text = self.code_pattern.sub(r'<code>\1</code>', text)
    text = self.link_pattern.sub(r'<a href="\2">\1</a>', text)
    return text  # raw HTML from markdown content passes through unescaped

An _escape_html method exists in HTMLRenderer, but it is only used for metadata and title rendering — not for body content. This means user-provided Markdown content containing &, <, >, or raw HTML tags would produce unexpected (and potentially unsafe) output.

Two of three models got this right. The third had a perfectly clean implementation otherwise. This is exactly the kind of defect that is easy to miss in a single-shot generation but matters in production.

Divergence #4: Architecture Style

Each model chose a different architectural approach:

Big Pickle — Coordinated Class Dependencies

Big Pickle uses five classes with SiteGenerator as the orchestrator that composes FileManager, MarkdownParser, and HTMLRenderer. The FileManager is the most feature-rich of the three, handling file discovery, non-Markdown file counting, read/write, output preparation, and path collision resolution.

The pipeline flow is straightforward:

FileManager.find_markdown_files()
For each file: FrontMatter.parse() → MarkdownParser.parse() → HTMLRenderer.render() → FileManager.write()
_generate_index() → summary

DeepSeek V4 Flash — Block-Based Pipeline

DeepSeek separates parsing and rendering into two explicit phases with an intermediate representation. MarkdownParser splits text into semantic blocks stored as (type, content) tuples:

# Blocks look like:
("heading", (1, "My Title"))
("paragraph", "Some text here")
("code", ("python", "print('hello')"))
("unordered_list", ["item one", "item two"])

HTMLRenderer.render_block() then consumes these tuples polymorphically. This two-phase approach is the cleanest separation of concerns among the three implementations.

DeepSeek also went beyond the prompt by supporting blockquotes (>), language-tagged code blocks (<pre><code class="language-python">), and an extra_head injection point for custom <head> content.

Mimo 2.5 — Dataclass-Driven with Builder Pattern

Mimo uses Python @dataclass for clean data modeling:

@dataclass
class PageMetadata:
    title: str
    date: Optional[str] = None
    description: Optional[str] = None

@dataclass
class Page:
    filename: str
    source_path: str
    output_path: str
    metadata: PageMetadata
    content: str
    html: str

The SiteBuilder.build() method returns a bool rather than calling sys.exit() directly, giving callers more control over the exit flow. The index page sorts entries by date in descending order — a nice UX touch.

Divergence #5: Line Count vs. Completeness

The smallest implementation (Big Pickle, 410 lines) covered every prompt requirement. The largest (DeepSeek, 583 lines) added features beyond the prompt (blockquotes, language-tagged code blocks). Mimo (566 lines) also added UX extras (date-sorted index, short CLI flags).

Model	Lines	Extra features	Missing features
Big Pickle	410	index.md collision handling	No --output flag
DeepSeek	583	Blockquotes, lang tags, custom exceptions	No --output flag
Mimo 2.5	566	--output/-o flags, date-sorted index	No HTML escaping, no index.md handling

More code did not mean more completeness. Big Pickle was 30% smaller than DeepSeek but handled the index.md edge case that Mimo missed entirely.

Failure Case: Nemotron Ultra

The Nemotron Ultra folder is empty. Unlike the game experiment's Nemotron 3 Ultra, which at least captured an upstream timeout error message, this run produced nothing at all — no code, no error log, no artifact. This is a harder failure to diagnose and a reminder that generation reliability is a separate concern from generation quality.

Patterns Across Both Experiments

The game experiment (round 1) and the SSG experiment (round 2) share some common findings:

1. Surface compliance is the easy part

Every successful model in both experiments met the stated requirements. The divergences are in edge-case handling, subtle bugs, and architectural choices — not in whether the program runs.

2. Ambiguity drives divergence

The game prompt's "exactly 3 choices" was interpreted differently by every model. The SSG prompt's "output/ directory" got two interpretations. When a prompt leaves room for interpretation, models fill that room differently.

3. Security details are fragile

In the game experiment, Mimo 2.5 had hidden mutable global state that would cause bugs after repeated play. In the SSG experiment, Mimo 2.5 missed HTML escaping. These are both "works on first glance, fails under real use" defects.

4. Architecture ≠ correctness

The most architecturally clean implementation (Mimo 2.5's GameState/EventHandler/ChoiceGenerator/GameEngine separation in the game, DeepSeek's block-based pipeline in the SSG) also had the most subtle bugs. Clean code is not a guarantee of correct code.

5. Failures matter

Both experiments had a model that produced no output. These are not just null data points — they highlight reliability constraints in the generation pipeline itself.

Running the same experiment across two very different domains (a terminal game and a static site generator) reveals patterns that a single run couldn't. The same types of divergence — edge-case handling, architectural taste, security awareness — showed up in both.

The raw artifacts and full analysis are available at:

https://github.com/kotrats/same-prompt-multiple-local-models

The repo now contains both experiments with unedited model outputs, detailed comparison tables, architecture diagrams, and per-model observations. If you run your own experiments or have ideas for the next prompt to test, I'd love to hear about it.

All model outputs preserved as raw artifacts. No edits were made to any generated code. Analysis based on source inspection, syntax parsing, and functional testing.

Same Prompt, 4 LLMs: The Roguelike Showdown

Harish Kotra (he/him) — Mon, 08 Jun 2026 17:31:36 +0000

I gave four different LLMs exactly the same prompt: build a complete, single-file, terminal-based Python 3 roguelike game using only the standard library. Three models produced runnable code. One timed out before generating anything.

The goal was not to pick a winner. The goal was to see what changes when the prompt is held constant — and the results revealed more about LLM behavior than any leaderboard could.

The Prompt

The specification was detailed and unambiguous:

Build a terminal-based roguelike with player stats (Health 100, Gold 0, Attack 15), exactly 20 turns, 3 randomized choices per turn from a pool of 4+ event types (fight, chest, tavern, merchant), ANSI color-coded output, screen clearing, input validation, and an end-game summary.

Full prompt is in the repository README.

Architecture Diagram

Model-by-Model Analysis

DeepSeek V4 Flash (524 lines)

DeepSeek took the most architecturally disciplined approach. It defined an abstract Event base class and four concrete subclasses:

class Event:
    def describe(self, player): ...
    def can_afford(self, player): return True
    def execute(self, player): ...

class FightMonsterEvent(Event): ...
class ChestEvent(Event): ...
class TavernEvent(Event): ...
class MerchantEvent(Event): ...

Choices are generated by sampling event classes from a list, then instantiating them:

EVENT_CLASSES = [FightMonsterEvent, ChestEvent, TavernEvent, MerchantEvent]
chosen_types = random.sample(EVENT_CLASSES, k=3)
choices = [cls() for cls in chosen_types]

This polymorphic approach is clean and extensible — adding a new event type means adding one class and registering it in the list.

The bug: The end-game summary displays the player's current gold, not the lifetime gold accumulated. If you spend gold at taverns or merchants, the final figure under-reports. The prompt asked for "total Gold accumulated," but no lifetime counter was implemented.

MiniMax M3 (802 lines)

MiniMax went all-in on user experience. It added color fallback detection, health bars that change color (green > yellow > red), character-by-character slow-print narration, ASCII art banners, and a multi-tier verdict system.

Architecturally, it used a Choice class carrying a Callable closure:

class Choice:
    def __init__(self, key, title, description, color, action: Callable):
        self.key = key
        self.action = action

The game engine simply calls choice.action(self.player) — a clean dispatch pattern.

Choice generation used an interesting strategy. Instead of always showing all options, it filtered out unaffordable ones and padded with duplicates:

def generate_choices(player):
    pool = [make_fight_choice(), make_chest_choice()]
    tavern = make_tavern_choice(player)    # None if can't afford
    merchant = make_merchant_choice(player)
    if tavern:    pool.append(tavern)
    if merchant:  pool.append(merchant)
    while len(pool) < 3:
        pool.append(random.choice(pool[:2]))   # pad!
    random.shuffle(pool)
    return pool[:3]

The bugs: This padding strategy can produce duplicate choices (e.g., fight, chest, chest) on early turns. Also, like DeepSeek, it reports current gold rather than lifetime earned gold.

Mimo 2.5 (800 lines)

Mimo produced the cleanest architecture, splitting responsibilities across four classes:

GameState        — owns player stats + summary counters
EventHandler     — event execution, mutates GameState
ChoiceGenerator  — menu generation, affordability checks
GameEngine       — control flow, wires everything together

It was the only model that correctly tracked total_gold_earned:

class GameState:
    def __init__(self):
        ...
        self.total_gold_earned = 0
        self.monsters_slain = 0
        self.damage_dealt = 0
        self.damage_taken = 0

The hidden bug: Mimo stored live Monster instances in a global MONSTER_POOL and mutated them during combat. If the same monster object was selected again in a later fight, it could start with corrupted stats or even dead. This is precisely the kind of state-management defect that survives surface-level review.

There was also an off-by-one in turn tracking: a full 20-turn survival path would report 21/20 turns.

Nemotron 3 Ultra (0 lines)

Nemotron produced no game source. The captured error was:

write Failed
"Upstream idle timeout exceeded"

This is a reliability data point, not a code quality data point. It belongs in the comparison because if the experiment is "ask models to perform the same task," completion reliability is part of the outcome.

Lessons for Engineers Using LLM-Generated Code

1. Surface Compliance ≠ Correctness

All three successful models implemented ANSI colors, turn loops, combat, and summaries — the visible requirements. But the bugs were in edges and bookkeeping that a human reviewer would need to trace.

2. Cardinality Constraints Force Design Tradeoffs

The "exactly 3 choices" requirement pushed each model into a different strategy:

DeepSeek: Show all options, block unaffordable ones at execution time (player wastes a turn)
MiniMax: Filter unaffordable ones, pad with duplicates (violates "distinct" intent)
Mimo: Show unaffordable options with labels, route to handler anyway (most pragmatic)

None of these are obviously correct. The prompt was ambiguous, and each model resolved the ambiguity differently.

3. Architecture Quality and Correctness Are Independent Axes

Mimo had the cleanest state/handler/generator separation — and the most interesting hidden state bug (mutated global monsters). MiniMax had the most polished UX — and the most obvious choice-generation issue. Clean architecture is a good thing, but it doesn't guarantee correct behavior.

4. Bookkeeping Is the Weak Spot

Two out of three successful models got the "total gold accumulated" requirement wrong because they conflated "current gold" with "lifetime earned gold." This is a pattern: LLMs are good at generating visible features but often miss exact semantic bookkeeping.

5. Failed Runs Are Still Useful

The Nemotron timeout tells us something about infrastructure reliability. When evaluating LLMs for real work, completion rate is a legitimate metric — separate from code quality.

A Practical Review Checklist

Based on this experiment, here is a review lens for generated code:

Check visible prompt compliance — does the broad structure match?
Check edge-case semantics — are numbers genuinely correct, not just present?
Check hidden mutable state — are objects shared where they should be copied?
Check final-summary bookkeeping — does "total X" mean what it says?
Separate model quality from infrastructure reliability — a timeout is not bad code.

Running the Games

Everyone can run these locally — no dependencies required:

python3 deepseek-v4-flash/roguelike.py
python3 minimax-m3/rogue.py
python3 mimo-2.5/roguelike.py

The most useful result from this experiment is not a ranking. It is the observation that same-prompt comparisons reveal different model instincts:

One model optimized for concise, prompt-faithful coverage.
One optimized for presentation and game feel.
One optimized for clean, separated architecture.
One failed at the execution layer before code could be evaluated.

For real engineering work, that suggests a practical approach: use LLMs for drafts, apply structured review for correctness, and never assume that compliant-looking output is correct output.

Outputs

Code and more: https://www.dailybuild.xyz/project/157-same-prompt-multiple-local-models

Building PromptVault: An Encrypted AI Prompt Marketplace with Fully Homomorphic Encryption

Harish Kotra (he/him) — Sat, 06 Jun 2026 19:07:23 +0000

The Problem

AI prompts have become digital assets. A carefully crafted prompt can save
hours of iteration — the difference between a generic ChatGPT response and
something genuinely useful. People invest real time into engineering these
prompts, and a marketplace is the natural next step.

But there's a fundamental tension: a buyer needs to see the prompt to know
it's valuable, but the creator can't reveal it without getting paid.

Traditional marketplaces solve this with "trust me" — you pay, and the seller
sends you the content. That works until it doesn't. Chargebacks, fake
prompts, sellers who disappear after the sale.

PromptVault replaces trust with cryptography.

Why Fully Homomorphic Encryption?

Fully Homomorphic Encryption (FHE) is a cryptographic primitive that lets you
compute on encrypted data without ever decrypting it. The CoFHE coprocessor
from Fhenix brings this to Ethereum: smart contracts can manipulate encrypted
values using operations like FHE.add(), FHE.mul(), and — most importantly
for our use case — FHE.allow().

FHE.allow(encryptedValue, address) grants a specific wallet the ability to
decrypt a ciphertext. The smart contract can do this atomically: the buyer
pays, and the contract calls FHE.allow() in the same transaction. No second
step, no trust required.

This is the key enabling technology: the encryption key never appears in
plaintext anywhere — not on-chain, not in an API response, not in any
database. It exists only transiently in the browser of the authorised buyer
or creator, reconstructed from FHE ciphertexts stored on-chain.

The Architecture Decision: AES + FHE Hybrid

Pure FHE has a constraint: each encrypted value is limited to 128 bits
(euint128). A typical AI prompt is 200–2,000 bytes. Encrypting it directly
with FHE is impractical.

The solution is a two-layer encryption model:

Layer	Algorithm	What it encrypts	Where stored
1	AES-256-GCM	Prompt body (any length)	IPFS (Pinata)
2	FHE (CoFHE)	AES-256 key (split into 2×128b halves)	Sepolia blockchain

This hybrid approach removes the size limit entirely. Encrypt the prompt body
with a fast symmetric cipher (AES-256-GCM), then use FHE to gate access to
the symmetric key. The prompt ciphertext on IPFS is public — it's useless
without the AES key, which is FHE-gated on-chain.

The 256-bit AES key is split into two 128-bit halves (key0 and key1),
each stored as an euint128 on-chain. To reconstruct: bytes32(key0 << 128 | key1) in big-endian byte order.

The Smart Contract

PromptVault.sol

The Solidity contract is the core of the system. It uses @fhenixprotocol/cofhe-contracts for the FHE.sol library.

Deployed address: 0xc369bd84AE4a4468DA5635619e62F942BeaF5DA3 on Sepolia.

Listing Flow

function listPrompt(
    InEuint128 calldata encryptedKey0,
    InEuint128 calldata encryptedKey1,
    string     calldata title,
    string     calldata category,
    string     calldata metadataURI,
    string     calldata promptCID,
    uint256             priceWei
) external returns (uint256 listingId)

The creator encrypts their AES key halves in the browser using the CoFHE SDK,
sending InEuint128 structs (ciphertext + ZK proof) to the contract. The
contract validates the ZK proofs via FHE.asEuint128(), stores the encrypted
handles, and sets two ACL entries:

FHE.allowThis() — the contract retains access so it can grant access to buyers later
FHE.allowSender() — the creator can verify their own listing

The prompt body (AES ciphertext) goes to IPFS via Pinata. The CID is stored
on-chain as a string.

Purchase Flow

function purchasePrompt(uint256 listingId) external payable

The buyer sends ETH equal to priceWei. The contract:

Verifies the listing is active, the buyer hasn't already purchased, and the buyer isn't the creator
Calls FHE.allow(keyPart0, buyer) and FHE.allow(keyPart1, buyer) — permanently granting decryption access
Records the purchase
Splits payment: 97.5% to creator, 2.5% platform fee

Key design property: FHE.allow() is permanent. Once a buyer gets access,
it cannot be revoked. This means buyers keep access even if the creator
delists — a deliberate trade-off for atomicity (no revoke means no race
conditions on access control).

Revenue Model

The platform takes 250 basis points (2.5%). The feeRecipient is set to the
deployer in the constructor. Earnings accumulate in a mapping and can be
withdrawn at any time via withdrawEarnings(). The contract follows the
checks-effects-interactions pattern — zeroing the balance before the external
call to prevent re-entrancy.

Key View Functions

getListing(listingId) — returns all metadata (title, category, price, sales count, etc.) but not the key handles
getKeyHandles(listingId) — returns the euint128 handles, but only for the creator or a verified purchaser (reverts with NotAuthorised otherwise)
getListings(offset, limit) — paginated listing IDs
hasPurchased(listingId, buyer) — check purchase status
pendingEarnings(account) — unpaid earnings balance

Error Handling

The contract uses custom errors (solidity revert) instead of string messages
for gas efficiency: ListingDoesNotExist, AlreadyPurchased,
IncorrectPayment, CreatorCannotBuyOwnPrompt, and ten more covering every
edge case.

Test Coverage

41 tests across 9 describe blocks, covering deployment, listing creation with
all validation paths, purchase flow (success and all error states), delisting,
earnings and withdrawals, authorised key handle access, and paginated
enumeration.

The Frontend

Stack

Layer	Choice
Framework	Next.js 14 (App Router)
Blockchain	Wagmi v2 / viem 2.x
FHE	@cofhe/sdk 0.5.2
State	@tanstack/react-query (server reads)
Styling	Tailwind CSS v3 + shadcn/ui v4
IPFS	Pinata (JWT-based upload)
WYSIWYG	@uiw/react-md-editor
Crypto	Web Crypto API (SubtleCrypto)

Data Flow: Listing a Prompt

This is the most complex operation in the application, involving multiple
cryptographic operations across different systems:

browser → AES-256 keygen → split into 2 halves → encrypt prompt with AES
    → upload ciphertext to IPFS → get CID
    → encrypt key halves with CoFHE SDK → get InEuint128 structs
    → wallet.writeContract("listPrompt", [encKey0, encKey1, ..., cid, price])

The useListPrompt hook orchestrates this entire pipeline. Key detail: the
AES key is generated using the browser's crypto.subtle.generateKey() with
{ name: "AES-GCM", length: 256 } — the same primitive used by Signal,
WhatsApp, and every modern browser. The key is exported as raw bytes, split
into two bigint values (128 bits each), and encrypted by the CoFHE SDK
before being sent to the contract.

Data Flow: Purchasing a Prompt

buyer → wallet.writeContract("purchasePrompt", id, { value })
    → FHE.allow(key0, buyer) + FHE.allow(key1, buyer) [atomic tx]
    → contract.read.getKeyHandles(id) → euint128 handles
    → CoFHE SDK decrypts handles → two bigint halves
    → reconstruct AES-256 key from halves
    → download ciphertext from IPFS
    → AES-GCM decrypt → plaintext

A critical detail: getKeyHandles() is a view function — it doesn't cost
gas. The buyer only pays gas for the purchasePrompt transaction. The key
handles are fetched after the transaction confirms, and the CoFHE SDK decrypts
them locally in the browser. The AES key is materialised as a browser-native
CryptoKey object and never persisted — no localStorage, no cookies, no
network send. When the user navigates away, the key is gone.

SSR Safety and the CoFHE SDK

The CoFHE SDK uses IndexedDB internally (for cached FHE keys and WASM
modules), which doesn't exist on the server. The client is initialised via a
dynamic import("@cofhe/sdk/web") guarded by typeof window === "undefined".
The singleton pattern in cofhe.ts ensures a single client instance with
lazy initialisation:

async function initClient() {
  if (typeof window === "undefined") return;
  const [{ createCofheClient, createCofheConfig }, { sepolia }] =
    await Promise.all([
      import("@cofhe/sdk/web"),
      import("@cofhe/sdk/chains"),
    ]);
  const config = createCofheConfig({ supportedChains: [sepolia] });
  cofheClient = createCofheClient(config);
}

Version Debugging: The 0.4.0 → 0.5.2 Migration

During development, we encountered a cryptic error when calling
encryptInputs():

Failed to fetch FHE key and CRS
Caused by: Error serializing FHE publicKey
Error: Custom("invalid value: integer `7809075072243073024`, expected usize")

The value 7809075072243073024 in hex is 0x6C6F6F6B — ASCII for "look".
The CoFHE SDK was receiving a text response (likely an error page or redirect)
instead of binary FHE key data, and the bincode deserializer was trying to
interpret the text as a usize.

The root cause: @cofhe/sdk 0.4.0 had stale testnet coordinator URLs. When
the SDK tried to fetch the FHE public key from the old endpoint, it got an
unexpected response. Upgrading to @cofhe/sdk 0.5.2 (with updated chain
configurations) resolved the issue.

WYSIWYG Markdown Editor

The prompt content field uses @uiw/react-md-editor in live-preview mode.
Users get a full toolbar (bold, italic, headings, lists, code blocks) and see
their rendered markdown below the editor in real-time. The prompt is submitted
as raw markdown text — the AES encryption happens on the raw text, and buyers
see it rendered via react-markdown after decryption.

Security Model

Trust assumptions:
├── Creator is honest about prompt content
├── Buyer has a legitimate wallet (no Sybil defense)
└── Sepolia RPC provider does not inspect traffic

What the contract protects against:
├── Platform operator reading prompt content
├── Third-party blockchain observer reading prompt content
├── Non-purchasers decrypting the AES key
└── Front-running purchase transactions

What is NOT protected:
├── Buyer sharing decrypted content (no DRM)
├── Malicious JavaScript in prompt (no sandbox)
└── Creator listing stolen/plagiarised prompts

The threat model is honest-but-curious for all parties except the contract
itself, which is trustless by design. The hybrid AES+FHE architecture means
a compromise of the IPFS gateway, the RPC provider, or the Vercel deployment
does not leak prompt content. The only way to decrypt is to hold a wallet
that the contract has authorised via FHE.allow().

This isn't DRM. Once a buyer decrypts the prompt, they can share it. We're
solving the discovery-and-payment problem, not preventing piracy.

What I'd Do Differently

CoFHE SDK version pinning: Locking to exact versions and testing
against the live testnet earlier would have caught the endpoint mismatch
sooner. The 0.4.0 → 0.5.2 jump required viem upgrades and type casting.
Field size consideration: euint128 is sufficient for AES-128, but
for AES-256 we need two handles. If the CoFHE protocol adds euint256
support, the smart contract could be simplified to store a single handle.
Local permit caching: The CoFHE SDK's permit system requires a MetaMask
signature each session. Caching the permit hash in sessionStorage would
eliminate the redundant signing step on page reloads.

The Code

All code is open-source on GitHub: harishkotra/promptvault

contracts/PromptVault.sol — The FHE-enabled smart contract with ACL-based key gating
frontend/src/lib/aes.ts — AES-256-GCM key generation, splitting, reconstruction, encrypt, and decrypt using Web Crypto API
frontend/src/lib/cofhe.ts — CoFHE client singleton with SSR safety
frontend/src/lib/ipfs.ts — Pinata-based IPFS upload and download
frontend/src/hooks/useListPrompt.ts — End-to-end encryption pipeline
frontend/src/hooks/usePurchasePrompt.ts — On-chain purchase + local decryption flow
frontend/src/lib/contract.ts — Full ABI with complete function and error signatures

Built With

Fhenix CoFHE — FHE coprocessor for Ethereum
Hardhat — Smart contract development
Next.js 14 — React framework
Wagmi — Ethereum hooks for React
shadcn/ui — Component library
Pinata — IPFS pinning service

Screenshots

Code and more: https://www.dailybuild.xyz/project/156-promptvault

Conclave: Confidential Multi-Agent Consensus on Ethereum Using Fully Homomorphic Encryption

Harish Kotra (he/him) — Sat, 06 Jun 2026 19:02:21 +0000

How we built a protocol where AI agents vote on subjective tasks without ever revealing their individual scores — using FHE, Solidity, and a dark-terminal frontend.

The Problem

When multiple AI agents evaluate the same task — an LLM output, a code review, a creative brief — their individual scores carry valuable signal. But today's on-chain voting has a fundamental flaw: every vote is visible.

This creates three problems:

Anchoring — The first score revealed biases all subsequent voters. If Agent A submits an 87, Agent B is subconsciously pulled toward 87 rather than evaluating independently.
Collusion — Agents can coordinate to manipulate the consensus by adjusting their scores after seeing peers' submissions.
Chilling effects — An agent that wants to submit an honest low score (say, 30) may hesitate if other agents or the round creator can see it and retaliate.

Existing solutions — multi-sigs, DAO voting, commit-reveal schemes — all leak individual votes at some point in the lifecycle. Commit-reveal just delays the reveal; it doesn't prevent it.

What we needed was a way to compute the average of encrypted inputs — and only decrypt the final result.

The Solution: FHE-Based Consensus

Fully Homomorphic Encryption (FHE) lets you perform arithmetic directly on ciphertexts. You can add, subtract, multiply, and divide encrypted numbers — and the result, when decrypted, equals what you'd get by operating on the plaintexts.

Conclave uses Fhenix's CoFHE (Confidential FHE) SDK to implement a multi-agent consensus protocol where:

Scores are encrypted on the client side — no one, including the contract, ever sees a plaintext score
The contract sums ciphertexts using FHE — the running total stays encrypted throughout
Only the final average is decrypted — by a threshold network of FHE nodes, after all agents have committed

Individual scores remain encrypted forever.

Agent 1 ───── encrypt(87) ─────┐
                                ▼
Agent 2 ───── encrypt(92) ───► FHE.sum() ──► FHE.div() ──► avg = 81
                                ▲
Agent 3 ───── encrypt(64) ─────┘
                                        │
                              Threshold Decrypt
                                        │
                                   81/100

The Protocol

Conclave's protocol has five phases, encoded as a Solidity enum:

enum Phase { Voting, Revision, Finalized, Revealed }

1. Create

The round creator specifies:

A list of agent addresses (2–50)
A task URI (either a URL or inline data:application/json URI)
A revisionsEnabled flag

The contract initializes two FHE accumulators — encryptedSum and encryptedCount — both set to FHE.asEuint32(0). These will hold the running total and count in encrypted form.

r.encryptedSum   = FHE.asEuint32(0);
r.encryptedCount = FHE.asEuint32(0);

FHE.allowThis(r.encryptedSum);
FHE.allowThis(r.encryptedCount);

The allowThis calls are CoFHE's permission model — they grant the contract itself the ability to read (and operate on) these encrypted values.

2. Vote

Each agent:

Fetches the task from the URI
Scores it via an LLM (e.g., GPT-4o), producing a plaintext integer 0–100
Encrypts it client-side using @cofhe/sdk:

const [encrypted] = await cofheClient
  .encryptInputs([Encryptable.uint32(BigInt(score))])
  .execute();

Submits the InEuint32 ciphertext to the contract

The contract decrypts nothing. It adds the ciphertext to the encrypted sum using pure FHE arithmetic:

euint32 score = FHE.asEuint32(encryptedScore);
euint32 newSum = FHE.add(r.encryptedSum, score);
r.encryptedSum = newSum;

euint32 newCount = FHE.add(r.encryptedCount, FHE.asEuint32(1));
r.encryptedCount = newCount;

3. Revision (Optional)

If the creator enabled revisions, they can open a revision window after all agents have voted. Agents who already voted can submit a new encrypted score. The contract subtracts the old ciphertext and adds the new one — all in the encrypted domain:

euint32 sumAfterRemoval = FHE.sub(r.encryptedSum, oldScore);
euint32 newSum = FHE.add(sumAfterRemoval, newScore);
r.encryptedSum = newSum;

This is the power of FHE: the contract can update values without ever seeing what those values are.

4. Finalize

Once quorum is met, the creator locks the round. The contract computes the encrypted average:

euint32 avg = FHE.div(r.encryptedSum, r.encryptedCount);

It stores this encrypted average as consensusHandle and moves the phase to Finalized. At this point, no more votes or revisions are accepted.

5. Reveal

The Fhenix threshold network decrypts the average. revealConsensus() is called with the plaintext result and a cryptographic proof:

function revealConsensus(uint256 roundId, euint32 ctHash, uint32 plaintext, bytes calldata signature) external {
    FHE.publishDecryptResult(ctHash, plaintext, signature);
    r.consensusScore = plaintext;
    r.phase = Phase.Revealed;
}

The threshold network ensures that no single party can forge a decryption — the signature proves a quorum of FHE nodes validated the result.

Smart Contract Architecture (353 Lines)

The entire protocol fits in a single Solidity contract. Key design decisions:

Errors, Not Strings

18 custom errors for gas-efficient reverts. This is Solidity best practice — custom errors are cheaper than require with string messages and provide typed data for frontend handling.

error QuorumNotMet(uint256 roundId, uint32 submitted, uint32 required);
error ScoreOutOfRange(uint32 plaintext, uint32 max);
error RevisionNotEnabled(uint256 roundId);

Permission Model

CoFHE requires explicit allow calls for every encrypted value — otherwise it's inaccessible. The contract scopes access tightly:

FHE.allowThis() — the contract itself can read and operate on the value
FHE.allow(score, msg.sender) — the submitting agent can read their own score later
FHE.allowPublic() — only called on the final average, so the threshold network can decrypt it

Without these permits, even the contract deployer cannot decrypt individual votes.

Zero-Knowledge About Individual Inputs

The contract never stores plaintext scores. The mapping storing each agent's vote is:

mapping(uint256 => mapping(address => euint32)) private _agentScoreHandle;

This is an encrypted handle, not a plaintext value. Even a storage-level attack on the blockchain would only yield ciphertexts.

The Agent Runner

The agent/ directory contains a Node.js/TypeScript runner that:

Polls the contract every 30 seconds
Fetches the task from the on-chain URI
Sends it to an OpenAI-compatible LLM with the scoring rubric
Encrypts the score using @cofhe/sdk/node
Submits the encrypted ciphertext via submitVote()

We recently refactored it to accept a --agent flag so each agent runs in its own terminal:

npx ts-node agent/index.ts --agent 1
npx ts-node agent/index.ts --agent 2
npx ts-node agent/index.ts --agent 3

The agent process is stateless — it reads everything it needs from the contract. You can kill and restart any agent, and it will pick up where it left off.

Rate Limiting

Running 3 agents against Infura's free tier quickly hits rate limits. We added exponential backoff with jitter:

async function withRetry<T>(fn: () => Promise<T>, attempt = 1): Promise<T> {
  try {
    return await fn();
  } catch (e: any) {
    if (e?.code === "BAD_DATA" && attempt < 6) {
      const delay = Math.min(1000 * 2^attempt + Math.random() * 1000, 30_000);
      await new Promise((r) => setTimeout(r, delay));
      return withRetry(fn, attempt + 1);
    }
    throw e;
  }
}

Each agent also starts with a random 0–5s stagger and desynchronizes its poll interval by ±2.5s.

The Frontend

The frontend is a Next.js 14 App Router application with a visual identity inspired by Linear, Vercel, and Stripe — clean, monochrome, with a single purple accent (#c084fc).

Design System

The palette is deliberately restricted:

Base: #040816 (near-black blue)
Surfaces: #070B1F, #0A0F2A, #1A1F3A
Accent: #c084fc (purple, single use)
Success: #22c55e (emerald)
Warning: #f59e0b (amber)
Borders: thin, 1px solid #1A1F3A

No gradients. No blur effects. No box shadows. The "glass" card is achieved with flat color and a thin border — no backdrop-filter:

.glass {
  background: rgba(10, 15, 42, 0.6);
  border: 1px solid rgba(30, 35, 60, 0.6);
}

Pages

Route	Purpose
`/`	Landing page (hero, protocol explainer, FHE comparison) when disconnected. Switches to round list when wallet connects.
`/create`	4-step wizard: Task, Agents, Rules, Launch. Supports inline task entry (title, description, rubric) or URL paste.
`/round/[id]`	Mission control. Two-column layout: protocol execution flow on the left, agent telemetry on the right.

Key Components

FhePipeline — Vertical stage diagram showing the protocol execution flow with animated timeline connectors
AgentList — Participant identity cards showing wallet address, vote status, ciphertext count, and local decrypt
ConsensusResult — SVG ring meter with the final score and protocol completion bar
RoundCard — Protocol timeline with horizontal phase indicators (Created → Voting → Revision → Finalized → Revealed)
VoteForm — Encrypted vote slider with encrypt-then-submit flow
ProtocolStrip — Phase status bar at the top of every round detail page

The Consensus Visualization

The landing page features an animated SVG showing the full protocol flow: agent nodes pulse, data packets travel downward into an FHE computation box, then through threshold decryption, and finally the consensus score appears with a scale-in animation.

@keyframes data-packet {
  0%   { opacity: 0; transform: translateY(0); }
  25%  { opacity: 1; }
  75%  { opacity: 1; }
  100% { opacity: 0; transform: translateY(68px); }
}

Testing

52 test cases covering the full protocol spec. Run with:

npx hardhat test

Breakdown:

Group	Tests	What It Covers
Create Round	4	Quorum validation, duplicates, empty URI, max agents
Submit Vote	6	Encryption path, submission, double-vote rejection, agent-only access
Revision	8	Open, revise, re-revision rejection, disabled-round
Finalize	6	Quorum check, re-finalize rejection, encrypted average
Reveal	6	Threshold decrypt, score bounds, double-reveal
ACL	6	Permission model, allowThis/allow scoping
Full E2E	8	No-revision path, with-revision path, all phases
Truncation	8	Score boundaries, div-by-zero safety

Test Helper: FHE

Testing FHE contracts requires a local CoFHE node. The test helper sets up the environment:

// test/helpers/fhe.ts
import { createCofheConfig, createCofheClient } from "@cofhe/sdk/node";
// ... configures hardhat in-process environment

Deployment

The contract is deployed on Ethereum Sepolia at:

0x0C83824a9800f9ED1e22ec289CB67E065ceA73C2

Deployment via Hardhat:

npx hardhat run scripts/deploy.ts --network sepolia

The deploy script uses dynamic gas pricing — 2 × baseFee + maxPriorityFeePerGas — to avoid "max fee per gas less than block base fee" errors that plagued earlier versions with hardcoded caps.

What We Learned

1. FHE is production-ready (with caveats)

The Fhenix CoFHE SDK works. Client-side encryption is straightforward. The threshold decryption network adds latency (5–15 seconds for decrypt), but it's reliable on Sepolia. The biggest friction point was configuration: the SDK's environment option accepts "node", "hardhat", "web", or "react" — not chain names like "sepolia".

2. Monorepos need explicit Vercel config

The frontend lives in frontend/ but Vercel expects the root to contain the Next.js app. The solution: set Root Directory to frontend/ in the Vercel project settings. vercel.json's rootDirectory property isn't valid when the project is already linked via GitHub — you must use the dashboard.

3. Hydration errors are a wagmi footgun

useAccount() returns different values on the server vs client, causing React hydration mismatches. The fix: use a mounted state guard that renders a static placeholder until useEffect fires on the client.

const [mounted, setMounted] = useState(false);
useEffect(() => setMounted(true), []);
if (!mounted) return <StaticPlaceholder />;

4. Infura's free tier is aggressive

3 agents × multiple eth_calls per poll × 30s interval = rapid rate limiting. Solution: exponential backoff, staggered startup, desynchronized poll intervals.

5. WASM circular dependencies

CoFHE's WebAssembly workers create circular webpack chunks. They're harmless but noisy. Suppress with:

config.ignoreWarnings = [/Circular dependency.*cofhe_sdk/];

Project Structure

conclave/
├── contracts/
│   └── Conclave.sol           # 353 lines, full protocol
├── frontend/
│   └── src/
│       ├── app/               # 4 routes (layout, home, create, round)
│       ├── components/        # 6 React components
│       ├── hooks/             # 6 custom hooks (useRound, useVote, etc.)
│       ├── lib/               # ABI, chain config, CoFHE client
│       └── types/             # Phase enum, Round interface
├── agent/
│   ├── index.ts               # Agent runner with --agent flag
│   ├── llm.ts                 # OpenAI-compatible scoring
│   └── wallets.ts             # Wallet management
├── test/
│   ├── Conclave.test.ts       # 52 tests
│   └── helpers/
│       └── fhe.ts             # FHE test utilities
└── scripts/
    └── deploy.ts              # Hardhat deployment

Try It Yourself

Prerequisites

3 Sepolia-funded agent wallets (~0.005 ETH each)
An OpenAI API key
SEPOLIA_RPC_URL (Alchemy recommended over Infura)

Quick Start

git clone https://github.com/harishkotra/conclave
npm install

# Set up .env
cp .env.example .env
# Fill in: SEPOLIA_RPC_URL, AGENT_{1,2,3}_PRIVATE_KEY, LLM_API_KEY

# Deploy the contract (or use the existing one at 0x0C83...)
npm run deploy

# Start the frontend
cd frontend && npm run dev

# In 3 separate terminals, run the agents:
npx ts-node agent/index.ts --agent 1
npx ts-node agent/index.ts --agent 2
npx ts-node agent/index.ts --agent 3

# Create a round on the frontend with those 3 agent addresses
# Watch the protocol execute

Future Work

Multi-round scheduling: An auction or queue where rounds are processed in batches
Gas optimization: The current contract makes multiple FHE operations per vote; batching could reduce costs
Slashing: Penalties for agents that submit scores but fail to revise when the revision phase opens
VC (Verifiable Computation) proofs: Prove that the FHE computation was correct without relying on the threshold network
Agent reputation: Track historical score deviations from consensus to weight future votes

Conclave is open source. Built with Solidity, Fhenix CoFHE, Next.js, and TypeScript.

Screenshots

Code and more: https://www.dailybuild.xyz/project/155-conclave

Deep Dive: Bypassing Browser Memory Caps to Build an Instant 7,000+ AI Model Compatibility Engine

Harish Kotra (he/him) — Fri, 05 Jun 2026 18:10:18 +0000

As local hardware models grow in popularity, choosing the right LLM configuration has been plagued by a difficult friction: "Will this actually load on my machine, or will it thrash my RAM and lock up my system?"

In this post, we explain how we built ModelFit, a high-precision browser-based estimator covering more than 7,000 AI models. We unpack how we bypassed standard browser device privacy caps using async WebGPU profiling, how quantization file sizing is calculated in the browser, and the mathematics driving the matching core.

The Core Technical Core

                                  +-----------------------------+
                                  |    Browser Hardware API     |
                                  | (Navigator Global Probe)    |
                                  +--------------+--------------+
                                                 |
                                                 | (gpuName, RAM limits, Cores)
                                                 v
                                  +-----------------------------+
                                  |   WebGPU Async Adapter /    |
                                  |    Limit Fingerprinting     |
                                  +--------------+--------------+
                                                 |
                                                 | (Precise hardware specs)
                                                 v
   +-------------------------+    +-----------------------------+   +------------------------+
   |  AI Model Directory API |--->|   Real-Time Match Engine    |<--| Local Storage Overrides|
   |   (7,400+ entries)      |    |   & Compatibility Scorer    |   +------------------------+
   +-------------------------+    +--------------+--------------+
                                                 |
                                                 | (Score & memory estimations)
                                                 v
                                  +-----------------------------+
                                  |     Smart Recommendations   |
                                  |    Interactive Model Hub    |
                                  +-----------------------------+

1. Bypassing the browser's 8GB Fingerprinting Cap

Historically, modern browsers constrain navigator.deviceMemory to 8 GB regardless of whether a developer has 16GB, 32GB, or 128GB of installed RAM. This is an intentional security design to limit tracking fingerprinting.

To overcome this, ModelFit implements a hybrid device signature analyzer. We first examine the synchronous browser properties, and then initiate an asynchronous WebGPU Probe to query the active hardware boundaries:

// Query GPU boundaries asynchronously
const adapter = await (navigator as any).gpu.requestAdapter();
if (adapter) {
  const limits = adapter.limits;

  // High-performance adapters typically support a storage buffer binding size > 2GB
  const maxBindingSize = limits.maxStorageBufferBindingSize || 0;

  if (maxBindingSize > 2147483648) { 
    // This indicates professional desktop hardware (RTX 3090, 4095/4090, Apple Pro/Max Silicon)
    // We adjust current memory estimates upwards to realistic configurations based on GPU VRAM levels:
    if (gpuType === 'nvidia') {
      vram = 24; 
      ram = 64; // High VRAM GPUs are almost universally paired with strong 32G or 64G RAM setups
    }
  }
}

By correlating CPU cores (navigator.hardwareConcurrency), GPU manufacturer strings, and explicit WebGPU hardware limits, we reconstruct a near-perfect guess of user hardware with zero server-side telemetry or active fingerprint tracking.

2. Quantization and Parameter Arithmetic

A model's actual disc footprint and execution VRAM depend heavily on its parameter size ($P$) and bits used per weight ($B$). The basic memory calculation for local weights is formulated as:

$$\text{Estimated VRAM} = \frac{P \times B}{8} \times \lambda$$

Where:

$P$ is the parameter count in billions (e.g. 7.2B for Qwen-7B).
$B$ represents the active quantization precision (typically 4-bit for standard GGUF configurations, 8-bit, or 16-bit float).
$\lambda$ is the overhead multiplier (we use $1.2$ to safely account for standard KV Cache, Context Window memory, and backend framework loading overhead).

Here is our browser implementation:

export function estimateModelSize(parameterSize: number, quantization: QuantizationLevel): number {
  if (!parameterSize) return 0;

  let bitsPerWeight = 16;
  switch (quantization) {
    case 'Q2': bitsPerWeight = 2.5; break;
    case 'Q3': bitsPerWeight = 3.5; break;
    case 'Q4': bitsPerWeight = 4.5; break;
    case 'Q5': bitsPerWeight = 5.5; break;
    case 'Q6': bitsPerWeight = 6.5; break;
    case 'Q8': bitsPerWeight = 8.5; break;
    case 'FP16': bitsPerWeight = 16; break;
    default: bitsPerWeight = 4.5; // Optimal GGUF standard default
  }

  // standard size + KV overhead
  const baseSize = (parameterSize * bitsPerWeight) / 8;
  const overhead = baseSize * 0.2; // 20% Context buffer

  return parseFloat((baseSize + overhead).toFixed(1));
}

3. Designing a Smooth Progress Engine

Developers want immediate visual signals. We added clean progress indicators embedded directly in each model item. This allows users to easily visualize what percentage of their RAM is consumed by any given model:

{sizeGB !== null && sizeGB > 0 && (
  <div className="mt-1 max-w-[280px] space-y-1">
    <div className="flex justify-between items-center text-[10px] font-mono text-slate-400">
      <span className="font-semibold text-slate-500">Local RAM Needed: {sizeGB} GB</span>
      <span>{Math.min(Math.round((sizeGB / specs.ram) * 100), 100)}% of {specs.ram}G</span>
    </div>
    <div className="w-full h-1.5 bg-slate-100 rounded-full border border-slate-200/50 overflow-hidden">
      <div 
        className={`h-full rounded-full transition-all duration-500 ${
          comp.status === 'smooth' ? 'bg-emerald-500' :
          comp.status === 'partial' ? 'bg-amber-500' : 
          comp.status === 'cloud' ? 'bg-sky-500' : 'bg-rose-500'
        }`}
        style={{ width: `${Math.min(Math.round((sizeGB / specs.ram) * 105), 100)}%` }}
      />
    </div>
  </div>
)}

4. Ranking the Best Fits in Real-Time

To minimize developer friction, we implemented a Smart Recommendations Card. Rather than requiring a user to sort through the exhaustive list, we parse open model weights and project their compatibility rankings instantly, picking the top 3 options:

const smartRecommendations = useMemo(() => {
  const openModels = flatModels.filter(m => m.model.open_weights === true);

  const scored = openModels.map(m => {
    const comp = evaluateCompatibility(m.model, specs, quant);
    const params = m.model.parsedParams || 7;

    let statusScore = 0;
    if (comp.status === 'smooth') statusScore = 1500; // Perfect fit
    else if (comp.status === 'partial') statusScore = 500; // Workable CPU fallback

    return {
      entry: m,
      comp,
      score: statusScore + params
    };
  });

  return scored
    .filter(x => x.comp.status === 'smooth' || x.comp.status === 'partial')
    .sort((a, b) => b.score - a.score)
    .slice(0, 3);
}, [flatModels, specs, quant]);

Custom Quantization Evaluator: Empower users to declare their own quantization depth (e.g. Q4_K_M vs Q8_K_S) to get absolute byte precision.
WASM-Based Speed Benchmarks: Leverage interactive in-browser calculations to measure CPU threads and display expected tokens/sec before running heavy weights.

Try it here: https://model-fit-gamma.vercel.app/

Code & more: https://www.dailybuild.xyz/project/154-modelfit

Building "Customer Escape Room": A Voice-Powered Game That Teaches Customer Experience by Making You Live Through Support Hell

Harish Kotra (he/him) — Thu, 04 Jun 2026 15:21:49 +0000

"Can you survive being a customer?"

At every hackathon, teams build the same thing: chatbots, AI agents, customer support copilots. All of them try to fix customer experience. None of them force you to feel what broken customer experience is actually like.

So I built the opposite. A game.

The Idea

Customer Escape Room is a mobile-first, voice-powered game where players must escape increasingly absurd customer service nightmares. Think Portal meets The Stanley Parable meets your worst call center experience.

Six levels. Six NPCs. Six unique mechanics. All connected by one question: can you survive being a customer?

The Tech Stack

Technology	Purpose
Next.js 16 (App Router)	Full-stack framework
TypeScript	Type safety
Tailwind CSS v4	Styling
Framer Motion	Animations
shadcn/ui	Component library
MediaRecorder API	Voice recording
OpenAI Whisper	Speech-to-text
React Context + useReducer	State management

Architecture

┌──────────────────────────────────────────┐
│               Page Layer                  │
│  /  (Game Hub)      /game/judge (Demo)   │
├──────────────────────────────────────────┤
│            Game Engine                    │
│  ┌────────────────────────────────────┐  │
│  │  Level 1  │  Level 2  │  Level 3  │  │
│  │  Level 4  │  Level 5  │  Level 6  │  │
│  └────────────────────────────────────┘  │
├──────────────────────────────────────────┤
│        Shared Components                 │
│  VoiceInput  NPCDialogue  ScoreDisplay   │
│  Achievements  ShareCard  LevelComplete  │
├──────────────────────────────────────────┤
│              State Layer                 │
│  GameProvider → useReducer → Context     │
├──────────────────────────────────────────┤
│               API Layer                  │
│  /api/ai  →  OpenAI / Featherless       │
│  /api/ai  →  Whisper Transcription      │
└──────────────────────────────────────────┘

The 6 Levels

Level 1: The Refund Maze

The player is trapped in a corporate maze. The Refund Robot NPC obsesses over "Policy 42(a)(3)(b)(ii)" — a fictional policy that keeps getting more nested the deeper you go. The player must ask for Form R-1, fill it out, then demand supervisor escalation to escape.

Mechanic: Bureaucratic layer navigation. Each stage requires specific keywords to advance.

Level 2: IVR Hell

A timed level. The player is stuck in an infinite phone menu system that loops back on itself. Press 1 for Billing. Press 2 for Billing Questions. Press 3 for Billing Questions About Billing. The only escape is saying "operator" or "representative" — the hidden human path.

Mechanic: Countdown timer + menu depth tracking. The hint system activates after 3+ failed attempts.

Level 3: Transfer Dungeon

The Transfer Goblin enthusiastically transfers the player to random departments, forgetting everything each time. The player must track their own story consistency — repeating yourself gets penalized. Escape by asking for "Escalations" after 5+ transfers.

Mechanic: Transfer counter + repetition detection (word-level matching against previous responses).

Level 4: Subscription Prison

Manager Dragon uses every retention tactic in the book. "Are you sure?" asked 4 times. Discount offers. Guilt trips. The player must stay firm through multiple "sure?" checkpoints without accepting any offers.

Mechanic: Persuasion gauntlet. Saying "no" or accepting offers resets progress. Only firm persistence wins.

Level 5: Chatbot Labyrinth

The Chatbot Wizard answers every question wrong with extreme confidence. The player must discover 3 hidden keywords ("human", "agent", "representative") to prove they're not a bot. Every regular input is met with creatively unhelpful responses.

Mechanic: Keyword collection. Misunderstanding counter unlocks progressive hints.

Level 6: Karen Boss Fight

The final boss. Karen Queen interrupts, contradicts herself, escalates unreasonably, and demands everything for free. The player must use empathy words ("understand", "sorry", "help") to de-escalate without triggering more rage.

Mechanic: De-escalation score. Empathy words reduce anger; demanding or fighting back triggers interruptions.

Level Design Pattern

Every level follows the same architecture:

type Stage = "intro" | "stage1" | "stage2" | "escaped"

// Stage data with deterministic responses
const STAGE_DATA: Record<Stage, StageConfig> = {
  intro: {
    npc: "...NPC dialogue...",
    advanceOn: ["keyword1", "keyword2"],
    advanceTo: "stage1",
    hint: "Hint for confused players"
  },
  // ...
}

function handleTranscript(text: string) {
  // 1. Detect confused input ("i don't know", "help")
  if (isConfused(text)) return showHint()

  // 2. Check for advancement keywords
  if (matchesKeyword(text, currentStage.advanceOn)) {
    return advanceStage(currentStage.advanceTo)
  }

  // 3. Redirect to objective
  return showRedirectMessage()
}

This pattern ensures:

No random responses — every NPC line is stage-appropriate
Confused players get help — "i don't know" always shows a hint
Clear progression — keywords gate advancement
Graceful failure — off-script input redirects to the objective

Voice System

The voice system uses the native MediaRecorder API:

// src/lib/voice.ts
export function useVoice() {
  const startRecording = async () => {
    const stream = await navigator.mediaDevices.getUserMedia({ audio: true })
    const mediaRecorder = new MediaRecorder(stream)
    // ... record audio chunks
  }

  const stopRecording = async () => {
    // ... create blob, send to /api/ai with X-Transcribe
    const text = await transcribeAudio(blob)
    return text
  }
}

The VoiceInput component wraps this with a toggle:

<VoiceInput onTranscript={handleTranscript} />
// Shows mic button + "⌨️ Type instead" toggle

Falls back gracefully:

No microphone → shows text input only
No API key → simulates transcription with context-aware phrases
Error → shows text input as fallback

AI Abstraction Layer

The API route handles both dialogue generation and transcription through a unified endpoint:

// /api/ai handles:
// 1. Chat completions (dialogue)
// 2. Audio transcriptions (Whisper)

const provider = process.env.AI_PROVIDER || "openai"
const baseUrl = provider === "featherless"
  ? "https://api.featherless.ai/v1"
  : "https://api.openai.com/v1"

Provider switching via env vars:

AI_PROVIDER=openai           # Uses gpt-4o-mini
AI_PROVIDER=featherless      # Uses Llama 3.1 8B

State Management

Game state uses React Context with useReducer:

type Action =
  | { type: "SET_PHASE"; phase: GamePhase }
  | { type: "SET_LEVEL"; levelId: LevelId }
  | { type: "ADD_SCORE"; levelId: LevelId; category: ScoreCategory; amount: number }
  | { type: "ADD_ACHIEVEMENT"; achievementId: string }
  | { type: "RESET_GAME" }

// Scores are calculated cumulatively
// Achievements are checked and dispatched by level logic
// Game phase controls which screen renders

Scoring & Ranks

6 Categories × 6 Levels × 100 points = 3,600 max

Categories:
  patience       - Staying calm under absurdity
  problemSolving - Finding the escape path
  persistence    - Not giving up
  empathy        - Showing understanding (critical for Level 6)
  escapeSpeed    - Completing efficiently
  negotiation    - Arguing effectively

Ranks:
  🥉 Casual Complainer    (0+ pts)
  🥈 Support Veteran      (300+ pts)
  🥇 Customer Champion    (600+ pts)
  👑 Escape Legend        (900+ pts)

Judge Demo Mode

One of the most important features: /game/judge drops judges directly into Level 2 (IVR Hell) with zero friction.

// /game/judge/page.tsx
<GameEngine initialLevel={2} />

No signup. No onboarding. Ten seconds from scanning a QR code to playing.

What I'd Add Next

Multiplayer — Socket.io is installed. 4-8 players in a shared escape room with voice cooperation.
Dynamic AI scenarios — Use the AI provider to generate unique company names and NPC dialogue per playthrough.
Supabase persistence — Leaderboards, saved scores, daily challenges.
Sound design — Hold music, menu beeps, NPC voice lines.
More levels — "The Data Deletion Request," "The Warranty Voidening," "The Return Policy Paradox."
Share cards — Generate shareable SVG images with scores and rank.

Try It

npm install
npm run dev
# → http://localhost:3000
# → http://localhost:3000/game/judge (judge demo)

Screenshots

Code & more: https://www.dailybuild.xyz/project/153-escape-velocity

Guarding the Gate - Building a Local-First Core Notification Manager in Android

Harish Kotra (he/him) — Wed, 03 Jun 2026 17:52:37 +0000

In an era of relentless attention hacks, notifications have transformed from micro-reminders into psychological trigger points. The solution seems simple: customize alert profiles. However, standard Android rule builders are either built-in rigidly or ship user data straight to remote clusters.

Enter Gatekeeper—a local-first, privacy-by-design Open Source Software (OSS) utility built entirely with Kotlin, Jetpack Compose, Room Database, WorkManager, and Android's specialized NotificationListenerService.

In this architectural deep dive, we will decompose the stack, patterns, and codebases that power Gatekeeper on Android.

The Guardrail Paradigm: 100% On-Device

If code is not in your repo, it shouldn't have access to your thoughts. Gatekeeper does not require or declare standard internet usage parameters:

<!-- ❌ ABSENT from androidmanifest.xml: android.permission.INTERNET -->

By refusing outbound network permission, every data structure, log packet, and rule configuration remains encapsulated within the app's local sandbox directories.

System Architecture Flow

Here is how the lifecycle flows when an alert lands from any device app:

[System Notification Event (e.g., WhatsApp, Slack)]
                       |
                       v
     [NotificationListenerService Hook]
                       |
                       v
         (Saves preview clip to cache) 
                       |
                       v
    [Query Rule Table inside local Room DB]
                       |
             +---------+---------+
             |                   |
       No Match Found       Rule Match Found!
             |                   |
             v                   v
      [Deliver Alert]     Execute Action Criteria
                      +----------+----------+
                      |                     |
                  [Action MUTE]       [Action SNOOZE]
                      |                     |
                      v                     v
              Cancel Alert        Cancel Alert
                                            |
                                            v
                                   Schedule WorkManager 
                                    (15 mins later)
                                            |
                                            v
                                 Post Local System Alert 
                                  to Notification Tray

Let's dissect the core pillars step-by-step.

1. Interception Engine: `NotificationListenerService`

Android restricts global notification tracking for security reasons. To read or cancel third-party events, we tap into NotificationListenerService.

When registered and granted special system authorization, the OS holds a persistent binder to this service, waking it whenever a system level notification event is posted.

Implementing the Daemon Hook

In GatekeeperEngineService.kt, we listen to incoming alerts:

package com.example.service

import android.app.Notification
import android.service.notification.NotificationListenerService
import android.service.notification.StatusBarNotification
import com.example.data.ActionType
import com.example.data.DatabaseProvider
import kotlinx.coroutines.CoroutineScope
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.SupervisorJob
import kotlinx.coroutines.launch

class GatekeeperEngineService : NotificationListenerService() {

    private val job = SupervisorJob()
    private val scope = CoroutineScope(Dispatchers.IO + job) // Run DB searches away from Main UI Thread

    override fun onNotificationPosted(sbn: StatusBarNotification) {
        val packageName = sbn.packageName
        val notification = sbn.notification
        val title = notification.extras.getCharSequence(Notification.EXTRA_TITLE)?.toString() ?: ""
        val text = notification.extras.getCharSequence(Notification.EXTRA_TEXT)?.toString() ?: ""
        val bigText = notification.extras.getCharSequence(Notification.EXTRA_BIG_TEXT)?.toString() ?: ""

        val content = "$title $text $bigText".lowercase()

        scope.launch {
            val db = DatabaseProvider.getDatabase(applicationContext)
            val activeRules = db.ruleDao().getActiveRulesForPackageSync(packageName)

            for (rule in activeRules) {
                // If keyword is left blank, match everything inside this app.
                val match = if (rule.keyword.isBlank()) {
                    true
                } else {
                    content.contains(rule.keyword.lowercase())
                }

                if (match) {
                    if (rule.actionType == ActionType.MUTE) {
                        cancelNotification(sbn.key) // Instantly suppresses the notification
                    } else if (rule.actionType == ActionType.SNOOZE) {
                        cancelNotification(sbn.key) // Suppresses immediately
                        scheduleSnooze(title, text, packageName) // Shifts delivery window
                    }
                    break
                }
            }
        }
    }
}

2. Temporal Delay: Handled by `WorkManager` & `SnoozeWorker`

When a "Snooze" action is selected, we dismiss the live system notification and hand over delivery responsibility to Jetpack WorkManager as a background worker.

private fun scheduleSnooze(title: String, text: String, packageName: String) {
    val data = Data.Builder()
        .putString("title", title)
        .putString("text", text)
        .putString("packageName", packageName)
        .build()

    val workRequest = OneTimeWorkRequestBuilder<SnoozeWorker>()
        .setInitialDelay(15, TimeUnit.MINUTES) // Hardcoded 15-minute wait window
        .setInputData(data)
        .build()

    WorkManager.getInstance(applicationContext).enqueue(workRequest)
}

Redelivery with `SnoozeWorker`

When 15 minutes have elapsed, SnoozeWorker builds a fresh local channel and notifies the tray:

class SnoozeWorker(
    private val context: Context,
    workerParams: WorkerParameters
) : Worker(context, workerParams) {

    override fun doWork(): Result {
        val title = inputData.getString("title") ?: "Snoozed Notification"
        val text = inputData.getString("text") ?: ""
        val packageName = inputData.getString("packageName") ?: ""

        sendNotification(title, text, packageName)
        return Result.success()
    }

    private fun sendNotification(title: String, text: String, packageName: String) {
        val notificationManager = context.getSystemService(Context.NOTIFICATION_SERVICE) as NotificationManager
        val channelId = "snoozed_notifications"

        // Android O+ Notification Channel Creation
        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
            val channel = NotificationChannel(
                channelId, "Snoozed Notifications", NotificationManager.IMPORTANCE_DEFAULT
            )
            notificationManager.createNotificationChannel(channel)
        }

        val appName = try {
            val pm = context.packageManager
            val ai = pm.getApplicationInfo(packageName, 0)
            pm.getApplicationLabel(ai).toString()
        } catch (e: Exception) { packageName }

        val notification = NotificationCompat.Builder(context, channelId)
            .setSmallIcon(android.R.drawable.ic_dialog_info)
            .setContentTitle("[$appName] $title")
            .setContentText(text)
            .build()

        notificationManager.notify(Random.nextInt(), notification)
    }
}

3. UI State Pipeline & Interaction with Compose

We leverage Room to stream the list of active user rules to our Compose layer cleanly. A reactive flow streams rule entities updates:

@Dao
interface RuleDao {
    @Query("SELECT * FROM rules ORDER BY id DESC")
    fun getAllRules(): Flow<List<Rule>>
}

The GatekeeperViewModel then converts this Flow<List<Rule>> into a Compose state-compatible lifecycle-aware lifecycle state utilizing stateIn on the Kotlin viewModelScope:

val rules = repository.allRules.stateIn(
    scope = viewModelScope,
    started = SharingStarted.WhileSubscribed(5000),
    initialValue = emptyList()
)

Within our UI composables, we capture this via:

val rules by viewModel.rules.collectAsStateWithLifecycle()

Aesthetic Evolution: Minimalist Utility Design

Gatekeeper features a gorgeous "Clean Utility / Minimal" layout, styled with high contrast slate buttons, responsive state indicators, and subtle warning accents:

Adaptive Bottom Sheets: Double-clicking or simple tapping on any rule switches state flags, pre-populating fields instantly for deep refinement edits.
Notification Sneak Heuristics: Recent notification text previews from system apps are tracked on-device in a temporary cache (NotificationCache), assisting users in formulating precise regex or literal rules without leaving the workflow page!

Gatekeeper offers a scalable blueprint for building local-first Android utility daemons. The architecture stays light, reliable, and strictly inside the user's pocket.

Code and more: https://www.dailybuild.xyz/project/152-gatekeeper

Engineering Call of Customer: Building an AI-Powered Voice CX Battle Arena

Harish Kotra (he/him) — Mon, 01 Jun 2026 17:17:43 +0000

A deep-dive technical blueprint explaining real-time voice processing, procedural Web Audio creation, D3.js dark-mode visualization, and Gemini-driven structured scoring.

The Core Engineering Challenge

In customer experience (CX) training, static multiple-choice questionnaires fail to replicate the raw psychological tension of resolving a live customer dispute. We built Call of Customer to solve this exact problem: a full-stack, voice-dictated, peer-challenged training environment where users are put under a countdown timer to de-escalate aggressive, multi-tier-rage customer complaints.

This article reviews the architectural components, code implementations, and key engineering compromises chosen to bring this multiplayer gaming experience to life.

Architectural Overview

                               ┌────────────────────────────────┐
                               │     Web Speech Recognition     │
                               │   (Continuous Audio Stream)    │
                               └───────────────┬────────────────┘
                                               │
                                               ▼ Output: String Text
┌────────────────────────┐     ┌────────────────────────────────┐     ┌────────────────────────┐
│     Web Audio Synth    │ ◄───┤        React State Engine      ├────►│       D3 SVG Line      │
│ (Procedural Sound FX)  │     │   (Haptic & QA Calibration)    │     │  (Performance Chart)   │
└────────────────────────┘     └───────────────┬────────────────┘     └────────────────────────┘
                                               │
                                               ▼ Pipeline: Post Action
                               ┌────────────────────────────────┐
                               │     Express API (/api/rooms)   │
                               └───────────────┬────────────────┘
                                               │
                                               ▼ Payload: String Transcript
                               ┌────────────────────────────────┐
                               │   Server-Side Google GenAI     │
                               │   (JSON Structured Output)     │
                               └────────────────────────────────┘

The system operates across three core domains:

The Client Interface: Continuous client-side Speech Recognition (Web Speech API) and real-time canvas-rendered waveform indicators.
Interactive Hardware Feedback: Procedural sound synthesis (Web Audio API) coupled with local haptic parameters (navigator.vibrate) representing game status.
The Intelligent Grading Core: An ESM-compliant Node.js Express server that proxy-scores transcripts against contextual complaint records using client-hidden Gemini API credentials.

Deep Technical Drills & Code Snippets

Let's explore the four core systems enabling this performance training engine.

1. High-Fidelity Procedural Sound Synthesis (Web Audio API)

Using raw sound files slows client cold-starts and breaks theme customization. Call of Customer generates high-impact synth sounds dynamically using browser audio contexts:

// /src/utils/audio.ts
let audioCtx: AudioContext | null = null;

export function getAudioContext(): AudioContext {
  if (!audioCtx) {
    audioCtx = new (window.AudioContext || (window as any).webkitAudioContext)();
  }
  return audioCtx;
}

export function playSound(type: 'click' | 'success' | 'alert' | 'tick' | 'scoreReveal') {
  try {
    const isMuted = localStorage.getItem('call_of_customer_mute') === 'true';
    if (isMuted) return;

    const ctx = getAudioContext();
    const now = ctx.currentTime;

    if (type === 'click') {
      const osc = ctx.createOscillator();
      const gain = ctx.createGain();
      osc.type = 'triangle';
      osc.frequency.setValueAtTime(150, now);
      osc.frequency.exponentialRampToValueAtTime(80, now + 0.08);
      gain.gain.setValueAtTime(0.2, now);
      gain.gain.exponentialRampToValueAtTime(0.01, now + 0.08);
      osc.connect(gain);
      gain.connect(ctx.destination);
      osc.start(now);
      osc.stop(now + 0.08);
    } else if (type === 'success') {
      const osc1 = ctx.createOscillator();
      const osc2 = ctx.createOscillator();
      const gain = ctx.createGain();

      osc1.frequency.setValueAtTime(330, now);
      osc1.frequency.setValueAtTime(440, now + 0.08);
      osc1.frequency.setValueAtTime(660, now + 0.16);

      gain.gain.setValueAtTime(0.15, now);
      gain.gain.exponentialRampToValueAtTime(0.01, now + 0.4);

      osc1.connect(gain);
      gain.connect(ctx.destination);
      osc1.start(now);
      osc1.stop(now + 0.4);
    }
  } catch (err) {
    console.warn('Audio Context interaction blocked: ', err);
  }
}

This ensures we have a Zero-Dependency, latency-free retro game-show response for clicks, timer countdowns, and performance score unveils.

2. Client-Side Speech Recognition & Quality Assured Inputs

Speech recognition can feel fragile if accidental or low-quality clicks are processed. The frontend leverages continuous speech synthesis triggers alongside deep string length constraints:

// /src/components/RecordingView.tsx
const handleSubmit = (force = false) => {
  const cleanTranscript = transcript.trim();

  if (!force) {
    if (!cleanTranscript) {
      setValidationError("QA Alert: Response is empty! Write or record a customer resolution first.");
      return;
    }

    const words = cleanTranscript.split(/\s+/).filter(Boolean);
    if (words.length < 3) {
      setValidationError("QA Alert: Resolution too brief! Please address customer points with at least 3 words.");
      return;
    }

    if (cleanTranscript.length < 12) {
      setValidationError("QA Alert: Operator response lacks detail! Must be at least 12 characters long.");
      return;
    }
  }

  setValidationError(null);
  onSubmit(cleanTranscript || "Default resolution waiver proposed.", selectedPowerup);
};

3. Server-Side Difficulty Multiplier and LLM Structured Grading

Inside /server.ts, we implement evaluation parsing using the server-side Gemini API. The evaluated metrics (Empathy, Professionalism, Resolution, Clarity, Retention) are modified by difficulty multipliers. If the encounter is set to "Nightmare" mode, we multiply their final outputs by 1.5 to reward player bravery!

// /server.ts
const difficultyStr = (complaint.difficulty || 'medium').toLowerCase();
let diffMultiplier = 1.1;

if (difficultyStr === 'easy') diffMultiplier = 1.0;
else if (difficultyStr === 'medium') diffMultiplier = 1.1;
else if (difficultyStr === 'hard') diffMultiplier = 1.3;
else if (difficultyStr === 'nightmare') diffMultiplier = 1.5;

const originalScore = scoreResult.score;
const finalScore = Math.min(100, Math.floor(originalScore * diffMultiplier));

// Inject breakdown for rich UI visualization
scoreResult.originalScore = originalScore;
scoreResult.difficultyMultiplier = diffMultiplier;
scoreResult.difficultyApplied = difficultyStr;
scoreResult.score = finalScore;

On the frontend, this multiplier is displayed in an eye-catching Difficulty Bonus pill:

// /src/components/ResultsView.tsx
{evaluation.difficultyMultiplier !== undefined && (
  <div className="mb-4 bg-amber-500/10 border border-amber-500/20 rounded-xl p-3 flex items-center justify-between">
    <div className="flex gap-2">
      <Sparkles className="w-4 h-4 text-amber-400" />
      <div className="text-left font-mono">
        <span className="text-[10px] uppercase">Difficulty Bonus Active</span>
        <span className="text-[8px] text-slate-400">Multiplier: x{evaluation.difficultyMultiplier}</span>
      </div>
    </div>
    <span className="bg-amber-500 text-slate-950 px-2 rounded font-black text-xs">
      +{Math.round((evaluation.originalScore || 100) * (evaluation.difficultyMultiplier - 1.0))} PTS
    </span>
  </div>
)}

4. Vectorized Historical Calibration Charting (D3.js)

To visualize historical training progress across matches, we avoid messy static charting elements and use native, interactive D3.js SVG render loops:

// /src/components/AnalyticsChart.tsx
const xScale = d3.scaleLinear()
  .domain([0, data.length - 1])
  .range([paddingLeft, width - paddingRight]);

const yScale = d3.scaleLinear()
  .domain([0, 100])
  .range([height - paddingBottom, paddingTop]);

const empathyLineGenerator = d3.line<HistoryEntry>()
  .x((_, idx) => xScale(idx))
  .y(d => yScale(d.empathy ?? 50))
  .curve(d3.curveMonotoneX);

// We draw custom area overlays to render glowing neon gradient drops beneath paths
const empathyAreaGenerator = d3.area<HistoryEntry>()
  .x((_, idx) => xScale(idx))
  .y0(height - paddingBottom)
  .y1(d => yScale(d.empathy ?? 50))
  .curve(d3.curveMonotoneX);

We have unified low-latency browser APIs, custom styling parameters, and LLM reasoning arrays into a robust full-stack solution optimized for modern browser execution frames.

Try it here: https://call-of-customer-783263164775.us-west1.run.app

Code & more: https://www.dailybuild.xyz/project/150-call-of-customer

Building MapWiki: A Technical Deep Dive Into an Open Collaborative Mapping Platform

Harish Kotra (he/him) — Sun, 31 May 2026 11:48:19 +0000

MapWiki is a TypeScript MVP for collaborative geographic knowledge. The product idea is simple: combine the social editing model of Wikipedia, the spatial depth of OpenStreetMap, and the revision/audit habits of GitHub.

Most maps answer "where is it?" MapWiki is designed to help answer "what happened here?", "what exists here?", and "what relationships appear when multiple layers are viewed together?"

For example, a user can stack:

AI Research Labs
Universities
Venture Capital Firms
Semiconductor Fabs
Renewable Energy Projects

The result is not just a map. It is a geographic knowledge graph that can reveal clusters, dependencies, and missing context.

Product Scope

The MVP includes:

A map-first landing page.
Interactive MapLibre explorer.
Dataset creation wizard.
Point, line, and polygon objects.
Dataset pages with stats, contributors, comments, revisions, and exports.
CSV, TSV, GeoJSON, KML, and GPX import preview.
CSV, GeoJSON, JSON, KML, and GPX exports.
Ranked global search.
PostgreSQL/PostGIS persistence.
Append-only dataset and location revisions.
Moderation and audit tables.
Open contribution mode with abuse controls instead of mandatory login.
Vercel deployment configuration.

Architecture

There are two important boundaries:

The UI does not know whether data comes from seed data or Postgres.
Route handlers stay thin. They validate input, apply abuse controls, and call repositories/services.

That keeps the MVP easy to run locally while still giving production a real database path.

The Stack

Layer	Choice	Why
App framework	Next.js App Router	Server-rendered pages, API route handlers, Vercel deployment
Language	TypeScript	Shared domain types across UI, API, services, and tests
Styling	TailwindCSS + local ShadCN-style components	Fast, consistent, data-dense UI
Mapping	MapLibre GL JS	Open-source map rendering with layer control and clustering support
State	Zustand	Small persistent map-layer state
Server state	TanStack Query	Client-side caching for datasets, locations, and search
Database	PostgreSQL + PostGIS	Spatial indexing, full-text search, JSONB metadata, transactional history
Auth scaffold	NextAuth	Optional OAuth/email support if the open model changes
Tests	Vitest + Playwright	Fast unit/integration tests plus browser verification

Spatial Data Model

MapWiki revolves around two core entities:

Dataset: a community-maintained map layer.
Location: an object inside a dataset with geometry, metadata, sources, and revisions.

The database stores all geometry in PostGIS using SRID 4326:

CREATE TABLE locations (
  id uuid PRIMARY KEY DEFAULT uuid_generate_v4(),
  dataset_id uuid NOT NULL REFERENCES datasets(id) ON DELETE CASCADE,
  title text NOT NULL,
  description text NOT NULL DEFAULT '',
  geometry geometry(Geometry, 4326) NOT NULL,
  geometry_type text NOT NULL CHECK (
    geometry_type IN (
      'Point',
      'LineString',
      'Polygon',
      'MultiPoint',
      'MultiLineString',
      'MultiPolygon'
    )
  ),
  metadata jsonb NOT NULL DEFAULT '{}',
  created_by uuid NOT NULL REFERENCES users(id),
  updated_by uuid NOT NULL REFERENCES users(id),
  deleted_at timestamptz,
  search_vector tsvector GENERATED ALWAYS AS (
    setweight(to_tsvector('english', coalesce(title, '')), 'A') ||
    setweight(to_tsvector('english', coalesce(description, '')), 'B') ||
    setweight(to_tsvector('english', coalesce(metadata::text, '')), 'C')
  ) STORED,
  created_at timestamptz NOT NULL DEFAULT now(),
  updated_at timestamptz NOT NULL DEFAULT now()
);

CREATE INDEX locations_geometry_gix ON locations USING gist (geometry);
CREATE INDEX locations_search_idx ON locations USING gin (search_vector);

This gives the app the primitives it needs for:

Viewport queries.
Spatial filtering.
Full-text ranking.
JSON metadata filters.
Future vector tile generation.

Revisions: No Destructive Edits

Every edit should be recoverable. The current row represents the latest state, while revision rows store parent history, structured diffs, and snapshots.

CREATE TABLE location_revisions (
  id uuid PRIMARY KEY DEFAULT uuid_generate_v4(),
  location_id uuid NOT NULL REFERENCES locations(id) ON DELETE CASCADE,
  parent_revision_id uuid REFERENCES location_revisions(id),
  author_id uuid NOT NULL REFERENCES users(id),
  change_summary text NOT NULL,
  diff jsonb NOT NULL DEFAULT '{}',
  snapshot jsonb NOT NULL DEFAULT '{}',
  created_at timestamptz NOT NULL DEFAULT now()
);

Restoring a previous version should create another revision. It should not mutate history. This mirrors how Git preserves ancestry and how Wikipedia preserves edit history.

Layer System

The most important user experience is the ability to stack datasets. Users can enable, disable, recolor, and adjust opacity for each dataset layer.

The client layer state uses Zustand and persists into local storage:

export type LayerSettings = {
  datasetId: string;
  name: string;
  color: string;
  opacity: number;
  enabled: boolean;
  order: number;
};

The map explorer can then derive active datasets and request only the data needed for the current map state:

curl "https://your-domain.example/api/locations?datasetIds=DATASET_ID&bbox=-125,24,-66,50&format=geojson"

For the MVP, the app returns GeoJSON. At larger scale, the repository/API boundary can evolve to vector tiles without changing the higher-level dataset model.

Import Pipeline

Import is critical because community datasets often begin as spreadsheets or open-data files. MapWiki supports:

CSV
TSV
GeoJSON
KML
GPX

The import route validates and previews files before committing them.

const maxImportRows = 50_000;

function assertRowBudget(count: number) {
  if (count > maxImportRows) {
    throw new Error(`Import preview is limited to ${maxImportRows.toLocaleString()} records.`);
  }
}

CSV and TSV rows can use common latitude/longitude names:

const latitude = asNumber(record.latitude ?? record.lat ?? record.Latitude ?? record.LAT);
const longitude = asNumber(record.longitude ?? record.lng ?? record.lon ?? record.Longitude ?? record.LON);

Rows without coordinates can be marked for future geocoding instead of being silently dropped.

Export Pipeline

Exports are generated dynamically from the repository layer:

export function locationsToGeoJson(locations: Location[]): FeatureCollection {
  return toFeatureCollection(locations);
}

CSV output escapes values, and XML formats escape text before generating KML or GPX:

function escapeXml(value: unknown) {
  return String(value ?? "")
    .replace(/&/g, "&amp;")
    .replace(/</g, "&lt;")
    .replace(/>/g, "&gt;")
    .replace(/"/g, "&quot;")
    .replace(/'/g, "&apos;");
}

Open Contributions Without Mandatory Login

The project can run without forcing authentication. Public writes are attributed to an anonymous contributor row and protected by abuse controls.

That open model makes contribution easier, but it creates risk:

Spam comments.
Bot-created datasets.
Repeated duplicate submissions.
Large request bodies.
Script/HTML payloads.
API scraping and brute-force import attempts.

The solution is layered defense.

Abuse Controls

Input routes use:

Fixed-window rate limits stored in Postgres.
Burst and daily policies per route.
Request body byte limits before JSON parsing.
Zod schemas.
Honeypot fields.
Spam phrase detection.
URL-count limits.
Duplicate content fingerprints.
Script/HTML checks.
Invisible character checks.
Hashed IP bans.
Structured abuse event logs.

The client identity is hashed with a private salt:

export function getClientIdentity(request: Request): ClientIdentity {
  const url = new URL(request.url);
  const ip = getClientIp(request);
  const userAgent = request.headers.get("user-agent")?.slice(0, 300) ?? "unknown";
  const acceptLanguage = request.headers.get("accept-language")?.slice(0, 120) ?? "";
  const key = hash(`${ip}|${userAgent}|${acceptLanguage}`).slice(0, 48);

  return {
    key,
    ipHash: hash(ip).slice(0, 48),
    userAgentHash: hash(userAgent).slice(0, 48),
    route: url.pathname,
    method: request.method
  };
}

Active bans are checked before normal route work:

const activeBan = await getActiveIpBan(identity);
if (activeBan) {
  return {
    ok: false,
    identity,
    policy: "ip:ban",
    limit: 0,
    remaining: 0,
    resetAt: activeBan.bannedUntil,
    retryAfter: Math.max(1, Math.ceil((activeBan.bannedUntil - Date.now()) / 1000)),
    blocked: true,
    reason: activeBan.reason
  };
}

Suspicious submissions are logged and can trigger a temporary ban:

if (!ok || score >= 30) {
  await banClientIp(identity, {
    action: options.action,
    reason: reasons[0] ?? "Suspicious submission pattern.",
    durationMs: ok ? 60 * 60_000 : 24 * 60 * 60_000,
    score
  });
}

This protects the application and database. Large volumetric DDoS still belongs at the edge, using Vercel Firewall, bot protection, and provider-level defenses.

API Design

The MVP exposes REST-style route handlers:

Endpoint	Purpose
`GET /api/datasets`	List datasets
`POST /api/datasets`	Create a dataset
`GET /api/locations`	Query locations or GeoJSON
`POST /api/locations`	Create a map object
`GET /api/search`	Ranked global search
`GET /api/revisions`	View history
`POST /api/revisions`	Restore a revision
`GET /api/comments`	Read comments
`POST /api/comments`	Add comment
`POST /api/imports`	Preview imports
`GET /api/exports`	Download data
`GET /api/health`	Health check

An OpenAPI document is served from /api/openapi, and a static copy can be generated with:

npm run openapi

Deployment

The app is intended for Vercel:

Next.js App Router for server-rendered pages and API routes.
Neon Postgres with PostGIS for production data.
Vercel environment variables for database and security configuration.
Daily cron health check.

The Vercel config is intentionally small:

{
  "framework": "nextjs",
  "regions": ["iad1"],
  "crons": [
    {
      "path": "/api/health",
      "schedule": "0 0 * * *"
    }
  ]
}

Testing Strategy

The MVP includes:

Unit tests for parser/exporter/abuse behavior.
Integration tests for repositories.
Moderation workflow tests.
Playwright e2e coverage for browser behavior.
TypeScript, ESLint, and production build checks.

Recommended pre-merge checks:

npm run typecheck
npm run lint
npm run test
npm run build

Scaling Path

The MVP is designed so the next scaling steps do not require a full rewrite:

Add vector tiles with ST_AsMVT.
Add tile cache invalidation per dataset revision.
Add geometry simplification per zoom level.
Move import jobs into a queue.
Add dataset materialized views for high-traffic public layers.
Add edge caching for read APIs.
Add stronger Vercel Firewall rules and challenge flows.
Add per-dataset moderation policies.

What Developers Can Build Next

Good next features:

Visual geometry editor with snapping and undo/redo.
Revision compare UI with map-diff rendering.
Citation quality scoring.
Saved layer stacks with shareable URLs.
Geocoding adapters for address-only imports.
Moderation queue triage filters.
Vector tile API route.
Public profile activity feeds.
Dataset webhooks.
Embeddable maps.

MapWiki is not just a CRUD app with a map widget. The hard parts are the boundaries: spatial storage, collaborative revisions, import/export, public contributions, moderation, and abuse controls. The MVP builds those boundaries early so the project can grow from sample datasets into a large, community-maintained geographic knowledge base.

Code & more: https://www.dailybuild.xyz/project/149-mapwiki

Building ShouldWeAutomate: A Decision Intelligence Platform for Workflow Automation

Harish Kotra (he/him) — Sat, 30 May 2026 18:12:44 +0000

How we built an open-source platform that tells you whether your business process is ready for AI automation — with deterministic scoring, gamified UX, and optional LLM inference.

The Problem

Every week, someone asks: "Can we automate this workflow?" The answer is never simple. It depends on data quality, process stability, regulatory exposure, exception rates, integration readiness, decision complexity, and ROI potential — seven dimensions that interact in non-obvious ways.

Most automation decisions are made on gut feel. Teams spend months building automation only to discover the process changes too frequently, the data is too messy, or the compliance team blocks it.

We wanted to build a tool that makes this evaluation systematic, data-driven, and interactive — something a team can open in a browser, describe their workflow, and get a defensible answer in seconds.

The Architecture

Frontend

Single-page Flask application rendered server-side with Jinja2 templates. The frontend is vanilla JavaScript with Chart.js for the radar visualization and a custom SVG gauge for the overall score.

Key design decisions:

No build step. No webpack, no React, no npm. Pure HTML/CSS/JS. Zero friction for contributors.
Gamified sliders. Instead of 35 individual range inputs (5 questions × 7 dimensions), we show 7 aggregate dimension sliders with tier badges — Critical → Bronze → Silver → Gold → Mythic. Click "Fine-tune" to expand the 5 sub-questions.
Live preview. A mini gauge and recommendation badge update in real-time as sliders move. Users see their score change before they click "Analyze."

// Core rendering — dimension cards with aggregate + fine-tune
function createDimSection(key, dim, prefix) {
  const aggDefault = Math.round(
    dim.questions.reduce((s, q) => s + q.default, 0) / dim.questions.length
  );
  const tier = getTier(aggDefault);
  // ... builds the HTML with aggregate slider + expandable sub-sliders
}

// Live preview — recompute overall on every slider change
function updateLivePreview() {
  const weights = [0.20, 0.20, 0.15, 0.15, 0.10, 0.10, 0.10];
  dimKeys.forEach((key, i) => total += getAggregateValue(key) * weights[i]);
  // Update gauge SVG dashoffset, tier badge, recommendation text
}

Backend

Flask acts as both the web server and the decision engine. The architecture follows a modular design:

engine/
├── scorer.py          # Dimension scoring logic, defaults, recommendations
├── analyzer.py        # Orchestrator — ties all modules together
├── explainer.py       # Score breakdown with pull-up/pull-down analysis
├── what_if.py         # What-if simulation and sensitivity analysis
├── roi_calculator.py  # Quantitative ROI with NPV, payback, FTE impact
├── remediation.py     # Remediation playbooks per dimension
├── regulations.py     # Regulatory framework mapping (HIPAA, GDPR, SOX, etc.)
├── similarity.py      # Benchmark similarity search
├── sub_process.py     # Multi-process decomposition and aggregation
└── llm.py             # OpenAI-compatible LLM gateway

The Scoring Engine

The core scoring logic in scorer.py defines 7 dimensions, each with 5 weighted sub-questions:

SCORING_DEFAULTS = {
    "data_quality": {
        "label": "Data Quality",
        "weight": 0.20,
        "questions": [
            {"id": "data_completeness", "text": "How complete is your data?", ...},
            {"id": "data_consistency", "text": "How consistent is data format?", ...},
            # ... 5 questions per dimension
        ],
    },
    # ... 6 more dimensions
}

The overall score is a weighted average. The recommendation tier is determined by thresholds inspired by Capability Maturity Model (CMM) levels:

def get_recommendation(overall_score):
    if overall_score < 30:
        return {"level": "DO NOT AUTOMATE", ...}
    elif overall_score < 50:
        return {"level": "IMPROVE PROCESS FIRST", ...}
    elif overall_score < 70:
        return {"level": "HUMAN-IN-THE-LOOP AI", ...}
    elif overall_score < 85:
        return {"level": "AI ASSISTED AUTOMATION", ...}
    else:
        return {"level": "AGENT AUTOMATION READY", ...}

AI Integration

The LLM integration in engine/llm.py is optional and modular. It follows the OpenAI chat completions format, making it compatible with LM Studio, Ollama, OpenAI, Anthropic, or any other provider.

When enabled, the AI performs three tasks:

Score inference — given a workflow description, infer preliminary dimension scores
Contextual risk analysis — generate specific failure modes tied to the actual workflow context
Executive summary — produce a CTO-ready summary with key findings and recommendations

def infer_workflow(description, industry):
    user_prompt = f"Industry: {industry}\n\nWorkflow Description:\n{description}"
    result = _call_llm(SYSTEM_WORKFLOW_ANALYSIS, user_prompt)
    if result and "dimension_scores" in result:
        # Clamp scores to 0-100 and return
        scores = {k: max(0, min(100, int(v))) for k, v in result["dimension_scores"].items()}
        return result
    return None

The system prompt instructs the LLM to be skeptical and default to moderate scores unless the description strongly suggests otherwise — preventing over-optimistic AI outputs.

Benchmark Dataset

The data/benchmark_generator.py creates 600+ synthetic workflows across 10 industries with deliberately injected failure modes:

FAILURE_PROFILES = {
    "contradictory_rules": "Business rules are contradictory across departments",
    "broken_apis": "Legacy systems have no stable API endpoints",
    "regulatory_churn": "Regulations change quarterly, invalidating logic",
    "data_rot": "Historical data uses outdated schemas",
    "seasonal_spikes": "Volume varies 10x between peak and off-peak",
    "fraud_scenarios": "Fraud patterns evolve faster than detection rules",
    # ... more failure modes
}

Each workflow gets randomized dimension scores, a metadata profile, and injected failure modes. The result is a realistic benchmark for similarity matching — when a user analyzes their workflow, we find the 5 most similar synthetic workflows.

The Gamification Layer

The original UI had 35 range sliders visible at once. Users found it overwhelming. We redesigned it with three principles:

Progressive disclosure. Show 7 aggregate sliders. "Fine-tune" expands to the full 35.
Instant feedback. Every slider move updates the gauge, tier badge, and recommendation preview.
Tier badges. Each dimension gets a fun label: 🥉 Bronze, 🥈 Silver, 🥇 Gold, 🏆 Mythic.

function getTier(score) {
  if (score >= 85) return { text: "Mythic", icon: "🏆", cls: "tier-excellent" };
  if (score >= 70) return { text: "Gold",   icon: "🥇", cls: "tier-good" };
  if (score >= 50) return { text: "Silver", icon: "🥈", cls: "tier-moderate" };
  if (score >= 30) return { text: "Bronze", icon: "🥉", cls: "tier-poor" };
  return { text: "Critical", icon: "⛔", cls: "tier-critical" };
}

AI auto-fill is now the default path. Users describe their workflow in a textarea, click "Auto-fill Scores," and the AI pre-fills all 35 sub-scores. Users can then fine-tune before analyzing.

The Results Dashboard

After analysis, users get a comprehensive dashboard with seven tabs:

Tab	Content
Overview	Gauge, radar chart, risks, red flags, failure mode analysis, ROI, benchmark comparison, next steps
Explanation	Per-dimension breakdown with pull-up/pull-down factors and improvement tips
What-If	Sensitivity analysis + preset scenarios + custom sliders
Remediation	Phased action plans per dimension with effort estimates
Regulatory	Applicable regulations with governance penalties and audit requirements
AI Summary	Executive summary generated by LLM (when enabled)

What We Learned

Deterministic engines are underrated. The LLM is a nice-to-have, but the deterministic scoring engine handles 90% of use cases. It's fast (~1 second), predictable, and doesn't require users to set up external services.
Gamification reduces friction. Users engaged more with tier badges and live preview than with a static form. The instant feedback loop makes the evaluation feel like a game rather than a survey.
AI prefill is a trust cliff. When AI prefills scores, users trust it more if they can see and tweak every value. The fine-tune section is critical for building confidence.
Synthetic benchmarks are surprisingly useful. Even though they're generated, they provide a reference frame. Users want to know how their scores compare to "similar" workflows.

Getting Started

git clone https://github.com/harishkotra/ShouldWeAutomate.git
cd ShouldWeAutomate
pip install -r requirements.txt
python app.py

Code & more: https://www.dailybuild.xyz/project/148-should-we-automate

Building an Alien Language from Scratch with LangChain

Harish Kotra (he/him) — Fri, 29 May 2026 16:07:37 +0000

How 100 AI agents evolved a shared symbolic vocabulary through trade — with no pre-programmed definitions, no mock data, and no shortcuts.

The Core Idea

Most emergent communication demos cheat. They hardcode symbol meanings, or use mock LLM responses, or simulate the entire thing with random number generators. The result is a demo that looks impressive but teaches you nothing about how actual language models behave when they need to coordinate.

I wanted to build something real: two civilizations of AI agents, each with 50 unique personalities, negotiating trades using abstract symbols — where every single message and decision flows through a real LLM via LangChain SDK pipelines.

No mock data. No hardcoded symbol mappings. Just pure reinforcement: successful trades reinforce a symbol's meaning, failed trades weaken it. Over hundreds of rounds, a shared vocabulary emerges.

Why LangChain

LangChain.js (v1.4) is the backbone of this project. I deliberately used three different LangChain patterns to show how the SDK can handle different levels of agent complexity:

Pattern 1: The Message Chain

const chain = ChatPromptTemplate
  .fromMessages([["system", prompt], ["human", "{input}"]])
  .pipe(model)
  .pipe(parser);

Every symbol an agent sends is generated through this pipeline. The ChatPromptTemplate injects the agent's personality, observations, recent successes/failures, and conversation history. The model returns structured JSON ({"message": "🟢⚡🔺"}), which the JsonOutputParser validates.

The trickiest part was the {{ escaping — LangChain uses {} for template variables, but I needed literal {} in the JSON example. The double-brace escape ({{"message": "..."}}) resolves this cleanly.

Pattern 2: Trade Evaluation Chain

Same structure, different prompt — but this one returns a boolean decision. {"accept": true} or {"accept": false}. The agent evaluates whether the proposed resource exchange is beneficial based on its observations and personality.

Pattern 3: The ReAct Agent

This is where LangChain really shines. Using createAgent() from the LangGraph-based SDK, I built a full ReAct agent that can:

Inspect its civilization's current resource levels via a DynamicTool
Calculate the net impact of a proposed trade via another DynamicTool
Decide whether to accept based on that information

The agent literally thinks, uses tools, and then decides — all within LangChain's agent loop.

Handling Real-World LLM Quirks

The moment you switch from mock to real LLMs, everything gets interesting. Models wrap JSON in markdown code fences. They include chain-of-thought reasoning. They run out of tokens mid-response. They return empty content and put their thoughts in vendor-specific fields like reasoning_content.

I built a LenientJsonParser that extends LangChain's JsonOutputParser to handle all of these cases:

class LenientJsonParser extends JsonOutputParser {
  async parse(text: string): Promise<object> {
    try { return await super.parse(text); } catch {
      // Strip ```
{% endraw %}
json ...
{% raw %}
 ``` fences
      // Match balanced braces for nested objects
      // Fall back gracefully
    }
  }
}

This was essential. Without it, models like Gemma 4 (a reasoning model) would output all their thinking in reasoning_content and leave content empty, causing the parser to fail on every message.

The Multi-Provider Architecture

All three provider types — OpenAI, Featherless.ai, and LM Studio — use the same ChatOpenAI class from @langchain/openai. This means:

Zero code duplication between providers
LM Studio works through its OpenAI-compatible endpoint with just a baseURL config change
Switching providers is a dropdown selection in the UI — no code changes needed

The model factory in orchestrator.ts creates the right ChatOpenAI instance based on the config:

function createChatModel(config: SimulationConfig) {
  switch (config.provider) {
    case "openai":    return new ChatOpenAI({ model: "gpt-4o-mini", ... });
    case "featherless": return new ChatOpenAI({ model: "...", configuration: { baseURL: "..." } });
    case "lmstudio":  return new ChatOpenAI({ model: "...", configuration: { baseURL: ".../v1" } });
  }
}

Every provider swap is instant — no restart, no rebuild.

The UI: Premium Light Product

I went through two complete redesigns. The first was dark cyberpunk — glowing elements, neon accents, dramatic. It looked great in screenshots but was exhausting to work with.

The second is a premium light product aesthetic inspired by Civilization VI, Notion, and Stripe:

White cards, subtle shadows (box-shadow: 0 1px 2px rgba(0,0,0,0.04))
12–16px rounded corners
Inter font family
Segregated control panels with clear visual hierarchy

Dark/light mode uses CSS custom properties mapped through @theme, with localStorage persistence and prefers-color-scheme detection. No Tailwind dark: variants cluttering the component code.

What I Learned

Real LLMs are messy — JsonOutputParser fails the moment a model wraps output in markdown. Build lenient parsers from day one.
Reasoning models need special handling — Gemma 4, DeepSeek R1, and similar models put everything in reasoning_content and leave content empty. You need higher maxTokens and explicit "do not reason" instructions in the system prompt.
{{ escaping is essential — LangChain's ChatPromptTemplate uses {} for template variables. JSON examples need {{ and }} to produce literal braces in the output.
createAgent() is powerful but expensive — the ReAct loop makes multiple LLM calls per decision. For simple trade evaluation, Pattern 2 (a single chain call) is more efficient. Use Pattern 3 when you need tool-use and multi-step reasoning.
Template variable collision is real — LangChain's {} syntax conflicts with JSON's {}. The switch to {{ escaping was a "wait, that's it?" moment after hours of debugging.
CSS custom properties + Tailwind = clean themes — mapping all colors through @theme variables instead of using dark: variants keeps component code readable and theming centralized.

Run It Yourself

git clone https://github.com/harishkotra/alien-translator.git
cd alien-translator
npm install
npm run dev

Open the settings, configure an LLM provider, and click Start. Watch the language emerge.

Screenshots

Code and more: https://www.dailybuild.xyz/project/147-alient-translator

DEV Community: Harish Kotra (he/him)

Building Self-Healing LLM Agents with Agno and Streamlit

The Problem

The Solution: RetryAgentRun

Architecture Overview

Key Implementation Lessons

1. Use Any Type Annotations

2. Force the Agent to Make Mistakes

3. Timeout Safety

4. Parsing the Timeline

14 Real-World Scenarios

Results & Metrics

Running It Yourself

Same Prompt, Multiple Local Models — Round 2: Static Site Generator

The Experiment

Prompt

Models

Methodology

Results: The Baseline

Divergence #1: The index.md Collision Problem

Divergence #2: Configurable Output Directory

Divergence #3: HTML Escaping (Security)

Divergence #4: Architecture Style

Big Pickle — Coordinated Class Dependencies

DeepSeek V4 Flash — Block-Based Pipeline

Mimo 2.5 — Dataclass-Driven with Builder Pattern

Divergence #5: Line Count vs. Completeness

Failure Case: Nemotron Ultra

Patterns Across Both Experiments

1. Surface compliance is the easy part

2. Ambiguity drives divergence

3. Security details are fragile

4. Architecture ≠ correctness

5. Failures matter

Same Prompt, 4 LLMs: The Roguelike Showdown

The Prompt

Architecture Diagram

Model-by-Model Analysis

DeepSeek V4 Flash (524 lines)

MiniMax M3 (802 lines)

Mimo 2.5 (800 lines)

Nemotron 3 Ultra (0 lines)

Lessons for Engineers Using LLM-Generated Code

1. Surface Compliance ≠ Correctness

2. Cardinality Constraints Force Design Tradeoffs

3. Architecture Quality and Correctness Are Independent Axes

4. Bookkeeping Is the Weak Spot

5. Failed Runs Are Still Useful

A Practical Review Checklist

Running the Games

Outputs

Building PromptVault: An Encrypted AI Prompt Marketplace with Fully Homomorphic Encryption

The Problem

Why Fully Homomorphic Encryption?

The Architecture Decision: AES + FHE Hybrid

The Smart Contract

PromptVault.sol

Listing Flow

Purchase Flow

Revenue Model

Key View Functions

Error Handling

Test Coverage

The Frontend

Stack

Data Flow: Listing a Prompt

Data Flow: Purchasing a Prompt

SSR Safety and the CoFHE SDK

Version Debugging: The 0.4.0 → 0.5.2 Migration

WYSIWYG Markdown Editor

Security Model

What I'd Do Differently

The Code

Built With

Screenshots

Conclave: Confidential Multi-Agent Consensus on Ethereum Using Fully Homomorphic Encryption

The Problem

The Solution: FHE-Based Consensus

The Protocol

1. Create

The Solution: `RetryAgentRun`

1. Use `Any` Type Annotations

1. Interception Engine: `NotificationListenerService`

2. Temporal Delay: Handled by `WorkManager` & `SnoozeWorker`

Redelivery with `SnoozeWorker`