File size: 2,674 Bytes
b3c91c5 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 | # Recovery algorithm
Agentic Space Factory uses the Factory as an observer and guardrail layer, and Pi as the repair agent.
## Roles
### Factory
The Factory is responsible for deterministic observation and state management:
1. poll the Hugging Face Job and generated Space;
2. read `get_space_runtime()` and Space logs;
3. detect terminal build/runtime failures instead of waiting blindly;
4. collect raw evidence into artifacts;
5. give Pi a complete repair context;
6. enforce safe action budgets and cooldowns;
7. re-upload/revalidate after Pi changes the workspace.
The Factory should not solve arbitrary dependency or application bugs by hardcoding fixes.
### Pi
Pi is responsible for the actual agentic repair work:
1. read the HF Spaces gist rules;
2. read `INCIDENT_BRIEF.md`;
3. read `DEPENDENCY_ERROR_BRIEF.md` when present;
4. inspect build/runtime logs and the current workspace;
5. identify the first actionable error;
6. patch the minimal file(s), usually `requirements.txt` for pip failures;
7. explain the patch in `REPAIR_SUMMARY.md`;
8. let the Factory upload and validate the repaired Space.
## Main recovery flow
```text
live validation fails or Space enters BUILD_ERROR/RUNTIME_ERROR
→ Factory collects Space runtime + logs
→ Factory writes build_error_observation.json when applicable
→ Factory writes INCIDENT_BRIEF.md
→ Factory asks Pi for diagnosis
→ Pi writes REPAIR_DECISION.json
→ Factory normalizes unsafe decisions
→ if patch_code:
Pi receives REPAIR_BRIEF.md + logs + gist + workspace
Pi patches the existing workspace
Pi writes REPAIR_SUMMARY.md
Factory uploads and validates
→ if wait_for_logs / factory_rebuild_same_code:
Factory applies budget/cooldown guardrails
→ if manual_hardware / technical_blocker:
UI shows explicit action/blocker
```
## Dependency errors
Dependency errors are not handled by a giant table of hardcoded pins.
The Factory only extracts the first useful pip error and writes `DEPENDENCY_ERROR_BRIEF.md`, for example:
```text
ResolutionImpossible
Cannot install ...
No matching distribution found ...
metadata-generation-failed
```
Then Pi must apply the gist method:
```text
read first actionable error
patch once, surgically
rebuild
validate live
```
## Safety guarantees
- Pi receives `HF_TOKEN` / `HUGGING_FACE_HUB_TOKEN` inside the Job as secrets.
- Token context is recorded only as redacted metadata in `token_context.json`.
- The Factory blocks same-code rebuild loops with budgets and cooldowns.
- The Factory does not continue waiting when the Space is already in `BUILD_ERROR`.
- Repair phases are part of the same run and unified in trace artifacts.
|