Architecture

Four-Phase Agentic Framework

Stan implements the complete Project Phoenix Four-Phase Framework, providing progressive levels of transparency and control for agentic interactions.

0

Foundation

CLI, tools, data client

Complete

1

Glass Box

Plan builder, agentic engine

Complete

2

Human-in-Loop

Pause, resume, cancel

Complete

3

Progressive Disclosure

Expandable step details

Complete

4

Multi-Modal Output

Artifact workspace, exports

Complete

Component Architecture

unified_agent/
    data_client.py      # StanDataClient: homework metadata access
    tool_registry.py    # ToolRegistry: 17+ registered tools
    execution_context.py # ExecutionContext: shared state
    plan_builder.py     # PlanBuilder: query to ExecutionPlan
    agentic_engine.py   # AgenticEngine: state machine orchestrator

cli/main.py             # Interactive REPL or command-line
cockpit/stan_cockpit.py # Tkinter GUI (all four phases)
            

Core Flow

Query: PlanBuilder.build_plan() matches patterns to generate ExecutionPlan
Plan: AgenticEngine transitions: IDLE to PLANNING to AWAITING_APPROVAL
Execute: ToolRegistry dispatches to handlers, results stored in ExecutionContext
Result: Engine transitions to COMPLETED, GUI updates artifact workspace

State Machine

The AgenticEngine manages execution through a well-defined state machine:

IDLE
  |
  v
PLANNING
  |
  v
AWAITING_APPROVAL --[cancel]--> IDLE
  |
  [approve]
  |
  v
RUNNING --[pause]--> PAUSED --[resume]--> RUNNING
  |                     |
  [complete]        [cancel]
  |                     |
  v                     v
COMPLETED             IDLE
            

State Descriptions

State	Description	Valid Transitions
`IDLE`	Ready to accept new queries	PLANNING
`PLANNING`	Building execution plan from query	AWAITING_APPROVAL, IDLE (on error)
`AWAITING_APPROVAL`	Plan ready, waiting for user approval	RUNNING, IDLE (on cancel)
`RUNNING`	Executing plan steps	PAUSED, COMPLETED, IDLE (on error)
`PAUSED`	Execution paused by user	RUNNING, IDLE (on cancel)
`COMPLETED`	All steps executed successfully	IDLE (on reset)

Pattern Matching

The PlanBuilder uses regex patterns matched in priority order (most-specific first):

Pattern Categories

Priority	Category	Example Queries
1	Cross-homework	"compare homework 1 and 4", "chapter 7"
2	Homework-specific	"homework 1", "KNN", "naive bayes"
3	Exploration	"list scripts", "show capabilities"

Data Source

Homework scripts and data are read from ~/Python/Stan/:

~/Python/Stan/
    ESLII_print12_toc.pdf    # Textbook reference
    Stats315ASubmission.pdf   # Course submission
    Hmk1/                     # KNN Classification
        1/                    # Problem 1 scripts
    Hmk2/                     # Zipcode Analysis
    Hmk3/                     # Discriminant Analysis
        DA/                   # Golf analysis
    Hmk4/                     # Naive Bayes
        18.9/                 # Data piling
            