Merge pull request #1 from Xplorers-org/docker

.github/workflows/deploy-hf-space.yml

@@ -0,0 +1,33 @@
+name: Deploy to Hugging Face Space
+
+on:
+  push:
+    branches: ["main"]
+  workflow_dispatch:
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Configure Git
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+      - name: Push to Hugging Face Space
+        env:
+          HF_TOKEN: ${{ secrets.HF_TOKEN }}
+        run: |
+          if [ -z "${HF_TOKEN}" ]; then
+            echo "HF_TOKEN secret is missing"
+            exit 1
+          fi
+
+          git remote add hf "https://oauth2:${HF_TOKEN}@huggingface.co/spaces/xplorers/GAIT_API"
+          git push --force hf HEAD:main

.gitignore

@@ -173,6 +173,9 @@ cython_debug/
 # PyPI configuration file
 .pypirc
 
+# Runtime outputs
+runs/
+
 # Cursor  
 #  Cursor is an AI-powered code editor.`.cursorignore` specifies files/directories to 
 #  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data

Dockerfile

@@ -0,0 +1,34 @@
+FROM python:3.11-slim
+
+ENV PYTHONDONTWRITEBYTECODE=1
+ENV PYTHONUNBUFFERED=1
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y \
+    libglib2.0-0 \
+    libsm6 \
+    libxext6 \
+    libxrender1 \
+    libgomp1 \
+    libgl1 \
+    && rm -rf /var/lib/apt/lists/*
+
+# Set working directory
+WORKDIR /app
+
+# Copy requirements and install Python dependencies
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy application files
+COPY app.py /app/app.py
+COPY scripts /app/scripts
+
+# Create output directory
+RUN mkdir -p /app/runs/outputs && chmod +x /app/scripts/start.sh
+
+# Expose port
+EXPOSE 7860
+
+# Run the application
+CMD ["/app/scripts/start.sh"]

README.md

@@ -20,7 +20,15 @@ Open Swagger UI:
 - `POST /analyze`
   - form-data:
     - `video`: video file (front-view gait)
-    - `patient_gender`: `male` or `female`
+    - `gender`: `male` or `female`
+
+- `POST /analyze_files`
+  - form-data:
+    - `video`: video file
+    - `gender`: `male` or `female`
+
+- `GET /download/{filename}`
+- `GET /health`
 
 Response includes:
 
@@ -29,3 +37,63 @@ Response includes:
 - full feature values
 - URL to annotated output video
 - URL to biomarker plot image
+
+## Automatic cleanup for runs/
+
+Generated files from `/analyze_files` are stored under `runs/outputs`.
+To prevent storage growth, use the cleanup script every 30 minutes.
+
+Script path:
+
+- `scripts/cleanup_runs.py`
+
+Behavior:
+
+- Deletes files older than 30 minutes (default)
+- Removes empty subdirectories
+
+### Local host cron example
+
+```bash
+*/30 * * * * /usr/bin/python3 /path/to/GAIT_API/scripts/cleanup_runs.py --path /path/to/GAIT_API/runs --max-age-minutes 30 >> /var/log/gait_cleanup.log 2>&1
+```
+
+### Docker container cron example (host cron running docker exec)
+
+```bash
+*/30 * * * * docker exec gait-api python /app/scripts/cleanup_runs.py --path /app/runs --max-age-minutes 30 >> /var/log/gait_cleanup.log 2>&1
+```
+
+Replace `gait-api` with your running container name.
+
+## Hugging Face Spaces (Docker) deployment
+
+This repository is ready for Docker Spaces deployment. The container now:
+
+- listens on `PORT` (default `7860`) required by Spaces
+- starts a background cleanup loop for `/app/runs`
+- launches the API via `scripts/start.sh`
+
+Environment variables (optional):
+
+- `PORT` (default: `7860`)
+- `CLEANUP_INTERVAL_SECONDS` (default: `1800`)
+- `RUNS_MAX_AGE_MINUTES` (default: `30`)
+
+## GitHub Actions auto-deploy to your HF Space
+
+Workflow file:
+
+- `.github/workflows/deploy-hf-space.yml`
+
+Target Space:
+
+- `xplorers/GAIT_API`
+
+### Required GitHub secret
+
+Add this repository secret in GitHub:
+
+- `HF_TOKEN` = a Hugging Face User Access Token with write permission to `xplorers/GAIT_API`
+
+On every push to `main`, GitHub Actions force-pushes this repo to your Space.

app.py

@@ -1,58 +1,54 @@
-import uuid
-from typing import Annotated
-from pathlib import Path
-from typing import Any, Dict, List, Literal, Tuple
-
+from fastapi import FastAPI, File, UploadFile, Form, HTTPException
+from fastapi.responses import FileResponse, JSONResponse
+from fastapi.middleware.cors import CORSMiddleware
 import cv2
 import mediapipe as mp
+import numpy as np
 import matplotlib
+matplotlib.use('Agg')  # Use non-interactive backend
 import matplotlib.pyplot as plt
-import numpy as np
-from fastapi import FastAPI, File, Form, HTTPException, UploadFile
-from fastapi.responses import FileResponse
-from fastapi.staticfiles import StaticFiles
-from pydantic import BaseModel
-from scipy.signal import detrend, find_peaks, savgol_filter
+from scipy.signal import find_peaks, savgol_filter, detrend
+import os
+import tempfile
+import shutil
+from pathlib import Path
+from typing import Dict, List, Tuple
+import base64
+import io
 
-# Use a non-interactive backend for server-side rendering.
-matplotlib.use("Agg")
+app = FastAPI(
+    title="Gait Analysis API",
+    description="Clinical gait analysis using MediaPipe Pose estimation",
+    version="1.0.0"
+)
 
-# Initialize MediaPipe Pose Model (High Complexity for Clinical Accuracy)
+# Add CORS middleware
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+# Initialize MediaPipe Pose Model
 mp_pose = mp.solutions.pose
 pose = mp_pose.Pose(
     static_image_mode=False,
     model_complexity=2,
     min_detection_confidence=0.5,
-    min_tracking_confidence=0.5,
+    min_tracking_confidence=0.5
 )
-
 mp_drawing = mp.solutions.drawing_utils
 
-BASE_DIR = Path(__file__).resolve().parent
-RUNS_DIR = BASE_DIR / "runs"
-INPUTS_DIR = RUNS_DIR / "inputs"
-OUTPUTS_DIR = RUNS_DIR / "outputs"
-PLOTS_DIR = RUNS_DIR / "plots"
-for folder in (RUNS_DIR, INPUTS_DIR, OUTPUTS_DIR, PLOTS_DIR):
-    folder.mkdir(parents=True, exist_ok=True)
-
-app = FastAPI(
-    title="HEMAS NeuroTrack Gait Analysis API",
-    description="FastAPI version of the complete gait notebook with identical scoring and interpretation logic.",
-    version="1.0.0",
-)
-app.mount("/runs", StaticFiles(directory=str(RUNS_DIR)), name="runs")
-
+# Create output directory(1)
+# OUTPUT_DIR = Path("/tmp/gait_outputs")
+# OUTPUT_DIR.mkdir(exist_ok=True)
 
-class AnalyzeResponse(BaseModel):
-    run_id: str
-    fps: float
-    features: Dict[str, float]
-    clinical_report: str
-    gait_score: float
-    gait_interpretation: str
-    annotated_video_url: str
-    plot_image_url: str
+# Create output directory(2) (cross-platform, inside repository)
+BASE_DIR = Path(__file__).resolve().parent
+OUTPUT_DIR = BASE_DIR / "runs" / "outputs"
+OUTPUT_DIR.mkdir(parents=True, exist_ok=True)
 
 
 def smooth_signal(data, window_length=9, polyorder=3):
@@ -68,18 +64,14 @@ def extract_validate_and_visualize(input_video_path, output_video_path):
 
     width = int(cap.get(cv2.CAP_PROP_FRAME_WIDTH))
     height = int(cap.get(cv2.CAP_PROP_FRAME_HEIGHT))
-    fourcc = cv2.VideoWriter_fourcc(*"mp4v")
+    fourcc = cv2.VideoWriter_fourcc(*'mp4v')
     out = cv2.VideoWriter(output_video_path, fourcc, fps, (width, height))
 
     signals = {
-        "l_ankle_y": [],
-        "r_ankle_y": [],
-        "l_arm_swing": [],
-        "r_arm_swing": [],
-        "mid_hip_x": [],
-        "mid_hip_y": [],
-        "l_foot_x": [],
-        "r_foot_x": [],
+        'l_ankle_y': [], 'r_ankle_y': [],
+        'l_arm_swing': [], 'r_arm_swing': [],
+        'mid_hip_x': [], 'mid_hip_y': [],
+        'l_foot_x': [], 'r_foot_x': []
     }
 
     while cap.isOpened():
@@ -97,54 +89,46 @@ def extract_validate_and_visualize(input_video_path, output_video_path):
         if results.pose_landmarks:
             lm = results.pose_landmarks.landmark
 
-            # -----------------------------
-            # BODY CENTER (IMPORTANT)
-            # -----------------------------
+            # BODY CENTER
             mid_hip_x = (lm[23].x + lm[24].x) / 2
             mid_hip_y = (lm[23].y + lm[24].y) / 2
 
-            signals["mid_hip_x"].append(mid_hip_x)
-            signals["mid_hip_y"].append(mid_hip_y)
+            signals['mid_hip_x'].append(mid_hip_x)
+            signals['mid_hip_y'].append(mid_hip_y)
 
-            # -----------------------------
-            # LOWER BODY (RELATIVE SIGNAL)
-            # -----------------------------
-            signals["l_ankle_y"].append(lm[27].y)
-            signals["r_ankle_y"].append(lm[28].y)
+            # LOWER BODY
+            signals['l_ankle_y'].append(lm[27].y)
+            signals['r_ankle_y'].append(lm[28].y)
 
-            # FIX: normalize foot X relative to body center
-            signals["l_foot_x"].append(lm[31].x - mid_hip_x)
-            signals["r_foot_x"].append(lm[32].x - mid_hip_x)
+            # Normalize foot X relative to body center
+            signals['l_foot_x'].append(lm[31].x - mid_hip_x)
+            signals['r_foot_x'].append(lm[32].x - mid_hip_x)
 
-            # -----------------------------
-            # ARM SWING (IMPROVED)
-            # -----------------------------
+            # ARM SWING
             l_torso_len = np.linalg.norm([
                 lm[11].x - lm[23].x,
-                lm[11].y - lm[23].y,
+                lm[11].y - lm[23].y
             ])
             r_torso_len = np.linalg.norm([
                 lm[12].x - lm[24].x,
-                lm[12].y - lm[24].y,
+                lm[12].y - lm[24].y
             ])
 
-            # FIX: relative to shoulder (remove body sway)
+            # Relative to shoulder
             l_ws = np.linalg.norm([
                 lm[15].x - lm[11].x,
-                lm[15].y - lm[11].y,
+                lm[15].y - lm[11].y
             ])
             r_ws = np.linalg.norm([
                 lm[16].x - lm[12].x,
-                lm[16].y - lm[12].y,
+                lm[16].y - lm[12].y
             ])
 
-            # FINAL: normalized + stabilized
-            signals["l_arm_swing"].append(l_ws / (l_torso_len + 1e-6))
-            signals["r_arm_swing"].append(r_ws / (r_torso_len + 1e-6))
+            # Normalized + stabilized
+            signals['l_arm_swing'].append(l_ws / (l_torso_len + 1e-6))
+            signals['r_arm_swing'].append(r_ws / (r_torso_len + 1e-6))
 
-            # -----------------------------
             # DRAW SKELETON
-            # -----------------------------
             mp_drawing.draw_landmarks(
                 image_bgr,
                 results.pose_landmarks,
@@ -154,7 +138,7 @@ def extract_validate_and_visualize(input_video_path, output_video_path):
                 ),
                 connection_drawing_spec=mp_drawing.DrawingSpec(
                     color=(255, 255, 255), thickness=2
-                ),
+                )
             )
 
         out.write(image_bgr)
@@ -162,78 +146,61 @@ def extract_validate_and_visualize(input_video_path, output_video_path):
     cap.release()
     out.release()
 
-    # -----------------------------
     # VALIDATION
-    # -----------------------------
-    if len(signals["mid_hip_x"]) == 0:
+    if len(signals['mid_hip_x']) == 0:
         raise ValueError("❌ No person detected in the video.")
 
     # IMPROVED SIDE VIEW DETECTION
-    x_var = np.var(signals["mid_hip_x"])
-    y_var = np.var(signals["mid_hip_y"])
+    x_var = np.var(signals['mid_hip_x'])
+    y_var = np.var(signals['mid_hip_y'])
 
-    if x_var > y_var:  # more horizontal movement -> side view
+    if x_var > y_var:
         raise ValueError("❌ SIDE-VIEW DETECTED: Upload FRONT-VIEW video")
 
-    # -----------------------------
     # SMOOTH SIGNALS
-    # -----------------------------
     for key in signals:
         signals[key] = smooth_signal(np.array(signals[key]))
 
-    print("✅ Signal extraction complete (normalized + stabilized)")
-
     return signals, fps
 
 
-def robust_amplitude(signal, threshold=0.08):
-    """
-    Computes real movement amplitude and removes MediaPipe noise.
-    """
+def robust_amplitude(signal, threshold=0.01):
+    """Computes real movement amplitude and removes MediaPipe noise."""
     if len(signal) == 0:
         return 0
-
-    amp = np.max(signal) - np.min(signal)
-
-    # Noise filtering
+    amp = np.percentile(signal, 95) - np.percentile(signal, 5)
     return amp if amp > threshold else 0
 
 
 def compute_gait_features(signals, fps):
     features = {}
 
-    # -----------------------------
-    # 1. FOOT X SIGNAL
-    # -----------------------------
-    l_signal = detrend(signals["l_foot_x"])
-    r_signal = detrend(signals["r_foot_x"])
+    # FOOT X SIGNAL
+    l_signal = detrend(signals['l_foot_x'])
+    r_signal = detrend(signals['r_foot_x'])
 
     def smooth(x):
-        return np.convolve(x, np.ones(7) / 7, mode="same")  # balanced smoothing
+        return np.convolve(x, np.ones(7)/7, mode='same')
 
     l_signal = smooth(l_signal)
     r_signal = smooth(r_signal)
 
-    # -----------------------------
-    # 2. PEAK DETECTION
-    # -----------------------------
+    # PEAK DETECTION
     min_distance = int(fps * 0.3)
 
     l_peaks, _ = find_peaks(
         l_signal,
         distance=min_distance,
-        prominence=np.std(l_signal) * 0.25,
+        prominence=np.std(l_signal) * 0.25
     )
 
     r_peaks, _ = find_peaks(
         r_signal,
         distance=min_distance,
-        prominence=np.std(r_signal) * 0.25,
+        prominence=np.std(r_signal) * 0.25
     )
 
-    # -----------------------------
-    # 3. CLEAN PEAKS
-    # -----------------------------
+    # CLEAN PEAKS
     def clean_peaks(peaks, fps, min_gap=0.4):
         if len(peaks) == 0:
             return peaks
@@ -247,15 +214,11 @@ def compute_gait_features(signals, fps):
     l_peaks = clean_peaks(l_peaks, fps)
     r_peaks = clean_peaks(r_peaks, fps)
 
-    # -----------------------------
-    # 4. STRIDE TIMES
-    # -----------------------------
+    # STRIDE TIMES
     l_stride = np.diff(l_peaks) / fps if len(l_peaks) > 1 else np.array([])
     r_stride = np.diff(r_peaks) / fps if len(r_peaks) > 1 else np.array([])
 
-    # -----------------------------
-    # 5. ROBUST FILTER (RELAXED)
-    # -----------------------------
+    # ROBUST FILTER
     def filter_stride(strides):
         if len(strides) < 2:
             return strides
@@ -263,9 +226,8 @@ def compute_gait_features(signals, fps):
         median = np.median(strides)
 
         filtered = strides[
-            (strides > 0.4)
-            & (strides < 1.3)  # slightly relaxed
-            & (np.abs(strides - median) < 0.15)  # not too strict
+            (strides > 0.4) & (strides < 1.3) &
+            (np.abs(strides - median) < 0.15)
         ]
 
         return filtered
@@ -273,70 +235,45 @@ def compute_gait_features(signals, fps):
     l_stride = filter_stride(l_stride)
     r_stride = filter_stride(r_stride)
 
-    # -----------------------------
-    # 6. STRIDE VARIABILITY (FIXED PROPERLY)
-    # -----------------------------
+    # STRIDE VARIABILITY
     stride_variability = None
 
-    # Case 1: Both sides available
     if len(l_stride) >= 2 and len(r_stride) >= 2:
         cv_left = np.std(l_stride) / np.median(l_stride)
         cv_right = np.std(r_stride) / np.median(r_stride)
-
         stride_variability = ((cv_left + cv_right) / 2) * 100
-
-    # Case 2: Only one side available
     elif len(l_stride) >= 2:
         stride_variability = (np.std(l_stride) / np.median(l_stride)) * 100
-
     elif len(r_stride) >= 2:
         stride_variability = (np.std(r_stride) / np.median(r_stride)) * 100
-
-    # Case 3: Not enough data
     else:
-        stride_variability = 0.5  # fallback (NOT zero)
+        stride_variability = 0.5
 
-    # Clamp to realistic clinical range
     stride_variability = max(0.5, min(stride_variability, 8.5))
+    features['stride_variability'] = stride_variability
 
-    features["stride_variability"] = stride_variability
-
-    # -----------------------------
-    # 7. CADENCE
-    # -----------------------------
+    # CADENCE
     total_steps = len(l_peaks) + len(r_peaks)
     duration_minutes = len(l_signal) / fps / 60
-
     cadence = total_steps / duration_minutes if duration_minutes > 0 else 0
-    features["cadence"] = cadence
+    features['cadence'] = cadence
 
-    # -----------------------------
-    # 8. SYMMETRY
-    # -----------------------------
+    # SYMMETRY
     if len(l_stride) > 0 and len(r_stride) > 0:
         l_mean = np.mean(l_stride)
         r_mean = np.mean(r_stride)
-
         symmetry = abs(l_mean - r_mean) / ((l_mean + r_mean) / 2)
     else:
         symmetry = 0
 
-    features["symmetry_ratio"] = symmetry
-
-    # -----------------------------
-    # 9. ARM SWING (UNCHANGED)
-    # -----------------------------
-    def robust_amplitude_local(signal, threshold=0.01):
-        if len(signal) == 0:
-            return 0
-        amp = np.percentile(signal, 95) - np.percentile(signal, 5)
-        return amp if amp > threshold else 0
+    features['symmetry_ratio'] = symmetry
 
-    l_arm = smooth(signals["l_arm_swing"])
-    r_arm = smooth(signals["r_arm_swing"])
+    # ARM SWING
+    l_arm = smooth(signals['l_arm_swing'])
+    r_arm = smooth(signals['r_arm_swing'])
 
-    l_amp = robust_amplitude_local(l_arm)
-    r_amp = robust_amplitude_local(r_arm)
+    l_amp = robust_amplitude(l_arm)
+    r_amp = robust_amplitude(r_arm)
 
     scale_factor = 20.0
     l_amp *= scale_factor
@@ -344,208 +281,114 @@ def compute_gait_features(signals, fps):
 
     avg_arm = (l_amp + r_amp) / 2
 
-    features["l_arm_amp"] = l_amp
-    features["r_arm_amp"] = r_amp
-    features["avg_arm_swing"] = avg_arm
+    features['l_arm_amp'] = l_amp
+    features['r_arm_amp'] = r_amp
+    features['avg_arm_swing'] = avg_arm
 
-    # -----------------------------
-    # 10. ARM ASYMMETRY
-    # -----------------------------
+    # ARM ASYMMETRY
     if l_amp > 0 and r_amp > 0:
         asym = abs(l_amp - r_amp) / max(l_amp, r_amp) * 100
     else:
         asym = 100
 
-    features["arm_asymmetry_index"] = asym
+    features['arm_asymmetry_index'] = asym
 
-    # -----------------------------
     # Save signals for plots
-    # -----------------------------
-    signals["l_signal"] = l_signal
-    signals["r_signal"] = r_signal
+    signals['l_signal'] = l_signal
+    signals['r_signal'] = r_signal
 
     return features, l_peaks, r_peaks
 
 
 def interpret_clinical_features(features, gender):
-    lines: List[str] = []
-    lines.append("\n" + "=" * 50)
-    lines.append(f" HEMAS NEUROTRACK: CLINICAL INTERPRETATION ({gender.upper()})")
-    lines.append("=" * 50)
-
-    cv = features["stride_variability"]
-    lines.append(f"\n▶ STRIDE TIME VARIABILITY: {cv:.2f}%")
-    if gender.lower() == "male":
+    """Generate clinical interpretation text"""
+    interpretation = []
+    
+    interpretation.append("=" * 50)
+    interpretation.append(f" HEMAS NEUROTRACK: CLINICAL INTERPRETATION ({gender.upper()})")
+    interpretation.append("=" * 50)
+
+    # Stride Variability
+    cv = features['stride_variability']
+    interpretation.append(f"\n▶ STRIDE TIME VARIABILITY: {cv:.2f}%")
+    if gender.lower() == 'male':
         if cv <= 2.5:
-            lines.append("   ↳ Status: NORMAL (Healthy rhythm)")
+            interpretation.append("   ↳ Status: NORMAL (Healthy rhythm)")
         elif cv <= 4.0:
-            lines.append("   ↳ Status: MILD DEVIATION (Slight irregularity)")
+            interpretation.append("   ↳ Status: MILD DEVIATION (Slight irregularity)")
         elif cv <= 6.0:
-            lines.append("   ↳ Status: MODERATE IMPAIRMENT (Noticeable rhythm fluctuation)")
+            interpretation.append("   ↳ Status: MODERATE IMPAIRMENT (Noticeable rhythm fluctuation)")
         else:
-            lines.append("   ↳ Status: HIGH IMPAIRMENT (Severe gait instability detected)")
-    elif gender.lower() == "female":
+            interpretation.append("   ↳ Status: HIGH IMPAIRMENT (Severe gait instability detected)")
+    elif gender.lower() == 'female':
         if cv <= 3.0:
-            lines.append("   ↳ Status: NORMAL (Healthy rhythm)")
+            interpretation.append("   ↳ Status: NORMAL (Healthy rhythm)")
         elif cv <= 4.5:
-            lines.append("   ↳ Status: MILD DEVIATION (Slight irregularity)")
+            interpretation.append("   ↳ Status: MILD DEVIATION (Slight irregularity)")
         elif cv <= 6.5:
-            lines.append("   ↳ Status: MODERATE IMPAIRMENT (Noticeable rhythm fluctuation)")
+            interpretation.append("   ↳ Status: MODERATE IMPAIRMENT (Noticeable rhythm fluctuation)")
         else:
-            lines.append("   ↳ Status: HIGH IMPAIRMENT (Severe gait instability detected)")
+            interpretation.append("   ↳ Status: HIGH IMPAIRMENT (Severe gait instability detected)")
 
-    cad = features["cadence"]
-    lines.append(f"\n▶ CADENCE: {cad:.1f} steps/min")
-    if gender.lower() == "male":
+    # Cadence
+    cad = features['cadence']
+    interpretation.append(f"\n▶ CADENCE: {cad:.1f} steps/min")
+    if gender.lower() == 'male':
         if cad >= 100:
-            lines.append("   ↳ Status: NORMAL (Healthy pace)")
+            interpretation.append("   ↳ Status: NORMAL (Healthy pace)")
         elif cad >= 90:
-            lines.append("   ↳ Status: MILD REDUCTION (Slightly slower pace)")
+            interpretation.append("   ↳ Status: MILD REDUCTION (Slightly slower pace)")
         elif cad >= 80:
-            lines.append("   ↳ Status: MODERATE REDUCTION (Bradykinesia indicator)")
+            interpretation.append("   ↳ Status: MODERATE REDUCTION (Bradykinesia indicator)")
         else:
-            lines.append("   ↳ Status: HIGH REDUCTION (Severe shuffling or freezing tendency)")
-    elif gender.lower() == "female":
+            interpretation.append("   ↳ Status: HIGH REDUCTION (Severe shuffling or freezing tendency)")
+    elif gender.lower() == 'female':
         if cad >= 105:
-            lines.append("   ↳ Status: NORMAL (Healthy pace)")
+            interpretation.append("   ↳ Status: NORMAL (Healthy pace)")
         elif cad >= 95:
-            lines.append("   ↳ Status: MILD REDUCTION (Slightly slower pace)")
+            interpretation.append("   ↳ Status: MILD REDUCTION (Slightly slower pace)")
         elif cad >= 85:
-            lines.append("   ↳ Status: MODERATE REDUCTION (Bradykinesia indicator)")
+            interpretation.append("   ↳ Status: MODERATE REDUCTION (Bradykinesia indicator)")
         else:
-            lines.append("   ↳ Status: HIGH REDUCTION (Severe shuffling or freezing tendency)")
+            interpretation.append("   ↳ Status: HIGH REDUCTION (Severe shuffling or freezing tendency)")
 
-    lines.append("\n▶ GAIT SYMMETRY:")
-    sym = features["symmetry_ratio"]
+    # Symmetry
+    interpretation.append("\n▶ GAIT SYMMETRY:")
+    sym = features['symmetry_ratio']
     if sym >= 0.95:
-        lines.append("   ↳ Status: HIGHLY SYMMETRIC (Healthy left/right balance)")
+        interpretation.append("   ↳ Status: HIGHLY SYMMETRIC (Healthy left/right balance)")
     elif sym >= 0.85:
-        lines.append("   ↳ Status: MILD ASYMMETRY (Slight favoring of one leg)")
+        interpretation.append("   ↳ Status: MILD ASYMMETRY (Slight favoring of one leg)")
     else:
-        lines.append("   ↳ Status: SIGNIFICANT ASYMMETRY (Typical of unilateral Parkinsonian symptoms)")
+        interpretation.append("   ↳ Status: SIGNIFICANT ASYMMETRY (Typical of unilateral Parkinsonian symptoms)")
 
-    lines.append("\n▶ OVERALL ARM SWING:")
-    swing = features["avg_arm_swing"]
-    lines.append(f"   [Raw AI Swing Variance Score: {swing:.2f}]")
+    # Arm Swing
+    interpretation.append("\n▶ OVERALL ARM SWING:")
+    swing = features['avg_arm_swing']
+    interpretation.append(f"   [Raw AI Swing Variance Score: {swing:.2f}]")
 
     if swing > 5.0:
-        lines.append("   ↳ Status: HEALTHY RANGE OF MOTION (Fluid arm swing)")
+        interpretation.append("   ↳ Status: HEALTHY RANGE OF MOTION (Fluid arm swing)")
     elif swing > 2.5:
-        lines.append("   ↳ Status: REDUCED AMPLITUDE (Stiffened arm movement)")
+        interpretation.append("   ↳ Status: REDUCED AMPLITUDE (Stiffened arm movement)")
     else:
-        lines.append("   ↳ Status: SEVERELY RESTRICTED (En-bloc / Rigid posture detected)")
+        interpretation.append("   ↳ Status: SEVERELY RESTRICTED (En-bloc / Rigid posture detected)")
 
-    lines.append("\n▶ ARM SWING ASYMMETRY:")
-    arm_asym = features["arm_asymmetry_index"]
-    lines.append(f"   [Raw AI Asymmetry Index: {arm_asym:.1f}%]")
+    # Arm Asymmetry
+    interpretation.append("\n▶ ARM SWING ASYMMETRY:")
+    arm_asym = features['arm_asymmetry_index']
+    interpretation.append(f"   [Raw AI Asymmetry Index: {arm_asym:.1f}%]")
 
     if arm_asym <= 25.0:
-        lines.append("   ↳ Status: BALANCED (Both arms swing/rest equally)")
+        interpretation.append("   ↳ Status: BALANCED (Both arms swing/rest equally)")
     elif arm_asym <= 45.0:
-        lines.append("   ↳ Status: MILD ASYMMETRY (One arm shows slight rigidity)")
+        interpretation.append("   ↳ Status: MILD ASYMMETRY (One arm shows slight rigidity)")
     else:
-        lines.append("   ↳ Status: UNILATERAL RIGIDITY (One arm is significantly stiffer than the other)")
-
-    lines.append("\n" + "=" * 50)
-
-    return "\n".join(lines)
-
-
-def plot_clinical_biomarkers(signals, features, l_peaks, r_peaks, fps, plot_output_path):
-    fig, axs = plt.subplots(3, 2, figsize=(16, 14))
-    fig.suptitle(
-        "NeuroTrack AI: Kinematic Gait Analysis",
-        fontsize=20,
-        fontweight="bold",
-        color="#1f77b4",
-    )
-
-    time_axis = np.arange(len(signals["l_ankle_y"])) / fps
-
-    # -----------------------------
-    # 1. Ankle Vertical Displacement
-    # -----------------------------
-    axs[0, 0].plot(time_axis, signals["l_ankle_y"], label="Left Ankle", color="blue", alpha=0.7)
-    axs[0, 0].plot(time_axis, signals["r_ankle_y"], label="Right Ankle", color="orange", alpha=0.7)
-    axs[0, 0].set_title("Ankle Vertical Displacement")
-    axs[0, 0].invert_yaxis()
-    axs[0, 0].legend()
-
-    # -----------------------------
-    # 2. Peak Detection (FIXED)
-    # -----------------------------
-    if "l_signal" in signals and "r_signal" in signals:
-        axs[0, 1].plot(time_axis, signals["l_signal"], color="gray", alpha=0.6)
-
-        if len(l_peaks) > 0:
-            axs[0, 1].plot(
-                time_axis[l_peaks],
-                signals["l_signal"][l_peaks],
-                "X",
-                color="red",
-                markersize=8,
-                label="Left Steps",
-            )
-
-        if len(r_peaks) > 0:
-            axs[0, 1].plot(
-                time_axis[r_peaks],
-                signals["r_signal"][r_peaks],
-                "X",
-                color="green",
-                markersize=8,
-                label="Right Steps",
-            )
-
-        axs[0, 1].set_title("Step Detection (Foot X Signal)")
-        axs[0, 1].legend()
-    else:
-        axs[0, 1].set_title("Step Detection (No Data)")
-
-    # -----------------------------
-    # 3. Stride Times
-    # -----------------------------
-    l_stride_times = np.diff(l_peaks) / fps if len(l_peaks) > 1 else []
-    r_stride_times = np.diff(r_peaks) / fps if len(r_peaks) > 1 else []
-
-    if len(l_stride_times) > 0:
-        axs[1, 0].plot(l_stride_times, marker="o", linestyle="-", color="blue", label="Left")
-
-    if len(r_stride_times) > 0:
-        axs[1, 0].plot(r_stride_times, marker="o", linestyle="-", color="orange", label="Right")
+        interpretation.append("   ↳ Status: UNILATERAL RIGIDITY (One arm is significantly stiffer than the other)")
 
-    axs[1, 0].set_title(f"Stride Variability (CV: {features['stride_variability']:.2f}%)")
-    axs[1, 0].legend()
-
-    # -----------------------------
-    # 4. Arm Swing
-    # -----------------------------
-    axs[1, 1].plot(time_axis, signals["l_arm_swing"], label="Left Arm", color="purple", alpha=0.7)
-    axs[1, 1].plot(time_axis, signals["r_arm_swing"], label="Right Arm", color="brown", alpha=0.7)
-    axs[1, 1].set_title("Normalized Arm Swing")
-    axs[1, 1].legend()
-
-    # -----------------------------
-    # 5. Arm Amplitude
-    # -----------------------------
-    axs[2, 0].bar(
-        ["Left Arm", "Right Arm"],
-        [features["l_arm_amp"], features["r_arm_amp"]],
-        color=["purple", "brown"],
-    )
-    axs[2, 0].set_title(f"Arm Asymmetry Index: {features['arm_asymmetry_index']:.1f}%")
-    axs[2, 0].set_ylabel("Amplitude")
-
-    # -----------------------------
-    # 6. Postural Sway
-    # -----------------------------
-    axs[2, 1].plot(time_axis, signals["mid_hip_x"], color="teal")
-    axs[2, 1].set_title("Postural Sway (Hip X Movement)")
-
-    # -----------------------------
-    plt.tight_layout(rect=[0, 0.03, 1, 0.95])
-    fig.savefig(plot_output_path, dpi=150)
-    plt.close(fig)
+    interpretation.append("\n" + "=" * 50)
+    
+    return "\n".join(interpretation)
 
 
 def score_stride_variability(v):
@@ -612,26 +455,24 @@ def score_arm_asymmetry(a):
 
 
 def compute_gait_stability_score(features):
-    sv = features["stride_variability"]
-    sym = features["symmetry_ratio"]
-    cad = features["cadence"]
-    arm = features["avg_arm_swing"]
-    asym = features["arm_asymmetry_index"]
+    sv = features['stride_variability']
+    sym = features['symmetry_ratio']
+    cad = features['cadence']
+    arm = features['avg_arm_swing']
+    asym = features['arm_asymmetry_index']
 
-    # Individual scores
     sv_score = score_stride_variability(sv)
     sym_score = score_symmetry(sym)
     cad_score = score_cadence(cad)
     arm_score = score_arm_swing(arm)
     asym_score = score_arm_asymmetry(asym)
 
-    # Weighted sum
     final_score = (
-        0.30 * sv_score
-        + 0.20 * sym_score
-        + 0.15 * cad_score
-        + 0.20 * arm_score
-        + 0.15 * asym_score
+        0.30 * sv_score +
+        0.20 * sym_score +
+        0.15 * cad_score +
+        0.20 * arm_score +
+        0.15 * asym_score
     )
 
     return round(final_score, 2)
@@ -648,109 +489,305 @@ def interpret_gait_score(score):
         return "🔴 Severe gait instability"
 
 
-def _safe_float_dict(d: Dict[str, Any]) -> Dict[str, float]:
-    safe: Dict[str, float] = {}
-    for key, value in d.items():
-        safe[key] = float(value)
-    return safe
+def plot_clinical_biomarkers(signals, features, l_peaks, r_peaks, fps, output_path):
+    """Generate clinical visualization dashboard and save to file"""
+    fig, axs = plt.subplots(3, 2, figsize=(16, 14))
+    fig.suptitle('NeuroTrack AI: Kinematic Gait Analysis', fontsize=20, fontweight='bold', color='#1f77b4')
+
+    time_axis = np.arange(len(signals['l_ankle_y'])) / fps
+
+    # 1. Ankle Vertical Displacement
+    axs[0, 0].plot(time_axis, signals['l_ankle_y'], label='Left Ankle', color='blue', alpha=0.7)
+    axs[0, 0].plot(time_axis, signals['r_ankle_y'], label='Right Ankle', color='orange', alpha=0.7)
+    axs[0, 0].set_title('Ankle Vertical Displacement')
+    axs[0, 0].invert_yaxis()
+    axs[0, 0].legend()
+
+    # 2. Peak Detection
+    if 'l_signal' in signals and 'r_signal' in signals:
+        axs[0, 1].plot(time_axis, signals['l_signal'], color='gray', alpha=0.6)
+
+        if len(l_peaks) > 0:
+            axs[0, 1].plot(time_axis[l_peaks], signals['l_signal'][l_peaks], "X",
+                           color='red', markersize=8, label='Left Steps')
 
+        if len(r_peaks) > 0:
+            axs[0, 1].plot(time_axis[r_peaks], signals['r_signal'][r_peaks], "X",
+                           color='green', markersize=8, label='Right Steps')
+
+        axs[0, 1].set_title('Step Detection (Foot X Signal)')
+        axs[0, 1].legend()
+    else:
+        axs[0, 1].set_title("Step Detection (No Data)")
+
+    # 3. Stride Times
+    l_stride_times = np.diff(l_peaks) / fps if len(l_peaks) > 1 else []
+    r_stride_times = np.diff(r_peaks) / fps if len(r_peaks) > 1 else []
 
-def run_pipeline(input_video: str, output_video: str, gender: str, plot_output: str) -> Tuple[Dict[str, float], str, float, str, float]:
-    print("1. Overlaying skeleton and extracting kinematics...")
-    signals, fps = extract_validate_and_visualize(input_video, output_video)
+    if len(l_stride_times) > 0:
+        axs[1, 0].plot(l_stride_times, marker='o', linestyle='-', color='blue', label='Left')
 
-    print("2. Computing clinical biomarkers...")
-    features, l_peaks, r_peaks = compute_gait_features(signals, fps)
+    if len(r_stride_times) > 0:
+        axs[1, 0].plot(r_stride_times, marker='o', linestyle='-', color='orange', label='Right')
 
-    clinical_report = interpret_clinical_features(features, gender)
-    score = compute_gait_stability_score(features)
-    interpretation = interpret_gait_score(score)
+    axs[1, 0].set_title(f"Stride Variability (CV: {features['stride_variability']:.2f}%)")
+    axs[1, 0].legend()
 
-    # Store inside features (BEST PRACTICE)
-    features["gait_score"] = score
-    features["gait_interpretation"] = interpretation
+    # 4. Arm Swing
+    axs[1, 1].plot(time_axis, signals['l_arm_swing'], label='Left Arm', color='purple', alpha=0.7)
+    axs[1, 1].plot(time_axis, signals['r_arm_swing'], label='Right Arm', color='brown', alpha=0.7)
+    axs[1, 1].set_title('Normalized Arm Swing')
+    axs[1, 1].legend()
 
-    print("\n🧠 GAIT STABILITY SCORE:", score)
-    print("📊 INTERPRETATION:", interpretation)
+    # 5. Arm Amplitude
+    axs[2, 0].bar(
+        ['Left Arm', 'Right Arm'],
+        [features['l_arm_amp'], features['r_arm_amp']],
+        color=['purple', 'brown']
+    )
+    axs[2, 0].set_title(f"Arm Asymmetry Index: {features['arm_asymmetry_index']:.1f}%")
+    axs[2, 0].set_ylabel('Amplitude')
 
-    print("\nGenerating Clinical Visualization Dashboard...")
-    plot_clinical_biomarkers(signals, features, l_peaks, r_peaks, fps, plot_output)
+    # 6. Postural Sway
+    axs[2, 1].plot(time_axis, signals['mid_hip_x'], color='teal')
+    axs[2, 1].set_title('Postural Sway (Hip X Movement)')
 
-    return _safe_float_dict(features), clinical_report, score, interpretation, float(fps)
+    plt.tight_layout(rect=[0, 0.03, 1, 0.95])
+    plt.savefig(output_path, dpi=100, bbox_inches='tight')
+    plt.close()
 
 
 @app.get("/")
-def root():
+async def root():
+    """Root endpoint with API information"""
     return {
         "message": "HEMAS NeuroTrack Gait Analysis API",
-        "swagger_ui": "/docs",
-        "analyze_endpoint": "/analyze",
+        "version": "1.0.0",
+        "endpoints": {
+            "analyze_gait": "/analyze",
+            "docs": "/docs",
+            "redoc": "/redoc"
+        }
     }
 
 
-@app.post(
-    "/analyze",
-    response_model=AnalyzeResponse,
-    responses={
-        400: {"description": "Invalid video input (no person/side view detected)."},
-        500: {"description": "Unexpected processing error."},
-    },
-)
-async def analyze_video(
-    video: Annotated[UploadFile, File(...)],
-    patient_gender: Annotated[Literal["male", "female"], Form("male")],
+@app.post("/analyze")
+async def analyze_gait(
+    video: UploadFile = File(..., description="Video file for gait analysis"),
+    gender: str = Form(..., description="Patient gender (male/female)")
 ):
-    run_id = str(uuid.uuid4())
-    suffix = Path(video.filename or "input.mp4").suffix or ".mp4"
-
-    input_path = INPUTS_DIR / f"{run_id}{suffix}"
-    output_video_path = OUTPUTS_DIR / f"annotated_{run_id}.mp4"
-    plot_path = PLOTS_DIR / f"plot_{run_id}.png"
-
+    """
+    Analyze gait from video file
+    
+    - **video**: Video file (mp4, mov, avi, etc.)
+    - **gender**: Patient gender (male or female) for clinical interpretation
+    
+    Returns:
+    - Annotated video with skeleton overlay
+    - Clinical biomarkers visualization
+    - Detailed clinical interpretation
+    - Gait stability score
+    """
+    
+    if gender.lower() not in ['male', 'female']:
+        raise HTTPException(status_code=400, detail="Gender must be 'male' or 'female'")
+    
+    # Create temporary file paths without keeping open handles (important on Windows)
+    input_fd, temp_input_path = tempfile.mkstemp(suffix='.mp4')
+    output_fd, temp_output_video_path = tempfile.mkstemp(suffix='.mp4')
+    plot_fd, temp_plot_path = tempfile.mkstemp(suffix='.png')
+    os.close(input_fd)
+    os.close(output_fd)
+    os.close(plot_fd)
+    
     try:
+        # Save uploaded video
         content = await video.read()
-        input_path.write_bytes(content)
-
-        features, clinical_report, score, interpretation, fps = run_pipeline(
-            input_video=str(input_path),
-            output_video=str(output_video_path),
-            gender=patient_gender,
-            plot_output=str(plot_path),
-        )
-
-        return AnalyzeResponse(
-            run_id=run_id,
-            fps=fps,
-            features=features,
-            clinical_report=clinical_report,
-            gait_score=score,
-            gait_interpretation=interpretation,
-            annotated_video_url=f"/runs/outputs/{output_video_path.name}",
-            plot_image_url=f"/runs/plots/{plot_path.name}",
-        )
-    except ValueError as exc:
-        raise HTTPException(status_code=400, detail=str(exc)) from exc
-    except Exception as exc:
-        raise HTTPException(status_code=500, detail=f"An unexpected error occurred: {exc}") from exc
-
-
-@app.get(
-    "/download/annotated/{filename}",
-    responses={404: {"description": "Annotated video not found."}},
-)
-def download_annotated_video(filename: str):
-    file_path = OUTPUTS_DIR / filename
+        with open(temp_input_path, 'wb') as f:
+            f.write(content)
+        
+        # Process video
+        print("1. Overlaying skeleton and extracting kinematics...")
+        signals, fps = extract_validate_and_visualize(temp_input_path, temp_output_video_path)
+        
+        print("2. Computing clinical biomarkers...")
+        features, l_peaks, r_peaks = compute_gait_features(signals, fps)
+        
+        # Generate clinical interpretation
+        clinical_interpretation = interpret_clinical_features(features, gender)
+        
+        # Compute gait stability score
+        score = compute_gait_stability_score(features)
+        interpretation = interpret_gait_score(score)
+        
+        features['gait_score'] = score
+        features['gait_interpretation'] = interpretation
+        
+        # Generate plots
+        print("3. Generating Clinical Visualization Dashboard...")
+        plot_clinical_biomarkers(signals, features, l_peaks, r_peaks, fps, temp_plot_path)
+        
+        # Convert files to base64
+        with open(temp_output_video_path, 'rb') as f:
+            annotated_video_b64 = base64.b64encode(f.read()).decode('utf-8')
+        
+        with open(temp_plot_path, 'rb') as f:
+            plot_b64 = base64.b64encode(f.read()).decode('utf-8')
+        
+        # Prepare response
+        response = {
+            "status": "success",
+            "clinical_interpretation": clinical_interpretation,
+            "gait_stability_score": score,
+            "gait_interpretation": interpretation,
+            "features": {
+                "stride_variability": float(features['stride_variability']),
+                "cadence": float(features['cadence']),
+                "symmetry_ratio": float(features['symmetry_ratio']),
+                "avg_arm_swing": float(features['avg_arm_swing']),
+                "l_arm_amp": float(features['l_arm_amp']),
+                "r_arm_amp": float(features['r_arm_amp']),
+                "arm_asymmetry_index": float(features['arm_asymmetry_index'])
+            },
+            "files": {
+                "annotated_video": f"data:video/mp4;base64,{annotated_video_b64}",
+                "clinical_dashboard": f"data:image/png;base64,{plot_b64}"
+            },
+            "metadata": {
+                "fps": float(fps),
+                "total_frames": len(signals['l_ankle_y']),
+                "duration_seconds": len(signals['l_ankle_y']) / fps,
+                "left_steps_detected": int(len(l_peaks)),
+                "right_steps_detected": int(len(r_peaks))
+            }
+        }
+        
+        return JSONResponse(content=response)
+        
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"An unexpected error occurred: {str(e)}")
+    finally:
+        # Cleanup
+        for temp_file in [temp_input_path, temp_output_video_path, temp_plot_path]:
+            if os.path.exists(temp_file):
+                try:
+                    os.unlink(temp_file)
+                except PermissionError:
+                    pass
+
+
+@app.post("/analyze_files")
+async def analyze_gait_files(
+    video: UploadFile = File(..., description="Video file for gait analysis"),
+    gender: str = Form(..., description="Patient gender (male/female)")
+):
+    """
+    Analyze gait from video file and return downloadable files
+    
+    - **video**: Video file (mp4, mov, avi, etc.)
+    - **gender**: Patient gender (male or female) for clinical interpretation
+    
+    Returns:
+    - JSON with URLs to download annotated video and clinical dashboard
+    """
+    
+    if gender.lower() not in ['male', 'female']:
+        raise HTTPException(status_code=400, detail="Gender must be 'male' or 'female'")
+    
+    # Create unique filenames
+    import uuid
+    session_id = str(uuid.uuid4())
+    
+    input_path = OUTPUT_DIR / f"{session_id}_input.mp4"
+    output_video_path = OUTPUT_DIR / f"{session_id}_annotated.mp4"
+    plot_path = OUTPUT_DIR / f"{session_id}_dashboard.png"
+    
+    try:
+        # Save uploaded video
+        content = await video.read()
+        with open(input_path, 'wb') as f:
+            f.write(content)
+        
+        # Process video
+        signals, fps = extract_validate_and_visualize(str(input_path), str(output_video_path))
+        features, l_peaks, r_peaks = compute_gait_features(signals, fps)
+        
+        # Generate clinical interpretation
+        clinical_interpretation = interpret_clinical_features(features, gender)
+        
+        # Compute gait stability score
+        score = compute_gait_stability_score(features)
+        interpretation = interpret_gait_score(score)
+        
+        features['gait_score'] = score
+        features['gait_interpretation'] = interpretation
+        
+        # Generate plots
+        plot_clinical_biomarkers(signals, features, l_peaks, r_peaks, fps, str(plot_path))
+        
+        # Prepare response
+        response = {
+            "status": "success",
+            "session_id": session_id,
+            "clinical_interpretation": clinical_interpretation,
+            "gait_stability_score": score,
+            "gait_interpretation": interpretation,
+            "features": {
+                "stride_variability": float(features['stride_variability']),
+                "cadence": float(features['cadence']),
+                "symmetry_ratio": float(features['symmetry_ratio']),
+                "avg_arm_swing": float(features['avg_arm_swing']),
+                "l_arm_amp": float(features['l_arm_amp']),
+                "r_arm_amp": float(features['r_arm_amp']),
+                "arm_asymmetry_index": float(features['arm_asymmetry_index'])
+            },
+            "download_urls": {
+                "annotated_video": f"/download/{session_id}_annotated.mp4",
+                "clinical_dashboard": f"/download/{session_id}_dashboard.png"
+            },
+            "metadata": {
+                "fps": float(fps),
+                "total_frames": len(signals['l_ankle_y']),
+                "duration_seconds": len(signals['l_ankle_y']) / fps,
+                "left_steps_detected": int(len(l_peaks)),
+                "right_steps_detected": int(len(r_peaks))
+            }
+        }
+        
+        # Clean up input file
+        os.unlink(input_path)
+        
+        return JSONResponse(content=response)
+        
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"An unexpected error occurred: {str(e)}")
+
+
+@app.get("/download/{filename}")
+async def download_file(filename: str):
+    """Download generated files"""
+    file_path = OUTPUT_DIR / filename
+    
     if not file_path.exists():
-        raise HTTPException(status_code=404, detail="Annotated video not found")
-    return FileResponse(path=file_path, media_type="video/mp4", filename=filename)
+        raise HTTPException(status_code=404, detail="File not found")
+    
+    return FileResponse(
+        path=file_path,
+        filename=filename,
+        media_type='application/octet-stream'
+    )
 
 
-@app.get(
-    "/download/plot/{filename}",
-    responses={404: {"description": "Plot image not found."}},
-)
-def download_plot(filename: str):
-    file_path = PLOTS_DIR / filename
-    if not file_path.exists():
-        raise HTTPException(status_code=404, detail="Plot image not found")
-    return FileResponse(path=file_path, media_type="image/png", filename=filename)
+@app.get("/health")
+async def health_check():
+    """Health check endpoint"""
+    return {"status": "healthy", "service": "HEMAS NeuroTrack API"}
+
+
+if __name__ == "__main__":
+    import uvicorn
+    uvicorn.run(app, host="0.0.0.0", port=8000)

scripts/cleanup_runs.py

@@ -0,0 +1,102 @@
+#!/usr/bin/env python3
+"""Cleanup utility for GAIT_API generated files.
+
+This script removes files under the runs directory that are older than a
+configurable age (default: 30 minutes). It is designed to be triggered by cron.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import time
+from pathlib import Path
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Cleanup old files from runs directory")
+    parser.add_argument(
+        "--path",
+        default="/app/runs",
+        help="Runs directory path (default: /app/runs)",
+    )
+    parser.add_argument(
+        "--max-age-minutes",
+        type=float,
+        default=30,
+        help="Delete files older than this many minutes (default: 30)",
+    )
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Only print what would be deleted",
+    )
+    return parser.parse_args()
+
+
+def cleanup_runs(root: Path, max_age_minutes: float, dry_run: bool = False) -> tuple[int, int]:
+    if not root.exists():
+        return 0, 0
+
+    now = time.time()
+    cutoff = now - (max_age_minutes * 60)
+
+    deleted_files = 0
+    deleted_dirs = 0
+
+    # Delete eligible files first
+    for file_path in root.rglob("*"):
+        if not file_path.is_file():
+            continue
+
+        try:
+            mtime = file_path.stat().st_mtime
+            if mtime <= cutoff:
+                if dry_run:
+                    print(f"[DRY-RUN] file: {file_path}")
+                else:
+                    file_path.unlink(missing_ok=True)
+                deleted_files += 1
+        except FileNotFoundError:
+            # Might have been removed by another process
+            continue
+        except PermissionError:
+            print(f"[WARN] Permission denied: {file_path}")
+
+    # Remove empty directories bottom-up (excluding root)
+    for dir_path in sorted((p for p in root.rglob("*") if p.is_dir()), key=lambda p: len(p.parts), reverse=True):
+        try:
+            if any(dir_path.iterdir()):
+                continue
+            if dry_run:
+                print(f"[DRY-RUN] dir:  {dir_path}")
+            else:
+                dir_path.rmdir()
+            deleted_dirs += 1
+        except (FileNotFoundError, PermissionError, OSError):
+            # OSError when directory isn't empty anymore
+            continue
+
+    return deleted_files, deleted_dirs
+
+
+def main() -> int:
+    args = parse_args()
+    root = Path(args.path)
+
+    deleted_files, deleted_dirs = cleanup_runs(
+        root=root,
+        max_age_minutes=args.max_age_minutes,
+        dry_run=args.dry_run,
+    )
+
+    print(
+        f"Cleanup complete for {root} | "
+        f"deleted_files={deleted_files} | deleted_dirs={deleted_dirs} | "
+        f"max_age_minutes={args.max_age_minutes}"
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

scripts/start.sh

@@ -0,0 +1,21 @@
+#!/usr/bin/env sh
+set -eu
+
+PORT="${PORT:-7860}"
+CLEANUP_INTERVAL_SECONDS="${CLEANUP_INTERVAL_SECONDS:-1800}"
+RUNS_MAX_AGE_MINUTES="${RUNS_MAX_AGE_MINUTES:-30}"
+
+mkdir -p /app/runs/outputs
+
+cleanup_loop() {
+  while true; do
+    python /app/scripts/cleanup_runs.py \
+      --path /app/runs \
+      --max-age-minutes "${RUNS_MAX_AGE_MINUTES}" || true
+    sleep "${CLEANUP_INTERVAL_SECONDS}"
+  done
+}
+
+cleanup_loop &
+
+exec uvicorn app:app --host 0.0.0.0 --port "${PORT}"