README.md

---
title: Agentic Space Factory
sdk: docker
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

### V36 Docker OAuth dependency fix

V36 adds the `huggingface_hub[oauth]` extra to the Docker runtime requirements. This is required by the official FastAPI OAuth helper `attach_huggingface_oauth(...)`; without it, the Docker Space starts but fails during app import with a missing OAuth dependency error.


The product root (`/`) is the custom dashboard. `/custom` is kept as an alias for the same UI. The app is served as a Docker/FastAPI Space with the official Hugging Face OAuth FastAPI helper, so there is no Gradio shell around the product UI.

The custom dashboard 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 UI follows the validated dashboard layout: Run build, 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.


### V34 Space startup fix

V34 removes the explicit `uvicorn.run(...)` launcher from `app.py`. Hugging Face Spaces already starts the app server, so launching a second server from the module can cause `address already in use` on port 7860. The app now only exposes the ASGI `app` object.

### V33 root custom dashboard

V33 removes the Gradio iframe/product shell problem: the public root is the custom dashboard itself. The old Gradio controls are not part of the normal UI anymore.

## 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. Run build

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


### Custom UI V27

The custom interface now includes run-level actions: select a previous run, open its Job/Space/Settings/Artifacts, or prepare the Test 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.


### V35 Docker/FastAPI OAuth startup

V35 switches the product Space to `sdk: docker` and serves the custom dashboard with a single uvicorn process from the Dockerfile. Hugging Face OAuth is attached directly to FastAPI via `attach_huggingface_oauth`, with login at `/oauth/huggingface/login`. This removes the previous ambiguity between Gradio startup, FastAPI startup, and custom UI routing.


## v37 premium simplified UI

The product dashboard now exposes only two top-level workflows: **Run build** and **Test Space**. The Run Explorer remains visible inside the build cockpit, so users can browse previous runs without switching context. Artifact links open the connected bucket at `runs/<run_id>`.

### V38 UI refinement

The custom dashboard separates two user intents more clearly:

- **Prepare new build** clears the selected run context and makes it explicit that the form launches a fresh private Space build.
- Selecting a previous run in the Run Explorer only updates progress, details, links, and report preview. It does not modify the build form.
- Run filtering/search is now local and cached after the latest bucket refresh, so status filters should feel instant. Use **Refresh runs** to reload the bucket.

## Current product UI

The public custom UI uses three top-level workflow tabs:

1. **New Build** — prepare and launch a fresh private Space build from a model card.
2. **Live Progress** — inspect active or historical runs, follow the compact step timeline, open Job/Space/Settings/Artifacts, and browse the connected bucket's Run Explorer.
3. **Space Test** — run a live smoke test after manual hardware selection or after a generated Space is ready.

The build form is intentionally isolated from selected historical runs. Selecting a run only updates Live Progress, details, quick links, and report preview; it never mutates the New Build form.

The Run Explorer reads launch metadata, summary metadata, state, gate files, and validation files from the connected user's bucket. New Jobs write launch metadata immediately so in-progress runs can appear before the worker has finished writing final artifacts.

The live progress timeline is designed to avoid horizontal scrolling and uses explicit step states: completed, active, pending, and failed. Historical run Job links are reconstructed from `job_id` when possible, so the Job button should remain available even when older summaries did not store a full `job_url`.