Metadata-Version: 2.4
Name: lua-device-client
Version: 1.2.0
Summary: Connect physical devices to Lua AI agents via MQTT.
Author-email: Lua AI <support@heylua.ai>
License: MIT
Project-URL: Homepage, https://docs.heylua.ai/devices
Project-URL: Repository, https://github.com/lua-ai-global/lua-core-services
Project-URL: Issues, https://github.com/lua-ai-global/lua-core-services/issues
Keywords: lua,device,iot,mqtt,agent,ai,heylua,raspberry-pi
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: paho-mqtt>=2.0
Requires-Dist: httpx>=0.24
Dynamic: license-file

# lua-device-client

Connect physical devices to [Lua AI](https://heylua.ai) agents via MQTT.

## Install

```bash
pip install lua-device-client
```

## Quick Start

```python
import asyncio
from lua_device import DeviceClient, DeviceCommandDefinition

client = DeviceClient(
    agent_id="baseAgent_agent_abc123",
    api_key="api_your_key_here",
    device_name="warehouse-scanner",
    commands=[
        DeviceCommandDefinition(
            name="scan_barcode",
            description="Scan a barcode and return its value",
        ),
        DeviceCommandDefinition(
            name="get_status",
            description="Return device battery and connectivity status",
        ),
    ],
)

async def handle_scan(payload):
    return {"barcode": "ABC-12345", "format": "CODE128"}

async def handle_status(payload):
    return {"battery": 85, "signal": "strong"}

client.on_command("scan_barcode", handle_scan)
client.on_command("get_status", handle_status)

async def main():
    await client.connect()
    print("Device connected!")

    # Fire a trigger to the agent
    ack = await client.trigger("barcode_scanned", {"value": "ABC-12345"})
    print(f"Trigger acknowledged: {ack}")

    # Keep running
    await asyncio.Event().wait()

asyncio.run(main())
```

## Features

- **MQTT transport** -- connects to Lua AI via MQTT (paho-mqtt)
- **Self-describing commands** -- no server config needed
- **CDN uploads** -- upload screenshots and files via `CDN.upload()`
- **Device triggers** -- fire events from device to agent
- **Auto-reconnection** -- exponential backoff
- **Async/await** -- built on asyncio

## MicroPython

For Raspberry Pi Pico W and other MicroPython boards, use the standalone MicroPython client included in `lua_device/micropython.py`. See the [MicroPython docs](https://docs.heylua.ai/devices/micropython-client) for details.

## Documentation

Full documentation: [https://docs.heylua.ai/devices](https://docs.heylua.ai/devices)

## License

MIT
