# Module: ai_config

## Purpose

Data class holding all AI recognition configuration parameters, with factory method for deserialization from dict format.

## Public Interface

### Class: AIRecognitionConfig

#### Fields

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `frame_period_recognition` | int | 4 | Process every Nth frame in video |
| `frame_recognition_seconds` | double | 2.0 | Minimum seconds between valid video annotations |
| `probability_threshold` | double | 0.25 | Minimum detection confidence |
| `tracking_distance_confidence` | double | 0.0 | Distance threshold for tracking (model-width units) |
| `tracking_probability_increase` | double | 0.0 | Required confidence increase for tracking update |
| `tracking_intersection_threshold` | double | 0.6 | IoU threshold for overlapping detection removal |
| `model_batch_size` | int | 1 | Batch size for inference |
| `big_image_tile_overlap_percent` | int | 20 | Tile overlap percentage for large image splitting |
| `altitude` | double | 400 | Camera altitude in meters |
| `focal_length` | double | 24 | Camera focal length in mm |
| `sensor_width` | double | 23.5 | Camera sensor width in mm |

#### Methods

| Method | Signature | Description |
|--------|-----------|-------------|
| `from_dict` | `(dict data) -> AIRecognitionConfig` | Static cdef; deserializes from Python dict |

## Internal Logic

`from_dict` applies defaults for missing keys using full descriptive key names.

**Removed**: `paths` field and `file_data` field were removed as part of the distributed architecture shift (AZ-174). Media paths are now resolved via the Annotations service API, not passed in config. `from_msgpack()` was also removed as it was unused.

## Dependencies

- **External**: none
- **Internal**: none (leaf module)

## Consumers

- `inference` — creates config from dict, uses all fields for frame selection, detection filtering, image tiling, and tracking

## Data Models

- `AIRecognitionConfig` — the sole data class

## Configuration

Camera/altitude parameters (`altitude`, `focal_length`, `sensor_width`) are used for ground sampling distance calculation in aerial image processing.

## External Integrations

None.

## Security

None.

## Tests

- `tests/test_ai_config_from_dict.py` — tests `ai_config_from_dict()` helper with defaults and overrides