---
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
colorFrom: red
colorTo: purple
---

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

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