LAP (Lean API Platform): compiling API specs into agent-native format

The problem LAP targets: agents guessing at endpoints

An LLM agent that has to call an API usually gets one of two things: nothing, or a full OpenAPI document. The README states the first case plainly, writing that without API documentation agents "hallucinate endpoints, invent parameters, and guess auth flows," and cites a blind-test accuracy of 0.399. The second case is quieter but just as costly. A large OpenAPI file spends most of its tokens on YAML scaffolding that carries no information for the caller: paths, requestBody, schema wrappers, repeated field definitions. You pay for that on every request, and the model still has to find the one endpoint it needs inside it.

LAP is aimed at the second case. It is a compiler, not a minifier, and the README is explicit about the distinction: the output has its own grammar, with directives and compressed type expressions, rather than being the same document with whitespace removed. The intended user is anyone building an agent that calls third-party APIs and wants the spec in context without the structural overhead. The repository also ships a registry of pre-compiled specs, so you can start from someone else's compiled output instead of compiling your own.

How the compiler works: five stages and a directive grammar

The README describes five compression stages, each removing a different kind of token waste. Structural removal strips YAML scaffolding such as paths, requestBody and schema, and the README attributes roughly 30 percent of the savings to this stage. Directive grammar replaces nested structures with flat, single-line declarations, about 25 percent. Type compression turns a pair like type: string plus format: uuid into str(uuid), about 10 percent. Redundancy elimination extracts shared fields once through @common_fields and @typ (the README text is truncated at this point), and a fifth stage is listed but not described in the excerpt.

Two things are worth separating here. The first is the type vocabulary: enum(a|b|c), str(uuid), int=10. These are constraints, not just shorter spellings. The README argues they "prevent agent hallucination," and that is the more defensible claim than raw size, because a model that sees int=10 knows the bound rather than inferring it. The second is the directive layer. Flattening nested structures into single-line declarations is what makes the format agent-native rather than merely small, and it is also what makes the output non-standard: nothing else reads it. That is why the round-trip command matters. lapsh convert exists to turn a compiled spec back into OpenAPI, and it is the only way to check that compression did not drop something.

Installing lapsh and compiling a first spec

LAP ships on npm as @lap-platform/lapsh and on PyPI as lapsh. The Python package requires Python 3.10 or newer, and its runtime dependencies are pyyaml, tiktoken and graphql-core, so a pip install pulls those in. If you only want the CLI, npm is the shorter path.

npm install -g @lap-platform/lapsh

With the CLI on your PATH, the first real use is compiling a spec you already have. The README gives this example, and the --lean flag selects the compressed output rather than a fuller form:

npx @lap-platform/lapsh compile api.yaml --lean

You should get a .lap file next to your source. Open it and check two things before trusting it: that every endpoint you expect is present, and that the parameter types survived as directives rather than being dropped. If you would rather not compile anything yet, the registry path is search then get:

npx @lap-platform/lapsh search payment
npx @lap-platform/lapsh get stripe -o stripe.lap

The search command queries the registry, which the README says holds more than 1500 pre-compiled specs. The get command writes the spec to the path you give with -o. To install a spec as an agent skill instead, the README uses skill-install with a service name:

npx @lap-platform/lapsh skill-install stripe

For editor integration, init writes the skill into the target tool's directory. The README documents three targets, and notes that Codex skills land in ~/.codex/skills/. It also states that Codex agents use curl for registry operations instead of npx, and that auto-update hooks are pre-configured but depend on a codex_hooks feature flag the README calls experimental. Treat that flag as a dependency, not a detail.

npx @lap-platform/lapsh init                    # Claude Code
npx @lap-platform/lapsh init --target cursor    # Cursor
npx @lap-platform/lapsh init --target codex     # Codex

Where LAP stops helping: single endpoints, exotic specs and unverifiable output

The compression argument scales with spec size. The README reports a 5.2x median on OpenAPI and up to 39.6x on large specs, which means the small end of the range is modest. If your agent calls one endpoint on one API, writing that endpoint into the system prompt by hand costs fewer tokens than installing a compiler, a registry lookup and a skill, and it removes a moving part. LAP is the wrong tool at that scale.

The second limit is format coverage. Six input formats are listed: OpenAPI, GraphQL, AsyncAPI, Protobuf, Postman and Smithy. That is broad, but it is not everything, and the README does not describe what happens when a spec uses features the compiler does not model. The claim of "zero information loss" is asserted rather than demonstrated in the excerpt, and no failure mode is documented. For a compiler whose entire value proposition is fidelity, that is the gap to probe first. Compile a spec you know well, convert it back with lapsh convert, and diff the result against the original. If the diff is empty for your specs, the claim holds where it matters to you.

The third limit is the output format itself. A .lap file is not readable by Swagger UI, Postman, code generators or anything else in the OpenAPI ecosystem. Every consumer of that spec now has to go through LAP tooling. That is a real coupling, and it is the price of the directive grammar.

LAP versus plain OpenAPI in the prompt

The obvious alternative is to skip the compiler and put the raw OpenAPI document in the agent's context, or to write a short hand-maintained summary of the endpoints you need. The difference is where the work happens. Raw OpenAPI keeps the spec in a format every tool understands, and the agent reads the same document a human would. The cost is tokens on every turn and a model that has to parse YAML nesting to find a parameter. A hand-written summary is cheapest of all until the API changes, at which point it is silently wrong.

LAP sits between them: it keeps the source spec as the source of truth and regenerates the agent-facing form from it. The trade is that you add a build step and a proprietary format, and you depend on the compiler preserving semantics. The README's benchmark page reports LAP Lean scoring 0.851 against 0.825 for raw OpenAPI while using 35 percent less cost and 29 percent less time, across what it describes as 500 blind runs over 50 specs. Those numbers come from the project's own benchmark repository, so read them as the authors' measurement, not an independent one. The direction of the claim, same accuracy at lower cost, is more plausible than the exact figures.

Maintenance, licence and what upgrading costs

The repository is not archived, and the last push was on 2026-09-14. Releases are spaced months apart: v0.6.1 on 2026-03-19, v0.7.0 on 2026-03-26, and v0.7.1 on 2026-07-30. The pyproject.toml pins the package version at 0.7.1 and classifies the project as "Development Status :: 4 - Beta". Beta status plus multi-month release gaps means you should expect the compiled grammar to change between minor versions. A .lap file compiled today may not be the file the next release emits, so keep the source spec in your repository and treat the .lap output as a build artifact rather than a checked-in document.

The licence is Apache-2.0, declared both in the repository and in the pyproject.toml license field. That permits commercial use and modification, and it includes a patent grant. It does not tell you anything about the registry content: specs downloaded via lapsh get originate from third-party API publishers, and the README's publisher flow (registering at registry.lap.sh) does not state what licence those specs carry. If you redistribute compiled specs, check the upstream API's terms separately. This is a description of what the files say, not legal advice.

The dependency surface is small: pyyaml, tiktoken and graphql-core in the Python package, with tiktoken pulling in its own tokenizer data. That is a light footprint for a tool that runs in CI.

Editorial conclusion

Adopt LAP if your agents already call real APIs and you are paying tokens for full OpenAPI documents on every turn: the compiler is one command, the output is inspectable, and lapsh convert gives you a round-trip check before you commit. Do not adopt it if your agents only need one or two endpoints, or if you cannot verify a compiled spec against the upstream source, because a wrong parameter in a compressed spec is harder to spot than in the original YAML. Before rolling it out, compile your largest spec with lapsh compile api.yaml --lean, compare the endpoint and parameter counts against the source, and confirm the Python package on PyPI (lapsh, requires Python 3.10 or newer) is the distribution you intend to depend on.

Frequently asked questions

Official sources

1. Lap-Platform/LAP on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases