Upload 4 files

docs/ARCHITECTURE.md

@@ -0,0 +1,81 @@
+# Architecture
+
+Agentic Space Factory is a Hugging Face-native implementation of the local agent workflow described in the ZeroGPU Spaces article.
+
+```text
+User
+  → Gradio orchestrator Space with HF OAuth
+  → ephemeral HF Job
+  → Pi coding agent + HF Inference Providers model
+  → generated private target Space
+  → Storage Bucket run record
+  → live validation job when hardware is ready
+```
+
+## Components
+
+### Orchestrator Space
+
+The public UI has two workflows:
+
+1. **Build from model card** — starts an HF Job that analyzes a model card and asks Pi to generate a private Gradio Space.
+2. **Validate existing Space** — starts a separate HF Job that smoke-tests a generated Space after hardware has been configured, measures latency, and stores the output artifact.
+
+The orchestrator never stores a global admin token. It uses the signed-in user's HF OAuth token.
+
+### HF Jobs
+
+Jobs do the long-running work: installing Pi, generating code, creating/uploading the target Space, checking runtime state, and running live validations.
+
+The builder job is allowed to create a private Space and upload generated files. Hardware assignment is attempted on a best-effort basis only. If ZeroGPU or fixed-GPU assignment fails because of quota, billing, or OAuth limits, the run is marked as requiring manual hardware.
+
+### Pi + coding model
+
+Pi runs inside the Job and uses a model such as `Qwen/Qwen3-Coder-Next` through Hugging Face Inference Providers. It receives a strict goal:
+
+- generate a Gradio app from the model card;
+- keep the Space private;
+- add `/health` and generation endpoints where possible;
+- do not mark placeholders as full inference;
+- write blockers if full inference is impossible.
+
+### Storage Bucket
+
+Every run writes to the configured Bucket:
+
+```text
+runs/<run_id>/state.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/
+```
+
+### Target Space
+
+Generated Spaces are private by default. The builder attempts ZeroGPU first when selected, then an optional fixed-GPU fallback. If both fail, the Space can still be configured manually in Settings, then validated with the second workflow.
+
+## Result lifecycle
+
+```text
+Build from model card
+  → generated private Space
+  → ZeroGPU/fixed GPU best-effort
+  → health/API gate
+  → manual_hardware_required or candidate status
+
+Validate existing Space
+  → call /generate or configured endpoint
+  → verify output type
+  → measure latency
+  → save artifact
+  → full_inference_success when output is valid
+```
+
+## Known limits
+
+- Automatic paid hardware assignment through OAuth may fail; manual hardware selection is supported.
+- ZeroGPU may be unavailable because of quota or namespace limits.
+- Multi-GPU, Docker-only, ComfyUI, custom CUDA/FlashAttention, external API keys, or gated models may require manual intervention or produce `technical_blocker`.

docs/NEXT_STEPS.md

@@ -0,0 +1,40 @@
+# Next Steps
+
+## Product follow-ups
+
+1. Add a dedicated hardware diagnostic workflow that compares:
+   - `request_space_hardware()` after Space creation;
+   - `create_repo(..., space_hardware=...)` at creation time;
+   - OAuth token vs personal access token behavior.
+
+2. Add optional live Pi progress streaming:
+   - periodic heartbeat during the Pi run;
+   - partial `pi_output.txt` tailing;
+   - intermediate trace syncing.
+
+3. Add a repair workflow:
+   - read target Space build/runtime logs;
+   - ask Pi to patch generated files;
+   - upload patch;
+   - re-run validation.
+
+4. Improve validation presets per task:
+   - text-to-image prompt → image output;
+   - text-generation prompt → text output;
+   - ASR audio sample → text output;
+   - image-to-image test image → image output.
+
+5. Improve generated report UI:
+   - clearer final status badges;
+   - direct links to generated Space, Bucket files, and trace JSONL;
+   - explicit manual hardware checklist.
+
+## Current product workflow
+
+```text
+Build from model card
+→ if hardware automatic assignment succeeds, validate directly
+→ if not, set hardware manually in target Space Settings
+→ Validate existing Space
+→ full_inference_success if output type and latency are validated
+```

docs/PUBLIC_PREVIEW.md

@@ -0,0 +1,23 @@
+# Public Preview
+
+Agentic Space Factory is a public-preview tool for turning Hugging Face model cards into private, testable Gradio Spaces.
+
+## What it does
+
+- Creates private Spaces from model cards.
+- Uses Pi and a coding model through Hugging Face Inference Providers.
+- Attempts ZeroGPU first when selected, then a fixed-GPU fallback if enabled.
+- Stores run state, generated files, traces, validation results, and reports in a Storage Bucket.
+- Supports manual hardware selection when automatic hardware assignment is unavailable.
+- Provides a separate live generation smoke test with latency measurement.
+
+## What it does not promise
+
+It does not guarantee that every model card becomes a fully working Space. Some models require multi-GPU systems, Docker, custom CUDA/FlashAttention, external services, accepted gated licenses, or hardware beyond what is available.
+
+## Recommended demo path
+
+1. Build a private Space from a model card.
+2. If the run reports `manual_hardware_required`, open the generated Space Settings and set an appropriate GPU.
+3. Run Validate existing Space with a small test input.
+4. Confirm `full_inference_success`, saved output artifact, and latency.

docs/SECURITY.md

@@ -0,0 +1,25 @@
+# Security Notes
+
+## Token model
+
+The orchestrator uses Hugging Face OAuth. Do not store a global admin `HF_TOKEN` in the Space.
+
+The user OAuth token is passed to HF Jobs as a secret named `HF_TOKEN`. The worker must never write it to the Bucket, traces, reports, generated files, or logs.
+
+## Resource ownership
+
+Generated Spaces are constrained to the signed-in user's namespace and are private by default.
+
+The validation workflow is also limited to Spaces under the signed-in user's namespace.
+
+## Hardware
+
+Hardware assignment is best-effort. GPU upgrades may involve billing and may fail through OAuth. The supported fallback is manual hardware selection by the user followed by a separate validation job.
+
+## Traces
+
+Pi traces can contain prompts, tool outputs, paths, generated code, and potentially sensitive information. Raw traces should remain private. Redaction is best-effort and should not be treated as a formal data-loss-prevention system.
+
+## Publication
+
+The app never publishes generated Spaces automatically. Users should review generated code, license requirements, and validation results before making any generated Space public.