CONNECT_ARES_ENGINE.md

# Connect the Static UI to a Real Ares Checkpoint

The Hugging Face Space uses Static SDK, so it cannot run PyTorch inside the Space. To make the official UI generate real Ares responses, run Ares in Colab and connect the Static UI to that Colab endpoint.

## Overview

1. Train Ares in Colab.
2. Keep `FINAL_CKPT` and `TOKENIZER_PATH` from the notebook.
3. Start the Ares API server in Colab.
4. Expose it with `cloudflared`.
5. Copy the public `https://...trycloudflare.com` URL.
6. Paste it into the official UI's **Ares engine** box.
7. Send a chat message.

## Install API dependencies in Colab

Run this after training:

```python
!pip -q install fastapi uvicorn pydantic
```

## Start the Ares API server in Colab

Run this in a notebook cell after `FINAL_CKPT` and `TOKENIZER_PATH` exist:

```python
import subprocess, sys, time, re, os, pathlib

PORT = 8000
server_cmd = [
    sys.executable, '-m', 'ares_core.api_server',
    '--checkpoint', str(FINAL_CKPT),
    '--tokenizer', str(TOKENIZER_PATH),
    '--device', 'auto',
    '--host', '0.0.0.0',
    '--port', str(PORT),
]
server = subprocess.Popen(server_cmd)
time.sleep(5)
print('Ares API server started on port', PORT)
```

## Expose with cloudflared

Run:

```python
!wget -q https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64 -O /usr/local/bin/cloudflared
!chmod +x /usr/local/bin/cloudflared

import subprocess, time, re
cloudflared = subprocess.Popen(
    ['cloudflared', 'tunnel', '--url', 'http://127.0.0.1:8000'],
    stdout=subprocess.PIPE,
    stderr=subprocess.STDOUT,
    text=True,
)
public_url = None
for _ in range(120):
    line = cloudflared.stdout.readline()
    print(line, end='')
    m = re.search(r'https://[-a-zA-Z0-9.]+\.trycloudflare\.com', line)
    if m:
        public_url = m.group(0)
        break
    time.sleep(1)
print('PUBLIC ARES ENGINE URL:', public_url)
```

## Test the API from Colab

```python
import requests
print(requests.get(public_url + '/health').json())
print(requests.post(public_url + '/generate', json={
    'prompt': 'Ares, explain validation loss.',
    'max_new_tokens': 120,
    'temperature': 0.75,
    'top_k': 50,
}).json()['text'])
```

## Connect official UI

Open:

```text
https://huggingface.co/spaces/jacmor64/ares-static-lab
```

In the right-side **Ares engine** panel, paste:

```text
https://YOUR-SUBDOMAIN.trycloudflare.com
```

Do not add `/generate` at the end. The UI adds `/generate` automatically.

Click **Connect**.

Now chat messages will call the Ares checkpoint server instead of the static fallback.

## Important limitations

- The cloudflared URL changes each time you restart the tunnel.
- Colab must stay open and running.
- The model response quality depends on the checkpoint you trained.
- This uses your own Ares checkpoint, not an external AI model.