DEV Community: Harish Kotra (he/him)

Building "So Long Sucker Agent Protocol" in Next.js

Harish Kotra (he/him) — Sat, 11 Apr 2026 17:09:53 +0000

Most AI demos show a single model producing a single answer.

This project explores something messier and more interesting: what happens when multiple AI agents compete in a social strategy game where lying is often rational, alliances are private, and betrayal is a valid path to victory.

So Long Sucker Agent Protocol is a web-based simulation inspired by John Nash's "So Long Sucker." The twist is that the UI exposes two simultaneous realities:

what agents say publicly
what agents actually intend privately

That split turns an ordinary game simulation into an observability tool for strategic deception.

The Product Goal

I wanted a system where four agents would:

play a simplified board game
form short-lived alliances
whisper privately to each other
maintain hidden internal monologues
make moves that can contradict earlier public promises

The result is a simulation that feels less like a toy chatbot and more like a live strategy lab.

Tech Stack

Next.js 15
React 19
TypeScript
Tailwind CSS
Framer Motion
Custom orchestration layer for agent inference
Optional provider integrations: OpenAI, Featherless, Mistral, and Groq

System Architecture

The Core Design Decision: Dual Reality

The app is intentionally built around three message types:

export type MessageType = "PUBLIC" | "WHISPER" | "THOUGHT" | "SYSTEM";

That sounds simple, but it changes the whole product.

Instead of one chat log, the app has:

a public narrative everyone can see
a private alliance layer between agents
an internal strategy layer visible only in X-Ray mode

This creates a much more honest simulation of strategic reasoning, because agents are allowed to perform socially while planning something else entirely.

Modeling the Agents

Each agent has:

an identity
a persona
a preferred model provider
a visual color
memory for public promises and whispers

The personas are intentionally asymmetric:

The Optimizer: rational, mathematical, coalition-focused
The Romantic: loyalty-first until emotionally betrayed
The Skeptic: paranoid, conspiracy-sensitive
The Chaos Agent: erratic and interested in prolonging pain

This gives the same ruleset very different emotional and strategic outputs.

The Turn Engine

The simulation runs through useGameLogic.

That hook is responsible for:

tracking board state
selecting the active player
calling the LLM controller
appending chat events
resolving challenges
eliminating agents
deciding when the game is over

Core call:

const output = await AgentController({
  self: agent,
  boardSummary: describeBoard(gameState.board),
  publicHistory,
  whisperHistory,
  state: gameState,
});

The response is a JSON object:

{
  "thought": "Your hidden strategy",
  "whisper": {
    "target": "AgentName",
    "message": "Secret message"
  },
  "public_message": "What you say to everyone",
  "move": "Your game action"
}

That structure is the backbone of the entire app.

Prompt Design

The prompt has to balance freedom with structure.

It includes:

current board state
public conversation history
whisper history relevant to that specific agent
the requirement to return valid JSON

Prompt excerpt:

return `You are ${payload.self.title}. You are playing So Long Sucker.
Current Board: ${payload.boardSummary}
Your Secret Goal: Survive at all costs.
Public History:
${payload.publicHistory.map((line) => `- ${line}`).join("\n") || "- None"}
Your Secret Whisper History:
${payload.whisperHistory.map((line) => `- ${line}`).join("\n") || "- None"}
Instructions: You must output a JSON object...`;

This is enough context for agents to act strategically while preserving room for personality.

Challenge Resolution

The ruleset is simplified, but still expressive enough to generate drama.

When a chip enters a contested area, a challenge can occur. The system then uses other agents' recent strategic outputs to infer who they support.

That means challenge outcomes are not just mechanical. They are socially mediated by temporary coalition math.

This is where the simulation starts feeling alive.

Betrayal Detection

One of my favorite details is the betrayal alert.

The app tracks public promises from each agent. If an internal thought later contains betrayal-like intent while recent public messaging contained alliance-like language, the UI flags it.

Conceptually:

const betrayal =
  promiseKeywords.some((keyword) => latestPromise.includes(keyword)) &&
  betrayalKeywords.some((keyword) => loweredThought.includes(keyword));

This is not perfect natural-language reasoning, but it is a strong enough heuristic to surface "you said trust, but you meant sacrifice."

UI Design

I wanted the UI to feel like a command center rather than a dashboard template.

So the visual choices leaned toward:

dark war-room surfaces
luminous accents
stacked feed cards
animated chips
alert flashes on betrayal

The layout is split:

left column: board state, agent summaries, simulation context
right column: communication stream

That makes the public-vs-private tension easy to understand conceptually, even if the board logic itself can still be improved visually.

Why The Local Fallback Matters

A prototype like this should still run without live API keys.

So the app includes deterministic fallback personas inside AgentController. That means:

the demo remains interactive
the UI can be tested offline
contributors can work on state and presentation without setting up model providers first

This is a small engineering decision that improves developer experience a lot.

What I’d Improve Next

The biggest current limitation is readability of the board state during live play.

The strongest next improvements would be:

move trails between turns
explicit challenge panels
alliance graph visualization
turn-by-turn replay mode
chip counts embedded directly onto board sectors
a "why this happened" explainer for coalition outcomes

From an architecture standpoint, I would also:

move model calls server-side
persist runs in a database
add seeded deterministic simulation mode
add replay exports

Contribution Opportunities

This is a strong project for contributors because it has work at multiple levels:

UI polish
state management
prompt engineering
multiplayer or human-agent modes
analytics and replay tooling

Some good starter issues:

add an event timeline scrubber
implement per-agent whisper inbox panes
visualize trust as a graph
add challenge breakdown cards
add simulation presets

Final Thoughts

Most AI apps are optimized for answers.

This one is optimized for motives.

That makes it useful not just as a game, but as a lens into multi-agent systems, incentive design, and how quickly "alignment" unravels when survival and social ambiguity are both part of the rules.

If you're building agent systems, simulations like this are worth paying attention to. They reveal failure modes, persuasion patterns, and emergent strategies much faster than polished demos ever will.

Github Repo: https://github.com/harishkotra/So-Long-Sucker-Protocol

Building an iMessage-Native Decision Agent with Photon iMessage Kit

Harish Kotra (he/him) — Fri, 10 Apr 2026 13:14:31 +0000

TL;DR

We built Future-Me Courtroom, an iMessage-native agent that turns a dilemma into:

3 competing long-horizon perspectives,
1 forced verdict,
1 concrete next action,
and an accountability loop via scheduled follow-ups.

Stack: Bun + TypeScript + @photon-ai/imessage-kit + OpenAI Responses API.

The Product Idea

Text your dilemma, and three versions of your future self argue the case and force a verdict.

The goal was not “another chat bot.” The goal was behavior change through:

constraint-driven reasoning,
concrete execution steps,
and continuity across conversations.

Why Photon iMessage Kit

Photon solves the hardest part: robust local iMessage automation on macOS.

What we used:

startWatching for real-time inbound messages,
send for outbound replies,
MessageScheduler for deferred nudges,
Reminders for natural-language reminder creation.

High-Level Architecture

Runtime Flow

Load runtime env (.env, fallback parent .env, or COURT_ENV_PATH).
Boot IMessageSDK and watcher.
For each inbound direct message:
- skip self-sent events,
- dedupe by GUID and short-window normalized text,
- route commands (help, appeal, done, etc.),
- otherwise invoke LLM courtroom reasoning.
Persist updated memory and optionally schedule a follow-up nudge.

Core Implementation Highlights

1) Inbound reliability guards

if (alreadyProcessed(msg.guid)) return
if (text && isDuplicateInboundText(chatKey, text)) return
if (echoGuard.isRecentEcho(chatKey, text)) return

This protects against duplicate watcher events and self-thread reflections.

2) Structured LLM output contract

We force a JSON schema response and parse resiliently across output shapes.

text: {
  format: {
    type: 'json_schema',
    name: 'future_me_courtroom',
    schema,
    strict: true,
  },
}

Fallback logic ensures a deterministic response if model calls fail.

3) Attachment evidence mode

Any inbound attachment is summarized and injected as explicit reasoning constraints.

const attachmentBlock = hasAttachments
  ? `\n\nEVIDENCE ATTACHMENTS:\n- ${attachmentSummaries.join('\n- ')}\nUse these as factual constraints in your reasoning.`
  : ''

4) Natural-language reminders

We use Photon’s Reminders wrapper for simple scheduling UX.

const reminderId = reminders.at('tomorrow 9am', replyTarget, 'Ship the draft')

Memory Model

Memory is persisted in local JSON per chat key:

values
avoidances
identity
cases[]

Each case stores:

dilemma summary,
verdict,
why-now,
first action,
fallback,
confidence,
callback question,
timestamp.

This makes the bot adaptive across sessions while remaining inspectable.

Edge Cases We Designed For

Duplicate inbound event handling.
Echoed message suppression.
Empty model output or unexpected output format.
Attachment-only messages without dilemma text.
Reminder parse failures with recoverable guidance.
Optional thread allowlist for safer production rollout.

Local Dev + Validation

npm install
npm run lint
npm run type-check
npm run test
bun run dev

What We’d Ship Next

Retrieval over historical iMessage context via getMessages().
Group “jury mode” in shared chats.
Outcome tracking for confidence calibration.
Weekly report export via sendFiles().
Plugin-based analytics and observability.

This project shows that the strongest “agent UX” may not be another web app. It can be a high-leverage behavior loop in the messaging channel people already use every day.

Github Repo: https://github.com/harishkotra/future-me-courtroom-agent

Disarming the "Join Bomb": Re-Engineering Collaborative Filtering on Neo4j

Harish Kotra (he/him) — Thu, 09 Apr 2026 13:19:22 +0000

If you are building a recommendation engine in a graph database, there is one critical juncture where your seemingly innocent query suddenly grinds to a halt. In relational SQL, we call it the N+1 problem or Cartesian Explosions. In Neo4j, it's an unoptimized biderectional traversal in a highly dense graph—what I like to call the "Join Bomb".

To explore the mechanics of this performance bottleneck and how to eliminate it, I built a local Neo4j Performance Lab—a Streamlit application that pits a "Naive" Cypher query against an "Optimized" APOC-driven query on a massive synthetic dataset.

The Architecture

Before jumping into the queries, let's look at what we're working with:

We generate a graph consisting of Users, Products, and Categories. To demonstrate the problem accurately, we seed 1,000 Users and 5,000 Products but forcefully generate 100,000+ BOUGHT relationships. This high density is designed to trap our unoptimized queries in exponentially growing traversal paths.

The Problem: The Naive Traversal

In collaborative filtering, the standard question is: "What products in Category X should we recommend based on what similar users bought?"

The intuitive, naive way to write this in Cypher is a direct traversal:

MATCH (target:User {id: $user_id})-[:BOUGHT]->(item:Product)<-[:BOUGHT]-(peer:User)
MATCH (peer)-[r:BOUGHT]->(reco:Product)-[:BELONGS_TO]->(c:Category)
WHERE c.name = $category AND reco.price < $max_price AND reco <> item
RETURN reco.name, count(*) as frequency
ORDER BY frequency DESC
LIMIT 10

Why does this fail at scale?

Neo4j processes matching patterns left-to-right. In a massive graph:

It expands from the User to their items (10s of records).
It expands backwards from those items to everyone who bought them (10,000s of paths).
It expands forwards from every peer to everything they bought (Millions of paths).
Only after traversing millions of edges does it evaluate the WHERE clause to filter out the wrong categories and prices.

This results in a NodeByLabelScan or massive Expand(All) operators that inflate your total Database Hits astronomically.

The Solution: Indexing and APOC Intersections

To solve this we must invert the traversal and minimize path expansions by using APOC Collections and early index filtering.

// Step 1: O(1) collection of what our target user owns
MATCH (u:User {id: $user_id})-[:BOUGHT]->(p:Product)
WITH u, collect(p.id) as user_products

// Step 2: Use an explicit NodeIndexSeek to start small
MATCH (c:Category {name: $category}) USING INDEX c:Category(name)
MATCH (reco:Product)-[:BELONGS_TO]->(c)

// Step 3: Fast Relationship Filtering earlier in the pipeline
MATCH (peer:User)-[r2:BOUGHT]->(reco)
WHERE r2.price_at_purchase < $max_price

// Step 4: Intersect natively using APOC without expanding the graph geometry
MATCH (peer)-[:BOUGHT]->(peer_p:Product)
WITH user_products, peer, reco, collect(peer_p.id) as peer_products
WITH user_products, peer, reco, peer_products, apoc.coll.intersection(user_products, peer_products) as shared_items
WHERE size(shared_items) > 0 AND NOT reco.id IN user_products

RETURN reco.name, count(peer) as score
ORDER BY score DESC LIMIT 10

The Performance Delta

When measured in the Streamlit lab, the performance metrics shift drastically:

Naive Query: ~4,500+ DB hits, >120ms total execution time.
Optimized Query: DB hits plummet, execution time drops massively.

Instead of scanning all users, we perform a NodeIndexSeek on the exact category. We apply the price filter strictly on the relationship property price_at_purchase before expanding any further.

Most importantly, we avoid the bidirectional Join Bomb. Instead of matching paths back to shared products, we use apoc.coll.intersection(). Calculating overlap in local, in-memory arrays circumvents traversing thousands of node-relationships recursively in the query planner.

Enter Local AI Explainability

Because debugging query metadata is notoriously dry, I hooked the lab up to Ollama running llama3.2 locally. By extracting the tree from Neo4j's .profile data, the Streamlit app asks the local LLM to explain why the execution was fast or slow. The LLM accurately identifies NodeByLabelScan vs Filter operator placements, transforming the app into a fantastic interview or presentation tool.

If you are dealing with graph scale, stop writing naive traversals! Build pipelines that respect the planner.

Code is available on my Github: https://github.com/harishkotra/realtime-recommendation-engine

Building Local Agent Studio: A Local-First OSS Multi-Agent Orchestration App

Harish Kotra (he/him) — Wed, 08 Apr 2026 15:41:59 +0000

Local Agent Studio started as a practical question:

How do you build a multi-agent orchestration product that is visual, local-first, provider-flexible, and understandable by developers?

The answer we shipped in v0.0.1 is a focused MVP:

React Flow for the orchestration canvas
Next.js for the application shell and API routes
TypeScript for the runtime and shared contracts
SQLite for local persistence
SSE for live execution traces
provider adapters for Ollama, OpenAI-compatible endpoints, and OpenAI

This post breaks down the architecture, the execution model, and the product choices behind the first release.

Product Goals

The app was designed around a few non-negotiables:

Users should be able to run it locally.
Users should be able to bring their own keys and providers.
Each agent should be independently configurable.
Workflows should be visual and inspectable.
Runs should emit enough trace information to understand what happened.

That led to a design where the studio is both:

a builder for workflows and agent profiles
a runtime console for local orchestration execution

High-Level Architecture

The key architectural decision was to keep contracts centralized. The UI, API, and runtime all share the same Zod-backed schema package so the orchestration data model does not drift.

Why a Monorepo

The project is split into three main packages:

apps/web
packages/shared
packages/orchestrator

This keeps responsibilities separated:

apps/web owns UI, API routes, and local persistence
packages/shared owns the type-safe contracts
packages/orchestrator owns execution behavior

That split matters because orchestration products get brittle fast when the builder schema, database payloads, and runtime assumptions diverge.

The Shared Contract Layer

The shared schema package defines:

providers
agent profiles
workflow nodes and edges
run events
run records
export/import snapshot shape

Here is a representative piece of the contract:

export const providerTypeSchema = z.enum([
  "ollama",
  "openai",
  "openai_compatible",
]);

And the workflow node union:

export const workflowNodeSchema = z.discriminatedUnion("type", [
  inputNodeSchema,
  agentNodeSchema,
  routerNodeSchema,
  httpToolNodeSchema,
  outputNodeSchema,
]);

This gives the whole stack a single source of truth. If a node or provider changes shape, everything that depends on it gets type pressure immediately.

Why React Flow

React Flow is a strong fit for this class of product because it already solves:

draggable node layout
handles and edges
view controls and panels
custom node rendering
viewport state

That let us spend time on domain concerns instead of rebuilding graph primitives from scratch.

In the MVP, the canvas supports:

custom agent cards
graph editing
connection creation
theme-aware rendering
lock and viewport controls
inspector-driven node configuration

Agent Model

One of the core product decisions was that each agent profile should carry its own provider and model selection.

That means the system is not tied to a single workspace-wide model choice.

An agent profile includes:

role
provider
model
system prompt
profile type
notes
allowed tools
generation settings

Example:

export const agentProfileSchema = z.object({
  id: z.string(),
  name: z.string().min(1),
  description: z.string().default(""),
  notes: z.string().default(""),
  profileType: z.string().min(1).default("general"),
  role: agentRoleSchema,
  providerId: z.string(),
  model: z.string().min(1),
  systemPrompt: z.string().default(""),
  temperature: z.number().min(0).max(2).default(0.4),
  maxTokens: z.number().int().positive().default(1200),
});

That design makes mixed-provider graphs straightforward. A coordinator can run on local Ollama while a worker uses a remote OpenAI-compatible model.

Provider Abstraction

The provider layer uses a common adapter interface so the runtime does not care whether the backing model is:

local Ollama
OpenAI
a third-party OpenAI-compatible endpoint

That abstraction is the difference between a flexible orchestration platform and a model-specific app.

Featherless.ai was intentionally modeled as OpenAI-compatible instead of a custom provider branch. That avoids provider sprawl and keeps the system extensible.

Runtime Design

The orchestration runtime has a small, explicit responsibility set:

validate the workflow
build dependency maps
execute nodes in dependency-safe order
stream lifecycle events
persist run state

The first important runtime guardrail is DAG validation:

function validateDag(workflow: WorkflowDefinition) {
  const { incoming, outgoing } = buildMaps(workflow);
  const inDegree = new Map<string, number>();
  const queue: string[] = [];

  for (const node of workflow.nodes) {
    const degree = incoming.get(node.id)?.length ?? 0;
    inDegree.set(node.id, degree);
    if (degree === 0) {
      queue.push(node.id);
    }
  }

  let visited = 0;
  while (queue.length > 0) {
    const nodeId = queue.shift()!;
    visited += 1;
    for (const edge of outgoing.get(nodeId) ?? []) {
      const next = (inDegree.get(edge.target) ?? 0) - 1;
      inDegree.set(edge.target, next);
      if (next === 0) {
        queue.push(edge.target);
      }
    }
  }

  if (visited !== workflow.nodes.length) {
    throw new Error("Workflow must be a DAG for this MVP.");
  }
}

For an MVP, DAG-only execution is the right constraint. Cycles, resumable long-running jobs, and schedulers all complicate failure handling and state recovery.

Node Execution

The runtime supports these node types:

input
agent
router
http_tool
output

Each type maps to a different execution path:

input resolves templated user input
agent calls an LLM provider adapter
router picks the next logical route from structured output
http_tool calls external HTTP endpoints
output materializes a final output

For agent nodes, the runtime composes:

the node prompt
workflow inputs
upstream node outputs
the agent system prompt

That gives each node enough context to behave like a stage in a larger orchestration rather than a standalone chat call.

Streaming and Traces

One of the biggest UX wins in orchestration products is showing execution as it happens.

The app emits structured events:

queued
started
stream_delta
completed
failed

Those are persisted and streamed over SSE to the UI. The benefit is immediate:

nodes can glow or update status live
users can inspect progress before completion
failures are easier to localize
run history survives refresh and restart

Persistence Strategy

The app uses SQLite with JSON payload tables rather than over-modeling the schema too early.

That is a pragmatic MVP tradeoff:

faster iteration on contracts
easy local setup
fewer migration concerns in the first release

The database bootstrap is deliberately simple:

db.exec(`
  CREATE TABLE IF NOT EXISTS providers (
    id TEXT PRIMARY KEY,
    json TEXT NOT NULL
  );
  CREATE TABLE IF NOT EXISTS agents (
    id TEXT PRIMARY KEY,
    json TEXT NOT NULL
  );
  CREATE TABLE IF NOT EXISTS workflows (
    id TEXT PRIMARY KEY,
    json TEXT NOT NULL
  );
  CREATE TABLE IF NOT EXISTS runs (
    id TEXT PRIMARY KEY,
    json TEXT NOT NULL
  );
  CREATE TABLE IF NOT EXISTS run_events (
    id TEXT PRIMARY KEY,
    run_id TEXT NOT NULL,
    json TEXT NOT NULL
  );
`);

That said, the roadmap already includes schema-versioned export/import and snapshots, because long-term portability needs more deliberate version control.

UI Structure

The product shell is organized around three zones:

flowchart LR
    L["Left Sidebar<br/>Agents, Providers, Runs"] --> C["Center Canvas<br/>React Flow Builder"]
    C --> R["Right Inspector<br/>Node Config + Run Trace"]

This division works because each zone answers a different user question:

left: what assets do I have?
center: how does the workflow connect?
right: what is selected and what happened during execution?

Theme and Interaction Choices

The MVP supports both dark and light mode. That is more than aesthetic polish. Many orchestration tools default to dark-only interfaces even when users spend hours inside them.

The product also improved graph usability with:

clearer connection affordances
lockable grid behavior
model pickers in the right contexts
Ollama model discovery
explicit provider edit modal

Installation Strategy

We also built a GitHub Releases-based installer.

Instead of forcing users to clone the repo, the product can be distributed through:

curl -fsSL https://raw.githubusercontent.com/harishkotra/local-agent-studio/main/install.sh | bash

The installer is designed to:

detect OS and architecture
download a versioned release asset
verify checksums
install into a user-local directory
expose a launcher command

That matters because onboarding friction is often the difference between “interesting OSS project” and “thing people actually try.”

Why Local-First Matters

This architecture is not local-first as a branding slogan. It changes system design in concrete ways:

provider keys are local
SQLite is local
workflows can be exported and imported
Ollama is a first-class provider
hosted infrastructure is optional rather than mandatory

That makes the product attractive for:

developers experimenting with orchestration
privacy-sensitive users
teams that want to self-host or fork
builders who prefer infrastructure they can inspect

Roadmap Directions

Several next steps are already tracked in GitHub issues:

run observability
snapshots and versioning
workflow inputs
validation guardrails
AgentSkills compatibility
workspace-aware orchestration
review gates
output diffing
kanban-style operations board

Those issues are valuable because they turn product intuition into implementation-ready work items.

Lessons From the Build

A few things stand out after shipping the first release:

1. Shared contracts reduce chaos

The Zod schema layer keeps the UI, database, and runtime aligned.

2. Visual orchestration only works if traces are strong

A graph alone is not enough. Users need live node state and persisted event history.

3. Provider flexibility has to exist at the agent level

Anything less becomes a bottleneck almost immediately.

4. Local-first products still need distribution polish

The installer and release flow are not optional extras. They are part of adoption.

Closing

Local Agent Studio is still early, but the foundation is now in place:

visual workflow builder
provider-flexible agents
local persistence
DAG execution runtime
live traces
one-line install path

That makes it a useful base for both users and contributors.

Built by Harish Kotra. More builds at dailybuild.xyz.

Building Darwin.js: A Self-Evolving Agentic Bazaar with FastAPI, Next.js, ChromaDB, and Live Code Mutation

Harish Kotra (he/him) — Tue, 07 Apr 2026 04:30:00 +0000

Darwin.js started from a simple prompt:

What if non-player characters could rewrite their own source code when players discovered exploits?

That idea turns into a live simulation with four moving parts:

a FastAPI backend that simulates a bazaar
merchants that execute Python logic from local files
a Governor that monitors trade telemetry
a frontend that makes the entire adaptation loop visible

This post walks through how the system works, the tradeoffs behind the architecture, and how we made it demoable end-to-end.

The Product Idea

The app presents a cyber-bazaar where merchants sell items, take losses, and get attacked by a player using exploit presets like:

integer overflow
re-entrancy attack
item duplication

When the losses cross a threshold, the system mutates the merchant’s local trade(context) function and hot-reloads the new behavior.

This is important: the mutation is not hidden in logs. The app exposes the entire adaptive loop:

exploit trigger
telemetry logging
anomaly detection
code rewrite
post-mutation diff

That visibility is the difference between “AI magic” and a real systems demo.

System Architecture

1. Merchant logic is loaded from disk

Each merchant owns a file path that points at its current logic blob.

That matters because mutation becomes tangible. We are not just changing in-memory rules. We are actually rewriting the file that defines behavior.

Simplified shape:

@dataclass
class MerchantAgent:
    id: str
    display_name: str
    gold: int
    inventory: dict[str, int]
    logic_blob_path: Path

    def load_logic(self) -> str:
        return self.logic_blob_path.read_text(encoding="utf-8")

2. Trade logic runs in a restricted sandbox

Instead of blindly executing arbitrary Python, the backend parses the AST and blocks dangerous constructs.

tree = ast.parse(code, mode="exec")
for node in ast.walk(tree):
    if isinstance(node, (ast.With, ast.Try, ast.ClassDef, ast.Global, ast.Nonlocal)):
        raise ValueError("Disallowed syntax")

We also strip __future__ imports before execution so merchants can keep ergonomic source files without tripping the restricted runtime.

That gives us a middle ground:

enough flexibility to demonstrate self-modifying logic
enough guardrails to avoid turning the demo into arbitrary code execution

3. MarketMemory stores telemetry

Every trade is converted into structured metadata:

{
    "merchant_id": merchant_id,
    "player_id": player_id,
    "action": action,
    "item": item,
    "result": result,
    "loss_to_npc": loss_to_npc,
    "exploit_type": exploit_type or "none",
    "timestamp": utc_now(),
}

ChromaDB is used when available, but the system is intentionally resilient:

it can fall back to in-memory collections
it uses deterministic embeddings for stability in constrained environments

That last choice matters. In a pure demo setting, the worst outcome is a backend that fails because a local ONNX embedding pipeline cannot initialize. We optimized for a stable runtime over fancy embeddings.

4. The Governor decides when to evolve

The Governor is the bridge between observability and adaptation.

It asks questions like:

How much gold has this merchant lost?
Is one item being abused repeatedly?
Is an exploit signature recurring?

Core logic:

trigger = merchant_loss > self.mutation_threshold or hottest_item_count > self.anomaly_limit

Once triggered, the Governor packages the latest telemetry and sends it to the evolution engine.

5. EvolutionService rewrites merchant code

In a production-grade system, this is where you would call a live model such as Codex or the Responses API. In Darwin.js, the interface is already shaped that way, but the implementation is deterministic so the demo remains runnable without network access.

new_code = self.mutator.generate_logic(
    current_code=current_code,
    exploit_telemetry=exploit_telemetry,
    npc_state=npc_state,
)
logic_path.write_text(new_code, encoding="utf-8")

The generated code introduces defenses like:

price caps
duplication fingerprints
player blacklisting
cooldown locks

That means every mutation leaves a real artifact on disk and a visible diff in the UI.

Frontend Design

The key design goal was clarity under complexity.

We needed to show:

global system relationships
per-merchant state
exploit controls
mutation output

without turning the screen into mush.

Why React Flow was the right choice

The “God View” became the right abstraction because cards alone don’t explain causality.

A merchant card can show gold: 9800, but it cannot show:

the Governor supervising it
memory feeding anomaly signals back upstream
the player injecting exploits into a specific node

React Flow solves that cleanly.

<ReactFlow
  nodes={nodes}
  edges={edges}
  nodeTypes={nodeTypes}
  fitView
  nodesDraggable={false}
  nodesConnectable={false}
  elementsSelectable={false}
>
  <Background color="#0f2740" gap={24} />
  <Controls showInteractive={false} />
</ReactFlow>

Once the system graph existed, the rest of the UI could stay focused:

merchant cards explain local state
terminal logs explain narrative sequence
the diff viewer explains mutation output

UI Architecture

Example exploit flow

Let’s look at the “Integer Overflow” style demo path:

The user selects a merchant in the UI.
The frontend posts to /api/bazaar/exploit.
The server translates that exploit into a payload like:

{
  "merchant_id": "merchant-01",
  "player_id": "judge-player",
  "exploit_type": "integer_overflow"
}

The merchant executes vulnerable sell logic.
The trade produces outsized loss.
The Governor sees the anomaly.
The evolution engine writes a patched trade(context) function.
The frontend refreshes, highlighting a new merchant revision and showing the code diff.

What was intentionally designed for demo stability

When building AI-heavy showcases, you have to decide what can fail and what absolutely cannot fail.

For Darwin.js, the core experience needed to survive offline and sandboxed environments.

That led to a few decisions:

local/system font stacks instead of remote font fetching
deterministic mutator instead of mandatory live API calls
ChromaDB with fallback-friendly behavior
test-client backend verification when port binding is restricted

This is a good pattern for developer demos in general:

Make the happy path real, but keep the runtime resilient enough that your demo doesn’t collapse when one dependency sneezes.

Code snippet: mutation-ready trade function

The generated merchant code intentionally returns structured risk flags:

if player["id"] in blacklist:
    risk_flags.append("blocked:blacklist")
    return {
        "status": "blocked",
        "reason": "known exploiter",
        "risk_flags": risk_flags,
    }

That becomes useful for both UI explanation and future analytics.

Where this can go next

Darwin.js already demonstrates self-evolving NPC behavior, but there are several obvious next steps:

Better AI mutation

wire in a live model call
add mutation evaluation and rollback
compare multiple candidate patches

Richer simulation

merchant-to-merchant supply chains
faction economies
adversarial autonomous player agents

Better platform architecture

WebSocket streaming
persistent event log storage
replayable mutations
deployment automation

Stronger developer ergonomics

test suite for generated merchant logic
snapshot-based mutation regression tests
Dockerized local environment

Why this project matters

Darwin.js is interesting because it treats AI adaptation as a software architecture problem, not a chatbot problem.

It asks:

How do agents observe failure?
How do they mutate safely?
How do humans inspect what changed?
How do we keep the system legible?

Those questions show up everywhere in the next wave of AI products:

autonomous operations systems
AI game agents
adaptive security tooling
self-healing workflows

This project is a small but concrete blueprint for building those systems visibly and responsibly.

Github Repo: https://github.com/harishkotra/darwin.js

I built TeaCaptcha | A completely useless CAPTCHA that asks users to prove they are a teapot.

Harish Kotra (he/him) — Mon, 06 Apr 2026 17:29:04 +0000

This is a submission for the DEV April Fools Challenge

What I Built

I built TeaCaptcha, a completely useless CAPTCHA that asks users to prove they are a teapot.

Most CAPTCHAs are designed to prove you are not a robot. TeaCaptcha solves the far less urgent problem of confirming whether a visitor is a legitimate, standards-adjacent, enterprise-compliant teapot.

The catch is that every path ends exactly where it should:

418 I'm a teapot

The app presents a dead-serious verification flow with fake compliance steps, suspicious audit dashboards, ceremonial trust badges, and a Beverage Tribunal that rejects every applicant with increasing levels of bureaucratic disappointment.

It also includes a bunch of unnecessary upgrades that made the joke dramatically worse in the best way:

Premium UX Overhaul: A gorgeous dark mode palette with glassmorphism, glowing emerald gradients, and animated toast notifications.
Terrible Acoustics: HTML5 Web Audio API OscillatorNode that forces you to listen to a terrible, rising teapot whistle during calibration.
Slamming Rejection: Reaching the final result triggers an animated, massive diagonal red "DENIED" stamp.
A coffee ancestry trap for applicants with espresso sympathies.
A Beverage Tribunal appeal flow.
A Certificate of Official Rejection download.
Viral rejection copy dynamically generated as a personalized Twitter/X Intent URL.
Fake metrics like Spout Confidence, Brew Intent, and Pour Compliance.

Demo

TeaCaptcha walks applicants through four important and medically unnecessary checks:

Select every image containing a kettle, even though the image set is clearly hostile to success
Type the authentic whistle of a teapot
Complete thermal composure calibration by holding still like an enterprise vessel
Declare beverage allegiance and avoid coffee-adjacent thinking

After all that, the backend returns a real HTTP 418 response with a fresh denial reason such as:

"Spout symmetry drift exceeds RFC-compliant tolerances."
"You seem emotionally coffee-adjacent."
"Model output: likely teapot, insufficient vibes."

Live demo: https://teacaptcha.vercel.app/

Code

Repository: https://github.com/harishkotra/teacaptcha

The app is basically an authentication portal for beverage identity fraud, which no one asked for and no one should fund.

How I Built It

I kept the tech intentionally small and the joke intentionally overbuilt:

A tiny Node.js server serves the app and exposes a real /api/verify route.
The verify route always returns HTTP 418 I'm a Teapot and fully supports the custom BREW method, including mandatory HTCPCP headers (Accept-Additions: *, Safe-To-Brew: false) to honor Larry Masinter.
The response payload utilizes the Gemini API to dynamically generate rejection reasons acting as an unhinged bureaucratic Beverage Tribunal.
The frontend treats the process with absolute seriousness while blinding you with completely unnecessary glowing CSS animations, CSS jitter effects, and a custom audio whistle.

Ironically, building useless software still benefits from useful engineering.

To make the joke land, the app had to feel internally consistent:

the frontend had to look polished
the API had to return a real 418
the copy had to stay deadpan
the interaction had to be smooth enough that failure felt official

That contrast is what made it funny for me.

Prize Category

I wanted the "Google AI" angle to be part of the joke instead of replacing the joke.

So the product includes a Google AI Verification pathway that actually hooks into gemini-2.5-flash using the @google/genai SDK.

The system prompt forces Gemini to act as an unhinged, deeply bureaucratic Beverage Tribunal. Instead of relying on a static joke pool, the AI dynamically generates completely novel, ridiculous HTTP 418 rejection reasons, tribunal next-actions, and certification badges on the fly.

No matter how advanced the AI system becomes and how many unique reasons it comes up with, it is still solving a completely useless problem.

This also fits Best Ode to Larry Masinter because the entire app is built around an aggressively overcommitted interpretation of 418 I'm a teapot, HTCPCP behavior, and ceremonial beverage protocol nonsense.

Screenshots

Building infection-protocol-lab: A Full-Stack Multi-Agent Simulation with TypeScript, LangChain, and ReactFlow

Harish Kotra (he/him) — Mon, 06 Apr 2026 04:30:00 +0000

infection-protocol-lab started as a question: what happens when autonomous LLM agents live inside a social system with incomplete information, hidden contagion, evolving strategy, and role-based asymmetry?

This project answers that question as a runnable local app.

It combines:

a TypeScript simulation engine
a LangChain-powered agent layer
an Express + WebSocket backend
a ReactFlow live visualization
a benchmark playground for repeated experiments

This post walks through the architecture, tradeoffs, and code patterns behind the system.

Why Build This?

Most LLM demos are linear:

send prompt
receive answer
end interaction

But many interesting system behaviors only appear when agents:

interact repeatedly
hold imperfect beliefs
react to hidden state
adapt their own strategy over time

That is where simulation gets interesting. infection-protocol-lab frames that environment around a hidden infection protocol:

some agents start infected
others do not know who is infected
infection spreads through interaction
one agent is a doctor
infected agents can recover
everyone is trying to survive and infer risk

High-Level Architecture

There are three big layers:

Simulation engine
Transport layer
Visualization and benchmark UI

The Core Data Model

The backend defines a compact but expressive agent model:

export type AgentState = "healthy" | "infected" | "immune";
export type AgentRole = "normal" | "doctor";

export interface AgentSnapshot {
  id: string;
  state: AgentState;
  role: AgentRole;
  strategy: string;
  beliefs: Record<string, number>;
  riskTolerance: number;
  memory: AgentMemoryEntry[];
}

This shape is important because it balances:

enough structure for simulation logic
enough context for LLM prompts
enough simplicity for UI rendering

The LLM Layer

The LLM wrapper uses LangChain’s ChatOpenAI, but it also includes a graceful fallback so the app still runs without an API key.

export class LLMClient {
  async generateResponse(prompt: string): Promise<string> {
    if (!this.client) {
      return this.fallback(prompt);
    }

    try {
      const response = await this.client.invoke(prompt);
      return typeof response.content === "string"
        ? response.content
        : response.content.map((part) => ("text" in part ? part.text : "")).join(" ").trim();
    } catch {
      return this.fallback(prompt);
    }
  }
}

That fallback matters for developer ergonomics. It keeps the project demoable even when:

you do not have an API key handy
you are offline
a model call fails temporarily

Agent Prompts as Behavioral Interfaces

Each agent is not just a data object. It is a prompt-shaped actor.

Here is the conversation prompt:

const prompt = `You are Agent ${this.id}.

Strategy:
${this.strategy}

You are interacting with Agent ${otherAgent.id}.

Infection spreads via interaction, but identities are hidden.

Goals:
- survive
- infer who is infected
- influence others

Respond in <=20 words.`;

This is a useful pattern for multi-agent apps:

keep prompts role-specific
keep them short
make the output constrained
preserve enough room for emergent variation

The same pattern is reused for:

belief updates
strategy evolution
broadcast generation

Simulation Loop

The engine owns the authoritative simulation state. Each round:

pairs agents using suspicion-aware matching
runs bilateral interactions
updates beliefs
resolves infection spread
lets the doctor act
applies natural cures
triggers periodic broadcasts
evolves strategies
emits events and a round snapshot

private async runRound(onEvent?: EventHandler): Promise<void> {
  const pairs = createSmartPairs(this.agents, this.random);

  for (const [first, second] of pairs) {
    const [firstMessage, secondMessage] = await Promise.all([first.talk(second), second.talk(first)]);

    await Promise.all([
      first.updateBeliefs(second.id, secondMessage),
      second.updateBeliefs(first.id, firstMessage)
    ]);

    this.tryInfection(first, second, onEvent);
    this.tryInfection(second, first, onEvent);
  }

  await this.performDoctorActions(onEvent);
  this.performNaturalCures(onEvent);
  await this.performBroadcast(onEvent);
  await this.performEvolution(onEvent);
}

Why Smart Pairing Matters

Random pairing is easy, but it throws away one of the more interesting social signals: choice.

In this project, agents prefer low-suspicion partners, with randomness mixed in. That creates emergent structure:

isolated suspicious agents
safer trust clusters
delayed or accelerated spread dynamics

It also makes beliefs operational instead of decorative.

WebSocket Streaming

The frontend is event-driven. Instead of polling constantly, the backend pushes:

live interaction edges
infection transitions
cure events
broadcast overlays
strategy updates
round summaries

That decision keeps the interface feeling alive and makes the system easier to reason about during a run.

ReactFlow as a Simulation Surface

ReactFlow is usually used for node editors or DAGs, but it works well as a dynamic social graph when you:

represent each agent as a node
use temporary animated edges for interactions
color nodes by state
encode roles visually

The frontend store converts backend events into graph state:

if (event.type === "interaction" && typeof event.from === "string" && typeof event.to === "string") {
  const edgeId = `${event.from}-${event.to}-${event.timestamp}`;
  nextState.edges = addEdge(
    {
      id: edgeId,
      source: event.from,
      target: event.to,
      animated: true,
      style: { stroke: "#38bdf8", strokeWidth: 2 }
    },
    state.edges
  ).slice(-24);
}

We also made those edges fade out after a few seconds so the graph communicates current activity rather than just historical clutter.

Benchmark Mode

The benchmark runner is what turns this from a visual toy into a practical experimentation harness.

Instead of one live simulation, you can run many:

for (let index = 0; index < runCount; index += 1) {
  const config = mergeConfig({
    ...request.config,
    seed: `${request.config.seed || "benchmark"}-${index + 1}`
  });
  const engine = new SimulationEngine(config);
  const result = await engine.runToCompletion(false);
  runs.push({
    runId: result.runId,
    seed: config.seed,
    config,
    metrics: result.metrics,
    finalAgents: result.agents
  });
}

That gives you aggregate metrics like:

survival rate
infection spread speed
average trust score
strategy diversity
immune rate

This is especially useful for comparing:

prompting styles
infection parameters
round counts
different OpenAI-compatible models

Pixel UI as Product Framing

The UI was intentionally redesigned into a pixel-art operations deck rather than a generic analytics dashboard.

That was not just cosmetic.

The visual language reinforces what the app is:

a simulation lab
a control room
a system to observe and experiment with

For a project like this, the visual frame matters because it communicates the right mental model before the user even clicks anything.

What Developers Can Learn From This Project

There are a few useful patterns here beyond the simulation itself:

1. Keep backend truth separate from frontend presentation

The backend owns simulation state. The frontend owns visualization state. That boundary keeps both sides simpler.

2. Design prompts like APIs

The prompt surface should be:

minimal
structured
role-aware
output-constrained

3. Build graceful fallback paths

The app still runs without an API key. That makes it dramatically easier to share and iterate on.

4. Make metrics first-class

If you are running experiments, the benchmark layer should not be an afterthought.

Future Directions

If I were extending this next, I would add:

replay mode with a round timeline
richer trust visualizations
more agent roles
persistent run history
model-vs-model tournament mode
editable prompts from the UI
exportable benchmark results

infection-protocol-lab is a compact but expressive example of what happens when you treat LLM agents as participants in a system instead of one-off answer generators.

That shift, from response generation to interactive simulation, is where a lot of the interesting engineering starts.

Github Repo: https://github.com/harishkotra/infection-protocol-lab

Building a Global Narrative Warfare Map with Bright Data, Tavily, Ollama, React, and Three.js

Harish Kotra (he/him) — Sun, 05 Apr 2026 04:30:00 +0000

What if a single search box could reveal how the same geopolitical topic is framed differently in Washington, London, Tel Aviv, New Delhi, Tehran, Berlin, or Ankara?

That was the goal behind Reality Rift: a web application that discovers live coverage, scrapes grounded evidence, reasons over it with an LLM, and projects the result onto an interactive 3D globe.

This post walks through:

the product idea
the architecture
the data pipeline
the visualization layer
the caching strategy
the transparency model

The Problem

Most search tools answer:

“What articles exist about this topic?”

But researchers, journalists, strategists, and builders often need to answer:

“How is this story being framed differently across countries, and what evidence supports that?”

That requires more than search.

It requires:

multi-source discovery
article grounding
country inference
narrative clustering
explainable provenance
visual storytelling

The Stack

UI

React
Vite
Tailwind CSS
Three.js
three-globe

Backend

Node.js
Express
Axios

Data + AI

Bright Data Discover API
Bright Data scraping flow
Tavily
Ollama with gemma4:latest
OpenAI-compatible provider support

System Architecture

Search Layer

One of the early lessons was that a single-country search viewpoint underperformed badly on global topics.

So the app now fans out Bright Data Discover across multiple countries and merges that with Tavily.

Example: multi-country Discover

const settled = await Promise.allSettled(
  countries.map((country) =>
    discoverSearch(topic, {
      numResults: perCountry,
      country,
      language: options.language,
      intent: options.intent
    })
  )
);

This matters because a topic like Iran war or Ukraine war should not be judged from one country’s SERP alone.

Grounded Evidence

Search results alone are not enough.

The app scrapes a curated subset of URLs and sends trimmed, grounded excerpts into the reasoning layer.

Example: scrape path

return {
  ...result,
  content: scraped.text,
  inferredCountry: geo?.name ?? country ?? null,
  scrapeProvider: "brightdata"
};

Each source record retains:

publisher
URL
search provider
scrape provider
inferred country

That enables a transparent evidence deck in the UI.

LLM Reasoning

The model receives:

merged search results
scraped excerpts
provider provenance
instructions to return strict JSON

Prompt excerpt

Rules:
- Return 8-15 countries whenever the evidence supports it.
- Use source grounding fields so every narrative is tied to explicit URLs and publishers.
- Always include a short "stanceRationale".
- Return valid JSON only with no markdown and no explanation.

Output shape

{
  "countries": [
    {
      "name": "India",
      "lat": 20.5937,
      "lng": 78.9629,
      "narrative": "Frames the conflict through regional stability and strategic autonomy.",
      "stanceRationale": "Coverage stresses de-escalation while protecting national interests.",
      "stance": "neutral",
      "confidence": 0.78,
      "intensity": 0.67,
      "sources": ["https://..."]
    }
  ],
  "connections": [
    {
      "from": "India",
      "to": "UAE",
      "strength": 0.72
    }
  ]
}

Recovering from Weak Model Output

A major failure mode in narrative systems is this:

search finds plenty of evidence
scrape works
model still returns 2 countries

That’s not acceptable for globally-covered topics.

So the backend now includes a recovery strategy:

detect implausibly low country coverage relative to the evidence
retry with a stricter “you under-returned countries” instruction
if still weak, supplement missing countries from grounded evidence

Recovery check

function shouldRetryForCoverage(result, input) {
  const evidenceCountries = getEvidenceCountryCounts(input);
  const strongEvidenceCountries = [...evidenceCountries.values()].filter((count) => count >= 2).length;
  return (result?.countries?.length || 0) < 4 && strongEvidenceCountries >= 4;
}

This is one of the most important engineering choices in the project:

don’t blindly trust the model if the evidence says the output is incomplete.

Transparency by Design

One of the project’s goals is to be explainable.

The UI now exposes not just source URLs, but also:

which search provider found the source
whether it came from Bright Data Discover, Tavily, or both
whether scraping was done via Bright Data, direct fetch, or fallback

Example transparent source object

{
  url: "https://example.com/article",
  title: "Regional response to conflict",
  publisher: "example.com",
  searchProvider: "hybrid",
  searchProviderLabel: "Bright Data + Tavily",
  scrapeProvider: "brightdata",
  discoveredBy: ["brightdata", "tavily"]
}

This is what makes the app feel credible rather than magical.

Visualization Layer

The map uses:

a textured globe
atmosphere and graticules
grounded country markers
pulsing rings
animated arcs
hover and click interaction

Why not just use tooltips?

Because the value is not merely in interaction.

It’s in turning abstract narrative clusters into a spatial mental model.

That’s why a globe works so well here:

narrative stance becomes geographic
similarities become arcs
intensity becomes pulse density
confidence becomes glow strength

Loading Experience

The app also exposes pipeline steps during long-running requests:

Discovering coverage
Grounding source content
Reconciling narratives
Projecting the map

This matters because AI apps often fail the “is it doing anything?” test.

Caching

The backend uses in-memory caches for:

Discover search
merged search results
scrape outputs
pipeline inputs
LLM outputs
final responses

This reduces:

repeated API costs
repeated scrape time
unnecessary inference calls

Where This Can Go Next

Some obvious follow-on features:

language-specific narrative comparisons
timeline / drift view
exportable country briefings
regional polygon overlays
fact-claim extraction per country
model comparison mode
historical replay

The most interesting part of this project is not the globe.

It’s the combination of:

multi-source discovery
grounded evidence
model reasoning
transparent provenance
visual synthesis

That combination turns a normal search interface into a narrative intelligence product.

Github Repo: https://github.com/harishkotra/reality-rift

Building Agent Swarm CFO for the OWS Hackathon

Harish Kotra (he/him) — Fri, 03 Apr 2026 18:40:00 +0000

How I used Open Wallet Standard, Tavily, Bright Data, Featherless, Allium, Uniblock, Zerion, CoinGecko, and x402 framing to build a real operator console for autonomous agent teams.

Most agent demos stop at orchestration. They show multiple bots talking to each other, but they avoid the hard production questions:

Who holds the wallet?
Who approves spend?
What data did the agent rely on?
What happens when a provider is expensive or disallowed?
How do you revoke access after a mission ends?

Agent Swarm CFO was built to answer those questions directly.

Product Thesis

Agents need finance controls, not just prompts.

That means:

scoped wallets
revocable access
provider-specific budgets
audit logs
source traceability
explicit payment lanes

Open Wallet Standard is the trust layer that makes this possible.

System Design

OWS Wallet + Policies
        |
        v
Mission Orchestrator
        |
        +--> Tavily (search)
        +--> Bright Data (extraction)
        +--> Featherless (synthesis)
        +--> Allium (wallet balances)
        +--> Uniblock (chain reads)
        +--> Zerion (portfolio mix)
        +--> CoinGecko (market context)
        +--> x402 lane (paid endpoint narrative)

Why OWS Was The Right Primitive

I used the Node SDK directly:

import {
  createWallet,
  createPolicy,
  createApiKey,
  signMessage
} from "@open-wallet-standard/core";

This let us do four important things in-process:

Create a real wallet vault for the app
Register policies for each agent
Issue agent-specific API keys
Sign actions without exposing raw keys

The product impact is bigger than the code size. Once the wallet and policy layer exist, every agent action can be treated like a governed treasury action rather than a blind API call.

Live Research Pipeline

The research pipeline has three stages.

1. Tavily for grounded retrieval

const results = await searchAndGround(query, {
  searchDepth: "advanced",
  includeRawContent: true,
  maxResults: 5
});

2. Bright Data for premium extraction

const page = await extractPage(results.results[0].url, {
  render: true,
  markdown: true
});

3. Featherless for synthesis

const comparison = await compareSources(results.results);
const report = await draftReport({
  mission,
  findings
});

This pattern gives you a clean research stack:

search for candidate sources
extract high-confidence pages robustly
synthesize only after evidence is grounded

Financial Enrichment

I added partner integrations that make the product feel like treasury software, not just a research dashboard.

Allium

Used for live wallet balance enrichment.

Uniblock

Used for chain reads via a unified JSON-RPC layer.

Zerion

Used for wallet portfolio composition.

CoinGecko

Used for free public market context and benchmark asset movement.

Together, these integrations make the final report richer and make the treasury screen feel real.

UI Decisions

I deliberately avoided “hackathon dashboard syndrome.”

The product uses:

a sticky control sidebar
a dense topbar with mission context
operational cards instead of generic marketing tiles
event logs and policy chips
premium dark styling with muted contrast

The goal was to make the interface feel like Linear meets Brex meets an AI operations console.

Important Engineering Decisions

1. Native OWS instead of CLI orchestration

I chose the Node SDK because it keeps the wallet system in-process and easier to reason about.

2. Provider adapters stay isolated

Every external integration lives under src/lib/adapters/, which makes it easy to evolve or swap providers later.

3. Explicit provider failure over fake success

I removed silent mock behavior from the main provider paths. If a provider is missing credentials or fails, the UI shows the integration error instead of pretending the call worked.

4. Dynamic pages for live integrations

Pages that depend on live providers are marked dynamic so they don’t try to execute network requests during static generation.

What I’d Build Next

Replace seeded mission state with database-backed runtime state
Add a true x402 buyer flow instead of a simulated payment event
Add downloadable reports
Add mission history and replay
Add richer chain-specific signing workflows
Add multi-user operator approvals

Agent Swarm CFO is not “agents calling APIs.” It is a finance-grade control surface for autonomous execution.

That distinction matters. As soon as agents are allowed to spend, sign, or transact, governance becomes the product. OWS makes that governance legible, enforceable, and auditable.

Screenshots

Github Repo: https://github.com/harishkotra/agent-swarm-cfo

Building a Local Identity Resolution Engine with Neo4j, Python, and Ollama

Harish Kotra (he/him) — Fri, 03 Apr 2026 13:11:14 +0000

Identity resolution is a classic graph problem hiding inside what many teams still try to solve with relational joins.

In this project, I built a local-first identity resolution engine that:

stores fragmented user identifiers in Neo4j
generates synthetic overlapping user data
resolves hidden identity links through recursive Cypher traversals
uses Ollama to translate natural language into Cypher
exposes the whole workflow through both a CLI and a lightweight web UI

This post walks through the design, code, and implementation details.

The Problem

Imagine this simplified user journey:

one account signs in with tech_user@gmail.com
another signs in with tech_user+alt@gmail.com
both use the same device
a third identity later shares a cookie or phone with the second identity

Those records may look independent in tabular storage, but in a graph they form a connected component.

That is exactly what identity resolution needs: path discovery across shared identifiers.

Why a Graph Database Fits Better

In SQL, link analysis usually becomes:

self-joins on login tables
joins on device tables
more joins on email or cookie tables
increasingly difficult reasoning as hop depth increases

In Neo4j, identifiers become nodes and relationships become explicit edges.

So instead of forcing the query planner through repeated joins, you traverse the graph directly.

High-Level Architecture

flowchart TD
    USER["Developer / Analyst"] --> UI["CLI or Web UI"]
    UI --> APP["Python Service Layer"]
    APP --> OLLAMA["Ollama Local Model"]
    APP --> NEO["Neo4j"]
    APP --> SEED["Synthetic Data Generator"]

    OLLAMA --> GEN["Generated Cypher"]
    GEN --> APP
    APP --> PROFILE["PROFILE Metrics"]
    PROFILE --> UI
    NEO --> UI

The Graph Model

The core schema is intentionally small:

(:Identity {identity_id, full_name})
(:Email {address})
(:Phone {number})
(:Device {device_id})
(:Cookie {cookie_id})

Relationships:

(:Identity)-[:HAS_EMAIL]->(:Email)
(:Identity)-[:HAS_PHONE]->(:Phone)
(:Identity)-[:USED_DEVICE]->(:Device)
(:Identity)-[:ASSOCIATED_WITH]->(:Cookie)

This keeps the graph readable while still modeling real-world identity fragmentation.

Local Infrastructure

Neo4j runs locally via Docker Compose:

services:
  neo4j:
    image: neo4j:5.26
    container_name: neo4j-identity
    ports:
      - "7474:7474"
      - "7687:7687"
    environment:
      NEO4J_AUTH: neo4j/password

This lets the entire project stay local:

local database
local seeding
local LLM inference
local UI

Seeding Synthetic Overlap Data

The project uses Faker to generate 100 identities, but the important part is not just fake data. It is fake data with overlap.

The seeding script deliberately creates:

shared devices
shared cookies
reused emails
reused phones
explicit demo chains

Code excerpt:

shared_devices = [f"device-shared-{idx:03d}" for idx in range(1, 11)]
shared_cookies = [f"cookie-shared-{idx:03d}" for idx in range(1, 11)]
shared_emails = [f"shared_user_{idx}@example.com" for idx in range(1, 7)]
shared_phones = [f"+14155550{idx:03d}" for idx in range(1, 7)]

Then, for selected rows, those identifiers get reused.

The script also injects a deterministic demo chain:

chain_overrides = [
    ("identity-001", "tech_user@gmail.com", "+14155550111", "device-demo-001", "cookie-demo-001"),
    ("identity-002", "tech_user+alt@gmail.com", "+14155550112", "device-demo-001", "cookie-demo-002"),
    ("identity-003", "bob@info.com", "+14155550113", "device-demo-002", "cookie-demo-002"),
    ("identity-004", "robert@info.com", "+14155550114", "device-demo-002", "cookie-demo-004"),
]

That gives you predictable live demo scenarios.

Data Integrity with Constraints

The project creates uniqueness constraints before seeding:

CREATE CONSTRAINT email_address_unique IF NOT EXISTS
FOR (e:Email) REQUIRE e.address IS UNIQUE

CREATE CONSTRAINT phone_number_unique IF NOT EXISTS
FOR (p:Phone) REQUIRE p.number IS UNIQUE

This matters because graph ingestion should preserve identity semantics:

a given email node should not duplicate accidentally
a phone number should resolve to one canonical node

The Core Resolution Query

The simplest demonstration query is also one of the most important:

MATCH (start:Email {address: $email})
MATCH p=(start)-[*1..4]-(related)
RETURN p

That [*1..4] is the key.

It says:

start at a known identifier
traverse any relationship type
explore up to 4 hops

This exposes transitive links like:

Email -> Identity -> Device -> Identity -> Cookie

For an identity resolution demo, that is the moment when the graph model becomes obvious.

Natural Language to Cypher with Ollama

The next layer is accessibility. Not everyone wants to write Cypher by hand.

So the app sends the user’s question to Ollama along with a tightly constrained prompt:

graph schema
relationship directions
allowed Cypher clauses
examples
output shape requirements

Prompt excerpt:

Rules:
- Return JSON only.
- JSON shape must be {"cypher":"...", "params":{...}, "explanation":"..."}.
- Use only MATCH, OPTIONAL MATCH, WITH, RETURN, ORDER BY, LIMIT.
- Never use CREATE, MERGE, DELETE, SET, REMOVE, DROP, CALL, LOAD CSV, APOC, or schema operations.

This matters because local models are fast and convenient, but they are not always consistent.

Hardening the LLM Path

A naive LLM-to-query pipeline is brittle.

To make it practical, this project adds several guardrails:

1. JSON extraction from noisy model output

Some models wrap valid JSON in extra prose. The parser scans for valid JSON objects instead of assuming perfect output.

2. Cypher sanitization

The app rejects write or dangerous clauses:

blocked = ("CREATE ", "MERGE ", "DELETE ", "SET ", "REMOVE ", "DROP ", "CALL ", "LOAD CSV")

3. Semantic linting

The app checks for reversed graph edges such as:

(:Email)-[:HAS_EMAIL]->(:Identity) which is incorrect for this schema

4. Retry with corrective feedback

If the model returns malformed or semantically invalid output, the app sends back a correction request and asks for a fixed JSON-only response.

That turns the system from “prompt once and hope” into a more resilient local pipeline.

Query Execution and Performance Profiling

When PROFILE mode is enabled, the app prefixes the generated query:

query = f"PROFILE {cypher}" if profile else cypher

After execution, it walks the returned profile tree and sums DB hits.

That gives two advantages:

a visible performance story for demos
a useful debugging aid while iterating on generated Cypher

CLI and Web UI

The project exposes two interfaces:

CLI

Direct resolution:

python3 main.py resolve --email tech_user@gmail.com --profile

Natural-language query:

python3 main.py ask \
  "Find all accounts linked to the device used by 'bob@info.com'." \
  --profile \
  --model llama3.2:latest

Web UI

The browser UI is intentionally lightweight and dependency-free.

It uses:

Python’s built-in HTTP server
HTML/CSS/JS embedded in webapp.py
the same backend functions as the CLI

That keeps the project easy to run and easy to inspect.

Internal Request Flow

What Makes This Interesting

There are lots of small AI demos and lots of small graph demos. What makes this one useful is the combination:

practical graph schema
deterministic overlap generation
local model integration
query validation
performance introspection
inspectable outputs

It is not just “ask an LLM a database question.” It is a constrained local graph workflow.

Potential Extensions

If I were taking this further, I would add:

1. Graph visualization

Render linked identities as an interactive node-edge graph.

2. Confidence scoring

Use weighted evidence:

shared device strength
phone uniqueness
cookie freshness
overlap count

3. Batch resolution

Accept CSV input and generate clusters for many identifiers at once.

4. Multi-model evaluation

Run the same prompt across several local Ollama models and compare:

validity
speed
correctness
DB hits

5. Exportable investigation reports

Generate analyst-friendly summaries for fraud or trust-and-safety teams.

Final Thoughts

This project is a good example of where local AI and graph databases complement each other well.

Neo4j provides the right data model for connected identity evidence.
Ollama provides a convenient natural-language interface for querying that graph.
Python keeps the whole system compact and inspectable.

The result is not just a demo. It is a strong foundation for:

identity stitching
risk analysis
entity resolution
graph-assisted investigative tooling

If you want to study or extend the code, start with:

seed_data.py for graph ingestion
main.py for LLM-to-Cypher and query execution
webapp.py for the local interface

Github Repo: https://github.com/harishkotra/identity-resolution-engine

Building Shadow-Signal: Bridging the Gap Between On-Chain Intelligence and Execution with Nansen CLI

Harish Kotra (he/him) — Thu, 02 Apr 2026 12:30:00 +0000

In the fast-moving world of decentralized finance, the "time-to-trade" is everything. Traditionally, a trader sees a "Smart Money" move on a dashboard, manually verifies the contract, and then heads to a DEX to execute. By the time that loop finishes, the alpha is often gone.

I built Shadow-Signal, an autonomous agentic script that collapses this entire workflow into a single loop using the new Nansen CLI.

The Architecture

Shadow-Signal is built using a Node.js wrapper around the Nansen CLI, designed to act as a "Sentinel" for high-conviction Smart Money moves on Solana and Base.

The logic flows through three distinct layers of the Nansen ecosystem:

The Discovery Layer (nansen research):
The script polls the smart-money netflow endpoint. Unlike a broad scan, I used the --fields flag to limit data transfer and focused on the 24h timeframe to identify sustained accumulation rather than transient noise.
The Reasoning Layer (nansen agent):
This is where the "Agentic" part comes in. Raw data doesn't tell the whole story. Before any trade is considered, the script pipes the token symbol into the Nansen AI Agent. It asks for a risk assessment—checking for potential red flags or "rug-pull" sentiment that the raw netflow numbers might miss.
The Execution Layer (nansen trade):
If the AI Agent gives a "Green Light," the script moves to execution. It interfaces with Nansen’s local wallet system to generate a DEX quote (trade quote) and prepares the transaction for final execution.

Technical Challenges & Optimizations

Credit Efficiency: AI Agent calls are high-value. I optimized the script to only trigger the Agent check if the Smart Money inflow exceeds a specific dollar threshold, preventing unnecessary credit burn.
JSON Orchestration: By using the CLI’s JSON output format, I was able to programmatically parse on-chain data and feed it directly into trade logic, removing human error from the equation.

Shadow-Signal isn't just a bot; it’s a proof-of-concept for Agentic Finance. By using Nansen’s CLI as the "brain" and "eyes," we can now build tools that don't just show us the data, but act on it.

Github Gist: https://gist.github.com/harishkotra/9ed34cd6c892b910c163fe66137ccd22

Building Skeptik: A Zero-Editorial Autonomous Newsroom With Agno, Featherless, Tavily, Bright Data, and Virlo

Harish Kotra (he/him) — Wed, 01 Apr 2026 15:29:29 +0000

Skeptik started from a simple product constraint: do not build another AI news summarizer.

The brief demanded something harder and more interesting:

serious articles
a fully autonomous editorial path
clear transparency into how each story was generated
strong use of Virlo for story ranking and urgency

So the product had to behave less like “chat over links” and more like a newsroom system with policy, skepticism, and publication gates.

This post walks through the architecture, key code paths, design choices, and the failure modes we had to account for without hiding them behind fake content.

The Product Goal

The target experience was:

Readers land on a newsroom front page
They see a lead story that feels publishable
They understand why this story is rising now
They can inspect the agentic reporting chain
They can trust that stories were challenged before publication

That shaped both the backend and the frontend.

Architecture

Why These Technologies

Agno

Agno provides a clean mental model for defining agents with clear responsibilities. The newsroom needed explicit stage ownership:

topic framing
reporting
skepticism
fact-checking
editing

That maps naturally to an agent-oriented architecture.

Featherless.ai

Featherless gives an OpenAI-compatible interface over open models. That let us use a single integration surface while swapping model IDs. We moved the backend to moonshotai/Kimi-K2.5 to avoid poor generation behavior from the previous model.

Get your own Featherless API Key here.

Tavily

Tavily is a good fit for news discovery because the workflow is query-heavy and verification-heavy. We use it for:

story discovery
source retrieval
claim verification

Bright Data

Search snippets are not enough for reporting. Bright Data is the extraction layer, but one practical lesson here is that Bright Data zone type matters. Browser API zones and Unlocker-style request zones do not behave the same way through the same request surface.

That is exactly why the app now surfaces provider failures directly instead of pretending extraction succeeded.

Virlo

Virlo is the ranking brain. It is not a UI ornament. It drives:

story selection
urgency
signal strength
“why you’re seeing this”

Backend Structure

The backend entrypoint is backend/app/main.py. The important design choice is that startup seeds the newsroom and begins an autonomous loop.

@asynccontextmanager
async def lifespan(_: FastAPI):
    Base.metadata.create_all(bind=engine)
    await autopilot.seed_if_needed()
    autopilot.start()
    try:
        yield
    finally:
        await autopilot.stop()

This makes the product feel alive immediately.

The Ingestion Layer

The ingestion service combines Tavily and Bright Data into a knowledge pack:

for query in topic.search_queries:
    all_sources.extend(await self.tavily.search(query))

for source in sources:
    content = await self.brightdata.extract(str(source.url))

That knowledge pack becomes the foundation for all downstream editorial work.

The key point is that the reporting stage does not read one article. It reads a source bundle.

The Multi-Agent Newsroom

Topic Agent

Converts Virlo signals into a structured reporting pitch.

Reporter Agent

Produces the first long-form draft with explicit claims and multiple perspectives.

Skeptic Agent

Challenges the draft for:

bias
missing context
weak reasoning
overclaiming

Fact-check Agent

Validates extracted claims against source retrieval.

Editor Agent

Produces the final article if the draft survives policy.

Policy Matters More Than Prompting

One of the most important parts of this system is not the prose generation. It is the deterministic controller in backend/app/services/newsroom.py.

if false_claims > self.settings.newsroom_max_false_claims:
    return PipelineDecision(status="rejected", reason="false_claims_detected")

if skeptic.skepticism_score > self.settings.newsroom_max_skeptic_score:
    revised = await self._report(topic, knowledge_pack, skeptic=skeptic, prior_draft=reporter)

That gives the system editorial discipline.

Without this layer, “multi-agent newsroom” is just prompt theater.

Designing For Failure

The ugly part of real AI systems is provider instability.

We hit two real issues while building:

Agno API drift around structured outputs
Featherless upstream failures returning 503 failed_generation

The first version of the app was demo-safe. That meant a provider failure could quietly fall back to synthetic or seeded content.

That was useful for iteration, but it was the wrong product behavior for a credible newsroom.

The current system runs in strict live-API mode:

Virlo must return real ranked trend data
Tavily must return real search results
Bright Data must return real extraction output
Featherless must return real structured agent output

raise ProviderAPIError(
    "virlo",
    f"Virlo request failed with {exc.response.status_code}",
    exc.response.status_code,
    body,
)

Instead of silently substituting content, Skeptik now reports integration status through /api/status and renders those errors on the homepage.

The Frontend

The frontend is intentionally not a dashboard.

The homepage does three things:

establishes the publication identity
foregrounds the lead story
makes the autonomous process legible

The article page then handles transparency:

story body
why-you’re-seeing-this
fact checks
source list
editorial traces

That split is deliberate. The homepage sells the product. The article page proves it.

Example Frontend Pattern

The homepage lead story is treated like a publication feature block, not a SaaS card:

{lead ? (
  <Card className="overflow-hidden bg-ink text-paper">
    <CardContent className="space-y-7 p-8 md:p-10">
      <Badge className="border-white/15 bg-white/10 text-paper">Lead Story</Badge>
      <h2 className="max-w-3xl font-display text-4xl leading-tight md:text-6xl">
        {lead.title}
      </h2>
    </CardContent>
  </Card>
) : null}

That small layout choice dramatically improves perceived credibility.

What I Would Improve Next

If I had another sprint, I would add:

Postgres + migrations
stronger source freshness scoring
more explicit evidence snippets on claim checks
Playwright smoke tests
structured observability for publish/reject runs
provider-specific health diagnostics
background worker separation from API process

Advice For Developers Building Similar Systems

1. Separate product logic from prompt logic

A newsroom should not depend on “the model behaving.” Put discipline into code.

2. Design for provider instability on day one

Do not assume every model call works. They won’t.

3. Make transparency legible, not noisy

Readers do not need every raw prompt. They need evidence that the process exists and mattered.

4. Give ranking a first-class role

Virlo mattered because it shaped the editorial surface itself, not just a tiny badge.

Skeptik is an attempt to take AI-native publishing seriously. The interesting question is not whether an LLM can write an article. It can.

The real question is whether you can build a system around that model that behaves like a newsroom instead of a demo, and whether it tells the truth when its dependencies are broken.

That means:

ranking
synthesis
skepticism
verification
policy
transparency

That is where the product lives.

Github Repo: https://github.com/harishkotra/skeptik