XPARO Python SDK
================
The **XPARO Python SDK** allows applications, robots, and services to communicate with the XPARO platform.
It provides a simple interface for:
- Sending messages or questions to the XPARO engine
- Receiving responses from the server
- Updating task history
- Managing project configuration
- Automatically syncing behavior files
- Connecting through WebSocket or REST
The SDK is designed to run inside:
- robots
- backend services
- automation systems
- local applications
---
Installation
------------
Install the required dependency:
.. code-block:: bash
pip install websocket-client
Then install the XPARO package.
Example:
.. code-block:: bash
pip install xparo
Or install from source.
---
Basic Usage
-----------
Import the SDK and create an engine instance.
.. code-block:: python
from xparo import Engine
xp = Engine(
project_id="your_project_id",
secret_key="your_secret_key"
)
After creating the engine, connect it to the server.
.. code-block:: python
xp.connect()
The connection will run in the background.
---
Connection Types
----------------
The SDK supports two communication methods.
**WebSocket (recommended)**
Real-time communication with the server.
.. code-block:: python
xp = Engine(
project_id="project_id",
secret_key="secret_key",
connection_type="websocket"
)
**REST API**
Used when real-time connection is not required.
.. code-block:: python
xp = Engine(
project_id="project_id",
secret_key="secret_key",
connection_type="rest"
)
---
Sending Messages
----------------
Applications can send text messages to the XPARO engine.
Example:
.. code-block:: python
xp.send("Hello robot")
The message is processed by the XPARO engine and a response is returned.
---
Receiving Responses
-------------------
Responses from the XPARO engine are received through a callback function.
Example:
.. code-block:: python
def response_handler(message, **kwargs):
print(message)
xp.call_message = response_handler
Whenever the server sends a response, the callback function will be executed.
Example output:
::
Hello, how can I help you?
Applications can use this response for:
- text-to-speech
- UI display
- command execution
- logging
---
Receiving JSON Messages
-----------------------
Some responses are sent as structured JSON data.
To handle these messages, use another callback.
Example:
.. code-block:: python
def json_handler(data, **kwargs):
print(data)
xp.call_json = json_handler
Example message:
::
{"intent":"navigate","target":"table_5"}
This is useful for:
- navigation commands
- task instructions
- UI dashboards
---
Updating Task History
---------------------
Applications can send task updates to the XPARO platform.
Example:
.. code-block:: python
xp.add_task_history({
"task": "delivery",
"status": "completed"
})
This information is stored in the XPARO database and can be viewed from the dashboard.
Typical uses:
- delivery status
- robot actions
- mission tracking
---
Configuration Files
-------------------
The SDK automatically manages several configuration files.
These files are stored inside the project folder.
Example structure:
::
project_folder/
├── config/
│ ├── default.xml
│ ├── default.env
│ ├── default.txt
│ └── properties.txt
├── custom_behaviors/
└── database/
These files are automatically updated when the server sends new behavior data.
Users normally do not need to modify them manually.
---
Behavior Files
--------------
Behavior files define how the XPARO engine responds to different situations.
The server can automatically update these files.
The main behavior file is:
::
config/default.xml
Robots or applications can use this file to execute behavior logic locally.
---
Complete Example
----------------
A minimal example program:
.. code-block:: python
from xparo import Engine
def handle_response(message, **kwargs):
print("Response:", message)
xp = Engine(
project_id="your_project_id",
secret_key="your_secret_key"
)
xp.call_message = handle_response
xp.connect()
xp.send("Hello")
Expected output:
::
Response: Hello, how can I help you?
---
Checking Connection
-------------------
When the connection is successful, the SDK will begin receiving messages from the server.
If the server is unavailable, messages will be queued and sent later.
---
Typical Workflow
----------------
1. Create an Engine instance.
::
xp = Engine(project_id="project_id", secret_key="secret")
2. Connect to the server.
::
xp.connect()
3. Send messages.
::
xp.send("Hello")
4. Receive responses using callbacks.
---
Troubleshooting
---------------
Connection not working
^^^^^^^^^^^^^^^^^^^^^^
Check the following:
- internet connection
- correct project_id
- correct secret_key
---
Messages not received
^^^^^^^^^^^^^^^^^^^^^
Make sure the callback function is assigned before connecting.
Example:
.. code-block:: python
xp.call_message = handler
xp.connect()
---
Support
-------
Website
::
https://xparo-website.onrender.com
GitHub
::
https://github.com/lazyxcientist
Contact
::
xpassistantpersonal@gmail.com
.. raw:: html
.. raw:: html
.. raw:: html
