Metadata-Version: 2.4
Name: nikki_python
Version: 2.2.2
Summary: Python SDK for Nikki Services, PlayStore and Agent APIs.
Author-email: dev nikki <dev.nikki.build@gmail.com>
License: MIT License
Project-URL: Homepage, https://github.com/nikki-build/nikki.python
Project-URL: Repository, https://github.com/nikki-build/nikki.python
Project-URL: Issues, https://github.com/nikki-build/nikki.python/issues
Keywords: nikki,sdk,websocket,agent,playstore,automation
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
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: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Internet
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.31.0
Requires-Dist: urllib3>=2.0.0
Requires-Dist: websockets>=12.0
Dynamic: license-file

# 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

```bash
pip install nikki_python
```

## Project Structure

Place these configuration files in your project directory:

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

Or specify a custom location using:

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

## Quick Start

```python
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

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

# Service Response
client.onResponseData

# Agent Realtime Updates
client.onAgentDataEventUpdate
client.onAgentPlanUpdate
```

### Example Usage

```python
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
```python
await client.send({
    "state": True
})
```

### Fire-and-forget
Safe to call from callbacks.
```python
client.send_nowait({
    "state": True
})
```

## Agent API

The SDK includes a wrapper around Nikki Agent APIs.

### Get Current Plan
```python
plan = client.getPlan()
print(plan)
```

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

## PlayStore API

### Store JSON
```python
result = client.storeJson({
    "name": "Nikki",
    "version": "2.2.0"
})
```

### Upload File
```python
result = client.storeFile(
    "example.pdf"
)
```

### Retrieve Store
```python
store = client.getStore()
print(store)
```

Retrieve the complete store:
```python
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](https://nikki.build)**

## GitHub

👉 **[https://github.com](https://github.com)**

## License

[MIT License](LICENSE)
