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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.