Humanize Cerebras Output in Python: An API Deprecation Notice Linter + 5 Free Tools (2026)

#!/usr/bin/env python3
"""Deprecation notice linter for API changes drafted with Cerebras.

Usage:
  python3 deprecation_lint.py --draft "raw notes about the change"
  python3 deprecation_lint.py notice.md
  python3 deprecation_lint.py -          # read stdin
  add --json for machine-readable output
Exit: 0 clean, 1 lint failures, 2 usage/network/API errors
"""
import json
import os
import re
import sys
import urllib.error
import urllib.request

OPENERS = re.compile(r"^(sure|certainly|of course|absolutely|here(?:'s| is))\b", re.I)
SIGNOFF = re.compile(r"(hope this helps|let me know if|happy to help|as an ai)", re.I)
FLUFF = re.compile(r"\b(exciting|thrilled|seamless|journey|leverage|empower|"
                   r"game[- ]changing|revolutionary|delighted)\b", re.I)
SOFTENERS = re.compile(r"\b(may|might|possibly|perhaps|eventually|at some point|soon)\b", re.I)
DATE = re.compile(r"\b(\d{4}-\d{2}-\d{2}|(Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)[a-z]*\.? \d{1,2},? \d{4})\b")
ENDPOINT = re.compile(r"`?(GET|POST|PUT|PATCH|DELETE)\s+/\S+|`/[\w/{}.-]+`")
REPLACEMENT = re.compile(r"\b(use|switch to|migrate to|replace(?:d)? (?:with|by))\b", re.I)
PLACEHOLDER = re.compile(r"\b(TODO|TBD|XXX|lorem ipsum)\b|\[(date|endpoint|link)\]", re.I)
MAX_WORDS = 180


def lint(text):
    issues = []
    body = text.strip()
    if not body:
        return ["empty notice"]
    first = body.splitlines()[0]
    if OPENERS.match(first):
        issues.append("chatbot opener on first line")
    if SIGNOFF.search(body):
        issues.append("chatbot sign-off")
    if FLUFF.search(body):
        issues.append("launch-announcement fluff in a deprecation notice")
    soft = len(SOFTENERS.findall(body))
    if soft > 1:
        issues.append(f"vague timing words ({soft}); give a date instead")
    if not DATE.search(body):
        issues.append("no sunset date (YYYY-MM-DD or 'Mon D, YYYY')")
    if not ENDPOINT.search(body):
        issues.append("no endpoint named (e.g. GET /v1/orders)")
    if not REPLACEMENT.search(body):
        issues.append("no replacement or migration path")
    words = len(body.split())
    if words > MAX_WORDS:
        issues.append(f"too long ({words} words; cap {MAX_WORDS})")
    if PLACEHOLDER.search(body):
        issues.append("placeholder left in")
    return issues


def draft(notes):
    key = os.environ.get("CEREBRAS_API_KEY")
    if not key:
        raise RuntimeError("CEREBRAS_API_KEY not set")
    base = os.environ.get("CEREBRAS_BASE_URL", "https://api.cerebras.ai")
    model = os.environ.get("CEREBRAS_MODEL", "qwen-3.8-27b")
    payload = {
        "model": model,
        "reasoning_effort": "none",
        "temperature": 0.2,
        "messages": [
            {"role": "system", "content": (
                "You write API deprecation notices for developers. Plain text, under "
                "150 words. Name the endpoint, the sunset date, and the replacement. "
                "No greeting, no sign-off, no marketing words.")},
            {"role": "user", "content": notes},
        ],
    }
    req = urllib.request.Request(
        base.rstrip("/") + "/v1/chat/completions",
        data=json.dumps(payload).encode("utf-8"),
        headers={"Authorization": f"Bearer {key}", "Content-Type": "application/json",
                 "User-Agent": "deprecation-lint/1.0"},
        method="POST",
    )
    try:
        with urllib.request.urlopen(req, timeout=30) as resp:
            data = json.loads(resp.read().decode("utf-8"))
    except urllib.error.HTTPError as e:
        raise RuntimeError(f"HTTP {e.code}: {e.read().decode('utf-8', 'replace')[:200]}")
    except urllib.error.URLError as e:
        raise RuntimeError(f"network error: {e.reason}")
    try:
        content = data["choices"][0]["message"]["content"]
    except (KeyError, IndexError, TypeError):
        raise RuntimeError("unexpected response shape")
    if not content:
        raise RuntimeError("empty content in response")
    return content


def main(argv):
    as_json = "--json" in argv
    args = [a for a in argv if a != "--json"]
    if not args:
        print(__doc__.strip(), file=sys.stderr)
        return 2
    try:
        if args[0] == "--draft":
            if len(args) < 2:
                print("--draft needs notes", file=sys.stderr)
                return 2
            text = draft(" ".join(args[1:]))
        elif args[0] == "-":
            text = sys.stdin.read()
        else:
            with open(args[0], encoding="utf-8") as fh:
                text = fh.read()
    except FileNotFoundError:
        print(f"missing file: {args[0]}", file=sys.stderr)
        return 2
    except RuntimeError as e:
        print(str(e), file=sys.stderr)
        return 2
    issues = lint(text)
    if as_json:
        print(json.dumps({"ok": not issues, "issues": issues}))
    elif issues:
        for i in issues:
            print(f"- {i}")
    else:
        print("ok")
    return 0 if not issues else 1


if __name__ == "__main__":
    sys.exit(main(sys.argv[1:]))

#!/usr/bin/env python3
"""Tiny stand-in for POST /v1/chat/completions. Usage: python3 mock_cerebras.py [clean|robotic|empty|401] [port]"""
import json
import sys
from http.server import BaseHTTPRequestHandler, HTTPServer

MODE = sys.argv[1] if len(sys.argv) > 1 else "clean"
PORT = int(sys.argv[2]) if len(sys.argv) > 2 else 8797
BODIES = {
    "clean": ("GET /v1/invoices/{id}/pdf is deprecated and stops working on 2027-03-01. "
              "Use GET /v2/invoices/{id}/document instead; it returns the same PDF plus a "
              "signed URL. Requests to the old path will return 410 Gone after that date."),
    "robotic": ("Sure! Here's your notice.\n\nWe're thrilled to share an exciting update on our "
                "journey. The legacy invoice endpoint may be retired at some point soon, so you "
                "might possibly want to plan ahead.\n\nHope this helps!"),
    "empty": "",
}


class H(BaseHTTPRequestHandler):
    def do_POST(self):
        raw = self.rfile.read(int(self.headers.get("Content-Length", 0)) or 0)
        body = json.loads(raw or b"{}")
        rec = {"path": self.path,
               "bearer": self.headers.get("Authorization", "").startswith("Bearer "),
               "model": body.get("model"), "roles": [m["role"] for m in body.get("messages", [])]}
        sys.stderr.write(json.dumps(rec) + "\n")
        if MODE == "401":
            out, code = {"message": "Wrong API Key", "code": "wrong_api_key"}, 401
        else:
            out = {"id": "chatcmpl-mock", "object": "chat.completion", "model": body.get("model"),
                   "choices": [{"index": 0, "finish_reason": "stop",
                                "message": {"role": "assistant", "content": BODIES.get(MODE, "")}}]}
            code = 200
        data = json.dumps(out).encode()
        self.send_response(code)
        self.send_header("Content-Type", "application/json")
        self.send_header("Content-Length", str(len(data)))
        self.end_headers()
        self.wfile.write(data)

    def log_message(self, *a):
        pass


HTTPServer(("127.0.0.1", PORT), H).serve_forever()

#!/usr/bin/env bash
set -u
pass=0; fail=0
check() { # name expected_exit actual_exit
  if [ "$2" = "$3" ]; then pass=$((pass+1)); echo "PASS $1"; else fail=$((fail+1)); echo "FAIL $1 (want $2 got $3)"; fi
}
L="python3 deprecation_lint.py"
$L samples/robotic.md >/dev/null; check robotic 1 $?
$L samples/clean.md >/dev/null; check clean 0 $?
$L --json samples/long.md | grep -q 'too long'; check long-json 0 $?
$L - < samples/clean.md >/dev/null; check stdin 0 $?
$L nope.md 2>/dev/null; check missing-file 2 $?
$L 2>/dev/null; check no-args 2 $?
env -u CEREBRAS_API_KEY $L --draft x 2>/dev/null; check missing-key 2 $?
for mode in clean robotic empty 401; do
  python3 mock_cerebras.py $mode 8797 2>>mock.log & pid=$!; sleep 0.6
  CEREBRAS_API_KEY=csk-test CEREBRAS_BASE_URL=http://127.0.0.1:8797 $L --draft "retire v1 invoices pdf" >/dev/null 2>&1; rc=$?
  kill $pid; wait $pid 2>/dev/null
  case $mode in clean) want=0;; robotic) want=1;; *) want=2;; esac
  check mock-$mode $want $rc
done
CEREBRAS_API_KEY=csk-test CEREBRAS_BASE_URL=http://127.0.0.1:1 $L --draft x 2>/dev/null; check conn-refused 2 $?
CEREBRAS_API_KEY=csk-fake $L --draft "x" 2>real.err; check real-api-fake-key 2 $?
echo "$pass passed, $fail failed"

`GET /v1/orders` is deprecated. It stops responding on 2027-02-15.

Switch to `GET /v2/orders`, which returns the same fields plus `fulfillment_status`. Pagination moves from `page` to a `cursor` parameter; the migration guide has a before-and-after request.

Until the sunset date, v1 responses carry a `Deprecation` header. After it, v1 returns 410 Gone.