PlantAI-dev/docs/PROJECT_EXECUTION_FRAMEWORK_2026-05-20.md

# bbav5 Project Execution Framework

Date: 2026-05-20

This document records the execution framework that should be used for current and future revisions. It is based on source-level reading of the current bbav5 project and the two reference projects, CellVoyager and AutoBA. It is not a replacement for per-stage source audits; before changing any stage, the corresponding `apps/cli/run_*.py`, contract, skill wrapper, backend dispatch path, and frontend parameter path must still be read.

## 1. Reference Project Pattern

### 1.1 CellVoyager

Relevant files:

- `/home/xia-lab/wutx/01model/CellVoyager/cellvoyager/agent.py`
- `/home/xia-lab/wutx/01model/CellVoyager/cellvoyager/hypothesis.py`
- `/home/xia-lab/wutx/01model/CellVoyager/cellvoyager/execution/legacy.py`
- `/home/xia-lab/wutx/01model/CellVoyager/cellvoyager/execution/claude.py`
- `/home/xia-lab/wutx/01model/CellVoyager/cellvoyager/prompts/*.txt`

Observed framework:

1. Built-in analysis environment and constraints.
   - Known packages are constrained.
   - `adata` is prepared and summarized before code generation.
   - Prompt files define analysis expectations and code style.
2. LLM generates structured analysis plan and first code cell.
3. Notebook executor runs the generated code.
4. On failure, executor captures traceback/error output.
5. Repair loop feeds old code, error, and context back into the LLM.
6. New code replaces the failed cell and is rerun.

Conclusion: CellVoyager is not prompt-only. It has a fixed execution scaffold and a runtime code repair loop.

### 1.2 AutoBA

Relevant files:

- `/home/xia-lab/wutx/01model/AutoBA/src/agent.py`
- `/home/xia-lab/wutx/01model/AutoBA/src/executor.py`
- `/home/xia-lab/wutx/01model/AutoBA/src/prompt.py`

Observed framework:

1. Agent generates executable shell code for a task.
2. Executor writes `.execute.sh`, activates runtime environment, and executes shell code.
3. stdout/stderr are captured and summarized.
4. A second LLM prompt judges whether execution succeeded.
5. If failed, previous code and error information are injected into the next generation prompt.
6. The loop continues until success or interruption.

Conclusion: AutoBA is also not pure prompting. It uses an execution/evaluation/regeneration loop.

## 2. Current bbav5 Execution Framework

### 2.1 Main User Flow

Current natural language path:

```text
frontend input
  -> /api/agent/chat
  -> RouterAgent
  -> IntentAgentV2 / intent_parser
  -> /api/agent/plan
  -> PlanningAgentV2
  -> frontend confirmation dialog
  -> /api/execute
  -> apps.web.pipeline_backend.run_stage()
  -> apps/cli/run_*.py
  -> final artifacts + manifest
  -> frontend task polling
  -> result display / interpretation
```

Current direct stage path:

```text
frontend stage button
  -> confirmation dialog
  -> /api/execute
  -> run_stage_sync / Celery task
  -> pipeline_backend.run_stage()
  -> apps/cli/run_*.py
  -> manifest validation
  -> task status API
```

Current utility path:

```text
natural language utility request
  -> Router/Intent parser
  -> utility_tasks stage id
  -> plan/execute or direct execution
```

Problem: utility routing is not sufficiently object-aware. Result viewing, file transformation, sequence download, and pipeline execution can still be confused.

### 2.2 Current Diagnostic Path

Current intended path:

```text
stage failure
  -> DiagnosisAgent
  -> issue report / pending confirmation / runtime repair
```

Actual source-level finding:

1. `gfa_core/mas/agents/diagnosis.py` has useful rules and several job-local repair actions.
2. `gfa_core/mas/core/langgraph_orchestrator.py` advertises a diagnosis loop, but execution failures can short-circuit through result parsing and final output.
3. `apps/web/vue3/main.py` exposes diagnosis endpoints and task polling can display diagnosis data, but normal execution failure is not guaranteed to call diagnosis.
4. `/api/execute` and `run_stage_sync` do not consistently enforce preflight/failure/postflight diagnosis.

Conclusion: diagnosis exists but is not a mandatory execution node. This is why users can see ordinary stage failure messages without diagnosis popup or auto repair.

## 3. Target Global Multi-Agent Framework

The target should be a global orchestration contract, not only a DiagnosisAgent patch.

```text
User Request
  -> Intent Object Parser
  -> ProjectContextIndex
  -> StageCapabilityRegistry
  -> ArtifactResolver
  -> Planner
  -> PreflightDiagnosis
  -> Executor
  -> FailureDiagnosis / RuntimeRepair / bounded retry
  -> PostflightValidation
  -> ResultParser / Interpretation
  -> Reproducibility + Learning Store
```

### 3.1 Agent/Module Responsibilities

Router/Intent:

- Determine whether the user wants pipeline execution, result query, file preview, file transformation, sequence download, repair, or knowledge QA.
- Must use object references from the message, not only keywords or file extensions.

ProjectContextIndex:

- Read the actual job state before planning.
- Sources: `input/`, `final/`, stage directories, manifests, logs, `config.xlsx`, scope JSON, upload records, and task records.
- Output a structured context object containing family, species roles, files, artifacts, status, logs, aliases, and warnings.

StageCapabilityRegistry:

- Provide machine-readable stage contracts.
- For each stage: consumed artifact types, provided artifact types, scope support, input alternatives, preflight checks, postflight checks, repair candidates, rerun policy, runtime environment, CLI script.

ArtifactResolver:

- Resolve semantic needs to concrete files.
- Example needs: target proteome, reference family protein, selected-scope family members, target GFF, genome FASTA, count matrix, annotation background.
- Resolution priority:
  1. Explicit user path or parameter.
  2. Scope file.
  3. Successful manifest artifact.
  4. Canonical final file.
  5. `config.xlsx` row path.
  6. Canonical input file.
  7. Known reference database.
  8. Derivable artifact through safe repair/preparation.

Planner:

- Build executable plan from intent + context + capability + resolved artifacts.
- Do not reject with "missing protein" before checking final artifacts, scope files, and derivable alternatives.

Executor:

- Execute only after preflight resolution.
- Always pass resolved paths and scope parameters explicitly to CLI when possible.
- On failure, return structured error payload with log path, command, stage, prefix/scope, and stderr tail.

Diagnosis/Repair:

- Mandatory on preflight issue, stage failure, and postflight anomaly.
- Classify issue into:
  - `auto`: safe job-local repair.
  - `confirm`: user-visible confirmation required.
  - `report_only`: cannot repair automatically but should explain.
  - `dev_fix`: global source change required.
- Apply bounded retry for auto repairs.

Validator/ResultParser:

- Validate artifact existence, non-empty outputs, manifest schema, and semantic health.
- Stage success is not only exit code 0.

Learning/Repro:

- Record context snapshot, resolver decision, repairs applied, retry count, final status, and issue signatures.
- Future runs should reuse successful resolver/repair rules.

## 4. Repair Policy

Safe automatic repairs:

- Clean protein FASTA trailing `*` stop markers in job-local derived files.
- Symlink/copy NCBI family download to `{Species}.{Family}.pep.fa` when needed by reference-family logic.
- Repair missing manifest when final artifacts exist and can be validated.
- Re-resolve protein/GFF/genome files from final/input/config when preflight selected the wrong source.
- Regenerate pep/cds from genome+GFF when prepared pep/cds are missing or look genome-like.
- Use local HMM/PFAM fallback when remote PFAM URL fails.
- Produce ID mapping and overlap reports when FASTA/GFF/CDS IDs disagree.

Confirmation-required repairs:

- Overwrite user-uploaded inputs.
- Delete or replace existing final outputs.
- Change analysis scope from target-only to target+reference or all-selected.
- Re-run expensive stages after partial success if user has not requested auto-rerun.

Report-only or dev-fix cases:

- Missing external tools or conda packages.
- Broken global source code.
- Unsupported biological interpretation.
- Ambiguous user request that cannot be resolved from context.

## 5. Real Data Test Requirement

Each implementation phase must be tested with real data, not only syntax or compile checks.

Primary real-data scenario:

- Family: `SPL`
- Target species: `Lc`, `Dl`
- Reference species: `At`
- Comparative species: `Os`

Minimum required tests:

1. Upload/use `At.SPL.ids` by filename only and download protein sequences.
2. Query downloaded FASTA header IDs without triggering NCBI download again.
3. Prepare genome data with missing pep/cds where genome+GFF extraction is required.
4. Identify family members for selected target species only.
5. Build phylogeny with target+reference scope.
6. Run reference classification using tree + reference labels.
7. Run motif/domain/structure/combo from the same selected scope.
8. Simulate PFAM 404 and verify diagnosis + fallback behavior.
9. Simulate missing manifest with valid final artifacts and verify status/repair.
10. Verify frontend diagnosis popup appears after stage failure.