text-adventure-llm/setup_guide.md

# Setup Guide for Text-Based LLM Interaction System (Linux)

This guide describes a clean Linux-first setup (tested on Ubuntu/Debian). It removes macOS/Windows specifics and focuses on a reliable developer workflow with pyenv, virtual environments, Docker, and Portainer.

## Prerequisites

- Git
- curl or wget
- build tools (gcc, make, etc.)
- Docker Engine and Docker Compose plugin

Recommended (optional but helpful):
- net-tools or iproute2 for networking diagnostics
- ca-certificates

On Ubuntu/Debian you can install Docker and the Compose plugin via apt:

```bash
sudo apt update
sudo apt install -y docker.io docker-compose-plugin
# Allow running docker without sudo (re-login required)
sudo usermod -aG docker "$USER"
```

## Installing pyenv (Ubuntu/Debian)

Install dependencies required to build CPython:

```bash
sudo apt update
sudo apt install -y make build-essential libssl-dev zlib1g-dev \
  libbz2-dev libreadline-dev libsqlite3-dev wget curl llvm \
  libncursesw5-dev xz-utils tk-dev libxml2-dev libxmlsec1-dev \
  libffi-dev liblzma-dev
```

Install pyenv:

```bash
curl https://pyenv.run | bash
```

Add pyenv to your shell (bash; recommended on Linux):

```bash
echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.profile
echo 'export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.profile
echo 'eval "$(pyenv init --path)"' >> ~/.profile

# Interactive shells
echo 'eval "$(pyenv init -)"' >> ~/.bashrc

# Reload your shell
source ~/.profile
source ~/.bashrc
```

Using zsh on Linux? Add to ~/.zprofile and ~/.zshrc instead:

```bash
echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.zprofile
echo 'export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.zprofile
echo 'eval "$(pyenv init --path)"' >> ~/.zprofile
echo 'eval "$(pyenv init -)"' >> ~/.zshrc
source ~/.zprofile
source ~/.zshrc
```

## Installing Python with pyenv

```bash
# List available Python versions
pyenv install --list

# Install a specific Python version (project default)
pyenv install 3.9.16

# Set it as your global default (optional)
pyenv global 3.9.16
```

Note: If you prefer a newer interpreter and your tooling supports it, Python 3.11.x also works well.

## Creating a Virtual Environment

Choose ONE of the methods below.

### Method 1: Using pyenv-virtualenv (recommended)

```bash
# Install pyenv-virtualenv plugin
git clone https://github.com/pyenv/pyenv-virtualenv.git "$(pyenv root)"/plugins/pyenv-virtualenv

# Initialize in your interactive shell
echo 'eval "$(pyenv virtualenv-init -)"' >> ~/.bashrc
source ~/.bashrc

# Create and activate a virtual environment
pyenv virtualenv 3.9.16 text-adventure
pyenv local text-adventure   # auto-activates in this directory
# or activate manually
pyenv activate text-adventure
```

### Method 2: Using Python's built-in venv

```bash
# Use the selected Python version in this directory
pyenv local 3.9.16

# Create and activate venv
python -m venv .venv
source .venv/bin/activate
```

## Installing Project Dependencies

With your virtual environment active:

```bash
python -m pip install --upgrade pip setuptools wheel
pip install -r requirements.txt
```

## Verifying Setup

```bash
# Check Python version
python --version

# Check installed packages
pip list

# Run basic tests
python test_system.py
# Optionally:
python test_llm_connection.py
python test_llm_exchange.py
```

## Docker (Linux)

Docker provides a clean, reproducible environment.

### Build and Run

```bash
# Build the image
docker build -t text-adventure .

# Run using host networking (Linux-only)
docker run -it --rm --network host -v "$PWD":/app text-adventure
```

### Docker Compose (v2 CLI)

Update [docker-compose.yml](docker-compose.yml) as needed. On Linux you may use host networking:

```yaml
services:
  text-adventure:
    build: .
    network_mode: "host"   # Linux-only
```

Then:

```bash
docker compose up --build
# Run detached
docker compose up -d --build
# Stop and remove
docker compose down
```

### Connecting to LM Studio from a container

LM Studio is assumed to run on the Linux host (default in [config.py](config.py)). Prefer using the special hostname host.docker.internal inside containers.

Option A (recommended when not using host network): add an extra_hosts mapping using Docker’s host-gateway:

```yaml
services:
  text-adventure:
    build: .
    extra_hosts:
      - "host.docker.internal:host-gateway"
```

Then in [config.py](config.py), set:

```python
self.LM_STUDIO_HOST = "host.docker.internal"
self.LM_STUDIO_PORT = 1234
```

Option B (Linux-only): use host networking (container shares host network namespace). In this case keep LM_STUDIO_HOST as 127.0.0.1 or the host’s IP address.

Fallback: If neither applies, you can use your Docker bridge gateway IP (often 172.17.0.1), but this can vary by system.

Connectivity quick check from inside the container:

```bash
docker compose exec text-adventure python - <<'PY'
import requests
import sys
url = "http://host.docker.internal:1234/v1/models"
try:
    r = requests.get(url, timeout=5)
    print(r.status_code, r.text[:200])
except Exception as e:
    print("ERROR:", e)
    sys.exit(1)
PY
```

## Portainer Deployment (Linux)

Portainer simplifies Docker management via the web UI.

### Prerequisites

- Portainer instance reachable (e.g., http://10.0.0.199:9000)
- Valid Portainer credentials
- Docker image available (local or registry)

Create a local env file and never commit secrets:

```bash
cp .env.example .env
# edit .env and set PORTAINER_URL, PORTAINER_USERNAME, PORTAINER_PASSWORD
```

### Deploy

The script [deploy_to_portainer.py](deploy_to_portainer.py) deploys a single container using host networking, which works on Linux:

```bash
python deploy_to_portainer.py
```

You can also override environment variables:

```bash
export PORTAINER_URL=http://10.0.0.199:9000
export PORTAINER_USERNAME=admin
export PORTAINER_PASSWORD=yourpassword
python deploy_to_portainer.py
```

After deployment, verify connectivity to LM Studio using the container exec method shown above.

## Troubleshooting (Linux)

- pyenv: command not found
  - Ensure the init lines exist in ~/.profile and ~/.bashrc, then restart your terminal:
    - eval "$(pyenv init --path)" in ~/.profile
    - eval "$(pyenv init -)" in ~/.bashrc

- Python build errors (e.g., "zlib not available")
  - Confirm all build deps are installed (see Installing pyenv).

- Virtual environment activation issues
  - For venv: source .venv/bin/activate
  - For pyenv-virtualenv: pyenv activate text-adventure

- Docker permission errors (e.g., "permission denied" / cannot connect to Docker daemon)
  - Add your user to the docker group and re-login:
    sudo usermod -aG docker "$USER"

- docker compose not found
  - Install the Compose plugin: sudo apt install docker-compose-plugin

- Container cannot reach LM Studio
  - If using extra_hosts: verify host-gateway mapping and LM_STUDIO_HOST=host.docker.internal in [config.py](config.py).
  - If using host network: ensure LM Studio is listening on 0.0.0.0 or localhost as appropriate.
  - Try the connectivity check snippet above; if it fails, verify firewall rules and that LM Studio is running.

## Notes

- The LM Studio address 10.0.0.200:1234 in [config.py](config.py) is a placeholder. Adjust it to your environment as described above.
- Do not commit your [.env](.env) file. Use [.env.example](.env.example) as a template.
- Use docker compose (v2) commands instead of the deprecated docker-compose (v1) binary.