Qefro Python Backend SDK
qefro-backend is the Python framework for building Qefro Business Tool
handlers and Business Flows. Register your tools and flows, serve the signed
Qefro webhook, and let the Qefro Runtime orchestrate everything — including
multi-step flows and customer verification.
Wire-compatible with the JavaScript
and Rust SDKs: same signed
protocol, same capabilities.list schema, same 8 flow step types.
Install
pip install qefro-backend
Zero runtime dependencies — it uses only the Python standard library.
Quick start
from qefro_backend import Qefro
app = Qefro(signing_secret="dev-secret") # or QEFRO_SIGNING_SECRET from env
@app.tool("get_orders", auth="required", lookup={"required": ["email"]})
async def get_orders(ctx):
customer = ctx.customer.require()
return [{"orderId": "ord_1", "customerId": customer["id"]}]
app.run(8088) # POST http://0.0.0.0:8088/qefro
Set the same signing secret in Admin Console → Business Tools → SDK
Connections, then Sync Tools. Handlers may be sync or async.
Customer authorization
Register a provider to resolve and verify customers. auth="required" tools
authorize automatically before the handler runs; a challenge outcome pauses
the tool and asks the customer for a code, then resumes.
from qefro_backend import Qefro, CustomerProvider
app = Qefro("dev-secret")
class Customers(CustomerProvider):
async def lookup(self, ctx):
return {"id": ctx.identity.get("phone", "demo")}
async def authorize(self, ctx):
if not ctx.response:
return ctx.auth.sms_otp(ctx.customer["id"], "Enter the code we texted you.")
if ctx.response.strip() != "123456":
return ctx.auth.sms_otp(ctx.customer["id"], "Wrong code, try again.")
return ctx.auth.success(ctx.customer, {"type": "bearer_token", "access_token": "demo"})
app.customer(Customers())
Business Flows
Flows describe how your Business Tools are orchestrated. They are metadata
only — the SDK advertises them through capabilities.list and the Qefro
Runtime discovers, validates, versions, and executes them. Nothing runs inside
the SDK.
(
app.flow({
"id": "order_lookup", # immutable identity — renaming `name` never creates a new flow
"name": "Order Lookup",
"description": "Look up customer orders",
"category": "crm",
"tags": ["customer", "orders"],
"intent": ["track order", "where is my order"],
"inputs": ["email"],
"outputs": ["get_orders"],
})
.ask("email", field="email", prompt="Please enter your email.")
.tool("orders", tool_ref="get_orders")
.complete("done", message="Here are your recent orders.")
)
Every step needs a unique id; tool steps reference an existing Business Tool
by tool_ref. Step builders: .ask() .tool() .challenge() .upload() .condition() .delay() .approval() .complete(). A duplicate/empty flow or step id raises
FlowError. See examples/order-approval for a full
ask → tool → condition → approval → OTP-authenticated tool → complete flow.
Protocol
| Message | Purpose |
|---|---|
ping |
Health / Test Connection |
capabilities.list |
Discover tools and business flows for Sync Tools |
tools.list |
Legacy tool-only discovery (still supported) |
tool.invoke |
Run a handler |
tool.resume |
Continue after a customer challenge reply |
Requests are HMAC-SHA256 signed (X-Qefro-Signature / X-Qefro-Timestamp,
payload v1:<timestamp>:<body>). Responses include X-Qefro-Protocol,
X-Qefro-SDK, and X-Qefro-Version.
Examples
export QEFRO_SIGNING_SECRET=dev-secret
python examples/basic/server.py # ask -> tool -> complete
python examples/order-approval/server.py # condition + approval + OTP-authenticated tool
Docs
Development
pip install -e ".[dev]"
pytest
License
MIT
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file qefro_backend-1.0.0.tar.gz.
File metadata
- Download URL: qefro_backend-1.0.0.tar.gz
- Upload date:
- Size: 13.5 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/6.1.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
8a15261faf5a0aa58e10213dead6c5c093dd552d1e6e28db55063eefa18e3c95
|
|
| MD5 |
d9eac5e58678af8c2bed98d367e5567b
|
|
| BLAKE2b-256 |
45e2c88eb16078b00ff8fc9b8a39d521f370d8265e443e27aa2b1afb5f4bffe0
|
File details
Details for the file qefro_backend-1.0.0-py3-none-any.whl.
File metadata
- Download URL: qefro_backend-1.0.0-py3-none-any.whl
- Upload date:
- Size: 14.2 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/6.1.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
72a356740852a8199715be23f5e353d50ddcda7da848e2ceb9c2cd08d880b7c0
|
|
| MD5 |
c13a6fe92c648753c308c73129479ad2
|
|
| BLAKE2b-256 |
3e9b7611c2877339e000a35ea460bd9cad3bcd485de938850916212a93a6e52d
|
