(Untested) Enhance entity handling and statistics in AI analysis

[GodPuffin]

• Introduced new Entity and EntityType definitions for standardized entity detection in video analysis.
• Updated existing interfaces to utilize the new Entity type for improved type safety.
• Added functions to retrieve entity statistics from analysis results and events, enabling better insights into detected entities.
• Created a new SQL migration to define the entity type enum in the database for consistency across the application.

This commit significantly improves the structure and functionality of entity management within the AI analysis framework.

[claude]

Pull Request Review: Entity Handling Enhancement

Thank you for this PR! This is a well-structured enhancement that brings proper type safety to entity handling.

Strengths

1. Excellent Type Safety Improvements - Introduction of EntityType enum and Entity interface significantly improves type safety across all layers
2. Good Database Design - SQL migration properly defines the entity type enum with helpful documentation
3. Improved API - New statistics functions provide valuable analytics capabilities with clean function signatures
4. Code Quality - Proper error handling, good JSDoc comments, and consistent formatting

Issues and Concerns

1. Performance Issue: N+1 Query Pattern (High Priority)
Location: lib/ai-analysis-queries.ts:395-416, 472-493

The getEntityStatistics() and getEntityStatisticsFromEvents() functions fetch ALL rows and process them in-memory. This doesn't scale - with thousands of analysis results, you'll transfer massive amounts of data, consume excessive memory, and experience slow response times.

Recommendation: Use PostgreSQL JSONB aggregation or Supabase RPC functions for complex queries instead of fetching all data client-side.

2. Performance Issue: Multiple Database Queries (Medium Priority)
Location: lib/ai-analysis-queries.ts:421-467

getEntityStatisticsForAsset() makes two sequential queries. Use a JOIN to combine into a single query for better performance.

3. Type Safety Gap: JSONB Casting (Medium Priority)

The code uses type assertions without runtime validation. If data in the database doesn't match the Entity interface, this will fail silently or at runtime. Add runtime validation using Zod for JSONB data.

4. Missing Error Context (Low Priority)

Error handling just rethrows without context. Add context to errors for better debugging.

5. Database-TypeScript Type Mismatch Risk (Low Priority)

The enum is defined in SQL but must be manually kept in sync with TypeScript types across multiple files. Add tests to validate type sync or use code generation.

Security

No major security issues identified. JSONB fields are properly handled, no SQL injection risks, and no sensitive data exposure.

Test Coverage (High Priority)

The PR title says Untested which is concerning for production code. No test files found in the repository. Entity statistics functions handle data aggregation logic that should be tested.

Recommendations:

• Add unit tests for the new statistics functions
• Test edge cases: empty results, missing entity fields, invalid data types
• Add integration tests for the database enum
• Test the Zod schema validation in gemini-client.ts

Additional Recommendations

1. Add Data Migration Script - The new enum constrains entity types, but existing data might have non-conforming values
2. Consider Adding Indexes - GIN indexes on JSONB fields for better query performance
3. Documentation - Add examples of the new functions and document the entity type hierarchy
4. Type Export Organization - EntityType and Entity are duplicated across 3 files, consider creating a shared types file

Summary

Overall Assessment: Good foundation with important improvements needed before merge

Must Fix (Blocking):

• Performance: Refactor statistics functions to use database aggregation
• Testing: Add tests for the new functionality

Should Fix (Recommended):

• Add runtime validation for JSONB entity data
• Optimize multi-query patterns with JOINs
• Add proper error context
• Add database indexes for JSONB queries

Nice to Have:

• Consolidate duplicate type definitions
• Add data migration for existing records
• Improve documentation

Great work on improving type safety! Once the performance and testing concerns are addressed, this will be a solid enhancement to the codebase.