---
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?](#-what-is-pokedex-web)
- [⚡ Get Started](#-get-started)
- [🚀 Features](#-features)
- [🛠️ Technical Stack](#-technical-stack)
- [🏗️ Architecture](#-architecture)
- [📄 License](#-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+](https://www.python.org/downloads/)
- [Node.js 20+](https://nodejs.org/)
- [uv](https://docs.astral.sh/uv/)
- [Docker](https://docs.docker.com/get-started/)
### 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):**
```bash
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):**
```bash
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):
```bash
# 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:
```bash
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.