Metadata-Version: 2.4
Name: nilstanny-xs
Version: 0.3.0
Summary: Ultra-lightweight Claude-like AI agent for ARM devices
Author: NILstanny Team
License: Apache-2.0
Project-URL: Homepage, https://github.com/nilstanny/nilstanny-xs
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: openai>=1.0.0
Dynamic: license-file

# NILstanny-xs

**Ultra-lightweight Claude-like AI agent** (XS edition)  
**Recommended for ARM devices**

## Installation

```bash
pip install nilstanny-xs
```

### Optional

```bash
pip install "nilstanny-xs[advanced]"
```

## Usage

### Basic (zero-dependency, trainable brain)

```python
from nilstanny_xs import NILstannyXS

ai = NILstannyXS()

# Train single fact
ai.train("raspberry pi", "Excellent device for running NILstanny-xs on ARM!")
print(ai.chat("raspberry pi"))

# Batch training with proximity matching for typos
ai.train_batch([
    ("hello", "Hey there! What can I do for you?"),
    ("openai", "Advanced mode uses OpenAI's API for real LLM responses."),
])
print(ai.chat("helo"))
```

### Import / Export knowledge

```python
# knowledge.txt lines look like:
# key => value
ai.train_from_file("knowledge.txt", delimiter="=>")

ai.export_knowledge("backup.json")
ai.import_knowledge("backup.json", merge=True)
ai.clear_brain()
print(ai.stats())
```

### Advanced AI (OpenAI)

```python
from nilstanny_xs import NILstannyXSAdvanced

ai = NILstannyXSAdvanced(api_key="sk-...", model="gpt-4o")
reply = ai.chat("Write a Python web server for ARM")
print(reply)

ai.reset()
print(ai.history())
ai.save_conversation("chat.json")
```

Requirements: `openai` package + `OPENAI_API_KEY` env var or `--api-key`.

## CLI(run in terminal)

```bash
nilstanny-xs
nilstanny-xs "hello"
nilstanny-xs --advanced --api-key sk-... "say hi"
nilstanny-xs --train "raspberry pi=>Excellent device for ARM!"
nilstanny-xs --train-file knowledge.txt
nilstanny-xs --stats
nilstanny-xs --export-knowledge backup.json
```

Interactive commands in REPL: `:help`, `:train`, `:train batch`, `:import`, `:export`, `:stats`, `:history`, `:reset`, `:quit`.

### Knowledge file format

```text
# comments allowed
hello => Hey there!
raspberry pi => Great ARM device
```

## Publishing to PyPI

```bash
uv build
uv publish
```

## Features
- **Basic**: zero dependencies, trainable brain, fuzzy match, import/export, stats
- **Advanced**: real LLM via OpenAI with conversation memory
- **CLI**: REPL + direct messages + train/import/export via flags
- Optimized for ARM / edge devices

Open source under Apache 2.0.
