docs/PUBLIC_PREVIEW.md

Public Preview

Agentic Space Factory turns Hugging Face model cards into private, testable Gradio Spaces using Hugging Face Jobs, Pi, Inference Providers, and per-user Storage Buckets.

What it does

• Creates private Spaces from model cards.
• Runs the build inside an ephemeral Hugging Face Job.
• Uses Pi with an Inference Providers coding model.
• Injects the shared GitHub gist as Pi's operational instruction source.
• Stores state, events, raw/redacted traces, reports, generated files, validation results, and output artifacts in a private user Bucket.
• Attempts ZeroGPU first when requested, then optional fixed-GPU fallback.
• Supports manual hardware selection when automatic hardware assignment is unavailable.
• Runs a separate Space validation job with endpoint discovery, output-type checks, latency measurement, and generated artifact capture.

Current UI

The dashboard is split into three working areas:

1. Left column — Run storage setup, model pre-scan, New Build form, Billing & compute readiness.
2. Center tabs — Active Run for build details and Space Test for validation details.
3. Right column — Run Explorer for navigation and Run Stats for aggregate history.

The Run Explorer is navigation-only. Build run details live in Active Run; validation run details live in Space Test.

Recommended demo path

1. Sign in with Hugging Face OAuth.
2. Check or create the private run Bucket.
3. Review the default Tongyi-MAI/Z-Image-Turbo example or enter another model card, then run the model pre-scan.
4. Launch only after the scan returns safe/caution or after explicitly acknowledging a risky verdict.
5. Watch Active Run: progress timeline, latest events, latency when available, Space/Settings/Artifacts links, and trace documents.
6. If hardware is manual, open Space Settings and select the recommended hardware.
7. Open Space Test, prefill from the build, inspect available Gradio endpoints, click an endpoint to use it, and launch validation.
8. Confirm full_inference_success, measured latency, and saved output artifact.

What it does not promise

The app does not guarantee that every model card can become a working Space. Some models require large or unusual hardware, Docker, multi-GPU execution, custom kernels, external services, accepted gated licenses, or manual fixes.

Production-readiness note

The app is suitable for a controlled public-preview or internal production deployment when deployed with OAuth enabled, per-user Buckets, private generated Spaces, and clear billing expectations.

Before broad public launch, keep monitoring:

• Job cost and user quota expectations;
• token redaction in traces;
• failed build/validation rates;
• hardware assignment failure modes;
• latency and ZeroGPU duration recommendations.

Additional preview checklist

• Pre-scan a few representative model cards before launching Jobs.
• Confirm that risky models require acknowledgement and unsupported models stay blocked.

UI reliability checks

For preview deployments, verify that repeated refreshes do not duplicate click handlers: endpoint chips should update one API field once, run pagination should move one page per click, and run explorer selection/delete should remain independent.

• Repair is one bounded automated retry with visible artifacts and no unbounded loop.

Recovery behavior

If a generated Space fails with HF build/runtime errors, especially empty logs or no-reason runtime errors, the Factory asks Pi to diagnose the blockage before any code patch is allowed. The system may wait for logs, re-upload the same workspace to force a rebuild, patch code once, request manual hardware, or stop with an auditable technical blocker.

v120 note: Agent recovery visibility

The UI now exposes Pi diagnosis/recovery state through the Active Run Agent recovery card and links to recovery decision/blockage artifacts. This helps users understand when the Factory is waiting for HF logs, rebuilding the same code, patching, requesting hardware, or declaring a technical blocker.

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.