README.md

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

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

If automatic hardware assignment fails, 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.