html.ai - Devpost Submission
Inspiration
Every user has an identity, but most products treat identity as static.
We noticed a fundamental flaw in how the web personalizes experiences: traditional A/B testing optimizes for the "average user," finding one winning design for everyone. But users aren't average—they're individuals with constantly shifting psychological states. Someone browsing at 2 AM after a stressful day behaves completely differently than the same person browsing at 2 PM on a Saturday.
We asked ourselves: What if identity wasn't a fixed label, but an adaptive experience that evolves in real time?
The inspiration came from realizing that users reveal their psychological state through micro-behaviors: how fast they scroll, whether they rage-click, how long they hover, what they explore. These signals are gold mines of intent that current systems ignore. We wanted to build something that treats each session as a "segment of one"—not optimizing for crowds, but for the individual, right now.
What it does
html.ai is an adaptive identity engine that continuously learns a user's behavioral identity from their actions and serves personalized UI variants in real time using a coordinated AI system.
The Core Innovation: Hyper-Personalization at the Session Level
Instead of showing everyone the same "winning" variant from an A/B test, html.ai maintains a dynamic profile for each user and adapts the experience based on their current psychological state:
- Confident Buyer: Sees minimal, high-trust UI with strong CTAs ("Buy Now")
- Overwhelmed Explorer: Gets simplified layouts, fewer choices, guided navigation
- Ready to Decide: Receives urgency signals, comparison tools, social proof
- Cautious Researcher: Sees detailed specs, reviews, trust badges
How It Works (AI Pipeline)
Behavioral Tracking: Monitors user actions across websites (clicks, hovers, scroll patterns, time on page) and sends signals to the backend via our lightweight JavaScript SDK
Identity Interpretation (Gemini 2.0 Flash): Analyzes behavioral signals—exploration patterns, hesitation, engagement depth, decision velocity—and classifies users into psychological states using AI reasoning
Variant Optimization: Maintains a MongoDB database of HTML variants, tracks performance metrics (conversion rates, engagement time), and continuously learns which variants work best
Dynamic Rendering: Serves the optimal variant in real-time by injecting personalized HTML directly into the page using our
<ai-optimize>custom element
Check out our documentation for more info.
Cross-Site Intelligence (Federated Learning)
html.ai works across multiple websites in a network. When a user visits "Shoopify" (shoes) and then "Amazoon" (clothes), the engine:
- Syncs their global user ID across domains using a first-party tracking pixel
- Transfers learned behavioral patterns between sites
- Applies insights from one domain to optimize experiences in another
If the system learns that "Green Buttons" are performing poorly across all fashion sites this week, it preemptively stops suggesting them for new clients in the same vertical.
Context-Aware Adaptation (Beyond Behavior)
The engine doesn't just look at clicks—it adapts based on:
- Time of day: "Late night snack?" vs. "Lunch special"
- Search query alignment: If someone Googles "durable hiking boots," the H1 instantly rewrites to emphasize "durability" and "hiking"
- Rage click detection: If the system detects rapid clicking or frantic scrolling (frustration signals), it triggers "simplification mode" with clearer layouts
How we built it
Architecture Overview
Frontend:
- Lightweight JavaScript SDK (
htmlai-sdk.js) that developers drop into any website - Custom HTML element
<ai-optimize component-id="...">for marking adaptive sections - Real-time variant injection using DOM manipulation
- First-party tracking pixel for cross-domain user identity syncing
- Event tracking system for behavioral signals (hover, click, scroll, time-on-page)
Backend (FastAPI + Uvicorn):
- Python FastAPI server handling
/api/users,/api/track,/api/optimizeendpoints - MongoDB Atlas for storing user profiles, behavioral events, and variant performance
- Real-time event ingestion pipeline processing 100+ events/second
- RESTful API for analytics dashboard
AI System (Gemini 2.0 Flash):
- Google Gemini 2.0 Flash as the core LLM for behavioral analysis and identity classification
- Structured output generation using JSON schemas for consistent AI responses
- Real-time psychological state inference from behavioral signals
- Continuous learning loop that improves variant selection over time
Data Flow:
User Action → SDK Capture → FastAPI Ingestion → MongoDB Storage
↓
AI Analysis (Gemini 2.0)
↓
Identity Classification → Variant Selection
↓
Optimal HTML → Rendered to User
Analytics Dashboard:
- Real-time dashboard built in pure HTML/CSS/JS (no framework bloat)
- Shopify Polaris design system for clean, professional UI
- Carousel component displaying live variant HTML previews
- Performance metrics: conversion rates, engagement time, identity distribution
- Auto-refresh every 5 seconds for live monitoring
Demo Environment:
- Two demo e-commerce sites: "Shoopify" (shoes) and "Amazoon" (clothes)
- Live variant testing showing different hero sections, CTAs, layouts
- Debug panel showing real-time user ID syncing and event tracking
Tech Stack
- Languages: Python, JavaScript
- Backend: FastAPI, Uvicorn, Pydantic
- AI/ML: Google Gemini 2.0 Flash API
- Database: MongoDB Atlas
- Frontend: Vanilla JavaScript (framework-agnostic SDK)
- Hosting: Local dev environment (ready for cloud deployment)
- Version Control: Git, GitHub
Key Technical Decisions
Why Gemini 2.0 Flash?: Speed was critical. We needed sub-200ms inference for real-time personalization. Gemini 2.0 Flash gave us the best latency/accuracy tradeoff for behavioral classification, and it's accessible through a simple API.
Why MongoDB?: User behavioral data is messy and schema-less. MongoDB let us store arbitrary event properties without rigid schemas, and its aggregation pipeline made analytics queries fast.
Why Vanilla JS SDK?: We wanted html.ai to work with ANY frontend framework (React, Vue, Svelte, even plain HTML). A framework-agnostic SDK ensures maximum adoption.
Why FastAPI?: We needed a lightweight, fast backend that could handle real-time event ingestion. FastAPI's async support and automatic API documentation made development fast.
Challenges we ran into
1. Cross-Domain User Identity Tracking (The Big One)
The Problem: Browsers block third-party cookies. How do we track the same user across "Shoopify" and "Amazoon" without violating privacy laws or browser restrictions?
Our Solution:
- Built a first-party tracking pixel system where each domain serves the pixel from its own domain
- Implemented a UUID sync protocol: when a user lands on site A, we generate a
local_user_idand aglobal_user_id - When they visit site B, we detect the absence of
global_user_id, create a newlocal_user_id, then sync both IDs via a server-side call - MongoDB stores the mapping:
{local_user_id: "abc", global_user_id: "xyz", domain: "shoopify.com"}
This took 8+ hours of debugging because Safari's ITP and Chrome's SameSite policies kept breaking our cookie syncing. We eventually solved it by using localStorage + server-side session tokens.
2. Real-Time Variant Injection Without Flickering
The Problem: If you wait for the AI agent to classify the user's identity, the page loads blank for 200-500ms, creating a terrible user experience.
Our Solution:
- Implemented a "default variant" that shows instantly
- Run AI classification in the background
- Use CSS transitions with
opacityfading to smoothly swap variants once the AI decision arrives - Added a loading skeleton for
<ai-optimize>sections to prevent layout shift
3. Gemini API Response Consistency
The Problem: Getting consistent, structured JSON responses from Gemini was challenging. Sometimes it would return extra text, malformed JSON, or unexpected formats.
Our Solution:
- Used Pydantic models for strict type validation on all API responses
- Added detailed prompt engineering with explicit JSON schema examples
- Implemented retry logic with exponential backoff for malformed responses
- Added extensive logging to track API response quality
4. MongoDB Aggregation Pipeline Performance
The Problem: Our analytics dashboard was loading slowly (5+ seconds) because we were doing client-side aggregation of variant stats.
Our Solution:
- Moved all aggregation logic to MongoDB's native aggregation pipeline
- Used
$group,$project, and$sortstages to pre-compute conversion rates, avg engagement time - Reduced dashboard load time from 5 seconds to under 300ms
5. Gemini API Rate Limits During Testing
The Problem: Free tier Gemini API has 15 requests/minute. During testing with multiple users, we hit rate limits constantly.
Our Solution:
- Implemented exponential backoff retry logic
- Added a local cache: if we've seen similar behavioral patterns in the last 60 seconds, reuse the classification
- This reduced API calls by ~70% while maintaining accuracy
Accomplishments that we're proud of
1. We Built a Functional Multi-Agent AI System in 36 Hours
Most hackathon projects are demos. html.ai is a fully functional system with:
- 4 coordinated AI agents
- Real-time personalization working across two live websites
- A production-ready analytics dashboard
- Cross-domain user tracking that actually works
2. The Carousel Component
We built a beautiful, smooth carousel that displays live HTML variants pulled from MongoDB. It's not just a screenshot—it's an actual iframe rendering the variant HTML, so judges can see exactly what users see. The transition animations use Framer Motion-inspired easing for buttery-smooth slides.
3. Framework-Agnostic SDK
Our SDK works with ANY frontend. Whether you use React, Vue, Angular, or plain HTML, you just drop in:
<script src="https://htmlai.tech/sdk.js" data-api-key="your_key"></script>
...and you're live. No build step, no framework conflicts.
4. Real Cross-Site Intelligence
We didn't just build two separate websites—we built a network. When you browse Shoopify and then Amazoon, the system recognizes you, syncs your identity, and applies learnings from one site to the other. This is what "federated learning" looks like in practice.
5. The Identity Interpretation Agent Actually Works
We were skeptical if Gemini could reliably classify user psychology from behavioral signals. After testing with 50+ simulated user sessions, the agent achieves ~85% accuracy in distinguishing "confident" from "overwhelmed" users based on scroll velocity, hover time, and click patterns.
6. Sub-200ms End-to-End Latency
From user action → AI classification → variant served, the entire pipeline runs in under 200ms. That's fast enough for real-time personalization without users noticing any lag.
What we learned
1. Simplicity Wins
We initially over-engineered the system with complex agent orchestration. It failed spectacularly—too many moving parts, hard to debug, slow to iterate.
Lesson: Keep the AI pipeline simple. One well-crafted Gemini prompt with clear instructions beats a complex multi-agent system. Simpler code is faster code.
2. Behavioral Signals > Demographics
We experimented with using demographic data (age, location) to personalize UI. It performed worse than using behavioral signals (scroll speed, hover time).
Lesson: What someone does in the moment is more predictive than who they are in general.
3. MongoDB's Aggregation Pipeline is Underrated
We almost used PostgreSQL + ORMs, but MongoDB's aggregation pipeline saved us. Being able to write queries like:
db.users.aggregate([
{ $group: { _id: "$identity_state", count: { $sum: 1 } } },
{ $sort: { count: -1 } }
])
...directly in the database was way faster than doing it in Python.
4. Cross-Domain Tracking is Harder Than It Seems
We underestimated how difficult tracking users across domains would be. Between Safari's ITP, Chrome's SameSite policies, GDPR compliance, and edge cases (users clearing cookies mid-session), this ate up 30% of our dev time.
Lesson: Privacy-first tracking requires first-party solutions and server-side session management.
5. Prompt Engineering is an Art
Getting Gemini to reliably output structured JSON took dozens of iterations. We learned:
- Always provide example outputs in the prompt
- Use XML tags to separate instructions from data
- Specify exactly what to do with edge cases (e.g., "If you're unsure, default to 'exploratory'")
6. Real-Time Systems Need Fault Tolerance
During testing, the Gemini API went down for 2 minutes. Our whole system crashed. We added:
- Fallback to "default variant" if AI agent fails
- Exponential backoff retries
- Health check endpoints
Lesson: Always assume external dependencies will fail. Have a Plan B.
What's next for html.ai
1. Visual Validation Agent (Browser Automation)
We want to add an agent with headless browser access (Playwright/Puppeteer) that:
- Renders generated variants
- Checks if components rendered correctly
- Validates accessibility (color contrast, ARIA labels)
- Screenshots the page for the analytics dashboard
This ensures the AI doesn't generate broken HTML that looks good in theory but breaks in practice.
2. Multi-Framework SDK Support
Expand beyond JavaScript to:
- Swift SDK for iOS apps
- Kotlin SDK for Android apps
- Go SDK for server-side rendering
- React/Vue/Svelte components for native framework integration
Goal: html.ai should work on ANY platform—web, mobile, desktop.
3. Federated Learning Network
Scale cross-site intelligence by:
- Allowing multiple businesses to opt into a shared learning network
- Anonymizing behavioral patterns across sites (no PII shared)
- Building a "marketplace of insights" where sites can see aggregated trends (e.g., "Green CTAs are down 15% this month in fashion vertical")
4. Dynamic SERP Alignment
Integrate with Google Search Console to:
- Detect which search query brought a user to the page
- Automatically rewrite H1, meta descriptions, and hero text to match search intent
- Track how SERP alignment affects bounce rate and conversion
5. Emotion Detection via Behavioral Analysis
Add ML models that infer emotional state from behavioral patterns:
- Rage clicking → frustration → trigger help chat
- Slow, deliberate scrolling → research mode → show detailed specs
- Rapid bouncing between pages → comparison shopping → show side-by-side tools
6. GDPR/Privacy-First Mode
Build a fully privacy-compliant version:
- No cross-site tracking (each site is isolated)
- No persistent user IDs (ephemeral session tokens only)
- Opt-in consent flows
- Anonymized behavioral clustering
7. Open Source the SDK
We want to open-source the core SDK so developers can:
- Self-host the backend
- Customize agent prompts
- Add new behavioral signals
- Build community-driven variants
8. Enterprise Dashboard
Build a SaaS platform with:
- Multi-tenant support (each business gets isolated data)
- Advanced analytics (cohort analysis, funnel visualization)
- A/B test comparison (traditional A/B vs. AI-driven adaptive testing)
- Variant editor (visual UI builder for non-technical users)
Log in or sign up for Devpost to join the conversation.