Metadata-Version: 2.4
Name: lapsh
Version: 0.4.4
Summary: Lean API Platform -- Token-efficient API specs for AI agents
Author: LAP Contributors
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/Lap-Platform/lap
Project-URL: Documentation, https://github.com/Lap-Platform/lap#readme
Project-URL: Repository, https://github.com/Lap-Platform/lap
Project-URL: Issues, https://github.com/Lap-Platform/lap/issues
Project-URL: Changelog, https://github.com/Lap-Platform/lap/blob/main/CHANGELOG.md
Keywords: api,openapi,ai,llm,agents,compression,platform
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Documentation
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: pyyaml>=6.0
Requires-Dist: tiktoken>=0.5.0
Requires-Dist: graphql-core>=3.2.0
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-timeout; extra == "dev"
Requires-Dist: rich; extra == "dev"
Requires-Dist: graphql-core; extra == "dev"
Requires-Dist: tiktoken; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Dynamic: license-file

<div align="center">

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="assets/readme-logo-dark.png">
  <source media="(prefers-color-scheme: light)" srcset="assets/light/readme-logo-light.png">
  <img alt="LAP — Lean API Platform" src="assets/readme-logo-dark.png">
</picture>

# LAP -- Lean API Platform

**Compile API specs into token-efficient contracts for LLM agents.**

[![PyPI](https://img.shields.io/pypi/v/lapsh.svg)](https://pypi.org/project/lapsh/)
[![npm](https://img.shields.io/npm/v/@lap-platform/lapsh.svg)](https://www.npmjs.com/package/@lap-platform/lapsh)
[![CI](https://github.com/Lap-Platform/lap/actions/workflows/ci.yml/badge.svg)](https://github.com/Lap-Platform/lap/actions/workflows/ci.yml)
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)

[Website](https://lap.sh) · [Registry](https://lap.sh) · [Benchmarks](https://github.com/Lap-Platform/Lap-benchmark-docs) · [Docs](docs/)

</div>

---

LLMs waste thousands of tokens parsing bloated API specs. Stripe's OpenAPI spec is **1M+ tokens** — mostly YAML scaffolding, nested wrappers, and repeated schemas. LAP compiles any API spec into a typed, flat format that preserves every endpoint, parameter, and constraint in a fraction of the tokens.

**Not minification** — a purpose-built compiler with its own grammar.

### Proven in 500 blind runs across 50 APIs

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="assets/benchmark_savings.png">
    <source media="(prefers-color-scheme: light)" srcset="assets/light/benchmark_savings.png">
    <img alt="88% fewer tokens, 35% lower cost, same accuracy" src="assets/benchmark_savings.png" width="700">
  </picture>
</p>

LAP Lean scored **0.851** (vs 0.825 raw) while using **35% less cost** and **29% less time** -- same accuracy, far fewer tokens.

> [Full benchmark report (500 runs, 50 specs, 5 formats)](https://lap-platform.github.io/Lap-benchmark-docs/results/LAP_Benchmark_v2_Full_Report.html) · [Benchmark methodology and data](https://github.com/Lap-Platform/Lap-benchmark-docs)

## Install

```bash
# Try without installing
npx @lap-platform/lapsh compile api.yaml

# Or install
pip install lapsh
lapsh compile api.yaml -o api.lap
```

## What You Get

- 🗜️ **5.2× median compression** on OpenAPI, up to 39.6× on large specs — **35% cheaper, 29% faster** ([benchmarks](BENCHMARKS.md))
- 📐 **Typed contracts** — `enum(a|b|c)`, `str(uuid)`, `int=10` prevent agent hallucination
- 🔌 **6 input formats** — OpenAPI, GraphQL, AsyncAPI, Protobuf, Postman, Smithy
- 🎯 **Zero information loss** — every endpoint, param, and type constraint preserved
- 🔁 **Round-trip** — convert back to OpenAPI with `lapsh convert`
- 📦 **Registry** — browse and install pre-compiled specs at [lap.sh](https://lap.sh)
- 🤖 **Skill generation** — `lapsh skill` creates agent-ready skills from any spec
- 🔗 **Integrations** — LangChain, CrewAI, OpenAI function calling, MCP

## How It Works

<p align="center">
  <img src="assets/pipeline.png" alt="How LAP works — 5 compression stages" width="800">
</p>

Five compression stages, each targeting a different source of token waste:

| Stage | What it does | Savings |
|-------|-------------|--------:|
| **Structural removal** | Strip YAML scaffolding — `paths:`, `requestBody:`, `schema:` wrappers vanish | ~30% |
| **Directive grammar** | `@directives` replace nested structures with flat, single-line declarations | ~25% |
| **Type compression** | `type: string, format: uuid` → `str(uuid)` | ~10% |
| **Redundancy elimination** | Shared fields extracted once via `@common_fields` and `@type` | ~20% |
| **Lean mode** | Strip descriptions — LLMs infer meaning from well-named parameters | ~15% |

<p align="center">
  <img src="assets/demo.gif" alt="LAP CLI demo" width="700">
</p>

## Benchmarks

**162 specs · 5,228 endpoints · 4.37M → 423K tokens**

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="assets/format_comparison.png">
    <source media="(prefers-color-scheme: light)" srcset="assets/light/format_comparison.png">
    <img alt="Compression by API format" src="assets/format_comparison.png" width="600">
  </picture>
</p>

| Format | Specs | Median | Best |
|--------|------:|-------:|-----:|
| **OpenAPI** | 30 | **5.2×** | 39.6× |
| **Postman** | 36 | **4.1×** | 24.9× |
| **Protobuf** | 35 | **1.5×** | 60.1× |
| **AsyncAPI** | 31 | **1.4×** | 39.1× |
| **GraphQL** | 30 | **1.3×** | 40.9× |

Verbose formats compress most — they carry the most structural overhead. Already-concise formats like GraphQL still benefit from type deduplication.

## The Ecosystem

LAP is more than a compiler:

| Component | What | Command |
|-----------|------|---------|
| **Compiler** | Any spec → `.lap` | `lapsh compile api.yaml` |
| **Registry** | Browse & install pre-compiled specs | `lapsh skill-install stripe` |
| **Skill Generator** | Create agent-ready skills from any spec | `lapsh skill api.yaml --install` |
| **API Differ** | Detect breaking API changes | `lapsh diff old.lap new.lap` |
| **Round-trip** | Convert LAP back to OpenAPI | `lapsh convert api.lap -f openapi` |
| **Publish** | Share specs to the registry | `lapsh publish api.yaml --provider acme` |

## Supported Formats

```bash
lapsh compile  api.yaml           # OpenAPI 3.x / Swagger
lapsh compile  schema.graphql     # GraphQL SDL
lapsh compile  events.yaml        # AsyncAPI
lapsh compile  service.proto      # Protobuf / gRPC
lapsh compile  collection.json    # Postman v2.1
lapsh compile  model.smithy       # AWS Smithy
```

Format is auto-detected. Override with `-f openapi|graphql|asyncapi|protobuf|postman|smithy`.

## Top Compressions

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="assets/compression_bar_chart.png">
    <source media="(prefers-color-scheme: light)" srcset="assets/light/compression_bar_chart.png">
    <img alt="Top 15 OpenAPI APIs by compression ratio" src="assets/compression_bar_chart.png" width="650">
  </picture>
</p>

## Integrations

```python
# LangChain
from lap.integrations import LAPLoader
docs = LAPLoader("stripe.lap").load()

# OpenAI function calling
from lap.integrations import to_openai_functions
functions = to_openai_functions("stripe.lap")
```

Also: CrewAI tool, MCP server and compression proxy. See [integration docs](docs/guide-integrate.md).

## FAQ

<details>
<summary><b>How is this different from OpenAPI?</b></summary>

LAP doesn't replace OpenAPI — it compiles FROM it. Like TypeScript → JavaScript: you keep your OpenAPI specs, your existing tooling, everything. LAP adds a compilation step for the LLM runtime.
</details>

<details>
<summary><b>How is this different from MCP?</b></summary>

MCP defines how agents discover and invoke tools (the plumbing). LAP compresses the documentation those tools expose (the payload). They're complementary — LAP can compress MCP tool schemas.
</details>

<details>
<summary><b>Why not just minify the JSON?</b></summary>

Minification removes whitespace — that's ~10% savings. LAP performs semantic compression: flattening nested structures, deduplicating schemas, compressing type declarations, and stripping structural overhead. That's 5-40× savings. Different class of tool.
</details>

<details>
<summary><b>What about prompt caching?</b></summary>

Use both. Compress with LAP first, then cache the compressed version. LAP reduces the first-call cost and frees context window space. Caching reduces repeated-call cost. They stack.
</details>

<details>
<summary><b>Will LLMs understand this format?</b></summary>

Yes. LAP uses conventions LLMs already know — `@directive` syntax, `{name: type}` notation, HTTP methods and paths. In blind tests, agents produce identical correct output from LAP and raw OpenAPI. The typed contracts actually reduce hallucination.
</details>

<details>
<summary><b>What if token costs keep dropping?</b></summary>

Cost is the least important argument. The core value is typed contracts: `enum(succeeded|pending|failed)` prevents hallucinated values regardless of token price. Plus: formal grammar (parseable by code, not just LLMs), schema diffing, and faster inference from fewer input tokens.
</details>

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md). The test suite has 545 tests across 177 example specs in 6 formats.

```bash
git clone https://github.com/Lap-Platform/lap.git
cd lap
pip install -e ".[dev]"
pytest
```

## License

[Apache 2.0](LICENSE) — See [NOTICE](NOTICE) for attribution.

---

<div align="center">

**[lap.sh](https://lap.sh)** · Built by the LAP team

</div>
