README.md

metadata

title: Agentic Space Factory
emoji: 🏭
colorFrom: indigo
colorTo: blue
short_description: Build, inspect, validate Gradio Spaces from model cards.
sdk: docker
hf_oauth: true
hf_oauth_expiration_minutes: 1440
hf_oauth_scopes:
  - read-repos
  - write-repos
  - manage-repos
  - gated-repos
  - inference-api
  - jobs
  - read-billing

Agentic Space Factory

Agentic Space Factory turns Hugging Face model cards into private, testable Gradio Spaces through an agentic build loop running on Hugging Face.

The app is an operator interface for model-to-Space generation. A user enters a model URL, reviews a compact pre-scan, launches a build, watches progress, opens the generated Space, validates the live API, and inspects the full run archive.

The project builds on the idea that a deployed Space can be the coding assistant's lab: generated code is not enough; the live Space must boot, expose an API, run inference, and return a valid artifact.

What the Factory does

• Reads a Hugging Face model card or model URL.
• Runs a compact pre-scan before launch.
• Creates a private target Space under the signed-in user's namespace.
• Launches the build inside a Hugging Face Job.
• Prepares a grounded workspace for Pi, the coding assistant.
• Uploads the generated Space implementation.
• Applies platform dependency guardrails.
• Assigns hardware on a best-effort basis, including ZeroGPU when applicable.
• Validates the deployed Space through live Gradio API calls.
• Captures reports, logs, traces, generated files, tests, and output artifacts.
• Classifies outcomes honestly: full success, partial validation, technical blocker, manual hardware required, auth refresh required, or failure.
• Optionally publishes privacy-safe anonymous eval records.

User journey

Paste model card
→ run compact pre-scan
→ launch build
→ watch Active Run timeline
→ inspect generated Space and artifacts
→ validate through Space Test
→ review Run Explorer and Run Stats

The interface is organized around:

• New Build — model URL, pre-scan, launch readiness, and billing/compute hints.
• Center workspace — Active Run for build details and Space Test for linked validation runs.
• Runs Explorer — compact history of build runs.
• Run Stats — aggregate status and outcome overview.

Hugging Face-native architecture

The Factory uses Hugging Face primitives end to end:

• Spaces for the orchestrator UI and generated demos.
• Jobs for long-running build, validation, and repair work.
• Storage Buckets for run archives.
• Inference Providers for assistant/model access.
• ZeroGPU for serverless GPU demos when a model fits the Gradio/ZeroGPU execution model.
• Gradio for live API validation.

Typical run artifacts are written under:

runs/<run_id>/state.json
runs/<run_id>/summary.json
runs/<run_id>/events.jsonl
runs/<run_id>/report.md
runs/<run_id>/analysis_inputs/
runs/<run_id>/planning/
runs/<run_id>/generated/
runs/<run_id>/tests/
runs/<run_id>/artifacts/
runs/<run_id>/logs/
runs/<run_id>/traces/redacted/

Model-card grounding

At build time, the worker prepares analysis_inputs/ for Pi:

model_card.md
model_card_source.json
model_repo_tree.json
prescan_summary.json
source_policy.md

The rule is simple: the model card is canonical, the repo tree is structural evidence, and generated Hugging Face snippets are hints only. Pi is asked to cite model-card evidence before implementing the Space.

Validation contract

Generated Spaces are expected to describe what they implemented through an inference contract. The worker uses that contract to decide whether to run a generation smoke test, skip it as a declared technical blocker, or ask for manual validation.

For successful full-inference builds, the live Gradio API is the source of truth. The validator checks health, discovers endpoints, calls the generation endpoint, verifies returned artifacts, and records latency. For ZeroGPU-compatible apps, measured inference latency can inform @spaces.GPU(duration=...) recommendations.

Privacy and safety

Generated Spaces are private by default. Run Buckets are per-user. Pi session traces are archived only in redacted form; RAW Pi traces are not published to Buckets or exposed in the UI. Redacted traces are best-effort and should still be reviewed before public sharing.

Anonymous eval records contain aggregate signals only. They must not include raw model cards, generated code, prompts, tokens, private bucket paths, validation payloads, endpoint schemas, or target Space IDs.

Documentation

Public-facing documentation is in docs/:

• ARCHITECTURE.md — system overview.
• PUBLIC_PREVIEW.md — public-preview guidance and user journey.
• SECURITY.md — token, bucket, trace, and eval privacy notes.
• RECOVERY_ALGORITHM.md — repair behavior and safety boundaries.
• RELEASE_VALIDATION.md — release checklist.
• NEXT_STEPS.md — product roadmap.

Detailed version history is kept in the changelog files at the repository root.

See CHANGELOG_V194.md for the Model Pre-scan Decision Card UI pass.

See CHANGELOG_V195.md for the Runtime CSS Cleanup with Legacy Safety Net pass.

Current release: Agentic Space Factory v198.26.32.

v198.26.32 — Recipe-Aware Repair Loop

• Adds repair/RECIPE_AWARE_REPAIR_PACKET.json, built from MODEL_RECIPE.json and APP_RUNTIME_CONTRACT.json, so Pi repairs with the same model-family authority used at generation time.
• Extends repair task packets with model family, artifact role, loader strategy, expected output type, known failure match, and family-specific directives.
• Adds known repair signatures for duplicate Diffusers token injection, non-writable HF cache paths, missing ZeroGPU @spaces.GPU, schema/dropdown mismatch, SDXL-LoRA text-encoder mismatch, FLUX template syntax failures, and model-not-loaded-after-boot failures.
• Makes failed Pi patch attempts terminal and honest: no publishable patch becomes no_patch_produced_by_pi / related guard statuses instead of ending as post_repair_validation=not_started.
• Allows a more direct recipe-aware relaunch when Pi produced no useful patch and repair budget remains; otherwise the run ends with explicit repair_exhausted metadata.

See CHANGELOG_V198_26_31.md.

v198.26.27 — Pi Repair Execution Guarantee & Model-Family Runtime Recipes

• Executes a targeted Pi repair when pre-upload integrity still has repairable defects after deterministic compile/API/decorator patches.
• Guarantees smoke-repair terminal outcomes: no more repair_candidate=true / triggered=true with post_repair_validation=not_started and no patch reason.
• Adds SDXL-LoRA text-encoder mismatch classification and a smoke-primary error packet so Pi repairs from the real /generate failure even when Space runtime logs are unavailable.
• Preserves the worker stabilization, schema coercion, token/cache guards, manual-hardware actionability, and terminal UI hydration from v198.26.14–v198.26.26.

See CHANGELOG_V198_26_27.md.

v198.26.24 — Worker Stabilization & Regression Replay

• Converts known repairable pre-upload integrity failures from fail-fast to repair-first.
• Adds deterministic @spaces.GPU insertion for ZeroGPU apps that expose /generate but missed the decorator.
• Archives rejected pre-upload payloads under generated_rejected/ with pre_upload_integrity_failure.json for audit and regression replay.
• Keeps recent safeguards for Diffusers duplicate token injection, writable HF cache paths, manual hardware actionability, and Gradio schema coercion.

See CHANGELOG_V198_26_24.md.

v198.26.13 — Runtime Stage Granularity

See CHANGELOG_V198_26_13.md.

v198.26.12 — OAuth Recovery

See CHANGELOG_V198_26_12.md.