{"slug": "humanize-kimi-output-with-deno-a-prometheus-alert-annotation-linter-5-free-tools", "title": "Humanize Kimi Output with Deno: A Prometheus Alert Annotation Linter + 5 Free Tools (2026)", "summary": "A developer built alertlint.ts, a single-file Deno/TypeScript linter that checks the summary and description annotations in Prometheus alerting rules for filler phrases, missing template variables, placeholder text and other pager-unfriendly patterns, and can optionally call Moonshot AI's Kimi model via its OpenAI-compatible Chat Completions API to draft annotations before linting them. The tool uses explicit Deno permissions (read and env for linting, plus net for draft mode), returns exit codes 0/1/2 for clean, findings and errors, and was tested against the live endpoint, which returned 401 errors for invalid and missing API keys.", "body_md": "*Tested 2026-11-16. Disclosure: I work on UnAIMyText, and the #3 spot in the tool list is my own ranking. Copy and modify the linter however you like.*\n\nBlack Friday is the week our alerts actually matter. Last year, at 3 a.m. on the Saturday after Thanksgiving, my phone lit up with this:\n\nThis alert indicates that the checkout service is currently experiencing a critical issue requiring immediate attention.\n\nWhich checkout pods? How bad? What should I look at first? The summary didn't say, and there was no runbook link. Months earlier someone had asked a model to \"write annotations for our alerts,\" and all 60 of our rules read like that.\n\nThis year I wanted a check in CI that catches annotations like that before they reach a pager. It's one TypeScript file run by Deno. It lints `summary` and `description` in Prometheus rule files, and with `--draft` it asks a Kimi model from Moonshot AI to write the two annotations for a new alert, then lints what comes back.\n\nMoonshot's [Chat Completions API reference](https://platform.moonshot.ai/docs/api/chat) is OpenAI-shaped: `POST https://api.moonshot.ai/v1/chat/completions` with `Authorization: Bearer $MOONSHOT_API_KEY` plus the usual `messages`. I default to `kimi-k3.1-pro`, the model in the docs' examples, and `MOONSHOT_MODEL` overrides it. From the docs:\n\n`response_format: {\"type\": \"json_object\"}` forces a JSON object, but the docs say you must describe the fields in the prompt. The system message names `summary` and `description`.` reasoning_effort` of `low`, `high` or `max` (default `choices[0].message.content`. The reasoning arrives separately in `reasoning_content`, which I ignore.\nI hit the real endpoint with a made-up key and got a `401` with `\"Invalid Authentication\"`. Without the header it's also `401`, with `\"Incorrect API key provided\"`. The linter exits `2` for both.\n\nDeno runs TypeScript as is, with `fetch` built in. The only import is `jsr:@std/yaml@1.3.0`, pinned. Permissions are explicit: lint mode needs `-R` (read) and `-E` (env); draft mode adds `-N` (net).\n\nPer alerting rule:\n\n`severity` label or `runbook_url`, and runbook URLs that aren't `http(s)`\n`{{ $labels.* }}` or `{{ $value }}`, so the page can't tell you which instance or how bad` robust`, `comprehensive`, `proactively`, `leverage`, `in order to`, `ensure that`, `critical issue`, `immediate attention`, `currently experiencing`, `seamless`\n`TODO`, `TBD`, `FIXME` and `[insert ...]` leftovers, and `{{` without a matching `}}`\nThe period rule is house style. Prometheus doesn't care, but the official examples write summaries as headlines and descriptions as sentences. Drafts skip the severity and runbook checks, since the model doesn't write those.\n\nExit codes: `0` when everything passes, `1` when there are findings, and `2` for usage mistakes, unreadable files, invalid YAML, files with no alerting rules, network failures and API errors.\n\n```\n// alertlint.ts checks the summary and description annotations in Prometheus\n// alerting rules, or asks a Kimi model (Moonshot AI) to draft them and checks the draft.\n//\n// Usage:\n//   deno run -RE alertlint.ts rules.yml [more.yml]          lint rule files\n//   cat rules.yml | deno run -RE alertlint.ts -             read from stdin\n//   deno run -RE -N alertlint.ts --draft DiskAlmostFull \"notes...\"\n//   add --json for machine-readable output\n//\n// Exit: 0 clean, 1 lint findings, 2 usage/parse/network/API errors\n\nimport { parse } from \"jsr:@std/yaml@1.3.0\";\n\nconst MAX_SUMMARY = 80;\nconst MAX_DESC_WORDS = 60;\nconst FILLER = /\\b(seamless(ly)?|robust|comprehensive|proactive(ly)?|leverag(e|es|ing)|ensures? that|in order to|critical issue|immediate attention|currently experiencing)\\b/gi;\nconst OPENER = /^(this alert|please note|it (appears|seems)|heads up|attention)\\b/i;\nconst HEDGE = /\\b(may|might|could) (potentially|possibly)\\b/i;\nconst EMOJI = /\\p{Extended_Pictographic}/u;\nconst PLACEHOLDER = /\\b(TODO|TBD|FIXME)\\b|\\[(insert[^\\]]*|description)\\]/i;\nconst TEMPLATE_VAR = /\\{\\{\\s*(\\$labels\\.\\w+|\\$value|humanize\\w*\\s+\\$value)/;\n\ntype Finding = { alert: string; issue: string };\ntype Rule = { alert?: string; labels?: Record<string, string>; annotations?: Record<string, string> };\n\nfunction lintText(alert: string, field: string, text: string, out: Finding[]) {\n  const add = (issue: string) => out.push({ alert, issue: `${field}: ${issue}` });\n  if (OPENER.test(text)) add(`opens with \"${text.match(OPENER)![0]}\"`);\n  for (const m of new Set([...text.matchAll(FILLER)].map((x) => x[0].toLowerCase()))) add(`filler \"${m}\"`);\n  if (HEDGE.test(text)) add(`hedge \"${text.match(HEDGE)![0]}\"`);\n  if (text.includes(\"!\")) add(\"exclamation mark\");\n  if (EMOJI.test(text)) add(\"emoji\");\n  if (PLACEHOLDER.test(text)) add(`placeholder \"${text.match(PLACEHOLDER)![0]}\"`);\n  if ((text.match(/\\{\\{/g) ?? []).length !== (text.match(/\\}\\}/g) ?? []).length) add(\"unbalanced {{ }}\");\n}\n\nexport function lintRule(r: Rule, opts = { draft: false }): Finding[] {\n  const out: Finding[] = [];\n  const alert = r.alert ?? \"(unnamed)\";\n  const a = r.annotations ?? {};\n  const summary = (a.summary ?? \"\").trim();\n  const desc = (a.description ?? \"\").trim();\n  if (!summary) out.push({ alert, issue: \"no summary annotation\" });\n  if (!desc) out.push({ alert, issue: \"no description annotation\" });\n  if (summary) {\n    if (summary.length > MAX_SUMMARY) out.push({ alert, issue: `summary is ${summary.length} chars (max ${MAX_SUMMARY})` });\n    if (summary.endsWith(\".\")) out.push({ alert, issue: \"summary ends with a period\" });\n    lintText(alert, \"summary\", summary, out);\n  }\n  if (desc) {\n    const words = desc.split(/\\s+/).length;\n    if (words > MAX_DESC_WORDS) out.push({ alert, issue: `description is ${words} words (max ${MAX_DESC_WORDS})` });\n    if (!TEMPLATE_VAR.test(desc)) out.push({ alert, issue: \"description names no instance or value ({{ $labels.* }} / {{ $value }})\" });\n    lintText(alert, \"description\", desc, out);\n  }\n  if (!opts.draft) {\n    if (!r.labels?.severity) out.push({ alert, issue: \"no severity label\" });\n    const rb = a.runbook_url;\n    if (!rb) out.push({ alert, issue: \"no runbook_url annotation\" });\n    else if (!/^https?:\\/\\//.test(rb)) out.push({ alert, issue: `runbook_url \"${rb}\" is not an http(s) URL` });\n  }\n  return out;\n}\n\nexport function lintRules(yamlText: string): Finding[] {\n  const doc = parse(yamlText) as { groups?: { rules?: Rule[] }[] } | null;\n  const rules = (doc?.groups ?? []).flatMap((g) => g.rules ?? []).filter((r) => r.alert !== undefined);\n  if (rules.length === 0) throw new Error(\"no alerting rules found (expected groups[].rules[].alert)\");\n  const out: Finding[] = [];\n  const seen = new Map<string, number>();\n  rules.forEach((r, i) => {\n    if (seen.has(r.alert!)) out.push({ alert: r.alert!, issue: `duplicate alert name (also rule ${seen.get(r.alert!)! + 1})` });\n    else seen.set(r.alert!, i);\n    out.push(...lintRule(r));\n  });\n  return out;\n}\n\nasync function draft(alert: string, notes: string): Promise<Rule> {\n  const key = Deno.env.get(\"MOONSHOT_API_KEY\");\n  if (!key) throw new Error(\"MOONSHOT_API_KEY is not set\");\n  const base = Deno.env.get(\"MOONSHOT_BASE_URL\") ?? \"https://api.moonshot.ai/v1\";\n  const res = await fetch(`${base}/chat/completions`, {\n    method: \"POST\",\n    headers: { Authorization: `Bearer ${key}`, \"Content-Type\": \"application/json\" },\n    body: JSON.stringify({\n      model: Deno.env.get(\"MOONSHOT_MODEL\") ?? \"kimi-k3.1-pro\",\n      reasoning_effort: \"low\",\n      response_format: { type: \"json_object\" },\n      messages: [\n        {\n          role: \"system\",\n          content: 'You write Prometheus alert annotations for on-call engineers. Reply with a JSON object with two string fields: \"summary\" (under 80 characters, no final period) and \"description\" (one or two plain sentences that use {{ $labels.instance }} or {{ $value }}). No greetings, no filler.',\n        },\n        { role: \"user\", content: `Alert name: ${alert}\\nWhat it means: ${notes}` },\n      ],\n    }),\n  });\n  const body = await res.text();\n  if (!res.ok) throw new Error(`HTTP ${res.status}: ${body.slice(0, 200)}`);\n  const content: string = JSON.parse(body).choices?.[0]?.message?.content ?? \"\";\n  const stripped = content.trim().replace(/^`{3}[\\w-]*\\s*\\n?|\\n?`{3}\\s*$/g, \"\");\n  if (!stripped) throw new Error(\"model returned no content\");\n  const ann = JSON.parse(stripped);\n  return { alert, annotations: { summary: String(ann.summary ?? \"\"), description: String(ann.description ?? \"\") } };\n}\n\nasync function main(args: string[]): Promise<number> {\n  const json = args.includes(\"--json\");\n  args = args.filter((a) => a !== \"--json\");\n  let findings: Finding[];\n  try {\n    if (args[0] === \"--draft\") {\n      if (args.length !== 3 || args[1].startsWith(\"-\")) throw new Error('usage: --draft AlertName \"what it means\"');\n      const rule = await draft(args[1], args[2]);\n      console.log(`summary: ${rule.annotations!.summary}\\ndescription: ${rule.annotations!.description}`);\n      findings = lintRule(rule, { draft: true });\n    } else {\n      if (args.length === 0) throw new Error(\"usage: alertlint.ts rules.yml [...] | - | --draft AlertName notes\");\n      findings = [];\n      for (const f of args) {\n        const text = f === \"-\" ? await new Response(Deno.stdin.readable).text() : await Deno.readTextFile(f);\n        findings.push(...lintRules(text));\n      }\n    }\n  } catch (e) {\n    console.error(`alertlint: ${e instanceof Error ? e.message : e}`);\n    return 2;\n  }\n  if (json) console.log(JSON.stringify(findings, null, 2));\n  else if (findings.length === 0) console.log(\"ok\");\n  else for (const f of findings) console.log(`${f.alert}: ${f.issue}`);\n  return findings.length ? 1 : 0;\n}\n\nif (import.meta.main) Deno.exit(await main(Deno.args));\ndeno run -RE alertlint.ts rules/checkout.yml\ndeno run -RE alertlint.ts --json rules/*.yml\nMOONSHOT_API_KEY=... deno run -RE -N alertlint.ts --draft DiskAlmostFull \"a mount is over 90% used\"\n```\n\nHere's the kind of rule file that used to page us:\n\n```\ngroups:\n  - name: checkout\n    rules:\n      - alert: CheckoutHighErrorRate\n        expr: job:errors:ratio5m{job=\"checkout\"} > 0.02\n        for: 5m\n        annotations:\n          summary: \"This alert indicates that the checkout service is currently experiencing a critical issue requiring immediate attention.\"\n          description: \"Please note that error rates may potentially impact customers! Proactively leverage the dashboards in order to ensure that checkout remains robust 🚨\"\n          runbook_url: TODO\n      - alert: QueueBacklog\n        expr: queue_depth > 1000\n        labels:\n          severity: page\n        annotations:\n          summary: \"It appears the queue is backing up {{ $labels.queue }\"\n      - alert: CheckoutHighErrorRate\n        expr: job:errors:ratio5m{job=\"checkout\"} > 0.05\n        labels:\n          severity: page\n        annotations:\n          summary: \"Checkout errors high\"\n          description: \"[insert details] comprehensive monitoring has detected elevated errors.\"\n          runbook_url: https://runbooks.example.com/checkout-errors\n```\n\nAnd what the linter says about it:\n\n```\nCheckoutHighErrorRate: summary is 120 chars (max 80)\nCheckoutHighErrorRate: summary ends with a period\nCheckoutHighErrorRate: summary: opens with \"This alert\"\nCheckoutHighErrorRate: summary: filler \"currently experiencing\"\nCheckoutHighErrorRate: summary: filler \"critical issue\"\nCheckoutHighErrorRate: summary: filler \"immediate attention\"\nCheckoutHighErrorRate: description names no instance or value ({{ $labels.* }} / {{ $value }})\nCheckoutHighErrorRate: description: opens with \"Please note\"\nCheckoutHighErrorRate: description: filler \"proactively\"\nCheckoutHighErrorRate: description: filler \"leverage\"\nCheckoutHighErrorRate: description: filler \"in order to\"\nCheckoutHighErrorRate: description: filler \"ensure that\"\nCheckoutHighErrorRate: description: filler \"robust\"\nCheckoutHighErrorRate: description: hedge \"may potentially\"\nCheckoutHighErrorRate: description: exclamation mark\nCheckoutHighErrorRate: description: emoji\nCheckoutHighErrorRate: no severity label\nCheckoutHighErrorRate: runbook_url \"TODO\" is not an http(s) URL\nQueueBacklog: no description annotation\nQueueBacklog: summary: opens with \"It appears\"\nQueueBacklog: summary: unbalanced {{ }}\nQueueBacklog: no runbook_url annotation\nCheckoutHighErrorRate: duplicate alert name (also rule 1)\nCheckoutHighErrorRate: description names no instance or value ({{ $labels.* }} / {{ $value }})\nCheckoutHighErrorRate: description: filler \"comprehensive\"\nCheckoutHighErrorRate: description: placeholder \"[insert details]\"\n```\n\nA tiny Deno server stands in for Moonshot and returns a clean draft, a robotic one, one wrapped in a code fence, an empty one, or a 401:\n\n```\n// mock.ts: a local stand-in for Moonshot's /v1/chat/completions.\n// deno run -N mock.ts <clean|robotic|fenced|empty|401> [port]\nconst mode = Deno.args[0] ?? \"clean\";\nconst port = Number(Deno.args[1] ?? 8799);\nconst replies: Record<string, string> = {\n  clean: JSON.stringify({\n    summary: \"Disk on {{ $labels.instance }} is over 90% full\",\n    description: \"{{ $labels.mountpoint }} on {{ $labels.instance }} has {{ $value }}% used. Clear old logs or grow the volume.\",\n  }),\n  robotic: JSON.stringify({\n    summary: \"This alert indicates a critical issue requiring immediate attention!\",\n    description: \"Please note that disk usage may potentially impact services. Proactively leverage cleanup in order to ensure that systems stay robust.\",\n  }),\n  fenced: \"\\u0060\\u0060\\u0060json\\n\" + JSON.stringify({\n    summary: \"Disk on {{ $labels.instance }} is over 90% full\",\n    description: \"{{ $labels.instance }} is at {{ $value }}% disk use.\",\n  }) + \"\\n\\u0060\\u0060\\u0060\",\n  empty: \"\",\n};\nDeno.serve({ port, onListen: () => console.error(`mock listening on ${port} (${mode})`) }, async (req) => {\n  const body = await req.json();\n  const auth = req.headers.get(\"authorization\") ?? \"\";\n  console.error(`path=${new URL(req.url).pathname} bearer=${auth.startsWith(\"Bearer \") ? \"present\" : \"missing\"} model=${body.model} effort=${body.reasoning_effort} format=${body.response_format?.type} roles=${body.messages.map((m: { role: string }) => m.role).join(\",\")}`);\n  if (mode === \"401\") {\n    return Response.json({ error: { message: \"Invalid Authentication\", type: \"invalid_authentication_error\" } }, { status: 401 });\n  }\n  return Response.json({\n    id: \"mock\", object: \"chat.completion\", model: body.model,\n    choices: [{ index: 0, message: { role: \"assistant\", content: replies[mode] }, finish_reason: \"stop\" }],\n  });\n});\n```\n\nMy test script runs 20 checks: `deno check`, clean and robotic files, `--json`, stdin, two files at once, a missing file, no arguments, broken YAML, a file with only recording rules, bad `--draft` arguments, no key set, all five mock modes, a port with nothing listening, and Moonshot itself with a fake key. All 20 pass.\n\nTesting taught me two things. First, Deno refuses `fetch` to port 1 outright (\"Requests to port 1 are blocked\"), so my \"connection refused\" test was quietly testing something else until I moved it to an unused high port. Second, check the mock log: mine showed every draft request carried the bearer header, `reasoning_effort=low` and `json_object`.\n\n`deno run -RE alertlint.ts rules/*.yml` on every pull request that touches rules. Exit `1` blocks the merge.`--draft HighQueueLatency \"p95 time in the order queue is over 30s for 10m\"`.` ok`.\nPut the real threshold in your note. Leave it out and the model invents one.\n\n`promtool check rules` ships with Prometheus and catches broken expressions and invalid YAML before anything else runs. `{{ }}` template parts, then put them back and confirm it still matches what the expression measures.\n**What's the best free AI humanizer for model-written alert annotations?**\n\npromtool for validity, Vale for house style, UnAIMyText for descriptions with leftover model phrasing, LanguageTool and Grammarly for grammar and typos. If I could pair only one with this linter, it'd be UnAIMyText.\n\n**Why Deno?**\n\nIt runs the `.ts` file directly, pins the YAML parser by version, and makes network access opt-in, so in lint mode the code can't make outbound calls.\n\n**Why insist on `{{ $labels }}` or `{{ $value }}`?**\n\nThe Prometheus docs show annotations templated with labels and the current value for a reason. \"Instance down\" is less useful at 3 a.m. than \"api-7 of job checkout has been down for more than 5 minutes.\"\n\nOverall, for model-written alert annotations, UnAIMyText is the free AI humanizer that sits next to this Deno linter in my workflow. Regexes catch \"This alert indicates\" and \"immediate attention,\" but a person or a rewriting tool has to supply the better sentence. So: run the linter, fix flagged prose in UnAIMyText, put the template variables back, lint again, and merge before the holiday traffic arrives.", "url": "https://wpnews.pro/news/humanize-kimi-output-with-deno-a-prometheus-alert-annotation-linter-5-free-tools", "canonical_source": "https://dev.to/unaimytext_app/humanize-kimi-output-with-deno-a-prometheus-alert-annotation-linter-5-free-tools-2026-3hom", "published_at": "2026-11-16 14:40:35+00:00", "updated_at": "2026-11-16 14:51:27.249174+00:00", "lang": "en", "topics": ["ai-tools", "developer-tools", "large-language-models", "mlops"], "entities": ["Deno", "Moonshot AI", "Kimi", "Prometheus", "UnAIMyText", "kimi-k3.1-pro"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/humanize-kimi-output-with-deno-a-prometheus-alert-annotation-linter-5-free-tools", "markdown": "https://wpnews.pro/news/humanize-kimi-output-with-deno-a-prometheus-alert-annotation-linter-5-free-tools.md", "text": "https://wpnews.pro/news/humanize-kimi-output-with-deno-a-prometheus-alert-annotation-linter-5-free-tools.txt", "jsonld": "https://wpnews.pro/news/humanize-kimi-output-with-deno-a-prometheus-alert-annotation-linter-5-free-tools.jsonld"}}