README.md

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