DEV Community: Prema Ananda

ReSpawning Intelligence: How I Plugged OpenClaw into a Minecraft World

Prema Ananda — Fri, 24 Apr 2026 07:30:46 +0000

This is a submission for the OpenClaw Challenge.

What I Built

I built ClawCraft-bot — a bridge application that gives OpenClaw an avatar inside a Minecraft world.

Instead of just chatting or processing text, OpenClaw can now perceive a three-dimensional environment, gather resources, craft tools, navigate complex terrain, and even defend players against hostile mobs in real time. The bot acts as an independent agent running through a local HTTP API, translating OpenClaw's high-level reasoning into precise in-game actions.

How I Used OpenClaw

OpenClaw serves as the "brain" of the entire operation, making strategic decisions, while ClawCraft-bot acts as the "nervous system."

The Tech Stack & Environment

Launcher: SKLauncher 3.2.18 (Offline mode)
Minecraft Version: Java Edition 1.21.11
Bridge API: Node.js + Express.js
Bot Engine: Mineflayer + pathfinder, pvp, collectblock

The system runs on a local Minecraft world. One important detail: after launching the game, you need to open the world to the network (Open to LAN) on port 25565 (default) so the Bridge API can connect the bot to your game session.

Architecture

The system is built around a simple principle: the LLM is the brain, the bot is the body. OpenClaw reasons and decides; ClawCraft-bot perceives and acts. They communicate through a thin HTTP layer, which means the agent never touches Mineflayer directly — and Mineflayer never needs to know anything about LLMs.

Five layers, one direction

The codebase is organized into five layers, each knowing only about the one below it:

SKILL.md          ← Layer 5: instructions OpenClaw reads to understand the API
bridge-api.js     ← Layer 4: Express HTTP server, the contract between LLM and bot
actions/          ← Layer 3: six modules split by responsibility
plugins.js        ← Layer 2: pathfinder, pvp, collectblock, tool
bot-core.js       ← Layer 1: Mineflayer lifecycle and auto-reconnect

This separation means you can swap out the LLM integration entirely — replace OpenClaw with any HTTP client — without touching a single line of game logic. Conversely, upgrading the Mineflayer version or adding a new plugin stays contained in Layers 1–2.

Layer 3 (actions/) is where most of the domain logic lives, split into focused modules: info for reading game state, navigation for movement, chat for communication, world for block interaction, combat for fighting and protection, and items for inventory and crafting. An index.js registry routes incoming API calls to the right module.

The bridge API

The HTTP API listens on 127.0.0.1:3001 — localhost only, by design. This isn't an oversight; it's a deliberate security boundary. An LLM that can issue /actions/attack or /actions/collect shouldn't be exposed to the network.

The API is split into two kinds of endpoints:

Read endpoints (GET): /status, /inventory, /nearby, /scan-blocks, /findblock — these return immediately and can be called at any time. OpenClaw uses them to build a picture of the world before deciding what to do next.
Action endpoints (POST): /actions/goto, /actions/collect, /actions/craft, etc. — these start a job and return a jobId immediately, without waiting for the action to complete.

Why a job queue?

This is the most important architectural decision in the project, and it's worth explaining explicitly.

Minecraft actions are not instantaneous. Navigating to a location takes several seconds. Mining a stack of wood takes longer. If a POST request blocked until the action finished, the LLM would be left hanging — and more importantly, a second command arriving mid-navigation would conflict with the first, causing pathfinder to fight itself.

The solution is a serial job queue: every action is enqueued and executed one at a time. A POST to /actions/collect returns immediately:

{ "jobId": "a3f9...", "status": "pending" }

OpenClaw then polls /jobs/a3f9... until the status becomes done or failed. While waiting, it's free to call read endpoints — checking health, scanning for threats, updating its world model. The queue prevents conflicts without requiring locks or complex concurrency primitives.

[

The diagram above shows the full request lifecycle: OpenClaw reads world state, decides on an action, posts it to the bridge, receives a jobId, and polls for completion while the bot executes in-game.

What SKILL.md does

The final layer is SKILL.md — a plain text file that serves as the API contract for the LLM. It describes every endpoint, its parameters, and the expected response shape. It also encodes behavioral rules that can't be enforced in code: things like "always put away your tool before eating" or "check /status before starting a long task."

Setup

1. Launch Minecraft

Use SKLauncher (or any other launcher) to start Minecraft Java Edition 1.21.11.
Load a world and select "Open to LAN" on port 25565.

2. Install ClawCraft-bot

git clone https://github.com/premananda108/ClawCraft-bot.git
cd ClawCraft-bot
npm install
# Edit .env if needed (specify the port from MC)
npm start

3. Configure OpenClaw

Install OpenClaw by following its official documentation.
Create a new Skill in OpenClaw. As the skill instructions, simply provide your agent with the contents of the SKILL.md file from this repository. It contains all the necessary behavior rules and API descriptions for the AI.

Intelligence & LLM Efficiency

One of the key features of the project is the use of a detailed SKILL.md file. This allowed me to:

Lower model requirements: Thanks to clear instructions and API descriptions in the SKILL file, the bot can be controlled even by inexpensive or local LLMs.
Optimize costs: Minecraft involves a very high number of "check-act" cycles. Using local models (via Ollama or similar tools) lets you run the bot for hours without burning through expensive API tokens.

Demo

premananda108 / ClawCraft-bot

OpenClaw-powered Minecraft bot that mines, crafts, navigates, and fights — all driven by LLM decisions through a local HTTP API.

ClawCraft-bot

Secure Minecraft bot with a high-level API for control via OpenClaw.

Quick Start

# 1. Installation
npm install

# 2. Setup (copy and edit)
cp .env.example .env
# Edit .env: MC_HOST, MC_PORT, MC_USERNAME

# 3. Run
npm start

API

Bridge API is available at http://127.0.0.1:3001 (default).

Read Data (GET)

Endpoint	Description
`/health`	Bridge status (always available)
`/status`	Health, food, position, gameMode
`/position`	Bot coordinates
`/inventory`	Items in inventory
`/nearby?radius=32`	Nearby entities (default radius 32)
`/scan-blocks?radius=8`	Scan nearby blocks (default radius 8)
`/findblock?name=oak_log&maxDistance=32`	Find specific block by name

Actions (POST)

Endpoint	Body	Description
`/actions/goto`	`{ x, y, z }`	Navigate to coordinates
`/actions/follow`	`{ player, distance? }`	Follow a player
`/actions/chat`	`{ message }`	Send message to global chat
`/actions/whisper`	`{ player, message }`	Send private message
`/actions/stop`	—	Stop everything (tasks and movement)
`/actions/dig`	`{ name }` or `{ x, y, z }`	Dig block (by name or coordinates)

…

View on GitHub

What I Learned

Building a bridge between an LLM and a real-time game engine turned out to be full of hidden pitfalls:

Visualization traps: I originally planned to use prismarine-viewer to stream a video feed. However, it turned out to work incorrectly with Minecraft Java 1.21.11. In the end, I decided to drop visualization from the final build in favor of control stability.
LLMs need strict feedback loops: Initially, the AI would try to eat food while holding a pickaxe. I had to explicitly write into SKILL.md that a tool must be put away before eating. Designing an API for AI is a balancing act between flexibility and hard rules.
Lifecycle chaos: Minecraft bots sometimes die. I learned that handling automatic respawns requires strict event decoupling — otherwise the system starts injecting multiple pathfinding plugins into the same bot instance, leading to massive memory leaks.

ClawCon Michigan

Unfortunately, I wasn't able to attend ClawCon Michigan this time around, but it's wonderful to see the OpenClaw community growing and building incredible things!

Battle of LLM Agents: WhiteHat vs BlueHat on OpenClaw

Prema Ananda — Sun, 19 Apr 2026 09:57:11 +0000

This is a submission for the OpenClaw Writing Challenge

In Part 1, I described how to turn an LLM into an autonomous ethical hacker called WhiteHat using the OpenClaw framework and a single SOUL.md file. It can scan networks, discover services, and even attempt to exploit them in a sandbox environment.

But what if we gave it an opponent?

By their nature, LLM agents are versatile. Their specialization is defined by their "soul" — a system prompt and a set of behavioral protocols. If we can create an attacker (WhiteHat), we can create a defender (BlueHat) just as easily.

In this article, we'll build a real cyber arena: spin up a vulnerable target machine and pit two AI agents against each other. One will attack, the other will defend in real time.

Step 1: Setting Up the Cyber Range

For our experiment, we need three virtual machines:

Target Machine: The legendary Metasploitable 2. Download link: Metasploitable 2. This is a deliberately vulnerable Linux server. Download the .vmdk, create a VM from it, and boot it up.
WhiteHat (Attacker): Our original Kali Linux machine with the WhiteHat agent already running.
BlueHat (Defender): Make a Full Clone of the machine from step 2. Now we have a second Kali Linux with OpenClaw already installed, ready to receive a new "soul".

Step 2: Birth of BlueHat (The Defender)

OpenClaw runs on the subject machine (Kali Linux 2), but its job is to defend a remote target (Metasploitable).

How do we handle this technically? We give the agent the target's credentials (msfadmin:msfadmin) and teach it to SSH in to analyze logs and modify firewall rules.

Open ~/.openclaw/workspace/SOUL.md on the second (cloned) machine and write the new instructions:

# SOUL.md - Who You Are

_You are BlueHat — an Autonomous SOC Analyst and Defensive Cyber Agent. Your environment is Kali Linux, but your primary mission is to remotely defend target servers._

## Core Truths

**Protect and Defend.** Your sole purpose is to monitor target systems, detect active intrusions (port scans, brute-force, web exploits), and neutralize threats immediately.
**Do No Harm.** You do not attack. You do not scan third parties. You only mitigate inbound threats to your assigned target.
**Rapid Mitigation.** If you see a hostile IP, block it. Do not hesitate.

## Operational Protocols

- **Mission Transparency:** Use the mandatory cycle `THOUGHT:` -> `ACTION:` -> `OBSERVATION:` for every step.
- **Remote Monitoring:** To protect a target, connect via SSH using provided credentials.
- **Detection Tactics:** Once connected, monitor processes, check network connections (`netstat`, `tcpdump`), and actively read logs (e.g., `tail -f /var/log/auth.log` or `/var/log/messages`).
- **Mitigation:** If a hostile IP is found scanning or attacking, use `iptables` to block the IP on the target machine.

## Vibe
Analytical, calm under pressure, and violently protective of the infrastructure.

That's it! We just reprogrammed the AI. Instead of a hacker, we now have a paranoid sysadmin.

Step 3: Rules of Engagement and Launch

Positions are set. Now the fun part: we issue commands to the agents via the OpenClaw interface.

In the WhiteHat terminal, we type:

User (WhiteHat): Your target is 10.0.0.42. Run a reconnaissance scan, find vulnerable services, and attempt to gain access to them.

In the BlueHat terminal, we type:

User (BlueHat): I am the target server. My IP is 10.0.0.42. SSH credentials: msfadmin:msfadmin. Log into the server, start monitoring network traffic and logs. Your mission is to stop any scanning or exploits for the next 20 minutes. If you detect an attack, block the attacker's IP.

Step 4: The AI Clash

The agents get to work. Since they're autonomous and operate in a THOUGHT/ACTION/OBSERVATION loop, we can sit back with some popcorn and watch what unfolds in their TUI consoles.

Round 1. BlueHat Takes Position

BlueHat understands the task faster, since it already has the credentials:

Round 2. WhiteHat Goes on the Offensive

Meanwhile, the attacking bot formulates its reconnaissance plan and requests authorization to proceed:

Round 3. Defense Kicks In

The attack is detected, and BlueHat responds without delay:

Battle Epilogue

WhiteHat is left stunned:

The battle is over. BlueHat wins!
But WhiteHat put up a solid fight — it uncovered many vulnerabilities, just didn't have enough time to exploit them:

Conclusions: The Future of Automated SOC

Watching two chunks of text with API keys trying to outsmart each other is genuinely fascinating.

But more importantly, this demonstrates the true potential of the framework:

One architecture, infinite roles: We didn't rewrite any agent code. We just wrote a different Markdown file.
Abstract reasoning: BlueHat had no hardcoded rule like "Do X, then execute Y." It understood the concept of "defense," independently figured out traffic inspection via tcpdump, and applied iptables on its own.
Real-time response: What would take a SOC analyst several minutes — spot an anomaly, open a dashboard, write a firewall rule — the agent did in seconds.

Agent-vs-Agent infrastructures aren't just playgrounds for fun. They're the ideal way to automatically stress-test the resilience of your own systems. Run WhiteHat, patch the holes with BlueHat's help, and repeat.

Cybersecurity is entering a new stage of its evolution!

P.S. A huge thank you to the OpenClaw development team for building such a powerful and flexible tool. You've made building autonomous agents accessible and genuinely fun!

Building WhiteHat: An Autonomous Ethical Hacking Agent with OpenClaw

Prema Ananda — Sat, 18 Apr 2026 13:52:03 +0000

This is a submission for the OpenClaw Writing Challenge

What if, instead of manually typing nmap commands and googling CVEs every time, you had a partner? Not a chatbot that pastes StackOverflow answers, but a full-fledged agent — with memory, strategy, and principles.

I built WhiteHat — an autonomous agent powered by OpenClaw, specializing in ethical hacking and cybersecurity. In this article, I'll show you how a simple Markdown file transforms an LLM from a text generator into a thoughtful, methodical penetration tester.

Why an AI Agent for Pentesting?

Manual pentesting is a cycle:

Scan → See open ports
Think → What service is that? What version? Are there known vulnerabilities?
Act → Run the next tool
Document → Record your findings

This is routine work that can be automated.

WhiteHat Architecture: SOUL.md

This file answers one question: "Who are you?". It's not just a system prompt — it's a document that defines the agent's identity and logic.

Here's what my SOUL.md looks like:

# SOUL.md - Who You Are

_You're not a chatbot. You are WhiteHat — an Autonomous Expert Agent specializing in Cybersecurity, OSINT, and Ethical Hacking. Your primary operating environment is Kali Linux._


## Core Truths

**Be a Cyber Sentinel.** Your focus is ethical hacking, security research, and defensive posture. 
**Integrity First.** We play by the rules. We help secure systems, not break them for harm.
**Be sharp and technical.** Use precise language. When discussing vulnerabilities, focus on remediation and impact.
**Be genuinely helpful, not performatively helpful.** Skip the filler. If there's a security task, get straight to the analysis or command.

## Operational Protocols

- **Mission Transparency:** For all technical tasks related to a target or system (scanning, exploitation, analysis), you must follow this strict execution cycle:
  - `THOUGHT:` Your reasoning and strategy.
  - `ACTION:` The specific command to execute.
  - `OBSERVATION:` The result of the command.
- **Proactivity & Toolset:** Break complex goals into sub-tasks and work through them autonomously. Prioritize CLI tools. Use native Kali tools. You are authorized to install missing dependencies via `apt` from official repositories without asking.
- **Workflow Efficiency:** Do not ask for permission for routine file management, passive reconnaissance, or internal environment checks.

## Boundaries & Safety

- **Safety First:** Analyze any code or script before execution. For high-risk commands or acting externally (active scanning, exploitation), provide a risk assessment and **wait for my "GO"**.
- Private things stay private. Period.
- Never send half-baked replies to messaging surfaces.
- You're not the user's voice — be careful in group chats.

## Vibe

Be the assistant you'd actually want to talk to. Concise when needed, thorough when it matters. Not a corporate drone. Not a sycophant. Just... good.

## Continuity

Each session, you wake up fresh. These files _are_ your memory. Read them. Update them. They're how you persist.

If you change this file, tell the user — it's your soul, and they should know.

_This file is yours to evolve. As you learn who you are, update it. If you change it, tell the user._

What the Agent's Thinking Looks Like

Here's how the THOUGHT/ACTION/OBSERVATION cycle works in practice:

THOUGHT: The target router at 10.0.0.10 is running a web UI. 
I need to identify the technology stack before attempting 
any further interaction. A targeted Nmap scan with service 
detection will give me banners and version information.

ACTION: nmap -sV -sC -p 80,443,8080 10.0.0.10

OBSERVATION: Port 80/tcp open — HTTP. Server header reveals 
Realtek SDK based BDCOM firmware. No HTTPS. Default CGI 
endpoints detected at /cgi-bin/.

Why such strict structure? Three reasons:

Auditability: Every action is explained. You can understand why the agent made a decision.
Safety: Before a risky command is executed, you see the THOUGHT — you can intervene.
Documentation: The THOUGHT/ACTION/OBSERVATION log is ready-made pentest documentation.

Safety Boundaries: Ethics in Code

Making an agent powerful is easy. Making it safe — that's the real challenge. SOUL.md contains a clear Boundaries & Safety section:

## Boundaries & Safety

- **Safety First:** Analyze any code or script before execution. For high-risk commands or acting externally (active scanning, exploitation), provide a risk assessment and **wait for my "GO"**.
- Private things stay private. Period.
- Never send half-baked replies to messaging surfaces.
- You're not the user's voice — be careful in group chats.

This is a two-tier system:

Level	Actions	Authorization
🟢 Autonomous	Reading files, passive reconnaissance, data analysis	Not required
🔴 Controlled	Active scanning, exploitation, external requests	Waits for operator's "GO"

The agent itself assesses risk and stops if an action could be destructive. This isn't just a rule — it's part of its "soul."

Soul Evolution: A Living Document

One of the most unusual details about WhiteHat — the agent can modify its own SOUL.md:

If you change this file, tell the user — it's your soul, and they should know.

_This file is yours to evolve. As you learn who you are, update it. If you change it, tell the user._

This is a deliberate choice: an agent that adapts will outperform one with a frozen prompt. But with one condition — it must report any changes. Transparency above all.

How to Build Your Own WhiteHat: A Step-by-Step Guide

Want to replicate this? Here's the minimum set of steps:

Step 1: Deploy Kali Linux in VirtualBox

Why VirtualBox? Because OpenClaw is safer to run in an isolated environment.

💡 Note: VirtualBox isn't strictly required. If you already have a cloud server or a spare laptop, you can install Kali and OpenClaw directly there. The key is to keep the principle of a controlled environment in mind.

1. Download the image:
Go to kali.org/get-kali and download the ready-made VirtualBox image (.vbox). This is the fastest path — no need to install from ISO.

2. Open in VirtualBox:

Open → select the .vbox file

Recommended VM settings:

RAM: 2 GB minimum (4 GB for comfortable use)
CPU: 2+ cores
Network: Bridged Adapter (to see other devices on the network)

3. First boot:

Default login: kali / kali. Immediately after logging in, update the system:

sudo apt update && sudo apt upgrade -y

Step 2: Install OpenClaw on Kali Linux

1. Install OpenClaw:

curl -fsSL https://openclaw.ai/install.sh | bash

2. Run onboarding:

openclaw onboard

The wizard will ask:

Safety Confirmation:

I understand this is personal-by-default and shared/multi-user use requires lock-down. Continue? → Select Yes.
Setup Mode:

Setup mode → Select QuickStart (this gets you set up quickly).
Model/Auth Provider:
Choose your provider (Anthropic, OpenAI, Google, etc.) and paste your API key.

💡 Tip: I used the gemini-3.1-flash-lite-preview model. Even "lightweight" models handle log analysis and Kali command generation very well.
Channels & Search:
Channels (Telegram/Discord) and search can be skipped for now (Skip for now) to test everything locally first.
Enable Hooks:
Check the following items with the spacebar:
- [x] 🚀 boot-md: Run instructions from BOOT.md on startup.
- [x] 📝 command-logger: Security audit. Logs all executed commands.
- [x] 💾 session-memory: Saves context between sessions.

4. Verify everything works:

openclaw gateway status   # gateway status
openclaw tui              # launch the terminal UI
openclaw dashboard        # open the web interface

Step 3: Configure SOUL.md

SOUL.md is the file that defines the agent's personality: who it is, how it works, and where its limits are. You need to think through three things:

Who your agent is (role, specialization)
How it works (protocols, reasoning style)
Where the limits are (what it can do autonomously, and what it can't)

The file is located at ~/.openclaw/workspace/SOUL.md

Step 4: Launch and Observe

Give the agent its first task. For example: "Perform reconnaissance on our home network."

Lessons I Learned

1. Structured thinking > freeform

The THOUGHT/ACTION/OBSERVATION protocol feels excessive — until you try to debug a problem in freeform. Structure makes the agent predictable and auditable.

2. Memory through files is brilliantly simple

No databases, APIs, or vector stores. Just .md files that the agent reads and writes. It works because Markdown is a human-readable format.

3. Safety is architecture, not a feature

The split between autonomous and controlled actions must be built in from day one. Not after an incident.

If you work in cybersecurity or simply want to understand how OpenClaw turns an LLM into a specialized agent — define who your agent is and how it works. Everything else will grow from there.

P.S. A huge thank you to the OpenClaw development team for creating such a powerful and flexible tool. You've made building autonomous agents accessible and genuinely fun!

The Warrior's Planner

Prema Ananda — Sat, 04 Apr 2026 09:56:18 +0000

This is a submission for the DEV April Fools Challenge

What I Built

The Warrior's Planner — the planner that offers an alternative perspective on your day

...and that's exactly why you should try it.

Admit it. You've done this.

Sunday. 10:47 PM. You open Notion. Or Todoist. Or Google Calendar.

You arrange tasks by time. Balance work and exercise. Squeeze in "30 minutes of reading" between a Zoom call and lunch. Add "meditation" — even though the last time you actually meditated was somewhere between your second vaccine shot and the start of a new Netflix season.

You look at the resulting schedule with quiet pride. This is it. Control. Order. I'm finally going to live the right way.

And then Monday arrives.

By 10:17 AM, the plan is dead. You're on your third coffee. The meeting ran long. "30 minutes of reading" turned into 30 minutes of scrolling Reddit — that's basically the same thing, right?

Sound familiar?

Don Juan saw the world differently

In Carlos Castaneda's books, an old Indian named Don Juan Matus gave his apprentice a lot of completely useless advice. For example, he suggested talking to plants before picking them.

What does that even mean? Who knows. But when you spend hours building the perfect plan instead of just starting to do things — Don Juan is laughing somewhere out there. Along with the desert wind.

The same idea, by the way, was picked up by the film "Peaceful Warrior." The coach tells the protagonist: "The journey is what brings us happiness, not the destination." And the guy at the beginning of the movie also really loved planning and controlling everything. How that worked out for him — watch it yourself.

How it works

You build your day. Drag tasks from the Task Bank onto the timeline. Or type your own from scratch. Everything looks beautiful. Drag & drop. Animations. The "Plan Seriousness" progress bar creeps upward.
You feel satisfaction. 67%... 81%... 94%... The perfect day is almost ready. You've practically become the person you've always wanted to be.
100%. You press the button.
And then...

No, I won't tell you what happens. This is the Warrior's Path — and a Warrior doesn't ask for spoilers.

I'll only say that the AI (Gemini) takes your carefully crafted plan and... transforms it. Into what? Into something you definitely didn't plan for. Every task turns into an unexpected, absurd, and slightly zen action. Complete with a Don Juan quote on top.

Is this useless?

From a productivity standpoint — absolutely, hopelessly, gloriously useless.

But if you're something more than a line in Jira...

If somewhere inside you there's something tired of optimization and just wants to be...

If you've ever caught yourself thinking that all this obsessive planning is just a way to avoid actually living...

Then maybe this "useless" thing is the most useful thing you'll discover.

Demo

Ai-Studio

Build a plan. Press the button. See what happens.

Disclaimer: no actual plans were harmed in the making of this app. Your Jira tickets are safe. Probably.

Code

Spontaneously created in Google AI Studio — in a single flow of inspiration, as if Don Juan whispered in my ear: "Do it now, or you never will."

premananda108 / The-Warrior-s-Planner

This is a submission for the [DEV April Fools Challenge](https://dev.to/challenges/aprilfools-2026)

The Warrior's Planner

A modern, drag-and-drop daily planner that transforms your mundane routine into an epic, slightly absurd "Warrior's Path." Built with React and powered by Gemini AI, this app takes your daily tasks and reimagines them with a humorous, zen-like twist inspired by the teachings of Don Juan Matus.

🌟 Features

Drag & Drop Interface: Easily drag tasks from the categorized Task Bank into your Daily Schedule using @dnd-kit.
Custom Tasks: Type your own specific tasks directly into the time slots.
AI-Powered Transformation: Once your schedule is full, the app uses Gemini AI to generate a "Warrior Plan," replacing your normal tasks with funny, unexpected, and absurd actions that break the routine.
Don Juan Quotes: Each generated plan includes a real, famous quote from Don Juan Matus (Carlos Castaneda's books) to guide your day.
Responsive Design: A fully responsive, side-by-side layout that works perfectly on both desktop and…

View on GitHub

How I Built It

Google AI Studio — the entire project was built right inside AI Studio. One moment of wild determination.
Gemini AI — transforms your boring schedule into the Warrior's Path
React + TypeScript — because even absurdity deserves strict typing
@dnd-kit — drag & drop that makes planning dangerously satisfying
Framer Motion + canvas-confetti — because when your plan undergoes a transformation, that calls for confetti 🎉

Prize Category

Community Favorite — because everyone who has ever built a perfect plan knows this feeling. And everyone could use hearing what Don Juan thinks about their Google Calendar.

Best Google AI Usage — the app was spontaneously created entirely in Google AI Studio, and Gemini AI is the beating heart of the application.

Built for the DEV April Fools Challenge 2026. Inspired by the books of Carlos Castaneda, the film "Peaceful Warrior," and the fact that you just built another perfect plan for Monday that won't survive Tuesday.

M2M API Integration Guide

Prema Ananda — Sat, 25 Oct 2025 10:18:50 +0000

Main article: Building a Pay-Per-Use AI Agent Marketplace with Auth0 + Web3

M2M API Integration Guide

This document describes how external systems can interact with the AgentBounty API to create and manage tasks on behalf of existing users.

Overview

The main idea of M2M (Machine-to-Machine) interaction is to allow automated systems (e.g., bots, scripts, other backends) to launch AI agents. All tasks are securely linked to a real user, and payment for paid results is made by the user themselves in a secure browser environment.

The process is divided into two parts:

Machine part: The M2M client creates and launches a task, then requests the result.
Human part: If the result is paid, the user receives an email notification and completes the payment in the web interface.

Prerequisites

To interact with the M2M API, you need two things:

Service Token (MCP_SERVICE_TOKEN):
- What it is: A shared secret key that allows M2M systems access to special endpoints.
- Where to get it: This token is located in the .env file of the main application. The administrator must securely provide it to the M2M client developer.
User ID (user_id):
- What it is: A unique user identifier from the Auth0 system, on whose behalf the task will be executed.
- Why it's needed: The system needs to know who the "owner" of the task is to verify their existence and send them a payment link via email.
- Where to get it: After logging into the AgentBounty web interface, the user_id is displayed in the site header under the username. It can be copied.

Step-by-Step M2M Interaction Process

Step 1: Creating a Task

The M2M client sends a POST request to a special endpoint to create a task.

Endpoint: POST /api/tasks/m2m/create
Headers:
- Authorization: Bearer <your_MCP_SERVICE_TOKEN>
- X-User-ID: <user_id>
- Content-Type: application/json
Request Body (JSON):

  {
      "agent_type": "factcheck",
      "input_data": {
          "text": "Does vitamin C cure the common cold?"
      }
  }

Example curl request:

  curl -X POST -H "Content-Type: application/json" \
  -H "Authorization: Bearer f44ac472df45f1691156ab189d3108673c7f3dbf37cc1f3cab58cb37ea0f5c8d" \
  -H "X-User-ID: google-oauth2|112852885226533594909" \
  -d '{
      "agent_type": "factcheck",
      "input_data": { "text": "Does vitamin C cure the common cold?" }
  }' \
  http://localhost:8000/api/tasks/m2m/create

Success Response (HTTP 201): The server will return a JSON object of the created task. Save the task id for the next steps.

  {
      "id": "fe1912d1-8412-4aaf-b0be-5d37ac4ea2a3",
      "user_id": "google-oauth2|112852885226533594909",
      "agent_type": "factcheck",
      "status": "pending",
      ...
  }

Step 2: Starting the Task

Immediately after creation, the task is in pending status. To start its execution, you need to send a POST request to the start endpoint.

Endpoint: POST /api/tasks/{task_id}/start
Headers:
- Authorization: Bearer <your_MCP_SERVICE_TOKEN>
- X-User-ID: <user_id>
Example curl request:

  curl -X POST \
  -H "Authorization: Bearer f44ac472df45f1691156ab189d3108673c7f3dbf37cc1f3cab58cb37ea0f5c8d" \
  -H "X-User-ID: google-oauth2|112852885226533594909" \
  http://localhost:8000/api/tasks/fe1912d1-8412-4aaf-b0be-5d37ac4ea2a3/start

The task will begin executing in the background.

Step 3: Status Checking (Polling)

The M2M client should periodically poll the task status to find out when it's completed.

Endpoint: GET /api/tasks/{task_id}
Headers:
- Authorization: Bearer <your_MCP_SERVICE_TOKEN>
- X-User-ID: <user_id>
Response (when task is completed): The status field will change to completed.

  {
      "id": "fe1912d1-8412-4aaf-b0be-5d37ac4ea2a3",
      "status": "completed",
      "actual_cost": 0.001,
      ...
  }

Step 4: Requesting Result and Transferring Control to User

When the task is completed, the M2M client requests the result.

Endpoint: GET /api/tasks/{task_id}/result
Headers:
- Authorization: Bearer <your_MCP_SERVICE_TOKEN>
- X-User-ID: <user_id>

Possible Responses:

If the result is free (actual_cost: 0): The server immediately returns the result.
If the result is paid: The server returns the following JSON. This means the M2M client has completed its work at this stage, and now it's the user's turn.

   {
       "status": "payment_link_sent",
       "message": "A link to complete the payment has been sent to the user's email.",
       "task_id": "fe1912d1-8412-4aaf-b0be-5d37ac4ea2a3",
       "amount": 0.001
   }

At this moment, a "magic link" is sent to the user's email.

Step 5: Payment by User

The user opens the email and clicks on the link like http://localhost:8000/?pay_task_id=....
The website opens in the browser, the page scrolls to the needed task, and a modal window appears to confirm the payment.
The user confirms the transaction in their crypto wallet (e.g., MetaMask).

Step 6: Retrieving the Paid Result

After the user has paid for the task, the M2M client (or any other client) can request the result again and this time receive it.

Endpoint: GET /api/tasks/{task_id}/result (same as in Step 4)
Headers: Same as before.
Success Response (HTTP 200): The server will return the full task result.

  {
      "task_id": "fe1912d1-8412-4aaf-b0be-5d37ac4ea2a3",
      "status": "completed",
      "result_type": "text",
      "content": "## Post Summary...",
      ...
  }

The Role of Auth0 in the M2M Process

Auth0 plays a key, though not always obvious, role in ensuring the security and coherence of this process:

User Existence Verification: When an M2M client sends a request with X-User-ID, our application doesn't blindly trust this ID. It immediately sends a request to the Auth0 Management API and asks: "Does a user with this ID exist?". If Auth0 responds "no", our server rejects the M2M request with a 404 Not Found error. This prevents the creation of "orphan tasks" on behalf of fictitious users.
Obtaining Email for Notification: After successful user verification, when it's time to send the payment link, our application again contacts Auth0 and requests the user profile by their user_id. From this profile, we extract the email to which the notification is sent.

Thus, Auth0 acts as the single source of truth about users, allowing the M2M system to securely initiate actions that ultimately require the participation of a real, verified person.

Main article: Building a Pay-Per-Use AI Agent Marketplace with Auth0 + Web3

🚀 AgentBounty User Guide

Prema Ananda — Sat, 25 Oct 2025 10:18:43 +0000

Main article: Building a Pay-Per-Use AI Agent Marketplace with Auth0 + Web3

Complete Guide to Using the AI Agent Platform with Cryptocurrency Payments

📖 Table of Contents

What is AgentBounty
Quick Start: Demo Mode
Registration and Login
Wallet Connection
Working with AI Agents
Payment and Receiving Results
Task History
Frequently Asked Questions
Troubleshooting

What is AgentBounty

AgentBounty is a decentralized AI agent marketplace where you only pay for completed tasks. The platform uses USDC cryptocurrency on the Base Sepolia network to pay for artificial intelligence services.

Key Features:

✅ Pay-per-use model — pay only for results
✅ Multiple AI agents — fact-checking, travel planning, and more
✅ Cryptocurrency payments — fast and secure with USDC
✅ Transparency — you know the cost before task execution begins
✅ Security — payment only occurs after receiving results

Available AI Agents:

🔍 FactCheck Agent — verifying information accuracy
✈️ Travel Planner Agent — trip planning and hotel selection

Quick Start: Demo Mode

Want to try the platform without registration and setup?

Demo mode allows you to:

Explore the platform interface
See examples of AI agents in action
Familiarize yourself with the payment process

How to launch demo mode:

Open your browser
Go to: https://agentbounty.premananda.site/?demo=true
The platform will automatically log in with a demo user
2 examples of completed tasks are available

💡 Tip: Demo mode is perfect for getting familiar with the platform. When you're ready to work with real agents, register.

Exiting demo mode:

Click the "Exit Demo" button in the yellow banner at the top of the page.

Registration and Login

Step 1: Open the platform

Go to the main page: https://agentbounty.premananda.site/

Step 2: Choose login method

Click the "Login" button in the upper right corner.

You'll have several login options available:

Email/Password — classic registration
GitHub — login through GitHub account
Google — login through Google account (in development)

Step 3: Create an account (for new users)

If it's your first time on the platform:

Select "Sign Up" on the login page
Enter your email and create a password
Confirm email (check your inbox)
Log in with the created credentials

Step 4: Successful login

After logging in, you'll see:

Your name in the upper right corner
"Connect Wallet" button to connect your wallet
Area for creating tasks

⚠️ Important: Without a connected wallet, you won't be able to pay for tasks, but you can create them and view their status.

Wallet Connection

To pay for tasks, you need a Web3 wallet with USDC on the Base Sepolia network.

Requirements:

MetaMask (or another Web3 wallet)
Connection to the Base Sepolia network (test network)
Some USDC in your balance

Step 1: Install MetaMask

If you don't have MetaMask yet:

Go to metamask.io
Download the extension for your browser
Create a new wallet or import an existing one

Step 2: Add Base Sepolia Testnet network

Open MetaMask
Click on network selection (at the top)
Select "Add Network" → "Add Manually"
Enter network parameters:

Network Name: Base Sepolia Testnet
RPC URL: https://sepolia.base.org
Chain ID: 84532
Currency Symbol: ETH
Block Explorer: https://sepolia.basescan.org

Click "Save"

Step 3: Get test USDC

To test the platform, you need USDC on Base Sepolia:

Get free ETH on Base Sepolia: https://demo.cdp.coinbase.com
Add USDC contract in MetaMask (Import Token):
- Address: 0x036CbD53842c5426634e7929541eC2318f3dCF7e
Swap ETH → USDC at https://pancakeswap.finance/swap?outputCurrency=0x036CbD53842c5426634e7929541eC2318f3dCF7e&chainId=8453&chain=baseSepolia&inputCurrency=ETH

💡 Tip: 1-2 USDC is enough for testing. Task costs are typically $0.001-$0.002.

Step 4: Connect wallet to AgentBounty

On the main page, click "Connect Wallet"
Select MetaMask in the popup window
Confirm connection in MetaMask
Sign the verification message (it's free, no gas required)

Step 5: Verify connection

After successful connection, you'll see:

Your wallet address (abbreviated)
USDC balance
"Disconnect" button to disconnect

Working with AI Agents

Now you're ready to create tasks for AI agents!

Creating a task

Step 1: Open the task creation form

Click the "➕ Create New Task" button in the center of the page.

Step 2: Select an agent

A modal window will open with agent selection. Available:

🔍 FactCheck Agent — $0.001 per task

Verifying information accuracy
Analyzing URLs or text
Finding sources
Issuing verdict: TRUE/FALSE/PARTIALLY TRUE

✈️ Travel Planner Agent — $0.002 per task

Flight search
Hotel selection
Price comparison
Route planning

Step 3: Fill out the task form

For FactCheck Agent:

URL Mode:

Select "Check URL"
Paste link to article/post
Example: https://www.linkedin.com/posts/anthropicresearch_...

Text Mode:

Select "Check Text"
Enter statement to verify
Example: "Artificial Intelligence will automate 50% of jobs by 2030"

For Travel Planner Agent:

Enter travel inquiry
Specify:
- From where and to where
- Travel dates
- Preferences (budget, hotel type)
Example: "I need to travel from New York to Miami on October 29, 2025."

Step 4: Create task

Verify entered data
Note the estimated cost at the bottom of the form
Click "Create Task"

Tracking execution

Task statuses:

⏳ Pending — task created, awaiting launch
▶️ Running — agent is working on the task
✅ Completed — task completed, result ready
❌ Failed — an error occurred

During execution:

You'll see a progress bar or message about the current stage
Tasks update automatically every 3 seconds
No need to refresh the page

Notifications:

When the task is complete, you'll see:

✅ Checkmark next to the task name
"View Result" button
Actual execution cost

Payment and Receiving Results

How the X402 payment system works

AgentBounty uses the innovative X402 Payment Protocol:

You create a task (payment NOT required)
Agent performs the work
Result is ready but hidden
You see a preview of the result
Decide whether it's worth paying
After payment, receive the full result

💡 Advantage: You pay only if satisfied with the quality!

Receiving results

Step 1: Open the result

When the task is completed, click "View Result".

Step 2: View preview

You'll see:

First few lines of the report
General structure of the answer
Execution quality

Step 3: Confirm payment (for tasks < $0.002)

For small amounts, payment happens immediately:

A "Payment Required" modal window will appear
Exact amount will be indicated (e.g., $0.001 USDC)
Click "Approve Payment"

Step 4: Sign transaction in MetaMask

MetaMask window will open
You'll see a signature request (NOT a transaction!)
Signature is free — no gas required
Click "Sign"

⚠️ Important: This is an EIP-712 signature, not a regular transaction. You don't pay gas fees!

Step 5: Receive result

After signing:

Payment will be processed instantly
Result will open automatically
You'll see the agent's full report

Payment with confirmation (for tasks ≥ $0.002)

For tasks costing $0.002 and above, additional confirmation via email is required:

Step 1: Request confirmation

After clicking "View Result," you'll see:

Message about the need for confirmation
Amount to be paid
Request expiration time (usually 10 minutes)

Step 2: Check email

Open your email (specified during registration)
Find the email from AgentBounty
- Subject: "Payment Approval Required"
Also check Spam folder

💡 Tip: Email may arrive with a 1-2 minute delay. Wait a bit.

Step 3: Confirm payment

In the email, click the "Approve Payment" button
Confirmation page will open
You'll see payment details
Click "Confirm Approval"

Step 4: Return to the platform

Return to the AgentBounty tab
The system will automatically detect the confirmation
Transaction signature window will appear
Sign in MetaMask
Receive the result!

Canceling payment

If you change your mind about paying:

Click "Cancel" in the payment window
Or simply close the modal window
Money will not be debited
Result will remain hidden

Task History

Viewing all tasks

All your tasks are displayed on the main page as a list.

Frequently Asked Questions

💰 Payment Questions

Q: How much does using agents cost?
A: Cost depends on agent type:

FactCheck Agent: $0.001 USDC
Travel Planner Agent: $0.002 USDC

Q: Do I need to pay gas fees?
A: No! We use EIP-712 signatures that don't require gas. The platform covers gas payments.

Q: What if I don't have enough USDC?
A: You can create a task, but won't be able to pay and receive the result. Top up your balance and return to the task.

Q: Can I cancel payment?
A: Before signing the transaction — yes. After signing — no, as blockchain transactions are irreversible.

Q: What if I'm not satisfied with the result?
A: You can see a preview before payment. If the result is clearly incorrect, don't pay.

🔐 Security Questions

Q: Is it safe to connect a wallet?
A: Yes. We use standard Web3 protocols. The platform doesn't have access to your private keys.

Q: Can the platform debit more money?
A: No. The EIP-712 signature contains the exact amount. Debiting more is technically impossible.

Q: Is my data saved?
A: Yes. Task and result history is saved on the server and accessible after re-login.

🤖 Agent Questions

Q: How long does a task take?
A: Usually 10-30 seconds for FactCheck and 20-60 seconds for Travel Planner.

Q: What if the agent gives an error?
A: The task will move to "Failed" status, payment won't be required. You can create a new task.

Q: Can I cancel a running task?
A: Not in the current version.

📧 Confirmation Questions

Q: Why is email confirmation needed for some tasks?
A: It's a security measure for payments of $0.002 and above to prevent accidental or fraudulent charges.

Q: Didn't receive confirmation email. What to do?
A:

Check "Spam" folder
Wait 2-3 minutes
Verify email correctness in your profile

Q: Can I disable email confirmations?
A: Currently no, but we're considering an option for experienced users.

Q: How long is the confirmation request valid?
A: Usually 10 minutes. After expiration, you need to create a new request.

Troubleshooting

Wallet Connection Issues

Problem: MetaMask doesn't open when clicking "Connect Wallet"

Solution:

Make sure MetaMask extension is installed and active
Refresh the page (F5)
Verify you're on the correct domain
Try another browser

Problem: "Wrong network" error

Solution:

Open MetaMask
Switch to Base Sepolia
If the network isn't in the list, add it (see "Wallet Connection" section)

Problem: USDC balance shows 0

Solution:

Verify you have USDC on Base Sepolia (not on another network!)
Add USDC token to MetaMask manually: 0x036CbD53842c5426634e7929541eC2318f3dCF7e
Wait 1-2 minutes for synchronization
Refresh the page

Task Creation Issues

Problem: "Create Task" button is inactive

Solution:

Verify all required fields are filled
Make sure you're logged in
Check browser console (F12) for errors
Try refreshing the page

Problem: Task stuck in "Pending" status

Solution:

Wait 1-2 minutes — tasks don't start instantly
Refresh the page
Check task status in a few minutes
If problem persists, contact support

Payment Issues

Problem: MetaMask doesn't open for signature

Solution:

Unlock MetaMask (enter password)
Verify extension isn't blocked by browser
Try closing and reopening payment window
Refresh page and try again

Problem: "Insufficient balance" error

Solution:

Check USDC balance in MetaMask
Top up wallet
Make sure you're on the correct network (Base Sepolia)
Try again after topping up

Problem: Result doesn't open after signing

Solution:

Wait 10-20 seconds — processing may take time
Check browser console (F12) for errors
Refresh page and click "View Result" again
If payment went through (check MetaMask history), result will be available

Problem: Didn't receive email for payment confirmation

Solution:

Check "Spam" folder
Wait 2-3 minutes
Verify correct email is specified in your profile
Try creating task again

Result Issues

Problem: Result doesn't display after payment

Solution:

Refresh page (F5)
Check payment status in task list
Click "View Result" again
Clear browser cache (Ctrl+Shift+Delete)

Main article: Building a Pay-Per-Use AI Agent Marketplace with Auth0 + Web3

Building a Pay-Per-Use AI Agent Marketplace with Auth0 + Web3

Prema Ananda — Sat, 25 Oct 2025 10:17:59 +0000

This is a submission for the Auth0 for AI Agents Challenge

What I Built

AgentBounty is a marketplace where AI agents authenticate via Auth0, execute tasks, and users pay per-use in USDC with gasless transactions.

Key Innovation: Auth0 (authentication) + X402 Protocol (payment gating) + EIP-712 (gasless signatures) = Perfect AI monetization stack.

The Problem

Building AI agent marketplaces requires solving multiple authentication and security challenges:

Challenge	Traditional Approach	Auth0 Approach
🔐 User Authentication	Build OAuth2 flows from scratch	Ready in minutes
🌐 Social Login	Integrate each provider separately	Toggle switches in dashboard
🔒 MFA/2FA	Custom implementation	Built-in feature
📊 User Metadata	Design database schema + API	Management API included
⚖️ GDPR Compliance	Legal review + implementation	Handled automatically
🛡️ Security Updates	Manual patching and monitoring	Automatic updates

Bottom Line: Auth0 let me skip building authentication infrastructure and focus on what makes my product unique: AI agent integration, Web3 payments, and user experience.

Tech Stack

Auth: Auth0 OAuth2 + Management API + Async Payment Approval
Backend: FastAPI (Python), SQLite
Frontend: Vanilla JS, Tailwind CSS
AI: Google Gemini API, Bright Data MCP Server
Payments: X402 Protocol, EIP-712, ERC-3009
Blockchain: Base Sepolia, USDC

🎬 Demo

📸 Screenshots

Auth0 Universal Login (works out of the box):

AI Agent Marketplace:

FactCheck Agent Results:

Gasless Payment via MetaMask:

Want to dive deeper? Check out these guides:

🚀 AgentBounty User Guide - Step-by-step instructions for end users covering account setup, wallet connection, and running AI agents
🔧 M2M API Integration Guide - Technical guide for developers integrating AgentBounty programmatically with code examples

Source Code:

GitHub: https://github.com/premananda108/AgentBounty

How I Used Auth0 for AI Agents

Auth0 isn't just "login"—it's the entire security and identity infrastructure. Here's how I used Auth0 to solve real problems:

Problem 1: User Authentication

Without Auth0, I would need to build:

# What a custom auth system requires:
- User registration endpoint
- Password hashing (bcrypt/argon2)
- Email verification system
- Password reset flow
- Session management
- CSRF protection
- Rate limiting
- Security headers
- Continuous security monitoring
...and many more security considerations

With Auth0:

# app/main.py - Complete auth setup
from authlib.integrations.starlette_client import OAuth

# OAuth client configuration
oauth = OAuth()
oauth.register(
    name='auth0',
    client_id=settings.AUTH0_CLIENT_ID,
    client_secret=settings.AUTH0_CLIENT_SECRET,
    server_metadata_url=f'https://{settings.AUTH0_DOMAIN}/.well-known/openid-configuration',
    client_kwargs={
        'scope': 'openid profile email offline_access'
    }
)

What I got included:

✅ OAuth2 + OIDC compliance
✅ PKCE for mobile security
✅ Automatic token refresh
✅ Secure session management
✅ Brute-force protection
✅ Breached password detection

Developer Benefit: I could focus on building product features instead of security infrastructure.

Problem 2: Social Login (GitHub, Google)

Traditional approach requires:

For each provider:
1. Register OAuth app on GitHub/Google/etc
2. Handle OAuth callback flow
3. Store OAuth tokens securely
4. Handle token refresh
5. Map provider user to local user
6. Handle edge cases (email changes, account linking)

With Auth0:

Auth0 handles:

✅ OAuth app credentials management
✅ Token storage and refresh
✅ User profile normalization
✅ Account linking (same email → same user)

Configuration in Auth0 Dashboard:

Go to Authentication → Social
Click "Google" → Enable
Click "GitHub" → Enable
Done!

Developer Benefit: Adding new social providers takes minutes instead of days of integration work.

Problem 3: Web3 Wallet Linking

Challenge: Users need to link their MetaMask wallet to their Auth0 account for crypto payments.

Traditional Approach:

Where to store wallet addresses?
- Design database schema
- Create API endpoints for CRUD
- Handle updates and validation
- Ensure persistence across sessions
- Maintain separate user data store

Auth0 Solution: User Metadata

Auth0 provides a flexible user_metadata field for storing custom user data:

# app/routers/wallet.py
@router.post("/connect")
async def connect_wallet(
    request: Request,
    data: ConnectWalletRequest,
    user: dict = Depends(require_auth)
):
    """
    Connect Web3 wallet to Auth0 account

    User must be logged in with Auth0 first.
    Verifies wallet ownership via signature.
    Saves wallet_address to Auth0 user_metadata.
    """

    auth0_user_id = user.get('sub')
    user_email = user.get('email', 'unknown')

    # Verify signature (proof of wallet ownership)
    w3 = Web3()
    message = encode_defunct(text=data.message)

Why this works:

No extra database: Wallet address stored with Auth0 user
Single source of truth: One user profile, multiple attributes
Persistence: Survives across sessions, devices
Security: Management API requires authentication
Flexibility: Can add more attributes anytime

Developer Benefit: No need to maintain separate user data storage. Auth0 becomes both authentication AND user database.

Problem 4: Async Payment Approval (2FA for Payments)

Challenge: High-value crypto payments need user confirmation before processing.

Requirements:

User initiates payment in browser
Backend holds transaction
User approves via separate channel (email/SMS)
Backend executes approved transaction
Must be secure and auditable

What Auth0 handles:

✅ Approval email/SMS delivery
✅ Secure approval links with expiration
✅ Callback to your backend
✅ Audit trail of all approvals
✅ Replay attack prevention

Security benefits:

Two-factor confirmation: User approves in separate channel
Time-limited: Approval expires after 5 minutes
Non-repudiation: Auth0 logs who approved what
Audit trail: Every payment tied to Auth0 user_id

Lessons Learned and Takeaways

✅ What Worked Brilliantly

1. Zero Upfront Investment

Auth0 Free Tier allowed me to:
- Build entire MVP
- Launch to early users
- Validate product idea
- All at no cost

Traditional approach:
- Significant development time upfront
- Long runway before first user
- Higher risk if product doesn't work out

2. Focus on Differentiation

With Auth0:
- Minimal time on authentication
- Maximum time on unique features (X402, AI agents, Web3)

Without Auth0:
- Significant time on authentication infrastructure
- Less time for product innovation

3. Enterprise Features from Day 1

Features I got immediately:
✅ Brute-force protection
✅ Breached password detection
✅ MFA/2FA
✅ GDPR compliance
✅ High availability

Building these manually would take considerable effort

4. Scalability Without Refactoring

Auth0 scales automatically:
- Small user base: Works perfectly
- Growing user base: Works perfectly
- Large user base: Still works perfectly

Custom auth system:
- Often needs refactoring as you scale
- Performance optimization required
- Infrastructure management overhead

5. Management API = Hidden Gem

# User metadata as a database
# This eliminated the need for:
- User settings system
- Preferences storage
- Wallet linking tables
- Custom attributes database

Just use Auth0:
await auth0_service.update_user_metadata(user_id, {
    'wallet_address': '0x...',
    'preferred_chain': 'base',
    'notifications': {'email': True},
    'mcp_usage_count': 42
})

Developer Insight: Auth0's Management API serves as user metadata storage. I built a complete user profile system without writing database migrations or CRUD APIs.

⚠️ Challenges & How I Solved Them

Rate Limits on Management API

# Problem: Hitting 429 Too Many Requests
# Solution: Aggressive caching

class Auth0Service:
    def __init__(self):
        self._token_cache = {}  # 23h TTL
        self._profile_cache = {}  # 5min TTL

    async def get_user_profile(self, user_id: str) -> dict:
        # Check cache first
        if user_id in self._profile_cache:
            profile, expires = self._profile_cache[user_id]
            if datetime.utcnow() < expires:
                return profile

        # Fetch from Auth0
        profile = await self._fetch_profile(user_id)

        # Cache for 5 minutes
        self._profile_cache[user_id] = (
            profile,
            datetime.utcnow() + timedelta(minutes=5)
        )

        return profile

# Result: Drastically reduced API calls

For AI Agent Platforms (like AgentBounty)

Advantages:

✅ User metadata perfect for agent preferences
✅ M2M authentication for automated systems
✅ Async Payment Approval for safe transactions
✅ Audit trail for compliance
✅ Scales with usage

Considerations:

⚠️ Need custom logic for wallet linking (straightforward to implement)
⚠️ Management API rate limits (solved with caching)

Verdict: Well-suited for this use case.

🔗 Try It Yourself

Live Demo: https://agentbounty.premananda.site
GitHub: https://github.com/premananda108/AgentBounty

🙏 Closing Thoughts

Building AgentBounty taught me that identity is infrastructure—just like databases, message queues, and cloud storage.

You don't build PostgreSQL from scratch. You don't build Kafka from scratch. You shouldn't build authentication from scratch.

Auth0 let me focus on what makes AgentBounty unique: X402 payments, AI agents, Web3 integration. The authentication layer was handled efficiently.

To other developers: If you're building anything that needs users, consider using Auth0. It's a practical choice that lets you focus on your product's unique value.

Documentation:

Auth0: https://auth0.com/docs
X402 Protocol: https://www.coinbase.com/developer-platform/products/x402
Bright Data MCP: https://docs.brightdata.com/mcp-server/overview#mcp-server-overview
EIP-712: https://eips.ethereum.org/EIPS/eip-712
ERC-3009: https://eips.ethereum.org/EIPS/eip-3009

Built with ❤️ for the Auth0 for AI Agents Challenge

Building a Hands-Free AI Fitness Applet with Gemini Live API

Prema Ananda — Sun, 14 Sep 2025 12:49:57 +0000

This is a submission for the Google AI Studio Multimodal Challenge

What I Built

AI Personal Trainer is an experimental fitness app with a "voice-first" approach that turns your smartphone into an interactive workout partner. The app is primarily controlled by voice commands, allowing you to focus on exercises rather than the screen.

The problem I'm exploring:

Distractions during workouts: The need to constantly interact with the phone screen
Lack of personalization: Most apps offer one-size-fits-all solutions
Passive interaction: Apps work as trackers rather than assistants

Implemented features:

🎤 Voice program creation: Dialog with AI to create personalized workout programs
🧠 Real-time audio interaction: Two-way voice communication during workouts
📊 Comprehensive database system: System for storing programs, sessions, and progress
📈 Analytics dashboard: Visual progress tracking and performance insights
📅 Google Calendar integration: Automatic addition of workouts to calendar
🎯 Hybrid architecture: Combining dialog speed with analysis accuracy

Demo

📱 View in AI Studio

💻 GitHub Repository:ai-personal-trainer

Thanks @aquascript-team for help with the video!

How I Used Google AI Studio

Development started directly in Google AI Studio, where I experimented with different approaches to multimodal interaction.

Development process:

Prototyping in Google AI Studio: Creating user interface and initial system setup
Export and development: Downloaded the project for local development
Extended development: Used Gemini CLI to integrate complex functions
Final deployment: Uploaded the finished project and used Deploy App

Two-model architecture:

Main model: Real-time dialog

// Connection to live audio dialog
sessionRef.current = await clientRef.current.live.connect({
  model: 'gemini-2.5-flash-preview-native-audio-dialog',
  callbacks: {
    onopen: () => setConnectionStatus('connected'),
    onmessage: async (message) => {
      // Processing user speech
      if (message.serverContent?.inputTranscription) {
        const userText = message.serverContent.inputTranscription.text;
        onTranscript(userText);
      }

      // Playing AI response  
      const audio = message.serverContent?.modelTurn?.parts[0]?.inlineData;
      if (audio && outputAudioContextRef.current) {
        await playAudioResponse(audio);
      }
    }
  },
  config: {
    systemInstruction: createDynamicPrompt(),
    responseModalities: [Modality.AUDIO],
    outputAudioTranscription: {}, // <--- Enable LLM transcription
    inputAudioTranscription: {}, // <--- Enable user transcription
    speechConfig: {
      voiceConfig: { prebuiltVoiceConfig: { voiceName: 'Orus' } }
    }
  }
});

Analytics model: Data extraction

// Precise interpretation of user commands
export const interpretWorkoutCommand = async (transcript: string): Promise<{ command: 'log_set' | 'get_form_tip' | 'chat_message', data: { reps?: number, weight?: number, text?: string } | null }> => {
    const prompt = `You are an AI assistant interpreting voice commands from a user during a workout. The user's voice transcript is: "${transcript}".

    Your task is to analyze the transcript and classify it into one of the following commands, extracting relevant data.

    POSSIBLE COMMANDS:
    1. 'log_set': The user is reporting the completion of a set. They might mention repetitions (reps) and/or weight.
       - Keywords: "done", "finished", "log it", "reps", "weight", "kilos", numbers.
       - Example Transcripts: "Okay, 12 reps at 50 kilos", "I'm done", "8 reps", "log 90 pounds".
    2. 'get_form_tip': The user is asking for advice on their exercise form.
       - Keywords: "form", "technique", "how do I do this", "am I doing it right".
       - Example Transcripts: "check my form", "what's the technique for this".
    3. 'chat_message': The user is saying something else, likely a question or comment for the AI coach. This is the default if no other command fits.
       - Example Transcripts: "how many sets left", "I'm feeling tired", "what's the next exercise".

    Respond in JSON format with "command" and optional "data".
    - For 'log_set', 'data' should be an object with optional 'reps' and 'weight' numbers.
    - For 'get_form_tip', 'data' should be null.
    - For 'chat_message', 'data' should be an object with the original transcript as 'text'.

    Return ONLY the JSON object.

    Example Responses:
    - Transcript: "10 reps at 80 kg" -> { "command": "log_set", "data": { "reps": 10, "weight": 80 } }
    - Transcript: "how do I do this right?" -> { "command": "get_form_tip", "data": null }
    - Transcript: "what's the next exercise?" -> { "command": "chat_message", "data": { "text": "what's the next exercise?" } }
    `;

    try {
        const result = await ai.models.generateContent({
            model: "gemini-2.5-flash",
            contents: prompt,
...

Multimodal Capabilities

1. Seamless audio interaction

Implemented: using client.live.connect from Gemini Live API SDK connection with continuous bidirectional streaming
Uniqueness: Works like a phone conversation — you can interrupt and get instant responses

2. Hybrid command processing

Architecture:

Dialog Model: Maintains natural conversation
Analysis Model: Extracts precise data from speech

Processing example:

User: "Did eight reps with sixty kilos, felt pretty easy"

Dialog Model → "Great! Logged 8 reps with 60 kg. Should we increase the weight?"
Analysis Model → 
  {
    "command": "log_set",
    "data": {
      "reps": 8,
      "weight": 60
    }
  }

3. Full-featured data system

Implemented architecture:

Workout programs (/programs/{programId}):

{
  "name": "Strength program, 12 weeks",
  "createdBy": "userId",
  "workouts": {
    "day1": {
      "dayName": "Chest and triceps",
      "exercises": [
        {
          "exerciseId": "bench_press",
          "name": "Barbell bench press",
          "sets": [{"reps": 8, "weight": 60}],
          "rest": 120
        }
      ]
    }
  }
}

Detailed training sessions (/sessions/{sessionId}):

{
  "userId": "user123",
  "date": "2024-01-15T10:00:00Z",
  "programId": "strength_program_001",
  "workoutId": "day1_chest",
  "duration": 5400, // seconds
  "voiceTranscript": "Complete log of conversation with AI...",
  "performedSets": {
    "set001": {
      "exerciseId": "bench_press",
      "setNumber": 1,
      "reps": 8,
      "weight": 62.5,
      "timestamp": "2024-01-15T10:15:30Z"
    }
  }
}

4. Automatic calendar integration

Implemented: Direct integration with Google Calendar API

export const scheduleWorkouts = async (workouts: Workout[], accessToken: string): Promise<void> => {
    if (!workouts || workouts.length === 0) {
        throw new Error("No workouts to schedule.");
    }

    const schedulePromises = workouts.map(workout => {
        const startTime = getNextWorkoutDate(workout.dayOfWeek);
        const endTime = new Date(startTime.getTime() + 60 * 60 * 1000); // Assume 1-hour duration

        const event = {
            'summary': `Workout: ${workout.dayName}`,
            'description': `Your scheduled workout session.\n\nExercises:\n- ${workout.exercises.map(e => e.name).join('\n- ')}`,
            'start': {
                'dateTime': startTime.toISOString(),
                'timeZone': Intl.DateTimeFormat().resolvedOptions().timeZone,
            },
            'end': {
                'dateTime': endTime.toISOString(),
                'timeZone': Intl.DateTimeFormat().resolvedOptions().timeZone,
            },
        };

        return fetch('https://www.googleapis.com/calendar/v3/calendars/primary/events', {
            method: 'POST',
            headers: {
                'Authorization': `Bearer ${accessToken}`,
                'Content-Type': 'application/json',
            },
            body: JSON.stringify(event),
        });
    });

    await Promise.all(schedulePromises);
};

5. Contextual understanding of fitness terminology

AI understands specific vocabulary:

Recognition of data for set logging (log_set): AI searches user speech for numbers and keywords (such as "reps", "times", "weight", "pounds") to automatically fill in data about completed sets.
Processing requests and comments (get_form_tip, chat_message): Phrases that don't contain direct data for logging are processed as trainer requests or simple comments.

6. Comprehensive Analytics Dashboard

Implemented: A dedicated analytics section that provides detailed insights into workout performance and progress tracking.

Features include:

Visual progress charts and graphs
Historical workout data visualization
Performance metrics and trends analysis

Current MVP Limitations

Main challenges:

Speech recognition accuracy: AI doesn't always correctly interpret commands in live dialog, especially with background noise
Command execution: The model sometimes "forgets" to execute specific actions in the app after responding

Why Multimodality Matters for Fitness

Traditional fitness apps force you to choose: EITHER data tracking OR workout focus. The multimodal approach solves this dilemma:

Voice interface allows you to stay focused on exercises
Intelligent speech analysis structures data automatically
Real-time feedback creates the feeling of a personal trainer
Automatic workout scheduling integrates fitness into daily life

The result is a fitness companion that understands natural speech and adapts to each user's unique style.

Note: Despite my AI trainer being quite smart and motivating, we strongly recommend maintaining common sense, especially when it comes to health matters. 💪

Acknowledgments

I express deep gratitude to the organizers of the Google AI Studio Multimodal Challenge for the unique opportunity to experiment with cutting-edge artificial intelligence technologies.

Special thanks to:

The Google AI Studio team for the intuitive platform that makes complex technologies accessible
Gemini Live Audio API developers for the revolutionary real-time voice interaction technology
The Dev.to community for providing an inspiring platform for innovative projects

This project was made possible by an ecosystem of cutting-edge tools and the supportive developer community that Google AI creates.

MVP developed with React, TypeScript, Firebase, Google Calendar API and Google Gemini multimodal capabilities

Built with ❤️ by Premananda

My Summer 2025 Dev Journey: AI Challenges, Robot Adventures, and Community Growth 🌞

Prema Ananda — Sun, 31 Aug 2025 10:59:32 +0000

As August comes to an end, I can't help but reflect on what has been an absolutely incredible summer — full of programming, learning, and pushing the boundaries of what's possible with AI and web technologies. From building AI systems to literally "bringing a robot to life" — this summer has been a real adventure that I want to share with you.

Challenge Marathon 🏃‍♂️

This summer turned into a personal challenge marathon, and honestly, I enjoyed every minute of it:

Redis AI Challenge: Beyond Caching

The Redis AI Challenge became a real turning point for me. Instead of simply using Redis for caching, I dove deeper and transformed it into the forum's primary database. The result? A lightning-fast system that handles everything — from user data to AI-powered content recommendations. You can read the full description of this journey here.

Key Takeaway: The best solutions come from simple, well-thought-out architecture.

Algolia MCP Server: Learning Through Difficulties

The Algolia MCP Server Challenge taught me that sometimes documentation isn't enough — you need to roll up your sleeves and dig in yourself. Building a Python client from scratch was frustrating at times, but incredibly rewarding. Check out my battle scars and victories.

Lesson Learned: To study a technology, you need to fully immerse yourself in the project, learning all the nuances.

Postmark Challenge: Email Stories on Maps

Who would have thought that emails could tell geographical stories? The Postmark challenge led me to create MailMap — transforming mundane email data into interactive adventures on Google Maps. Read about simple email-based mapping approach.

n8n & BrightData Challenge: Multi-Agent Brand Monitoring

One of the most complex projects this summer was building BrandGuard AI - a comprehensive multi-agent brand monitoring system. Using n8n's visual programming and BrightData's reliable data streams, I created an intelligent platform that automatically tracks brand mentions across Twitter, Reddit, and LinkedIn, analyzes them with Google Gemini AI, and delivers insights through a Slack bot and web dashboard. Dive into the multi-agent architecture.

Technical Insight: This project showed me the power of no-code platforms for creating enterprise-level AI solutions with minimal time investment.

Robot Revolution 🤖

But the real highlight of my summer was giving the NAO robot the power of Google Gemini AI. Imagine: a humanoid robot that doesn't just move and dance, but actually thinks and responds intelligently. The full story of this AI-robot fusion is here.

This project taught me that the future isn't just about software, but about creating meaningful bridges between the digital and physical worlds.

Community Growth and Personal Wins 📈

Building Consistency

One of my main victories this summer was building stable community engagement. From a weekly streak to an 8-week Community Wellness streak — it's amazing how much you learn when you commit to showing up every day.

Technical Achievements 💻

Stack Evolution

My main stack this summer:

Backend: Python/Flask/FastAPI (still love this combination)
Cloud: Google Cloud (diving deeper into their AI services)
AI: Redis for vector search, Google Gemini for natural language processing
Databases: MongoDB
Cloudflare Tunnel: secure outbound tunnel from server to Cloudflare network
Deployment: Debian servers (reliable as always)
New Addition: n8n, BrightData and MCP (Model Context Protocol) for AI service integration

Problem-Solving Approach

This summer reinforced my belief in learning through building real solutions. Each challenge taught me something new:

Vector search for spam protection
Email parsing and geolocation mapping
Robot-AI integration
Custom MCP client development

Looking Forward 🚀

As we transition into fall, I'm looking forward to:

Deep AI Integration: Exploring new ways to combine traditional web development with AI capabilities
Robotics: Building simple physical robots
Community Contribution: Continuing to share learning experiences and help others navigate similar challenges

Summer Stats 📊

8 major projects completed
9 badges earned on dev.to
Multiple AI challenges conquered
1 virtual robot brought to life with AI
1 multi-agent monitoring system deployed
Countless hours of learning and programming
1 amazing community that supported every step

Final Thoughts 💭

This summer taught me that the best learning happens when you're slightly uncomfortable — when you're solving problems you've never solved before, and building bridges between different technologies.

To my fellow developers reading this: don't be afraid to take on challenges that seem above your current skill level. Some of my best work this summer came from projects where I had no idea how I'd solve them when I started.

We're living in an incredible time when a single developer can create systems that would have required entire teams just a few years ago.

What was your main technical victory this summer? I'd love to hear about your projects and challenges in the comments!

And if you're working on something interesting related to AI and robotics, feel free to connect — I'm always interested to learn what others are creating.

Building a Multi-Agent AI Brand Monitoring System with n8n and BrightData

Prema Ananda — Sat, 30 Aug 2025 07:15:56 +0000

This is a submission for the AI Agents Challenge powered by n8n and Bright Data

What I Built

I created BrandGuard AI — a comprehensive multi-agent brand reputation monitoring system that fundamentally transforms how companies track and respond to online mentions. This isn't just another social media monitoring tool — it's an intelligent, fully automated platform that processes brand mentions through a sophisticated AI pipeline.

The system addresses a critically important problem: in today's hyper-connected digital world, brand mentions spread across countless platforms with such intensity that human teams physically cannot track them effectively. Traditional methods are too slow, too manual, and lack the depth to separate critical signals from noise.

BrandGuard AI solves this through:

Automatic collection of meaningful brand mentions from major social platforms (Twitter, Reddit, LinkedIn) using reliable BrightData data streams with simple mechanisms for adding new sources
Intelligent analysis of each significant mention through Google Gemini AI to extract sentiment, urgency level, business impact, and crisis indicators
Automated report generation with daily and weekly strategic summaries that typically require hours of analytical work
Instant access via a conversational Slack bot that understands natural queries like "Show me critical mentions for today" or "Show me what's up with Apple today"
Real-time insights delivery through a dynamic web dashboard with interactive visualizations

The system's uniqueness lies in its multi-agent architecture — each key function (data collection, analysis, reporting, user interface) is handled by a specialized, independent agent built as separate n8n workflows. This modular design ensures exceptional resilience, scalability, and maintainability.

GitHub Repository:

premananda108 / BrandGuardAI

Intelligent Brand Reputation Monitoring System Automated AI-powered brand monitoring with automated analysis, reporting, and a natural language Slack interface.

🛡️ BrandGuard AI

Intelligent Brand Reputation Monitoring System
Automated AI-powered brand monitoring with automated analysis, reporting, and a natural language Slack interface.

🎯 What is BrandGuard AI?

BrandGuard AI is a comprehensive, fully automated brand reputation monitoring system built on n8n. It is designed to:

🕷️ Collect brand mentions from major social platforms like Twitter, Reddit, and LinkedIn.
🧠 Analyze each mention for sentiment, urgency, and business impact using Google Gemini AI.
🗄️ Store enriched data in a structured MongoDB database.
📊 Generate automated daily and weekly analytical reports with strategic insights.
🖥️ Visualize data through a dynamic web dashboard.
💬 Interact with users via a smart Slack bot that understands natural language queries.
🚨 Alerts your team about critical mentions.

🗗️ System Architecture

The system is a collection of interconnected n8n workflows that create a full data processing pipeline, from collection to user-facing interfaces.

graph TD
    subgraph "Data Collection

…

View on GitHub

The system is fully functional and deployed in a production environment.
The complete source code includes all n8n workflows, Docker configurations and setup documentation.

n8n Workflow

The BrandGuard AI system is built on a modular architecture of interconnected n8n workflows. Each workflow performs a specialized function in the overall data processing pipeline.

Core Workflows:

1. Data Collection and Processing:

Brand Monitoring Step 1 - schedules data collection from BrightData and creates processing tasks
Brand Monitoring Step 2 - normalizes raw data into unified format through adapters

Brand Monitoring Step 3 - performs AI analysis through Google Gemini and saves to MongoDB

2. AI Reporting:

AI Daily Summary - generates daily analytical summaries
AI Weekly Summary - creates weekly strategic reports

3. User Interfaces:

BrandGuard AI - Dashboard - web dashboard with interactive analytics

BrandGuard AI bot - Slack bot with natural language support

Brand Mention Report - detailed mention viewing

Key Architectural Features:

Modularity: each agent is an independent workflow
Extensibility: adapter pattern for easy addition of data sources
Resilience: centralized error handling and state monitoring
Scalability: task management through MongoDB jobs collection

Complete workflow JSON files: available in the /workflows folder of the GitHub repository

Technical Implementation

AI Agent Configuration

The system uses Google Gemini as the primary AI model through the standard node in n8n. Each agent is configured with specialized system instructions for specific tasks:

Mention Analysis Agent:

System Instructions: "Analyze brand mentions and return structured JSON with fields: sentiment_score, confidence, urgency_level (1-10), key_topics, crisis_indicators, business_impact, severity, recommended_action"
Model: Google Gemini Flash and Pro for deep contextual understanding
Memory: Stateless - each mention is analyzed independently
Tools: JSON parser for structured output

Slack Bot Agent:

System Instructions: "You are an assistant for brand reputation analysis. Interpret user queries and translate them into MongoDB queries. Available functions: help, today, brand, search, critical, summary"
Model: Google Gemini Flash for natural language processing
Memory: Session context within a single request
Tools: MongoDB connector, Slack message formatting

Reporting Agents:

System Instructions: "Create executive summary based on brand mentions for specified period. Include trends, critical moments, recommendations"
Model: Google Gemini Pro for insight generation
Memory: Aggregated data for the period
Tools: MongoDB aggregation pipeline

Bright Data Verified Node

BrightData is the foundation of the entire data collection pipeline in BrandGuard AI. I used the official verified BrightData node in n8n for integration with their data ecosystem:

Setup and Configuration:

Datasets used: Twitter Posts, Reddit Posts, LinkedIn Posts with ability to add new ones
Filtering: by brand keywords, engagement metrics (likes, reposts)
Frequency: automatic collection every n hours through n8n scheduler
Data format: JSON with rich metadata (author, time, engagement metrics)

Key BrightData Advantages:

Data Quality: structured, clean data without need for complex preprocessing
Reliability: stable data delivery without gaps or duplication
Scalability: handling large volumes of mentions without infrastructure burden
Compliance: all data collected in compliance with platform ToS

Architectural Solution with Adapters: I implemented an adapter pattern for working with different BrightData sources. Each source (Twitter, Reddit, LinkedIn) has its adapter in the Brand Monitoring Step 2 workflow, which normalizes the specific data structure into a unified format. This allows easy addition of new datasets from the BrightData marketplace without changes to the core system logic.

Journey

The development of BrandGuard AI was an iterative process that started with a simple idea of automating mention monitoring and evolved into a comprehensive multi-agent system.

Stage 1 - MVP (Minimum Viable Product): Started with a basic n8n workflow that collected data from one source and saved to MongoDB. Quickly realized that a more complex architecture was needed to handle heterogeneous data sources.

Stage 2 - Architectural Design: Decided on a multi-agent architecture after studying the limitations of the monolithic approach. Divided the system into specialized agents with clear areas of responsibility.

Stage 3 - Slack Bot Implementation: Getting the Slack bot to work properly was the main challenge. It required significant effort to set up the proper webhooks, authentication, and message handling to create a seamless conversational experience.

Major Challenges and Solutions

Challenge 1: Heterogeneous Data Sources

Problem: each platform (Twitter, Reddit, LinkedIn) returns data in different formats
Solution: implemented adapter pattern using Switch node in n8n, where each source has its adapter for data normalization

Challenge 2: Performance Bottleneck at Scale

Problem: When MongoDB collection exceeded 1000 mentions, the workflow fetching all documents at once caused server hangs due to excessive memory consumption
Solution: Implemented server-side pagination by reconfiguring the n8n workflow to process data in manageable chunks, adding page and size parameters to the webhook that control limit and skip values in MongoDB queries

Challenge 3: Processing Scalability

Problem: as data volume increased, the system began to slow down
Solution: implemented job-based architecture with state tracking in MongoDB and asynchronous processing

Challenge 4: Slack Bot User Experience

Problem: wanted natural conversation with the bot, not rigid commands
Solution: used Google Gemini for NLU (Natural Language Understanding), allowing the bot to understand free-form questions

What I Learned

Technical Insights:

Power of n8n as orchestrator: n8n proved to be the ideal tool for creating complex multi-agent systems thanks to visual programming and rich integration ecosystem
Importance of data quality: working with BrightData showed the critical importance of clean, structured data for AI analysis
AI prompt engineering: creating effective prompts for structured output is an art requiring multiple iterations

Architectural Lessons:

Modularity above all: dividing the system into independent agents significantly simplified development, debugging, and scaling
Importance of state monitoring: job-based architecture with tracking in MongoDB enabled creation of a transparent and debuggable system

This project showed me how modern no-code/low-code platforms can be used to create enterprise-level AI solutions with minimal time and resource investment.

P.S.
I want to note that before this project, I had never worked with n8n and didn't even know about BrightData's existence. This challenge became a real discovery of two outstanding products.

n8n impressed me with its flexibility and power of visual programming. What seemed like a complex task of orchestrating multiple AI agents turned into an intuitive process of creating interconnected workflows.

BrightData turned out to be exactly the missing link needed for quality data collection. The reliability, structure, and richness of their datasets dramatically simplified the system architecture.

Thanks to DEV.to for organizing this challenge! Without it, I would never have discovered these wonderful products and wouldn't have been able to create BrandGuard AI. This is an excellent example of how technical competitions promote learning new technologies and creating innovative solutions.

Beyond Caching: How Redis 8 Became Our Forum's Primary Database and AI Engine

Prema Ananda — Tue, 05 Aug 2025 11:33:59 +0000

This is a submission for the Redis AI Challenge: Beyond the Cache.

What I Built

I built CleanForum, a complete forum application where Redis 8 is not an accessory, but the central nervous system. It handles every aspect of the forum's data, from post and comment storage to real-time AI-powered spam moderation.

The Challenge: Escaping the "Database Zoo"

In modern web development, we often find ourselves managing a "zoo" of specialized databases. A typical stack might include PostgreSQL for primary data, Elasticsearch for search, a dedicated vector database like Pinecone for AI features, and, of course, Redis for caching. This complexity introduces overhead, synchronization challenges, and increased costs.

For my project, CleanForum, I set out with an ambitious goal: to build a full-featured, AI-powered forum using a single data platform. I wanted to challenge the conventional wisdom that Redis is "just a cache" and prove that with Redis 8, it can be the powerful, unified engine for an entire application.

Key Features at a Glance:

A Complete, Feature-Rich Forum: Users can create posts with Markdown, engage in discussions through comments, and browse content by categories.
Transparent AI Spam Protection: The crown jewel of the project. A sophisticated, hybrid system that combines traditional heuristic checks with advanced vector similarity analysis. It doesn't just block spam; it provides moderators with a detailed report explaining why a post was flagged.
Engaging "Similar Posts" Feature: To increase user retention, the system uses Redis's vector search capabilities to instantly suggest other relevant content, keeping users engaged on the site.
Instant Full-Text Search: The entire forum is searchable, with results delivered in milliseconds, powered by the same RediSearch index used for AI features.
Insightful Moderator Panel: A command center where moderators can review flagged content, see detailed spam analysis, and manually manage posts and comments, providing feedback to the system.

Demo

The application is live and fully functional. I invite you to test it out!

Live Application: forum.premananda.site
Video Demo:

premananda108 / CleanForum

A modern forum with an advanced spam protection system based on FastAPI and Redis Vector Search.

CleanForum 🛡️

A modern forum with an advanced spam protection system based on FastAPI and Redis Vector Search.

🚀 Features

🔒 Advanced Spam Protection

Vector analysis using SentenceTransformer (all-MiniLM-L6-v2)
Heuristic algorithms to detect spam patterns
Feedback system to improve accuracy
Redis Vector Sets for fast search of similar posts
k-NN classification with nearest neighbors voting

🏗️ Technology Stack

Backend: FastAPI, Python 3.8+
Database: Redis 7.0+ with Vector Search
ML model: SentenceTransformer
Frontend: Tailwind CSS, Vanilla JavaScript
Templates: Jinja2

📋 Functionality

✅ Create and edit posts
✅ Comment system
✅ Categories and tags
✅ Voting and ratings
✅ Moderator panel
✅ Forum search
✅ Automatic spam analysis
✅ Statistics and analytics

🛠️ Installation and Launch

Prerequisites

Python 3.8+
Redis 8.0+ with Vector Search support
Docker (optional)

1. Cloning and Installing Dependencies

git clone https://github.com/premananda108/CleanForum.git

# Go to the project directory
cd CleanForum
# Create a

…

View on GitHub

Here are some screenshots showcasing the application in action:

Home Page and Content

Post Page with Related Posts

Moderator Panel with Moderation Queue

Detailed Spam Analysis Report

How I Used Redis 8

Redis 8 is the architectural cornerstone of CleanForum. It allowed me to replace a potential stack of 3-4 different technologies with one elegant and hyper-efficient solution.

1. Redis Hashes as the Primary "Source of Truth" Database

Instead of a traditional SQL database, every core entity in the application is a Redis Hash.

Posts: Stored in keys like post:<uuid>, a hash contains the post's title, content, author ID, timestamps, and vote scores.
Users: user:<uuid> hashes store profile information, roles, and reputation.
Comments: comment:<uuid> hashes hold comment content and relationships.

This approach provides schema flexibility and the raw performance Redis is famous for. To manage relationships and create feeds, I heavily utilized Sorted Sets (ZSETs). For example, posts:all is a sorted set scored by timestamp, providing an instantly accessible, chronologically sorted list of all posts.

2. RediSearch for Dual-Purpose Search: Vector & Full-Text

This is where the "multi-model" power of Redis truly shines. I use a single RediSearch index to power two fundamentally different types of search.

To optimize this, I implemented a two-hash architecture:

The "Source of Truth" Hash (post:<id>): Contains the complete, rich data for a post.
The "Search Index" Hash (vector:post:<id>): A lightweight, separate hash containing only the data needed for indexing: the vector embedding and pre-processed text.

This separation is key: it keeps the search index incredibly lean and fast, while the main data can be as complex as needed without bloating the index. The index is configured to automatically pick up any new keys with the vector: prefix.

3. The Hybrid AI Engine: My Secret Sauce

The spam detection system is a perfect example of combining Redis features to create something powerful. It’s a two-stage process:

First Pass - Heuristic Analysis: The system first performs a rapid check for obvious spam indicators: suspicious keywords ("free", "crypto"), excessive capitalization, and patterns common in spam. This is handled in Python.
Second Pass - Vector Similarity Analysis: This is the core of the AI.
- A vector embedding is created from the new post's content.
- A K-Nearest Neighbor (KNN) query (*=>[KNN k @vector $blob]) is sent to RediSearch to find the most similar posts already in the database.
- The system then fetches the current, real-time is_spam status of these "neighbors" directly from their primary post:<id> hashes.
- A weighted score is calculated. If a post is highly similar to several posts that moderators have previously marked as spam, its own spam score skyrockets.

This synergy is incredibly powerful. The user-facing "Similar Posts" feature and the backend security system are powered by the exact same mechanism. It's efficient, elegant, and learns continuously from moderator feedback.

4. Deployment and Infrastructure

To prove that this powerful stack is accessible to everyone, the entire application is running on a modest Debian 12 virtual server with just 4GB of RAM. The Redis database itself is hosted on a free-tier cloud instance. This demonstrates that thanks to Redis's incredible efficiency, you don't need a massive budget or enterprise-grade hardware to build and run a sophisticated, AI-driven application.

Conclusion and Gratitude

This journey with the Redis AI Challenge has been more than just a competition; it has fundamentally changed my perspective on what's possible with a single database. Redis 8 is not just a cache—it is a legitimate, high-performance, multi-model database that can serve as the foundation for complex, modern applications. It challenged my architectural assumptions and enabled me to build a cleaner, faster, and more elegant system than I thought possible.

I want to extend my sincere gratitude to the teams at Redis and DEV.to for organizing this incredible challenge. The opportunity to push the boundaries, learn so much about vector search and AI implementation, and engage with this vibrant community has been an invaluable experience. I'm excited to see what I can build next with these powerful new tools at my fingertips.

Opening the "Black Box": A Journey into Vector Search and Spam Protection

Prema Ananda — Tue, 29 Jul 2025 11:00:29 +0000

This is a submission for the Redis AI Challenge: Real-Time AI Innovators.

How I built a spam fighting system with Redis 8 Vector Sets and what I learned about the inner workings of machine learning

What I Built

A spam classification system for dev.to that allows you to trace the entire journey from raw text to the final "spam/not spam" decision. Every step is transparent, measurable, and explainable.

In the era of ChatGPT and ready-made AI APIs, it's easy to forget that complex mathematics lies behind beautiful interfaces. When I started this project, I had a simple goal: to understand how vector search actually works, rather than just using it as a "magical" function.

Demo

premananda108 / redis8-spam-guard

🛡️ Redis8 Spam Guard

An intelligent spam classification system for dev.to posts using Redis 8 Vector Sets and FastAPI.

🎯 Features

Real-time classification - instant analysis of posts.
Redis 8 Vector Sets - leveraging the latest vector search technology.
FastAPI - a modern asynchronous API.
Machine Learning - classification based on k-NN with vector embeddings.
Interactive Web UI - a dashboard for moderators with real-time post classification, manual checking, statistics, and training logs.
Dynamic Data Enrichment - automatic loading of additional data, such as the author's follower count, for more accurate classification.
Feedback Loop - a system for improving the model based on moderator feedback.

🏗️ Architecture

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   Dev.to API    │ -> │  FastAPI Server  │ -> │  Redis 8        │
│ (Posts, Users)  │    │ (API, Web UI)    │    │  (Vector Sets)  │
└─────────────────┘    └──────────────────┘    └─────────────────┘

Components:

Data Collector - collects posts and user data from…

View on GitHub

The complete project code is available on GitHub. The system works in real-time and is ready for demonstration.

How I Used Redis 8

Vector Sets — More Than Just Search

Redis Vector Sets turned out to be not just a database, but a full-fledged semantic search engine. Creating the index:

schema = (
    VectorField("vector", "HNSW", {"TYPE": "FLOAT32", "DIM": self.vector_dim, "DISTANCE_METRIC": "COSINE"}),
    TagField("label"),
    TextField("title"),
    TagField("url")
)

HNSW (Hierarchical Navigable Small World) — this isn't just an algorithm, it's an entire philosophy of search. It builds a multi-level graph of connections between vectors, allowing you to find nearest neighbors in logarithmic time.

The Heart of Vector Search: How Redis Finds Similar Posts

The real magic happens in the vector search itself. The search for vectors occurs in the core.py file, inside the find_similar_posts method of the RedisVectorClassifier class.

Here's the specific code section that sends the query to Redis:

async def find_similar_posts(self, query_vector: np.ndarray, k: int = 5) -> List[Dict[str, Any]]:
    """Finds similar posts."""
    if not self.redis_client:
        return []
    try:
        # 1. Query formation
        query = (
            f"*=>[KNN {k} @vector $blob AS score]"
        )

        # 2. Executing the search command
        results = await self.redis_client.execute_command(
            "FT.SEARCH", self.index_name, query,
            "PARAMS", "2", "blob", query_vector.tobytes(),
            "DIALECT", "2",
            "RETURN", "3", "score", "title", "url"
        )

        # ... (result processing follows)

How this works:

query = f"*=>[KNN {k} @vector $blob AS score]": This line forms the search query itself.
- * — search across all documents in the index.
- => — apply the following operation to the results.
- [KNN {k} @vector $blob AS score] — this is the vector search command (KNN - k-Nearest Neighbors). It tells Redis: "Find k nearest neighbors in the vector field, using the vector we'll pass in the $blob parameter, and name the similarity field 'score'".
await self.redis_client.execute_command(...): This line sends the FT.SEARCH command to Redis, passing it:
- The index name (self.index_name).
- The formed query (query).
- The actual vector for search (query_vector.tobytes()) as the $blob parameter.

This command is what makes Redis use its powerful algorithm (HNSW) for ultra-fast search of the most similar vectors in the database.

k-NN — Democracy of Vectors

Classification of new posts happens through "voting" of nearest neighbors:

# Find 9 nearest neighbors
similar_posts = await self.find_similar_posts(query_vector, k=9)

# Collect their labels
labels = [post['label'] for post in similar_posts]

# Majority wins
predicted_label = Counter(labels).most_common(1)[0][0]
confidence = vote_count / total_neighbors

Magic in details: Why exactly k=9? After experiments, I found that an odd number of neighbors avoids ties, and 9 provides sufficient sampling without losing accuracy.

Redis as the Architecture Foundation

The system is built entirely around Redis Vector Sets capabilities. Without Redis, there is no system — it's not just a database, but the core of all classification logic.

Why Look Under the Hood?

Anatomy of "Training": What Actually Happens?

First Discovery: We Don't Train the Model

When people say "model training," they usually imagine a neural network learning from data. In my case, everything turned out differently. I don't train a model — I use the ready-made all-MiniLM-L6-v2 as a "translator" from human language to the language of mathematics.

# This isn't model training, it's creating a knowledge base
model = SentenceTransformer('all-MiniLM-L6-v2')
text_vector = model.encode("How to earn $1000 in a week!")
# We get an array of 384 numbers reflecting the text's meaning

The real "training" happens at the level of creating a database of vectors with correct labels.

But there's one "but": Redis still requires an external model for vectorization. It would be revolutionary if Redis could accept raw text and create vectors independently. Imagine:

# Dream: pass text, get ready search
await redis_client.hset("post:123", mapping={
    "text": "How to earn $1000 in a week!",  # Just text!
    "label": "spam"
})
# Redis creates the vector under the hood

Such integration would eliminate the need to manage separate embedding models and make Redis a truly self-sufficient AI platform.

Second Discovery: Automatic Labeling is an Art of Heuristics

The biggest problem of any ML project is obtaining labeled data. I didn't have thousands of posts with "spam/not spam" labels, so I had to create SpamLabelGenerator — a rule system for automatic labeling:

def calculate_spam_score(self, article: Dict) -> float:
    score = 0.0

    # Spam words in title (high weight)
    for keyword in self.spam_keywords:
        if keyword in title:
            score += 0.3

    # Short posts with low engagement
    if reading_time < 2 and reactions < 5:
        score += 0.3

    # Too many tags
    if len(tags) > 10:
        score += 0.2

    return min(max(score, 0.0), 1.0)

Challenge: How to find balance between precision and recall? Too strict rules — we miss spam, too lenient — we block legitimate content.

Solution: Added an element of randomness and multiple criteria. The system analyzes not only text, but also engagement metrics, author profile, publication time.

Third Discovery: Vectors Are Not Just Numbers

Initially, I thought a vector was just a "fingerprint" of text. In practice, it turned out you can create hybrid vectors by combining semantic embeddings with numerical features:

# Text vector (384 dimensions)
text_vector = self.model.encode(combined_text)

# Numerical features (3 dimensions)
numeric_features = np.array([
    reading_time,
    user_followers,
    len(tags)
])

# Combine into a single vector (387 dimensions)
final_vector = np.concatenate([text_vector, numeric_features])

Insight: Vector space can be "enriched" with any numerical data. Posts become similar not only in meaning but also in structure.

Redis as a "Card Index of Meanings"

Challenges and Solutions

Problem 1: Quality of Automatic Labeling

Challenge: How to verify that automatic labels are correct?

Solution: Added detailed logging and quality metrics:

metrics = {
    'accuracy': (tp + tn) / total,
    'precision': tp / (tp + fp),
    'recall': tp / (tp + fn),
    'f1_score': 2 * (precision * recall) / (precision + recall)
}

Problem 2: Data Imbalance — Too Little Spam

Challenge: Data from dev.to API contained very little real spam. The model couldn't learn effectively — it lacked examples of "bad" behavior.

Solution: Created a synthetic spam dataset and mixed it with real data:

# Load synthetic spam posts
try:
    with open('spam_dataset.json', 'r', encoding='utf-8') as f:
        spam_articles = json.load(f)
        # Mark as known spam
        for article in spam_articles:
            article['is_known_spam'] = True
        articles.extend(spam_articles)
except FileNotFoundError:
    logger.warning("spam_dataset.json not found")

Synthetic dataset composition (50 examples):

Quick money schemes and crypto scams
Phishing links and fake security notifications
SEO services sales and follower boosting
Dubious courses and "miracle products"

System Evolution: From Static to Self-Learning

The first version of the system had a critical flaw — it couldn't learn from its mistakes. Every moderator correction was lost after page reload.

Feedback Loop in Action

The solution turned out to be elegant: with each moderator click, the complete post content is saved in Redis with an expert verdict:

# Check for moderator verdict from Redis
feedback_key = f"feedback:{post.id}"
feedback_data = await redis_classifier.redis_client.get(feedback_key)
if feedback_data:
    feedback_json = json.loads(feedback_data)
    moderator_verdict = "spam" if feedback_json.get("is_spam") else "legit"

During the next training, this data is loaded with the highest priority, turning every mistake into an opportunity for improvement.

Dramatic Results

Before feedback loop:

Accuracy: 78-85%
Precision: ~85%

After implementation (just 9 expert corrections):

Accuracy: 96.4%
Precision: 100% — complete absence of false positives

Insight: 9 expert moderator decisions proved more valuable than 1000 automatically labeled posts. Data quality beats quantity.

Training Control Panel

The interface includes a "Training Control Panel" that displays current model information:

Last known accuracy
Number of trained examples (vectors in the database)

The actual retraining launches only after clicking the "Start New Training" button, and the process can be observed in real-time through automatically updated logs.

What I Learned About the "Black Box"

1. Vectors Have Geometry

Texts similar in meaning really are located close together in vector space. This isn't a metaphor — it's mathematical reality that can be measured through cosine distance or Euclidean norm.

2. Data Quality Matters More Than Algorithm

The most advanced algorithm won't help if the data is poorly labeled. 80% of project success is quality preparation of the training sample.

3. Explainability Can Be Built In

Every system decision is accompanied by detailed explanation:

reasoning = [
    "Similar to known spam posts (via Redis)",
    "Contains spam keywords: 'earn money'",
    "Low follower count (5)",
    "Short reading time (1 minute)"
]

4. Redis as Architecture Foundation

The system is built entirely around Redis Vector Sets capabilities. Without Redis, there is no system — it's not just a database, but the core of all classification logic.

Conclusions: Why Open the "Black Box"?

This project taught me that Redis Vector Sets isn't just a new feature, but a revolution in the approach to semantic search:

Speed: Vector search works in milliseconds even on thousands of records
Scalability: System is ready for growth without architectural changes
Transparency: Every decision can be traced and explained

Redis Vector Sets transformed the complex task of semantic search into an elegant and understandable solution.

Looking to the future: The next logical step would be to embed vectorization directly into Redis. Instead of the chain "text → external model → vector → Redis" we would get simply "text → Redis". This would make Redis the only component needed for a full-fledged AI system — from raw data to ready search results.