{"id":30855259,"url":"https://github.com/andrewchee/huggingface-uv-cursor","last_synced_at":"2026-04-12T09:02:28.616Z","repository":{"id":311235617,"uuid":"1042974989","full_name":"andrewchee/huggingface-uv-cursor","owner":"andrewchee","description":"macOS/MPS Hugging Face starter managed by uv; Jupyter, Accelerate, and Gradio; works in VS Code/Cursor.","archived":false,"fork":false,"pushed_at":"2025-08-22T23:34:01.000Z","size":9,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-09-07T17:29:41.189Z","etag":null,"topics":["accelerate","apple-silicon","cursor","gradio","huggingface","jupyter","macos","mps","python","pytorch","starter","template","transformers","uv"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/andrewchee.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-08-22T22:36:53.000Z","updated_at":"2025-08-22T23:36:23.000Z","dependencies_parsed_at":"2025-08-23T01:27:51.021Z","dependency_job_id":"1069ddc1-a967-4216-999d-21f9a4ab8cb1","html_url":"https://github.com/andrewchee/huggingface-uv-cursor","commit_stats":null,"previous_names":["andrewchee/huggingface-uv-cursor"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/andrewchee/huggingface-uv-cursor","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrewchee%2Fhuggingface-uv-cursor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrewchee%2Fhuggingface-uv-cursor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrewchee%2Fhuggingface-uv-cursor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrewchee%2Fhuggingface-uv-cursor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/andrewchee","download_url":"https://codeload.github.com/andrewchee/huggingface-uv-cursor/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrewchee%2Fhuggingface-uv-cursor/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278949274,"owners_count":26074000,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-08T02:00:06.501Z","response_time":56,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["accelerate","apple-silicon","cursor","gradio","huggingface","jupyter","macos","mps","python","pytorch","starter","template","transformers","uv"],"created_at":"2025-09-07T11:03:59.051Z","updated_at":"2025-10-08T13:16:56.925Z","avatar_url":"https://github.com/andrewchee.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# huggingface-uv-cursor\n\n![Python](https://img.shields.io/badge/Python-3.10%2B-blue)\n![uv](https://img.shields.io/badge/uv-managed-6E56CF)\n![macOS](https://img.shields.io/badge/MPS-Ready-black?logo=apple)\n![Transformers](https://img.shields.io/badge/🤗_Transformers-enabled-yellow)\n![JupyterLab](https://img.shields.io/badge/JupyterLab-ready-orange)\n![Gradio](https://img.shields.io/badge/Gradio-demo-green)\n![License](https://img.shields.io/badge/License-MIT-informational)\n\nmacOS/MPS‑optimized Hugging Face starter managed by uv; works in VS Code/Cursor. Jupyter, Accelerate, and Gradio included.\n\n## 🚀 Quick Start\n\n1. **Activate the virtual environment:**\n   ```bash\n   source .venv/bin/activate\n   ```\n\n2. **Run the demo script:**\n   ```bash\n   python src/demo.py\n   ```\n\n3. **Start JupyterLab:**\n   ```bash\n   jupyter lab\n   ```\n\n## 📁 Project Structure\n\n```\nhuggingface-uv-cursor/\n├── .vscode/\n│   └── settings.json          # VS Code/Cursor settings\n├── notebooks/\n│   └── intro.ipynb           # Jupyter notebook examples\n├── src/\n│   ├── demo.py               # Basic HF model demo\n│   ├── training_example.py   # Accelerate training demo\n│   └── gradio_demo.py        # Web interface demo\n├── data/                     # Data files (gitignored if large)\n├── .venv/                    # Virtual environment\n├── accelerate_config.yaml    # Accelerate configuration\n├── .gitignore               # Git ignore rules\n├── pyproject.toml           # Project dependencies\n└── README.md               # This file\n```\n\n## 🛠️ Setup\n\nThis project uses:\n- **uv** for fast Python package management\n- **PyTorch** with CPU wheels (MPS acceleration on Apple Silicon)\n- **Transformers** for pre-trained models\n- **Datasets** for data loading\n- **Accelerate** for distributed training\n- **JupyterLab** for interactive development\n- **Gradio** for web demos\n- **WandB** for experiment tracking\n\n## 🍎 Apple Silicon (MPS) Support\n\nThe project is configured to use MPS acceleration when available:\n\n```python\nimport torch\ndevice = \"mps\" if torch.backends.mps.is_available() else \"cpu\"\n```\n\n## 🔧 VS Code/Cursor Configuration\n\nThe `.vscode/settings.json` file configures:\n- Python interpreter pointing to `.venv/bin/python`\n- Automatic virtual environment activation\n- Jupyter notebook settings\n- Type checking mode\n\n## 📚 Examples\n\n### Basic Text Generation\n```python\nfrom transformers import pipeline\n\npipe = pipeline(\"text-generation\", model=\"sshleifer/tiny-gpt2\")\npipe.model.to(device)  # Move to MPS if available\nresult = pipe(\"Hello world:\", max_new_tokens=20)\n```\n\n### Model Loading\n```python\nfrom transformers import AutoTokenizer, AutoModelForCausalLM\n\ntokenizer = AutoTokenizer.from_pretrained(\"sshleifer/tiny-gpt2\")\nmodel = AutoModelForCausalLM.from_pretrained(\"sshleifer/tiny-gpt2\").to(device)\n```\n\n### Training with Accelerate\n```bash\npython src/training_example.py\n```\n\n### Web Demo with Gradio\n```bash\npython src/gradio_demo.py\n```\n\n## 💡 Gradio tips\n\n- **Pick a free port automatically**: we launch with `server_port=None`, so Gradio chooses an available port. If you prefer a fixed port:\n  ```bash\n  GRADIO_SERVER_PORT=7861 python src/gradio_demo.py\n  ```\n- **Local vs public link**:\n  - Local only (default): opens at `http://127.0.0.1:\u003cport\u003e`.\n  - Public share link:\n    ```python\n    # in src/gradio_demo.py\n    demo.launch(share=True)\n    ```\n    Useful for quick demos; anyone with the link can access while the app runs.\n- **Port already in use**: free 7860 and retry\n  ```bash\n  lsof -i :7860 | awk 'NR\u003e1{print $2}' | xargs -r kill\n  python src/gradio_demo.py\n  ```\n\n## 🚀 Next Steps\n\n1. **Authenticate with Hugging Face:**\n   ```bash\n   huggingface-cli login\n   ```\n\n2. **Explore models and datasets:**\n   - Visit [Hugging Face Hub](https://huggingface.co/)\n   - Try different models in `notebooks/intro.ipynb`\n\n3. **Create your own experiments:**\n   - Add new scripts in `src/`\n   - Create notebooks in `notebooks/`\n\n## 📦 Dependencies\n\nCore dependencies are defined in `pyproject.toml` and require Python 3.10+.\n\nInstall with uv (recommended):\n```bash\nuv pip install -e .\n```\n\nIf you prefer pip:\n```bash\npip install -e .\n```\n\n## 🔒 Privacy \u0026 safety\n\n- No secrets are committed. Authenticate locally with `huggingface-cli login`; tokens are stored in your keychain and never written to this repo.\n- Large artifacts and private data are ignored via `.gitignore` (`data/`, `datasets/`, model files, logs, caches).\n- Before making this public, quickly scan your git history for accidental secrets:\n  ```bash\n  git log -p | grep -iE \"(hf_|token|password|api|secret)\" || true\n  ```\n\n## 🧩 Use this as a template\n\nClick “Use this template” on GitHub or run:\n```bash\ngit clone \u003cyour-repo-url\u003e my-hf-sandbox\ncd my-hf-sandbox \u0026\u0026 ./setup.sh\n```\n\n\n## 🤝 Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Test with `python src/demo.py`\n5. Submit a pull request\n\n## 📄 License\n\nThis project is open source and available under the MIT License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandrewchee%2Fhuggingface-uv-cursor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fandrewchee%2Fhuggingface-uv-cursor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandrewchee%2Fhuggingface-uv-cursor/lists"}