--- 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//state.json runs//summary.json runs//events.jsonl runs//report.md runs//analysis_inputs/ runs//planning/ runs//generated/ runs//tests/ runs//artifacts/ runs//logs/ runs//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. 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.33. ## v198.26.33 — Model Card Instruction Authority & Terminal Repair Reconciliation - Adds `MODEL_CARD_INSTRUCTIONS.json`, extracted from the README/model card, so explicit install commands, loader symbols, runtime notes and model-card deviations become first-class worker context. - Promotes explicit model-card requirements into `MODEL_RECIPE.json`, Pi generation prompts, repair task packets and recipe-aware repair packets. - Adds model-card alignment and local-requirement sanity guards so generated Spaces cannot silently replace official model-card install commands with missing or non-publishable local artifacts such as invented `.whl` files. - Propagates structured `/health` failure classes into recipe-aware repair matching, including SDXL-LoRA `CLIPTextModel.text_model` failures. - Strengthens terminal repair reconciliation so `repair_outcome.json` terminal failures cannot leave Active Run or Runs Explorer stuck on `running`. See `CHANGELOG_V198_26_33.md`. ## v198.26.27 — Pi Repair Execution Guarantee & Model-Family Runtime Recipes - Executes a targeted Pi repair when pre-upload integrity still has repairable defects after deterministic compile/API/decorator patches. - Guarantees smoke-repair terminal outcomes: no more `repair_candidate=true` / `triggered=true` with `post_repair_validation=not_started` and no patch reason. - Adds SDXL-LoRA text-encoder mismatch classification and a smoke-primary error packet so Pi repairs from the real `/generate` failure even when Space runtime logs are unavailable. - Preserves the worker stabilization, schema coercion, token/cache guards, manual-hardware actionability, and terminal UI hydration from v198.26.14–v198.26.26. See `CHANGELOG_V198_26_27.md`. ## v198.26.24 — Worker Stabilization & Regression Replay - Converts known repairable pre-upload integrity failures from fail-fast to repair-first. - Adds deterministic `@spaces.GPU` insertion for ZeroGPU apps that expose `/generate` but missed the decorator. - Archives rejected pre-upload payloads under `generated_rejected/` with `pre_upload_integrity_failure.json` for audit and regression replay. - Keeps recent safeguards for Diffusers duplicate token injection, writable HF cache paths, manual hardware actionability, and Gradio schema coercion. See `CHANGELOG_V198_26_24.md`. ## v198.26.13 — Runtime Stage Granularity See `CHANGELOG_V198_26_13.md`. ## v198.26.12 — OAuth Recovery See `CHANGELOG_V198_26_12.md`.