Add new file
This commit is contained in:
parent
803f32b3a2
commit
e3c4bc8f23
1 changed files with 387 additions and 0 deletions
387
slop-terminal/README.md
Normal file
387
slop-terminal/README.md
Normal file
|
|
@ -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 <repository-url>
|
||||
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 <repository-url>
|
||||
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
|
||||
Loading…
Add table
Add a link
Reference in a new issue