Zelinqa Python SDK

The official Python client for Zelinqa. Configure a domain in Zelinqa Studio, publish it, and let the API select the next useful question for each conversation.

Python 3.11+ · Sync and async clients · Typed responses

Install

pip install zelinqa

Set your API key

Create a runtime API key for your published domain in Studio and set it on your backend:

export ZELINQA_API_KEY="YOUR_RUNTIME_API_KEY"

Keep API keys out of browser code, mobile apps, logs and source control.

Get a question and send the reply

This small console example asks one question and submits the person's reply. For choice questions, enter one of the displayed labels exactly.

from zelinqa import ZelinqaClient

with ZelinqaClient() as client:
    session = client.start_session(client_reference="demo-001")
    decision = session.next()

    if decision.action == "ask":
        question = decision.candidates[0]
        print(question.text)
        for choice in question.choices:
            print(f"- {choice.label}")

        reply = input("> ")
        if not reply.strip():
            decision = session.answer(outcome="asked_no_answer")
        elif question.choices:
            decision = session.answer(choice_labels=[reply])
        else:
            decision = session.answer(reply)

        print(decision.action)  # "ask" for another question, or "stop"

The session handle supplies session, decision, question and choice IDs for you. Each answer() records the reply and returns the next decision; do not call next() again just to retrieve that question. Use a session sequentially and store session.id in your backend if you need to resume after a restart.

Open questions need the person's actual words. Choices alone need no model call; free text is analyzed by the engine. Report a real refusal with outcome="refused", or an empty reply with outcome="asked_no_answer". Keep warnings visible and let your application decide when to finish. Once the session reaches max_turns, the decision has action == "stop" and stop_reason == "max_turns_reached"; later calls return the same stop.

What you can do

• Run conversations, resume sessions, add context and record business feedback.
• Use AsyncZelinqaClient with await for asynchronous applications.
• Read questions, edit drafts and publish with ZelinqaConfigurationClient and the corresponding configuration scopes.
• Handle typed errors, configure timeouts and retries, and provide idempotency keys.

Learn more

• Documentation and API reference
• Python guide: choices, async, configuration and errors
• Changelog
• Report an issue

License

Apache-2.0. See LICENSE.