kryten-llm 0.1.1__tar.gz

kryten_llm-0.1.1/INSTALL.md

@@ -0,0 +1,212 @@
+# Installation Guide
+
+## Prerequisites
+
+- Python 3.10 or higher
+- Poetry (Python package manager)
+- NATS server (running and accessible)
+- Git
+
+## Quick Start
+
+### 1. Clone the Repository
+
+```bash
+git clone https://github.com/grobertson/kryten-llm.git
+cd kryten-llm
+```
+
+### 2. Install Dependencies
+
+```bash
+poetry install
+```
+
+### 3. Configure the Service
+
+Copy the example configuration:
+
+```bash
+cp config.example.json config.json
+```
+
+Edit `config.json` with your settings:
+
+```json
+{
+  "nats_url": "nats://localhost:4222",
+  "nats_subject_prefix": "cytube",
+  "service_name": "kryten-llm"
+}
+```
+
+### 4. Run the Service
+
+**Development mode:**
+
+```bash
+poetry run kryten-llm --config config.json --log-level DEBUG
+```
+
+**Using startup script (PowerShell):**
+
+```powershell
+.\start-llm.ps1
+```
+
+**Using startup script (Bash):**
+
+```bash
+./start-llm.sh
+```
+
+## Production Installation
+
+### System User Setup
+
+Create a dedicated system user:
+
+```bash
+sudo useradd -r -s /bin/false -d /opt/kryten-llm kryten
+```
+
+### Installation Directory
+
+```bash
+sudo mkdir -p /opt/kryten-llm
+sudo chown kryten:kryten /opt/kryten-llm
+```
+
+### Configuration Directory
+
+```bash
+sudo mkdir -p /etc/kryten/llm
+sudo chown kryten:kryten /etc/kryten/llm
+sudo cp config.example.json /etc/kryten/llm/config.json
+sudo chown kryten:kryten /etc/kryten/llm/config.json
+sudo chmod 600 /etc/kryten/llm/config.json
+```
+
+Edit the configuration:
+
+```bash
+sudo nano /etc/kryten/llm/config.json
+```
+
+### Log Directory
+
+```bash
+sudo mkdir -p /var/log/kryten-llm
+sudo chown kryten:kryten /var/log/kryten-llm
+```
+
+### Install Application
+
+```bash
+cd /opt/kryten-llm
+sudo -u kryten git clone https://github.com/grobertson/kryten-llm.git .
+sudo -u kryten poetry install --no-dev
+```
+
+### Systemd Service
+
+Install the systemd service:
+
+```bash
+sudo cp systemd/kryten-llm.service /etc/systemd/system/
+sudo systemctl daemon-reload
+sudo systemctl enable kryten-llm
+sudo systemctl start kryten-llm
+```
+
+Check service status:
+
+```bash
+sudo systemctl status kryten-llm
+sudo journalctl -u kryten-llm -f
+```
+
+## Updating
+
+### Development
+
+```bash
+git pull
+poetry install
+```
+
+### Production
+
+```bash
+cd /opt/kryten-llm
+sudo systemctl stop kryten-llm
+sudo -u kryten git pull
+sudo -u kryten poetry install --no-dev
+sudo systemctl start kryten-llm
+```
+
+## Troubleshooting
+
+### Check NATS Connection
+
+Ensure NATS server is running:
+
+```bash
+# Check if NATS is listening
+netstat -tuln | grep 4222
+```
+
+### View Logs
+
+```bash
+# Systemd service logs
+sudo journalctl -u kryten-llm -f
+
+# Check for errors
+sudo journalctl -u kryten-llm --since "1 hour ago" | grep -i error
+```
+
+### Test Configuration
+
+```bash
+# Validate JSON syntax
+python -m json.tool config.json
+
+# Test connection manually
+poetry run kryten-llm --config config.json --log-level DEBUG
+```
+
+### Permissions Issues
+
+Ensure correct ownership:
+
+```bash
+sudo chown -R kryten:kryten /opt/kryten-llm
+sudo chown -R kryten:kryten /etc/kryten/llm
+sudo chown -R kryten:kryten /var/log/kryten-llm
+```
+
+## Uninstalling
+
+### Stop and Disable Service
+
+```bash
+sudo systemctl stop kryten-llm
+sudo systemctl disable kryten-llm
+sudo rm /etc/systemd/system/kryten-llm.service
+sudo systemctl daemon-reload
+```
+
+### Remove Files
+
+```bash
+sudo rm -rf /opt/kryten-llm
+sudo rm -rf /etc/kryten/llm
+sudo rm -rf /var/log/kryten-llm
+```
+
+### Remove User
+
+```bash
+sudo userdel kryten
+```

kryten_llm-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Kryten Robot Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

kryten_llm-0.1.1/PKG-INFO

@@ -0,0 +1,271 @@
+Metadata-Version: 2.4
+Name: kryten-llm
+Version: 0.1.1
+Summary: Kryten LLM integration service - provides AI chat responses and interactions
+License: MIT
+License-File: LICENSE
+Keywords: cytube,moderation,chat,nats,microservices
+Author: Kryten Robot Team
+Requires-Python: >=3.10,<4.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+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: Programming Language :: Python :: 3.14
+Classifier: Topic :: Communications :: Chat
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Dist: aiohttp (>=3.13.2,<4.0.0)
+Requires-Dist: emoji (>=2.15.0,<3.0.0)
+Requires-Dist: kryten-py (>=0.6.0,<0.7.0)
+Requires-Dist: pydantic (>=2.12.5,<3.0.0)
+Requires-Dist: pydantic-settings (>=2.12.0,<3.0.0)
+Project-URL: Documentation, https://github.com/grobertson/kryten-llm/blob/main/README.md
+Project-URL: Homepage, https://github.com/grobertson/kryten-llm
+Project-URL: Repository, https://github.com/grobertson/kryten-llm
+Description-Content-Type: text/markdown
+
+# Kryten LLM
+
+AI-powered chat bot service for CyTube, part of the Kryten ecosystem.
+
+## Features
+
+- **Trigger-Based Responses**: Configurable trigger words with probabilities
+- **Direct Mentions**: Responds when mentioned by name
+- **LLM Integration**: Multiple LLM provider support (OpenAI, OpenRouter, local)
+- **Rate Limiting**: Per-user, per-trigger, and global rate limits
+- **Spam Detection**: Automatic spam detection with exponential backoff penalties
+- **Context Awareness**: Tracks chat history and video context
+- **Hot-Reload**: Reload configuration without restart (SIGHUP)
+- **Service Discovery**: Publishes heartbeats and responds to discovery polls
+- **Dry-Run Mode**: Test responses without sending to chat
+
+## Requirements
+
+- Python 3.10+
+- Poetry
+- NATS server
+- kryten-py library
+
+## Installation
+
+### Using Poetry
+
+```bash
+# Install dependencies
+poetry install
+
+# Copy example configuration
+cp config.example.json config.json
+
+# Edit configuration with your settings
+# See config.example.json for all options
+```
+
+### Using pip
+
+```bash
+pip install kryten-llm
+```
+
+## Configuration
+
+Configuration is stored in a JSON file. See `config.example.json` for a complete example.
+
+### Key Sections
+
+| Section | Description |
+|---------|-------------|
+| `nats` | NATS connection settings |
+| `channels` | CyTube channel connections |
+| `personality` | Bot character and behavior |
+| `llm_providers` | LLM API configurations |
+| `triggers` | Trigger words with patterns and probabilities |
+| `rate_limits` | Rate limiting rules |
+| `spam_detection` | Spam detection settings |
+| `testing` | Dry-run and logging options |
+
+### Environment Variables
+
+Override configuration with environment variables:
+
+```bash
+export OPENROUTER_API_KEY="your-api-key"
+export KRYTEN_LLM_DRY_RUN="true"
+```
+
+## Usage
+
+### Running the Service
+
+```bash
+# Using Poetry
+poetry run kryten-llm --config config.json
+
+# Direct Python execution
+python -m kryten_llm --config config.json
+```
+
+### Command Line Options
+
+| Option | Description |
+|--------|-------------|
+| `--config PATH` | Path to configuration file (default: `config.json`) |
+| `--log-level LEVEL` | Logging level: DEBUG, INFO, WARNING, ERROR |
+| `--dry-run` | Generate responses but don't send to chat |
+| `--validate-config` | Validate configuration and exit |
+
+### Validation Mode
+
+Validate your configuration without starting the service:
+
+```bash
+poetry run kryten-llm --config config.json --validate-config
+```
+
+### Dry-Run Mode
+
+Test responses without sending to chat:
+
+```bash
+poetry run kryten-llm --config config.json --dry-run
+```
+
+## Hot-Reload (POSIX)
+
+Reload configuration without restarting the service:
+
+```bash
+# Send SIGHUP to reload configuration
+kill -HUP $(pgrep -f kryten_llm)
+```
+
+Safe changes that can be hot-reloaded:
+- Triggers (patterns, probabilities, enabled status)
+- Rate limits
+- Spam detection settings
+- Personality configuration
+- LLM provider settings
+
+Unsafe changes (require restart):
+- NATS connection settings
+- Channel configuration
+- Service name
+
+## Production Deployment
+
+### Systemd Service
+
+Install the systemd service file:
+
+```bash
+# Copy service file
+sudo cp kryten-llm.service /etc/systemd/system/
+
+# Create config directory
+sudo mkdir -p /etc/kryten-llm
+sudo cp config.json /etc/kryten-llm/
+
+# Create log directory
+sudo mkdir -p /var/log/kryten-llm
+sudo chown kryten:kryten /var/log/kryten-llm
+
+# Enable and start service
+sudo systemctl daemon-reload
+sudo systemctl enable kryten-llm
+sudo systemctl start kryten-llm
+```
+
+### Service Management
+
+```bash
+# Check status
+sudo systemctl status kryten-llm
+
+# View logs
+sudo journalctl -u kryten-llm -f
+
+# Reload configuration
+sudo systemctl reload kryten-llm
+
+# Restart service
+sudo systemctl restart kryten-llm
+```
+
+## Development
+
+### Running Tests
+
+```bash
+# Run all tests
+poetry run pytest
+
+# Run with coverage
+poetry run pytest --cov=kryten_llm
+
+# Run specific test file
+poetry run pytest tests/test_trigger_engine.py -v
+```
+
+### Code Quality
+
+```bash
+# Linting
+poetry run ruff check .
+
+# Formatting
+poetry run black .
+
+# Type checking
+poetry run mypy kryten_llm
+```
+
+## Architecture
+
+The service processes messages through a pipeline:
+
+```
+Chat Message
+    ↓
+MessageListener (parse/filter)
+    ↓
+TriggerEngine (detect triggers/mentions)
+    ↓
+RateLimiter (check rate limits)
+    ↓
+SpamDetector (check spam)
+    ↓
+ContextManager (gather context)
+    ↓
+PromptBuilder (build LLM prompt)
+    ↓
+LLMManager (call LLM API)
+    ↓
+ResponseValidator (validate response)
+    ↓
+ResponseFormatter (format for chat)
+    ↓
+Send to Chat
+```
+
+## Service Discovery
+
+The service publishes:
+
+- **Startup event**: When service starts
+- **Heartbeat**: Every 30s with health status
+- **Shutdown event**: When service stops gracefully
+
+Subscribe to service events:
+- `kryten.lifecycle.llm.startup`
+- `kryten.heartbeat.llm`
+- `kryten.lifecycle.llm.shutdown`
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+