Skip to main content

msh ai explain

Use AI to explain what an asset does in plain language.

Usage​

msh ai explain <asset_path> [--json]

Description​

Generates a natural language explanation of an asset, including:

  • What data it ingests
  • What transformation it performs
  • Output schema
  • Dependencies (upstream/downstream)
  • Business purpose

Options​

  • --json: Return structured explanation object instead of plain text

Examples​

Basic Explanation​

msh ai explain assets/revenue.msh

Example Output:

Asset: revenue

Summary:
This asset ingests customer order data from a PostgreSQL database and
calculates monthly revenue per customer. It joins orders with customer
information and aggregates revenue by month.

Grain: One row per customer per month

Upstream Assets:
- stg_orders (staging layer)
- stg_customers (staging layer)

Downstream Assets:
- fct_monthly_revenue (marts layer)

Business Terms:
- Customer: A customer entity
- Revenue: Total revenue amount
- Monthly: Aggregated by month

Structured Output​

msh ai explain assets/revenue.msh --json

Example JSON Output:

{
  "summary": "This asset ingests customer order data...",
  "grain": "One row per customer per month",
  "upstream_assets": ["stg_orders", "stg_customers"],
  "downstream_assets": ["fct_monthly_revenue"],
  "business_terms": [
    {
      "term": "Customer",
      "description": "A customer entity"
    },
    {
      "term": "Revenue",
      "description": "Total revenue amount"
    }
  ],
  "policies": []
}

Prerequisites​

  1. AI Configuration: Must configure AI provider first

    msh config ai --provider openai --model gpt-4 --api-key env:OPENAI_API_KEY

  2. Manifest: Generate manifest before using AI commands

    msh manifest

  3. Asset: Asset must exist and be parseable

Use Cases​

  • Understanding Legacy Assets: Quickly understand what existing assets do
  • Onboarding: Help new team members understand the project
  • Documentation: Generate documentation for assets
  • Code Review: Understand assets before reviewing changes