nikki-python 2.2.1

Python SDK for Nikki Services, PlayStore and Agent APIs.

Nikki Python SDK

A simple Python SDK for building Nikki Services, communicating over WebSockets, interacting with the PlayStore, and executing Agent workflows.

Features

• 🚀 Simple async WebSocket client
• 🔄 Automatic reconnect (optional)
• 📄 Automatic loading of serviceDef.json and serviceToken.json
• ✅ Strict configuration validation
• 📨 Event-based callbacks
• ⚡ Async and non-blocking message sending
• 🛡️ Built-in rate limiting and payload protection
• 🤖 Agent API support
  • Execute plans
  • Get current execution plan
• 📦 PlayStore API support
  • Store JSON data
  • Upload files
  • Retrieve stored data

Installation

pip install nikki_python

Project Structure

Place these configuration files in your project directory:

project/
│
├── serviceDef.json
├── serviceToken.json
└── app.py

Or specify a custom location using:

client = nikkiServiceBase(base_path="path/to/config")

Quick Start

import asyncio
from nikki_python.nikki_client import nikkiServiceBase

async def main():
    client = nikkiServiceBase(auto_reconnect=True)

    client.onConnect = lambda _: print("✅ Connected")
    client.onDisconnect = lambda d: print("❌ Disconnected", d)
    client.onError = lambda e: print("⚠️ Error", e)

    def onData(data):
        print("📨", data)
        # Example reply
        # client.send_nowait({"state": True})

    client.onData = onData

    await client.connect()

    await client.send({
        "state": True
    })

    await asyncio.sleep(30)
    await client.disconnect()

if __name__ == "__main__":
    asyncio.run(main())

Event Callbacks

client.onConnect
client.onDisconnect
client.onError
client.onData

Example

def onData(data):
    print(data)

client.onData = onData

Sending Data

Async

await client.send({
    "state": True
})

Fire-and-forget

Safe to call from callbacks.

client.send_nowait({
    "state": True
})

Agent API

The SDK includes a wrapper around Nikki Agent APIs.

Get Current Plan

plan = client.getPlan()
print(plan)

Execute Actions

result = client.execute(
    actions=[
        {
            "type": "speak",
            "text": "Hello!"
        }
    ],
    desc="Greeting user"
)
print(result)

PlayStore API

Store JSON

result = client.storeJson({
    "name": "Nikki",
    "version": "2.2.0"
})

Upload File

result = client.storeFile(
    "example.pdf"
)

Retrieve Store

store = client.getStore()
print(store)

Retrieve the complete store:

store = client.getStore(fullStore=True)

Configuration

The SDK automatically loads:

• serviceDef.json
• serviceToken.json

from the current working directory unless base_path is provided.

Requirements

• Python 3.8+
• serviceDef.json
• serviceToken.json

Official Website

Documentation, Playground and API Reference:
👉 https://nikki.build

GitHub

👉 https://github.com/nikki-build/nikki.python

License

MIT License