HACKATHON_GUIDE.md

Build Small Hackathon -- The Complete Winning Guide

Table of Contents

1. Hackathon Overview
2. What the Judges Want
3. Small Language Models -- Theory & Education
4. Gradio -- Theory & Education
5. Your Real Problem & Winning Strategy
6. Technical Stack & Hosting
7. Bonus Quests to Earn
8. Pitch & Demo Tips
9. 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:

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:

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)

# 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

# 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:

# 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)

• Read hackathon guidelines
• Define your idea and track
• Register on Hugging Face
• Join Gradio Discord
• Install Python, Gradio locally
• 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