README.md

metadata

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 a Hugging Face-native productization of the agentic ZeroGPU Spaces workflow:

model card → agentic build job → private Space → hardware if available → live validation → traces/report/artifacts

What the app does

• Creates private generated Spaces under the signed-in user's namespace.
• Launches long-running build and validation work as Hugging Face Jobs.
• Uses Pi with a coding model served through Hugging Face Inference Providers.
• Injects the configured GitHub gist as Pi's operational instruction source.
• Stores each run in a per-user private Storage Bucket.
• Attempts ZeroGPU first when requested, then optional fixed-GPU fallback.
• Supports manual hardware selection when automatic assignment is unavailable. Automatic fallback avoids high/restricted tiers such as A100/H200; use Space Settings manually if an account or organization has access.
• Distinguishes bootability from real inference.
• Measures live inference latency when a generation smoke test succeeds.
• Uses measured latency to recommend @spaces.GPU(duration=...) when the generated Space uses ZeroGPU.

Current UI

The product root / is a custom Docker/FastAPI dashboard. /custom is kept as an alias.

The UI is organized into three main areas:

v122 stability note

The v122 line intentionally rolls back the experimental v121 client-side caching/polling optimizations after real UI testing exposed flicker and broken build/run behavior. The app keeps the v120 Agent recovery UI and the v118/v119 core blockage protocol, but returns to the proven polling and run-selection model for production stability.

Left column

• Run storage — check or create the signed-in user's private Bucket.
• New Build — starts from Tongyi-MAI/Z-Image-Turbo by default, fast pre-scans the model card, then launches a private Space build only after an acceptable scan verdict.
• Billing & compute — show payment readiness, link to HF Billing, and centralize the compute-cost note for Jobs, Inference Providers, and safe hardware fallbacks.

Center workspace

Two tabs share the main detail area:

• Active Run — build progress, run actions, Space/Settings/Job/Artifacts links, manual hardware guidance, inference latency, a vector-icon latest-events feed, and curated trace documents.
• Space Test — validation run details, actionnable Gradio endpoint picker, endpoint params, validation status, latency, point-based progress, and validation actions.

Selecting a build run opens Active Run. Selecting a validation run opens Space Test. The Runs Explorer is intentionally compact: each row prioritizes the model or Space, status, relative freshness, and a secondary context line while keeping the raw run ID available in the row.

Right column

• Runs Explorer — navigation-only list of build and validation runs with filters, search, status badges, and inline delete.
• Run Stats — aggregate metrics across indexed runs: totals, success/pass rates, validation latency median/p95, and issue counts.

Agent recovery visibility

When a build or runtime blockage appears, the Active Run panel shows an Agent recovery card. It summarizes Pi's diagnosis decision, the selected recovery action (wait_for_logs, factory_rebuild_same_code, patch_code, manual hardware, or blocker), key evidence, and the next step. This makes the blockage protocol visible without turning the UI into a raw log viewer.

The Run traces dock also links to the unified agent_trace.jsonl, the diagnosis REPAIR_DECISION.json, repair artifacts, and blockage details when they exist.

Model pre-scan

New builds are gated by a fast model-card pre-scan. The scan is metadata-only and does not download model weights. It checks:

• model-card guidance and runnable usage examples;
• Diffusers signals such as library_name, model_index.json, pipeline class, and from_pretrained(...) examples;
• safetensors versus unsafe or legacy weight formats;
• gated/private access and unsupported task signals;
• custom-code indicators such as auto_map, custom pipeline files, or trust_remote_code hints.

Verdicts are intentionally product-facing: safe and caution allow launch, risky requires explicit acknowledgement, and unsupported blocks launch. Tongyi-MAI/Z-Image-Turbo is treated as the known-good default example because it has a clear Diffusers model card and works in the app's default test flow.

Run storage

Each signed-in user writes to their own private Storage Bucket. The default bucket is:

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:

SPACE_FACTORY_BUCKET_NAME=space-factory-runs
SPACE_FACTORY_BUCKET_MOUNT=/output

Typical run layout:

runs/<run_id>/launch.json
runs/<run_id>/state.json
runs/<run_id>/summary.json
runs/<run_id>/events.jsonl
runs/<run_id>/report.md
runs/<run_id>/generated/
runs/<run_id>/tests/
runs/<run_id>/artifacts/
runs/<run_id>/traces/raw/
runs/<run_id>/traces/raw/agent_trace.jsonl
runs/<run_id>/traces/redacted/
runs/<run_id>/traces/redacted/agent_trace.jsonl
runs/<run_id>/logs/

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;
• writes a strict GOAL.md for Pi;
• asks Pi to follow the configured GitHub gist before coding;
• generates a Gradio app;
• creates and uploads a private Space;
• attempts ZeroGPU/fixed-GPU assignment when requested;
• runs health/API checks and a live generation smoke test when possible;
• writes events, report, traces, and structured artifacts to the user's Bucket.

2. Validate Space

Validation is a separate HF Job. Use it after a build succeeds or after manually selecting hardware in Space Settings.

The validation job:

• waits for the target Space;
• discovers Gradio endpoints when possible;
• calls the selected endpoint;
• checks the returned output type;
• stores returned artifacts;
• measures latency;
• recommends a conservative ZeroGPU duration when relevant;
• writes validation state, events, report data, and smoke-test artifacts.

Result statuses

• full_inference_success: a live generation smoke test returned the expected output type.
• manual_hardware_required: the Space was generated, but hardware must be selected manually before validation.
• full_inference_candidate_health_passed: the Space boots and contains inference signals, but generation was not fully smoke-tested.
• health_only: the Space boots, but no real inference path was validated.
• technical_blocker: concrete blockers such as multi-GPU requirements, missing licenses, custom CUDA, or unclear usage.
• failed: the build, runtime, or validation job failed.

Guarantees

• Generated Spaces are private by default.
• Nothing is published automatically.
• Runs are persisted in the configured per-user Storage Bucket.
• The app distinguishes health checks from full inference validation.
• Hardware assignment is best-effort and can fall back to manual user action.
• Raw and redacted Pi traces are kept separate.

Unified agent trace

Pi can be invoked more than once during a run: the initial build, a blockage diagnosis pass, and an optional structured repair patch. The Factory now writes a canonical run-level agent journal to traces/raw/agent_trace.jsonl and traces/redacted/agent_trace.jsonl so those phases read as one auditable agentic loop instead of separate conversations. Specialized stdout logs remain available under logs/, but the Active Run Pi RAW / Pi redacted buttons prefer the unified trace when it exists.

Non-goals and limits

The app 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.

The app does not mirror live spend/quota totals from Hugging Face Billing. Users should consult the HF Billing dashboard for exact usage.

Local development

Install dependencies and run tests:

pip install -r requirements.txt
pytest

The Docker Space starts the app with one uvicorn process from the Dockerfile. Do not add an extra uvicorn.run(...) launcher inside app.py.

Documentation

See:

• docs/ARCHITECTURE.md
• docs/PUBLIC_PREVIEW.md
• docs/SECURITY.md
• docs/NEXT_STEPS.md

Default example model: Tongyi-MAI/Z-Image-Turbo. It is treated as a known-good Diffusers text-to-image model for the fast pre-scan calibration and public-preview smoke tests.

Pi diagnosis and structured recovery

When the generated Space fails live validation, the factory now enters a diagnosis-first blockage protocol instead of asking Pi to patch immediately. The worker collects HF build/runtime logs, Space status and validation errors, writes repair/INCIDENT_BRIEF.md, then asks Pi/Qwen Coder to choose one bounded action in repair/REPAIR_DECISION.json: wait for delayed logs, inspect again, force a same-code factory rebuild, patch code, request manual hardware, or declare a technical blocker.

A code repair is allowed only when Pi selects patch_code and the Factory accepts the decision. Empty/no-reason HF failures are routed through wait/rebuild/blocker paths rather than speculative code edits. Patch repair still writes REPAIR_BRIEF.md, REPAIR_PLAN.md, and REPAIR_SUMMARY.md, uploads once, then revalidates the live Space with the normal API checks.

Repair mode is intentionally strict: it must preserve the original model and real-inference contract, avoid fake/static outputs, keep a cheap health endpoint, and report blockers instead of hiding runtime errors.

v123 — Critical Job launch + failure timeline fix

• Fixed a production-critical HF Job startup failure where the large embedded worker script could make Python fail before startup with argument list too long.
• The worker script is now persisted as runs/<run_id>/_worker.py in the mounted run bucket before launch, and the Job receives only WORKER_SCRIPT_PATH.
• Kept a small WORKER_SCRIPT_B64 fallback only for compatibility/manual launch paths; normal app launches no longer put the worker source in env/argv.
• Added a failure-log fallback so pre-worker Job failures such as argument list too long still create an explicit failed timeline event and red failure point.

v124 — Timeline and Run Explorer stabilization

• Fixed the compact Overall Progress timeline so dynamically visible repair/failure groups cannot wrap dots onto a second row.
• Removed smooth timeline auto-scroll that could cause visible flicker during polling.
• Simplified Run Explorer type/status badges to neutral type labels and short status labels such as Success, Failed, Running and Manual.
• Added regression checks for timeline single-row behavior and compact Run Explorer labels.

v127 — Billing usefulness + UI event/timeline audit

• Reworked the Billing & compute card into an actionable compute checklist: payment readiness, Pi Inference Providers, build Job cost, generated Space hardware and high-tier GPU guardrails.
• Kept exact spend/quotas delegated to the Hugging Face Billing dashboard instead of inventing usage totals.
• Audited JS event bindings for one-shot/delegated listeners across navigation, run rows and timeline scroll.
• Reduced timeline auto-scroll churn: identical timeline renders no longer force keep-visible scrolling after user interaction.
• Confirmed run selection keeps the immediate cached/optimistic render path before network hydration.