# Architecture

## V2 foundation

This repository is the first safe foundation for a Hugging Face-native Agentic Space Factory.

```text
User
  ↓
Gradio orchestrator Space with HF OAuth
  ↓
HF Job launched with the user's OAuth token
  ↓
Mounted private Storage Bucket at /output
  ↓
Optional private target Space creation
  ↓
Live Gradio API validation
  ↓
Bucket report + state + events
```

## Current phases

### Phase 1 — Hello Job

Validates:

```text
OAuth → Jobs scope → HF Job → mounted Bucket → readback UI
```

### Phase 2 — Private target Space

Validates:

```text
OAuth → HF Job → create private Gradio Space → upload files → live API test → report
```

The target Space is private by default and must be created in the signed-in user's namespace.

## Why Phase 2 is intentionally simple

Before adding Pi, model-card analysis, or ZeroGPU, we need to prove that the system can safely create a target Space and validate it through the live API.

That live API validation gate will later remain the core success criterion.


## Phase 6

Adds a no-build runtime recommender Job that analyzes model metadata and writes `runtime_recommendation.json` to the Bucket.


## Phase 7 — LongCat article reproduction

Phase 7 attempts an article-style LongCat Space build: private target Space, Pi-guided app adaptation, ZeroGPU first, fixed GPU fallback when explicitly enabled, and live `/health` API validation. Full video generation remains a manual-review step until model-specific runtime validation is complete.