CueIQ Break And Pattern Intelligence Feature Plan

Status: planning backlog

Primary roadmap placement: Phase 3 feature family, with Phase 2 research gates only

Last updated: 2026-06-14

Strategic Intent

Break and pattern intelligence should extend CueIQ from a verified stroke-technique library into a broader pool intelligence product. The goal is not to add a novelty AI feature. The goal is to help players and coaches compare breaks, layouts, and runout choices against reviewed professional examples by discipline.

This feature family must stay behind the core SaaS quality gate. CueIQ should first prove the live product foundation: authenticated dashboard, real API data, subscription entitlement correctness, Stripe webhook reliability, reviewed pro examples, and coach beta feedback. Break and pattern intelligence becomes powerful only if the underlying product already feels trustworthy.

Product Positioning

The product promise:

• Compare a player's break or pattern choice against verified pro examples.
• Study how different pros break and run racks in 8-ball, 9-ball, and 10-ball.
• Build coach and academy training libraries around real, reviewed layouts and routes.

The long-term moat is a reviewed database of pro breaks, table layouts, runout routes, and coach-validated pattern decisions. The moat is not the generic video model.

Roadmap Alignment

Phase 2 - Production Foundation and Private Coach Beta:

• Keep the main focus on SaaS trust, entitlement correctness, live API data, billing, and the first verified pro library.
• Allow only planning, schema sketches, evaluation criteria, and optional manual break tagging if it directly supports coach beta learning.
• Do not launch Break Lab or Pattern Library as public product surfaces during Phase 2.

Phase 3 - Production Workspace and Paid Libraries:

• Build the first Break Intelligence MVP after the dashboard is a reliable paid workspace.
• Add Break Lab as a Coach+ or Academy-facing library surface.
• Add manual and AI-assisted break review workflows before automated CV claims.

Phase 4 - Crowdsourcing, Coaching Uploads, and Dataset Flywheel:

• Add coach/player-uploaded breaks and pattern clips.
• Compare private clips against verified pro references.
• Preserve consent, rights, retention, and training eligibility boundaries.

Phase 5 - Training Loop and Model Evaluation:

• Train or fine-tune billiards-specific ball detectors only after enough reviewed layout frames exist.
• Add formal CV evaluation harnesses for ball detection, table calibration, classification, and tracking.

Phase 6+ - Proprietary CueIQ Model:

• Use the reviewed break/layout/pattern dataset as part of a CueIQ-owned billiards vision model after the cost, data, and evaluation gates are met.

Quality Gate Before Feature Work

Do not begin broad implementation until the core SaaS has met these conditions:

• Cloudflare dashboard reads live API data instead of demo fallback data.
• Supabase Auth sign-in and token flow work on staging.
• Render/FastAPI health and core dashboard endpoints are reliable.
• Stripe webhook endpoint is registered and verified in test mode.
• Subscription entitlements are enforced server-side.
• At least 100 reviewed or golden pro technique examples exist.
• Coach beta feedback confirms that verified libraries are valuable enough to pay for.
• Rights posture remains intact: public YouTube evidence is not rehosted behind a paywall.
• Dashboard scope is controlled; larger workspace expansion waits for the planned frontend migration.

Architecture Decision

Use a hybrid intelligence pipeline:

• Video AI for scene understanding, broad labels, and pattern explanation.
• Computer vision for table, ball, and layout perception.
• Rules engine for 8-ball, 9-ball, and 10-ball legality and route constraints.
• Human review for trusted data, golden examples, and correction loops.

Do not ask one multimodal model to solve perception, rules, and coaching judgment by itself.

Hard Technical Constraints

Broadcast pool footage is difficult:

• Cameras cut, zoom, pan, and change perspective.
• Full-table visibility is inconsistent.
• Pool balls are small, glossy, partially occluded, and motion-blurred.
• Ball colors shift under table lighting and video compression.
• Exact numbered-ball detection is much harder than group-level detection.
• Runout conversion metrics are biased unless the sample contains complete break opportunities, not just clean clips.

Table calibration is the hardest unsolved engineering problem. Fixed overhead footage can use stable homography. Broadcast footage requires shot-boundary detection, table visibility scoring, and per-segment recalibration.

Candidate CV Approach

Early candidates to evaluate:

• Ball detection: YOLO-family object detectors or comparable lightweight detectors.
• Multi-object tracking: ByteTrack, DeepSORT, or equivalent tracker.
• Table calibration: table-edge/pocket detection plus homography when camera geometry is stable.
• Shot-boundary detection: detect broadcast cuts and reset calibration per segment.
• Classification: cue ball, 8-ball, solid, stripe, unknown; exact numbered-ball detection remains human-review-first until proven.

CV Evaluation Criteria

Define trust thresholds before using CV output as product data:

• Cue ball detection: target 90%+ precision before automated use.
• Object ball detection: target 85%+ precision before review-queue prefill.
• 8-ball classification: target 85%+ precision before assisted 8-ball layout tagging.
• Solids/stripes classification: target 85%+ precision before assisted pattern tagging.
• Exact numbered-ball classification: human-review-only until the model proves reliability by discipline.
• Pocketed-ball inference: human-review-only until tracking across full shot sequences is reliable.
• Cue-ball final-zone tagging: assisted only until table calibration is stable.

Every CV-produced layout should carry confidence, visibility, and review status. Low-confidence layouts should fall back to human review rather than product-facing claims.

Break Intelligence MVP

Start with break intelligence because breaks are short, bounded, easy to validate, and valuable to coaches.

Initial data to track:

• Discipline: 8-ball, 9-ball, or 10-ball.
• Player, event, source video, timestamp window, and source rights.
• Break side: left, center, or right.
• Cue-ball start position and final zone.
• First-ball contact when visible.
• Balls made.
• Dry break.
• Scratch or foul.
• Legal break.
• Open shot after break.
• Runout after break, only when the sample is complete enough.
• Safety after break.
• Spread score.
• Cluster score.
• Cue-ball control grade.
• Break style: power, controlled, cut break, soft break, square hit, second-ball, or unknown.

Break speed is aspirational. Do not include it in Phase 3 product claims unless frame rate, reference dimensions, and calibration are reliable.

Pattern Intelligence Scope

Pattern play should come after break tagging and layout snapshots.

Initial pattern data:

• Discipline.
• Table-layout snapshot after break or before a key shot.
• Ball group or numbered-ball state when visible.
• Problem clusters.
• Key ball.
• Breakout ball.
• Safety option.
• Player route as executed.
• Human-reviewed recommended route.
• Pattern style: conservative, aggressive, stun-route heavy, draw-route heavy, center-ball/simple-route, breakout-focused, or safety-first.

"Missed pattern opportunity" is not an early metric. It requires a verified route library and rules-aware comparison, so it belongs in later Phase 4 or Phase 5 work.

Rights And Library Boundaries

Break and pattern records inherit the existing three-library model:

• Public pro match evidence: library_type=pro_golden, rights_status=public_link_only, visibility=public_reference.
• Coach/team uploads: library_type=coach_team, visibility=coach_only or team_only.
• Personal uploads: private by default, explicit consent required, training_eligible=false by default.
• Community examples: opt-in only and moderation-required.

Public YouTube break or pattern evidence should remain timestamp links, embeds, annotations, derived data, and reviewed metadata unless footage is licensed or owned.

Access Tier Draft

• Free: sample educational examples and limited public summaries.
• Hobbyist: basic pro break examples and simple discipline filters.
• Coach: Break Lab, player comparison, reviewed break stats, saved teaching examples.
• Academy: advanced pattern library, top-player breakdowns, Golden Racks, academy training-library workflows.
• Admin: CV review queue, detector evaluation, benchmark labeling, rights review, and data export.

Player Profile Integration

Break and pattern intelligence should feed player_library_profiles rather than becoming isolated data.

Future aggregate profile fields may include:

• observed_break_count_by_discipline
• dry_break_rate_observed
• scratch_rate_observed
• legal_break_rate_observed
• break_runout_rate_observed
• cue_ball_control_after_break_pct
• average_spread_score
• average_cluster_score
• break_style_summary
• pattern_style_summary
• safety_after_break_pct
• offensive_route_tendency_pct
• conservative_route_tendency_pct

All rate fields should carry sample size and sample quality. Avoid definitive player claims from partial observed data.

Golden Rack Criteria

A Golden Rack should require:

• Clear discipline label.
• Complete enough video evidence to understand the route.
• Human-reviewed layout or route annotations.
• Source rights status recorded.
• Review status of verified.
• Coach or curator notes explaining why the route matters.
• Pattern category label, such as break-and-run, key-ball route, breakout pattern, safety-first route, or recovery pattern.
• Confidence and visibility metadata.

Separate Implementation Task List

Track 0 - SaaS Quality Gate

• Confirm staging dashboard reads live Render API data.
• Register and test Stripe webhook endpoint.
• Populate live Supabase-backed database with real analysis data.
• Verify auth, entitlement gates, and billing portal behavior.
• Curate the first 100 verified pro examples.
• Collect coach beta feedback before expanding feature surface area.

Track 1 - Break Intelligence Planning

• Define break taxonomy for 8-ball, 9-ball, and 10-ball.
• Draft BreakAnalysis and related schema models.
• Define manual break review fields and review statuses.
• Define break sample-quality levels: complete match sample, partial observed sample, curated example only, camera-qualified sample.
• Define first Break Lab dashboard filters.
• Map Break Lab access to Coach and Academy tiers.

Track 2 - Manual Break Tagging MVP

• Add admin-only manual break record creation.
• Add break review queue or reuse the existing review queue with break-specific fields.
• Tag 100-300 pro breaks across 8-ball, 9-ball, and 10-ball.
• Track source rights and timestamp windows for every break.
• Produce first aggregate break summaries only after sample-size gates are met.

Track 3 - Layout Snapshot Research

• Collect representative post-break frames from public pro footage.
• Label cue ball, 8-ball, solids, stripes, and unknown balls.
• Test table visibility scoring.
• Test shot-boundary detection for broadcast cuts.
• Test simple YOLO-family detector baseline.
• Define when layout output should be shown to humans, hidden, or rejected.

Track 4 - Pattern Route Curation

• Define pattern route schema and route-step fields.
• Build admin route annotation workflow.
• Curate first Golden Rack candidates manually.
• Add route categories and coach notes.
• Keep AI suggestions advisory until reviewed.

Track 5 - CV Evaluation Harness

• Create held-out labeled frame set.
• Measure per-class precision and recall.
• Measure calibration failure rate on broadcast footage.
• Measure tracker identity switches across shot sequences.
• Store CV model/version metadata with each layout suggestion.
• Block product-facing claims below agreed thresholds.

Track 6 - Coach/Player Comparison

• Add private upload comparison only after Phase 4 upload consent and storage flows are stable.
• Compare user break results to verified pro examples by discipline and style.
• Compare user pattern choices to reviewed Golden Rack routes.
• Preserve retention, deletion, export, and training-eligibility controls.

Out Of Scope Until Later

• Automated exact numbered-ball detection as a trusted product claim.
• Automated "best route" claims without human-reviewed route libraries.
• Break speed claims without calibrated video geometry and frame-rate confidence.
• Public community pattern review without moderation and minor-safety controls.
• Any copied or rehosted public YouTube clips without licensed or owned rights.

Immediate Recommendation

Treat break and pattern intelligence as a documented Phase 3+ feature family. During the current production foundation work, focus on SaaS quality, real data, billing/auth correctness, and coach beta validation. The only near-term implementation work that should be allowed is planning, schema design, evaluation design, and optionally manual break-tagging experiments that strengthen the verified library without expanding public product scope.