docs/implementation_plan.md

# Implementation Plan - Fraud Assistant Workflow Pattern

## Goal Description
Transition the `fraud_model_explainability_assistant` from a monolithic `Agent` loop to a structured "Workflow Pattern". This improves **Determinism** (explicit steps), **Auditability** (logging per step), **Reliability** (error handling per step), and enables **Human-in-the-loop** capabilities in the future.

The workflow will explicitly orchestrate:
1.  **Intent Analysis**: Understand what the user is asking.
2.  **Routing**: Decide which specialized sub-routine or tool to use.
3.  **Execution**: Run the tools (e.g., `explain_fraud_score`, `check_fair_lending_flags`).
4.  **Synthesis**: Generate the final response based on tool outputs.

## User Review Required
> [!IMPORTANT]
> This change refactors the core `query_agent` function in `app.py` to use a new `FraudWorkflow` class instead of the direct `strands.Agent` call. The external API endpoints remain the same.

## Proposed Changes

### Fraud Model Explainability Assistant

#### [NEW] [workflow.py](file:///Users/christiancontrerascampana/Desktop/GitHub/syf/fraud_model_explainability_assistant/workflow.py)
- **`FraudWorkflowState`**: A TypedDict/Pydantic model to hold the conversation state (messages, current context, tool outputs).
- **`FraudWorkflow` Class**:
    - `__init__`: Initialize models and tools.
    - `run(input)`: Main entry point.
    - `analyze_intent(state)`: Classify user query (Classification/Routing).
    - `execute_tools(state)`: Run selected tools based on intent.
    - `generate_response(state)`: Final synthesis.
    - Uses `strands` components where applicable (e.g., `OpenAIModel` for the cognitive steps).

#### [MODIFY] [app.py](file:///Users/christiancontrerascampana/Desktop/GitHub/syf/fraud_model_explainability_assistant/app.py)
- Import `FraudWorkflow`.
- Replace `create_enhanced_agent` with `create_workflow` (or update logic).
- Update `query_agent` to invoke `workflow.run()`.

#### [MODIFY] [utils.py](file:///Users/christiancontrerascampana/Desktop/GitHub/syf/fraud_model_explainability_assistant/utils.py)
- Ensure tools are compatible with direct python execution if needed (they already are decorated with `@tool` but can be called effectively as functions).

## Verification Plan

### Automated Tests
- Run `app.py` locally.
- Use `curl` or the built-in UI to send the example questions:
    - *"Why was application APP-78432 flagged?"* (Should trigger `get_application_summary` + `explain_fraud_score`)
    - *"Check fair lending compliance for APP-55555"* (Should trigger `check_fair_lending_flags`)

### Manual Verification
- Review logs to confirm the step-by-step execution (Intent -> Tool -> Response).
- Verify the quality of the answers matches or exceeds the previous implementation.