RECOVERY_ALGORITHM.md

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

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:

ResolutionImpossible
Cannot install ...
No matching distribution found ...
metadata-generation-failed

Then Pi must apply the gist method:

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.