agentic-data-stack-community
Version:
AI Agentic Data Stack Framework - Community Edition. Open source data engineering framework with 4 core agents, essential templates, and 3-dimensional quality validation.
482 lines (414 loc) • 15.5 kB
YAML
# 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"