Skip to content

API_README.md

Latest commit

 

History

History
224 lines (168 loc) · 4.52 KB

API_README.md

File metadata and controls

224 lines (168 loc) · 4.52 KB

TFLite Conversion API

This is a Flask-based REST API for converting TensorFlow.js models to TensorFlow Lite format and generating C/C++ byte arrays for microcontroller deployment.

Setup

  1. Install dependencies:
pip install -r requirements.txt
  1. Run the development server:
python app.py

The API will be available at http://localhost:3000

API Endpoints

POST /api/convert-to-tflite

Converts a TensorFlow.js model to TFLite format and returns formatted C/C++ code.

Request Body:

{
  "modelData": "base64-encoded model.json content",
  "weightsData": ["base64-encoded weight file 1", "..."],
  "modelMetadata": {
    "inputShape": [1, 224, 224, 3],
    "outputShape": [1, 10],
    "classes": ["class1", "class2", ...]
  },
  "options": {
    "quantize": true,
    "quantizationType": "int8",
    "arrayName": "g_person_detect_model_data",
    "includeMetadata": true
  }
}

Quantization Types:

  • "int8" (recommended): Full integer quantization - best for microcontrollers (smallest size, fastest inference)
  • "float16": Float16 weight quantization - moderate compression
  • "dynamic": Dynamic range quantization - weights to int8, activations stay float

Success Response (200):

{
  "success": true,
  "data": {
    "cppCode": "alignas(8) const unsigned char g_person_detect_model_data[] = {...}",
    "modelSize": 18432,
    "arrayName": "g_person_detect_model_data",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

Error Response (4xx/5xx):

{
  "success": false,
  "error": {
    "message": "Error message",
    "details": "Detailed error information",
    "type": "ERROR_TYPE",
    "suggestions": ["Suggestion 1", "Suggestion 2"],
    "retryable": true
  }
}

GET /api/health

Health check endpoint to verify the API is running.

Response (200):

{
  "status": "healthy",
  "service": "TFLite Conversion API",
  "timestamp": "2024-01-15T10:30:00Z"
}

GET /api/capture/camera

Returns the pre-compiled camera capture firmware binary for flashing to a device.

Request:

  • No request body required.

Response (200):

  • Content-Type: application/octet-stream
  • File download: camera_capture.bin

Error (404):

{
  "success": false,
  "error": {
    "message": "Binary not found",
    "details": "camera_capture.bin does not exist in templates/",
    "type": "FILE_NOT_FOUND",
    "retryable": false
  }
}

GET /api/capture/acceleration

Returns the pre-compiled acceleration capture firmware binary for flashing to a device.

Request:

  • No request body required.

Response (200):

  • Content-Type: application/octet-stream
  • File download: acceleration_capture.bin

Error (404):

{
  "success": false,
  "error": {
    "message": "Binary not found",
    "details": "acceleration_capture.bin does not exist in templates/",
    "type": "FILE_NOT_FOUND",
    "retryable": false
  }
}

GET /api/capture/gesture

Returns the pre-compiled gesture capture firmware binary for flashing to a device.

Request:

  • No request body required.

Response (200):

  • Content-Type: application/octet-stream
  • File download: gesture_capture.bin

Error (404):

{
  "success": false,
  "error": {
    "message": "Binary not found",
    "details": "gesture_capture.bin does not exist in templates/",
    "type": "FILE_NOT_FOUND",
    "retryable": false
  }
}

Error Types

  • VALIDATION_ERROR: Invalid request data (not retryable)
  • CONVERSION_ERROR: Model conversion failed (retryable)
  • UNSUPPORTED_OPS: Model contains unsupported operations (not retryable)
  • SIZE_LIMIT: Model exceeds size limits (not retryable)
  • NETWORK: Network-related errors (retryable)
  • UNKNOWN: Unexpected errors (retryable)

Configuration

  • Max Upload Size: 10MB (configurable in app.py)
  • Port: 3000 (default)
  • CORS: Enabled for localhost:5173 and localhost:3000

Testing

Run the test suite:

pytest tests/test_api.py -v

Run with coverage:

pytest tests/test_api.py --cov=app --cov-report=html

Production Deployment

For production, use a WSGI server like Gunicorn:

pip install gunicorn
gunicorn -w 4 -b 0.0.0.0:3000 app:app

Or use uWSGI:

pip install uwsgi
uwsgi --http :3000 --wsgi-file app.py --callable app --processes 4

Notes

  • The API automatically cleans up temporary files after each conversion
  • Conversion timeout is set to 60 seconds
  • Large models (>10MB) will be rejected
  • Quantization is enabled by default to reduce model size