Liquid

Canonical intents — one mental model across services

await liquid.execute_intent(adapter, "charge_customer", {"customer_id": "cus_xyz", "amount_cents": 9999, "currency": "USD"}) # Same intent on Stripe / Braintree / Square / Adyen — 71 canonical intents

Structured recovery — agents self-heal without parsing text

try: await liquid.fetch(adapter, "/orders") except LiquidError as e: if e.recovery and e.recovery.next_action: await agent.call_tool(e.recovery.next_action.tool, e.recovery.next_action.args)

Every error carries aRecoverywithnext_action: ToolCall,retry_safe, andretry_after_seconds. 401 →store_credentials. 404/410 →repair_adapter. 429 → retry after the given delay. And when the upstream's schema drifts, adaptersself-heal(repair_adapter) — the agent keeps working.

est = await liquid.estimate_fetch(adapter, "/orders") # FetchEstimate(expected_items=250, expected_tokens=52_000, confidence="high", …) if est.expected_tokens < my_budget: data = await liquid.fetch(adapter, "/orders")

Tools emitted byto_tools()carry ametadatablock (cost_credits,typical_latency_ms,cached,idempotent,side_effects,related_tools) so the agent can reason about which tool to pick — and ambient tools (liquid_check_quota,liquid_list_adapters, …) let it ask about state instead of memorizing it.

Deterministic benchmarks on realistic agent tasks (500-order, 200-ticket fixtures, mocked HTTP) — reproducible viapython -m benchmarks.run:

Full methodology + per-task breakdown:benchmarks/RESULTS.md.

pip install liquid-api # core + bundled MCP server (the liquid-mcp command) pip install 'liquid-api[discovery]' # + an LLM for discovering spec-less REST APIs & field mapping

Do you need an LLM extra?Self-describing interfaces — OpenAPI, GraphQL, gRPC, MCP, A2A, WSDL — andall databases(introspection) discover withno LLM, and the whole runtime (fetch/query/write/sense) never calls a model. You only need an LLM backend todiscover a REST API that has no machine-readable spec(heuristic + LLM) and tomapits fields.[discovery]pulls LiteLLM, which reaches OpenAI / Gemini / Anthropic / local / 100+ providers; or pick one directly:

pip install 'liquid-api[gemini]' # Google Gemini (or [anthropic]; OpenAI/local work with no extra via base_url) pip install 'liquid-api[grpc]' # gRPC transport (reflection) pip install 'liquid-api[ws]' # WebSocket transport pip install 'liquid-api[pg]' # Postgres / pgvector (asyncpg) pip install 'liquid-api[mysql]' # MySQL / MariaDB (aiomysql); SQLite needs no extra pip install 'liquid-api[neo4j]' # Neo4j graph (Bolt / Cypher) pip install 'liquid-api[duckdb]' # DuckDB (embedded analytics) pip install 'liquid-api[mssql]' # SQL Server (ODBC; needs a system ODBC driver) pip install 'liquid-api[mongodb]' # MongoDB (collections as endpoints) pip install 'liquid-api[redis]' # Redis (keyspace namespaces as endpoints) pip install 'liquid-api[mqtt]' # MQTT (IoT pub/sub) pip install 'liquid-api[modbus]' # Modbus (industrial registers) pip install 'liquid-api[opcua]' # OPC UA (Industry-4.0 nodes + subscriptions) pip install 'liquid-api[bacnet]' # BACnet (building automation; ADB needs the system adb binary) # Framework integration (LangChain / OpenAI / Anthropic / MCP) is built in — no extra package.

The core is dependency-free — every backend's library is an optional extra, imported only when used.

Point Liquid at an API it has never seen (no adapter, no OpenAPI spec, no auth) and get typed records back — you write no connector; discovery + mapping is the only place a model runs. Runnable end to end viaexamples/live_quickstart.py:

Connecting to an API Liquid has never seen: https://api.openbrewerydb.org/v1/breweries discovery method : rest_heuristic mapped fields : ['name', 'city', 'state', 'country'] LLM calls so far : 2 (discovery + mapping) fetch() -> 50 typed records; first 3: {'name': '(405) Brewing Co', 'city': 'Norman', 'state': 'Oklahoma', 'country': 'United States'} {'name': '(512) Brewing Co', 'city': 'Austin', 'state': 'Texas', 'country': 'United States'} {'name': '1 of Us Brewing Company', 'city': 'Mount Pleasant', 'state': 'Wisconsin', 'country': 'United States'} LLM calls during fetch : 0 LLM calls on 2nd fetch : 0

You wrote no connector, no schema, no auth glue — Liquid learned the interface for you, and will re-learn it if it changes. That's the point: integrations you don't build or babysit.

Run as an MCP server (open source, self-hosted)

Expose the engine to any MCP client (Claude Desktop, Cursor, Claude Code) — it runsin your own process, no cloud, no account, no lock-in:

One-click in Cursor (the button writes the server into yourmcp.json; add yourOPENAI_API_KEYin Cursor's MCP settings afterward). Or set it up manually:

pip install liquid-api export OPENAI_API_KEY=sk-... # or GEMINI_API_KEY / ANTHROPIC_API_KEY, # or OPENAI_BASE_URL=http://localhost:11434/v1 for local (Ollama/vLLM) liquid-mcp # or: python -m liquid.mcp_server

Zero-install withuvx(theliquid-mcppackage makes the command run by name) — Claude Code:

claude mcp add liquid --scope user -e OPENAI_API_KEY=sk-... -- uvx liquid-mcp

{ "mcpServers": { "liquid": { "command": "uvx", "args": ["liquid-mcp"], "env": { "OPENAI_API_KEY": "sk-..." } } } }

(Or afterpip install liquid-api, dropuvxand use"command": "liquid-mcp"directly.)

One-click in Claude Desktop:install the.mcpbbundle— it prompts for your model key on install (stored in the OS keychain), with no JSON to edit. Requiresuvon the machine.

from liquid import Liquid, InMemoryCache, RateLimiter from liquid._defaults import InMemoryVault, InMemoryAdapterRegistry, CollectorSink from liquid_langchain import LiquidToolkit from langgraph.prebuilt import create_react_agent from langchain_openai import ChatOpenAI liquid = Liquid( llm=my_llm, vault=InMemoryVault(), sink=CollectorSink(), registry=InMemoryAdapterRegistry(), cache=InMemoryCache(), rate_limiter=RateLimiter(), normalize_output=True, # cross-source canonical shapes include_meta=True, # _meta block on every response ) adapter = await liquid.get_or_create( "https://api.shopify.com", target_model={"id": "str", "total_cents": "int", "customer_email": "str"}, credentials={"access_token": "shpat_..."}, auto_approve=True, ) tools = LiquidToolkit(adapter, liquid).get_tools() agent = create_react_agent(ChatOpenAI(model="gpt-4o-mini"), tools) result = await agent.ainvoke( {"messages": [("user", "Find 5 recent orders over $100 from VIP customers")]} )

The agent's tools come with rich descriptions (WHEN to use, NOT FOR what, return shape, cost), structured recovery on every error, and server-side search so it never pulls 500 orders to find 5.

Discovery identifies the target and tags each endpoint with a protocol; a pluggable transport driver runs it — but the agent-facing API (fetch,query,write, mapping, recovery, cache, rate limits) is identical across all of them.

Read and write.liquid.write(adapter, endpoint, op="insert", values={...}, allow_write=True)mutates any database (SQLINSERT/UPDATE/DELETE, Mongo insert/update/delete, RedisSET/HSET/DEL, Neo4j node CRUD); web/agent writes go through verified actions. Identifiers come from introspection and values are parameterized;update/deleterequire awhere(no blanket mutations); writes areoff until you opt inwithallow_write=True.