DEPLOY.md

Deploying LearningStudio Wrapper to Hugging Face

This guide explains how to deploy the LearningStudio callout detection wrapper to a HuggingFace Inference Endpoint.

Prerequisites

1. HuggingFace Account: Create an account at huggingface.co
2. HuggingFace CLI: Install the CLI tool
3. AWS Infrastructure: The callout detection Lambda stack must be deployed

Install HuggingFace CLI

pip install huggingface_hub

Login to HuggingFace

huggingface-cli login

Follow the prompts to enter your HuggingFace token.

Step 1: Get AWS API Gateway Info

After deploying the callout detection Lambda stack, get the API Gateway URL and key:

cd callout-detection-lambda

# Get the API Gateway endpoint URL
aws cloudformation describe-stacks \
    --stack-name callout-detection-dev \
    --query "Stacks[0].Outputs[?OutputKey=='ServiceEndpoint'].OutputValue" \
    --output text

# Get the API key
aws apigateway get-api-keys \
    --name-query "learningstudio-key-dev" \
    --include-values \
    --query "items[0].value" \
    --output text

Save these values - you'll need them when configuring the HF endpoint.

Step 2: Create HuggingFace Model Repository

First time only - create the model repository:

huggingface-cli repo create YOUR_USERNAME/learningstudio-callout-wrapper --type model

Or create via the HuggingFace web interface at https://huggingface.co/new

Step 3: Upload Wrapper Files

Navigate to the wrapper directory and upload files:

cd callout-detection-lambda/hf_inference/learningstudio_wrapper

# Upload all files to the repository
huggingface-cli upload YOUR_USERNAME/learningstudio-callout-wrapper \
    handler.py inference.py requirements.txt README.md \
    --repo-type model

Step 4: Create Inference Endpoint

1. Go to https://ui.endpoints.huggingface.co/
2. Click "New endpoint"
3. Select your model repository (YOUR_USERNAME/learningstudio-callout-wrapper)
4. Configure the endpoint:
   • Instance type: CPU (this wrapper doesn't need GPU)
   • Region: Choose a region close to your API Gateway
   • Scaling: Start with 1 replica

Step 5: Configure Secrets

In the HuggingFace Inference Endpoint settings, add environment variables:

1. Go to your endpoint settings
2. Click "Settings" or "Environment Variables"
3. Add the following secrets:

Name	Value
API_GATEWAY_URL	https://xxx.execute-api.us-east-1.amazonaws.com/dev
API_KEY	Your API key from Step 1

Step 6: Test the Endpoint

Once the endpoint is running, test it:

# Set your HuggingFace token
export HF_TOKEN="your-hf-token"

# Test with a URL
curl -X POST https://YOUR_ENDPOINT.endpoints.huggingface.cloud \
  -H "Authorization: Bearer $HF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"inputs": "https://example.com/test-drawing.png"}'

Expected response:

{
  "predictions": [
    {
      "id": 1,
      "label": "callout",
      "class_id": 0,
      "confidence": 0.95,
      "bbox": {"x1": 100, "y1": 200, "x2": 300, "y2": 400}
    }
  ],
  "total_detections": 1,
  "image": "...",
  "image_width": 1920,
  "image_height": 1080
}

Updating the Wrapper

To update the wrapper code:

cd callout-detection-lambda/hf_inference/learningstudio_wrapper

# Upload updated files
huggingface-cli upload YOUR_USERNAME/learningstudio-callout-wrapper \
    handler.py inference.py requirements.txt README.md \
    --repo-type model

The endpoint will automatically pick up the changes on the next request (after a brief cold start).

Rotating API Keys

To rotate the API key without touching the HF endpoint:

1. Create a new API key in AWS API Gateway
2. Update the API_KEY secret in HF endpoint settings
3. Delete the old API key in AWS

Troubleshooting

"API_GATEWAY_URL and API_KEY must be set"

The environment variables are not configured. Go to your endpoint settings and add the secrets.

Timeout errors

The callout detection pipeline takes 30-120 seconds typically. If you're getting timeouts:

• Check that the Lambda stack is deployed and working
• Verify the API Gateway URL is correct
• Check CloudWatch logs for the Lambda functions

Authentication errors

• Verify the API key is correct
• Check that the key hasn't been deleted or rotated
• Ensure the key is associated with the usage plan

Connection refused

• Verify the API Gateway URL is correct
• Check that the endpoint is in the right region
• Ensure the Lambda stack is deployed

Monitoring

• HuggingFace: Check endpoint logs in the HF dashboard
• AWS CloudWatch: Monitor Lambda function logs and metrics
• API Gateway: View API Gateway metrics for request counts and errors