Skip to main content

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.mcp inspects and maintains the account's MCP servers — the endpoints Engini exposes over the Model Context Protocol:

servers = client.mcp.list()  # includes deactivated ones
client.mcp.deactivate(servers[0].mcp_server_token)  # reversible; sends only is_active
tools = client.mcp.available_tools(token, connection_id=2139)  # candidates for tool_slugs

update() replaces connections/workflows rather than merging them, and every connection entry needs an explicit connection_id (MCP servers are account-wide, so there is no per-user default). There is no create/delete: those stay in the engini.io UI.

client.opa provisions, inspects, configures and credentials on-premise agents — the Engini component a customer installs behind their own firewall to reach SQL Server, Oracle, Priority ERP and file shares:

# Provision one and hand the token to the installer
agent = client.opa.create("Warehouse SQL", pull_period_seconds=30)
print(agent.token)  # a credential - store it, do not log it

# Later: is it healthy?
a = client.opa.get(agent.agent_id)
print(a.status, a.version, a.last_seen_at)

# Change its log level; the agent picks it up on its next poll
r = client.opa.update(agent.agent_id, log_level="Debug")
if not r.applied_to_agent:
    print("stored; the agent is not Online yet")

An agent polls Engini, so anything that "talks to" it waits for its next poll. update() merges — an omitted keyword leaves that field alone, unlike connections.update(), which replaces its whole field map. Settings you omit take the server's defaults, and the minimums come from the connector's own declared metadata rather than the client. Agents are not connections: client.connections never returns them.

client.triggers is the event side of the platform: a trigger instance (ti_…) watches a connected system and captures events, which Engini POSTs to a destination you register.

# What can be triggered, then one instance of it
types = client.triggers.types.list(application_slug="monday")
trigger = client.triggers.create("monday_item_created", connection_name="prod")
client.triggers.enable(trigger.id)

# Where events are delivered. The secret is shown once - store it, never log it.
created = client.triggers.destinations.create("primary", "https://acme.test/hooks/engini")
signing_secret = created.signing_secret

Verify a delivery in your web handler. verify_webhook raises rather than returning a bool — a bool is silently ignorable, which is the one failure mode a signature check cannot afford — and hands back the parsed event so it is one call, not two:

from engini import verify_webhook
from engini.errors import EnginiWebhookSignatureError


def handle(request):  # raw bytes, not a re-serialised body
    try:
        event = verify_webhook(request.body, request.headers.get("X-Engini-Signature"), secret)
    except EnginiWebhookSignatureError:
        return 400
    ...  # dedupe on the X-Engini-Event-Id header

For local development subscribe() reads the same events as a blocking stream. It resumes by itself, which is not a nicety: the gateway caps every connection at one hour of wall-clock time, and the cut arrives as a truncated body with no goodbye. It reconnects from the last event you saw, and stops hard only where a gap would otherwise go unnoticed — a revoked stream, or a cursor the server has already pruned.

for event in client.triggers.subscribe(trigger_id=trigger.id):
    print(event["id"], event["payload"])
    # `event["delivery"]` is always "pending" on the stream - it is not a delivery
    # state. Use client.triggers.events.get(event["id"]) for the real one.

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

Metadata

Release files for engini 0.24.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 engini 0.24.0
File Size Uploaded Provenance Actions
engini-0.24.0.tar.gz 78.8 kB With provenance Details for engini-0.24.0.tar.gz

Built distribution (wheel)

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

Total release size: 135.5 kB

Release files / engini-0.24.0.tar.gz

Download URL engini-0.24.0.tar.gz
Size 78.8 kB
Tags Source
SHA-256 checksum
How to use checksums
41e86253a8e98673095b2205da0392b74651fccbe69e19af93039386b398466e
BLAKE2b-256 checksum
How to use checksums
d75bdc8f7e74befddcd36c5b32d3454c5a3e69c7f87a620bb0f607129bf1eda8
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 30, 2026.

Transparency log

Release files / engini-0.24.0-py3-none-any.whl

Download URL engini-0.24.0-py3-none-any.whl
Size 56.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
58ecf7c0c7974c0b15f3508f3120f183354cc0a66b09e7464b671530a7738722
BLAKE2b-256 checksum
How to use checksums
04a91afbe2e369f24e5247dc942f57b2336b1775d782b1dafbed78496cd05d71
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 30, 2026.

Transparency log

Security for engini 0.24.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.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for engini-0.24.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 30, 2026.

Transparency log

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

0.24.0 This release

2 release files Full 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