Python SDK
Official Python client for the LiyaEngine public API.
liyaengine is the official Python client for the API Reference. Requires Python 3.9+.
Early access
This SDK currently covers Collections, Agents, Workflows, and Evaluations, with a synchronous client. See its README for what's next (an async client included).
Install
pip install liyaengineQuickstart
from liyaengine import LiyaEngine
client = LiyaEngine(api_key="liya_...")
collection = client.collections.create(
slug="contracts", label="Contracts", domain_keys=["legal-ops"],
)
collections = client.collections.list()Or as a context manager, which closes the underlying HTTP connection pool automatically:
with LiyaEngine(api_key="liya_...") as client:
collections = client.collections.list()Get an API key from the dashboard under Settings → API Keys.
Error handling
Every failed request raises LiyaEngineAPIError, carrying the API's code, message, and HTTP status:
from liyaengine import LiyaEngineAPIError
try:
client.collections.create(slug="contracts", label="Contracts", domain_keys=["legal-ops"])
except LiyaEngineAPIError as err:
if err.code == "SLUG_CONFLICT":
...
raiseNetwork failures and timeouts raise LiyaEngineNetworkError. Requests retry automatically on 429/5xx responses (2 retries by default).
Configuration
LiyaEngine(
api_key="liya_...",
base_url="https://api.liyaengine.ai", # override for local/staging
timeout_s=30.0,
max_retries=2,
)Collections
client.collections.list()
client.collections.get(id)
client.collections.create(slug=..., label=..., domain_keys=[...])
client.collections.update(id, label=..., tags=[...], visibility=...)
client.collections.delete(id)Full field reference: Collections API.
Agents
client.agents.list()
client.agents.get(agent_key)
client.agents.create(agent_key=..., name=..., goal=...)
client.agents.update(agent_key, name=..., model=...)
client.agents.deploy(agent_key) # activate for execution
client.agents.run(agent_key, input={"message": ...})
client.agents.list_runs(agent_key)
client.agents.list_sessions(agent_key)
client.agents.get_transcript(agent_key, session_id)
client.agents.delete(agent_key)Full field reference: Agents API.
Workflows
client.workflows.list()
client.workflows.get(workflow_id_or_key)
client.workflows.create(name=..., steps=[...])
client.workflows.update(workflow_id_or_key, name=..., steps=[...])
client.workflows.toggle(workflow_id_or_key) # on/off, already-deployed only
client.workflows.deploy(workflow_id_or_key) # draft -> active; mints webhook secret once
client.workflows.rotate_webhook_secret(workflow_id_or_key, grace_period_seconds=300)
client.workflows.run(workflow_id_or_key, input={"email": ...})
client.workflows.list_runs(workflow_id_or_key)
client.workflows.delete(workflow_id_or_key) # hard deletedeploy() and rotate_webhook_secret() return the plaintext webhook secret exactly once — capture it from the response immediately. Full field reference: Workflows API.
Evaluations
A Suite binds a Dataset to one intent; suites.run() calls it for real. runs.submit()/evaluations.score() score a response you already generated yourself.
client.evaluations.datasets.create(name=..., cases=[...])
client.evaluations.suites.create(name=..., domain_key=..., intent_key=..., dataset_id=...)
client.evaluations.suites.run(suite_id) # 202, poll runs.get()
client.evaluations.runs.get(run_id)
client.evaluations.runs.resume(run_id) # only a failed run; already-scored cases are skipped
client.evaluations.runs.compare(run_id_a, run_id_b) # statistical
client.evaluations.score(input=..., output=...) # no dataset/suite requiredFull field reference: Evaluations API.