# Rekognition State Machines

This directory contains AWS Step Functions state machine definitions for Rekognition workflows.

## Rekognition.asl.json

This state machine represents the end-to-end workflow for processing images using AWS Rekognition. It has been improved to include model availability checks and efficient resource utilization. The workflow includes the following steps:

1. **Check Pending Images** - Determines if there are any unprocessed images waiting for analysis
2. **Has Pending Images** - Choice state that decides whether to proceed with model startup based on the `should_start_model` flag
3. **Start Model** - Starts the Rekognition model if needed
4. **Wait For Model Startup** - Waits for a fixed period (60 seconds) to allow the model to initialize
5. **Check Model Availability** - Verifies if the model is in RUNNING state and ready to use
6. **Is Model Available** - Choice state that either proceeds to image analysis if the model is running (`model_available` is true) or returns to waiting
7. **Analyze Image** - Processes all unprocessed images using the running model 
8. **Stop Model** - Stops the Rekognition model when analysis is complete to save costs

### Key Improvements

- **Resource Efficiency**: Only starts the model if there are pending images to process
- **Proper Status Checking**: Verifies model availability before attempting image analysis
- **Wait States**: Includes appropriate wait periods for model startup
- **Error Handling**: Each task includes retry configurations to handle transient errors

### State Variables

- `should_start_model`: Boolean flag indicating if there are pending images requiring processing
- `model_available`: Boolean flag indicating if the model is in RUNNING state and ready to use

### Scheduled Execution

This state machine is configured to run automatically on a daily schedule:
- Schedule: Every day at 2:00 AM UTC
- Purpose: Check for and process any pending images once per day
- EventBridge Rule Name: `${StackName}-daily-processing-${Environment}`

## Rekognition_training.asl.json

This state machine orchestrates the complete Rekognition model training workflow. It follows these steps:

1. **Check Manifest Freshness** - Verifies if the manifest file has been updated within the last 24 hours
2. **Is Manifest Fresh** - Choice state that proceeds only if the manifest is recent enough
3. **Delete Datasets** - Remove existing datasets to start fresh
4. **Split Manifest** - Split the manifest file into training (80%) and testing (20%) datasets
5. **Create Dataset** - Create new datasets using the split manifest files
6. **Wait For Datasets** - Wait for dataset creation to complete
7. **Check Dataset Status** - Verify if datasets are ready for training
8. **Are Datasets Ready** - Choice state that proceeds or loops back based on dataset status
9. **Start Training** - Begin the model training process
10. **Wait For Training** - Wait for a fixed period before checking training status
11. **Check Training Status** - Check if training is complete and update Supabase
12. **Is Training Complete** - Decision point to either complete the workflow or return to waiting

The workflow now uses the `manifest_fresh` flag from the CheckManifestFreshness function to determine whether to proceed with training. If the manifest file is older than 24 hours, the workflow will terminate early to avoid training with outdated data.

### Scheduled Execution

This state machine is configured to run automatically on a weekly schedule:
- Schedule: Every Sunday at 1:00 AM UTC
- Purpose: Retrain the model weekly with the latest data
- EventBridge Rule Name: `${StackName}-weekly-training-${Environment}`
- Note: Training will only proceed if the manifest file is less than 24 hours old

## Usage

Both state machines are defined in the CloudFormation template and can be triggered via their respective API Gateway endpoints or through the AWS Step Functions console.

- Rekognition State Machine: POST /analyze
- Training State Machine: POST /start-training

In addition to the API endpoints, both state machines run automatically on their configured schedules.

## Troubleshooting

Common issues and solutions:

- **State Machine Stuck**: Check CloudWatch logs for the specific Lambda function that might be failing
- **Choice State Errors**: Verify that Lambda functions are returning the expected variables (e.g., `should_start_model`, `model_available`, or `manifest_fresh`)
- **Model Startup Issues**: Check the IAM permissions for the Lambda functions to ensure they can interact with Rekognition
- **Database Synchronization**: Ensure that database status fields (`model_status` and `status`) are properly synchronized with the actual AWS Rekognition model status
- **Manifest Freshness Issues**: If training always skips due to stale manifests, verify that the manifests are being properly updated in the S3 bucket
- **Scheduled Execution Issues**: Check the EventBridge rule status and ensure the IAM role has proper permissions