README.md

metadata

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

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:

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:

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.52.

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 '<package>' 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.