From e3c4bc8f237d4f3e85cd4292e9926b5d3ce495f6 Mon Sep 17 00:00:00 2001 From: Groupr Date: Thu, 17 Jul 2025 00:43:27 +0000 Subject: [PATCH] Add new file --- slop-terminal/README.md | 387 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 387 insertions(+) create mode 100644 slop-terminal/README.md diff --git a/slop-terminal/README.md b/slop-terminal/README.md new file mode 100644 index 0000000..56dd1c7 --- /dev/null +++ b/slop-terminal/README.md @@ -0,0 +1,387 @@ +# SLOP Monolith Server + +A comprehensive SLOP (Streamlined Language Operations Protocol) server implementation with AI model integration, sandboxed code execution, and gaming capabilities. + +## Features + +### 🤖 AI Integration +- **Multi-Model Support**: Dynamic discovery of OpenAI-compatible endpoints (vLLM, Ollama, etc.) +- **Tool Calling**: AI can automatically invoke tools to assist with tasks +- **Chat Interface**: Full conversation support with context management + +### 🛡️ Security & Sandboxing +- **Firecracker Sandboxes**: Secure microVM-based code execution +- **User Isolation**: Per-user sandbox environments with persistent state +- **Permission Controls**: Configurable security policies and access controls + +### 🔧 Terminal Tools +- **File Operations**: Read, write, and manage files safely +- **Code Execution**: Python and shell command execution in sandboxes +- **System Information**: Access to system stats and environment details +- **Directory Management**: Navigate and explore filesystem + +### 🎮 Gaming Features +- **Casino Games**: Slots and Blackjack with persistent wallets +- **Agent Support**: Multi-agent gaming with individual statistics +- **Persistent State**: Game history and balances stored across sessions + +### 💾 Data Management +- **Memory System**: Key-value storage with query capabilities +- **Resource Management**: Hierarchical resource storage and retrieval +- **Persistent Storage**: File-based data persistence with locking + +## Quick Start + +### Prerequisites + +- **Linux/WSL2** (Ubuntu 18.04+ recommended) +- **Python 3.8+** +- **KVM support** (for Firecracker sandboxes) +- **Root/sudo access** (for initial setup) + +### Installation + +1. **Clone the repository**: + ```bash + git clone + cd slop-monolith + ``` + +2. **Run the setup**: + ```bash + make setup + ``` + + This will automatically: + - Install system dependencies + - Download and configure Firecracker + - Set up KVM permissions + - Install Python packages + - Configure environment variables + +3. **Test the installation**: + ```bash + ./test_firecracker.sh # Auto-generated by setup + ``` + +4. **Start the server**: + ```bash + make run + ``` + +## Configuration + +### Environment Variables + +The server supports extensive configuration through environment variables. Copy the template and customize: + +```bash +cp config/.env.example .env +nano .env +``` + +#### Model Endpoints +```bash +export MODEL_ENDPOINT_0="https://your-model-endpoint.com/v1" +export MODEL_API_KEY_0="your-api-key-or-not-needed" +# Add more endpoints with incrementing numbers +``` + +#### Server Settings +```bash +export SLOP_PORT="31337" # Server port +export SLOP_DATA_DIR="./data" # Data directory +export SLOP_LOG_LEVEL="INFO" # Logging level +export FLASK_DEBUG="true" # Debug mode +``` + +#### Security Settings +```bash +export ENABLE_FIRECRACKER="true" # Enable sandbox +export ALLOW_DANGEROUS_TOOLS="false" # Allow unsafe tools +export REQUIRE_USER_ID="true" # Require user identification +export DEFAULT_TIMEOUT="60" # Default execution timeout +``` + +#### Firecracker Settings +```bash +export FIRECRACKER_KERNEL="./firecracker/kernel/vmlinux.bin" +export FIRECRACKER_ROOTFS="./firecracker/rootfs/rootfs.ext4" +export FIRECRACKER_MEMORY="512" # Memory in MB +export FIRECRACKER_VCPU="1" # Virtual CPU count +``` + +## API Endpoints + +### Chat & AI +- `POST /chat` - Chat with AI models with tool calling support +- `GET /models` - List available AI models + +### Tools +- `GET /tools` - List all available tools +- `GET /tools/{tool_id}` - Get tool details +- `POST /tools/{tool_id}` - Execute a specific tool + +### Memory Management +- `GET /memory` - List all memory keys +- `GET /memory/{key}` - Retrieve memory value +- `POST /memory` - Store key-value pair +- `DELETE /memory/{key}` - Delete memory key +- `POST /memory/query` - Query memory with filters + +### Resource Management +- `GET /resources` - List all resources +- `GET /resources/{resource_id}` - Get specific resource +- `POST /resources` - Create new resource +- `PUT /resources/{resource_id}` - Update resource +- `DELETE /resources/{resource_id}` - Delete resource +- `GET /resources/search` - Search resources + +### Gaming +- `POST /tools/slots` - Play slot machine +- `POST /tools/blackjack` - Play blackjack + +### System +- `GET /info` - Server information and capabilities +- `POST /pay` - Mock payment processing + +## Available Tools + +### Terminal Tools +- **`sandbox_python`** - Execute Python code in secure sandbox +- **`sandbox_exec`** - Execute shell commands in secure sandbox +- **`file_read`** - Read file contents safely +- **`directory_list`** - List directory contents +- **`sysinfo`** - Get system information +- **`pwd`** - Get current directory +- **`sandbox_manage`** - Manage sandbox instances + +### Utility Tools +- **`calculator`** - Basic math calculations +- **`greet`** - Simple greeting tool + +### Gaming Tools +- **`slots`** - Slot machine game +- **`blackjack`** - Blackjack card game + +## Security Features + +### Firecracker Sandboxes +- **Isolated Execution**: Each user gets their own microVM +- **Resource Limits**: Configurable CPU and memory limits +- **Network Isolation**: No network access from sandboxes +- **Persistent Environments**: Python virtual environments persist across calls + +### Access Controls +- **User Identification**: Optional user ID requirement +- **Tool Restrictions**: Dangerous tools only available in sandboxes +- **Timeout Controls**: Configurable execution timeouts +- **Permission Levels**: Different access levels for different tools + +## Usage Examples + +### Chat with AI +```bash +curl -X POST http://localhost:31337/chat \ + -H "Content-Type: application/json" \ + -d '{ + "messages": [{"role": "user", "content": "Calculate 15 * 23"}], + "model": "your-model-name", + "enable_tool_calling": true, + "user_id": "user123" + }' +``` + +### Execute Python Code +```bash +curl -X POST http://localhost:31337/tools/sandbox_python \ + -H "Content-Type: application/json" \ + -d '{ + "code": "print(\"Hello, World!\")", + "user_id": "user123", + "packages": ["requests", "numpy"] + }' +``` + +### Store and Retrieve Memory +```bash +# Store +curl -X POST http://localhost:31337/memory \ + -H "Content-Type: application/json" \ + -d '{"key": "user_pref", "value": "dark_mode"}' + +# Retrieve +curl http://localhost:31337/memory/user_pref +``` + +### Play Casino Games +```bash +curl -X POST http://localhost:31337/tools/slots \ + -H "Content-Type: application/json" \ + -d '{"bet": 10, "agent_id": "player1"}' +``` + +## Development + +### Available Make Commands + +```bash +make help # Show all available commands +make setup # Run vars.sh setup +make install # Install Python dependencies +make run # Start the server +make test # Run tests +make clean # Clean up generated files +make docker-build # Build Docker image +make docker-run # Run with Docker Compose +``` + +### Project Structure +``` +slop-monolith/ +├── server.py # Main Flask server +├── vars.sh # Setup and configuration script +├── README.md # This file +├── requirements.txt # Python dependencies +├── Makefile # Build automation +├── Dockerfile # Container configuration +├── docker-compose.yml # Docker setup +├── .gitlab-ci.yml # CI/CD pipeline +├── .gitignore # Git ignore rules +├── config/ # Configuration files +│ └── .env.example # Environment template +├── docs/ # Documentation +├── tests/ # Test files +├── static/ # Static files +├── data/ # Data directory +│ ├── memory.json # Memory storage +│ ├── resources.json # Resource storage +│ ├── terminal/ # Terminal data +│ └── slop_monolith.log # Server logs +├── scripts/ # Generated scripts (gitignored) +│ ├── set_env.sh # Environment setup (auto-generated) +│ ├── test_firecracker.sh # Test script (auto-generated) +│ └── start_firecracker.sh # Firecracker wrapper (auto-generated) +├── firecracker/ # Firecracker components +│ ├── kernel/ # Kernel images +│ └── rootfs/ # Root filesystems +├── downloads/ # Downloaded files +└── bin/ # Binary files +``` + +### Adding New Tools +1. Create a class inheriting from `TerminalTool` +2. Implement required methods: `tool_id`, `description`, `arguments`, `execute` +3. Register the tool in `initialize_terminal_tools()` + +### Adding New Models +Simply add new environment variables: +```bash +export MODEL_ENDPOINT_X="https://your-endpoint.com/v1" +export MODEL_API_KEY_X="your-key" +``` + +## Troubleshooting + +### Common Issues + +**KVM Permission Errors**: +```bash +# Fix KVM permissions +sudo usermod -a -G kvm $USER +# Restart terminal or re-login +``` + +**Firecracker Not Working**: +```bash +# Test Firecracker setup +./test_firecracker.sh # Auto-generated by setup + +# Check KVM availability +ls -la /dev/kvm +``` + +**Model Connection Issues**: +```bash +# Test endpoint manually +curl https://your-endpoint.com/v1/models +``` + +**Memory/Resource Lock Timeouts**: +- Check disk space in data directory +- Ensure proper file permissions +- Restart server if persistent + +### Debug Mode +Enable detailed logging: +```bash +# Edit .env file +SLOP_LOG_LEVEL=DEBUG +FLASK_DEBUG=true + +# Then start server +make run +``` + +## Performance Tuning + +### Firecracker Settings +Edit your `.env` file: +```bash +FIRECRACKER_MEMORY=1024 # Increase memory +FIRECRACKER_VCPU=2 # More CPU cores +``` + +### Timeout Settings +Edit your `.env` file: +```bash +DEFAULT_TIMEOUT=120 # Longer timeouts +``` + +## License + +This project is released under the Public Domain. See the original SLOP specification for more details. + +## Contributing + +1. Fork the repository +2. Create a feature branch +3. Make your changes +4. Add tests if applicable +5. Submit a pull request + +## Support + +For issues and questions: +- Check the troubleshooting section +- Review server logs in `data/slop_monolith.log` +- Test with `./test_firecracker.sh` (auto-generated by setup) +- Use `make help` to see all available commands +- Verify endpoints with curl + +## Related Projects + +- [SLOP Specification](https://slop.unturf.com/) +- [Original SLOP Examples](https://github.com/agnt-gg/slop) + +## Quick Start Summary + +```bash +# Clone and navigate to project +git clone +cd slop-monolith + +# Setup environment +cp config/.env.example .env +make setup + +# Start server +make run + +# Test +curl http://localhost:31337/info +``` + +--- + +Built with ❤️ for the SLOP community \ No newline at end of file