Build an AI API Contract Breaking Change Detector with Claude API

pip install anthropic pyyaml deepdiff

import yaml
import anthropic
from deepdiff import DeepDiff
 
client = anthropic.Anthropic()
 
 
def load_openapi_spec(path: str) -> dict:
    with open(path) as f:
        return yaml.safe_load(f)
 
 
def get_raw_diff(old_spec: dict, new_spec: dict) -> dict:
    """Get the structural diff — this is the raw material, not the final answer."""
    diff = DeepDiff(old_spec, new_spec, ignore_order=True)
    return diff.to_dict()

CLASSIFY_PROMPT = """Analyze this OpenAPI schema diff and classify each
change by actual impact on existing API consumers.
 
Raw schema diff:
{raw_diff}
 
Old spec (relevant excerpt): {old_spec_excerpt}
New spec (relevant excerpt): {new_spec_excerpt}
 
Classify each individual change as:
- BREAKING: will cause existing client code to fail (removed field,
  removed endpoint, type change on existing field, new required field
  with no default, narrowed enum values, changed error response codes)
- SAFE: backward compatible (new optional field, new endpoint, widened
  enum values, new optional query parameter, relaxed validation)
- NEEDS_REVIEW: ambiguous impact depending on how strictly consumers
  validate responses (e.g. reordered fields in a response usually safe,
  but a consumer doing strict schema validation could break)
 
For each BREAKING change, explain specifically which client code pattern
would fail and why.
 
Respond with ONLY valid JSON:
{{"changes": [
  {{"path": "...", "classification": "BREAKING"|"SAFE"|"NEEDS_REVIEW",
    "explanation": "..."}}
], "overall_verdict": "safe_to_release" | "breaking_changes_present"}}"""
 
 
def classify_changes(raw_diff: dict, old_spec: dict, new_spec: dict) -> dict:
    response = client.messages.create(
        model="claude-sonnet-5",
        max_tokens=2500,
        messages=[{
            "role": "user",
            "content": CLASSIFY_PROMPT.format(
                raw_diff=raw_diff,
                old_spec_excerpt=str(old_spec)[:2000],
                new_spec_excerpt=str(new_spec)[:2000],
            )
        }]
    )
    text = response.content[0].text.strip()
    if text.startswith("```"):
        text = text.split("```")[1].replace("json", "", 1).strip()
    import json
    return json.loads(text)

# .github/workflows/api-contract-check.yml
name: API Contract Check
on:
  pull_request:
    paths: ["openapi.yaml"]
 
jobs:
  contract-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - run: git show origin/main:openapi.yaml > old-spec.yaml
      - run: python contract_check.py --old old-spec.yaml --new openapi.yaml
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
      # Script exits non-zero if overall_verdict is "breaking_changes_present"
      # AND the PR is targeting a version that shouldn't have breaking changes