tarekmasryo/QuickStart

⚡ QuickStart — Hugging Face Repo Quickstart Kit

QuickStart is a Gradio Space that turns Hugging Face repo URLs or Repo IDs into clean first-run artifacts: install commands, runnable Python snippets, snapshot download recipes, HF CLI commands, repo file previews, filename-based risk hints, badges, and a small exportable scaffold ZIP.

It is designed for the first practical question developers ask when they open a Hub repo:

“How do I start using this safely and quickly?”

🖼️ Preview

[image]

✨ What this Space does

• —🧭 Parses Hugging Face model, dataset, and Space URLs.
• —🔗 Accepts plain repo IDs such as bert-base-uncased or owner/repo.
• —🧪 Generates a best-effort Python starter snippet from repo metadata.
• —📦 Generates snapshot_download() code for full local downloads.
• —🖥️ Generates modern HF CLI commands using hf download.
• —📁 Shows a limited repo file table with quick filtering.
• —🛡️ Flags filename-based risk hints for secrets, keys, credentials, and large model artifacts.
• —🧰 Exports a starter ZIP containing run.py, download.py, requirements.txt, .env.example, and README.md.
• —🔒 Keeps server-side token usage disabled by default.

✅ Supported inputs

Repo IDs

<repo>
<owner>/<repo>

Examples:

bert-base-uncased
openai-community/gpt2

Hugging Face URLs

https://huggingface.co/<repo>
https://huggingface.co/<owner>/<repo>
https://hf.co/<owner>/<repo>
https://huggingface.co/<owner>/<repo>/tree/main
https://huggingface.co/<owner>/<repo>/blob/main/file.py
https://huggingface.co/<owner>/<repo>/discussions/1
https://huggingface.co/datasets/<owner>/<repo>
https://huggingface.co/datasets/<owner>/<repo>/viewer/default/train
https://huggingface.co/spaces/<owner>/<repo>

Short typed paths

datasets/<owner>/<repo>
spaces/<owner>/<repo>

🚀 How to use the Space

1. 1.Paste a Hugging Face repo URL or Repo ID.
2. 2.Keep repo type on auto, or choose model, dataset, or space manually.
3. 3.Click Generate.
4. 4.Copy the install command, Python snippet, download command, or generated badge.
5. 5.Use Build Zip when you want a minimal local starter scaffold.

📦 Exported ZIP contract

The generated ZIP intentionally stays small and reviewable:

run.py
        Minimal runnable starter snippet.

download.py
        Full snapshot download recipe.

requirements.txt
        Type-aware dependency list.

.env.example
        Token placeholder for gated/private repos.

README.md
        Short repo-specific usage notes.

This is a first-run starter, not a production project generator. Some repos need custom code, hardware, licenses, external files, or manual setup.

🔐 Public-safe default

QuickStart is safe to run publicly by default:

ALLOW_SERVER_TOKEN=0
HF_TOKEN=
TOKEN_ALLOWED_OWNERS=

With this default, the Space only queries public Hub metadata without using a server token.

🔒 Private or gated repos

Public repos work without a token.

Private or gated repos require an explicitly enabled and owner-scoped server token:

ALLOW_SERVER_TOKEN=1
HF_TOKEN=YOUR_TOKEN
TOKEN_ALLOWED_OWNERS=owner1,owner2

TOKEN_ALLOWED_OWNERS is required when server-token mode is enabled. This fail-closed behavior prevents an accidentally enabled token from being used against arbitrary repos.

Important: Do not enable server-token mode on a public Space unless you intentionally want visitors to access repos covered by TOKEN_ALLOWED_OWNERS through the Space runtime token. For private/internal usage, deploy the Space privately or keep server-token mode disabled.

Hugging Face Space secrets

Set these from Space Settings → Secrets only when needed:

HF_TOKEN
ALLOW_SERVER_TOKEN
TOKEN_ALLOWED_OWNERS

Recommended public Space configuration:

ALLOW_SERVER_TOKEN=0

Recommended private/internal Space configuration:

ALLOW_SERVER_TOKEN=1
TOKEN_ALLOWED_OWNERS=<trusted-owner-or-org>

🛡️ Risk hints limitation

QuickStart provides filename-based hints only.

It may flag names such as:

• —.env
• —token
• —api_key
• —credentials
• —.pem
• —.p12
• —id_rsa
• —large model artifacts such as .gguf, .onnx, .safetensors, and .bin

It does not scan file contents, validate licenses, inspect model behavior, verify model safety, or perform a security/compliance audit.

🧱 Project structure

.
├── app.py                   # Gradio UI and event wiring
├── quickstart_core.py        # Parsing, metadata, snippets, risk hints, ZIP export
├── assets/
│   └── Example.png           # Space preview screenshot
├── tests/
│   └── test_quickstart_core.py
├── requirements.txt          # Runtime dependencies for the Space
├── requirements-dev.txt      # Test/lint dependencies
├── pyproject.toml            # Ruff and pytest config
├── .env.example              # Optional token configuration template
├── .gitignore
├── LICENSE
└── README.md                 # HF Space card + documentation

🧪 Run locally

git clone https://huggingface.co/spaces/tarekmasryo/QuickStart
cd QuickStart

python -m venv .venv

# Windows PowerShell
.venv\Scripts\Activate.ps1

# macOS/Linux
source .venv/bin/activate

python -m pip install --upgrade pip
python -m pip install -r requirements.txt
python app.py

Then open the local Gradio URL shown in the terminal.

✅ Development checks

python -m pip install -r requirements.txt -r requirements-dev.txt
python -m ruff check .
python -m ruff format --check .
python -m compileall .
python -m pytest -q

Expected result for this version:

ruff check: passed
ruff format --check: passed
compileall: passed
pytest: passed

🚢 Deploy to Hugging Face Spaces

Create a new Space with:

SDK: Gradio
Hardware: CPU basic
App file: app.py
Python: 3.11

Then push these files to the Space repository:

git clone https://huggingface.co/spaces/<your-username>/QuickStart
cd QuickStart

# copy the project files into this folder

git add .
git commit -m "Initial Space release"
git push

The Space configuration is read from the YAML block at the top of this README.md.

📌 Notes

• —Generated snippets are best-effort and depend on Hub metadata.
• —Some repositories require custom code, extra files, GPU/VRAM, or manual setup.
• —Large repos should be downloaded selectively when possible.
• —Gated/private repositories require valid access permissions.
• —Server-side tokens should stay disabled for public demo usage.

📄 License

Apache License 2.0. See `LICENSE`.

Author: Tarek Masryo