# Metric Definition Template
# Standardized template for defining and documenting metrics across the AI Agentic Data Stack Framework

metadata:
  template_id: "metric-definition-tmpl"
  name: "Metric Definition Template"
  version: "1.0.0"
  description: "Comprehensive template for defining business and technical metrics with clear specifications, calculations, and governance"
  category: "metrics-governance"
  tags: ["metrics", "kpi", "definitions", "calculations", "governance", "standards"]
  created_by: "AI Agentic Data Stack Framework"
  created_date: "2025-01-23"

# Template Structure
template:
  name: "Metric Definition Template"
  description: "Template for creating comprehensive metric definitions with business context and technical specifications"
  version: "1.0.0"

sections:
  - metric_info
  - business_context
  - technical_definition
  - measurement_specs
  - temporal_characteristics
  - data_quality
  - governance
  - display_configuration
  - relationships
  - usage_guidelines
  - technical_implementation
  - testing
  - documentation
  - monitoring

# Metric Basic Information
metric_info:
  # Identity
  metric_id: "${metric_id}"
  metric_name: "${metric_name}"
  display_name: "${display_name}"
  short_name: "${short_name}"
  aliases: ["${metric_aliases}"]
  
  # Classification
  classification:
    category: "${metric_category}" # financial, operational, customer, product, quality, risk
    subcategory: "${metric_subcategory}"
    type: "${metric_type}" # kpi, operational, diagnostic, leading, lagging
    level: "${organizational_level}" # strategic, tactical, operational
    
  # Metadata
  metadata:
    owner: "${metric_owner}"
    steward: "${data_steward}"
    created_date: "${creation_date}"
    last_modified: "${last_modified_date}"
    version: "${metric_version}"
    status: "${metric_status}" # active, deprecated, draft, under_review

# Business Context
business_context:
  # Purpose and Objective
  purpose:
    business_objective: "${business_objective}"
    why_measured: "${why_measured}"
    decision_impact: "${decision_impact}"
    strategic_alignment: "${strategic_alignment}"
    
  # Audience and Usage
  audience:
    primary_users: ["${primary_users}"]
    secondary_users: ["${secondary_users}"]
    reporting_frequency: "${reporting_frequency}" # daily, weekly, monthly, quarterly, annually
    usage_context: ["${usage_contexts}"] # dashboard, report, alert, analysis
    
  # Business Rules
  business_rules:
    inclusion_criteria: ["${inclusion_criteria}"]
    exclusion_criteria: ["${exclusion_criteria}"]
    business_logic: "${business_logic}"
    special_considerations: ["${special_considerations}"]

# Technical Definition
technical_definition:
  # Calculation Specification
  calculation:
    formula: "${calculation_formula}"
    formula_description: "${formula_description}"
    calculation_method: "${calculation_method}" # sum, average, count, ratio, rate, percentage
    
    # Components
    numerator:
      definition: "${numerator_definition}"
      data_source: "${numerator_source}"
      filters: ["${numerator_filters}"]
      
    denominator:
      definition: "${denominator_definition}"
      data_source: "${denominator_source}"
      filters: ["${denominator_filters}"]
      
    # Calculation Steps
    calculation_steps:
      - step_number: ${step_number}
        description: "${step_description}"
        operation: "${step_operation}"
        inputs: ["${step_inputs}"]
        output: "${step_output}"
        
  # Data Sources
  data_sources:
    - source_id: "${source_id}"
      source_name: "${source_name}"
      source_type: "${source_type}" # database, api, file, manual
      table_name: "${table_name}"
      fields_used: ["${fields_used}"]
      join_conditions: ["${join_conditions}"]
      
  # Data Processing
  data_processing:
    aggregation_level: "${aggregation_level}" # transaction, daily, weekly, monthly
    time_grain: "${time_grain}"
    filters_applied: ["${filters_applied}"]
    transformations: ["${transformations}"]
    data_quality_rules: ["${quality_rules}"]

# Measurement Specifications
measurement_specs:
  # Units and Scale
  units:
    unit_of_measure: "${unit_of_measure}" # currency, percentage, count, ratio, rate
    currency: "${currency_code}" # USD, EUR, GBP, etc.
    decimal_places: ${decimal_places}
    scale_factor: "${scale_factor}" # thousands, millions, billions
    
  # Value Ranges
  value_ranges:
    minimum_value: ${minimum_expected_value}
    maximum_value: ${maximum_expected_value}
    typical_range: "${typical_value_range}"
    outlier_threshold: ${outlier_threshold}
    
  # Thresholds and Targets
  thresholds:
    target_value: ${target_value}
    target_type: "${target_type}" # absolute, relative, trending
    
    # Performance Bands
    performance_bands:
      excellent:
        threshold: ${excellent_threshold}
        color: "${excellent_color}"
        
      good:
        threshold: ${good_threshold}
        color: "${good_color}"
        
      acceptable:
        threshold: ${acceptable_threshold}
        color: "${acceptable_color}"
        
      poor:
        threshold: ${poor_threshold}
        color: "${poor_color}"
        
  # Benchmarks
  benchmarks:
    internal_benchmark: ${internal_benchmark}
    industry_benchmark: ${industry_benchmark}
    best_practice_benchmark: ${best_practice_benchmark}
    benchmark_source: "${benchmark_source}"

# Temporal Characteristics
temporal_characteristics:
  # Time Dimensions
  time_dimensions:
    measurement_frequency: "${measurement_frequency}" # real-time, hourly, daily, weekly, monthly
    reporting_frequency: "${reporting_frequency}"
    historical_availability: "${historical_availability}"
    retention_period: "${data_retention_period}"
    
  # Time-based Variations
  time_variations:
    seasonality: "${seasonality_pattern}"
    cyclical_patterns: ["${cyclical_patterns}"]
    trend_expectations: "${trend_expectations}"
    
  # Lag and Latency
  timing:
    data_latency: "${data_latency}" # real-time, 1-hour, 1-day, etc.
    reporting_lag: "${reporting_lag}"
    refresh_schedule: "${refresh_schedule}"

# Data Quality and Validation
data_quality:
  # Quality Dimensions
  quality_dimensions:
    accuracy:
      accuracy_threshold: ${accuracy_threshold}
      validation_method: "${accuracy_validation}"
      
    completeness:
      completeness_threshold: ${completeness_threshold}
      missing_data_handling: "${missing_data_strategy}"
      
    consistency:
      consistency_rules: ["${consistency_rules}"]
      cross_validation: ["${cross_validation_checks}"]
      
    timeliness:
      freshness_requirement: "${freshness_requirement}"
      staleness_threshold: "${staleness_threshold}"
      
  # Validation Rules
  validation_rules:
    - rule_id: "${rule_id}"
      rule_description: "${rule_description}"
      rule_type: "${rule_type}" # range, format, relationship, business
      validation_logic: "${validation_logic}"
      error_handling: "${error_handling_strategy}"
      
  # Data Lineage
  lineage:
    upstream_dependencies: ["${upstream_dependencies}"]
    downstream_impacts: ["${downstream_impacts}"]
    transformation_chain: ["${transformation_chain}"]

# Governance and Compliance
governance:
  # Ownership and Accountability
  ownership:
    business_owner: "${business_owner}"
    technical_owner: "${technical_owner}"
    data_steward: "${data_steward}"
    approver: "${metric_approver}"
    
  # Change Management
  change_management:
    change_approval_required: ${change_approval_required}
    change_notification_list: ["${change_notification_list}"]
    impact_assessment_required: ${impact_assessment_required}
    version_control_strategy: "${version_control_strategy}"
    
  # Compliance Requirements
  compliance:
    regulatory_requirements: ["${regulatory_requirements}"]
    privacy_considerations: ["${privacy_considerations}"]
    security_classification: "${security_classification}"
    audit_requirements: ["${audit_requirements}"]

# Display and Presentation
display_configuration:
  # Visualization Settings
  visualization:
    default_chart_type: "${default_chart_type}"
    color_coding: "${color_coding_scheme}"
    trend_display: "${trend_display_method}"
    comparison_method: "${comparison_method}"
    
  # Formatting
  formatting:
    number_format: "${number_format}" # #,##0, #,##0.0, 0.0%
    prefix: "${display_prefix}"
    suffix: "${display_suffix}"
    negative_handling: "${negative_value_display}"
    
  # Dashboard Integration
  dashboard_settings:
    widget_type: "${dashboard_widget_type}"
    size_requirements: "${widget_size}"
    refresh_behavior: "${refresh_behavior}"
    drill_down_enabled: ${drill_down_enabled}

# Related Metrics and Relationships
relationships:
  # Metric Hierarchy
  hierarchy:
    parent_metrics: ["${parent_metrics}"]
    child_metrics: ["${child_metrics}"]
    peer_metrics: ["${peer_metrics}"]
    
  # Dependencies
  dependencies:
    prerequisite_metrics: ["${prerequisite_metrics}"]
    derived_metrics: ["${derived_metrics}"]
    correlated_metrics: ["${correlated_metrics}"]
    
  # Metric Families
  metric_families:
    family_name: "${metric_family}"
    family_members: ["${family_members}"]
    family_relationships: ["${family_relationships}"]

# Usage Guidelines
usage_guidelines:
  # Interpretation Guidelines
  interpretation:
    what_good_looks_like: "${positive_interpretation}"
    what_bad_looks_like: "${negative_interpretation}"
    common_misconceptions: ["${common_misconceptions}"]
    interpretation_caveats: ["${interpretation_caveats}"]
    
  # Action Guidelines
  actions:
    threshold_breach_actions: ["${threshold_breach_actions}"]
    improvement_strategies: ["${improvement_strategies}"]
    escalation_procedures: ["${escalation_procedures}"]
    
  # Best Practices
  best_practices:
    usage_recommendations: ["${usage_recommendations}"]
    analysis_tips: ["${analysis_tips}"]
    reporting_guidelines: ["${reporting_guidelines}"]

# Technical Implementation
technical_implementation:
  # Database Schema
  database_schema:
    storage_table: "${storage_table}"
    primary_key: "${primary_key}"
    partition_strategy: "${partition_strategy}"
    indexing_strategy: ["${indexing_strategy}"]
    
  # Calculation Logic
  calculation_logic:
    sql_query: "${sql_calculation_query}"
    stored_procedure: "${stored_procedure_name}"
    calculation_engine: "${calculation_engine}"
    
  # API Specifications
  api_specs:
    endpoint: "${api_endpoint}"
    parameters: ["${api_parameters}"]
    response_format: "${response_format}"
    authentication: "${authentication_method}"
    
  # Automation
  automation:
    automated_calculation: ${automated_calculation}
    calculation_schedule: "${calculation_schedule}"
    error_handling: "${automated_error_handling}"
    monitoring: "${calculation_monitoring}"

# Testing and Validation
testing:
  # Test Cases
  test_cases:
    - test_id: "${test_id}"
      test_description: "${test_description}"
      test_data: "${test_data_description}"
      expected_result: "${expected_result}"
      actual_result: "${actual_result}"
      test_status: "${test_status}" # pass, fail, pending
      
  # Validation Scenarios
  validation_scenarios:
    edge_cases: ["${edge_cases}"]
    boundary_conditions: ["${boundary_conditions}"]
    error_conditions: ["${error_conditions}"]
    
  # Performance Testing
  performance_testing:
    calculation_performance: "${calculation_time}"
    data_volume_tested: "${test_data_volume}"
    scalability_limits: "${scalability_limits}"

# Documentation and Communication
documentation:
  # User Documentation
  user_documentation:
    user_guide: "${user_guide_location}"
    faq: ["${frequently_asked_questions}"]
    examples: ["${usage_examples}"]
    troubleshooting: ["${troubleshooting_guide}"]
    
  # Technical Documentation
  technical_documentation:
    technical_spec: "${technical_specification_location}"
    implementation_guide: "${implementation_guide}"
    api_documentation: "${api_documentation_link}"
    
  # Training Materials
  training:
    training_materials: ["${training_materials}"]
    certification_requirements: ["${certification_requirements}"]
    competency_requirements: ["${competency_requirements}"]

# Monitoring and Alerting
monitoring:
  # Performance Monitoring
  performance_monitoring:
    calculation_time_monitoring: ${calc_time_monitoring}
    data_freshness_monitoring: ${freshness_monitoring}
    accuracy_monitoring: ${accuracy_monitoring}
    
  # Alerting Rules
  alerting:
    - alert_id: "${alert_id}"
      alert_condition: "${alert_condition}"
      alert_threshold: ${alert_threshold}
      alert_recipients: ["${alert_recipients}"]
      alert_frequency: "${alert_frequency}"
      escalation_path: ["${escalation_path}"]
      
  # Health Checks
  health_checks:
    data_availability_check: "${availability_check}"
    calculation_validation_check: "${validation_check}"
    business_logic_check: "${business_logic_check}"

# Validation Rules
validation_rules:
  required_fields:
    - metric_id
    - metric_name
    - business_objective
    - calculation_formula
    - data_sources
    
  field_constraints:
    metric_type:
      allowed_values: ["kpi", "operational", "diagnostic", "leading", "lagging"]
    organizational_level:
      allowed_values: ["strategic", "tactical", "operational"]
    metric_status:
      allowed_values: ["active", "deprecated", "draft", "under_review"]
      
  business_requirements:
    - business_owner: "required"
    - target_value: "recommended"
    - thresholds: "recommended"

# Metric Categories
metric_categories:
  financial_metrics:
    examples: ["revenue", "profit_margin", "cost_per_acquisition", "roi"]
    common_attributes: ["currency_denomination", "accounting_standards"]
    
  operational_metrics:
    examples: ["efficiency", "utilization", "throughput", "cycle_time"]
    common_attributes: ["operational_context", "process_dependencies"]
    
  customer_metrics:
    examples: ["satisfaction", "retention", "lifetime_value", "churn_rate"]
    common_attributes: ["customer_segmentation", "survey_methodology"]
    
  quality_metrics:
    examples: ["defect_rate", "accuracy", "completeness", "compliance"]
    common_attributes: ["quality_standards", "measurement_methodology"]

# Usage Examples
examples:
  revenue_metric:
    metric_name: "Monthly Recurring Revenue"
    calculation_formula: "SUM(subscription_value) WHERE subscription_status = 'active'"
    unit_of_measure: "currency"
    reporting_frequency: "monthly"
    
  customer_satisfaction:
    metric_name: "Net Promoter Score"
    calculation_formula: "(%Promoters - %Detractors)"
    unit_of_measure: "percentage"
    value_ranges:
      minimum_value: -100
      maximum_value: 100

# Documentation References
documentation_references:
  metric_standards: "https://www.klipfolio.com/resources/articles/what-is-a-key-performance-indicator"
  calculation_best_practices: "https://www.tableau.com/learn/articles/kpi-dashboard"
  governance_frameworks: "https://www.dama-dmbok.org/"
  
# Template Metadata
template_metadata:
  author: "AI Agentic Data Stack Framework"
  maintainer: "Data Analyst"
  last_updated: "2025-01-23"
  changelog:
    - version: "1.0.0"
      date: "2025-01-23"
      changes: "Initial template creation with comprehensive metric definition structure"