axiom-coding-agent-setup 1.1.1 → 1.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.agents/skills/huggingface-deployment/SKILL.md +230 -0
- package/README.md +1 -0
- package/bin/cli.js +1 -0
- package/package.json +1 -1
- package/error/error.md +0 -57
|
@@ -0,0 +1,230 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: huggingface-deployment
|
|
3
|
+
description: Deploy and auto-deploy apps to Hugging Face Spaces from a GitHub repository. Use when setting up HF Space deployment pipelines, fixing Space build/CONFIG errors, debugging failed deploys, checking Space state, or diagnosing HF rate-limit failures. Triggers - "deploy to huggingface", "hf space", "huggingface sync", "CONFIG_ERROR", "space rebuild", "429 hub", "git push space".
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Hugging Face Space Deployment via GitHub
|
|
7
|
+
|
|
8
|
+
## Overview
|
|
9
|
+
|
|
10
|
+
How to deploy a project to a Hugging Face Space automatically whenever a GitHub repository is updated, hard lessons learned from a real production failure (rate-limited mid-deploy, broken/emptied Space), and the APIs used to debug Space state.
|
|
11
|
+
|
|
12
|
+
Core deployment strategies (in order of preference):
|
|
13
|
+
|
|
14
|
+
| Strategy | How | Pros | Cons |
|
|
15
|
+
|---|---|---|---|
|
|
16
|
+
| **`git push space`** (recommended) | CI pushes git history directly to the Space's git remote | 1 commit per push; incremental; native deletions; no SDK | Pushes all git-tracked files; needs LFS tracked properly |
|
|
17
|
+
| **Official `huggingface/hub-sync` action** | GitHub Action that mirrors files via the `hf` CLI | Zero-config; auto-excludes `.github/` + `.git/`; handles deletions | Mirror-based (not git-to-git); still commit-per-hook under the hood for large folders |
|
|
18
|
+
| **`hf upload` / `upload_folder` script** | Python API bulk upload with `ignore_patterns` | Full control over ignore list | Easy to trip commit rate limits if implemented as delete-per-file + upload |
|
|
19
|
+
| ~~Wipe-everything-then-upload~~ | `delete_file()` loop + `upload_folder` | (none — anti-pattern) | Burns ~1 commit **per deleted file**; a mid-run failure leaves the Space half-emptied |
|
|
20
|
+
|
|
21
|
+
---
|
|
22
|
+
|
|
23
|
+
## When to Use This Skill
|
|
24
|
+
|
|
25
|
+
- Setting up auto-deployment: GitHub repo → Hugging Face Space (same as Vercel/GH Pages flow)
|
|
26
|
+
- Space shows `CONFIG_ERROR` / "Missing configuration in README"
|
|
27
|
+
- Deploy job fails with `429 Too Many Requests ... commit rate limit`
|
|
28
|
+
- Space state looks wrong after a failed deploy (files missing, only partial tree)
|
|
29
|
+
- Choosing between `git push`, `hub-sync`, and `upload_folder` for a Space
|
|
30
|
+
|
|
31
|
+
---
|
|
32
|
+
|
|
33
|
+
## Prerequisites (What a Working Space Needs)
|
|
34
|
+
|
|
35
|
+
1. **`README.md` with YAML front matter at the very top** — this *is* the Space's build config. Without it HF shows:
|
|
36
|
+
|
|
37
|
+
```
|
|
38
|
+
configuration error
|
|
39
|
+
Missing configuration in README
|
|
40
|
+
Base README.md template:
|
|
41
|
+
---
|
|
42
|
+
title: {{title}}
|
|
43
|
+
emoji: {{emoji}}
|
|
44
|
+
colorFrom: {{colorFrom}}
|
|
45
|
+
colorTo: {{colorTo}}
|
|
46
|
+
sdk: {{sdk}}
|
|
47
|
+
sdk_version: "{{sdkVersion}}"
|
|
48
|
+
{{#pythonVersion}}
|
|
49
|
+
python_version: "{{pythonVersion}}"
|
|
50
|
+
{{/pythonVersion}}
|
|
51
|
+
app_file: app.py
|
|
52
|
+
pinned: false
|
|
53
|
+
---
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
- `sdk`: `gradio` | `streamlit` | `static` | `docker` | `panel` | etc.
|
|
57
|
+
- The error above is ALSO shown when `README.md` is missing entirely (e.g. failed deploy) — don't assume the front matter is malformed; check whether the file exists on the Space first (see Debugging).
|
|
58
|
+
|
|
59
|
+
2. **`requirements.txt` at repo root** — HF Spaces installs from this (it does NOT read `pyproject.toml`/`uv.lock` unless visible; keep `requirements.txt` authoritative).
|
|
60
|
+
|
|
61
|
+
3. **App file in repo root** matching `app_file` (usually `app.py`).
|
|
62
|
+
|
|
63
|
+
4. **GitHub secret `HF_TOKEN`** — a HF access token with write access to the Space, added in GitHub repo Settings → Secrets and variables → Actions.
|
|
64
|
+
|
|
65
|
+
---
|
|
66
|
+
|
|
67
|
+
## Recommended Setup: GitHub Workflow
|
|
68
|
+
|
|
69
|
+
```yaml
|
|
70
|
+
# .github/workflows/deploy.yml
|
|
71
|
+
name: Deploy to Hugging Face Space
|
|
72
|
+
|
|
73
|
+
on:
|
|
74
|
+
push:
|
|
75
|
+
branches: [main]
|
|
76
|
+
workflow_dispatch: # manual re-run after rate-limit recovery
|
|
77
|
+
|
|
78
|
+
jobs:
|
|
79
|
+
deploy-to-hf:
|
|
80
|
+
runs-on: ubuntu-latest
|
|
81
|
+
steps:
|
|
82
|
+
- name: Checkout repository
|
|
83
|
+
uses: actions/checkout@v4
|
|
84
|
+
with:
|
|
85
|
+
fetch-depth: 0 # full history — HF's pre-receive hook scans every pushed commit
|
|
86
|
+
lfs: true # required whenever any tracked file matches .gitattributes LFS patterns
|
|
87
|
+
|
|
88
|
+
- name: Push to HF Space
|
|
89
|
+
env:
|
|
90
|
+
HF_TOKEN: ${{ secrets.HF_TOKEN }}
|
|
91
|
+
SPACE_REPO: <HF_USERNAME>/<SPACE_NAME>
|
|
92
|
+
run: |
|
|
93
|
+
git lfs install
|
|
94
|
+
git remote add space "https://user:${HF_TOKEN}@huggingface.co/spaces/${SPACE_REPO}"
|
|
95
|
+
git push space main --force
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
Key mechanics:
|
|
99
|
+
|
|
100
|
+
- `git push --force` to the Space is **reconciling**: adds, updates, AND deletes files to match the repo — no wipe step needed, and a failed run can't half-emptied the Space (unlike a delete-all-then-upload script).
|
|
101
|
+
- **1 git push = 1 commit on HF** — the entire commit-rate-limit problem disappears. There is no need to delete per file. Delete files in git; push; they're deleted on the Space.
|
|
102
|
+
- LFS objects (assets, PDFs, models under `.gitattributes` tracking) upload automatically with the push because the Space remote supports Git LFS natively. `checkout` with `lfs: true` ensures the runner has the objects.
|
|
103
|
+
- `fetch-depth: 0`: HF scans history on push; shallow pushes with binary blobs in parents can be rejected — full history + LFS avoids surprises.
|
|
104
|
+
|
|
105
|
+
### Deployment scope is defined by git tracking, not an ignore list
|
|
106
|
+
|
|
107
|
+
The workflow deploys exactly what `git ls-files` outputs. Before wiring it up, run:
|
|
108
|
+
|
|
109
|
+
```bash
|
|
110
|
+
git ls-files # everything that will land on the Space
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
- Sensitive files (`.env`) must be `gitignored` — never rely on a deploy ignore list to catch them.
|
|
114
|
+
- Data/runtime dirs (`data/output/*`, uploaded user files, model outputs) belong in `.gitignore`.
|
|
115
|
+
- Non-needed extras (agent docs, local tool configs) may ride along harmlessly if you prefer parity-by-tracking over extra ignores — decide consciously.
|
|
116
|
+
|
|
117
|
+
---
|
|
118
|
+
|
|
119
|
+
## Alternative: Official Action
|
|
120
|
+
|
|
121
|
+
```yaml
|
|
122
|
+
steps:
|
|
123
|
+
- uses: actions/checkout@v6
|
|
124
|
+
- uses: huggingface/hub-sync@v0.1.0
|
|
125
|
+
with:
|
|
126
|
+
github_repo_id: ${{ github.repository }}
|
|
127
|
+
huggingface_repo_id: username/my-space
|
|
128
|
+
hf_token: ${{ secrets.HF_TOKEN }}
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
Mirrors file contents (not git history), excludes `.github/` and `.git/` automatically, and removes Hub files that were removed from GitHub. Files >10MB must be tracked with Git LFS. Use this when you don't want the Space to share your git history at all.
|
|
132
|
+
|
|
133
|
+
---
|
|
134
|
+
|
|
135
|
+
## Rate Limits (Failure Mode That Took Down a Real Space)
|
|
136
|
+
|
|
137
|
+
Hub commit quota is a **user-action rate limit** (not part of the published 5-minute-window API/resolver tiers). Empirically observed on a free account:
|
|
138
|
+
|
|
139
|
+
```
|
|
140
|
+
429 Too Many Requests — You have exceeded the rate limit for repository commits
|
|
141
|
+
(128 per hour). You can retry this action in about 1 hour.
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
Key facts:
|
|
145
|
+
|
|
146
|
+
- The limit counts **commits regardless of success/failure**, including retried failed ones — a failed upload mid-run still spent budget.
|
|
147
|
+
- `delete_file()` is **one commit per file**. Wiping a 70-file Space ≈ 70 commits.
|
|
148
|
+
- `upload_folder` splits into multiple commits (auto-splits at ~50–100 files per commit for large folders).
|
|
149
|
+
- Three deploys in one hour ≈ far over budget → mid-upload 429 → Space left empty → rebuild error.
|
|
150
|
+
|
|
151
|
+
Recovery from a 429:
|
|
152
|
+
1. Wait for the window to reset (the error message states the cooldown, usually ~1 hour).
|
|
153
|
+
2. Re-run the workflow via `workflow_dispatch` (Actions tab → Run workflow) — no new commit needed if `main` is already correct.
|
|
154
|
+
3. Local runs (running the same script locally with the HF token) hit the **same account-level** quota.
|
|
155
|
+
|
|
156
|
+
If you must clean a repo where per-file deletes are otherwise unavoidable, batch them into a single commit:
|
|
157
|
+
|
|
158
|
+
```python
|
|
159
|
+
from huggingface_hub import HfApi
|
|
160
|
+
from huggingface_hub.hf_api import CommitOperationDelete
|
|
161
|
+
|
|
162
|
+
api.create_commit(
|
|
163
|
+
repo_id="user/space", repo_type="space", token=token,
|
|
164
|
+
operations=[CommitOperationDelete(path=f) for f in existing_files],
|
|
165
|
+
commit_message="Clear existing files",
|
|
166
|
+
)
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
---
|
|
170
|
+
|
|
171
|
+
## Debugging a Space
|
|
172
|
+
|
|
173
|
+
### State inspection (works even when the UI is confusing)
|
|
174
|
+
|
|
175
|
+
```python
|
|
176
|
+
import os, requests
|
|
177
|
+
from dotenv import load_dotenv
|
|
178
|
+
load_dotenv()
|
|
179
|
+
h = {"Authorization": f"Bearer {os.environ['HF_TOKEN']}"}
|
|
180
|
+
|
|
181
|
+
# Files currently on the Space
|
|
182
|
+
r = requests.get("https://huggingface.co/api/spaces/<USER>/<SPACE>/tree/main", headers=h)
|
|
183
|
+
print(r.status_code, [f["path"] for f in r.json()])
|
|
184
|
+
|
|
185
|
+
# Space runtime/config status (runtime stage: RUNNING | BUILDING | CONFIG_ERROR | ...)
|
|
186
|
+
s = requests.get("https://huggingface.co/api/spaces/<USER>/<SPACE>", headers=h)
|
|
187
|
+
print(s.json().get("runtime", {}).get("stage"))
|
|
188
|
+
```
|
|
189
|
+
|
|
190
|
+
- `CONFIG_ERROR` + tree missing `README.md`/`app.py` → deploy died mid-run; find the failing workflow run's log (`gh run view <run-id> --log-failed`) — usually a 429 or upload exception — then fix root cause and re-run.
|
|
191
|
+
- `CONFIG_ERROR` + `README.md` present → front matter is actually malformed; the template block above tells you exactly what HF expects.
|
|
192
|
+
|
|
193
|
+
### Workflow failures
|
|
194
|
+
|
|
195
|
+
```bash
|
|
196
|
+
gh run list -R <OWNER>/<REPO> --limit 3 # history
|
|
197
|
+
gh run view <id> --log-failed -R <OWNER>/<REPO> # the exception
|
|
198
|
+
gh workflow run deploy.yml -R <OWNER>/<REPO> # manual rerun (workflow_dispatch)
|
|
199
|
+
```
|
|
200
|
+
|
|
201
|
+
### Space runtime issues
|
|
202
|
+
|
|
203
|
+
- **Logs tab** on the Space page is the only source of runtime (build/runtime) errors — config errors surface in the Space UI, not the GitHub Action log.
|
|
204
|
+
- Wrong `app_file` / missing root entry file → build succeeds, app fails. `app_file` must match exactly.
|
|
205
|
+
|
|
206
|
+
### After any Space-altering change
|
|
207
|
+
|
|
208
|
+
Check: file tree is complete (`tree/main` shows expected set), README front matter intact, and the Space's runtime stage becomes `RUNNING` after build.
|
|
209
|
+
|
|
210
|
+
---
|
|
211
|
+
|
|
212
|
+
## Gotchas
|
|
213
|
+
|
|
214
|
+
- **Rate limit is per account/token across everything**, so a local test run and a CI run share the same budget.
|
|
215
|
+
- The Hub's pre-receive hook scans **every commit in the push**, not just the tip — a binary blob that exists anywhere in history can break pushes around it. If that bites, push a single **orphan commit** of the current tree instead of raw history.
|
|
216
|
+
- **LFS pointer vs file content**: if the runner checks out with `lfs: true`, files in the working copy are real content; pushing to the Space via `git push` uploads the real LFS objects over the remote's LFS endpoint. Without LFS checkout, the Space receives pointer files → 404 on the asset.
|
|
217
|
+
- `upload_folder` failures mid-run are **not transactional** — partial state persists (this is what emptied a real Space down to one directory).
|
|
218
|
+
- Deleting LFS files only frees guardrail-level storage after history is rewritten (`super_squash_history`), but for Spaces the OPPOSITE pattern is fine: force-push resets history, so old Storage-deleted files aren't a top concern.
|
|
219
|
+
- Secrets on the Space come from Space Settings → Variables and secrets (HF side), NOT from GitHub secrets; a `.env` excluded from the repo is still not present at runtime unless you set it in HF Space settings too.
|
|
220
|
+
|
|
221
|
+
---
|
|
222
|
+
|
|
223
|
+
## Checklist (Per Deployment Change)
|
|
224
|
+
|
|
225
|
+
- `README.md` front matter exists and matcher (`sdk`, `app_file`) targets the actual entrypoint and SDK version
|
|
226
|
+
- `requirements.txt` authoritatively lists runtime deps (Free HF Spaces reads only it)
|
|
227
|
+
- GitHub secret `HF_TOKEN` present and has write scope to the Space
|
|
228
|
+
- All Space-relevant files tracked in git; private/user-data files gitignored
|
|
229
|
+
- Workflow file under `.github/workflows/` with `push: branches: [main]` and `workflow_dispatch`
|
|
230
|
+
- Trigger one deploy and watch it complete; verify Space tree completeness and rerun if throttled
|
package/README.md
CHANGED
|
@@ -116,6 +116,7 @@ Domain-specific skills that can be loaded on-demand:
|
|
|
116
116
|
- `frontend-design/` — Frontend UI/UX design patterns
|
|
117
117
|
- `git-commit/` — Conventional commit message generation
|
|
118
118
|
- `gradio/` — Gradio UI framework guides
|
|
119
|
+
- `huggingface-deployment/` — Deploy apps to Hugging Face Spaces
|
|
119
120
|
- `mcp-builder/` — MCP server development guide
|
|
120
121
|
- `n8n-patterns/` — n8n workflow automation patterns
|
|
121
122
|
- `project-design/` — Project planning & architecture documentation
|
package/bin/cli.js
CHANGED
|
@@ -43,6 +43,7 @@ const FILES_TO_DOWNLOAD = [
|
|
|
43
43
|
'.agents/skills/frontend-design/SKILL.md',
|
|
44
44
|
'.agents/skills/git-commit/SKILL.md',
|
|
45
45
|
'.agents/skills/gradio/SKILL.md',
|
|
46
|
+
'.agents/skills/huggingface-deployment/SKILL.md',
|
|
46
47
|
'.agents/skills/mcp-builder/SKILL.md',
|
|
47
48
|
'.agents/skills/project-design/SKILL.md',
|
|
48
49
|
'.agents/skills/ui-ux-pro-max/SKILL.md'
|
package/package.json
CHANGED
package/error/error.md
DELETED
|
@@ -1,57 +0,0 @@
|
|
|
1
|
-
npx axiom-coding-agent-setup
|
|
2
|
-
|
|
3
|
-
PS E:\Personal Projects\Snorlax Recognition> npx axiom-coding-agent-setup
|
|
4
|
-
Need to install the following packages:
|
|
5
|
-
axiom-coding-agent-setup@1.1.0
|
|
6
|
-
Ok to proceed? (y) y
|
|
7
|
-
|
|
8
|
-
============================================================
|
|
9
|
-
AXIOM Coding Agent Setup
|
|
10
|
-
============================================================
|
|
11
|
-
|
|
12
|
-
Target directory: E:\Personal Projects\Snorlax Recognition
|
|
13
|
-
|
|
14
|
-
Downloading AGENTS.md... ✓
|
|
15
|
-
Downloading opencode.json... ✓
|
|
16
|
-
Downloading .env.axiom... ✓
|
|
17
|
-
Downloading .agents/ENGINEERING.md... ✗ (Failed to download .agents/ENGINEERING.md: 404)
|
|
18
|
-
Downloading .agents/STACK.md... ✗ (Failed to download .agents/STACK.md: 404)
|
|
19
|
-
Downloading .agents/WORKFLOW.md... ✗ (Failed to download .agents/WORKFLOW.md: 404)
|
|
20
|
-
Downloading .agents/SECURITY.md... ✓
|
|
21
|
-
Downloading .agents/DEBUGGING.md... ✓
|
|
22
|
-
Downloading .agents/PERFORMANCE.md... ✓
|
|
23
|
-
Downloading .agents/CONTEXT-MANAGEMENT.md... ✓
|
|
24
|
-
Downloading .agents/templates/ai-engineering-python.md... ✓
|
|
25
|
-
Downloading .agents/templates/fullstack-ai-nextjs.md... ✓
|
|
26
|
-
Downloading .agents/skills/agent-browser/SKILL.md... ✓
|
|
27
|
-
Downloading .agents/skills/ai-integration/SKILL.md... ✓
|
|
28
|
-
Downloading .agents/skills/deployment-patterns/SKILL.md... ✓
|
|
29
|
-
Downloading .agents/skills/developing-with-streamlit/SKILL.md... ✓
|
|
30
|
-
Downloading .agents/skills/fastapi/SKILL.md... ✓
|
|
31
|
-
Downloading .agents/skills/fastapi-templates/SKILL.md... ✓
|
|
32
|
-
Downloading .agents/skills/frontend-design/SKILL.md... ✓
|
|
33
|
-
Downloading .agents/skills/git-commit/SKILL.md... ✓
|
|
34
|
-
Downloading .agents/skills/gradio/SKILL.md... ✓
|
|
35
|
-
Downloading .agents/skills/mcp-builder/SKILL.md... ✓
|
|
36
|
-
Downloading .agents/skills/n8n-patterns/SKILL.md... ✗ (Failed to download .agents/skills/n8n-patterns/SKILL.md: 404)
|
|
37
|
-
Downloading .agents/skills/project-design/SKILL.md... ✓
|
|
38
|
-
Downloading .agents/skills/ui-ux-pro-max/SKILL.md... ✓
|
|
39
|
-
|
|
40
|
-
============================================================
|
|
41
|
-
Setup complete! 21 files downloaded, 4 failed.
|
|
42
|
-
============================================================
|
|
43
|
-
|
|
44
|
-
Your project now has AXIOM coding agent instructions:
|
|
45
|
-
|
|
46
|
-
- AGENTS.md → Main agent instructions
|
|
47
|
-
- opencode.json → OpenCode IDE configuration
|
|
48
|
-
- .env.axiom → Environment variables template
|
|
49
|
-
- .agents/ENGINEERING.md → Engineering principles
|
|
50
|
-
- .agents/STACK.md → Tech stack knowledge
|
|
51
|
-
- .agents/WORKFLOW.md → Workflow guidelines
|
|
52
|
-
- .agents/SECURITY.md → Security principles & checklist
|
|
53
|
-
- .agents/DEBUGGING.md → Systematic debugging methodology
|
|
54
|
-
- .agents/PERFORMANCE.md → Performance awareness & optimization
|
|
55
|
-
- .agents/CONTEXT-MANAGEMENT.md → Context budget & session discipline
|
|
56
|
-
- .agents/templates/ → Project-type conventions
|
|
57
|
-
- .agents/skills/ → Domain-specific skills
|