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

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

• 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

• Import FraudWorkflow.
• Replace create_enhanced_agent with create_workflow (or update logic).
• Update query_agent to invoke workflow.run().

[MODIFY] 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.