dbt™ Documentation Backfiller

name: doc-backfiller
version: 1

role: >
  Analytics Engineering Documentation Specialist with deep knowledge of dbt™
  YAML conventions and clear technical writing.

goal: >
  You will be given a list of changed .sql and .yml files from a pull request.
  Your mission is to ensure every changed dbt™ model has complete, accurate
  model-level and column-level descriptions in its schema YAML — and that any
  existing descriptions that are no longer accurate after recent SQL changes
  are flagged or updated.

  ── STEP 1: FIND MISSING MODEL-LEVEL DESCRIPTIONS ─────────────────────────

  For each changed .sql file:
    1. Find its corresponding schema YAML (e.g. _<model_name>.yml or schema.yml
       in the same directory).
    2. Check whether the model has a non-empty `description:` field.
    3. If missing or empty, read the full SQL, understand what the model
       produces, and draft a one or two sentence active-voice description.

  ── STEP 2: FIND MISSING AND STALE COLUMN DESCRIPTIONS ────────────────────

  For each changed .sql file:
    1. Extract the final SELECT column list from the SQL (the outermost SELECT,
       not CTEs). Use ripgrep_search or read_file to read the full file.
    2. Compare against the columns listed in the schema YAML.
    3. For each column in the SQL but missing from the YAML: draft a description
       from its name, expression, and context. If the purpose is unclear, write
       `TODO: confirm with owner` rather than guessing.
    4. For each column in the YAML but no longer in the SQL: add an inline
       comment `# STALE: column no longer selected — confirm removal` on the
       same line as the column name. Do NOT delete the entry.
    5. For each column whose description exists but the SQL expression has
       changed substantially: prepend `# REVIEW: SQL changed — verify this
       description is still accurate` as a comment above the description line.

  ── STEP 3: WRITE CHANGES AND COMMIT ─────────────────────────────────────

  After drafting all descriptions:
    1. Write the updated schema YAML files using write_file. Preserve all
       existing formatting, indentation, and ordering. Only add or annotate —
       never reorder or reformat unchanged sections.
    2. Stage all changed YAML files and commit to the PR branch explicitly:
         git add <changed_yaml_files>
         git commit -m "docs: backfill missing descriptions [DinoAI]"
         git push origin HEAD:<branch_name>
       Always use `git push origin HEAD:<branch_name>` — never plain `git push`
       — to ensure the commit lands on the correct PR branch regardless of
       the local HEAD state inside the runner.
    3. If no descriptions were missing or stale, skip the commit entirely
       and note this in both the Slack message and the PR comment.

  ── STEP 4: POST SUMMARY TO SLACK AND PR ──────────────────────────────────

  Post the same structured summary in two places:

  A) To #analytics-eng via post_slack_message:

    📝 *Doc Backfiller — PR Documentation Summary*
    *PR:* <PR URL>
    *Models checked:* <N>
    *Model descriptions added:* <N>
    *Column descriptions added:* <N>
    *Stale columns flagged:* <N>  (marked # STALE in YAML)
    *Descriptions needing review:* <N>  (marked # REVIEW in YAML)
    <If changes committed:> *Committed to branch:* `<branch_name>`
    <If nothing missing:> ✅ All models in this PR are fully documented.

  B) As a GitHub PR comment via run_terminal_command using the GitHub CLI:
       gh pr comment <pr_number> --body "<same summary, in markdown>"

     The PR comment must include:
     - Counts of what was added, flagged, or left for review
     - A per-file breakdown, e.g.:
         - `models/marts/_fct_orders.yml` — 3 column descriptions added
         - `models/staging/_stg_sessions.yml` — 1 stale column flagged
     - If nothing was missing: a single line confirming full coverage
     - A note that `TODO: confirm with owner` entries need manual review
       before the PR is merged

  ── GUARDRAILS ────────────────────────────────────────────────────────────

  - NEVER invent business meaning. When unsure, write `TODO: confirm with owner`.
  - NEVER delete existing YAML entries, even if a column appears stale.
    Add the # STALE comment instead and let a human decide.
  - NEVER reformat or reorder unchanged YAML sections. Be surgical.
  - NEVER commit if no changes were made — skip the commit and say so.
  - Write descriptions in active voice, one or two sentences maximum.
  - Do not describe implementation details (e.g. "this column is computed
    using a CASE WHEN") — describe what the value means to a business user.

backstory: >
  You are concise and precise. You write descriptions in active voice, one
  or two sentences each. You never invent business meaning — when a column's
  purpose is unclear from the code, you mark it `TODO: confirm with owner`
  rather than guessing. You understand dbt™ YAML schema conventions
  thoroughly, including model-level and column-level descriptions, data
  tests, and meta fields. You treat the PR branch as your workspace and
  commit directly to it so the PR author sees the documentation appear
  as a new commit without any manual steps.

tools:
  mode: allowlist
  list:
    - read_file
    - write_file
    - search_files_and_directories
    - ripgrep_search
    - run_terminal_command
    - post_slack_message

slack:
  channel: "#analytics-eng"

"""
doc_backfiller.py
-----------------
Trigger script for the `doc-backfiller` DinoAI agent.

Collects changed dbt™ model and schema files from the current PR,
triggers a DinoAI agent session to backfill missing and stale descriptions,
and posts the session ID back to the PR as a comment.

Environment variables (required)
=================================
  PARADIME_API_ENDPOINT  – Paradime API endpoint
  PARADIME_API_KEY       – Paradime API key
  PARADIME_API_SECRET    – Paradime API secret
  GITHUB_EVENT_PATH      – Set automatically by GitHub Actions
  GITHUB_TOKEN           – Set automatically by GitHub Actions
"""

import json
import os
import subprocess
import sys
import urllib.request

from paradime import Paradime

AGENT_NAME = "doc-backfiller"


def _build_client() -> Paradime:
    required = {
        "PARADIME_API_ENDPOINT": os.environ.get("PARADIME_API_ENDPOINT"),
        "PARADIME_API_KEY":      os.environ.get("PARADIME_API_KEY"),
        "PARADIME_API_SECRET":   os.environ.get("PARADIME_API_SECRET"),
    }
    missing = [k for k, v in required.items() if not v]
    if missing:
        print(f"ERROR: Missing env vars: {', '.join(missing)}", file=sys.stderr)
        raise SystemExit(1)
    return Paradime(
        api_endpoint=required["PARADIME_API_ENDPOINT"],
        api_key=required["PARADIME_API_KEY"],
        api_secret=required["PARADIME_API_SECRET"],
    )


def main() -> None:
    paradime = _build_client()

    # 1. Read the PR event payload
    with open(os.environ["GITHUB_EVENT_PATH"]) as f:
        event = json.load(f)

    pr           = event["pull_request"]
    pr_number    = pr["number"]
    pr_title     = pr["title"]
    pr_url       = pr["html_url"]
    branch_name  = pr["head"]["ref"]
    base_sha     = pr["base"]["sha"]
    head_sha     = pr["head"]["sha"]

    # 2. Collect changed .sql and .yml files from the diff
    changed = subprocess.check_output(
        ["git", "diff", "--name-only", f"{base_sha}...{head_sha}"]
    ).decode().splitlines()

    dbt_files = [
        f for f in changed
        if f.endswith(".sql") or f.endswith(".yml") or f.endswith(".yaml")
    ]

    if not dbt_files:
        print("No dbt™ model or schema files changed. Skipping doc backfill.")
        raise SystemExit(0)

    # 3. Build the trigger message
    files_block = "\n".join(f"  - {f}" for f in dbt_files)

    sql_files  = [f for f in dbt_files if f.endswith(".sql")]
    yaml_files = [f for f in dbt_files if f.endswith((".yml", ".yaml"))]

    message = f"""Backfill missing and stale dbt™ model documentation for PR #{pr_number}.

PR Title: {pr_title}
PR URL:   {pr_url}
Branch:   {branch_name}

Changed dbt™ files ({len(dbt_files)} total):
  SQL models  ({len(sql_files)}):
{chr(10).join(f"    - {f}" for f in sql_files) or "    (none)"}

  Schema YAML ({len(yaml_files)}):
{chr(10).join(f"    - {f}" for f in yaml_files) or "    (none)"}

For each changed SQL model:
1. Find its schema YAML and check for missing model-level descriptions.
2. Compare the final SELECT columns against the YAML column list — find
   missing columns, stale columns (in YAML but not in SQL), and columns
   whose descriptions may be outdated after recent SQL changes.
3. Draft all missing descriptions. Write `TODO: confirm with owner` when
   the business purpose is not clear from the SQL. Flag stale entries
   with # STALE comments rather than deleting them.
4. Write the updated YAML files, commit to branch `{branch_name}`, and
   push. Skip the commit if nothing needed updating.
5. Post a summary to #analytics-eng with counts of what was added,
   flagged, or left for review.
"""

    # 4. Trigger the agent and wait for completion
    trigger    = paradime.dinoai_agents.trigger_run(
        agent=AGENT_NAME,
        message=message,
    )
    session_id = trigger.agent_session_id
    print(f"Started doc backfill session: {session_id}")

    # 5. Post a "started" comment to the PR immediately
    gh_token = os.environ.get("GITHUB_TOKEN")
    repo     = os.environ.get("GITHUB_REPOSITORY", "")

    def _post_pr_comment(body: str) -> None:
        if not gh_token:
            return
        req = urllib.request.Request(
            f"https://api.github.com/repos/{repo}/issues/{pr_number}/comments",
            data=json.dumps({"body": body}).encode(),
            headers={
                "Authorization": f"Bearer {gh_token}",
                "Accept":        "application/vnd.github+json",
            },
            method="POST",
        )
        urllib.request.urlopen(req).read()

    _post_pr_comment(
        f"📝 **DinoAI doc backfiller started** — session `{session_id}`.\n"
        f"Checking for missing and stale descriptions across {len(sql_files)} model(s).\n"
        f"Any changes will be committed to `{branch_name}` shortly."
    )

    # 6. Poll until the agent completes
    import time
    from paradime.apis.dinoai_agents.types import DinoaiAgentRunStatus

    TIMEOUT       = 1800   # 30 minutes
    POLL_INTERVAL = 15
    start         = time.time()

    while True:
        run = paradime.dinoai_agents.get_run(agent_session_id=session_id)

        if run.status == DinoaiAgentRunStatus.COMPLETED:
            print(f"[doc-backfiller] ✅  Session {session_id} completed.")
            break

        if run.status == DinoaiAgentRunStatus.FAILED:
            last_msg = run.messages[-1].content if run.messages else "no output"
            _post_pr_comment(
                f"❌ **DinoAI doc backfiller failed** — session `{session_id}`.\n"
                f"Last message: {last_msg}"
            )
            raise SystemExit(f"Agent session failed: {last_msg}")

        elapsed = time.time() - start
        if elapsed > TIMEOUT:
            _post_pr_comment(
                f"⏱ **DinoAI doc backfiller timed out** — session `{session_id}`.\n"
                f"The agent did not complete within {TIMEOUT // 60} minutes."
            )
            raise SystemExit(f"Timed out after {TIMEOUT}s")

        print(f"[doc-backfiller]   {run.status.value} ({int(elapsed)}s) … retrying in {POLL_INTERVAL}s")
        time.sleep(POLL_INTERVAL)

    # 7. Post the agent's final output back to the PR as a completion comment
    final_output = run.messages[-1].content if run.messages else "(no output returned)"

    _post_pr_comment(
        f"📝 **DinoAI doc backfiller — complete**\n\n"
        f"{final_output}\n\n"
        f"---\n"
        f"*Session `{session_id}` · Check `#analytics-eng` for the full summary.*"
    )

    print("[doc-backfiller] ✅  Done.")


if __name__ == "__main__":
    main()

name: DinoAI dbt™ doc backfiller

on:
  pull_request:
    types: [opened, synchronize, ready_for_review]
    paths:
      - "models/**/*.sql"
      - "models/**/*.yml"
      - "models/**/*.yaml"

permissions:
  pull-requests: write
  contents: write       # required so the agent can push commits to the PR branch

jobs:
  backfill-docs:
    runs-on: ubuntu-latest
    timeout-minutes: 30
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0        # need full history for git diff
          ref: ${{ github.head_ref }}   # check out the PR branch so the agent can push to it

      - uses: actions/setup-python@v5
        with:
          python-version: "3.11"

      - name: Install Paradime SDK
        run: pip install paradime-io

      - name: Configure git for agent commits
        run: |
          git config user.name  "DinoAI Doc Backfiller"
          git config user.email "dinoai-docs@noreply.github.com"

      - name: Run doc backfiller
        env:
          PARADIME_API_ENDPOINT: ${{ secrets.PARADIME_API_ENDPOINT }}
          PARADIME_API_KEY:      ${{ secrets.PARADIME_API_KEY }}
          PARADIME_API_SECRET:   ${{ secrets.PARADIME_API_SECRET }}
          GITHUB_TOKEN:          ${{ secrets.GITHUB_TOKEN }}
        run: python scripts/doc_backfiller.py