setup typechecking and fix build errors

DETECTION_IMPROVEMENT_PLAN.md

@@ -0,0 +1,44 @@
+# Card Object Detection Reliability Improvement Plan
+
+This document outlines the strategy to improve the reliability of the card detection pipeline, moving from a heuristic-based approach to a robust computer vision pipeline.
+
+## Current Limitations
+- **Localization**: Relies on brightness thresholds, which are highly sensitive to lighting conditions and shadows.
+- **Geometry**: Crops raw bounding boxes without correcting for perspective (table angle), forcing the ML models to handle distortion.
+- **Stability**: Live detection is susceptible to frame-by-frame jitter (flickering).
+
+## Proposed Improvements
+
+### 1. Robust Localization (The "Where" Problem)
+Transition from brightness-based search to shape and edge detection:
+- **Edge-based Detection**: Implement **Canny Edge Detection** and **Contour Approximation** to identify rectangular shapes regardless of absolute brightness.
+- **Color Space Shift**: Move from RGB to **HSV (Hue, Saturation, Value)** or **LAB** color spaces to decouple lighting (Value/Lightness) from color information.
+- **End-to-End Detection (Long-term)**: Evaluate lightweight object detection models (e.g., **YOLOv8-nano** or **SSD MobileNet**) to replace manual region finding.
+
+### 2. Perspective Correction (The "Geometry" Problem)
+Eliminate image skew to provide standardized input to classifiers:
+- **Four-Point Transform (Warping)**: Identify the four corners of the detected card contour and apply a **Perspective Transform (Homography)** to "flatten" the card into a normalized top-down rectangle.
+- **Standardized Input**: Ensure the ML models always receive a centered, non-distorted crop, reducing the reliance on massive geometric data augmentation.
+
+### 3. Enhanced Classification (The "What" Problem)
+Improve the precision of identity recognition:
+- **Unified Multi-Head Model**: Combine Suit and Value models into a single network with two output heads to reduce latency and exploit shared features.
+- **Advanced Data Augmentation**: Expand the training set with:
+    - **Motion Blur**: Simulating handheld camera movement.
+    - **Perspective Distortions**: To handle imperfect warping.
+    - **Lighting Variations**: Simulating varied environmental lighting.
+- **Confidence Calibration**: Implement a minimum confidence threshold to avoid false positives in noisy environments.
+
+### 4. Temporal Stability (The "Flicker" Problem)
+Prevent identity jumping in live mode:
+- **Object Tracking**: Implement a **Centroid Tracker** or **Kalman Filter** to maintain card identity across frames instead of detecting from scratch every time.
+- **Temporal Smoothing**: Use a "Voting" mechanism where a card's identity is only confirmed if the model is consistent over a sliding window of 5-10 frames.
+
+## Implementation Roadmap
+
+| Phase | Focus | Key Change | Expected Impact |
+| :--- | :--- | :--- | :--- |
+| **Phase 1** | **Stability** | Edge detection + Temporal smoothing | Reduced flickering and lighting sensitivity. |
+| **Phase 2** | **Geometry** | Perspective Warping (Flattening) | Significant boost in classification accuracy. |
+| **Phase 3** | **Intelligence** | Unified Model + Expanded Dataset | Higher precision and lower inference latency. |
+| **Phase 4** | **Architecture** | Full Object Detection Model (YOLO) | Industry-standard reliability and speed. |