Skip to main content

a2api

a2api turns existing APIs and functions into a small call protocol that LLM hosts can search, describe and invoke cheaply — at any API size.

Convert what you already have — an OpenAPI document, a Java/Spring MVC, Go net/http or Rust Axum source tree, or plain Python functions — and call it directly, through three fixed MCP tools, or as selected function tools for a model. No review files, build directories or registry are required for the first call.

pip install a2api                 # core: convert, invoke, ToolSession
pip install "a2api[mcp]"          # MCP stdio bridge
pip install "a2api[openapi]"      # YAML OpenAPI documents
pip install "a2api[source]"       # Spring / Go / Rust source importers

Guides (Korean): converting legacy APIs — with OpenAPI and code, or code only (Spring, Go, Rust, Python, other languages) · call protocol · model host tools · evaluation

Python functions

from typing import TypedDict
from a2api import Application, ExecutionContext, capability

class Order(TypedDict):
    id: str
    status: str

@capability(id="orders.get", effect="read")
def get_order(id: str) -> Order:
    """Get one order by ID."""
    return {"id": id, "status": "paid"}

@capability(id="orders.cancel", effect="write")
async def cancel_order(id: str, *, context: ExecutionContext) -> Order:
    """Cancel an order. Writes are never retried automatically."""
    return {"id": id, "status": "cancelled"}

app = Application([get_order, cancel_order])
caller = ExecutionContext("alice", "tenant-a", frozenset())
print(app.invoke("orders.get", {"id": "ORD-1"}, context=caller))
# {'status': 'succeeded', 'data': {'id': 'ORD-1', 'status': 'paid'}, 'completeness': {...}}

Type hints and TypedDicts become JSON Schemas; inputs and outputs are validated on every call; context is host-only and never part of the model's input.

OpenAPI or source code → HTTP calls

from a2api import HTTPDeployment, convert
from a2api.importers import OpenAPIImporter, SpringSourceImporter

source = OpenAPIImporter.from_file("orders.openapi.json", namespace="shop")
# or: SpringSourceImporter.from_directory("src/main/java", namespace="shop")  (GoSourceImporter, RustSourceImporter)
app = convert(source, operations={
    "listOrders": {"effect": "read", "select": ["items[].id", "items[].status", "total", "hasMore"]},
    "cancelOrder": {"effect": "write"},
}, deployment=HTTPDeployment("https://orders.internal", credential_provider=lambda ctx: {...}, timeout_ms=5000))

select keeps only public fields (nested paths and [] array items supported) after the raw response is validated against the original schema. Credentials and origins stay with the host.

Model hosts: ToolSession

from a2api import ToolSession

session = ToolSession(app, caller)               # or ToolSession.from_mcp(mcp_client)
await session.auto(user_question)                # small catalog: all functions; large: host pre-search
tools = session.tools()                          # Chat Completions function tools for this request
result = await session.call(name, arguments)     # validated invoke, never retried
text = session.render(result)                    # compact model-facing result with failure hints

Small catalogs are exposed directly; large catalogs get one a2api_search tool plus the functions the host pre-selected from the question. Function parameters are the exact business input schema (HTTP path/query/body flattened when lossless).

MCP

import anyio
from a2api.mcp_bridge import serve_stdio
anyio.run(serve_stdio, app, caller)   # tools: a2api.discover / a2api.describe / a2api.invoke

The MCP tool list is always the same three tools, whatever the catalog size.

Protocol

a2api-call defines discover/describe/invoke requests, a six-field capability descriptor and structured errors; the JSON Schema ships in the package (a2api.protocol_schema()). a2api-tools defines how hosts present selected capabilities to models.

Evaluation

The repository contains a benchmark that implements the same API in Python, Spring, Go and Rust at three sizes (19 / 55 / 235 operations) and compares a2api with passing the OpenAPI specification to the model, either as one function per operation or as the whole document in the prompt. On a fixed holdout of 720 runs with nvidia/Muse-Glimmer-30B-NVFP4:

a2api spec → functions spec → prompt
Tasks passed 239/240 (1 provider error) 237/240 240/240
Median tokens per task (small / medium / large) 4.9k / 4.8k / 5.0k 8.1k / 19.6k / 75.2k 12.6k / 28.2k / 103.3k
Median seconds per task (small / medium / large) 10.7 / 10.6 / 10.7 9.4 / 9.8 / 14.8 10.2 / 11.3 / 18.8

Context stays flat as the API grows and latency drops 27–43% for the large API. Accuracy was near the ceiling for all approaches, and for small and medium APIs a2api was slower than one-function-per-operation. Details, failures and limits are in the evaluation document. Synthetic API, one model — not a guarantee for every API or model.

Licensed under MIT.

Metadata

Release files for a2api 1.0.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for a2api 1.0.0
File Size Uploaded Provenance Actions
a2api-1.0.0.tar.gz 195.1 kB Without provenance Details for a2api-1.0.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for a2api 1.0.0
File Interpreter ABI Platform Actions
a2api-1.0.0-py3-none-any.whl Python 3 none any Details for a2api-1.0.0-py3-none-any.whl

Total release size: 331.0 kB

Release files / a2api-1.0.0.tar.gz

Download URL a2api-1.0.0.tar.gz
Size 195.1 kB
Tags Source
SHA-256 checksum
How to use checksums
3f23f7672c5360f89073378c53068b522b2c2c5d86cace85f11f48a92619645e
BLAKE2b-256 checksum
How to use checksums
34a3286580939f46a831235db4b062931f91e222db4ddc55cee90b25f6ca05fe
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.4

Release files / a2api-1.0.0-py3-none-any.whl

Download URL a2api-1.0.0-py3-none-any.whl
Size 135.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
21431daa81af8a53522163ffe0621c0d9e349270bb429d7b04ae1668d19aa73c
BLAKE2b-256 checksum
How to use checksums
8b419badeb2321d6cf837a36723ebe963ad93301c1d0b7ba3ff483af2b625100
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.4

Security for a2api 1.0.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.0.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page