kryten-llm 0.2.2__py3-none-any.whl

kryten_llm-0.2.2.dist-info/METADATA

@@ -0,0 +1,271 @@
+Metadata-Version: 2.4
+Name: kryten-llm
+Version: 0.2.2
+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.9.4)
+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.
+

kryten_llm-0.2.2.dist-info/RECORD

@@ -0,0 +1,28 @@
+kryten_llm/__init__.py,sha256=d9mOIXiZjLOIdUmq5JQV2We6YQG1k-PqkwjeeeFayAs,565
+kryten_llm/__main__.py,sha256=xXCE70ZpcVcIBJQYDkblyPKZSo5gAolhPf-G6W7a8m8,4711
+kryten_llm/components/__init__.py,sha256=_f77534WF7_FQEJ5S4kwTzGECjL1xKzrlUPT_80FR0I,896
+kryten_llm/components/config_reloader.py,sha256=CZCD1FmWD03VUYL12HLaFR3rLYtacttgc1YDfwYI8yY,10671
+kryten_llm/components/context_manager.py,sha256=8AOeh0qTW8W3LYoTjIc_6OzfoZ7Eew9AAf-9mk1fwPg,7001
+kryten_llm/components/formatter.py,sha256=6Z455HvfMK1hiMdsiw2bq2Yx9N6MElZ_mIv8UcQMzhg,13254
+kryten_llm/components/health_monitor.py,sha256=fz1cbNw87WdQ9HENHeS_pY_csDPPEAAFKbXe7xZerGA,9281
+kryten_llm/components/heartbeat.py,sha256=aPjRZLDvZAVI_lr-qgYRfAl-dvmCVtPtfJFAlL-dNyc,3887
+kryten_llm/components/listener.py,sha256=qIUzOvrxRAyDYlpidP58kBV2FI5BqykxZvMUIOe_Hr8,2590
+kryten_llm/components/llm_manager.py,sha256=Weow6xd3c5IDYcjFgmjMuTtqBWEV6OneFwNPBZSr2dg,13237
+kryten_llm/components/prompt_builder.py,sha256=SBgtCKP3v2pkBEvszX1n64AbjJMctLdBQT8Zb6lh9gM,5671
+kryten_llm/components/rate_limiter.py,sha256=K77h7O7rU9llc2saY8Kol74Fpz-57-0V4l9gFVqVUMs,18271
+kryten_llm/components/response_logger.py,sha256=LVaqp_FQvCEhGFbE_VqKX9SgNLIhT9FlzhrKd0kO3XI,3879
+kryten_llm/components/spam_detector.py,sha256=40Zxg53U-ACSJkfG71gP8a8iR8sQ7wBd23eGB5jwkHg,14036
+kryten_llm/components/trigger_engine.py,sha256=RGQn6PJ_V5RMsZavqKKbG7LlSSK4sL5p8P2r2tu9dkY,10472
+kryten_llm/components/validator.py,sha256=oR0jp-iH-gOeR3GWVp5AxaeauEFPjN8iUN_JOUN8tzs,9586
+kryten_llm/config.py,sha256=qLJdaNt46vId0Yx8RS5kN80sTYaAwFzqkgMT-WhvhMQ,3132
+kryten_llm/models/__init__.py,sha256=743neYCwAB2FVZwy1aE4TafFw1otYJGKyhkPer2yz_4,494
+kryten_llm/models/config.py,sha256=BA4PSKAiJlf9pHIrHoRhIZs8ovK6tKnmGU13CWHD1hE,20269
+kryten_llm/models/events.py,sha256=kwC1EngFdKUFHLyG2hafC4se25nlb9LkaKUHCq5MfW0,371
+kryten_llm/models/phase3.py,sha256=QXOgI7PTGVKonnXVdREUmWfYWlX8fPQWTXpP-Vw0AF0,1318
+kryten_llm/service.py,sha256=KjMfufmHSUIYIMhzn0m1tho5wPQjlM0Z4PF6sO6qfd8,22247
+kryten_llm/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+kryten_llm-0.2.2.dist-info/entry_points.txt,sha256=bbnT67yByV9T1FSfv5hPYgEG1zgdS2_s_UXm6cej0lk,55
+kryten_llm-0.2.2.dist-info/licenses/LICENSE,sha256=4-aY9N48r38gULWwGnXZB0cFBoTcFneVGswDSK2bVi4,1095
+kryten_llm-0.2.2.dist-info/METADATA,sha256=rYY-_VziVdTfwGrSqRMiEj4lNaI_aRQqVRUXDEr5HaU,6277
+kryten_llm-0.2.2.dist-info/WHEEL,sha256=zp0Cn7JsFoX2ATtOhtaFYIiE2rmFAD4OcMhtUki8W3U,88
+kryten_llm-0.2.2.dist-info/RECORD,,

kryten_llm-0.2.2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: poetry-core 2.2.1
+Root-Is-Purelib: true
+Tag: py3-none-any

kryten_llm-0.2.2.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+kryten-llm=kryten_llm.__main__:main
+

kryten_llm-0.2.2.dist-info/licenses/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.