nikki-python 2.2.3

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)

    # Core data callback
    def onData(data):
        print("📨 Data received:", data)

    # Service response callback
    def onResponseData(data):
        print("📥 Received response:", data)

    # Agent realtime update callbacks
    def onAgentDataEventUpdate(data):
        print("🤖 Agent data event:", data)

    def onAgentPlanUpdate(data):
        print("📋 Agent plan event:", data)

    # Assign callbacks
    client.onData = onData
    client.onResponseData = onResponseData
    client.onAgentDataEventUpdate = onAgentDataEventUpdate
    client.onAgentPlanUpdate = onAgentPlanUpdate

    await client.connect()

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

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

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

Event Callbacks

# General & Connection
client.onConnect
client.onDisconnect
client.onError
client.onData

# Service Response
client.onResponseData

# Agent Realtime Updates
client.onAgentDataEventUpdate
client.onAgentPlanUpdate

Example Usage

def onResponseData(data):
    print("Received response", data)

def onAgentDataEventUpdate(data):
    print("Agent data event", data)

def onAgentPlanUpdate(data):
    print("Agent plan event", data)

client.onResponseData = onResponseData
client.onAgentDataEventUpdate = onAgentDataEventUpdate
client.onAgentPlanUpdate = onAgentPlanUpdate

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

License

MIT License