Skip to content

imandrax-api

Python client for the ImandraX API.

pip install imandrax-api

v1 and v2 clients

imandrax_api.v2 is the new client, with more features and a more ergonomic API. It is the one documented here.

imandrax_api.client (and imandrax_api.Client / imandrax_api.AsyncClient) currently point to the v1 client. They are deprecated and will soon point to v2. To keep using v1, import from imandrax_api.v1.

The ImandraX API client

This package defines the clients together with Python types for what they exchange with ImandraX: requests, responses, tasks and their results, and the terms, types, models, proofs and reports inside them.

Endpoints

Set url to the server you want to connect to:

  • imandrax_api.v2.url_prod (default): Imandra's hosted production server, https://api.imandra.ai/internal/imandrax/
  • imandrax_api.v2.url_dev: Imandra's hosted development server, https://api.dev.imandracapital.com/internal/imandrax/
  • A self-hosted server, e.g. Client(url="http://localhost:8089")

Authentication

The hosted servers need an API key; for a self-hosted server it is optional. Pass it to the client with api_key:

from imandrax_api.v2 import Client, url_prod

with Client(url=url_prod, api_key="your-api-key") as client:
    ...

Examples

Quick start

import os

from imandrax_api.v2 import Client, url_prod
from imandrax_api.v2.interface import InstanceResponse, VerifyResponse

api_key: str | None = os.environ.get("IMANDRAX_API_KEY") or os.environ.get("IMANDRA_UNI_KEY")

with Client(url=url_prod, api_key=api_key) as client:
    # 1. Load IML definitions into the session
    client.eval_src("let f x = if x > 0 then x + 1 else 0")

    # 2. Prove a property for all inputs
    prop1: VerifyResponse = client.verify_src("fun x -> f x >= 0")
    print(prop1.proved)
    #> True

    # 3. Prove a (wrong) property
    prop2: VerifyResponse = client.verify_src("fun x -> f x > x")
    print(prop2.refuted)
    #> True

    # 3.1 Counterexample from the refuted result
    print(prop2.counter_example)
    """
    module M = struct

      let x = 0

    end
    """

    # 4. Find inputs satisfying a goal
    instance_res: InstanceResponse = client.instance_src("fun x -> f x = 43")
    print(instance_res.instance)
    """
    module M = struct

      let x = 42

    end
    """

Region Decomposition

Given a function, region decomposition exhaustively decomposes its input space into disjoint regions, each characterized by a set of constraints and an invariant describing the function's behavior in that region. See Region Decomposition for details.

With prune=True, regions proved empty are removed, and each region proved feasible comes with a sample input and the function's output on it.

import os

from imandrax_api.v2 import Client, url_prod
from imandrax_api.v2.interface import DecompositionResult
from imandrax_api.v2.mir import PyValue, Uid

api_key = os.environ.get("IMANDRAX_API_KEY") or os.environ.get("IMANDRA_UNI_KEY")

with Client(url=url_prod, api_key=api_key) as client:
    client.eval_src("""
let fee amount =
  if amount < 0 then 0
  else if amount < 100 then 5
  else amount / 20
""")

    res: DecompositionResult = client.decompose("fee", prune=True, string_results=True)
    assert res.decomposition is not None, f"decomposition failed: {res.errors}"

    rows: list[tuple[str, str, str, str]] = [("constraints", "invariant", "sample input", "sample output")]
    for region in res.decomposition.regions:
        constraints: str = " && ".join(region.constraints_str or ())
        invariant: str | None = region.invariant_str
        # The sample input is keyed by each variable's unique ID; key it by name instead
        sample: dict[Uid, PyValue] = region.sample() or {}
        sample_input: dict[str, PyValue] = {uid.short_name: value for uid, value in sample.items()}
        sample_output: PyValue | None = region.sample_output()
        rows.append((constraints, str(invariant), str(sample_input), str(sample_output)))

    for row in rows:
        print(f"{row[0]:<30} | {row[1]:<15} | {row[2]:<15} | {row[3]}")
        #> constraints                    | invariant       | sample input    | sample output
        #> amount >= 100                  | amount / 20     | {'amount': 100} | 5
        #> amount >= 0 && amount <= 99    | 5               | {'amount': 0}   | 5
        #> amount <= (-1)                 | 0               | {'amount': -1}  | 0

All at once with eval_src

The steps above can also be written in one IML and run with a single eval_src. The results of theorem, verify and instance statements are in po_results, and those of [@@decomp ...] in decomp_results:

import os

from imandrax_api.v2 import Client, url_prod
from imandrax_api.v2.interface import EvalSrcResponse

api_key = os.environ.get("IMANDRAX_API_KEY") or os.environ.get("IMANDRA_UNI_KEY")

with Client(url=url_prod, api_key=api_key) as client:
    res: EvalSrcResponse = client.eval_src("""
let f x = if x > 0 then x + 1 else 0

theorem f_nonneg x = f x >= 0
theorem f_increasing x = f x > x
instance (fun x -> f x = 43)

let fee amount =
  if amount < 0 then 0
  else if amount < 100 then 5
  else amount / 20
[@@decomp top () |>> prune]
""")

    # For a theorem, `instance` means a counter-example was found
    for po in res.po_results:
        print(po.origin.from_sym, po.outcome)
        #> f_nonneg proof
        #> f_increasing instance
        #> _instance_6_1 instance

    for d in res.decomp_results:
        print(d.success, d.decomposition and len(d.decomposition.regions))
        #> True 3

Async client

AsyncClient has the same methods as Client, as coroutines. It needs optional dependencies and can be installed with pip install 'imandrax-api[async]'.

import asyncio
import os

from imandrax_api.v2 import AsyncClient, url_prod
from imandrax_api.v2.interface import VerifyResponse

api_key: str | None = os.environ.get("IMANDRAX_API_KEY") or os.environ.get("IMANDRA_UNI_KEY")


async def main() -> bool:
    async with AsyncClient(url=url_prod, api_key=api_key) as client:
        await client.eval_src("let f x = x + 1")
        res: VerifyResponse = await client.verify_src("fun x -> f x > x")
        return res.proved


print(asyncio.run(main()))
#> True