HACKATHON_GUIDE.md

# Build Small Hackathon -- The Complete Winning Guide

## Table of Contents

1. [Hackathon Overview](#hackathon-overview)
2. [What the Judges Want](#what-the-judges-want)
3. [Small Language Models -- Theory & Education](#small-language-models)
4. [Gradio -- Theory & Education](#gradio)
5. [Your Real Problem & Winning Strategy](#your-winning-strategy)
6. [Technical Stack & Hosting](#technical-stack--hosting)
7. [Bonus Quests to Earn](#bonus-quests)
8. [Pitch & Demo Tips](#pitch--demo-tips)
9. [Timeline & Checklist](#timeline--checklist)

---

## Hackathon Overview

**Name:** Build Small Hackathon
**Hosted by:** Gradio + Hugging Face
**URL:** https://huggingface.co/build-small-hackathon
**Dates:** May 29 -- June 8, 2026 (two weekends to build, ship, and demo)
**Cash Prizes:** $15,000
**Registration deadline:** May 27, 2026

### The Philosophy

The hackathon motto is **"Making AI Fun Again."** The organizers feel AI has become anxiety-inducing -- labs keep releasing bigger and bigger models doing things that feel threatening. This hackathon wants to bring back the 2021 vibe: when models were small enough to tinker with, and building with AI was joyful and personal.

The core instruction: **Think small.** Armed with only 32 billion parameters, solve a real problem for someone you know -- or build something whimsical and delightful.

### Two Tracks (Pick One)

#### Track 1: "Backyard AI" (Chapter One) -- YOUR TRACK

> Solve a real problem for someone you actually know. Pick a person -- a neighbor, a parent, a small-business owner on your street -- and build something that makes their day measurably better.

**Judged on:**
- Problem is specific and real
- The person actually *used* it
- Honest fit between problem and the small-model constraint
- Polish of the Gradio app

#### Track 2: "An Adventure in Thousand Token Wood" (Chapter Two)

> Build something delightful that wouldn't exist without AI. A toy, a tiny game, a strange interactive story, an art experiment. The AI should be doing the fun thing -- not just helping you build it. Strange is good. Joyful is the bar.

**Judged on:**
- Genuinely delightful (would you show a friend?)
- AI is load-bearing for the experience
- Originality of concept
- Polish of the Gradio app

### Three Hard Rules ("Pack Light")

| # | Rule | What It Means |
|---|------|---------------|
| 1 | **Small Models Only** | Total parameters must be **<= 32 billion**. The model must fit on a laptop. |
| 2 | **Built on Gradio** | Your app must be a **Gradio app**, hosted as a **Hugging Face Space**. |
| 3 | **Show, Don't Tell** | Submit a short **demo video** and a **social-media post** alongside your Space. |

### The Deliverable (What You Actually Submit)

1. **A running Gradio app** hosted as a Hugging Face Space under the `build-small-hackathon` org
2. **A short demo video** (screen recording showing the app in action)
3. **A social media post** (tweet, LinkedIn, etc.) about your project

That's it. No slides. No paper. A working app, a video, and a post.

---

## What the Judges Want

### Judge Mindset (Track 1 -- Backyard AI)

The judges are looking for projects where **a real person has a real problem, and AI genuinely helps.** They are NOT impressed by:
- Generic productivity tools
- Yet another RAG chatbot
- Technical complexity for its own sake

They ARE impressed by:
- **Authenticity** -- "I built this for myself / my own business"
- **Before vs. After** -- "This used to take 3 hours, now it takes 10 minutes"
- **Honest constraint fit** -- "I chose a small model because the task is structured extraction, not novel reasoning"
- **Polish** -- The Gradio app looks finished, not like a prototype

### The Secret Scoring Formula

| Criteria | Weight | What Wins |
|----------|--------|-----------|
| Real problem, real person | HIGH | You ARE the person. Show real documents, real store names. |
| Honest small-model fit | HIGH | Explain WHY a small model works: parsing structured docs, not writing novels |
| Gradio polish | HIGH | Beautiful UI, smooth flow, no jank |
| Actually used | MEDIUM | Demo with your actual PO documents and store data |

### The Meta-Game

Judges spend **3-10 minutes** per project. Your app must instantly communicate:
1. What the problem is
2. What the AI is doing
3. Why it's cool

---

## Small Language Models

### What Is a "Small" Model?

In this hackathon, "small" means **<= 32 billion parameters**. For context:
- GPT-4 is rumored to be ~1.8 trillion parameters
- Claude, Gemini are similarly massive
- A 3B model is roughly 600x smaller than GPT-4

Parameters are the "brain cells" of a neural network. More parameters = more knowledge and reasoning ability, but also more compute, memory, and cost.

### Size Tiers and What They're Good For

| Size | Examples | RAM Needed | Good For | Limitations |
|------|----------|-----------|----------|-------------|
| **0.5B -- 1.5B** | Qwen2.5-0.5B/1.5B, Llama 3.2-1B | 0.5--1 GB | Simple extraction, classification, formatting | Limited knowledge, short context |
| **3B** | Qwen2.5-3B, Llama 3.2-3B, Phi-3-mini | ~2 GB | Structured extraction, summarization, translation | Struggles with complex multi-step logic |
| **7B -- 8B** | Llama 3.1-8B, Mistral-7B, Qwen2.5-7B | ~5 GB | Strong extraction, conversation, code generation | Needs 8GB+ RAM machine |
| **14B** | Qwen2.5-14B, Phi-4-14B | ~10 GB | Good reasoning, strong coding, multi-language | Needs 16GB+ RAM, GPU recommended |
| **27B -- 32B** | Gemma-2-27B, Qwen2.5-32B | ~20 GB | Near-GPT-3.5 quality for many tasks | Needs 32GB RAM or GPU |

### Your Laptop: 6 GB RAM

Your AMD Ryzen 7 3700U with 6 GB RAM can run:
- **Qwen2.5:1.5b** -- comfortably (needs ~1 GB)
- **Qwen2.5:3b** -- tight but possible (needs ~2 GB)
- **Qwen2.5:7b** -- NOT possible (needs ~5 GB, your machine only has ~1.5 GB free)

**For the hackathon demo on HF Spaces**: The model runs on HF's servers, not your laptop. RAM doesn't matter.

**For local development**: Use the HF Inference API (free tier) -- the model runs in the cloud. Your laptop just runs the Gradio UI.

### Why Small Models Are GOOD (Not Just "Acceptable")

This is key for your pitch:

1. **Privacy:** Store sales data, supplier info, pricing -- stays private. Indonesian small businesses don't want data going to OpenAI.

2. **Cost:** Zero API fees. No monthly subscription. A small business owner can run this forever for free on a decent laptop.

3. **Right-sizing:** Parsing "20 sticker kucing hologram 5x5cm" from a messy PO document is structured extraction -- you DON'T need GPT-4 for this. A 3B model handles it perfectly.

4. **Speed:** For structured tasks, small models are often FASTER than cloud APIs because there's no network latency.

5. **Accessibility:** Works for Indonesian small businesses who may not have reliable internet or cloud budgets.

### What Small Models Do Well (YOUR Use Cases)

- **Structured data extraction from messy formats** -- THE core of your app. Different stores send POs in Excel, PDF, handwritten, different formats. LLM normalizes them all into structured data.
- **Text formatting/templating** -- Generating delivery documents, order summaries
- **Translation** -- English/Indonesian bilingual output
- **Summarization** -- Best seller reports, monthly summaries
- **Classification** -- Categorizing sticker types, matching product names across stores

### What Small Models Struggle With

- Open-ended creative writing
- Complex multi-step mathematical reasoning
- Tasks requiring broad world knowledge
- Very long context (>4K tokens on smaller models)

---

## Gradio

### What Is Gradio?

Gradio is a **Python library for building web-based UI for machine learning apps.** You write Python, and Gradio generates a full interactive web app.

Key facts:
- Made by Hugging Face (the hackathon host -- using it well MATTERS)
- Write **only Python** -- no HTML, CSS, or JavaScript needed (though you can add custom CSS)
- Generates a **shareable web URL** automatically
- Deploys to **Hugging Face Spaces** with one click
- Has 30+ built-in components (text boxes, tables, file uploads, buttons, chat interfaces, etc.)

### Gradio Core Concepts

#### 1. Interface (Simple Mode)

The simplest way. Define inputs, outputs, and a function:

```python
import gradio as gr

def greet(name):
    return f"Hello, {name}!"

demo = gr.Interface(fn=greet, inputs="text", outputs="text")
demo.launch()
```

#### 2. Blocks (Advanced Mode) -- WHAT YOU SHOULD USE

Full layout control with rows, columns, tabs:

```python
import gradio as gr

with gr.Blocks(title="My App") as demo:
    gr.Markdown("# My App Title")
    with gr.Row():
        with gr.Column(scale=1):
            input_text = gr.Textbox(label="Input", lines=5)
            submit_btn = gr.Button("Submit", variant="primary")
        with gr.Column(scale=2):
            output_table = gr.Dataframe(label="Results")
    submit_btn.click(fn=process, inputs=input_text, outputs=output_table)

demo.launch()
```

#### 3. Key Components You'll Use

| Component | What It Does | Your Use Case |
|-----------|-------------|---------------|
| `gr.Textbox` | Text input/output | Paste PO text from stores |
| `gr.Dataframe` | Editable table | Show parsed orders, stock levels |
| `gr.Markdown` | Rich text display | Delivery documents, reports |
| `gr.Button` | Clickable button | Submit, Export, Generate |
| `gr.File` | File download | Export CSV |
| `gr.Dropdown` | Select from options | Choose store |
| `gr.Tab` | Tabbed interface | Organize PO intake, stock, print calc, delivery |
| `gr.Number` | Numeric input | Edit quantities |
| `gr.State` | Persist data between interactions | All session data |

#### 4. Theming & CSS (For Polish)

```python
# Built-in themes available: Soft, Glass, Monochrome, Default
# Custom CSS also supported for branding
demo.launch(theme=gr.themes.Soft(), css="custom styles here")
```

#### 5. State Management

```python
# gr.State persists data across interactions within a session
store_data = gr.State(value={})

def update_store(new_data, current_data):
    current_data.update(new_data)
    return current_data

button.click(fn=update_store, inputs=[input, store_data], outputs=[store_data])
```

### Gradio + Hugging Face Spaces (Deployment)

Your final app must be hosted on Hugging Face Spaces:

1. Create a Space under the `build-small-hackathon` org
2. Choose "Gradio" as the SDK
3. Push your `app.py` + `requirements.txt` via git
4. The Space auto-builds and deploys
5. You get a public URL that judges can visit

**Free tier:** Yes, free CPU instances. Good enough for a hackathon demo.

**How to push:**
```bash
# Clone the space
git clone https://huggingface.co/spaces/build-small-hackathon/your-app-name
# Copy your files in
# Push
git add . && git commit -m "Initial app" && git push
```

For the model on HF Spaces, use the **Hugging Face Inference API** (free tier) -- the model runs on HF servers, not on the Space's CPU.

---

## Your Winning Strategy

### The REAL Problem (This Is Gold for Hackathon Judges)

You run a sticker shop in Jogja, Indonesia. You design and sell ~150 varieties of stickers through **25 offline partner stores** across Java island (Solo, Klaten, Semarang, Jakarta, Bandung, Bali, etc.). Each store gets your stickers on consignment (they pay you a % of sales).

**The monthly workflow (currently manual, ~3+ hours):**

1. **Receive reports from 25 stores** -- Each store sends a monthly sales report AND a Pre-Order (PO) for restocking. Every store uses a DIFFERENT format: Excel, PDF, handwritten, Indonesian, English, mixed.

2. **Parse and normalize** -- You manually read each report/PO and type the data into your own spreadsheet. 25 stores x different formats = tedious.

3. **Aggregate demand** -- Combine all 25 POs to see total demand per sticker variety.

4. **Check home stock** -- Compare aggregated demand against what you have in stock at home.

5. **Calculate printing** -- For stickers you need to produce, calculate how many A3 sheets to order from your printer (each A3 = 8 x A5 stickers, so divide quantity by 8, round up).

6. **Place print order** -- Send order to external printing service.

7. **Generate delivery documents** -- After printing, create a packing list for each store: "Store X, here are the stickers I'm sending you." This helps them match incoming shipments.

8. **Recommend best sellers** -- Some stores ask "What should I order?" You check sales data across all stores and recommend top sellers.

### Why This Is a PERFECT Hackathon Entry

| Judge Criteria | Your Score | Why |
|----------------|-----------|-----|
| Problem is specific and real | 10/10 | You literally do this every month. 25 real stores. Real documents. |
| Person actually used it | 10/10 | YOU are the person. You can demo with real data. |
| Honest small-model fit | 10/10 | Parsing messy POs into structured data is EXACTLY what small models excel at. No need for GPT-4. |
| Gradio polish | High | Multi-tab workflow, clean tables, export buttons, bilingual |

### The Pitch (Practice This)

> "I run a sticker shop in Jogja, Indonesia. I sell 150 designs through 25 partner stores across Java. Every month, each store sends me sales reports and restock orders -- in 25 different formats. Excel, PDF, handwritten notes, Indonesian, English. I spend 3+ hours every month just copying data into spreadsheets. Then I have to calculate what to print, and create delivery documents for each store.
> 
> I built an AI assistant that does all of this. Paste in any store's PO -- any format -- and a 3-billion parameter model extracts the structured data. It aggregates across stores, calculates my print order (A3 sheets, 8 stickers per sheet), and generates delivery documents in both English and Indonesian.
> 
> All running on a tiny model. Because parsing 'butuh 20 stiker kucing hologram' doesn't need GPT-4."

### App Features (What We Build)

#### Tab 1: PO Intake (Parse Store Orders)
- Select store from dropdown
- Paste PO text in any format (messy Excel copy, handwritten transcription, mixed languages)
- AI extracts: product name, quantity, notes
- Review and edit parsed data
- Save to session

#### Tab 2: Stock & Demand Dashboard
- View home stock levels (editable)
- See aggregated demand from all parsed POs
- Visual comparison: what you have vs. what stores want
- Highlight shortages

#### Tab 3: Print Calculator
- Shows what needs to be printed (demand - stock = shortage)
- Calculates A3 sheets needed (qty / 8, rounded up)
- Estimated cost
- Export print order

#### Tab 4: Delivery Documents
- Select a store
- Generate packing list of what to send them
- Bilingual (English / Indonesian)
- Export as text

#### Tab 5: Best Seller Report
- AI analyzes sales data across stores
- Recommends top sellers to stores that ask

---

## Technical Stack & Hosting

### What You Need

| Component | Tool | Why |
|-----------|------|-----|
| Language | **Python 3.11** | Only language needed |
| UI Framework | **Gradio 6.x** | Required by hackathon |
| LLM (Cloud) | **HF Inference API + Qwen2.5-3B** | Free, runs on HF servers, no local RAM needed |
| LLM (Local) | **Ollama + Qwen2.5:3b** (optional) | For offline/privacy demo on a machine with 8GB+ RAM |
| Data | **pandas** | CSV export, data manipulation |
| Deployment | **Hugging Face Spaces** | Required by hackathon. Free tier. |

### How the App Works

```
Store sends PO (messy text) --> You paste into Gradio UI --> 
Python sends to HF Inference API --> Qwen2.5-3B parses it --> 
Structured JSON returned --> Gradio displays editable table --> 
Python aggregates + calculates print needs --> Export
```

### Hosting on Hugging Face Spaces

**Cost: FREE** for the basic CPU tier. This is enough for your hackathon demo.

**What HF Spaces gives you:**
- Public URL (e.g., `https://huggingface.co/spaces/build-small-hackathon/your-app`)
- Auto-builds from your code
- Judges click the link and use your app instantly
- The LLM runs via HF Inference API (on HF's powerful servers), not on the Space's tiny CPU

**How to deploy (step by step):**
1. Create a free account on huggingface.co
2. Get a free API token (Settings > Access Tokens)
3. Create a new Space under `build-small-hackathon` org
4. Push your code via git
5. Set your HF token as a Space Secret (so the Inference API works)
6. Done -- your app is live

**It is NOT like AWS.** It's much simpler:
- No servers to configure
- No Docker files needed (Gradio Spaces handle it)
- No billing surprises (free tier has limits but won't charge you)
- Judges don't need accounts to use your app

---

## Bonus Quests

| Badge | Requirement | Recommendation |
|-------|------------|----------------|
| **Off the Grid** | No cloud APIs, fully local | Can demo this on a machine with 8GB+ RAM using Ollama. Mention it in pitch. |
| **Off-Brand** | Custom frontend beyond default Gradio | **DO THIS** -- custom CSS with your sticker shop branding |
| **Well-Tuned** | Fine-tuned model on HF | Skip (not enough time) |
| **Llama Champion** | Use llama.cpp runtime | Nice-to-have only |
| **Sharing is Caring** | Share agent trace on Hub | **DO THIS** -- easy, free |
| **Field Notes** | Blog post about the build | Do if time allows |

---

## Pitch & Demo Tips

### Demo Video Structure (60--90 seconds)

1. **Hook (10s):** "I sell stickers through 25 stores across Indonesia. Every month I spend 3 hours processing their orders manually."
2. **Problem (15s):** Show the messy reality -- different Excel formats, handwritten POs, mixed languages.
3. **Solution (40s):** Paste a real PO. Watch AI parse it. Show aggregation. Show print calculator. Show delivery document.
4. **Wow moment (10s):** "3 billion parameters. That's all you need to turn chaos into a clean order."
5. **Close (10s):** "Built with Gradio + Qwen2.5-3B for the Build Small Hackathon."

### What to Highlight

- The 25-store scale (real business, not a toy example)
- Before vs. after (3 hours -> 10 minutes)
- The variety of input formats (your unique challenge)
- Bilingual English/Indonesian
- The print calculator (a practical non-AI feature that adds real value)
- That 3B parameters is MORE than enough for structured extraction

### Common Mistakes to Avoid

1. Don't over-engineer -- a clean, working demo beats a half-finished ambitious project
2. Don't use jargon -- say "Paste your store's order" not "Enter NLP query"
3. Don't forget examples -- pre-fill sample POs so judges can try instantly
4. Don't make it generic -- the Indonesia sticker shop angle is your ADVANTAGE

---

## Timeline & Checklist

### Before May 29 (Prep Phase -- NOW)

- [x] Read hackathon guidelines
- [x] Define your idea and track
- [ ] Register on Hugging Face
- [ ] Join Gradio Discord
- [x] Install Python, Gradio locally
- [x] Build and test prototype locally
- [ ] Prepare real PO documents from your stores (anonymize if needed)
- [ ] Get HF API token (free)

### May 29 -- June 1 (Weekend 1)

- [ ] Create your HF Space under the build-small-hackathon org
- [ ] Polish the Gradio UI (custom CSS, sticker shop branding)
- [ ] Add all features (PO parsing, aggregation, print calc, delivery docs)
- [ ] Test with real PO data from your stores
- [ ] Deploy to HF Spaces

### June 2 -- 5 (Midweek)

- [ ] Record demo video
- [ ] Write social media post
- [ ] Attend Live AMA if possible
- [ ] Bug fixes and polish

### June 6 -- 8 (Weekend 2)

- [ ] Final polish and testing
- [ ] Submit: Space link + demo video + social post

---

## Quick Reference Card

```
HACKATHON:   Build Small Hackathon
TRACK:       Chapter One -- Backyard AI
IDEA:        Sticker Restock Manager -- AI-powered PO parser & print calculator
PERSON:      You (sticker shop owner in Jogja, 25 partner stores across Java)
MODEL:       Qwen2.5-3B (3B params, via HF Inference API)
UI:          Gradio Blocks with custom CSS
DEPLOY:      Hugging Face Space (free tier)
LANGUAGES:   English + Indonesian
DEADLINE:    June 8, 2026
PRIZE POOL:  $15,000
```