kryten-robot 0.6.9__py3-none-any.whl

kryten_robot-0.6.9.dist-info/METADATA

@@ -0,0 +1,469 @@
+Metadata-Version: 2.4
+Name: kryten-robot
+Version: 0.6.9
+Summary: CyTube to NATS bridge connector - publishes CyTube events to NATS message bus
+License: MIT
+License-File: LICENSE
+Keywords: cytube,nats,bridge,connector,socketio,microservices
+Author: Kryten Robot Team
+Requires-Python: >=3.10,<4.0
+Classifier: Development Status :: 4 - Beta
+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
+Classifier: Topic :: System :: Distributed Computing
+Requires-Dist: aiohttp (>=3.9.0)
+Requires-Dist: nats-py (>=2.9.0,<3.0.0)
+Requires-Dist: psutil (>=5.9.0,<6.0.0)
+Requires-Dist: pydantic (>=2.0.0,<3.0.0)
+Requires-Dist: pydantic-settings (>=2.0.0,<3.0.0)
+Requires-Dist: python-socketio[asyncio-client] (>=5.11.0)
+Requires-Dist: websockets (>=12.0)
+Project-URL: Documentation, https://github.com/grobertson/kryten-robot/blob/main/README.md
+Project-URL: Homepage, https://github.com/grobertson/kryten-robot
+Project-URL: Repository, https://github.com/grobertson/kryten-robot
+Description-Content-Type: text/markdown
+
+# Kryten-Robot
+
+[![Python Version](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/downloads/)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![PyPI Version](https://img.shields.io/pypi/v/kryten-robot.svg)](https://pypi.org/project/kryten-robot/)
+
+**Kryten-Robot** is a CyTube to NATS bridge connector that connects to CyTube chat servers via Socket.IO and publishes all events to a NATS message bus. This enables building distributed microservice architectures around CyTube channels.
+
+## Overview
+
+Kryten-Robot acts as the central bridge between CyTube and your microservices:
+
+- **Connects** to CyTube servers via Socket.IO
+- **Publishes** all CyTube events to NATS with structured subjects
+- **Subscribes** to command subjects to control CyTube
+- **Maintains** connection health with automatic reconnection
+- **Tracks** channel state (users, playlist, emotes)
+- **Exposes** state query API via NATS request/reply
+
+## Architecture
+
+```
+┌─────────────┐         ┌──────────────┐         ┌─────────────────┐
+│   CyTube    │◄───────►│ Kryten-Robot │◄───────►│   NATS Server   │
+│   Server    │ Socket  │   (Bridge)   │  Pub/   │                 │
+└─────────────┘  .IO    └──────────────┘  Sub    └─────────────────┘
+                                                          ▲
+                                                          │
+                    ┌─────────────────────────────────────┴──────────┐
+                    │                                                 │
+              ┌─────▼──────┐    ┌──────────────┐    ┌──────────────┐
+              │ kryten-cli │    │kryten-       │    │  Your Custom │
+              │  (Control) │    │userstats     │    │ Microservice │
+              └────────────┘    └──────────────┘    └──────────────┘
+```
+
+## Features
+
+- ✅ **Full CyTube Event Coverage**: All Socket.IO events published to NATS
+- ✅ **Unified Command Pattern**: Single subject per service (`kryten.robot.command`)
+- ✅ **State Management**: Real-time tracking of users, playlist, emotes
+- ✅ **State Query API**: Request/reply for current channel state
+- ✅ **Connection Resilience**: Automatic reconnection with exponential backoff
+- ✅ **Health Monitoring**: HTTP health endpoint for orchestration
+- ✅ **Correlation IDs**: Distributed tracing support
+- ✅ **Structured Logging**: JSON logs with correlation context
+
+## Installation
+
+### From PyPI
+
+```bash
+pip install kryten-robot
+```
+
+### As systemd Service (Linux)
+
+For production deployments on Linux with systemd:
+
+```bash
+# Clone the repository
+git clone https://github.com/grobertson/kryten-robot.git
+cd kryten-robot
+
+# Run installation script (requires root)
+sudo bash install.sh
+```
+
+The installer will:
+- Create system user and directories
+- Set up Python virtual environment
+- Install kryten-robot from PyPI
+- Configure systemd service
+- Create example config file
+
+See `systemd/README.md` for detailed setup instructions.
+
+### From Source
+
+```bash
+git clone https://github.com/grobertson/kryten-robot.git
+cd kryten-robot
+pip install -e .
+```
+
+### With Poetry
+
+```bash
+poetry add kryten-robot
+```
+
+## Quick Start
+
+### 1. Create Configuration File
+
+Create `config.json`:
+
+```json
+{
+  "cytube": {
+    "domain": "cytu.be",
+    "channel": "your-channel",
+    "user": "your-bot-username",
+    "password": "your-bot-password"
+  },
+  "nats": {
+    "servers": ["nats://localhost:4222"],
+    "user": null,
+    "password": null,
+    "max_reconnect_attempts": 60,
+    "reconnect_time_wait": 2
+  },
+  "health": {
+    "enabled": true,
+    "host": "0.0.0.0",
+    "port": 28080
+  },
+  "commands": {
+    "enabled": true
+  },
+  "logging": {
+    "format": "text",
+    "correlation_id": true
+  },
+  "log_level": "INFO"
+}
+```
+
+### 2. Run Kryten-Robot
+
+```bash
+# Using the installed command
+kryten-robot config.json
+
+# Or with Python module
+python -m kryten config.json
+
+# With custom log level
+kryten-robot config.json --log-level DEBUG
+```
+
+### 3. Verify Operation
+
+Check health endpoint:
+```bash
+curl http://localhost:28080/health
+```
+
+Expected response:
+```json
+{
+  "status": "healthy",
+  "cytube_connected": true,
+  "nats_connected": true,
+  "channel": "your-channel",
+  "uptime_seconds": 42.5
+}
+```
+
+## NATS Subject Structure
+
+### Event Publishing
+
+All CyTube events are published to:
+```
+kryten.events.cytube.{channel}.{event_name}
+```
+
+Examples:
+- `kryten.events.cytube.420grindhouse.chatmsg` - Chat messages
+- `kryten.events.cytube.420grindhouse.adduser` - User joins
+- `kryten.events.cytube.420grindhouse.userleave` - User leaves
+- `kryten.events.cytube.420grindhouse.changeMedia` - Video changes
+
+### Command Subscription
+
+Kryten-Robot accepts commands on:
+```
+kryten.robot.command
+```
+
+Command payload:
+```json
+{
+  "service": "robot",
+  "command": "state.userlist",
+  "correlation_id": "optional-trace-id"
+}
+```
+
+Available commands:
+- `state.emotes` - Get all channel emotes
+- `state.playlist` - Get current playlist
+- `state.userlist` - Get all users in channel
+- `state.user` - Get specific user info (requires `username` param)
+- `state.profiles` - Get all user profiles
+- `state.all` - Get complete channel state
+- `system.health` - Get system health status
+- `system.channels` - Get list of connected channels
+- `system.version` - Get Kryten-Robot version
+
+## Configuration Reference
+
+### CyTube Section
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `domain` | string | Yes | CyTube server domain (e.g., "cytu.be") |
+| `channel` | string | Yes | Channel name to connect to |
+| `user` | string | Yes | Bot account username |
+| `password` | string | Yes | Bot account password |
+
+### NATS Section
+
+| Field | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `servers` | array | Yes | - | NATS server URLs |
+| `user` | string | No | null | NATS authentication user |
+| `password` | string | No | null | NATS authentication password |
+| `max_reconnect_attempts` | int | No | 60 | Max reconnection attempts |
+| `reconnect_time_wait` | int | No | 2 | Seconds between reconnect attempts |
+
+### Health Section
+
+| Field | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `enabled` | bool | No | true | Enable HTTP health endpoint |
+| `host` | string | No | "0.0.0.0" | Health endpoint bind address |
+| `port` | int | No | 28080 | Health endpoint port |
+
+### Commands Section
+
+| Field | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `enabled` | bool | No | true | Enable command subscriber |
+
+### Logging Section
+
+| Field | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `format` | string | No | "text" | Log format: "text" or "json" |
+| `correlation_id` | bool | No | true | Include correlation IDs |
+
+### Root Level
+
+| Field | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `log_level` | string | No | "INFO" | Log level: DEBUG, INFO, WARNING, ERROR, CRITICAL |
+
+## Running as a Service
+
+### Systemd (Linux)
+
+See [systemd/README.md](systemd/README.md) for complete systemd service configuration.
+
+Quick setup:
+```bash
+sudo cp systemd/kryten-robot.service /etc/systemd/system/
+sudo systemctl daemon-reload
+sudo systemctl enable kryten-robot
+sudo systemctl start kryten-robot
+```
+
+### Windows Service
+
+Use NSSM (Non-Sucking Service Manager):
+```powershell
+nssm install kryten-robot "C:\Python311\python.exe" "-m kryten config.json"
+nssm set kryten-robot AppDirectory "C:\opt\kryten-robot"
+nssm start kryten-robot
+```
+
+## Development
+
+### Setup Development Environment
+
+```bash
+git clone https://github.com/grobertson/kryten-robot.git
+cd kryten-robot
+
+# Create virtual environment
+python -m venv .venv
+source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+
+# Install in editable mode with dev dependencies
+pip install -e ".[dev]"
+```
+
+### Running Tests
+
+```bash
+pytest
+```
+
+With coverage:
+```bash
+pytest --cov=kryten --cov-report=html
+```
+
+### Code Quality
+
+```bash
+# Format code
+black kryten/
+
+# Lint
+ruff check kryten/
+
+# Type checking
+mypy kryten/
+```
+
+## Integration Examples
+
+### Using kryten-py Library
+
+```python
+from kryten import KrytenClient, KrytenConfig
+
+config = KrytenConfig.from_json("config.json")
+
+async with KrytenClient(config) as client:
+    # Query current userlist
+    response = await client.nats_request(
+        "kryten.robot.command",
+        {"service": "robot", "command": "state.userlist"}
+    )
+    
+    if response["success"]:
+        users = response["data"]["users"]
+        print(f"Users online: {len(users)}")
+```
+
+### Using kryten-cli
+
+```bash
+# Get current playlist
+kryten list queue
+
+# Get all users
+kryten list users
+
+# Get channel emotes
+kryten list emotes
+```
+
+## Architecture Documentation
+
+- **[KRYTEN_ARCHITECTURE.md](KRYTEN_ARCHITECTURE.md)** - System architecture and patterns
+- **[STATE_QUERY_IMPLEMENTATION.md](STATE_QUERY_IMPLEMENTATION.md)** - State query API details
+- **[LIFECYCLE_EVENTS.md](LIFECYCLE_EVENTS.md)** - Lifecycle event handling
+- **[AUDIT_LOGGING.md](AUDIT_LOGGING.md)** - Audit logging implementation
+
+## Troubleshooting
+
+### Connection Issues
+
+**Problem**: Kryten-Robot won't connect to CyTube
+- Verify credentials in config.json
+- Check if channel name is correct
+- Ensure CyTube server is accessible
+
+**Problem**: NATS connection failures
+- Verify NATS server is running: `nats-server -v`
+- Check NATS server URL in config
+- Test NATS connectivity: `nats-cli pub test "hello"`
+
+### Performance Issues
+
+**Problem**: High memory usage
+- Check for excessive event backlog
+- Verify NATS consumers are processing events
+- Monitor with health endpoint: `curl http://localhost:28080/health`
+
+**Problem**: Events not being published
+- Check log level is INFO or DEBUG
+- Verify NATS subjects with `nats-cli sub "kryten.events.>"`
+- Check correlation logs for event flow
+
+## Requirements
+
+- Python 3.11 or higher
+- NATS server 2.9.0 or higher
+- CyTube server (any version with Socket.IO support)
+
+## Related Projects
+
+- **[kryten-py](https://github.com/grobertson/kryten-py)** - Python library for building Kryten microservices
+- **[kryten-userstats](https://github.com/grobertson/kryten-userstats)** - User statistics tracking service
+- **[kryten-cli](https://github.com/grobertson/kryten-cli)** - Command-line control interface
+
+## Contributing
+
+Contributions welcome! Please:
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Make your changes with tests
+4. Run tests and linting (`pytest && black . && ruff check .`)
+5. Commit your changes (`git commit -m 'Add amazing feature'`)
+6. Push to branch (`git push origin feature/amazing-feature`)
+7. Open a Pull Request
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Support
+
+- **Issues**: [GitHub Issues](https://github.com/grobertson/kryten-robot/issues)
+- **Documentation**: [GitHub Repository](https://github.com/grobertson/kryten-robot)
+
+## Changelog
+
+### v0.5.0 (2025-12-08)
+
+**Major Changes:**
+- ✅ Unified command pattern: All services now use `kryten.{service}.command`
+- ✅ State query API: Request/reply interface for channel state
+- ✅ Fixed startup banner bug with wildcard normalization
+- ✅ PyPI packaging: Now installable via `pip install kryten-robot`
+
+**API Updates:**
+- Changed: Command subjects from `kryten.commands.cytube.*` to `kryten.robot.command`
+- Added: State query commands (state.emotes, state.playlist, etc.)
+- Added: System health command via NATS
+
+**Documentation:**
+- Added: KRYTEN_ARCHITECTURE.md with comprehensive architecture overview
+- Updated: All examples to use unified command pattern
+- Added: PyPI publication workflow
+
+---
+
+**Built with ❤️ for the CyTube community**
+

kryten_robot-0.6.9.dist-info/RECORD

@@ -0,0 +1,32 @@
+kryten/__init__.py,sha256=wmWGGCaEunygK-ZKnxLn0vtLraw4_eAv3d4LxePDZ-g,3296
+kryten/__main__.py,sha256=jfGeDvGegP6QeaC9U1tgeDP8FF2di2Sbbauj3GA0cyQ,35784
+kryten/application_state.py,sha256=qDfa5SSCGJ_eBUZAvK_dzKPb6kbGmlrD_19DaGD-P9s,3667
+kryten/audit_logger.py,sha256=pVmztGyh28G7VhBUsz4SkX1BKvHK5SlFnguKxnfeLlM,8395
+kryten/command_subscriber.py,sha256=sb-GVXfbsLKGPNpSzwSD_Pj51sGkbU345XnSBPpoUa8,15069
+kryten/config.example.json,sha256=Bu62yNSKngYR_KZOaBBxyGpmoC02wf05qP2_KaQi0_o,818
+kryten/CONFIG.md,sha256=XE8k8jh0lKlWlQS4s8S0lpTh18lg7Yd8OrJGojUB174,12205
+kryten/config.py,sha256=VRe-i-pkltgHXd-a_v3gvLUJJ9LXrVKoBPV4FvCB_Vo,16966
+kryten/connection_watchdog.py,sha256=bv23gIX3lo1vDMYFUgXdhbyxu6lKoTUz63nT0IxdIv4,6748
+kryten/correlation.py,sha256=Wnq5YgTazV5hKjrKyWUf2YZUmNciYuyRZWzeopdbJkc,7745
+kryten/cytube_connector.py,sha256=JZRquOuKYL6nKtCRXuz-zHH-zBcLrBSQ56LkDMK5kJg,27812
+kryten/cytube_event_sender.py,sha256=z5E_pvaKyE_u-k3ajr5pJb3rivo20FftP3y2bKvQroQ,49796
+kryten/errors.py,sha256=LJW2JoO5whjoLaaXw1g2-yh_ZfVoQTkDLE8itZzsl2Q,4619
+kryten/event_publisher.py,sha256=WN7LGUxnKT5ilz6JXg-Y3faputOjDBV0oDYbKNMr78E,16135
+kryten/health_monitor.py,sha256=eHp2MgT3HwiOMUutUB_XllmK2q1Co6zZ1ZVriSediMA,17527
+kryten/lifecycle_events.py,sha256=68ujG7TrQCW0TAT3f4NM7oBCRUYNRaxPXFl2U2giUwg,10273
+kryten/logging_config.py,sha256=wEruMpptebKwSFo3-YO2lIzpyB_oh74KKtmAis8AH98,10254
+kryten/nats_client.py,sha256=X-SGlEh1swG6O__KYNWeBeWUNP16AbQFlPnwhMCycfY,15464
+kryten/raw_event.py,sha256=1CM48e-kD2y2Y5B0q_bnQRbN6URuOzbglcRZYOZ2Fkk,5170
+kryten/service_registry.py,sha256=CzQkL6t-XPN1FGvwe5jh3HZ0NcnEPaCV5EElxi19ow4,14334
+kryten/shutdown_handler.py,sha256=UDRpbPzGdtWQ2e1592D6_LJ5atdxGC7zTCJ-rBSWz2s,14197
+kryten/socket_io.py,sha256=3TOl2GblEOIT60b_EFYQgrvWo3LjucrIYnw529mb02s,28334
+kryten/state_manager.py,sha256=PNAmlhdJ7Z7ibkMeAMNhN8_Wa3Nz1YOPsqHshWNGkGg,23439
+kryten/state_query_handler.py,sha256=tv9E3QoCgB_C1-6WtRnNMqrF1q1LWq5eeCEtx5LhMBw,26897
+kryten/state_updater.py,sha256=xXW5Dhc2tY1gQVRCgxWW5X2H2RQIWAATsXczQulrTz0,10977
+kryten/stats_tracker.py,sha256=8w-Ybg03wrkCJnJCyXNjnVwQjlqdw3UBtGeVkcj1A0A,3459
+kryten/subject_builder.py,sha256=eVsAoIjO1G5ko9xQHFU4iKBXukYXlsk_t88FxOUj5Ig,11193
+kryten_robot-0.6.9.dist-info/entry_points.txt,sha256=MTAs-YdfHJ2N2wu5elqvwPuDb6PKM8NuFRxU1PFkmi4,52
+kryten_robot-0.6.9.dist-info/licenses/LICENSE,sha256=4-aY9N48r38gULWwGnXZB0cFBoTcFneVGswDSK2bVi4,1095
+kryten_robot-0.6.9.dist-info/METADATA,sha256=EBBU4jtDP4Qtbj1_Kf0fHlwHu80CyXK0EYQDdLJkHzo,13912
+kryten_robot-0.6.9.dist-info/WHEEL,sha256=zp0Cn7JsFoX2ATtOhtaFYIiE2rmFAD4OcMhtUki8W3U,88
+kryten_robot-0.6.9.dist-info/RECORD,,

kryten_robot-0.6.9.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_robot-0.6.9.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+kryten-robot=kryten.__main__:cli
+

kryten_robot-0.6.9.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.