lap-score 0.3.0__py3-none-any.whl

lap/README.md

@@ -0,0 +1,120 @@
+# lap — token-efficiency scorer for agent-facing APIs
+
+`lap` is the open, neutral, standalone toolkit (no pet-zoo dependency) that measures
+how many **tokens** an API's definitions cost an LLM. It answers: *is my agent-API
+menu efficient, and by how much could it shrink?* — an open, reproducible number to set
+beside the fast-growing MCP/OpenAPI tooling (see [`../docs/LANDSCAPE.md`](../docs/LANDSCAPE.md)
+for the neighbors LAP builds on and credits).
+
+## Install
+
+```bash
+pip install -e .                  # from the repo root (or: pip install lap-score once published)
+pip install -e ".[mcp]"           # + real-MCP baseline (fastmcp)
+pip install -e ".[faithful]"      # + faithful Anthropic count_tokens
+```
+
+Core deps are just `httpx` + `tiktoken` + `pyyaml`; `fastmcp` and `anthropic` are optional extras.
+Robust to real specs: `allOf`/`oneOf`/`anyOf`, `$ref` in params/requestBodies/responses,
+path-item-level parameters, OpenAPI 3.1 `type` lists, external `$ref`s (left intact), YAML input,
+**Swagger/OpenAPI 2.0** (response `schema`, `in: body` params, type-on-parameter, `#/definitions`),
+and non-JSON media types (`*+json`, form, XML). Verified crash-free + non-degenerate across 175+
+real APIs.guru specs — re-run with [`../experiments/fuzz_corpus.py`](../experiments/fuzz_corpus.py).
+
+## Quickstart
+
+```bash
+lap score  https://petstore3.swagger.io/api/v3/openapi.json   # menu (bucket A) token cost
+lap lint   https://petstore3.swagger.io/api/v3/openapi.json   # flag LAP rule violations
+lap score  --mcp-url http://localhost:8080/mcp                # score a live MCP server's tools
+lap score  lap/examples/bookstore.openapi.json
+
+# no install needed, from the repo root:
+python -m lap.score lap/examples/bookstore.openapi.json
+```
+
+Example output:
+
+```
+LAP menu score - Bookstore API
+operations: 6   referenced component schemas: 2
+
+  variant       A tokens  saved vs full  form
+  openapi_full  418       +0%            6 tool(s)
+  compact_sig   205       +51%           manifest text
+  numbered      168       +60%           manifest text
+
+Menu efficiency: compact signatures are +51% vs naive OpenAPI->tools (418 -> 205 tokens).
+```
+
+When `fastmcp` is installed, the score also includes a **real-MCP baseline**
+(`FastMCP.from_openapi`) — what an actual MCP generator emits — plus its
+output-schema-inclusive figure (`--no-mcp` to skip). On a real public API
+(**Swagger Petstore**, 19 ops) the real MCP server costs **2226** menu tokens
+(**3844** with output schemas) vs **415** for compact signatures — an ~81%
+reduction. The toy finding holds in the wild: a real MCP generator is *heavier*
+than the naive baseline.
+
+The score also includes a lazy **`tool_search`** form (the Anthropic Tool Search /
+Cloudflare Code Mode pattern: a fixed 2-tool menu + a name index, schemas loaded on
+demand). Because it doesn't preload schemas, its bucket A is ~flat in the number of
+operations — on a 120-operation API it collapses the menu ~83% vs full schemas,
+beating even compact signatures at scale (Petstore: 1740 → 207, −88%).
+
+- **Faithful counts:** set `ANTHROPIC_API_KEY` (uses the free Anthropic `count_tokens`
+  endpoint; tool defs counted via the real `tools=` parameter). Without it, a GPT-style
+  `tiktoken` approximation — absolute numbers approximate, **relative ordering robust**.
+
+## CI gate
+
+`--json` makes both commands machine-readable; thresholds set the exit code so LAP can fail a build:
+
+```bash
+lap score openapi.json --gate-form compact_sig --max-menu-tokens 800   # exit 1 if the menu is too heavy
+lap lint  openapi.json --fail-on warn                                  # exit 1 on any warning
+lap lint  openapi.json --ignore R2,A1                                  # suppress rules (or a ./.lapignore file)
+```
+
+GitHub Actions:
+
+```yaml
+- run: pip install lap-score          # or: pip install -e .
+- run: lap score api/openapi.json --gate-form compact_sig --max-menu-tokens 800
+- run: lap lint  api/openapi.json --fail-on warn
+```
+
+…or the bundled composite **Action** (one step, no manual install):
+
+```yaml
+- uses: lCrazyblindl/lap@v0.3.0
+  with:
+    spec: api/openapi.json
+    max-menu-tokens: "800"     # gate the compact_sig menu (omit = report only)
+    fail-on: warn              # fail on any lint warning (omit = report only)
+```
+
+Already lint OpenAPI with **Spectral**? The same LAP rules ship as a ruleset —
+see [`../spectral/`](../spectral/README.md).
+
+## What it measures (and what it doesn't)
+
+It measures **bucket A** (the definitions/menu the model carries in context) and **estimates
+C** (result size, from each response schema + an assumed `--page-size` — a structural lower
+bound that captures keys/nesting/types). **B** (the call) still depends on per-API tasks; for a
+full measured A/B/C run see
+[`../experiments/token-bench`](../experiments/token-bench/README.md). The conventions
+behind the compact form are the [LAP profile](../profile/llm-api-profile.md).
+
+## Files
+
+| file | role |
+| --- | --- |
+| `openapi_ir.py` | load any OpenAPI (file/URL) → normalized operations + `inline_refs` |
+| `menu.py` | render the menu forms (openapi_full / compact_sig / numbered) from the IR |
+| `mcp_form.py` | real-MCP baseline via `FastMCP.from_openapi` (optional; `--no-mcp` to skip) |
+| `mcp_client.py` | scores a live MCP server's advertised tools (`lap score --mcp-url`) |
+| `estimate.py` | estimates bucket C (result size) from response schemas (`--page-size`) |
+| `tokens.py` | token counting (Anthropic endpoint, or tiktoken approx) |
+| `score.py` | the `lap score` CLI |
+| `lint.py` | the `lap lint` CLI — checks a spec against the LAP profile rules (D3/R1/R2/R3/W1/E1/A1) |
+| `examples/` | sample specs: a Bookstore API, a gnarly OpenAPI 3.1 (allOf / $ref-params / nullable / external-ref), and a Swagger 2.0 spec (`swagger2.json`) |

lap/__init__.py

@@ -0,0 +1,8 @@
+"""LAP - an open, neutral token-efficiency toolkit for agent-facing APIs.
+
+`lap score <openapi>` measures the menu (bucket A) token cost of any OpenAPI spec
+under several interface forms. Reuses the parsing proven in the token-bench, but
+standalone (no pet-zoo dependency). See ../ROADMAP.md for the staged plan.
+"""
+
+__version__ = "0.1.0"

lap/cli.py

@@ -0,0 +1,37 @@
+"""Unified `lap` command: `lap score <openapi>` / `lap lint <openapi>`.
+
+Thin dispatcher so the toolkit is one console command after `pip install`. Each
+subcommand reuses its module's own argument parsing.
+"""
+
+from __future__ import annotations
+
+import sys
+
+_USAGE = "usage: lap {score|lint} <openapi-file-or-url> [options]\n" \
+         "  score  measure the menu (bucket A) token cost\n" \
+         "  lint   flag LAP profile rule violations"
+
+
+def main() -> None:
+    argv = sys.argv[1:]
+    if not argv or argv[0] in ("-h", "--help"):
+        print(_USAGE)
+        return
+    cmd, rest = argv[0], argv[1:]
+    sys.argv = [f"lap {cmd}", *rest]  # so each subcommand's argparse sees clean args
+    if cmd == "score":
+        from . import score
+
+        score.main()
+    elif cmd == "lint":
+        from . import lint
+
+        lint.main()
+    else:
+        print(f"lap: unknown command {cmd!r}\n{_USAGE}")
+        sys.exit(2)
+
+
+if __name__ == "__main__":
+    main()

lap/estimate.py

@@ -0,0 +1,115 @@
+"""Estimate bucket C (result tokens) from response schemas - no runtime needed.
+
+For each operation we synthesize a representative instance from its success
+response schema, serialize it compactly, and count tokens. For array (collection)
+responses we multiply the per-item cost by an assumed page size. Values are a
+*structural lower bound* - they capture keys + nesting + types (which dominate
+repeated-JSON cost), not real string lengths, so a live payload is >= this.
+"""
+
+from __future__ import annotations
+
+import json
+
+from . import openapi_ir as ir
+from . import tokens
+
+_PLACEHOLDER = {"string": "string", "integer": 0, "number": 0, "boolean": True, "null": None}
+
+# Common envelope keys real APIs wrap a list in, preferred in this order when
+# more than one array-typed property is present (rare, but pick deterministically).
+_ENVELOPE_KEYS = ("data", "items", "results", "value", "values", "content", "entries", "records")
+
+
+def example_instance(spec: dict, schema, stack: frozenset = frozenset(), depth: int = 0):
+    if not isinstance(schema, dict) or depth > 6:
+        return None
+    if "$ref" in schema:
+        ref = schema["$ref"]
+        if not ir._local(ref) or ref in stack:
+            return "ref"
+        return example_instance(spec, ir._resolve_ref(spec, ref), stack | {ref}, depth + 1)
+    if "allOf" in schema:
+        return {
+            fname: example_instance(spec, prop, stack, depth + 1)
+            for fname, prop in ir._collect_properties(spec, schema).items()
+        }
+    for comb in ("oneOf", "anyOf"):
+        if schema.get(comb):
+            return example_instance(spec, schema[comb][0], stack, depth + 1)
+    if "enum" in schema:
+        return schema["enum"][0]
+    t = schema.get("type")
+    if isinstance(t, list):
+        t = next((x for x in t if x != "null"), "string")
+    if t == "object" or "properties" in schema:
+        return {
+            k: example_instance(spec, v, stack, depth + 1)
+            for k, v in schema.get("properties", {}).items()
+        }
+    if t == "array":
+        return [example_instance(spec, schema.get("items", {}), stack, depth + 1)]
+    return _PLACEHOLDER.get(t, "x")
+
+
+def _success_schema(spec: dict, op: ir.Op):
+    # OpenAPI 3 (`content`) and 2.0 (`schema`), JSON-ish media types — see ir._response_schema.
+    return ir._response_schema(spec, op.raw)
+
+
+def _dumps(value) -> str:
+    return json.dumps(value, separators=(",", ":"), default=str, ensure_ascii=False)
+
+
+def _is_array_schema(spec: dict, schema) -> bool:
+    if not isinstance(schema, dict):
+        return False
+    deref = ir._deref(spec, schema)
+    return deref.get("type") == "array" or "items" in deref
+
+
+def _find_envelope_key(spec: dict, schema: dict) -> str | None:
+    """If `schema` is an object with an array-typed property - a common
+    `{"data": [...]}` / k8s `{"items": [...]}` / OData `{"value": [...]}` envelope -
+    return that property's name. Real APIs almost always wrap collections this
+    way; without this, an enveloped list scores as a tiny "object" (one item deep
+    in the envelope) and bucket C is badly undercounted."""
+    props = ir._collect_properties(spec, schema)
+    candidates = [fname for fname, prop in props.items() if _is_array_schema(spec, prop)]
+    if not candidates:
+        return None
+    for key in _ENVELOPE_KEYS:
+        if key in candidates:
+            return key
+    return candidates[0]
+
+
+def estimate(spec: dict, op: ir.Op, page_size: int = 20) -> tuple[str, int, int]:
+    """Returns (kind, per_unit_tokens, estimated_C_tokens) for an operation's
+    success response. kind in {"void", "object", "list"}.
+
+    A bare top-level array is scaled by `page_size` directly. A list wrapped in
+    an envelope object (`{"data": [...], "total_count": ...}`, k8s `{"items": [...],
+    "kind": ..., "metadata": ...}`) is detected too: the sibling fields are kept
+    (counted once) and the array property is scaled to `page_size` items, so the
+    *whole* envelope at a page is what's estimated - not just one wrapped item."""
+    schema = _success_schema(spec, op)
+    if not isinstance(schema, dict):
+        return ("void", 0, 0)
+    deref = ir._deref(spec, schema)
+    if schema.get("type") == "array" or "items" in deref:
+        per = tokens.count(_dumps(example_instance(spec, deref.get("items", {}))))
+        return ("list", per, per * page_size + 5)  # +5 for the array brackets/commas
+
+    envelope_key = _find_envelope_key(spec, schema)
+    if envelope_key:
+        instance = example_instance(spec, schema)
+        arr = instance.get(envelope_key) if isinstance(instance, dict) else None
+        if isinstance(arr, list) and arr:
+            item = arr[0]
+            per = tokens.count(_dumps(item))
+            instance[envelope_key] = [item] * page_size
+            return ("list", per, tokens.count(_dumps(instance)))
+
+    per = tokens.count(_dumps(example_instance(spec, schema)))
+    return ("object", per, per)

lap/examples/bookstore.openapi.json

@@ -0,0 +1,79 @@
+{
+  "openapi": "3.0.3",
+  "info": { "title": "Bookstore API", "version": "1.0.0" },
+  "paths": {
+    "/books": {
+      "get": {
+        "operationId": "list_books",
+        "summary": "List all books",
+        "responses": {
+          "200": {
+            "description": "ok",
+            "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Book" } } } }
+          }
+        }
+      },
+      "post": {
+        "operationId": "create_book",
+        "summary": "Add a book",
+        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookCreate" } } } },
+        "responses": { "201": { "description": "created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Book" } } } } }
+      }
+    },
+    "/books/{book_id}": {
+      "get": {
+        "operationId": "get_book",
+        "summary": "Get a book by id",
+        "parameters": [ { "name": "book_id", "in": "path", "required": true, "schema": { "type": "integer" } } ],
+        "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Book" } } } } }
+      },
+      "put": {
+        "operationId": "update_book",
+        "summary": "Replace a book",
+        "parameters": [ { "name": "book_id", "in": "path", "required": true, "schema": { "type": "integer" } } ],
+        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookCreate" } } } },
+        "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Book" } } } } }
+      },
+      "delete": {
+        "operationId": "delete_book",
+        "summary": "Delete a book",
+        "parameters": [ { "name": "book_id", "in": "path", "required": true, "schema": { "type": "integer" } } ],
+        "responses": { "204": { "description": "deleted" } }
+      }
+    },
+    "/authors/{author_id}/books": {
+      "get": {
+        "operationId": "list_author_books",
+        "summary": "List books by an author",
+        "parameters": [ { "name": "author_id", "in": "path", "required": true, "schema": { "type": "integer" } } ],
+        "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Book" } } } } } }
+      }
+    }
+  },
+  "components": {
+    "schemas": {
+      "Genre": { "type": "string", "enum": ["fiction", "nonfiction", "poetry", "reference"] },
+      "BookCreate": {
+        "type": "object",
+        "required": ["title", "author", "price", "genre"],
+        "properties": {
+          "title": { "type": "string", "minLength": 1 },
+          "author": { "type": "string" },
+          "price": { "type": "number", "minimum": 0 },
+          "genre": { "$ref": "#/components/schemas/Genre" }
+        }
+      },
+      "Book": {
+        "type": "object",
+        "required": ["id", "title", "author", "price", "genre"],
+        "properties": {
+          "id": { "type": "integer" },
+          "title": { "type": "string", "minLength": 1 },
+          "author": { "type": "string" },
+          "price": { "type": "number", "minimum": 0 },
+          "genre": { "$ref": "#/components/schemas/Genre" }
+        }
+      }
+    }
+  }
+}

lap/examples/gnarly.openapi.json

@@ -0,0 +1,68 @@
+{
+  "openapi": "3.1.0",
+  "info": { "title": "Gnarly API", "version": "1.0.0" },
+  "paths": {
+    "/pets": {
+      "parameters": [
+        { "name": "limit", "in": "query", "schema": { "type": "integer" } }
+      ],
+      "get": {
+        "operationId": "listPets",
+        "responses": {
+          "200": { "description": "ok", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Pet" } } } } }
+        }
+      },
+      "post": {
+        "operationId": "createPet",
+        "requestBody": { "$ref": "#/components/requestBodies/PetBody" },
+        "responses": { "201": { "description": "created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Pet" } } } } }
+      }
+    },
+    "/pets/{petId}": {
+      "get": {
+        "operationId": "getPet",
+        "parameters": [ { "$ref": "#/components/parameters/PetId" } ],
+        "responses": { "200": { "$ref": "#/components/responses/PetResp" } }
+      }
+    }
+  },
+  "components": {
+    "parameters": {
+      "PetId": { "name": "petId", "in": "path", "required": true, "schema": { "type": "integer" } }
+    },
+    "requestBodies": {
+      "PetBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PetCreate" } } } }
+    },
+    "responses": {
+      "PetResp": { "description": "a pet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Pet" } } } }
+    },
+    "schemas": {
+      "Status": { "type": "string", "enum": ["available", "sold"] },
+      "Base": {
+        "type": "object",
+        "properties": { "id": { "type": ["integer", "null"] } }
+      },
+      "Pet": {
+        "allOf": [
+          { "$ref": "#/components/schemas/Base" },
+          {
+            "type": "object",
+            "required": ["name"],
+            "properties": {
+              "name": { "type": "string" },
+              "status": { "$ref": "#/components/schemas/Status" }
+            }
+          }
+        ]
+      },
+      "PetCreate": {
+        "type": "object",
+        "required": ["name"],
+        "properties": {
+          "name": { "type": "string", "minLength": 1 },
+          "owner": { "$ref": "https://example.com/external.json#/Owner" }
+        }
+      }
+    }
+  }
+}

lap/examples/swagger2.json

@@ -0,0 +1,65 @@
+{
+  "swagger": "2.0",
+  "info": { "title": "Swagger2 Pets", "version": "1.0.0" },
+  "basePath": "/v1",
+  "consumes": ["application/json"],
+  "produces": ["application/json"],
+  "paths": {
+    "/pets": {
+      "get": {
+        "operationId": "listPets",
+        "summary": "List pets",
+        "parameters": [
+          { "name": "breed", "in": "query", "type": "string" }
+        ],
+        "responses": {
+          "200": {
+            "description": "a list of pets",
+            "schema": { "type": "array", "items": { "$ref": "#/definitions/Pet" } }
+          }
+        }
+      },
+      "post": {
+        "operationId": "createPet",
+        "summary": "Create a pet",
+        "parameters": [
+          { "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/PetCreate" } }
+        ],
+        "responses": {
+          "201": { "description": "created", "schema": { "$ref": "#/definitions/Pet" } }
+        }
+      }
+    },
+    "/pets/{petId}": {
+      "get": {
+        "operationId": "getPet",
+        "summary": "Get a pet",
+        "parameters": [
+          { "name": "petId", "in": "path", "required": true, "type": "integer" }
+        ],
+        "responses": {
+          "200": { "description": "ok", "schema": { "$ref": "#/definitions/Pet" } },
+          "404": { "description": "not found" }
+        }
+      }
+    }
+  },
+  "definitions": {
+    "Pet": {
+      "type": "object",
+      "properties": {
+        "id": { "type": "integer" },
+        "name": { "type": "string" },
+        "status": { "type": "string", "enum": ["available", "sold"] }
+      }
+    },
+    "PetCreate": {
+      "type": "object",
+      "required": ["name"],
+      "properties": {
+        "name": { "type": "string" },
+        "status": { "type": "string" }
+      }
+    }
+  }
+}

lap/lint.py

@@ -0,0 +1,149 @@
+"""`lap lint <openapi>` - check an API against the LAP profile rules.
+
+Static, advisory checks over an OpenAPI spec for the LAP conventions that are
+detectable without runtime: opaque names (D3), read shaping on collections
+(projection R1 / filter R2 / pagination R3), aggregation (A1), minimal writes
+(W1), and uniform errors (E1). Heuristic by nature - it flags likely token/clarity
+costs for a human to confirm, each tied to a profile rule.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+from dataclasses import dataclass
+
+from . import openapi_ir as ir
+
+PAGINATION = {"limit", "offset", "page", "page_size", "pagesize", "per_page", "perpage",
+              "cursor", "top", "skip", "$top", "$skip"}
+PROJECTION = {"fields", "field", "select", "$select", "include", "expand", "$expand"}
+FILTER_HINTS = {"filter", "$filter", "q", "query", "where", "search"}
+
+
+@dataclass
+class Finding:
+    rule: str
+    severity: str  # "warn" | "info"
+    where: str
+    message: str
+
+
+def _query_names(op: ir.Op) -> set[str]:
+    return {p["name"].lower() for p in op.params if p.get("in") == "query"}
+
+
+def _error_codes(op: ir.Op) -> list[str]:
+    return [c for c in op.raw.get("responses", {}) if c[:1] in ("4", "5")]
+
+
+def lint(spec: dict) -> list[Finding]:
+    ops = ir.operations(spec)
+    out: list[Finding] = []
+
+    for op in ops:
+        where = f"{op.method} {op.path}"
+
+        # D3 - opaque operation name
+        if re.fullmatch(r"\d+", op.name) or not re.search(r"[A-Za-z]", op.name) or len(op.name) < 3:
+            out.append(Finding("D3", "warn", where,
+                               f"opaque operation name '{op.name}' - LLMs ground on readable names"))
+
+        # Read shaping on collection (array-returning) GETs
+        if op.method == "GET" and op.returns.endswith("[]"):
+            q = _query_names(op)
+            if not (q & PAGINATION):
+                out.append(Finding("R3", "warn", where,
+                                   "collection GET has no pagination (limit/offset/cursor) - agents pull the whole list (big bucket C)"))
+            if not (q & PROJECTION):
+                out.append(Finding("R1", "info", where,
+                                   "no field projection (fields/select) - responses carry every field"))
+            if not (q & (FILTER_HINTS | (q - PAGINATION - PROJECTION))):
+                out.append(Finding("R2", "info", where,
+                                   "no server-side filter params - agents fetch then filter in-context"))
+
+        # W1 - writes returning a full representation by default
+        if op.method in ("POST", "PUT", "PATCH") and op.returns not in ("void", ""):
+            out.append(Finding("W1", "info", where,
+                               f"write returns a full representation ({op.returns}) by default - consider Prefer: return=minimal (server-generated fields only)"))
+
+        # E1 - no error responses declared
+        if not _error_codes(op):
+            out.append(Finding("E1", "warn", where,
+                               "no 4xx/5xx error response declared - agents can't distinguish success/empty/error"))
+
+    # A1 - no aggregate/count endpoint anywhere
+    if not any(re.search(r"count|aggregate|stats|summary", op.name + op.path, re.I) for op in ops):
+        out.append(Finding("A1", "info", "(global)",
+                           "no aggregate/count endpoint - 'how many...' questions force pulling the full list"))
+
+    return out
+
+
+def filter_ignored(findings: list[Finding], ignore) -> list[Finding]:
+    ignore = {r.upper() for r in ignore}
+    return [f for f in findings if f.rule.upper() not in ignore]
+
+
+def _load_ignore_file() -> set[str]:
+    if not os.path.exists(".lapignore"):
+        return set()
+    with open(".lapignore", encoding="utf-8") as fh:
+        toks = re.split(r"[,\s]+", fh.read())
+    return {t.strip().upper() for t in toks if t.strip() and not t.startswith("#")}
+
+
+def _print_human(title: str, source: str, findings: list[Finding], warns: int, infos: int) -> None:
+    print(f"\nLAP lint - {title}\nsource: {source}\n")
+    if not findings:
+        print("  No LAP rule violations detected. ✓\n")
+        return
+    order = {"warn": 0, "info": 1}
+    by_rule: dict[str, list[Finding]] = {}
+    for f in sorted(findings, key=lambda f: (order[f.severity], f.rule)):
+        by_rule.setdefault(f"{f.severity.upper()} {f.rule}", []).append(f)
+    for header, items in by_rule.items():
+        print(f"  [{header}] {items[0].message.split(' - ')[0]}")
+        for f in items[:6]:
+            print(f"      {f.where}")
+        if len(items) > 6:
+            print(f"      ... +{len(items) - 6} more")
+        print()
+    print(f"  {warns} warning(s), {infos} suggestion(s). See profile/llm-api-profile.md for the rules.\n")
+
+
+def main() -> None:
+    import argparse
+
+    ap = argparse.ArgumentParser(description="Lint an OpenAPI against the LAP profile rules.")
+    ap.add_argument("source", help="OpenAPI spec: file path or http(s) URL")
+    ap.add_argument("--json", action="store_true", help="emit machine-readable JSON")
+    ap.add_argument("--ignore", default="", help="comma-separated rule codes to suppress (also reads ./.lapignore)")
+    ap.add_argument("--fail-on", choices=["none", "info", "warn"], default="none",
+                    help="CI gate: exit 1 if any finding at/above this severity remains")
+    args = ap.parse_args()
+
+    spec = ir.load_spec(args.source)
+    ignore = _load_ignore_file() | {r.strip() for r in args.ignore.split(",") if r.strip()}
+    findings = filter_ignored(lint(spec), ignore)
+    title = spec.get("info", {}).get("title", "(untitled API)")
+    warns = sum(1 for f in findings if f.severity == "warn")
+    infos = len(findings) - warns
+
+    if args.json:
+        print(json.dumps({
+            "api": title, "source": args.source,
+            "findings": [{"rule": f.rule, "severity": f.severity, "where": f.where, "message": f.message}
+                         for f in findings],
+            "warnings": warns, "suggestions": infos,
+        }, indent=2))
+    else:
+        _print_human(title, args.source, findings, warns, infos)
+
+    if (args.fail_on == "warn" and warns) or (args.fail_on == "info" and findings):
+        raise SystemExit(1)
+
+
+if __name__ == "__main__":
+    main()