feat(localization): Enhance smart event handling and UI interactions

- Added `Confidence` column to the localization table for smart events.
- Implemented double-click functionality on confidence cells to confirm/reject annotations.
- Introduced signals for confirming and rejecting annotations in the `_TableAdapter`.
- Updated the `_SpottingTabsAdapter` to include a "Smart Inference" button.
- Modified event handling to ensure persistence of confidence scores and proper UI updates.
- Removed legacy smart keys from dataset normalization.
- Enhanced tests to cover new smart inference workflows and ensure correct behavior of confidence handling.

Author: SilvioGiancola

AGENTS.md

@@ -1,162 +1,91 @@
-# AGENTS Guide
+# AGENTS Guide (Compact)
 
 ## Purpose
-This file is the working contract for agents and contributors modifying this repository.
-It summarizes the current architecture and the business decisions that must stay stable unless explicitly changed.
+Working contract for contributors/agents. Preserve decisions here unless explicitly changed.
 
 ## Product Scope
-The product is a PyQt6 desktop annotation workspace for OSL-format sports video datasets.
-It supports the full edit loop for dataset curation:
-- Create/open/close/save/export dataset JSON projects.
-- Add/remove samples and manage dataset-level schema (`labels`) and metadata.
-- Annotate videos in four task modalities:
-  - Classification: sample-level single-label and multi-label heads.
-  - Localization (action spotting): timestamped event annotations.
-  - Description: sample-level captions / structured text.
-  - Dense Description: event-level timestamped textual descriptions.
-- Review and edit annotations through synchronized tree selection, timeline markers, tables, and media playback controls.
-- Maintain annotation quality and safety with undo/redo history and filtering.
-
-From the docs perspective, the data model target is the OSL JSON structure:
-- Top-level dataset metadata + taxonomy (`labels`) + item list (`data`).
-- Per-sample multimodal `inputs` and task-specific keys such as `labels`, `events`, `captions`, `dense_captions`.
-
-## Architecture Snapshot
-High-level layering:
-- UI layer (`annotation_tool/ui/...`):
-  - Loads `.ui` forms, owns widget composition, and emits user-intent signals.
-  - Contains view adapters (table models, button adapters, etc.) but not dataset mutation policy.
-- Controller layer (`annotation_tool/controllers/...`):
-  - Implements business behavior and state transitions.
-  - Converts UI intents to mutation requests and refresh events.
-- Composition layer (`annotation_tool/main_window.py`):
-  - Instantiates panels/controllers and wires all cross-module signal-slot connections.
-  - Acts as the only composition root.
-
-Core runtime ownership:
-- `DatasetExplorerController`:
-  - Canonical in-memory dataset document (`dataset_json`) owner.
-  - Handles project lifecycle, tree/index/filter/selection, and emits selection/media intents.
-- `HistoryManager`:
-  - Canonical mutation engine for tracked operations.
-  - Owns undo/redo replay and emits refresh intents after state changes.
-- `MediaController`:
-  - Canonical playback source/state owner.
-  - Owns route/load/play/pause/seek/stop/mute decisions.
-- Mode controllers:
-  - `ClassificationEditorController`
-  - `LocalizationEditorController`
-  - `DescEditorController`
-  - `DenseEditorController`
-  - Own mode-local UI state and emit typed mutation requests to history.
-
-Signal flow (default):
-1. UI widget emits intent to its owning controller.
-2. Controller emits typed request signal (mutation/media/status/etc.).
-3. `MainWindow.connect_signals()` routes that signal to the owning target controller.
-4. Owning controller updates state and emits refresh/context signals.
-5. Dependent controllers/panels refresh from those signals.
-
-## Hard Boundaries (Do Not Break)
-High-level module coupling rules:
-- Controllers do not own each other directly through constructor injection (scoped architecture).
-- No controller should accept/store `main_window`.
-- Cross-module coordination must happen through explicit Qt signal-slot wiring in `MainWindow.connect_signals()`.
-- No centralized event bus abstraction.
-- No `DatasetModelFacade`-style abstraction layer.
-- No legacy aliases such as `window.model` / `window.router`; use `window.dataset_explorer_controller`.
-- Mode controllers should only have their panel as constructor arguments.
-
-UI vs Controller split:
-- UI modules:
-  - Presentation only (layout, widgets, local rendering helpers, intent signals).
-  - Must not implement dataset lifecycle or persistence policy.
-- Controllers:
-  - Business rules, state transition orchestration, validation/no-op guards.
-  - Emit/consume typed signals; avoid direct widget-to-widget coupling across modules.
-
-Media boundary:
-- Explorer and editor controllers must not import/use `QMediaPlayer`.
-- `MediaController` is the only owner of playback source/state/mute logic.
-- Other modules request media actions by signals only.
-
-Mutation boundary:
-- `HistoryManager` is the mutation + undo/redo authority for tracked dataset edits.
-- Do not duplicate mutation implementations across explorer/editors/history.
-
-## Data Ownership and Mutation Rules
-- `dataset_json` in `DatasetExplorerController` is the canonical in-memory document.
-- All tracked dataset mutations should flow through `HistoryManager.execute_*` slots.
-- History contract:
-  - Effective JSON mutation => exactly one undo entry.
-  - No-op mutation => zero undo entries.
-  - Forward mutation clears redo.
+PyQt6 desktop annotation tool for OSL sports-video datasets.
+
+Must support:
+- Project lifecycle: create/open/close/save/export JSON.
+- Dataset curation: samples, metadata, schema (`labels`).
+- Modes: Classification, Localization, Description, Dense Description.
+- Editing/review UX: tree + timeline + table + media controls + filter + undo/redo.
+
+Data model target:
+- Root: metadata + `labels` + `data`.
+- Sample: `inputs` and task keys like `labels`, `events`, `captions`, `dense_captions`.
+
+## Architecture
+Layers:
+- UI (`annotation_tool/ui/...`): presentation + intent signals.
+- Controllers (`annotation_tool/controllers/...`): behavior/state orchestration.
+- Composition (`annotation_tool/main_window.py`): only place for cross-module wiring.
+
+Runtime owners:
+- `DatasetExplorerController`: canonical in-memory `dataset_json`, lifecycle, tree/filter/selection.
+- `HistoryManager`: tracked mutations + undo/redo authority.
+- `MediaController`: playback route/state/mute authority.
+- Mode controllers (`Classification`, `Localization`, `Description`, `Dense`): mode-local behavior; emit mutation/media intents.
+
+Default signal flow:
+1. UI emits intent.
+2. Controller emits typed request signal.
+3. `MainWindow.connect_signals()` routes to owner.
+4. Owner mutates state and emits refresh/context.
+
+## Hard Boundaries
+- No controller may store/accept `main_window`.
+- No direct controller-to-controller constructor coupling in scoped modules.
+- No event bus.
+- No `DatasetModelFacade`.
+- No legacy aliases (`window.model`, `window.router`); use `window.dataset_explorer_controller`.
+- Mode controllers should only receive their panel.
+- Explorer/editor controllers must not use `QMediaPlayer` directly.
+- Do not duplicate tracked mutation logic outside `HistoryManager`.
+
+## Data and History Contracts
+- Canonical document: `DatasetExplorerController.dataset_json`.
+- Tracked edits flow through `HistoryManager.execute_*`.
+- Effective mutation => exactly 1 undo entry.
+- No-op mutation => 0 undo entries.
+- Forward mutation clears redo.
 - Undo/redo must restore structural JSON equality.
 
-## Selection, Refresh, and Playback Contracts
-- Tab switch must not repopulate the dataset tree.
-- Tab switch with unchanged selection/path must not restart media.
-- Undo/redo should avoid full tree rebuild when lightweight refresh is sufficient.
-- Filter edge case: if selected row becomes hidden, clear selection (do not force-select first visible).
-- Selection-triggered routing should still ensure playback when user explicitly selects a sample/input and player is not already playing it.
-
-## Current UX Decisions to Preserve
-- No single-view vs multi-view project creation prompt.
-- No `is_multi_view` workflow branch for new project behavior.
-- Description controller consumes selected `sample` payload and emits caption-only updates.
-- Classification manual annotation saves immediately on effective value change.
-- Dense add flow is explicit modal add (`Add New Description`), while edits are table-driven.
-- Media mute control is icon-based and placed at the right side of the timeline row.
-
-## Module Responsibilities
-### DatasetExplorerController
-- Own: dataset lifecycle (create/open/save/close), tree/filter/selection, selection context emission, media routing intent emission.
-- Do not own: per-mode annotation mutation policy.
-
-### HistoryManager
-- Own: forward mutation execution + undo/redo replay for tracked operations.
-- Emit refresh intents; do not take over UI composition concerns.
-
-### MediaController
-- Own: source routing, play/pause/seek/stop/mute logic and state signals.
-- Keep playback guard logic centralized here.
-
-### Mode Controllers
-- Own: mode UI behavior and local mode state.
-- Emit typed mutation intents; avoid direct dataset mutation duplication.
-
-## Refactoring Principles
-- Prefer deleting legacy compatibility paths instead of adding shims.
-- Prefer one canonical implementation per business operation.
-- Prefer simple, explicit logic over clever or heavily abstracted implementations.
-- Keep constructors minimal and explicit.
-- If logic duplicates across controllers, centralize it in the owner module (usually `HistoryManager` for mutations, `MediaController` for playback).
-- Remove functions that are no longer used after refactors.
-- Eliminate redundant logic and redundant helper functions; keep only the canonical path.
-- Keep files smaller by extracting coherent helpers, not by adding extra orchestration layers.
-
-## Testing and Change Discipline
-When changing architecture or mutation/playback behavior, update and run relevant suites:
-- `tests/gui/test_signal_decoupling_contract.py`
-- `tests/gui/test_history_stack_contract.py`
-- `tests/gui/test_dataset_explorer_regressions.py`
-- `tests/gui/test_core_lifecycle.py`
-- `tests/gui/test_workflow_classification.py`
-- `tests/gui/test_workflow_localization.py`
-- `tests/gui/test_workflow_description.py`
-- `tests/gui/test_workflow_dense_description.py`
-- `tests/gui/test_media_player_controls.py`
-
-Always run the relevant tests after changes to check for regressions before considering work complete.
+## Selection/Refresh/Playback Contracts
+- Tab switch must not repopulate tree.
+- Tab switch with same selection/path must not restart media.
+- Undo/redo should prefer lightweight refresh over full rebuild when possible.
+- If filter hides selected row: clear selection (do not auto-select first visible).
+- Explicit user sample/input selection should ensure playback when needed.
+
+## UX Decisions to Preserve
+- No single-view vs multi-view creation prompt.
+- No `is_multi_view` new-project branch.
+- Description controller consumes selected `sample` and emits caption-only updates.
+- Classification manual edits save immediately on effective change.
+- Dense add remains explicit modal (`Add New Description`), edits table-driven.
+- Mute control: icon button on right side of timeline row.
+
+## Refactoring Rules
+- Prefer simple, explicit logic.
+- Keep one canonical implementation per operation.
+- Delete legacy paths instead of adding shims.
+- Keep constructors minimal/explicit.
+- Remove unused functions after refactors.
+- Remove redundant logic/helpers.
+
+## Testing Discipline
+For architecture, mutation, playback, or workflow changes, update/run relevant suites in the folder `tests/gui`. Always run relevant tests before considering work complete.
 
 ## PR/Agent Checklist
-1. Did you keep controller boundaries (no `main_window`, no direct controller-to-controller constructor dependency in scoped modules)?
-2. Did you preserve the 1-or-0 history push rule for mutations?
-3. Did you avoid unnecessary tree repopulate/media restart side effects?
-4. Did you wire new behavior through explicit signals in `MainWindow.connect_signals()`?
-5. Did you avoid reintroducing legacy aliases/facades?
-6. Did you keep the implementation simple and avoid unnecessary complexity?
-7. Did you remove functions that are no longer used?
-8. Did you remove redundant logic/functions and keep one canonical implementation?
-9. Did you update module README(s) if public behavior/contracts changed?
-10. Did you add or update regression tests for new behavior, and run relevant test suites to verify no regressions?
+1. Controller boundaries preserved?
+2. History 1-or-0 push rule preserved?
+3. No unnecessary tree/media regressions?
+4. New behavior wired through `MainWindow.connect_signals()`?
+5. No legacy aliases/facades reintroduced?
+6. Logic kept simple?
+7. Unused functions removed?
+8. Redundant logic removed and canonical path retained?
+9. README/docs updated if public contract changed?
+10. Relevant regression tests added/updated and run?

annotation_tool/README.md

@@ -41,7 +41,8 @@ The canonical persisted in-memory state is a single `dataset_json` owned by `Dat
 - Project root object (`dataset_json`) includes (non-exhaustive):
   - `version`, `date`, `dataset_name`, `description`, `metadata`, `labels`, `data`
 - Sample object (`dataset_json["data"][i]`) typically includes:
-  - `id`, `inputs`, `labels`, `smart_labels`, `events`, `smart_events`, `captions`, `dense_captions`
+  - `id`, `inputs`, `labels`, `events`, `captions`, `dense_captions`
+  - Classification smart prediction marker: `labels[head].confidence_score` (optional float)
 - Input item: `{ "type": "video", "path": "..." }`
 - Localization event: `{ "head": str, "label": str, "position_ms": int }`
 - Dense event: `{ "position_ms": int, "lang": str, "text": str }`

annotation_tool/controllers/classification/README.md

@@ -33,21 +33,27 @@ Implements Classification mode behavior and coordinates smart inference/train he
 ## Key Functions and Responsibilities
 - `setup_connections()`
   - Connects classification panel UI actions to controller actions.
-- `on_selected_sample_changed(sample, resolved_path="")`
+- `on_selected_sample_changed(sample)`
   - Refreshes manual/smart display for selected sample snapshot.
 - `on_schema_context_changed(schema)`
   - Rebuilds dynamic schema-driven controls from runtime schema context.
 - `save_manual_annotation(override_data=None, show_feedback=True)`
   - Normalizes annotation payload and emits tracked save intent.
 - `confirm_smart_annotation_as_manual()`
   - Delegates smart confirmation flow to `InferenceManager`.
+- `reject_smart_annotation_head(head)`
+  - Rejects inferred smart annotation for one head and restores pre-inference manual state.
 - `clear_current_manual_annotation()` / `clear_current_smart_annotation()`
   - Clears manual/smart state with proper history behavior.
 
 ## Business Rules
 - Manual tab changes save immediately when effective value differs.
 - No-op saves (same normalized annotation) do nothing.
 - Schema operations enforce duplicate checks.
+- Smart inference is persisted in `labels[head]` with `confidence_score`.
+- Confirming smart annotation removes `confidence_score` only.
+- Rejecting/clearing smart annotation restores pre-inference manual state (or removes head if none existed).
+- Smart inference is triggered per head from the manual panel (no Smart tab flow).
 
 ## Conventions
 - UI stays in panel classes; controller performs behavior orchestration.