engini

Agent-first Python SDK for the Engini Public API — discover tools, execute them against your connected apps, and wrap them as LLM tool definitions.

pip install engini

Quickstart

from engini import Engini

client = Engini(api_key="eng_…")  # or set ENGINI_API_KEY

# Discover canonical tool schemas
tools = client.tools.get(applications=["salesforce"], search="accounts", limit=5)

# Execute a tool against a connection
conn_id = next(c.connection_id for c in client.connections.list(application="salesforce"))
result = client.tools.execute(
    "salesforce_getrecords", {"sobject": "Account"}, connection_id=conn_id
)
print(result.output)

JWT auth is the fallback: Engini(token="<jwt>", company_token="<id>"), or set ENGINI_API_TOKEN / ENGINI_COMPANY_TOKEN. With an API key the company is bound to the key, so no company token is needed. Point at another host with Engini(..., base_url=…).

Every request carries a User-Agent identifying this SDK and its runtime (e.g. engini-sdk-python/0.13.0 python/3.11.6 darwin). If you're embedding the SDK inside your own product, prepend your own token with user_agent_prefix:

client = Engini(api_key="eng_…", user_agent_prefix="my-product/1.4.0")
# -> "my-product/1.4.0 engini-sdk-python/0.13.0 python/3.11.6 darwin"

user_agent_prefix only prepends a token — it can't override or remove the SDK's own identity.

Use with an LLM

Provider adapters wrap canonical schemas into vendor tool definitions client-side, with no vendor SDK dependency. OpenAI is the default; Anthropic is also available.

# Bind applications → connections once, then drive a tool-calling loop
toolset = client.toolset(tools=["salesforce_getrecords"], connections={"salesforce": "Prod"})

openai_tools = client.provider.wrap_tools(toolset.tools())  # plain OpenAI tool-JSON dicts
# … send openai_tools to the model, get a response …
results = toolset.handle_tool_calls(llm_response)  # runs the calls, returns results

client.toolset(...) builds a local toolset (no I/O until used) or loads a server one via toolset_id=….

Files

Tools whose input_schema marks a field "format": "engini/file" accept files. Wrap a file with engini.File and pass it as the field value — the SDK base64-encodes it into the {base64_content, mime_type, filename} wire shape. A field can take a single file or a list, per the tool's schema.

from engini import Engini, File

client = Engini(api_key="eng_…")
client.tools.execute(
    "doc_summarize",
    {
        "document": File.from_path("report.pdf"),  # single file
        "attachments": [File.from_path("a.png"), File.from_path("b.png")],  # list of files
    },
    connection_id=conn_id,
)

File.from_path infers the filename and mime type; File.from_bytes(data, filename=…, mime_type=…) and File.from_base64(…) cover in-memory content.

In the LLM loop an agent can't produce base64, so file fields are presented to it as string fields. Register the files you'll allow and let the model reference one by key:

results = toolset.handle_tool_calls(llm_response, files={"report": File.from_path("report.pdf")})

What this adds over the raw REST client

Built on the autogenerated engini-client, the SDK adds what the generated client deliberately lacks: typed errors (the EnginiError family), retry/backoff, auto-pagination, pluggable auth (ApiKeyAuth / BearerAuth), Provider adapters for OpenAI/Anthropic, and the ergonomic Toolset object.

Command-line interface

The engini CLI is npm-only now: npm install -g @engini/cli. See https://www.npmjs.com/package/@engini/cli (or ts/packages/cli/README.md in the source repo) for install, commands, and the machine-readable output/exit-code contract. This package (engini, PyPI) is the Python SDK only.

Source & docs: https://github.com/engini/engini-sdk