---
title: Agentic Space Factory
sdk: gradio
app_file: app.py
hf_oauth: true
hf_oauth_expiration_minutes: 480
hf_oauth_scopes:
  - read-repos
  - write-repos
  - manage-repos
  - gated-repos
  - inference-api
  - jobs
  - read-billing
---

# Agentic Space Factory

Agentic Space Factory turns a Hugging Face model card into a **private, testable Gradio Space** using a Hugging Face Job, Pi, a coding model through Hugging Face Inference Providers, and a private Storage Bucket for run state, traces, reports, generated files, and validation artifacts.

It is designed as a Hugging Face-native version of the local agent workflow described in the ZeroGPU Spaces article:

```text
model card → agentic job → generated private Space → hardware if available → live validation → report
```

## Custom UI

A custom dashboard is available at `/custom`. It is wired to the same OAuth-backed backend as the Gradio fallback and supports:

- bucket onboarding, including check/create before build;
- build launch with explicit ZeroGPU-first and fixed-GPU fallback controls;
- existing-Space validation launch;
- live run progress from `events.jsonl`;
- recent run exploration from the signed-in user's Bucket;
- quick links to the HF Job, generated Space, Space settings, and run artifacts.

The Gradio controls remain available as a conservative fallback while the custom UI is validated across more models. The custom UI now follows the validated dashboard layout: Build from model card, live progress, validation metrics, recent events, Run Explorer, selected run details, report preview, and quick links are visible from the main cockpit. It prevents build launches until the user bucket is ready, validates required fields before launch, shows explicit busy/error/success states, and keeps retrying live progress with a visible warning if polling is temporarily unavailable. This avoids leaving users unsure whether the Job is still running.

## V26 custom Run Explorer with selected-run actions

V26 expands the custom dashboard run explorer. Selecting a run now opens a detail panel with normalized status, model, target Space, hardware, validation signals, artifact links, and a report preview. The custom frontend reads richer run bundles from the user Bucket, including `inference_gate.json`, `generation_smoke.json`, `hardware_strategy.json`, `TECHNICAL_BLOCKERS.json`, logs, generated files, and artifacts when available.


## Main workflow

### 1. Build from model card

Paste a Hugging Face model ID or model-card URL. The app launches an HF Job that:

- fetches model metadata and repo information;
- asks Pi + Qwen Coder to build a Gradio app;
- creates a private Space under your namespace;
- uploads the generated workspace;
- attempts ZeroGPU first, then fixed-GPU fallback if enabled;
- validates `/health` or Gradio API availability;
- classifies the result honestly;
- returns quick links to the Job page, generated Space, Space settings, and run artifacts.

### 2. Validate existing Space

The builder now tries to assign hardware at Space creation time using the Hub `space_hardware` parameter. It attempts ZeroGPU first, then the preferred/fallback fixed GPU when enabled. If automatic hardware assignment fails because of OAuth, billing, quota, or permission limits, set the hardware manually in the generated Space settings, then run validation. The validation job:

- waits for the existing Space;
- calls the configured generation endpoint;
- checks the returned output type;
- stores returned artifacts in the Bucket;
- measures latency;
- recommends a conservative ZeroGPU duration;
- returns quick links to the validation Job, target Space, Space settings, and run artifacts.

## Result statuses

- `full_inference_success`: a live generation smoke test returned the expected output type.
- `manual_hardware_required`: the Space was generated but automatic ZeroGPU/fixed-GPU assignment failed; set hardware manually, then validate.
- `full_inference_candidate_health_passed`: the Space boots and contains inference signals, but generation was not smoke-tested yet.
- `health_only`: the Space boots, but no real inference path was validated.
- `technical_blocker`: the agent found concrete blockers such as multi-GPU requirements, missing licenses, custom CUDA, or unclear usage.
- `failed`: the build, runtime, or validation job failed.

## What this app guarantees

- Generated Spaces are private by default.
- Nothing is published automatically.
- Runs are persisted in the configured Storage Bucket.
- The app distinguishes bootability from real inference.
- Hardware assignment is treated as best effort, not as an assumed capability.

## What this app does not guarantee

It does not guarantee that every model card becomes a working Space. Some models require multi-GPU execution, Docker, unavailable CUDA extensions, external services, accepted licenses, very large hardware, or manual fixes.

## Required environment

Each signed-in user writes to their own private Storage Bucket by default. The app can now check and create this private bucket for the user from the **Run storage** section before launching Jobs. The default bucket is:

```text
https://huggingface.co/buckets/<your-username>/space-factory-runs
```

For local dev or deployment, configure only the bucket **name**; the namespace is derived from the signed-in OAuth user:

```bash
SPACE_FACTORY_BUCKET_NAME=space-factory-runs
SPACE_FACTORY_BUCKET_MOUNT=/output
```

Do not configure a shared owner/name bucket for a public Space. The app uses HF OAuth; no global admin token should be stored in the Space.

### Build repair behavior

If a generated Space fails during build or startup, the builder now performs one automatic repair pass. It collects the Space build/runtime logs, gives them back to Pi, asks for a minimal patch, reuploads the workspace, and retries validation once. This is intended for common issues such as dependency resolver conflicts, missing imports, invalid metadata, or Gradio endpoint mistakes.

Generated Spaces no longer pin `huggingface_hub<1.0.0`; modern model cards may require Transformers 5.x, which in turn requires newer Hub versions. The builder normalizes generated requirements to a compatible `huggingface_hub<2.0.0` range before upload.


Hardware decisions are written to `hardware_strategy.json` and `hardware_attempts.json` in the user run bucket.


## V24 custom UI shell

V24 introduces the first custom-frontend pass without replacing the validated Gradio controls yet. The custom dashboard is served at `/custom` and embedded in the app as **Custom UI preview**. It includes:

- a product-style Build from model card screen,
- a live progress card and timeline model,
- quick links placeholders,
- a Run Explorer with selected-run actions shell for the connected bucket,
- static frontend assets under `web/static/`,
- a small API skeleton for app info, progress projection, and future run listing.

The OAuth-backed actions remain in the functional Gradio controls for this pass. The next custom UI pass should wire the frontend actions to authenticated backend endpoints while preserving the same per-user bucket and Job security model.


### Custom UI V27

The custom interface now includes run-level actions: select a previous run, open its Job/Space/Settings/Artifacts, or prepare the Validate existing Space form directly from that run. A manual hardware action panel appears when a run requires user hardware selection.


## Custom UI live polish

The custom interface includes a Run Explorer with status filters, active-run persistence, quick refresh, and resilient live polling. If progress polling fails temporarily, the UI shows a warning while continuing to retry; the HF Job may still be running.