README.md

metadata

title: Pokédex AI — Who's That Pokémon?
emoji: 🔴
colorFrom: red
colorTo: yellow
sdk: docker
app_port: 7860
pinned: true

🔴 Pokédex Web

Who's That Pokémon? Solved with Computer Vision.

A modern, responsive web application that uses a custom-trained ResNet-18 model to identify Pokémon silhouettes from multiple sources (Anime, Monkepo, Geroid, etc.) out of 1,025 different classes.

---

Table of Contents

• 🤔 What is Pokédex Web?
• ⚡ Get Started
• 🚀 Features
• 🛠️ Technical Stack
• 🏗️ Architecture
• 📄 License

🤔 What is Pokédex Web?

Pokédex Web is an AI-powered application designed to solve the classic "Who's That Pokémon?" challenge. Built with a production-ready monolithic containerized architecture, it pairs a fast Next.js static frontend with a FastAPI Python backend. The system processes images entirely in memory, utilizing a deep segmentation engine (BiRefNet) and a 5-model PokedexNet ensemble (ResNet-18) to classify silhouettes across 1,025 distinct species.

⚡ Get Started

1. Prerequisites

• Python 3.12+
• Node.js 20+
• uv
• Docker

2. Local Development (Split Servers)

For an optimal development experience, run both servers simultaneously. The Next.js frontend is configured to automatically route API requests to the backend locally.

Terminal 1 (Backend):

cd pokedex_web/backend
uv venv
source .venv/bin/activate
uv pip install -r requirements.txt
uvicorn app:app --reload --port 7860

Terminal 2 (Frontend):

cd pokedex_web/frontend
npm install
npm run dev
# The frontend runs on http://localhost:3000 and auto-connects to the backend at 7860

3. Production Monolith (Local Testing)

To test the production-ready Single Page Application (SPA) exactly as it will run on Hugging Face Spaces (everything served from port 7860):

# 1. Build the Next.js static export
cd pokedex_web/frontend
npm install
npm run build

# 2. Copy the static files to the backend
rm -rf ../backend/static
cp -r out ../backend/static

# 3. Run FastAPI (serves both REST API and the Frontend)
cd ../backend
source .venv/bin/activate
uvicorn app:app --port 7860
# Access the complete app at http://localhost:7860

4. Deployment (Docker & Hugging Face Spaces)

This project includes a production-ready, multi-stage Dockerfile strictly optimized for Hugging Face Spaces (Free Tier). It automatically:

1. Builds the Next.js static SPA fallback.
2. Creates a secure, non-root user (UID 1000).
3. Optimizes Memory: Forces the installation of CPU-only PyTorch wheels, reducing the image size from ~2.5GB to ~500MB to prevent OOMKilled errors on free instances.

Running Locally via Docker:

cd pokedex_web
docker build -t pokedex-web .
docker run -p 7860:7860 pokedex-web
# The app will be available at http://localhost:7860

Deploying to Hugging Face Spaces:

1. Create a new Space on Hugging Face.
2. Select Docker as the SDK.
3. Push this repository to the provided Git remote. The Space will automatically detect the Dockerfile, build the optimized container, and serve the application.

🚀 Features

• Deep Segmentation Engine: Extracts continuous subject masks using BiRefNet with an automated multi-resolution fallback architecture (768×768 baseline, 1024×1024 fallback) to recover delicate anatomical structures.
• High-Accuracy Ensemble Inference: Identifies 1,025 distinct Pokémon classes using a trained ResNet-18 architecture, combining predictions across independent runs.
• Hierarchical Open-Set Recognition: Employs an ensemble of five models (seeds 3, 7, 25, 121, and 255). Features Stage-One Baseline Logit Thresholding ($\ge 6.0$) to discard abstract noise, and Stage-Two Strictness Ladder (Decision Hierarchy) operating across signal tiers and epistemic consensus (unique_predictions_count) to intercept out-of-distribution and ambiguous inputs.
• Active Learning Telemetry Flywheel: Automatically logs predictions triggering uncertainty warnings or divergent rejections and securely uploads telemetry payloads to Hugging Face datasets, driving a continuous model optimization loop.
• Scientific Documentation: Includes an embedded Research Paper route (/research) detailing the dataset preparation, method, and structural adaptations of the ResNet-18 model.
• Zero Disk Writes: Inference is processed entirely in memory (bytes to np.ndarray), optimizing execution speed and security on free-tier cloud environments.
• Client-Side Image Resizing: The frontend uses HTML5 Canvas to resize images before upload, saving bandwidth and backend CPU cycles.
• Premium UX/UI (Neon Glassmorphism): Asymmetrical layouts with an animated liquid aurora mesh background (radial-gradient + filter: blur), deep iOS/macOS frosted glass blurs, sleek SVG iconography, suspenseful prediction delays, and staggered CSS animations.
• Zero Trust Security: Strictly operates via environment variables. No secrets or .env files are tracked in the repository.
• Seamless HF Spaces Deploy: Fully configured with a multi-stage Dockerfile and Git LFS for automated Hugging Face Spaces deployment.

🛠️ Technical Stack

• Backend: Python (FastAPI, uvicorn)
• Machine Learning: PyTorch, torchvision, BiRefNet, OpenCV (Headless)
• Frontend: JavaScript (Next.js, React, CSS Modules)
• Tooling: uv (dependency management), Ruff (linting/formatting), mypy (static typing)
• Infrastructure: Docker (Multi-stage build), Hugging Face Spaces

🏗️ Architecture

Key principles include:

1. Monolithic Containerized: Single Docker container serving both REST API and static frontend.
2. FastAPI Serve All: Uvicorn handles both API endpoints and SPA static file fallback (html=True).
3. In-Memory Ensemble: All five PyTorch weight files (*.pth, tracked via Git LFS) are loaded once at startup into an ensemble of independent ResNet-18 classifiers. Each model was trained from scratch with a different random seed (3, 7, 25, 121, 255), ensuring representational diversity. Inference aggregates predictions via Softmax Averaging, utilizing BiRefNet segmentation and a two-stage hierarchical decision filter (Strictness Ladder) operating on raw logit strength and epistemic agreement.

🚀 Deployment and Production Architecture

To transition from the experimental environment to production deployment, the trained artifact is served natively through a high-performance backend engineered to optimize inference workflows. The deployment architecture leverages zero-copy memory structured inference, a technique that minimizes tensor serialization and deserialization overhead, ensuring ultra-low latencies in the millisecond range.

This infrastructure enables the model to process requests with stability and near-instantaneous response times, ensuring that the methodological rigor maintained during training translates into a final user experience defined by high availability and real-time predictive precision. Consequently, the system not only meets scientific validation requirements but also establishes itself as a technically viable solution for visual recognition tasks involving high morphological complexity.

📄 License

This project is licensed under the MIT License.