Semantic Metrics Modeling Assistant

🚀 セマンティックメトリクスモデリングアシスタント

このアシスタントは、データチームがセマンティックレイヤーを扱う際の認知負荷を軽減するために設計されたMCPエージェントです。エンタープライズレベルの永続性、信頼性スコアリング、BI統合機能を備え、メトリクスの定義、検証、可視化をサポートします。

🚀 クイックスタート

インストール

# リポジトリをクローン
git clone https://github.com/jkelleman/semantic-metrics-modeling-assistant.git
cd semantic-metrics-modeling-assistant

# 依存関係をインストール
pip install -e .

# MCPサーバーを起動
python -m semantic_metrics.server

# またはテストを実行
pytest tests/

データベースのセットアップ

エージェントは初回実行時に自動的にSQLiteデータベース (metrics.db) を作成します。以下の情報が格納されます。

• メトリクス定義テーブル
• 変更履歴の追跡
• 検証テスト結果
• 使用統計
• 信頼性スコアの推移

使用例

基本的な使用法

新しいメトリクスを定義する：

define_metric(
    name="Active Users",
    description="Daily unique user logins",
    calculation="COUNT(DISTINCT user_id) WHERE login_date = CURRENT_DATE",
    owner="@data-team",
    tags=["engagement", "daily"]
)

強化された信頼性スコアを確認する：

check_trust_score("Active Users")

# 返り値:
# Trust Score: 87/100 ↗️
# Tests: 4 passing (35/35 points) ✅
# Usage: 12 dashboards, 8 users (18/20 points)
# Freshness: Updated 2 hours ago (14/15 points)
# Documentation: Complete with examples (15/15 points)
# Ownership: @data-team (15/15 points)
#
# Trend: ▂▄▆█ (improving over 30 days)
# Recommendations: Add integration tests for edge cases

メトリクスの関係を可視化する：

visualize_lineage("Revenue per Customer")

# 返り値: ASCIIツリー
# Revenue per Customer
#   ├── Total Revenue
#   │   ├── Order Amount (raw.orders)
#   │   └── Refunds (raw.refunds)
#   └── Customer Count
#       └── Unique Customers (raw.users)

Mermaid図を生成する：

generate_mermaid_diagram("Revenue per Customer")

# 返り値:
# ```mermaid
# flowchart TD
#     A[Revenue per Customer] --> B[Total Revenue]
#     A --> C[Customer Count]
#     B --> D[Order Amount]
#     B --> E[Refunds]
#     C --> F[Unique Customers]
# ```

BIツールにエクスポートする：

# Lookerにエクスポート
export_to_looker("Active Users")
# 生成される: active_users.lkml

# Tableauにエクスポート
export_to_tableau("Active Users")
# 生成される: active_users.tds (XML)

# dbtにエクスポート
export_to_dbt("Active Users")
# 生成される: active_users.yml

✨ 主な機能

🗄️ エンタープライズデータの永続性

• SQLiteデータベース - 完全な監査トレイルを持つ永続的なストレージ
• 5テーブルスキーマ - メトリクス、履歴、テスト、使用状況、信頼性スコア
• 変更追跡 - すべてのメトリクス変更の完全な履歴
• バージョン管理対応 - Git統合とロールバックのために設計

💬 会話形式のメトリクス定義

会話を通じて自然にメトリクスを定義できます。

"Define 'Active Users' as daily unique logins"
"Create a metric for revenue per customer"
"What's the definition of our churn rate metric?"

📊 BIツールの統合

業界標準のプラットフォームにメトリクスをエクスポートできます。

• Looker (LookML) - 本番環境で使用可能なLookMLファイルを生成
• Tableau (TDS) - TableauデータソースXMLとしてエクスポート
• dbt - dbtメトリクスYAML定義を作成

🎯 強化された信頼性スコアリング

重み付けアルゴリズムによる高度な品質評価。

• テスト (35%の重み) - 検証テストのカバレッジと合格率
• 使用状況 (20%の重み) - チームやダッシュボード全体での採用状況
• 新鮮さ (15%の重み) - 時間経過によるデータの古さ
• ドキュメント (15%の重み) - 完全性と明瞭さ
• 所有権 (15%の重み) - 明確な責任所在
• トレンド分析 - スパークラインで品質の変化を経時的に追跡

🎨 視覚的な関係性と依存関係

メトリクスの関係を理解するための最新の可視化オプション。

• Mermaid図 - GitHub/Notion/Confluence用の美しいフローチャート
• ASCIIツリー - ターミナルで使いやすい依存関係の可視化
• 影響分析 - 変更前に下流の影響を理解
• 循環依存関係の検出 - 競合を特定して解決

✅ 包括的なテスト

本番環境で使用可能なテストカバレッジ。

• 35以上のテスト - データベース、信頼性スコアリング、エクスポーター、ツール
• pytestフレームワーク - フィクスチャを使用した業界標準のテスト
• 90%以上のカバレッジ - コア機能が十分に検証されている
• CI/CD対応 - 継続的統合のための自動テスト

📚 詳細ドキュメント

なぜこれが重要か

問題点

データチームは以下のようなシステム的な課題に直面しています。

• メトリクスの拡散 - コアビジネスメトリクスに複数の矛盾する定義が存在する
• 信頼性の不足 - 品質信号の欠如により、メトリクスの選択や報告の不一致が生じる
• 認知的負荷 - 複雑な依存関係のチェーンと関係性を理解するのが困難
• ガバナンスの断片化 - 所有権と検証プロセスが即興的または存在しない

解決策

このアシスタントは以下の方法でこれらの課題に対処します。

• 抽象化レイヤー - 自然言語インターフェイスにより、YAML構成の複雑さを抽象化
• 透明性メカニズム - 多次元の信頼性スコアにより、品質を可視化
• ガバナンスの自動化 - 所有権、テスト、ドキュメントのための組み込みプロンプト
• 可観測性の計装 - 使用状況の追跡と新鮮さの監視

アーキテクチャ

┌─────────────────────────────────────────┐
│  会話型インターフェイス (MCPツール)   │
├─────────────────────────────────────────┤
│  • define_metric()                      │
│  • validate_metric()                    │
│  • visualize_lineage()                  │
│  • check_trust_score()                  │
│  • search_metrics()                     │
└─────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────┐
│  メトリクスリポジトリ                  │
├─────────────────────────────────────────┤
│  • メトリクス定義を保存                │
│  • 関係性と依存関係を追跡              │
│  • 使用状況と品質メタデータを収集      │
└─────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────┐
│  データソースの統合                   │
├─────────────────────────────────────────┤
│  • dbtプロジェクトファイル            │
│  • LookMLモデル                        │
│  • YAMLメトリクス仕様                  │
│  • SQLクエリ                          │
└─────────────────────────────────────────┘

設計原則

1. 会話型を第一とする

自然言語インターフェイスにより、複雑なYAML構成を抽象化します。構文の暗記よりも会話型のインタラクションを優先し、学習曲線を軽減します。

2. 見せる、語らない

テキスト説明よりも視覚的な表現を優先します。関係性を有向非巡回グラフ (DAG) としてレンダリングし、依存関係を即座に理解できるようにします。

3. 透明性による信頼

品質指標を第一級属性として公開します。多次元の信頼性スコアにより、メトリクスの信頼性に関する実行可能な信号を提供します。

4. 段階的な開示

デフォルトでは高レベルの要約を表示し、詳細なメタデータにはドリルダウンでアクセスできるようにする情報階層を実装します。

5. デフォルトでのガバナンス

ガバナンスが最も簡単な方法になるようにインターフェイスを設計します。プロンプト、検証、必須フィールドを使用して、摩擦を増やすことなくベストプラクティスを強制します。

使用ケース

データチームメンバー

「誰もが信頼できる顧客生涯価値のメトリクスを作成したい。」

アシスタントの支援：

• メトリクスを平易な言葉で定義する
• SQLロジックを検証する
• 類似する既存のメトリクスを確認する
• 所有権とドキュメントを設定する
• メトリクスカタログに追加する

アナリティクスエンジニア

「なぜ私のダッシュボードが財務部門と異なる収益数値を表示しているのか？」

アシスタントの支援：

• 収益メトリクスの定義を比較する
• 関係性とデータソースを表示する
• 定義が異なる箇所を特定する
• 正規のメトリクスを推奨する

データリーダー

「最も重要で、より良いガバナンスが必要なメトリクスはどれか？」

アシスタントの支援：

• 使用状況と信頼性スコアでメトリクスを表示する
• 使用頻度が高く、信頼性が低いメトリクスを特定する
• ガバナンスのカバレッジを追跡する
• メトリクスの健全性を経時的に監視する

🔧 技術詳細

技術スタック

• Python 3.10+ - コア言語
• FastMCP - MCPプロトコルの実装
• SQLite - 永続的なデータベースストレージ
• pytest - 35以上のテストを持つテストフレームワーク
• YAML/JSON - メトリクス定義とエクスポート
• Mermaid - 最新の図生成

MCPツール (合計13個)

メトリクス管理

品質と信頼性

可視化

エクスポートと統合

高度な機能

このプロジェクトが示すもの

UXスキル

• 認知負荷の軽減 - 複雑なシステムを単純化する抽象化レイヤーを設計する
• 信頼性の設計 - 透明な品質信号と高度な重み付けスコアリングアルゴリズムにより信頼感を構築する
• 段階的な開示 - 発見性と詳細をバランスさせる情報アーキテクチャ
• 会話型UI - 技術的な構成のための自然言語インターフェイス

技術スキル

• MCP開発 - 13のツールと1,500行以上のコードを持つ本番グレードのAIエージェント
• データベース設計 - 5テーブルスキーマと完全な監査トレイルを持つSQLiteの永続性
• データモデリング - セマンティックレイヤーの設計パターンとメトリクス定義フレームワーク
• システムアーキテクチャ - ガバナンスの自動化と可観測性の計装
• テスト - pytestを使用した35以上のテスト、コア機能の90%以上のカバレッジ
• 統合パターン - Looker、Tableau、dbt用のBIツールエクスポーター

ドメインエキスパートナイズ

• メトリクスガバナンス - 所有権モデル、検証フレームワーク、ドキュメント標準を確立する
• データ関係性 - 依存関係グラフの構築と影響分析
• データ可観測性 - 新鮮さの追跡、時間経過による品質監視、使用状況分析
• セマンティックレイヤー - 最新のデータスタックパターンとメトリクスモデリングのベストプラクティス

このプロジェクトが重要な理由

Microsoftの主任コンテンツデザイナーとして、データとAIシステムに取り組んでいる私にとって、このプロジェクトは以下を示しています。

1. データチームの課題に対する深い理解 - 本番環境でのメトリクスの拡散と信頼性の不足に関する直接的な経験
2. 技術的なユーザーのためのUX - システムの機能を維持しながら認知負荷を軽減する抽象化レイヤーを設計する
3. 信頼性と可観測性のための設計 - 透明な品質計装と重み付けスコアリングによるエンタープライズレベルのガバナンスパターンを適用する
4. AI強化ワークフロー - MCPを活用して、人間の意思決定とドメインエキスパートナイズを強化する（置き換えるのではない）
5. 本番環境で使用可能な実装 - 35以上のテスト、データベースの永続性、およびBI統合が実世界のデプロイに対応している

これは、エンタープライズデータプラットフォームが必要とする人間中心の設計を表しています。摩擦のないガバナンス、測定可能な信頼性、管理可能な複雑さです。

📄 ライセンス

このプロジェクトはMITライセンスの下で公開されています。詳細については、こちらを参照してください。

最近の機能強化

✅ SQLiteデータベース - 5テーブルスキーマを持つ完全な永続性 ✅ BI統合 - LookerとTableauのエクスポートツール ✅ 強化された信頼性スコアリング - 時間経過による重み付けアルゴリズムとトレンド ✅ Mermaid図 - ドキュメント用の最新の可視化 ✅ テストスイート - pytestを使用した35以上のテストと90%以上のカバレッジ

完全な技術詳細については、IMPLEMENTATION_SUMMARY.mdを参照してください。

このプロジェクトについて

Jen Kelleman
スタッフプロダクトデザイナー

私は、透明で適切に計装されたシステムを通じて、認知負荷を軽減し、信頼感を構築するAIとデータのエクスペリエンスを設計しています。

コンタクト

• LinkedIn
• Medium
• AI Content Design Handbook

他のプロジェクト

• MCP-Oreilly - コンテンツデザイン、会議分析、およびドキュメント用の3つの本番用MCPエージェント
• AI Content Design Handbook - AIシステムのUXライティングに関する包括的なガイド

データガバナンスを人間中心に、1つのメトリクスずつ。