Motivation

This refactor introduces a graph-based structure to the existing imperative kaggle() workflow, allowing:

• Modular execution of each agent and integration step.

• State tracking for each stage (via LangGraph's shared state system).

• Future extensibility, including:

  • Plug-and-play memory retrieval (fast/slow mem),
  • Multi-turn Kaggle resolvers (this single turn serves as a subgraph)
  • Streaming intermediate results into a frontend or CLI interface.
  • Human-in-the-Loop support

LangGraph’s compositional structure allows better management of agent workflows as dynamic graphs, which aligns with long-term goals like auto-correction loops and human-agent collaboration.

Flow

┌───> 0. Init & shared state
│
├───> 1. Resume-decision (user)
│          │
│          └♦ cleans cache if resuming
│
├───> 2. Pick-competition & Download-dataset  (Kaggle API)
│
├───> 3. Fetch-overview & Summarise           (Kaggle API → Summary agent)
│
├───> 4. Advisor high-level report            (Advisor agent)
│
├───> 5. Generate dev-plan                    (Planner agent)
│
└───> 6. Coding-execution loop
            ├─ 6a. Code task      (Code agent)
            ├─ 6b. Debug-decision (user flag + code_report)
            └─ 6c. Debug loop     (Debug agent) ─► back to 6a if needed

flowchart TD
    %% ===== Main linear flow =====
    INIT[0 Init / shared state]
    RESUME["1 Resume-Decision (User)"]
    PICK[2 Select-Competition & Download]
    OVERVIEW[3 Fetch-Overview & Summarise]
    ADVISE[4 Advisor Report]
    PLAN[5 Generate Dev-Plan]
    CODELOOP["6 Coding-Execution (Sub-graph)"]

    INIT --> RESUME --> PICK --> OVERVIEW --> ADVISE --> PLAN --> CODELOOP

    %% ===== Coding / Debugging sub-graph =====
    subgraph CODELOOP [6 Coding-Execution loop]
        direction LR
        START_T[Start next task]
        CODE[6a. Code Task]
        DECIDE{{6b. Need Debug?}}
        DEBUG[6c. Debug Loop]
        END_T[Task done]

        START_T --> CODE
        CODE --> DECIDE
        DECIDE -- "auto-mode & debug=true" --> DEBUG
        DECIDE -- "otherwise" --> END_T
        DEBUG -- "fixed / success" --> END_T
        DEBUG -- "fail → recode" --> CODE
        END_T -->|next task| START_T
    end

Node catalogue

Edges & guards

Sequential edges: 0→1→2→3→4→5→6.

Conditional edges inside 6 (coding loop):

• DebugDecision routes either to CodeTask (new iteration) or to next-task/finish based on:
  • is_auto_mode = True AND code_report.debug == true → 6c
  • else → next task.
• DebugLoop re-enters CodeTask with the updated code_report.

Shared state schema

{
  "model": …,
  "cache": WorkflowCache,
  "integration": KaggleIntegration,
  "competition": str,
  "dataset_path": str,
  "ml_requirement": str,
  "advisor_report": str,
  "coding_plan": { "tasks": [ … ] },
  "is_auto_mode": bool,
  "code_report": dict,          # transient per iteration
  "final_code_reports": list    # aggregated after loop
}