semantic-metrics-modeling-assistant

The Semantic Metrics Modeling Assistant is a Python-based MCP agent that helps data teams define, validate, and visualize semantic metrics while tracking lineage, usage, and trust scores. It provides a conversational interface for creating metrics, validating definitions, and exporting metrics to BI and data modeling tools. Core capabilities include defining metrics with natural language prompts, validating metric definitions through tests, visualizing lineage and dependencies via ASCII trees or Mermaid diagrams, and assessing quality with a multi-dimensional trust score. It also supports exporting metrics to Looker (LookML), Tableau (TDS), and dbt YAML definitions for integration into existing data stacks.

To use the server, run the MCP entry point and interact with the defined API/CLI tools exposed by the semantic_metrics.server module. Typical workflows involve defining a metric using define_metric(...), validating it with validate_metric(...), visualizing its lineage with visualize_lineage(...), checking the trust score with check_trust_score(...), and exporting artifacts to BI tools with export_to_looker(...), export_to_tableau(...), or export_to_dbt(...). The system stores data in a SQLite database (metrics.db) with a five-table schema to persist metrics, history, tests, usage, and trust scores, enabling change tracking and governance automation over time.

Prerequisites:

• Python 3.10+ (per project README)
• Git
• Internet access to install dependencies

Step-by-step installation:

1. Clone the repository: git clone https://github.com/jkelleman/semantic-metrics-modeling-assistant.git cd semantic-metrics-modeling-assistant

2. (Optional) Create and activate a virtual environment: python -m venv venv source venv/bin/activate # On Windows use: venv\Scripts\activate

3. Install dependencies in editable mode (preferred for development): pip install -e .

4. Run the MCP server: python -m semantic_metrics.server

5. (Optional) Run tests: pytest tests/

Notes:

• The server uses SQLite by default and will create metrics.db on first run.
• Ensure network access if you plan to export metrics to external BI tools or Git integrations.

Tips and common considerations:

• Environment variables: The project stores data locally in SQLite (metrics.db). If deploying in a container or cloud environment, consider mounting a persistent volume for the database.
• Export options: Looker, Tableau, and dbt exporters generate production-ready artifacts (LookML, TDS XML, and YAML, respectively). Ensure appropriate permissions and paths when writing these files in your deployment environment.
• Change tracking and governance: The five-table schema enables audit trails and rollback capabilities. Use the history and trust score metadata to explain metric changes to stakeholders.
• Testing and quality: Leverage the trust scoring components (Tests, Usage, Freshness, Documentation, Ownership, Trend Analysis) to monitor metric health over time and guide improvements.
• Troubleshooting: If metrics.db is not created, verify write permissions in the working directory and ensure the server process has sufficient filesystem access. If Python dependencies fail to install, ensure pip is up to date and that you are using Python 3.10+ as recommended.