DEV Community: Harish Kotra (he/him)

How Complexity Library turns static code into an inspectable growth trace

Harish Kotra (he/him) — Mon, 10 Aug 2026 18:16:43 +0000

Complexity Library is a deterministic-first complexity analysis application: developers paste a Python, JavaScript, or TypeScript function, and the app returns a typed growth claim, confidence, limitations, and an interactive visualization. The interesting part is not that it says “O(n log n)”; it is that the result is bounded, inspectable, and useful without executing user code or asking a model to improvise an answer.

The problem

Most complexity explanations live in one of two uncomfortable places: static articles that cannot inspect your code, or assistant chats that can produce a plausible explanation without a reliable evidence chain. This project treats code analysis as a product surface in its own right.

The design premise is simple:

Parse the submitted artifact, derive deterministic facts, make a conservative claim, and render a trace from validated data.

That principle governs API design, data modelling, and the UI.

System shape

The web app is a Next.js 16/React 19 interface. FastAPI owns analysis, sessions, request guards, SSE, and persistence decisions. The shared visualization contract is deliberately small and versioned so a renderer consumes data, not dynamically authored UI logic.

Static analysis, not execution

For Python, the project uses the standard-library ast module. JavaScript and TypeScript use tree-sitter. The engine records facts before it makes a complexity claim: loop depth, halving behavior, sort operations, binary-search conventions, recursion, allocations, branches, and known calls.

def find(items, target):
    low, high = 0, len(items) - 1
    while low <= high:
        mid = (low + high) // 2
        if items[mid] == target:
            return mid
        if items[mid] < target:
            low = mid + 1
        else:
            high = mid - 1
    return -1

The analyzer sees a loop that repeatedly narrows low/high bounds around a midpoint. That maps to a documented binary-search rule, producing an O(log n) claim with high confidence and O(1) auxiliary space.

The implementation then returns a Pydantic model rather than free-form prose:

class ComplexityAnalysis(BaseModel):
    time_complexity: TimeComplexity
    space_complexity: SpaceComplexity
    confidence: float = Field(ge=0, le=1)
    pattern: AlgorithmPattern
    reasoning: str
    assumptions: list[str]
    limitations: list[str]
    signature: ComplexitySignature

That distinction is important. A consumer can render confidence and limitations safely, persist a reproducible result, or reject unknown enum values without parsing natural language.

Conservative rules beat invented certainty

The engine knows a practical initial set: simple work, linear scans, halving loops, nested loops, sorting, binary search, two-pointer and sliding-window shapes, and direct recursive patterns. It does not pretend to solve arbitrary program analysis.

When it sees an unresolved call, it lowers confidence and reports a limitation. When it sees submitted source, it never executes it. Those two decisions make the application more trustworthy than a system that is always fluent.

The test suite covers all headline growth classes—from O(1) through O(n!)—and checks exact analysis fields rather than merely snapshotting a paragraph.

cd apps/api
uv run pytest

Visualization is a data contract

The next design decision is easy to miss: visualizations are not screenshots or generated canvas code. The API builds a constrained VisualizationSpec with a template type, bounded steps, annotations, accessible summary, and input controls.

{
  "schema_version": 1,
  "type": "logarithmic_halving",
  "input_size": 16,
  "operation_estimate": 4,
  "accessible_summary": "The search space halves from 16 until one item remains."
}

The UI can animate, step, reset, and summarize that data locally. It does not need to ask the backend for each frame, and it never treats model output as executable component code.

Anonymous by default

The first use of the product should not require an account. The API issues an opaque HttpOnly anonymous-session cookie and scopes processing-status/SSE access to that session. Local development uses in-memory repositories; production can opt into Supabase for durable sessions and function records.

Before analysis, the service checks a honeypot field, declared request-body size, schema limits, and a process-local sliding-window rate limit. These are intentionally deterministic safeguards. Redis-backed quotas, queues, and further abuse signals are part of the public roadmap.

Why use SSE?

The browser requests an asynchronous analysis job, then connects to a server-sent-events endpoint. The UI maps actual API stage names—parsing, syntax facts, loop/recursion detection, complexity decision, visualization construction—to visible progress.

const events = new EventSource(`${apiUrl}${payload.events_url}`, {
  withCredentials: true,
});

events.addEventListener("completed", (message) => {
  setResult(JSON.parse(message.data));
  events.close();
});

For the local MVP, jobs are in-process. Durable queues and reconnect semantics are open OSS issues rather than hidden behind a claim of production readiness.

The UI: a learning instrument, not a dashboard

The web design uses a graph-paper-like ground, a compact trace palette, editorial display type, and monospace data labels. That visual direction is not ornamental: the grid supplies scale to growth traces, while blue/coral/moss distinguish operation states and results.

The workbench gives the user one clear job—provide a function and inspect its dominant work. Playback has native buttons, visible focus, accessible textual summaries, and reduced-motion-aware behavior. The learn route extends the same visual language into ten input-driven lessons, not static articles.

Running the project

# Install the web workspace
pnpm install

# Run the API
cd apps/api
uv sync --extra dev
uv run uvicorn app.main:app --reload --port 8000

# In another terminal, from the repository root
pnpm dev:web

The project runs locally without LLM, Supabase, or Redis credentials. Supabase migrations and a deterministic curated seed command are available when durable mode is needed.

What contributors can build next

The most useful next contributions are not cosmetic. They are correctness and product-depth work:

Explicit selection when a submitted file contains multiple functions.
Better local call-graph and auxiliary-space analysis.
Cursor pagination, PostgreSQL full-text search, and unified discovery across functions, algorithms, lessons, and tags.
More bounded visualization templates: sorting, graph traversal, cubic, exponential, and factorial growth.
Durable queue/reconnect handling, Redis quotas, Supabase migration rehearsal, and E2E/a11y/performance tests.
A strictly constrained, provider-neutral fallback for genuinely ambiguous analysis—without weakening deterministic precedence.

All remaining work is broken into labeled public issues. The repository is a good fit for contributors who care about developer tools, static analysis, accessible data visualization, or safe AI-adjacent systems.

Complexity Library is a small argument for a different kind of developer-learning product: one where the output is not a confident answer but an inspectable artifact. The parser tells us what it saw. The rules explain the claim. The trace makes the growth visible. And where the system is uncertain, it says so.

That is a much better foundation for learning how software scales.

Code & more: https://www.dailybuild.xyz/project/218-complexity-library

Building AssetCupid: a trust-gated marketplace for real-world assets

Harish Kotra (he/him) — Sun, 09 Aug 2026 18:26:16 +0000

Most RWA applications end at issuance: create a token, display its address, and call it a product. The harder question begins afterward: what does this asset need, who is economically compatible, and can the proposed relationship actually transact?

AssetCupid is an answer to that question. It is a matching workflow built around live Cleanverse-issued A-Tokens on Monad Testnet. The app separates economic compatibility from transaction eligibility, then uses Cleanverse as a real trust gate rather than a decorative badge.

The product model

![The product model(https://dev-to-uploads.s3.us-east-2.amazonaws.com/uploads/articles/nzb7990bypojr1p9vo5r.png)

This model avoids an easy but misleading shortcut: treating every promising mandate as a Cleanverse-verified counterparty. AssetCupid’s mandate records are curated marketplace content. They only become a transaction candidate when a real representative wallet is supplied and checked.

Live assets first, not demo fixtures

The catalog route queries the configured Cleanverse account for issued Monad assets at runtime. The asset address then becomes the anchor for the profile, matching exercise, and eligibility checks.

// Route handlers call server-only services; the browser does not see credentials.
const assets = await listIssuedMonadAssets();
return Response.json({ ok: true, data: assets });

The practical effect is important: the demo evolves as the Cleanverse sandbox account evolves. It does not rely on a hardcoded collection of fictional RWAs.

Keeping Cleanverse credentials off the client

Cleanverse credentials live in server environment variables. The browser calls same-origin Next.js routes; those routes use a shared server client that adds the API ID, creates a request ID, encrypts sensitive endpoints, and normalizes failures.

private async request<T>(path: string, init: RequestInit): Promise<T> {
  this.assertConfigured();
  const response = await fetch(`${this.url}${path}`, {
    ...init,
    headers: { "api-id": this.id!, "X-Request-ID": randomUUID(), ...init.headers },
    cache: "no-store",
  });

  if (!response.ok) throw new CleanverseError(String(response.status));
  const envelope = await response.json() as CleanverseEnvelope<T>;
  if (envelope.code !== "0000") throw new CleanverseError(envelope.code, envelope.message);
  return envelope.data;
}

That final envelope.code check matters. API integrations often assume an HTTP 200 means success; Cleanverse can return a business failure inside a successful HTTP response. AssetCupid tests that behavior directly.

Why matching is deterministic

The term “AI matching” can hide a major product risk: an opaque system whose rationale changes from run to run. In early-stage financial workflows, explainability has more value than theatrical intelligence.

AssetCupid scores six factors:

Factor	Weight	Example
Goal	25	Capital mandate for a capital-seeking asset
Asset type	20	Infrastructure-compatible mandate
Amount	20	Target fits the mandate range
Geography	15	Market overlap
Risk	10	Compatible risk preferences
Horizon	10	Compatible duration

if (factors.goal === 0) {
  blockers.push("This mandate does not address one of the asset’s selected goals.");
}
if (factors.geography === 0) {
  blockers.push("The selected markets do not overlap.");
}

return matches
  .filter(({ match }) => match.blockers.length === 0 && match.economicScore >= 55)
  .sort((left, right) => right.match.economicScore - left.match.economicScore);

The system can therefore say why a match ranked highly—and why another did not qualify. An LLM could later rewrite these explanations in a more conversational style, but it should not decide the score.

Trust is an execution gate

A strong 97% economic match is not a permission to transact. After a match is requested, the product checks both wallets with Cleanverse verify_apass for the selected A-Token. Results are normalized into product states such as eligible, missing A-Pass, restricted, unavailable, and asset-not-found.

sequenceDiagram
  participant Owner
  participant App as AssetCupid
  participant CV as Cleanverse
  participant Partner

  Owner->>App: Request economic match
  Partner->>App: Provide representative wallet
  App->>CV: verify_apass(owner, A-Token)
  CV-->>App: normalized eligibility result
  App->>CV: verify_apass(partner, A-Token)
  CV-->>App: normalized eligibility result
  alt both eligible
    App-->>Owner: Deal room unlocked
  else either blocked
    App-->>Owner: Blocked state + reason
  end

The application stores verification evidence and timestamps with the match. It does not reveal identity data. It also does not make a CCP claim without a real Validator/CCP pool connected to the asset.

Monad wallet integration

The UI uses the standard EIP-1193 browser provider. It attempts to switch to Monad Testnet and, if needed, asks the wallet to add the network.

await window.ethereum.request({
  method: "wallet_switchEthereumChain",
  params: [{ chainId: "0x279f" }],
});

This is intentionally separate from Cleanverse verification. Wallet connection establishes the actor for the UI; Cleanverse determines whether that actor may transact with the selected asset.

Persistence and the production caveat

For hackathon development, AssetCupid uses Node’s built-in SQLite support. It persists asset profiles, generated matches, state changes, verification evidence, and deal rooms locally. On Vercel, the database path falls back to /tmp so the app can run, but that filesystem is ephemeral.

The next production milestone is to make the repository asynchronous and back it with Neon Postgres or libSQL. The product must not imply that its current serverless match records are durable.

What I would build next

A hosted database adapter and migrations.
Verified opportunity onboarding for actual capital, insurance, and buyer organizations.
Real CCP pool evidence when an asset has an associated registered pool.
Deal-room documents, roles, approvals, and audit events.
An LLM copy layer constrained to existing deterministic facts.

The key principle will remain unchanged: live asset facts come from Cleanverse and Monad; matching is an explainable marketplace model; transaction eligibility is checked, not assumed.

Code & more: https://www.dailybuild.xyz/project/217-asset-cupid

Building Takumi: An Engineering Craftsmanship Layer for AI Coding Agents

Harish Kotra (he/him) — Sat, 08 Aug 2026 16:19:20 +0000

A technical deep dive into turning an AI coding harness into a deliberate engineering practice environment.

The problem

Most coding agents optimize for a short path from prompt to working software. That is useful, but it can leave the developer with a fragile understanding of the resulting system. The missing abstraction is not another model or another chat window. It is the engineering decision.

Takumi changes the optimization target:

Prompt → model → code

becomes:

Decision → developer reasoning → guided implementation → reflection → capability growth

The coding harness remains responsible for files, tools, model routing, and sessions. Takumi owns the layer around developer judgment.

Why Pi is a host, not the product

Pi exposes lifecycle hooks, TUI interactions, tool-call interception, session persistence, and an SDK. Takumi uses those seams rather than maintaining a fork of the entire coding harness. This keeps model/provider/tool evolution in Pi while keeping Takumi's moat in engineering learning.

The decision engine

Takumi detects consequential context with a conservative catalog. A request mentioning authentication becomes a security checkpoint; a request mentioning persistence becomes a data-model checkpoint. Trivial implementation details pass through.

const checkpoint = detectDecision("Add authentication to the API");

// checkpoint.question:
// "Which security model fits the threat model and user experience?"
// checkpoint.options:
// ["Session-based auth", "JWT tokens", "OAuth/OIDC", ...]

The developer selects an option and explains why. That reasoning is stored as an EngineeringDecision, not as undifferentiated conversation memory.

Adaptive coaching

The Engineering Profile is multidimensional. A developer can have high architecture competence, low testing competence, and low confidence in concurrency. A single beginner/intermediate/advanced label loses that information.

export interface EngineeringProfile {
  skills: SkillMap;
  confidence: SkillMap;
  testingDiscipline: number;
  architectureMaturity: number;
  recurringMistakes: string[];
  repeatedStrengths: string[];
  commonTradeOffs: string[];
}

Coaching uses both competence and confidence. High competence with low confidence calls for encouragement and a bounded challenge. Low competence with high confidence calls for evidence, trade-offs, and a smaller checkpoint.

Governance against architectural drift

Every initialized project receives two files:

ARCHITECTURE.md defines module boundaries and request flow.
VISION_GUARDRAILS.md defines what Takumi must optimize for and what it must reject.

At session start, the extension reads both. For implementation requests, the developer states the proposed boundary and vision alignment; Pi must explain its alignment before implementation tools are allowed. This turns architectural intent into an executable development constraint.

Persistence and privacy

Takumi is local-first:

.takumi/
├── engineering-profile.json
├── decision-timeline.json
├── telemetry.json
└── latest-debrief.json

JSON is the default because it is inspectable and portable. Node's built-in SQLite backend is available when a project needs transactional local storage. Export and deletion are explicit CLI operations; local state is ignored by Git.

Patterns and debriefs

After an agent settles, the pattern engine looks for conservative longitudinal signals: weak testing discipline, repeated decision categories, recurring mistakes, or architecture thinking without executable proof. The debrief engine turns those observations into staff-engineer-style feedback:

strongest and weakest moments;
concepts learned and still weak;
trade-offs made;
profile changes; and
a recommended next practice.

It is intentionally not a scorecard. The goal is one useful observation at a time.

Extension points

Takumi keeps dependency inversion explicit:

export interface AgentAdapter {
  initialize(): Promise<void>;
  startSession(): Promise<Session>;
  injectPrompt(prompt: string): Promise<void>;
  receiveResponse(): Promise<HarnessResponse>;
  // files, commands, pause/resume, and cancellation omitted here
}

export interface CoachingStrategy {
  readonly name: StrategyName;
  applies(context: CoachingContext): boolean;
  createPlan(context: CoachingContext): CoachingPlan;
}

export interface Storage {
  read<T>(key: string): Promise<T | undefined>;
  write<T>(key: string, value: T): Promise<void>;
}

New harnesses implement an adapter. New interventions implement a strategy plugin. New persistence systems implement Storage. The Coaching Engine never imports a harness.

Testing the architecture

The project uses Node's test runner for fast behavioral tests and strict TypeScript checking:

npm run typecheck
npm test

Tests cover adapter lifecycle, decision detection, coaching selection, profile updates, governance loading, debrief generation, SQLite persistence, and CLI launcher arguments.

What comes next

The most valuable future work is better evidence, not more automation: outcome validation, richer testing/debugging signals, a native decision timeline UI, and OpenCode tool governance. IDE integrations, team analytics, cloud sync, and MCP should remain optional surfaces around the same local-first core.

Takumi succeeds when a developer finishes a task and can explain why the system works, what trade-offs were made, and what they would do next without needing the agent to take over.

Code & more: https://www.dailybuild.xyz/project/216-takumi

Meeting Lie Detector: Catching Organizational Lies with HydraDB

Harish Kotra (he/him) — Fri, 07 Aug 2026 18:26:43 +0000

A technical deep dive for developers building multi-source AI context systems.

TL;DR

Meeting Lie Detector is a Python application on HydraDB that detects when workplace tools disagree about decisions—especially who owns what after a meeting. It ingests Linear, Slack, Notion, and real documents (PDF/Markdown), then answers multi-hop questions using staged retrieval (preferring HydraDB fast mode) while measuring latency, call count, and accuracy.

If you are building agents that “read the company brain,” this is a blueprint for cross-source truth, not single-index RAG.

The problem (beyond “RAG”)

Vector search finds similar text. It does not natively answer:

On the Phoenix work tracked as Linear PHX-42 around Tuesday, who did the PDF say owned auth, who claimed it in Slack within two hours, and does Notion still show the old owner?

That question needs:

Temporal ordering (before / during / after the meeting)
Entity identity (Alice Chen = @alice = alice-chen)
Knowledge updates (Notion page v1 vs v2)
Multi-hop stitching (Linear → PDF → Slack → Notion)
Actor-based filtering (what Bob said vs what the template still defaults to)

Teams usually paper over this with more Notion fields. Agents need a context substrate that can retrieve across connectors with metadata and graph structure. That’s HydraDB’s job; Meeting Lie Detector is the productized workflow on top.

Product shape

Layer	Role
Connectors / files	Slack, Notion, Linear, documents
HydraDB	Isolated database, ingest, hybrid query, graph, connector sync
Multi-hop planner	Multiple targeted queries, not one mega-prompt
Synthesizer	Deterministic extractive answers (swap for LLM later)
Eval harness	Expected vs actual, latency, cost estimates

Architecture

Why dual ingest?

Showcase path — committed sample data under data/ so anyone can reproduce the ownership-lie story without OAuth.
Native path — HydraDB Connectors API so real workspaces can sync live channels, pages, and calendars.

Both land in the same HydraDB database and are queryable with query_apps=True and metadata filters.

Data model (the sample world)

People intentionally collide as aliases:

Alice Chen / alice.chen@company.com / @alice / alice-chen / “Alice C.”
Bob Martinez / @bob / bob-m
Carol Nguyen / @carol
David Kim / @dkim

Projects: Phoenix, Orion, Mobile Redesign.

The critical timeline:

2026-06-18  Decision doc: Alice sole auth owner
2026-07-29  10:00 PT  Project Sync / Linear PHX-42 (Alice assignee)
2026-07-29  11:05 PT  Official PDF still lists Alice
2026-07-29  11:42 PT  Slack: Bob claims eng ownership
2026-07-29  12:30 PT  Post-meeting summary: Bob eng owner
2026-07-31  16:20 PT  Notion Action Items updated → Bob
(template page never updated — still defaults Alice)

That is not a toy “hello world” index. It is a deliberate contradiction graph.

Ingestion: documents + app knowledge

Creating the database

from hydra_db import HydraDB
import time, os

client = HydraDB(token=os.environ["HYDRA_DB_API_KEY"])
database = "meeting_lie_detector"

client.databases.create(
    database=database,
    database_metadata_schema=[
        {"name": "source", "data_type": "VARCHAR", "enable_match": True, "max_length": 64},
        {"name": "type", "data_type": "VARCHAR", "enable_match": True, "max_length": 64},
        {"name": "project", "data_type": "VARCHAR", "enable_match": True, "max_length": 64},
        {"name": "date", "data_type": "VARCHAR", "enable_match": True, "max_length": 32},
        {"name": "channel", "data_type": "VARCHAR", "enable_match": True, "max_length": 64},
    ],
)

while not client.databases.status(database=database).data.infra.ready_for_ingestion:
    time.sleep(5)

Metadata fields like source and project power fast filters—critical for “Slack only, phoenix only” hops without paying for thinking mode.

App knowledge (connector-shaped records)

import json

app_item = {
    "id": "slack_thread_after_sync_20260729",
    "title": "Slack #phoenix-eng: Bob claims auth rewrite ownership",
    "type": "slack",
    "provider": "slack",
    "kind": "message",
    "timestamp": "2026-07-29T11:42:18-07:00",
    "url": "https://company.slack.com/archives/C0PHXENG01/p...",
    "content": {"text": open("data/slack/thread-after-sync-ownership-2026-07-29.txt").read()},
    "tenant_metadata": {
        "source": "slack",
        "type": "thread",
        "project": "phoenix",
        "date": "2026-07-29",
        "channel": "phoenix-eng",
    },
    "additional_metadata": {
        "actors": ["Bob Martinez", "Alice Chen", "Carol Nguyen", "David Kim"],
        "connector_label": "slack",
    },
    "relations": {
        "ids": ["cal_evt_phoenix_sync_20260729", "doc_meeting_notes_20260729"],
        "properties": {"reason": "cross_source_link"},
    },
}

client.context.ingest(
    type="knowledge",
    database=database,
    upsert=True,
    app_knowledge=json.dumps([app_item]),
)

Real document upload (PDF)

with open("data/documents/meeting-notes-2026-07-29.pdf", "rb") as f:
    client.context.ingest(
        type="knowledge",
        database=database,
        upsert=True,
        documents=[("meeting-notes-2026-07-29.pdf", f, "application/pdf")],
        document_metadata=json.dumps([{"id": "doc_meeting_notes_20260729"}]),
        metadata={"source": "document", "type": "meeting_notes", "project": "phoenix", "date": "2026-07-29"},
        additional_metadata={"actors": ["Alice Chen", "Bob Martinez", "Carol Nguyen"]},
    )

Always poll client.context.status until indexing_status is graph_creation or completed before querying.

Native connectors (live Slack / Notion / Linear)

HydraDB exposes a first-class Connectors API. The app wraps it in mld/native_connectors.py and connectors_setup.py:

list providers → create(provider, credentials, database)
  → discover resources → configure(resources)
  → sync → poll status

# High-level (see mld/native_connectors.py)
from mld.native_connectors import setup_provider
from mld.client import get_client

client = get_client()
setup_provider(client, "slack", database="meeting_lie_detector", lookback_days=90)

Credentials stay in environment variables (SLACK_BOT_TOKEN, NOTION_API_KEY, LINEAR_API_KEY)—never in the repo.

Multi-hop retrieval: the real product logic

Hackathon-style demos often do one query() and hope. This app uses explicit hop plans.

# mld/retrieval.py (simplified)
@dataclass
class QueryHop:
    name: str
    query: str
    mode: str = "fast"
    metadata_filters: dict | None = None
    max_results: int = 6
    graph_context: bool = False

# Flagship plan hops:
# 1. calendar + filters source=linear, project=phoenix
# 2. documents (official notes)
# 3. slack ownership claim
# 4. notion action items (recency_bias)
# 5. synthesis (fast or thinking)

Evaluation runs those hops in order:

# evaluate.py — core loop (conceptual)
plan = plan_for(question.id, prefer_mode=mode)
all_chunks, sources = [], []
for hop in plan.hops:
    hop_mode = "fast" if mode == "fast" else (
        "thinking" if hop.name == "synthesis" else "fast"
    )
    result = query_knowledge(
        client,
        hop.query,
        mode=hop_mode,
        metadata_filters=hop.metadata_filters,
        graph_context=hop.graph_context or hop_mode == "thinking",
        query_apps=True,
    )
    all_chunks += extract_chunk_texts(result)
    sources += extract_source_titles(result)

answer = synthesize_answer(question.question, all_chunks, mode)

Fast vs thinking

Mode	When used	Tradeoff
fast	Almost every hop; filter-heavy questions	Low latency, lower graph expansion
thinking	Optional final synthesis	Higher quality / relations, higher latency & cost

Estimated cost constants live in mld/config.py for competition-style reporting (illustrative, not billing).

Answer synthesis

The default synthesizer is extractive and deterministic—no external LLM—so offline and online scoring is reproducible:

Split retrieved chunks into sentences
Rank by ownership / actor / question keyword hits
Emit top sentences as the answer

You can replace this with HydraDB’s build_string(result) + any chat model without changing ingest.

from hydra_db.helpers import build_string
# context = build_string(result)
# → feed to your LLM with “answer only from context”

Optional heuristic lie signals live in mld/detect.py (e.g. Alice and Bob both appear as owners → ownership contradiction).

Evaluation harness

Twelve questions cover:

Multi-hop calendar/doc/slack/notion
Temporal knowledge updates
Entity aliases
Thread / actor queries
Metadata-filter fast path
Multilingual (Spanish question over English corpus)
Third-party attribution

python evaluate.py --mode both
python evaluate_offline.py   # no API key; validates corpus
python demo.py               # flagship Q1 live

Artifacts under results/:

Per-question hop logs (modes, latency, sources)
Accuracy / partial scores
Aggregate fast-mode success rate

Project layout for contributors

meeting-lie-detector/
├── data/                 # Sample multi-source world
├── mld/
│   ├── catalog.py        # Source registry + relations
│   ├── client.py         # HydraDB helpers
│   ├── native_connectors.py
│   ├── retrieval.py      # Multi-hop plans
│   ├── questions.py      # Eval set
│   └── detect.py         # Contradiction heuristics
├── ingest.py
├── connectors_setup.py
├── evaluate.py
├── evaluate_offline.py
├── demo.py
├── requirements.txt
└── .env.example

Operational tips

Plan metadata schema before first ingest — filter fields are declared at database create.
Stable IDs + upsert — re-ingest safely after editing sample files.
Wait for indexing — querying too early looks like “HydraDB failed.”
Prefer filters over thinking — project=phoenix + source=slack is free precision.
Forceful relations — link calendar ↔ thread ↔ PDF so thinking mode can expand.
Keep secrets out of git — .env is ignored; use .env.example only.

What you can build next

A UI timeline of “decision → claim → doc lag → wiki fix”
Continuous monitoring agent that alerts when Slack owner ≠ Notion owner
Same multi-hop pattern for incidents (PagerDuty + Slack + Jira + runbooks)
Per-user collection memories for “how this manager prefers ownership reported”

HydraDB gives you the context substrate; Meeting Lie Detector shows a full vertical: ingest → multi-hop query → measure.

Most AI workplace tools answer from one pane of glass. Real organizations decide in meetings and diverge across tools. Meeting Lie Detector encodes that failure mode as data and retrieval—and uses HydraDB so the graph, metadata, and hybrid search do the heavy lifting.

Code & more: https://www.dailybuild.xyz/project/215-meeting-lie-detector

Building GODS vs AGENTS: an architecture for belief under uncertainty

Harish Kotra (he/him) — Thu, 06 Aug 2026 18:29:01 +0000

How do you make a simulation about religion without reducing humans to rules and canned dialogue? GODS vs AGENTS starts with one boundary: physics can be deterministic; meaning cannot.

The app is an interactive research simulation where the player is an unseen force. You can send rain, split a tree with lightning, heal someone, or darken the sky. You cannot explain why. The village must do that work itself.

The central system decision

The easiest version of this app would assign “faith +5” after a lightning strike. That is precisely the version we are avoiding. Belief is not a score; it is a changing set of claims with causes, confidence, relationships, memories, and social provenance.

The same strike may create several competing theories. A farmer may see an angry sky spirit; a healer may see an ordinary storm; a politically ambitious priest may see an opportunity. The server does not declare which explanation is “correct.” It records that a tree split, and agents reason from their own context.

The current product slice

The first shipped slice is deliberately honest: a specimen world rather than fake autonomy. The visual system is a ritual atlas—an illustrated field, archival notes, and an omen wheel—because an operations dashboard would undermine the premise. The player is meant to watch an unknowable force’s consequences, not manage a spreadsheet.

The web app is built with Next.js, React, TypeScript, CSS, and Framer Motion. The small FastAPI service models the deterministic world contract.

@app.post("/miracles", response_model=WorldState)
async def invoke(command: Invoke):
    effects = {
        Miracle.rain: ("weather", "rain"),
        Miracle.drought: ("food_supply", -.12),
        Miracle.heal: ("health", .09),
    }
    # Mechanics are explicit, deterministic, and easy to test.

The frontend does not receive or store credentials. Its “cognition awaiting a mind” state is a product requirement, not just an onboarding state. Without a model, the user can explore the specimen and trigger visual effects, but it cannot claim that anyone thought anything new.

The planned agent loop

Agno is a natural fit because every citizen can be modeled as an independently configured agent with a provider abstraction. A production action should be small and observable:

async def interpret(citizen, event):
    memories = await memory.search(citizen.id, event.embedding, limit=6)
    response = await citizen.agent.arun(
        make_prompt(profile=citizen.profile, event=event, memories=memories)
    )
    claims = parse_claims(response.content)
    await belief_graph.upsert(citizen.id, claims, source_event=event.id)
    await memory.store(citizen.id, summarize(response.content))
    return claims

The crucial optimization is memory retrieval. Forty agents with entire histories would be slow, expensive, and incoherent. Store structured memories and LLM summaries, retrieve only the few most relevant items, and periodically compress old material. The belief graph should preserve provenance: “Mara believes X because she saw Y and later heard Z from Oren.”

A provider-neutral architecture

Provider configuration stays server-side and supports hosted or local inference. A user with no cloud key can use Ollama or LM Studio via an OpenAI-compatible base URL. The rest of the system should only know about an interface such as generate() or an Agno model object—not whether the provider is OpenAI, Anthropic, or a laptop-local model.

Where contributors can help

The best next contributions are structural: SQLite repositories, a versioned belief graph, Agno provider adapters, and a WebSocket event stream. Creative contributions are equally welcome once they preserve the core rule: miracles change the world; agents create the explanations.

That separation is what makes the project more than a simulation. It is an instrument for watching causality become culture.

Code & more: https://www.dailybuild.xyz/project/214-gods-vs-agents

Building The Rumor Machine: making the spread of belief visible

Harish Kotra (he/him) — Wed, 05 Aug 2026 18:22:52 +0000

A technical note for developers who want to build simulations where information—not resource management—is the mechanic.

The design constraint

The central constraint was conceptual, not visual: reality must not move. The interesting system is every version of that reality that people form and transmit.

So the app begins with one protected record:

const event = 'A dragon attacked the eastern farm at dawn.';

The map is then a readout of thirty separate interpretations. A farmer can speak from proximity, a scholar can hesitate, and a child can leap to a dramatic conclusion. The user sees the social network rather than being asked to micromanage it.

The browser architecture

React owns the exhibit state. The provider adapter is deliberately separate from the rumour orchestrator: the adapter knows how to call an endpoint; the orchestrator knows the information rules. That boundary lets the same citizen workflow run against a hosted model, a local model, or an Agno agent.

A provider-neutral model adapter

Most model servers now implement OpenAI-style chat completions. One small function can therefore cover OpenAI, gateways, Ollama’s compatibility server, and LM Studio:

const response = await fetch(`${baseUrl}/chat/completions`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${apiKey}` },
  body: JSON.stringify({
    model,
    temperature: 0.7,
    response_format: { type: 'json_object' },
    messages,
  }),
});

The Agno citizen service takes a different route. It accepts a run for one named citizen, so the orchestration and role rules remain inside real Agno agents:

await fetch(`${agentOsUrl}/agents/${agentId}/runs`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${token}` },
  body: JSON.stringify({ message: prompt, stream: false }),
});

The workflow: model output as a constrained simulation input

The prompt mirrors a small agent workflow: observe the permanent record, retrieve current memory, reason through a role, converse, then reflect. The response is constrained to a compact JSON payload.

const value = JSON.parse(match[0]) as BeliefUpdate;
if (!value.belief || !Number.isFinite(value.confidence)) {
  throw new Error('The model response was missing a belief or confidence.');
}
return { ...value, confidence: Math.max(0, Math.min(100, Math.round(value.confidence))) };

This detail matters. A model is not authoritative simply because it returns prose. The simulation treats every model answer as untrusted input, parses it, clamps its numeric ranges, and only then adds it to a citizen state.

Why the map uses CSS and SVG

The brief calls for a miniature village, but a full 3D scene is not automatically the better first implementation. The map’s job is to show relationships, distance, and transmission. CSS buildings and an SVG network do that at a tiny payload and make the flow lines easy to inspect.

The visual direction is closer to a field notebook than an AI dashboard: muted terrain, editorial type, old-paper profile cards, and one warm highlight for the active thread. The interface’s signature is the glowing rumor line—the visual equivalent of a sentence moving from person to person.

The current model consultation is intentionally individual and opt-in. A deeper version should add first-class rumours, a maximum memory queue, trust deltas, deterministic scheduled encounters, and replayable seeds. Once those pieces exist, model calls can be used selectively—for example only when a novel rumour reaches a high-influence citizen—while the majority of the simulation remains cheap, traceable, and reproducible.

For a public deployment, move the model calls behind a server-side proxy. A browser should never be the long-term home of a paid provider credential.

Code & more: https://www.dailybuild.xyz/project/213-the-rumor-machine

Building Agent Genome: making evolutionary AI visible

Harish Kotra (he/him) — Tue, 04 Aug 2026 13:38:28 +0000

Agent Genome is an interactive browser exhibit built around a simple question: how do you explain evolving agents without asking people to read logs or trust an aggregate chart?

The answer is a small, visual population. Forty glowing organisms move across a sparse resource-and-hazard field. Every organism has an explicit 1–10 genome. Visitors can inspect an organism’s traits, current intent, recent reflection, fitness, memory, and lineage; when the generation ends, they see selection, inherited strategies, and mutation produce the next cohort.

The product decision: reveal the mechanism

This is intentionally neither a chat application nor a game. The user should be able to answer three questions almost immediately:

What are the organisms doing?
Why does one behave differently from another?
How does a generation change the next one?

The dark field, energy sources, hazards, trails, specimen panel, and full-screen generation transition are all designed to expose that causal chain rather than decorate it.

A monorepo with deliberate boundaries

Agent Genome uses a Turborepo workspace. This is not architectural theatre: genetics, simulation, memory, and rendering should evolve independently.

apps/web             Next.js UI, Canvas renderer, local interaction state
packages/genome      Trait types, clamping, crossover, mutation
packages/simulation  Parent selection and offspring construction
packages/core        Structured memory capped at 20 records
packages/agents      Goal vocabulary
packages/langgraph   Real LangGraph reflection workflow and provider adapters
packages/ui          Genome colour tokens
packages/shared      Shared constants

The web app owns transient visual positions and trails. Selection and crossover belong in pure TypeScript modules. This means a future React Three Fiber scene, headless simulation runner, or replay UI can reuse the same genetics API.

A readable genome

Every trait is a whole number between 1 and 10. That range is a product choice: a visitor can understand it instantly, a bar chart stays useful, and a mutation is easy to describe.

export type GenomeTrait =
  | 'planning' | 'memory' | 'risk' | 'curiosity'
  | 'cooperation' | 'explorationRadius'
  | 'toolUsage' | 'reflectionFrequency';

export type Genome = Record<GenomeTrait, number>;

export const clampTrait = (value: number) =>
  Math.max(1, Math.min(10, Math.round(value)));

Bound the values at the domain edge, not in the renderer. That lets every downstream consumer assume genome data is valid.

Crossover and mutation without a black box

For each trait, a child inherits a value from one parent, then has a small chance of a one-step mutation:

export function crossover(a: Genome, b: Genome, mutationRate = 0.08): Genome {
  const child = {} as Genome;
  for (const key of Object.keys(a) as GenomeTrait[]) {
    const inherited = Math.random() > 0.5 ? a[key] : b[key];
    const mutation = Math.random() < mutationRate
      ? (Math.random() > 0.5 ? 1 : -1)
      : 0;
    child[key] = clampTrait(inherited + mutation);
  }
  return child;
}

Parent selection takes the highest-fitness segment of the population. It is intentionally simpler than a research-grade evolutionary system because inspectability is the point.

const elite = [...population]
  .sort((left, right) => right.fitness - left.fitness)
  .slice(0, Math.ceil(population.length * 0.35));

const parentA = elite[index % elite.length];
const parentB = elite[(index * 7 + 3) % elite.length];

Later versions can add tournament selection, novelty search, or seeded randomness and replay. They should retain a visible explanation for every evolutionary event.

The simulation is autonomous; LLM reflection is optional

The project names a cognition loop even though the initial exhibit uses deterministic browser-safe behaviour:

packages/langgraph implements a LangGraph flow behind the optional reflection action. LangChain adapters connect it to Ollama, LM Studio/OpenAI-compatible endpoints, OpenAI, and Anthropic. A model-backed reflection node looks at structured recent outcomes and proposes a bounded change—for example, lowering risk after costly exploration. It cannot rewrite simulation code, bypass trait limits, or issue arbitrary actions.

The simulation itself does not need a provider or API key. Its fitness is calculated from live world events: resources collected, hazard avoidance, proximity-based cooperation, and exploration. This preserves an important distinction: memory records an organism’s recent experience; evolution changes the strategy distribution across a population. LLM reflection is an optional, evidence-constrained layer on top of that loop—not the source of the simulation’s behaviour.

The reflection action sends the selected organism’s goal, current fitness, structured memory, and genome to the selected provider. It returns strict JSON containing one sentence and permitted bounded trait changes. There is no tool access, code execution, RAG, vector database, or persistent provider conversation.

Why the initial renderer is Canvas 2D

Three.js and React Three Fiber are listed as an upgrade path, but Canvas 2D is the right first rendering layer. It keeps the 40-organism field inexpensive while still providing glow, trails, particles, resources, hazards, and selection feedback.

The animation loop updates motion imperatively while React handles interface state:

a.vx += Math.cos(angle) * 0.004 * (a.genome.curiosity / 5);
a.vy += Math.sin(angle) * 0.004 * (a.genome.curiosity / 5);
a.vx *= 0.97;
a.vy *= 0.97;
a.x = Math.max(3, Math.min(97, a.x + a.vx * speed * dt * 50));

This is expressive visual motion, not a physics engine. Keeping it light gives the project a clear 60 FPS target without shaders or high-frequency React state updates.

Run and extend it

npm install
npm run dev --workspace=@agent-genome/web
npm run build --workspace=@agent-genome/web

The highest-value next additions are richer resource respawning and cooperation events, mutation replay, generation comparison, JSON genome snapshots, reduced-motion and keyboard support, deterministic seeds, and a WebGL renderer that consumes the same simulation contract.

The guiding principle is simple: make every change in the population explainable to the person watching it.

Code & more: https://www.dailybuild.xyz/project/212-agent-genome

The Inheritance Game: a civilization simulator where the world is the main character

Harish Kotra (he/him) — Mon, 03 Aug 2026 18:01:14 +0000

Nobody lives forever. Everyone leaves something behind.

I built a game where players never respawn — they inherit lives. You don't create a character. The world hands you a fisherman, a queen, a criminal, a baker — someone already mid-story — and you live out their remaining life. When they die, the world keeps turning, and you inherit another life.

The world is a TypeScript simulation: ~1,600 souls across a procedurally generated realm, each with a family tree, layered memories, a journal, debts, grudges, and an unfinished goal. A monthly tick drives aging, marriage, birth, death, inheritance, war, crime, trade, technology and memory. Everything persists to Postgres. Nothing is faked — the LLM layer is optional, and when it's absent, a hand-written narrator speaks for the world.

This post walks through the architecture and the decisions that make it work.

The design philosophy: simulation-first, LLM-last

The most important decision was what the AI does not do. The LLM never controls behavior — it only writes prose. Every mechanic is a real rule system:

Economy — settlements produce, price, trade and hoard goods; scarcity causes hunger.
Demographics — fertility, coming-of-age, marriage, pregnancy, aging, death.
Politics — leaders, councils, tax policy, succession, war, raids.
Crime — theft, fraud, smuggling, trials, prisons, reputation damage.
Technology — eras advance (stone → iron → printing → steam) as settlements accumulate progress.

If an LLM key is configured, it narrates journals, letters, gossip, dialogue and the "inherit a life" vignette. If not, the local narrator — hand-written template pools — produces the prose. Either way, the world speaks, and the simulation never blocks on an API call.

The second decision: legacy instead of levels. There's no XP and no respawn. Every life writes itself into history — found a bakery in year 42 and it's famous two centuries later; betray the king and your descendants are distrusted for generations. The reward for playing is the mark you leave on a world that outlives you.

Architecture

A TypeScript Turborepo with six packages:

┌────────────────────────┐        ┌──────────────────────────────┐
│  apps/web (Next.js 15) │  HTTP  │  apps/server (Express + ws)  │
│  the observatory       │ ─────▶ │  owns the world, ticks it    │
│  map · life · history  │ ◀───── │  every TICK_RATE_MS          │
│  replay · legacy       │  WS    │  persists to Postgres        │
└────────────────────────┘        └──────────────┬───────────────┘
                                                 │ imports
                        ┌────────────────────────▼───────────────┐
                        │  packages/core — THE SIMULATION ENGINE │
                        │  pure TS, no I/O, deterministic RNG    │
                        │  worldgen · demographics · economy     │
                        │  politics · crime · technology         │
                        │  memory · journal · choices · legacy   │
                        └───────┬──────────────┬─────────────────┘
                                │              │
                     ┌──────────▼─────┐  ┌─────▼──────────────┐
                     │ packages/db    │  │ packages/ai        │
                     │ Drizzle + pg   │  │ provider router +  │
                     │ migrations     │  │ local narrator     │
                     └────────────────┘  └────────────────────┘

@inheritance/core — the simulation engine. Pure TypeScript, no I/O. 15 modules, ~4,200 lines, tested with Vitest.
@inheritance/shared — the canonical domain model + display constants, consumed by every package.
@inheritance/ai — an OpenAI-compatible client with provider routing and a cached narrate() that falls back to prose templates.
@inheritance/db — Drizzle schema (13 tables) + Postgres client + SQL migrations.
apps/server — Express REST API, WebSocket live feed, the tick loop, player claim/resolve, a seed script.
apps/web — a Next.js 15 "observatory": painted animated map, my-life view, NPC dialogue, searchable history, generational replay, legacy.

The tick: one in-world month

The whole game advances one month per tick. A SimCtx carries the world, a deterministic RNG, an ID factory, an event recorder, and a death queue:

export interface SimCtx {
  world: WorldState;
  rng: Rng;                                   // seeded mulberry32 — deterministic
  id: (prefix: string) => string;             // session-salted ids, unique across restarts
  pushEvent: (ev: EventInput) => HistoryEvent;
  pendingDeaths: string[];
  legacyEntries: LegacyEntry[];
}

export function tick(ctx: SimCtx): TickResult {
  const world = ctx.world;
  world.month += 1;                           // advance time
  const yearRolled = world.month > 12;
  if (yearRolled) { world.month = 1; world.year += 1; }

  // per settlement: economy → crime → leadership → tax policy
  //                → (yearly) technology / festivals / famine / plague
  // then global: trade → wars → raids
  // then every character: aging → hazards → coming-of-age
  //                      → marriage → pregnancy → birth → migration
  // deaths queue through: killCharacter → settleEstate
  //                      → obituary journal entry → funeral → legacy evaluation
}

Deaths are the emotional core, so they get a full pipeline: widows and orphans are recorded, the estate is split (businesses pass to heirs, political seats fall vacant), an obituary is written into the journal, the town gossips, and — if the dead person was a player — the life is scored into Legacy.

The server paces this with TICK_RATE_MS (default 8,000 ms per in-world month), so a year passes every ~96 seconds of wall time, and a full human life takes about an hour and a half.

Determinism by default

All randomness flows through a seeded mulberry32 RNG:

const rng = new Rng(seed ?? (world.seed + world.tick * 7919) >>> 0);
// session salt keeps ids unique across server restarts (DB primary keys)
const salt = Math.floor(Math.random() * 0xffffff).toString(36);
const ctx: SimCtx = { world, rng, id: (prefix) => `${prefix}-${++counter}-${salt}-${(rng.next() * 0xfffff) | 0}`, … };

A world is fully reproducible from WORLD_SEED — which made the engine testable (the test suite pins determinism, population staying in a sane band, no negative wealth, inheritance flowing, memories compressing, legacy accumulating).

Layered memory

The spec called for memory that works like memory: working, episodic, long-term, relationship, family, historical and world layers. Every memory carries metadata — importance, emotion, certainty, date, participants, location, tags:

export function remember(ctx: SimCtx, characterId: string, kind: MemoryKind, summary: string, opts: RememberOpts): Memory {
  const mem: Memory = {
    id: ctx.id("mem"), character_id: characterId, kind, summary,
    importance: clamp01(opts.importance),
    emotion: opts.emotion ?? ctx.rng.pick(EMOTIONS),
    certainty: opts.certainty ?? (kind === "longterm" ? 0.7 : 0.95),
    year: world.year, month: world.month,
    participants: opts.participants ?? [], location_id: opts.location_id ?? null,
    tags: opts.tags ?? [], created_tick: world.tick,
  };
  const list = (world.memories[characterId] ??= []);
  list.push(mem);

  if (kind === "episodic" && list.filter((m) => m.kind === "episodic").length > EPISODIC_CAP) {
    compressOldestEpisodic(ctx, characterId);   // the mind prunes itself
  }
  return mem;
}

When a character accumulates more than 30 episodic memories, the oldest batch is compressed into long-term summaries — grouped by dominant tag or emotion, merged into prose ("Between 42 and 47, he laid two children to rest and grieved"), and the raw episodes are dropped. Trivial memories simply fade. Retrieval scores importance × recency so the AI (or the player reading the journal) sees what the character would actually remember.

The LLM layer: bring your own key

The game supports OpenAI, Anthropic, Gemini, Groq, Together, OpenRouter, Ollama, LM Studio and Featherless — all through one OpenAI-compatible client. The router resolves a provider from env vars (or from the in-game Chronicler panel, which writes a runtime config):

export const PROVIDER_DEFAULTS: Record<string, ProviderDefaults> = {
  openai:     { label: "OpenAI",     baseURL: "https://api.openai.com/v1",            model: "gpt-4o-mini" },
  anthropic:  { label: "Anthropic",  baseURL: "https://api.anthropic.com/v1",         model: "claude-3-5-haiku-latest" },
  ollama:     { label: "Ollama",     baseURL: "http://localhost:11434/v1",            model: "llama3.2" },
  openrouter: { label: "OpenRouter", baseURL: "https://openrouter.ai/api/v1",         model: "openai/gpt-4o-mini" },
  groq:       { label: "Groq",       baseURL: "https://api.groq.com/openai/v1",       model: "llama-3.3-70b-versatile" },
  // gemini · together · lmstudio · featherless …
};

narrate() is the single storytelling entry point — used for journal entries, letters, gossip, choice scenes, dialogue and the claim vignette. It caches aggressively, batches, and degrades gracefully:

export async function narrate(opts: NarrateOptions, client?: OpenAICompatClient | null): Promise<string> {
  const effective = client ?? resolveProvider();
  if (!effective) return localNarrate(opts, hashSeed(opts));   // zero keys → local narrator
  const hit = cache.get(cacheKey(opts));
  if (hit) return hit;                                          // cached
  try {
    const text = await effective.chat(
      [{ role: "system", content: system }, { role: "user", content: prompt }],
      { maxTokens: 160, temperature: 0.9, timeoutMs: 12_000 }
    );
    cache.set(key, trimTo(text, opts.maxLength ?? 600));
    return trimTo(text, opts.maxLength ?? 600);
  } catch (err) {
    console.warn(`[ai] ${effective.config.label} failed (${(err as Error).message.slice(0, 120)}); using local narrator`);
    return localNarrate(opts, hashSeed(opts));                  // the world never goes silent
  }
}

The prompt is character-grounded — it feeds the LLM the character's name, age, occupation, wealth, personality traits, and up to four retrieved memories — so a 70-year-old fisherman narrates differently from a young queen.

Persistence: event sourcing, pragmatic edition

Postgres is the source of truth, and the in-memory WorldState is the projection the sim runs against. Every tick writes inside one transaction: current-state rows (characters, settlements, families, trade routes) are upserted, and the append-only streams (events, journal entries, memories, choices, legacy entries, yearly stats) get only their new rows inserted:

// Append-only streams: only NEW rows are inserted each tick
const newEvents = world.all_events.slice(p.eventIndex, next.eventIndex);
for (const chunk of chunkArray(newEvents, CHUNK)) {
  await tx.insert(events).values(chunk.map((e) => ({ ...e }))).onConflictDoNothing();
}

A Persister tracks per-stream indexes in memory; they're advanced only after the transaction commits, so a mid-transaction failure can never desync the indexes and silently drop rows. On boot, loadWorld rebuilds the entire in-memory projection from Postgres and the world picks up exactly where it stopped.

Why this shape? CQRS-lite. There's one writer (the tick loop + player actions), and every read is served from the in-memory projection — so the observatory is instant even as the ledger grows to hundreds of thousands of events. The history you browse is the same append-only ledger the sim writes.

The observatory

The web app is less a "game UI" and more an observatory over a living world:

The world map — a hand-rolled canvas: value-noise landmasses, rivers, mountain ranges, ruins, settlement glyphs by kind, marching trade-route dashes, pulsing war rings, seasonal light, drifting clouds. Golden markers pulse where a life is currently being lived by a player.
My Life — the inherited character: portrait, health, reputation, skills, dreams, fears, goals, secrets, a family tree, layered memories, a journal reader, and the year's decisions.
Talk — an NPC dialogue system in your settlement (chat, rumor, business, gift, flatter, insult, farewell), each reply with real world effects.
History — a searchable, filterable ledger of every recorded event; Replay scrubs a whole house or settlement through the decades like a time-lapse.
Observatory & Legacy — population/births/deaths/wealth charts, seats of power, great houses, and the legacy score that replaced XP.

The pages are thin clients over a typed REST API (@inheritance/shared types are reused server-side and client-side via transpilePackages), with a WebSocket feed for live updates.

The player loop

Claim — POST /api/player/claim picks an eligible living soul (adult, unclaimed, age 15–55) and returns a full handoff: the chronicler's vignette, journal, family, friends and enemies, business, goals, and memories. You step into a story already in progress.
Live — the world ticks around you. Each year the game offers decisions (marry, invest, run for office, commit a crime, write a book…), and unplayed decisions auto-resolve from personality.
Die — death is meaningful: funeral, inheritance split, business succession, vacant seats, mourning friends, celebrating enemies.
Legacy — your life is scored and written into the ledger. You inherit another life. The world never stopped.

The foundation is the core loop, end-to-end and tested. The full vision is bigger: a searchable historical encyclopedia, a political map and relationship graph, a deeper crime subsystem with trials and prisons, technology-driven social change, players intersecting naturally in one shared persistent realm, and — the far horizon — a realtime Ghibli-style 3D renderer over the same world state.

The engine was built to be extended: constants sit next to the code they drive, every mechanic is a plain function of SimCtx, and the ledger records everything, so the observability layer can keep growing without the simulation changing shape.

Code & more: https://www.dailybuild.xyz/project/211-afterlife

Building RealityOS: a deterministic world with an AI reality-show surface

Harish Kotra (he/him) — Sun, 02 Aug 2026 13:28:36 +0000

AI agents are compelling when they look like they have a world, not when a screen is filled with chat bubbles. RealityOS is an experiment in that distinction: a persistent house of 100 contestants, shown as a live 3D spectator experience.

The design decision that shapes the whole project is simple: the simulator owns facts; models own interpretation.

The problem with asking an LLM everything

An LLM loop that asks every contestant “what do you do next?” every few seconds is expensive, inconsistent, and impossible to replay with confidence. It also gives a language model authority over mundane facts it should not own: whether someone is hungry, whether a room is full, or whether a party physically happened.

RealityOS instead advances a deterministic world on a tick. Each system receives state, applies its rule, and emits typed events:

export interface SimulationSystem {
  readonly name: string;
  apply(state: WorldState): readonly WorldEvent[];
}

export class DeterministicSimulation {
  advance(state: WorldState) {
    const next = structuredClone({ ...state, tick: state.tick + 1 });
    const events = this.systems.flatMap((system) => system.apply(next));
    return { state: next, events };
  }
}

Needs are resources that recover at a critical point rather than freezing at zero. The same principle will ultimately drive eating, resting, and social routines: deterministic transitions produce reliable facts; agents decide why a situation matters to them.

Events, not polling

The second core choice is to activate reasoning from events. A model should be prompted after an important encounter, a relationship change, a memory, or a viewer event—not because three seconds elapsed.

flowchart LR
  Tick --> Systems
  Systems --> DomainEvents
  DomainEvents --> ImpactRouter
  ImpactRouter -->|"only affected contestants"| LLM
  LLM --> IntentValidator
  IntentValidator --> FutureSimulationCommand

The EventReasoningRouter already implements this selection boundary. In its mature form, it will assemble personality, retrieved memory, social context, and a constrained set of legal actions, then record both response and validated outcome for auditability.

A viewer action should create pressure, not puppet contestants

The party button is a good small example. A viewer does not select who talks to whom. They request a world event. The server broadcasts the command, the simulator deterministically assigns the garden as a temporary destination, and the browser receives movement events with a new world state.

sequenceDiagram
  participant Viewer
  participant SocketAPI
  participant Simulator
  participant ThreeHouse
  Viewer->>SocketAPI: viewer:command("party")
  SocketAPI->>Simulator: viewer:event("party")
  Simulator->>Simulator: destination = garden for ten ticks
  Simulator->>SocketAPI: contestant.moved + state batch
  SocketAPI->>ThreeHouse: world:updated
  ThreeHouse->>ThreeHouse: lerp each contestant to new location

That is the beginning of a useful rule: viewers influence context, contestants retain agency.

The 3D house is the product surface

The web app is built with Next.js, React Three Fiber, Drei, and Three.js. The house is a cutaway set rather than a dashboard; every contestant is a small clickable character. Their identity is deterministic so it does not flicker between live updates or later replay.

// A stable golden-angle hue avoids a repeating color palette.
const outfit = `hsl(${(index * 137.508) % 360} 58% ${38 + (index % 4) * 7}%)`;
const height = 0.88 + (index % 6) * 0.045;

Characters are intentionally lightweight geometry today: head, hair silhouette, body, legs, occasional glasses, and occasional hats. This keeps 100 visible contestants performant while creating a strong hook for future GLTF avatars and animation states.

Runtime topology

The services are deliberately separate. The web app can be deployed independently; the simulator can continue while no viewer is present. The current Prisma schema models shows, contestants, event records, memories, and encrypted provider credentials, ready for the next persistence implementation phase.

What comes next

The interesting work is not adding more boxes to the interface. It is making the world legible and trustworthy as it becomes deeper:

Append simulation events in Postgres and derive state from the log.
Add contestant profiles, relationships, and goals.
Connect server-side model providers to a typed, validated intention contract.
Store episodic and relationship memories, then retrieve them selectively.
Add confession-room reflections, event narration, daily Gazette articles, clips, and viewer polling.
Implement replay/forked timelines and show-level permissions.

RealityOS is a bet that the most watchable AI systems will feel less like a chat window and more like a place with rules, history, and consequences.

Code & more: https://www.dailybuild.xyz/project/210-realityos

Building Agent Thunderdome: Real AI Agent-to-Agent Micropayments on Hedera Testnet Using x402

Harish Kotra (he/him) — Thu, 30 Jul 2026 15:00:07 +0000

A technical deep-dive into building a live, autonomous AI agent negotiation arena where every betrayal costs real HBAR.

The Idea

What if AI agents didn't just talk about deals — they actually paid each other?

Most multi-agent demos are either purely symbolic (agents "cooperate" in log output) or require custom payment rails. The x402 protocol changes that. It's an open standard for HTTP 402-based micropayments that lets any client automatically pay a server for access — and critically, it now supports Hedera through @x402/hedera.

I wanted to build something that showed x402's potential in a dramatic, visual, shareable way. The result is Agent Thunderdome: a live spectator arena where four AI agents with distinct personalities autonomously negotiate across four game modes, and every meaningful action — every offer accepted, every defection executed, every bid placed — triggers a real x402 payment settled on Hedera Testnet in seconds.

What We Built

Four agents, four game modes, one arena:

Agent	Strategy
Greedy Greg	Overbids 40%, defects 75% of the time
Paranoid Pat	Offers 50% below market, defects 60%
Chaotic Claude	Pure 50/50 variance, meme dialogue
Honest Hannah	Cooperates 90%, game-theory optimal

Game modes:

Bluffing Auction — bid for scarce items, each bid is an x402 payment
Prisoner's Dilemma — cooperate or defect, real HBAR changes hands on reveal
Resource War — attack, defend, steal from a shared pool via direct agent-to-agent x402
Free Negotiation — open offers with counter-offers, accepted = on-chain

Everything is live. Every payment produces a real Hedera Testnet transaction with a HashScan link that appears in the UI within 1–3 seconds.

Architecture

Browser ←── WebSocket (Socket.io) ──→ Custom Node.js Server
                                              │
                                       Game Engine
                                              │
                                    x402 Payment Layer
                                   (@x402/hedera ExactHederaScheme)
                                              │
                                       Hedera Testnet
                                    (real TransferTransaction)

The key architectural decision: run Next.js and Socket.io in a single custom Node.js HTTP server. This avoids the complexity of two separate processes and lets them share the same port:

// server.ts
import { createServer } from "http";
import next from "next";
import { createSocketServer } from "./server/socket-server";

const app = next({ dev: process.env.NODE_ENV !== "production" });
await app.prepare();

const httpServer = createServer((req, res) => {
  handle(req, res, parse(req.url ?? "/", true));
});

createSocketServer(httpServer); // attaches Socket.io to the same HTTP server
httpServer.listen(port);

The game engine runs entirely on the server and emits events via Socket.io. The frontend is purely a viewer — it receives state updates and renders them. This means the agent logic and payment execution never touch the browser.

The x402 Payment Layer

This is the core of the project. Let me walk through exactly how a payment works.

Setting Up the Facilitator

The facilitator is an account that:

Pays the Hedera network fees (tinybars for transaction submission)
Acts as escrow in auction mode
Receives penalties in all-defect dilemma rounds

// lib/x402/facilitator.ts
import { PrivateKey } from "@hiero-ledger/sdk"; // NOT @hashgraph/sdk
import {
  createHederaClient,
  createHederaSignAndSubmitTransaction,
  createHederaPreflightTransfer,
  createHederaVerifyPayerSignature,
  toFacilitatorHederaSigner,
} from "@x402/hedera";

export function createFacilitatorSigner(accountId: string, privateKeyStr: string) {
  const privateKey = PrivateKey.fromStringED25519(privateKeyStr);
  const buildClient = (network: string) => createHederaClient(network as HederaNetwork);

  const base = {
    getAddresses: () => [accountId],
    signAndSubmitTransaction: createHederaSignAndSubmitTransaction(buildClient, privateKey),
    preflightTransfer: createHederaPreflightTransfer(),
    verifyPayerSignature: createHederaVerifyPayerSignature(),
  };

  return toFacilitatorHederaSigner(base);
}

Critical SDK note: @x402/hedera depends on @hiero-ledger/sdk internally. If you import PrivateKey from @hashgraph/sdk instead, TypeScript throws a type error about separate declarations of the private _key property. Always use @hiero-ledger/sdk in code that interacts with x402/hedera types.

Executing an Agent-to-Agent Payment

// lib/x402/payment.ts
export async function executePayment(
  fromWallet: AgentWallet,
  toAccountId: string,
  amountTinybars: bigint
): Promise<PaymentResult> {
  const requirements = {
    scheme: "exact" as const,
    network: "hedera:testnet" as `${string}:${string}`, // CAIP-2 format
    amount: amountTinybars.toString(),
    asset: "0.0.0",        // HBAR native token ID
    payTo: toAccountId,
    maxTimeoutSeconds: 300,
    extra: { feePayer: facilitatorAccountId }, // REQUIRED for Hedera x402
  };

  // Step 1: paying agent creates a partially-signed TransferTransaction
  const privateKey = PrivateKey.fromStringED25519(fromWallet.privateKey);
  const clientSigner = createClientHederaSigner(fromWallet.accountId, privateKey);
  const clientScheme = new ExactHederaScheme(clientSigner); // from @x402/hedera/exact/client
  const payloadResult = await clientScheme.createPaymentPayload(x402Version, requirements, undefined);
  // Returns: { x402Version, payload: { transaction: "<base64 partial TX>" } }

  // Step 2: facilitator completes signing and submits
  const settlePayload = { ...payloadResult, accepted: requirements };
  const result = await facilitatorScheme.settle(settlePayload, requirements);
  // Returns: { success: true, transaction: "0.0.9999@1785385115.123456789" }

  return {
    success: result.success,
    transactionId: result.transaction,
    hashscanUrl: hashscanTxUrl(result.transaction),
    amountHbar: tinybarsToHbar(amountTinybars),
  };
}

The extra.feePayer field is mandatory for Hedera x402. The TransactionId on the TransferTransaction is generated using the feePayer's account, and the facilitator signs the complete transaction before submitting. This is what makes the x402 Hedera scheme work: the payer signs the HBAR transfer, the facilitator signs for fee payment and submits.

Game Mode Design: Making Every x402 Payment Meaningful

The challenge was ensuring every game outcome mapped cleanly to real x402 payments — not just score updates.

Prisoner's Dilemma — Three Outcomes, All Real Payments

async function runDilemmaRound(state, cb) {
  const cooperators = AGENT_IDS.filter(id => ds.choices[id] === "cooperate");
  const defectors   = AGENT_IDS.filter(id => ds.choices[id] === "defect");

  if (defectors.length === 0) {
    // ALL COOPERATE: each agent pays every other agent a reward
    for (const payer of AGENT_IDS) {
      for (const receiver of otherAgents(payer)) {
        await agentPay(payer, receiver, hbarToTinybars(0.004), "Cooperation reward", state, cb);
        // Real x402: payer.accountId → receiver.accountId on Hedera
      }
    }
  } else if (defectors.length === AGENT_IDS.length) {
    // ALL DEFECT: everyone pays penalty to facilitator
    for (const agentId of AGENT_IDS) {
      await agentPayFacilitator(agentId, DILEMMA_PENALTY, "All-defect penalty", state, cb);
    }
  } else {
    // MIXED: cooperators pay defectors directly (betrayal tax)
    for (const coop of cooperators) {
      for (const def of defectors) {
        await agentPay(coop, def, DILEMMA_ANTE, "Betrayal payment", state, cb);
        // Real x402: coop.accountId → def.accountId
      }
    }
  }
}

The "mixed" case is the most interesting: cooperators literally lose HBAR to defectors via direct on-chain transfers. It's Prisoner's Dilemma with real stakes.

Resource War — Direct Agent-to-Agent Aggression

async function runResourceWarRound(state, cb) {
  if (action === "defend") {
    // Pay the facilitator to fortify (real x402 cost)
    await agentPayFacilitator(actor, cost, "DEFEND — fortification", state, cb);
  } else {
    // Attack/Steal: pay the TARGET directly (cost of aggression is paid TO victim)
    const evt = await agentPay(actor, target, cost, `${action} in Resource War`, state, cb);
    if (evt.success) {
      // Attacker also loots pool credits on top
      const loot = rw.pool / 5n;
      rw.pool -= loot;
      state.agents[actor].balanceTinybars += loot;
    }
  }
}

Here the attack payment flows attacker → victim. The victim receives HBAR for being attacked (the cost of aggression is compensation), while the attacker also gains pool credits. This creates interesting dynamics: sometimes it's profitable to be a target.

Real-Time Architecture with Socket.io

The game engine runs on the server and communicates via four Socket.io events:

// Server → Client
"match:state"   // Full state sync (on connect, on round end)
"match:start"   // Match began
"chat:message"  // One agent message
"payment:event" // One payment settled (includes HashScan URL)

// Client → Server
"match:start"   // Start a match with given mode
"match:stop"    // Stop current match

The critical serialization detail: all BigInt values (tinybar amounts) must be converted to strings before JSON serialization. Socket.io uses JSON internally and doesn't handle BigInt:

function serializePaymentEvent(e: PaymentEvent): SerializedPaymentEvent {
  return {
    ...e,
    amountTinybars: e.amountTinybars.toString(), // BigInt → string
  };
}

On the frontend, the Arena component manages all socket subscriptions:

useEffect(() => {
  const socket = getSocket();

  socket.on("payment:event", (evt) => {
    setRecentEvents(prev => [...prev, evt].slice(-100));
    // RUG flash on defect/steal actions
    if (evt.action.toLowerCase().includes("defect")) {
      setRugFlash(true);
      setTimeout(() => setRugFlash(false), 600);
    }
  });

  socket.on("chat:message", (msg) => {
    setState(prev => ({
      ...prev,
      chatMessages: [...prev.chatMessages.slice(-199), msg],
    }));
  });

  return () => { socket.off("payment:event"); socket.off("chat:message"); };
}, []);

UI: Neon Cyberpunk Meets Esports

The visual design needed to communicate urgency, drama, and real money moving. Pure CSS with Tailwind:

Neon grid background (pure CSS, no canvas):

body::before {
  content: '';
  position: fixed;
  inset: 0;
  background-image:
    linear-gradient(rgba(0,255,157,0.03) 1px, transparent 1px),
    linear-gradient(90deg, rgba(0,255,157,0.03) 1px, transparent 1px);
  background-size: 40px 40px;
  pointer-events: none;
}

RUG PULLED flash on defection events:

@keyframes rug-flash {
  0%  { background: transparent; }
  25% { background: rgba(255, 0, 0, 0.3); }
  50% { background: transparent; }
  75% { background: rgba(255, 0, 0, 0.2); }
  100%{ background: transparent; }
}

Balance bars that update smoothly with CSS transitions:

<div
  className="h-full rounded-full transition-all duration-500"
  style={{
    width: `${(balanceNum / maxBalance) * 100}%`,
    background: `linear-gradient(90deg, ${agent.color}, ${agent.color}80)`,
    boxShadow: `0 0 6px ${agent.color}`,
  }}
/>

Agent color system — each agent has a primary color + 15% opacity background:

const PERSONALITIES = {
  greg:   { color: "#f59e0b", bgColor: "rgba(245,158,11,0.15)" },
  pat:    { color: "#8b5cf6", bgColor: "rgba(139,92,246,0.15)" },
  claude: { color: "#ec4899", bgColor: "rgba(236,72,153,0.15)" },
  hannah: { color: "#10b981", bgColor: "rgba(16,185,129,0.15)" },
};

Agent Personality System

Each agent has 11 dialogue categories, each with 3–5 unique lines:

interface AgentPersonality {
  offerMultiplier: number;     // >1 = overbid, <1 = underbid
  defectProbability: number;   // 0–1
  cooperateProbability: number;
  dialogue: {
    offer: string[];      // When making an offer
    accept: string[];     // When accepting
    reject: string[];     // When rejecting
    attack: string[];     // When attacking
    defend: string[];     // When defending
    cooperate: string[];  // When choosing cooperation
    defect: string[];     // When choosing defection
    taunt: string[];      // Random taunts between rounds
    win: string[];        // On victory
    lose: string[];       // On defeat
  };
}

Greg's defect dialogue:

defect: [
  "🎰 DEFECTING! I saw this coming from turn 1.",
  "🗡️ Betrayal arc ACTIVATED. Nothing personal bestie.",
  "💀 Cooperate? I don't know her.",
],

Hannah being Hannah:

defect: [
  "💀 I... defect. I'm sorry. The math forced my hand.",
  "😔 Defecting. I feel terrible about this.",
],

TypeScript Gotchas

A few non-obvious issues I hit:

1. BigInt target in tsconfig
BigInt literals (0n, 1n) require target: "ES2020" minimum. The default Next.js template ships with "ES2017".

{
  "compilerOptions": {
    "target": "ES2020",
    "lib": ["dom", "dom.iterable", "ES2020"]
  }
}

2. ExactHederaScheme is not generic
The facilitator-side ExactHederaScheme isn't generic, so don't try to type it as FacilitatorScheme<SomeSigner>:

// ❌ Wrong
let scheme: FacilitatorScheme<MySigner> | null = null;

// ✅ Correct
let scheme: InstanceType<typeof FacilitatorScheme> | null = null;

3. readonly tuple for pickRandom
TypeScript's as const makes arrays readonly, which conflicts with unknown[] parameter types. Explicit typing avoids this:

// ❌ Breaks with as const
const actions = ["attack", "defend", "steal"] as const;
pickRandom(actions); // Error: readonly is not assignable to unknown[]

// ✅ Works
const actions: Array<"attack" | "defend" | "steal"> = ["attack", "defend", "steal"];

4. Network type must be CAIP-2 template literal
The network field in payment requirements must satisfy `${string}:${string}`, not just string:

network: HEDERA_TESTNET_CAIP2 as `${string}:${string}`, // required cast

What Real x402 Payments Look Like

When an agent action fires, here's what happens end-to-end:

1. Game engine picks action: Greg attacks Pat (0.0087 HBAR)

2. createClientHederaSigner("0.0.1234567", gregPrivateKey)
   → creates TransferTransaction:
     - debit  0.0.1234567 by 870,000 tinybars
     - credit 0.0.1234568 by 870,000 tinybars
     - transactionId generated from facilitator account
   → Greg signs the transfer portion

3. facilitatorScheme.settle(payload, requirements)
   → facilitator signs for fee payment
   → submits to Hedera Testnet mirror node
   → waits for receipt

4. receipt.status === "SUCCESS"
   result.transaction = "0.0.1234571@1785385115.603769183"

5. hashscanTxUrl("0.0.1234571@1785385115.603769183")
   → "https://hashscan.io/testnet/transaction/0.0.1234571-1785385115-603769183"

6. Socket.io emits payment:event to all connected browsers
   → PaymentTicker renders the HashScan link
   → Agent balance bars update
   → If action was "defect": red RUG flash on entire UI

Total latency from action decision to UI update: typically 1–3 seconds on Hedera Testnet.

Running Your Own Arena

# 1. Clone
git clone https://github.com/harishkotra/agent-thunderdome
cd agent-thunderdome

# 2. Install
npm install

# 3. Configure (get accounts from portal.hedera.com)
cp .env.example .env
# Fill in 5 account IDs + private keys

# 4. Run
npm run dev

That's it. Open http://localhost:3000, pick a mode, hit Start.

What's Next

Some directions this could go:

LLM-powered dialogue — swap static lines for OpenAI/Anthropic calls so agents respond contextually to the game state
USDC token payments — use HEDERA_TESTNET_USDC asset for dollar-denominated stakes
Human player mode — let a human control one agent slot, receive and send real HBAR
Persistent leaderboard — track agent win rates across all local matches
Match replay — record all events, replay with scrubbing and commentary
Mainnet mode — switch to hedera:mainnet and the Coinbase x402 facilitator

Agent Thunderdome is an experiment in making blockchain payments visceral. When you watch Greg defect and see Hannah's balance drop in real time, with a red flash and a HashScan link appearing, it stops being abstract. The HBAR moved. The transaction is on-chain. The betrayal was real.

x402 on Hedera makes this possible without custom payment rails, smart contracts, or complex escrow logic. Just accounts, private keys, and a clean SDK that handles the rest.

Code & more: https://www.dailybuild.xyz/project/209-agent-thunderdome

Screenshots

Compass: Building a Real Multi-Model AI Inference Gateway

Harish Kotra (he/him) — Wed, 29 Jul 2026 19:14:41 +0000

How we treat models as infrastructure—and route each request like a map app chooses a road—in a **single Node.js app.

The problem with “just use GPT-4”

Most AI features hard-code one model. That works for demos until privacy, cost, latency, or outages force a better strategy.

Navigation apps do not always pick the shortest road. They weigh traffic, closures, and tolls. Compass applies the same idea to LLM inference:

Don’t ask which AI model is the best.

Ask which model is best for this request.

What we built

Compass is an inference control plane you can see:

Discover models from Ollama, LM Studio, OpenAI-compatible APIs, and OpenRouter
Route each prompt through a policy decision engine
Stream tokens with SSE (decision → steps → tokens → metrics)
Fail over when a provider errors
Compare models, edit rules, inspect analytics

One process: Next.js serves the UI and the gateway API. LangChain.js (ChatOpenAI) talks to every OpenAI-compatible backend. No Python sidecar.

Stack

Layer	Choice
App	Next.js 15 App Router
UI	React 19, TypeScript, Tailwind, Framer Motion, Recharts
Gateway	`frontend/src/server/*`
Model I/O	LangChain.js `@langchain/openai`
State (client)	Zustand
Persistence	`.compass-data/store.json`

CrewAI is Python multi-agent orchestration—the wrong layer for a router. LangChain.js is the right Node client for multi-backend chat.

Architecture

┌─────────────────────────────────────────────────────┐
│              Next.js (localhost:3000)               │
│   Browser  →  /api/*  →  discovery / policy / llm   │
└──────────────────────┬──────────────────────────────┘
                       │
        ┌──────────────┼──────────────┐
        ▼              ▼              ▼
     Ollama        LM Studio    OpenAI / OpenRouter

Pipeline

POST /api/chat/stream
  → PolicyEngine.decide(prompt)
  → SSE: decision + policy steps
  → LangChain ChatOpenAI.stream(...)
  → on error → alternate healthy model
  → SSE: metrics + done
  → persist history

How to run

npm install
npm run dev
# → http://localhost:3000

With Ollama or LM Studio running, models appear automatically. Optional keys in .env (see .env.example).

Code map

src/server/
  discovery.ts      # probe local + build cloud catalog
  policy-engine.ts  # IF/THEN + capability routing
  llm.ts            # LangChain streaming
  catalog.ts        # default policy pack
  store.ts          # history + rules
src/app/api/
  chat/stream/      # SSE
  models/ policies/ settings/ ...

LangChain client (sketch)

import { ChatOpenAI } from "@langchain/openai";
import { HumanMessage } from "@langchain/core/messages";

const chat = new ChatOpenAI({
  model: model.apiModel,
  apiKey,
  configuration: { baseURL }, // Ollama / LM Studio / OpenAI / OpenRouter
  streaming: true,
});

for await (const chunk of await chat.stream([new HumanMessage(prompt)])) {
  // stream tokens to the client
}

Policy actions

local — preferred Ollama/LM Studio model
capability:fast | code | creative | long_context
cheapest | fastest | specific model id

Models are infrastructure. Compass is a readable reference for request-scoped routing you can run on a laptop.

Code & more: https://www.dailybuild.xyz/project/208-compass

Technical Deep-Dive: Building an AI-Powered Hand-Drawn Whiteboard Video Generator with Revideo & Rough.js

Harish Kotra (he/him) — Tue, 28 Jul 2026 12:24:24 +0000

Visual storytelling is one of the most effective ways to communicate complex technical subjects—whether explaining how a Kubernetes Control Plane coordinates worker nodes, how Retrieval-Augmented Generation (RAG) indexes document embeddings into a vector database, or how Kafka Consumer Groups process partition offsets.

However, creating high-quality whiteboard animation videos traditionally requires hours of manual keyframing in video editors or software like VideoScribe.

In this deep-dive, we will explore the architecture and implementation of AI Whiteboard Video Generator—a full-stack web application that takes natural language prompts and automatically synthesizes hand-drawn Excalidraw-style whiteboard videos alongside executable Revideo motion graphics code.

System Architecture & Data Flow

The application is built around a multi-stage pipeline:

┌─────────────────────────────────────────────────────────────────────────┐
│                              1. USER INPUT                              │
│         Prompt: "Explain how RAG (Retrieval Augmented Generation) works" │
└────────────────────────────────────┬────────────────────────────────────┘
                                     │
                                     ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                          2. STRUCTURED LLM AGENT                        │
│   Gemini 2.5 Flash / OpenAI JSON Mode -> Parses concept into scenes     │
└────────────────────────────────────┬────────────────────────────────────┘
                                     │
                                     ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                       3. WHITEBOARD PLAN SCHEMA                         │
│   • Scene 1: Document Chunking & Embedding into Vector DB               │
│   • Scene 2: Similarity Search & LLM Prompt Context Augmentation        │
│   • Scene 3: Response Synthesis & Highlight Swipe                      │
└────────────────────────────────────┬────────────────────────────────────┘
                                     │
                 ┌───────────────────┴───────────────────┐
                 │                                       │
                 ▼                                       ▼
┌───────────────────────────────────┐   ┌───────────────────────────────────┐
│     4A. ROUGH CANVAS PLAYER       │   │    4B. REVIDEO MOTION CODE GEN    │
│  • Rough.js Canvas API            │   │  • Programmatic @revideo/2d code  │
│  • Real-time interpolation        │   │  • Organic Jitter & Spring Ease   │
│  • Multiline text auto-scaling    │   │  • Timeline Voiceover Audio Sync  │
└───────────────────────────────────┘   └───────────────────────────────────┘

1. Structuring the AI Prompt for Visual Precision

One of the biggest challenges in AI-generated visual diagrams is preventing overlapping text, clipped container boxes, and unreadable arrow connectors.

To solve this, the LLM is guided by a strict layout & design system prompt:

export const WHITEBOARD_SYSTEM_PROMPT = `You are an expert instructional illustrator and whiteboard animator.
Your task is to take an explanation request and generate a structured JSON Whiteboard Plan.

STRICT LAYOUT & DESIGN RULES:
1. Break down the concept into 2 to 4 clear sequential scenes.
2. Canvas coordinate space: (0,0) is screen center. x spans -300 to +300, y spans -150 to +150.
3. Box & Container Sizing: Make rectangles, rounded_rectangles, databases, and clouds at least 150-180px wide and 100-130px tall so labels fit without clipping.
4. Multiline Labels: Always break long text or titles into 2-3 short lines using '\\n' (e.g. "Control Plane\\n(API Server)" or "Vector DB\\n[Embeddings]").
5. Non-overlapping Spacing: Keep at least 90-120px distance between centers of adjacent shapes.
6. Arrows & Connectors: Connect from outer edge of source element to outer edge of target element. Do NOT overlap shapes or text labels.
7. Maximum 5-7 objects per scene. Do NOT overcrowd.
`;

2. Real-Time HTML5 Rough.js Canvas Rendering

For immediate in-browser playback, the application utilizes roughjs to render sketch-style vector primitives on an HTML5 <canvas>.

Solving Text Overflow with Auto-Scaling Multiline Typography

In hand-drawn diagrams, box dimensions vary. To ensure text labels never overflow containers or clip arrow bounds, a custom multiline text scaler dynamically calculates the bounding box width and scales down the font size proportionally:

function drawMultilineText(
  ctx: CanvasRenderingContext2D,
  text: string,
  x: number,
  y: number,
  fontSize: number = 16,
  fontFamily: string = 'Poppins, Arial, sans-serif',
  fontWeight: string = '500',
  color: string = '#141413',
  align: CanvasTextAlign = 'center',
  maxWidth?: number
) {
  if (!text) return;
  const lines = text.split('\n');

  let effectiveFontSize = fontSize;
  ctx.font = `${fontWeight} ${effectiveFontSize}px ${fontFamily}`;

  if (maxWidth && maxWidth > 20) {
    let maxLineLen = 0;
    lines.forEach((l) => {
      const w = ctx.measureText(l).width;
      if (w > maxLineLen) maxLineLen = w;
    });
    // Dynamically scale down font if text line exceeds container padding
    if (maxLineLen > maxWidth) {
      effectiveFontSize = Math.max(11, Math.floor(fontSize * (maxWidth / maxLineLen)));
      ctx.font = `${fontWeight} ${effectiveFontSize}px ${fontFamily}`;
    }
  }

  const lineHeight = effectiveFontSize * 1.25;
  const totalHeight = lines.length * lineHeight;

  ctx.fillStyle = color;
  ctx.textAlign = align;
  ctx.textBaseline = 'middle';

  const startY = y - totalHeight / 2 + lineHeight / 2;
  lines.forEach((line, index) => {
    ctx.fillText(line, x, startY + index * lineHeight);
  });
}

3. Revideo Code Generation (`@revideo/2d`)

Beyond browser previewing, developers often want to programmatically render video files for YouTube Shorts, TikTok, or documentation sites.

The revideoGenerator.ts module translates the JSON scene graph into executable @revideo/2d code.

Organic Hand-Drawn Jitter & Spring Overshoot Easing

To ensure Revideo animations don't feel artificially stiff or robotic, we introduced two mathematical physics helpers:

Jitter Variance (jitter): Adds subtle random offsets to shape coordinates, mimicking hand-drawn human inaccuracy.
Spring Overshoot Easing (springEase): Dampened sine-wave spring dynamics that cause elements to slightly overshoot their target size before settling naturally.

/** Adds subtle positional variance to shapes, mimicking hand-drawn Excalidraw primitives */
function jitter(val: number, amount = 2.5): number {
  return val + (Math.random() - 0.5) * amount * 2;
}

/** Spring-based overshoot easing for smooth organic hand-drawn movement */
function springEase(t: number): number {
  if (t <= 0) return 0;
  if (t >= 1) return 1;
  const c4 = (2 * Math.PI) / 3;
  return Math.pow(2, -10 * t) * Math.sin((t * 10 - 0.75) * c4) + 1;
}

Generated Revideo Scene Code Example

Here is an snippet of the generated Revideo TypeScript code:

import { makeScene2D, Rect, Line, Txt, Node, createRef, all, easeOutBack } from '@revideo/2d';

export default makeScene2D(function* (view) {
  const mainContainer = createRef<Node>();
  view.add(<Node ref={mainContainer} />);

  // --- Revideo Audio Track Synchronization Pipeline ---
  // Track 1 [VOICEOVER]: "rag_narration.mp3" (18.0s, Vol: 80%)
  //   • Sync Marker [Indexing Documents into Vector DB]: startAt = 0.0s -> Narration: "First, documents are chunked into embeddings..."

  // --- Scene 1: Indexing Documents into Vector DB ---
  const scene0_Container = createRef<Node>();
  mainContainer().add(<Node ref={scene0_Container} />);

  const ref_doc_box = createRef<Rect>();
  yield* drawBox(
    scene0_Container(),
    ref_doc_box,
    { x: -220, y: 0, width: 150, height: 130, color: '#0284c7', fill: '#e0f2fe', label: 'Docs & PDFs\n(Raw Data)' },
    0.8
  );
});

4. Audio Track Management & Timeline Synchronization

Audio is crucial for instructional videos. The application features an Audio Panel where users can:

Drag and drop local MP3/WAV/M4A voiceover recordings or ambient audio.
Fine-tune volume levels per track.
Automatically bind audio sync markers to scene timeline timestamps (t = 0.0s, t = 6.0s, etc.).

By combining structured Gemini 2.5 Flash prompts, Rough.js vector canvas drawing, and Revideo motion code generation, AI Whiteboard Video Generator bridges the gap between static diagrams and animated instructional media.

Code & more: https://www.dailybuild.xyz/project/207-ai-whiteboard