| --- |
| title: Agentic Space Factory |
| emoji: 🏭 |
| colorFrom: indigo |
| colorTo: blue |
| short_description: Build, inspect, validate Gradio Spaces from model cards. |
| sdk: docker |
| hf_oauth: true |
| hf_oauth_expiration_minutes: 1440 |
| hf_oauth_scopes: |
| - read-repos |
| - write-repos |
| - manage-repos |
| - gated-repos |
| - inference-api |
| - jobs |
| - read-billing |
| --- |
| |
| # Agentic Space Factory |
|
|
| Agentic Space Factory turns Hugging Face model cards into private, testable Gradio Spaces through an agentic build loop running on Hugging Face. |
|
|
| The app is an operator interface for model-to-Space generation. A user enters a model URL, reviews a compact pre-scan, launches a build, watches progress, opens the generated Space, validates the live API, and inspects the full run archive. |
|
|
| The project builds on the idea that a deployed Space can be the coding assistant's lab: generated code is not enough; the live Space must boot, expose an API, run inference, and return a valid artifact. |
|
|
| ## What the Factory does |
|
|
| - Reads a Hugging Face model card or model URL. |
| - Runs a compact pre-scan before launch. |
| - Creates a private target Space under the signed-in user's namespace. |
| - Launches the build inside a Hugging Face Job. |
| - Prepares a grounded workspace for Pi, the coding assistant. |
| - Uploads the generated Space implementation. |
| - Applies platform dependency guardrails. |
| - Assigns hardware on a best-effort basis, including ZeroGPU when applicable. |
| - Validates the deployed Space through live Gradio API calls. |
| - Captures reports, logs, traces, generated files, tests, and output artifacts. |
| - Classifies outcomes honestly: full success, partial validation, technical blocker, manual hardware required, auth refresh required, or failure. |
| - Optionally publishes privacy-safe anonymous eval records. |
|
|
| ## User journey |
|
|
| ```text |
| Paste model card |
| → run compact pre-scan |
| → launch build |
| → watch Active Run timeline |
| → inspect generated Space and artifacts |
| → validate through Space Test |
| → review Run Explorer and Run Stats |
| ``` |
|
|
| The interface is organized around: |
|
|
| - **New Build** — model URL, pre-scan, launch readiness, and billing/compute hints. |
| - **Center workspace** — `Active Run` for build details and `Space Test` for linked validation runs. |
| - **Runs Explorer** — compact history of build runs. |
| - **Run Stats** — aggregate status and outcome overview. |
|
|
| ## Hugging Face-native architecture |
|
|
| The Factory uses Hugging Face primitives end to end: |
|
|
| - **Spaces** for the orchestrator UI and generated demos. |
| - **Jobs** for long-running build, validation, and repair work. |
| - **Storage Buckets** for run archives. |
| - **Inference Providers** for assistant/model access. |
| - **ZeroGPU** for serverless GPU demos when a model fits the Gradio/ZeroGPU execution model. |
| - **Gradio** for live API validation. |
|
|
| Typical run artifacts are written under: |
|
|
| ```text |
| runs/<run_id>/state.json |
| runs/<run_id>/summary.json |
| runs/<run_id>/events.jsonl |
| runs/<run_id>/report.md |
| runs/<run_id>/analysis_inputs/ |
| runs/<run_id>/planning/ |
| runs/<run_id>/generated/ |
| runs/<run_id>/tests/ |
| runs/<run_id>/artifacts/ |
| runs/<run_id>/logs/ |
| runs/<run_id>/traces/redacted/ |
| ``` |
|
|
| ## Model-card grounding |
|
|
| At build time, the worker prepares `analysis_inputs/` for Pi: |
|
|
| ```text |
| model_card.md |
| model_card_source.json |
| model_repo_tree.json |
| prescan_summary.json |
| source_policy.md |
| ``` |
|
|
| The rule is simple: the model card is canonical, the repo tree is structural evidence, and generated Hugging Face snippets are hints only. Pi is asked to cite model-card evidence before implementing the Space. |
|
|
| ## Validation contract |
|
|
| Generated Spaces are expected to describe what they implemented through an inference contract. The worker uses that contract to decide whether to run a generation smoke test, skip it as a declared technical blocker, or ask for manual validation. |
|
|
| For successful full-inference builds, the live Gradio API is the source of truth. The validator checks health, discovers endpoints, calls the generation endpoint, verifies returned artifacts, and records latency. For ZeroGPU-compatible apps, measured inference latency can inform `@spaces.GPU(duration=...)` recommendations. |
|
|
| ## Privacy and safety |
|
|
| Generated Spaces are private by default. Run Buckets are per-user. Pi session traces are archived only in redacted form; RAW Pi traces are not published to Buckets or exposed in the UI. Redacted traces are best-effort and should still be reviewed before public sharing. |
|
|
| Anonymous eval records contain aggregate signals only. They must not include raw model cards, generated code, prompts, tokens, private bucket paths, validation payloads, endpoint schemas, or target Space IDs. |
|
|
| ## Documentation |
|
|
| Public-facing documentation is in `docs/`: |
|
|
| - `ARCHITECTURE.md` — system overview. |
| - `PUBLIC_PREVIEW.md` — public-preview guidance and user journey. |
| - `SECURITY.md` — token, bucket, trace, and eval privacy notes. |
| - `RECOVERY_ALGORITHM.md` — repair behavior and safety boundaries. |
| - `RELEASE_VALIDATION.md` — release checklist. |
| - `NEXT_STEPS.md` — product roadmap. |
|
|
| Detailed version history is kept in the changelog files at the repository root. |
|
|
| <!-- Internal regression markers for historical tests; public version history remains in CHANGELOG files: v189.9, v190.10, v194, v191.11, Timeline polish and Run notes clarity, Run notes, Agent recovery, Anonymous eval archive activation, agent_trace.jsonl. --> |
| |
| See `CHANGELOG_V194.md` for the Model Pre-scan Decision Card UI pass. |
|
|
|
|
| See `CHANGELOG_V195.md` for the Runtime CSS Cleanup with Legacy Safety Net pass. |
|
|
|
|
| Current release: Agentic Space Factory v198.26.8. |
|
|
