pipeline-standards

UFC Pipeline Coding Standards

This document is the single source of truth for all backend service pipeline code standards. It is referenced by .bob/skills/sdd-pipeline-builder/SKILL.md during code generation.

1. Required File Structure (in order)

# 1. Imports + warnings suppression + logging setup
import warnings, logging, utils, pandas as pd
from typing import List, Dict, Any, Optional, Tuple
warnings.filterwarnings("ignore")
logging.basicConfig(level=logging.INFO,
    format='%(asctime)s - %(levelname)s - %(message)s', datefmt='%Y-%m-%d %H:%M:%S')

# 2. Environment shim
def init_environment():
    """Compatibility shim — delegates to utils.init_pipeline_environment()."""
    return utils.init_pipeline_environment()

# 3. UPPER_SNAKE_CASE constants (the ONLY allowed module-level names)
STAT_THRESHOLDS = { ... }       # if stat-based
MIN_FIGHTS_FOR_INSIGHT = 5
TOP_N_RANKINGS = 5
BASE_INSIGHT_SCORE = 100
PRESTIGE_PENALTY = 5
THRESHOLD_PENALTY = 3           # if applicable
INSIGHT_TYPE = "Pipeline Name"

# 4. Core metric/calculation functions
# 5. get_top_{metric}_for_group() + find_fighter_ranking()
# 6. calculate_insight_score()
# 7. _build_llm_system_and_user()
# 8. generate_insight_heading_deterministic()
# 9. generate_insight_heading()
# 10. _build_facts_object()
# 11. generate_insights()       ← always the last function

2. Imports

• Backend services: import utils (resolves to backend/utils.py)
• Never use import experimental.utils
• No variables declared outside functions — only UPPER_SNAKE_CASE constants are permitted at module level

3. Prestige Ranking System

Seven ranks, 1 = most prestigious:

• Get groups: utils.get_standard_ranking_groups()
• Filter per group: utils.filter_fighter_data_by_group(fighter_data, group)
• Select best: utils.find_best_ranking(all_rankings) — picks lowest prestige_rank, then lowest rank
• Use ranking_cache param in get_top_*_for_group() to avoid recomputing the same leaderboard