--- 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.110. ## v198.26.110 β€” Linked Validation Job Link Hydration - Space Test linked validation rows now hydrate missing Job metadata from cached validation run data before rendering. - Compact parent-derived rows can expose their Job button as soon as the validation run is known. - Status reconciliation remains authoritative, so enrichment does not flip visible validation verdicts. See `CHANGELOG_V198_26_110.md`. ## v198.26.87 β€” Runs Explorer Badge Rail Alignment - Keeps the title-first card structure from v198.26.81. - Moves the run age to the left under the run ID. - Moves the badges to the right side of the footer. - Reverses badge layout so the status badge is the rightmost badge. - Extends the footer badge rail to the same right-side visual column as the delete button. - Prevents the age label from compressing or shifting the status and Space Test badges. - Keeps the `β€’` separator before the linked Space Test count. - Keeps the Space Test badge height matched with the status badge. See `CHANGELOG_V198_26_87.md`. ## v198.26.67 β€” Recovered Space Test Success Tone - Treats `recovered_by_space_test` and `recovered_by_manual_validation` as terminal success statuses in the Active Run canonical UI state. - Prevents stale `visual_status: error` from coloring a successful recovered run badge red. - Keeps Runs Explorer / Runs Stats recovery accounting unchanged; this pass fixes the Active Run badge tone. See `CHANGELOG_V198_26_67.md`. ## v198.26.66 β€” Simplified Runs Loading State - Removes the animated dot suffix from the Runs Explorer loading state. - Keeps the container sweep and pulsing blue orb as the only loading motion. - Simplifies the loading markup and reduced-motion CSS by removing unused dot selectors. See `CHANGELOG_V198_26_66.md`. ## v198.26.65 β€” Stable Runs Loading Dots - Keeps the Runs Explorer loading label visually stable by reserving fixed space for the animated dots. - Replaces variable `content: "..."` dot animation with opacity/scale-only motion, preventing center text reflow. - Extends reduced-motion coverage to the updated dot pseudo-elements. See `CHANGELOG_V198_26_65.md`. ## v198.26.64 β€” Runs Explorer Loading Motion - Replaces the static initial `Loading runs...` text with a compact animated loading state. - Animates the Runs Explorer container during network refreshes while preserving cached rows when available. - Updates static asset cachebusters so the refreshed CSS/JS is served immediately. See `CHANGELOG_V198_26_64.md`. ## v198.26.63 β€” Factory Upload Retry Budget - Adds a small factory-side packaging/upload retry budget, defaulting to one retry, separate from Pi repair attempts. - Retries transient runtime payload or HF upload errors without relaunching Pi or consuming patch repair budget. - Records `factory_upload_retry.json` and richer `factory_upload_error.json` metadata so upload failures are classified instead of ending opaquely. See `CHANGELOG_V198_26_63.md`. ## v198.26.62 β€” LongCat Runtime Import and Payload Repair - Ensures deterministic gated-token injection puts `import os` before `HF_TOKEN = os.environ.get(...)`, even when Pi already placed `import os` later in `app.py`. - Preserves valid `from __future__ import ...` ordering while still placing token setup before application code. - Retries runtime payload copy once when a repair re-upload transiently loses a vendored package parent directory such as `longcat_video/audio_process`. See `CHANGELOG_V198_26_62.md`. ## v198.26.61 β€” Pre-scan Panel Output Authority - Separates pre-scan input detection from generated-output guessing. - Adds output confidence, evidence, and authority metadata to model pre-scan results. - Updates the pre-build panel to label the output as a provisional guess while runtime contracts and Gradio returns remain authoritative. See `CHANGELOG_V198_26_61.md`. ## v198.26.60 β€” Linked Validation Output Type From Gradio Returns - Uses the discovered Gradio endpoint return schema to resolve linked validation output type. - Lets `/generate` returning `Video` override a stale parent `EXPECTED_OUTPUT_TYPE=image`. - Records `linked_expected_output_resolution.json` so false prescan output mismatches are auditable. See `CHANGELOG_V198_26_60.md`. ## v198.26.59 β€” Linked Validation Argument Realignment - Rebuilds incomplete linked validation args from the discovered Gradio schema instead of preserving legacy positional prompt args in media slots. - Moves a provided prompt string to the actual prompt/text parameter when required image/audio inputs appear before it. - Preserves real replay payloads when they provide FileData, URLs, or existing file paths, and only falls back to smoke media for unusable media strings. See `CHANGELOG_V198_26_59.md`. ## v198.26.58 β€” Linked Validation Media Autofill - Auto-fills required image/audio/file inputs in linked validation using deterministic local smoke files. - Prevents required `audio_path` or `image_path` inputs from failing before `/generate` is called. - Keeps video-output validation aligned with the generated runtime contract while preserving real inference checks. See `CHANGELOG_V198_26_58.md`. ## v198.26.57 β€” Recoverable Blocker Space Test Unlock - Enables linked Space Test for blocked parent runs when a target Space and generation endpoint are available. - Keeps diagnostic-only/no-generation-endpoint blockers disabled. - Marks successful recovery validations as `recovered_by_space_test`. See `CHANGELOG_V198_26_57.md`. ## v198.26.56 β€” Conservative Pre-scan Output Hints - Detects LongCat/video-avatar model cards as video output even when the model has image inputs and no canonical `pipeline_tag`. - Falls back to `any` for custom libraries without a strong output signal instead of guessing image. - Keeps generated runtime contracts authoritative for final smoke validation. See `CHANGELOG_V198_26_56.md`. ## v198.26.55 β€” Linked Validation Recovery Promotion - Allows a successful linked Space Test to recover a parent run that was marked `technical_blocker` by a false automatic validation failure. - Preserves the original build verdict while exposing `recovered_by_space_test` as the effective/display status. - Keeps diagnostic-only and no-full-inference blockers non-promotable. See `CHANGELOG_V198_26_55.md`. ## v198.26.54 β€” Runtime Output Smoke Alignment - Uses the generated app runtime contract output type for automatic smoke validation, so a video app is validated as video even when model prescan guessed image. - Normalizes MIME-style outputs such as `video/mp4` before timeout and result checks. - Makes video smoke payloads prefer exact/non-cache acceleration over optional fast cache presets. See `CHANGELOG_V198_26_54.md`. ## v198.26.53 β€” Native Kernel Repair Diff Gate - Allows `NATIVE_KERNEL_RESOLUTION.json` during unrelated bounded repairs when it was produced by a successful deterministic native-kernel guard. - Prevents syntax/decorator repairs from being rejected merely because the native-kernel policy sidecar was refreshed. - Keeps `requirements_policy.json` quarantined as a benign advisory sidecar while preserving publishable native-kernel evidence. See `CHANGELOG_V198_26_53.md`. ## v198.26.52 β€” Native Kernel HF Kernels Policy - Resolves model-card `flash_attn` requirements through `NATIVE_KERNEL_RESOLUTION.json` before upload. - Prefers HF Kernels backends for Diffusers and Transformers instead of fragile Space source builds. - Allows documented xformers/SDPA fallback for LongCat-style apps, and blocks unresolved native-kernel source builds before upload. See `CHANGELOG_V198_26_52.md`. ## v198.26.51 β€” Final ZeroGPU Torch Guard - Re-checks `requirements.txt` after model-card convergence and immediately before upload. - Forces unsupported ZeroGPU torch stack pins to the supported ASF policy even if Pi or repair rewrote requirements late. - Treats Hub `CONFIG_ERROR` / `CONFIGURATION_ERROR` runtime stages as terminal instead of waiting for `/health`. See `CHANGELOG_V198_26_51.md`. ## v198.26.50 β€” ZeroGPU Torch Stack Policy - Normalizes ZeroGPU-targeted runs to supported torch stack requirements before upload. - Replaces incompatible generated torch pins with `torch==2.11.0` when the app needs torch on ZeroGPU. - Normalizes `torchaudio` and `torchvision` only when the app imports them or requirements already declare them. - Leaves non-ZeroGPU/CPU apps on the existing lighter dependency policy. See `CHANGELOG_V198_26_50.md`. ## v198.26.49 β€” Run Stats Linked Test Reconciliation - Fixes Run Stats showing `0 linked tests` when a Build Run is already effectively validated by a linked Space Test. - Counts durable validation facts from `post_build_validation` and `manual_validation_status`, not only explicit `linked_validations` rows. - Keeps Effective Success and Linked Space Tests aggregate counts consistent after linked validation deletion/reconciliation. See `CHANGELOG_V198_26_49.md`. ## v198.26.48 β€” Linked Space Test Deletion UI - Lists linked validation runs directly in the Space Test panel for the selected Build Run. - Adds a per-row delete button that reuses the existing delete confirmation modal. - Keeps Build Run deletion cascading through linked validation run folders, while validation-run deletion refreshes parent linked validation metadata. See `CHANGELOG_V198_26_48.md`. ## v198.26.47 β€” Space Test Multi-Choice Candidate Retry - Fixes Gradio choice retry when multiple schema-compatible arguments share the rejected value, for example `width=512` and `height=512`. - Updates all matching schema-backed choice parameters instead of toggling only the first matching argument. - Adds regression coverage for duplicate `512` width/height candidates. See `CHANGELOG_V198_26_47.md`. ## v198.26.46 β€” Space Test Alternate Choice Retry - Adds a bounded second retry for Gradio choice errors when the first schema-choice retry still fails. - Handles ambiguous `str`/`int` rendering where Gradio prints both rejected values and choices as `512`, making the first correction direction unknowable. - Writes `generation_smoke_payload_retry_2.json` for the alternate primitive retry path. See `CHANGELOG_V198_26_46.md`. ## v198.26.45 β€” Space Test Numeric Choice Retry - Fixes linked Space Test retries for ambiguous Gradio choice errors such as `Value: 512 is not in the list of choices: [512, 768, 1024]`. - Adds a fallback that toggles numeric-looking choice arguments from `int`/`float` to string when Gradio renders the current value and choices identically but still rejects the payload. - Adds a regression test in the existing Space validation payload. See `CHANGELOG_V198_26_45.md`. ## v198.26.44 β€” Space Test Payload Completeness Audit - Adds missing Space Test finalizers/imports needed after a linked validation succeeds or fails. - Ensures linked Space Test can write `summary.json` and `artifact_manifest.json` from its own worker payload. - Adds a no-network success-path test for `VALIDATE_EXISTING_SPACE_WORKER_SCRIPT`. See `CHANGELOG_V198_26_44.md`. ## v198.26.43 β€” Space Test Choice Retry Helper - Includes `coerce_smoke_args_from_choice_error` inside the linked Space Test worker payload. - Prevents Space Test from failing with `NameError` when the Gradio schema-choice retry path is reached. - Keeps the existing schema-choice retry behavior instead of disabling the fallback. See `CHANGELOG_V198_26_43.md`. ## v198.26.42 β€” Smoke Missing Dependency Repair - Classifies generation-smoke `NameError: name '' is not defined` as `missing_python_dependency` when the missing symbol looks like a Python package. - Marks those smoke failures as `repair_candidate=true`, `failure_owner=app_runtime`, instead of leaving them as opaque `generation_smoke_error`. - Preserves the v198.26.41 PRXPixel prevention rule, but ensures similar missing optional dependencies can trigger the normal smoke repair path. See `CHANGELOG_V198_26_42.md`. ## v198.26.41 β€” PRXPixel Runtime Dependency Guard - Adds `ftfy` automatically when a generated Space uses `PRXPixelPipeline` / `Photoroom/prxpixel-t2i`. - Classifies `NameError: name 'ftfy' is not defined` as `missing_python_dependency:ftfy` instead of a generic runtime error. - Keeps the repair scope narrow: requirements/app import repair only, with no inference fallback or placeholder output. See `CHANGELOG_V198_26_41.md`. ## v198.26.40 β€” Conservative Dependency Policy - Preserves stricter generated/model-specific `transformers>=...` lower bounds during requirements sanitization. - Prevents the platform dependency sanitizer from downgrading requirements such as `transformers>=4.57` to ASF's generic `transformers>=4.51.0` base policy. - Keeps the strict upload integrity guard after sanitize/convergence, but reduces avoidable repair churn before that guard. - Adds explicit policy evidence in `requirements_policy.json` when a stricter generated minimum is preserved. See `CHANGELOG_V198_26_40.md`. ## v198.26.39 β€” Repair Upload Convergence Ordering - Runs model-card dependency convergence before strict upload preflight, so repair uploads are not blocked before their requirements are normalized. - Accepts evidenced `diffusers.git@main` stale-ref repairs for deleted model-card branches such as `prx-pixel-pipeline`. - Restores explicit model-card minimums such as `transformers>=4.57` after platform requirements sanitization. - Keeps unaudited dependency deviations blocked. See `CHANGELOG_V198_26_39.md`. ## v198.26.38 β€” Model-Card Stale Git Ref Deviation Guard - Allows a narrow model-card git dependency deviation when the explicit branch/tag is proven unavailable and the replacement is the same official repo on default/main. - Fixes the `Photoroom/prxpixel-t2i` loop where Pi repaired the deleted `prx-pixel-pipeline` Diffusers branch, then the model-card guard rewrote or rejected the repair. - Keeps unaudited dependency deviations blocked before upload. - Preserves deterministic convergence for other explicit model-card requirements such as `transformers>=4.57`. See `CHANGELOG_V198_26_38.md`. ## v198.26.37 β€” Pre-Upload Payload Repair-First Convergence - Adds deterministic payload convergence before `runtime_payload_too_large` becomes terminal. - Prunes optional example/sample/demo media when those assets alone push the runtime payload over budget. - Keeps `app.py`, `README.md`, `requirements.txt`, `src/`, and `web/` protected from silent pruning. - Writes `runtime_payload_convergence.json` with the repair outcome before failing closed. - Preserves v198.26.36 `ref_spaces/` exclusion and Git LFS pointer detection. See `CHANGELOG_V198_26_37.md`. ## v198.26.36 β€” Runtime Payload Reference-Space LFS Guard - Excludes `ref_spaces/` snapshots from the generated Space runtime payload. - Detects unresolved Git LFS pointer stubs before upload and records `git_lfs_pointer_without_object`. - Fixes the failed `Photoroom/prxpixel-t2i` run where `ref_spaces/examples/ex*.png` LFS pointer files were sent to the commit endpoint. - Keeps v198.26.35 ZeroGPU actionability repair and fixed-GPU fallback behavior. See `CHANGELOG_V198_26_36.md`. ## v198.26.35 β€” ZeroGPU Actionability Repair & Hardware Fallback - Runs ZeroGPU actionability repair before Space creation, so ASF does not create a `zero-a10g` Space from a payload missing `@spaces.GPU`. - Reuses the deterministic decorator repair to add `@spaces.GPU` around the generated `/generate` path when possible. - Falls back to the configured fixed GPU hardware before creation when ZeroGPU remains non-actionable and fallback is allowed. - Writes `zero_gpu_actionability_resolution.json` and clearer failure metadata for remaining non-actionable manual-hardware payloads. - Keeps v198.26.34 model-card convergence and the default Pi assistant model `zai-org/GLM-5.2`. See `CHANGELOG_V198_26_35.md`. ## v198.26.34 β€” Model Card Repair Convergence & GLM Default - Adds deterministic model-card repair convergence after Pi repair: simple leftovers such as `transformers>=4.51.0` when the card requires `transformers>=4.57` are patched directly and re-checked. - Keeps pre-upload repair alive while Pi budget remains, relaunching Pi with direct guard deviations when model-card/template guards still fail. - Writes `model_card_repair_convergence_patch.json` with exact requirement changes, removed local artifacts, and README cleanup. - Cleans stale local Diffusers wheel artifacts and README β€œvendored wheel” claims when the final strategy follows an official model-card git dependency. - Changes the default Pi assistant model in the Launch Build form and backend fallback to `zai-org/GLM-5.2`. - Preserves v198.26.33 model-card instruction authority, local requirement sanity, health-to-repair propagation, terminal repair reconciliation, and v198.26.32 quick links. See `CHANGELOG_V198_26_34.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`.