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 brain
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:
pip install websocket-client
Then install the XPARO package.
Example:
pip install xparo
Or install from source.
—
Basic Usage
Import the SDK and create an engine instance.
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.
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.
xp = Engine(
project_id="project_id",
secret_key="secret_key",
connection_type="websocket"
)
REST API
Used when real-time connection is not required.
xp = Engine(
project_id="project_id",
secret_key="secret_key",
connection_type="rest"
)
—
Sending Messages
Applications can send text messages to the XPARO brain.
Example:
xp.send("Hello robot")
The message is processed by the XPARO brain and a response is returned.
—
Receiving Responses
Responses from the XPARO brain are received through a callback function.
Example:
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:
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:
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 brain 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:
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
Create an Engine instance.
xp = Engine(project_id="project_id", secret_key="secret")
Connect to the server.
xp.connect()
Send messages.
xp.send("Hello")
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:
xp.call_message = handler
xp.connect()
—
Support
Website
https://xparo-website.onrender.com
GitHub
https://github.com/lazyxcientist
Contact
xpassistantpersonal@gmail.com
