Agentic Data Analysis Workflow: Design Case Study

A synthetic case study of typed handoffs, revision routing, and traceable state transitions in an agentic data-analysis workflow. The runnable code is a small deterministic simulator written from scratch for this portfolio.

What the simulator demonstrates

• Strict Pydantic contracts that reject undeclared fields
• Discriminated payload schemas for planning, design, and review results
• One run-level trace ID shared by every handoff
• Separate transition sequencing and per-stage attempt counters
• A runnable design-review and targeted-revision loop
• Human-review escalation represented in the result contract and prompt policy

Implemented scope

The runnable path covers planning, analysis design, design review, one targeted revision, and the approved handoff to implementation. The later stages in this conceptual diagram are architecture context only.

flowchart LR
    A[Request Intake] --> B[Clarification]
    B --> C[Intent Planning]
    C --> D[Analysis Design]
    D --> E{Design Review}
    E -- revise --> D
    E -- approved --> F[Implementation]
    F --> G{Code Review}
    G -- revise --> F
    G -- approved --> H[Execution]
    H --> I{Result Validation}
    I -- redesign --> D
    I -- regenerate --> F
    I -- valid --> J[Interpretation]

Loading

Repository structure

• src/contracts.py: strict result, payload, issue, and handoff contracts
• src/workflow.py: deterministic in-memory workflow simulator
• src/prompts.py: sanitized prompt-policy examples
• tests/: contract, trace, routing, and sample-output tests
• docs/architecture.md: design decisions and trade-offs
• examples/sample_run.json: a tested summary of the five handoffs

Requirements and local run

• Python 3.12 (tested version)

python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -r requirements.txt
pytest
python -m src.workflow

The module prints a run-level trace ID and the full validated handoff history. Every handoff in one run has the same trace_id; transition_sequence orders events globally, while stage_attempt counts attempts at the current stage.

Limitations

• The routing decision is scripted so the first design is revised and the second is approved.
• State lives in memory. Checkpoint stores, queues, APIs, and asynchronous workers sit outside the runnable boundary.
• The simulator uses deterministic local code. LLM calls, a LangGraph runtime, generated code, sandboxes, and external tools sit outside the runnable boundary.
• Contract status and policy represent human review. The simulator stops before a pause/resume interface.
• Implementation, execution, result validation, and interpretation are shown conceptually but are not executed.

Data and code boundary

All requests and outputs are synthetic. The code and examples were written for this repository. Employer prompts, datasets, business rules, credentials, and application source stay outside it.