docs/lock-mode.md

# Lock Mode Specification & Filtering Engine

## Overview
**Lock Mode** restricts visual detection output so that **ONLY** objects matching a target string are rendered or returned.

```
All Pipeline Detections ──► Target Matcher ──► Match? ──YES──► Render Box & Tag
                                                 │
                                                 └──NO───► Suppress (No Box Rendered)
```

## Architectural Contract
- **Suppression Before Rendering**: Filtering occurs in the backend/orchestrator before returning bounding boxes to the client or drawing on frames.
- **Persistent Lock Target**: The lock target remains active across incoming webcam / stream frames until explicitly unlocked.
- **Header Indicator Banner**: Annotated frames display a prominent lock status banner: `🔒 LOCK MODE ACTIVE | Target: '<target>'`.

## Supported Target Types
1. **Generic Category Target**: `cup`, `laptop`, `person`
2. **Open-Vocabulary Prompt**: `red backpack`, `wireless mouse`
3. **Specific Taught Identity**: `My Cup`, `Lab Keys`

## SDK Example

```python
from object_intelligence import ObjectDetector

detector = ObjectDetector()
detector.lock("My Cup")

# Only 'My Cup' bounding boxes will be returned/drawn
annotated_frame, detections = detector.detect_and_draw(frame)

# To unlock
detector.unlock()
```