Metadata-Version: 2.4
Name: nikki_python
Version: 2.2.1
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)

    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

```python
client.onConnect
client.onDisconnect
client.onError
client.onData
```

### Example

```python
def onData(data):
    print(data)

client.onData = onData
```

## 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/nikki-build/nikki.python](https://github.com/nikki-build/nikki.python)**

## License

[MIT License](LICENSE)
