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