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

## v198.26.32 — Recipe-Aware Repair Loop

- Adds `repair/RECIPE_AWARE_REPAIR_PACKET.json`, built from `MODEL_RECIPE.json` and `APP_RUNTIME_CONTRACT.json`, so Pi repairs with the same model-family authority used at generation time.
- Extends repair task packets with model family, artifact role, loader strategy, expected output type, known failure match, and family-specific directives.
- Adds known repair signatures for duplicate Diffusers token injection, non-writable HF cache paths, missing ZeroGPU `@spaces.GPU`, schema/dropdown mismatch, SDXL-LoRA text-encoder mismatch, FLUX template syntax failures, and model-not-loaded-after-boot failures.
- Makes failed Pi patch attempts terminal and honest: no publishable patch becomes `no_patch_produced_by_pi` / related guard statuses instead of ending as `post_repair_validation=not_started`.
- Allows a more direct recipe-aware relaunch when Pi produced no useful patch and repair budget remains; otherwise the run ends with explicit `repair_exhausted` metadata.

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