hygate/README.md

# Hygate

## About

Hygate is a standalone, single-binary gateway that exposes Tencent's Hunyuan 3 (hy3) Gradio space through an OpenAI-compatible API. It translates the standard `/v1/chat/completions` and `/v1/models` endpoints into Gradio's `/gradio_api/call/chat` request/stream protocol, so any OpenAI-compatible client can talk to Hunyuan 3 without modification.

## Features

- OpenAI-compatible chat completions (streaming and non-streaming)
- Reasoning content passthrough (`reasoning_content`)
- Tool/function calling, including incremental streaming of tool-call arguments
- Fibonacci backoff retry on upstream calls
- Configurable endpoint and User-Agent
- No external dependencies (standard library only)

## Installation

You need Go 1.26 or newer. Install the latest release straight from the Git repository with `go install`:

```
go install code.luxferre.top/luxferre/hygate@latest
```

This fetches the module from `https://code.luxferre.top/luxferre/hygate.git` and places the `hygate` binary in `$(go env GOPATH)/bin`. Make sure that directory is on your `PATH`.

If you prefer to build from a local checkout instead:

```
git clone https://code.luxferre.top/luxferre/hygate.git
cd hygate
go install .
```

Alternatively, you can directly build from source by running `make`. This produces `bin/hygate` binary for your architecture.

## Usage

Run the gateway:

```
hygate [-port 8080] [-endpoint https://tencent-hy3.hf.space]
```

Available flags:

- `-port` — TCP port to listen on (default `8080`)
- `-endpoint` — root URL of the Hunyuan Gradio space (default `https://tencent-hy3.hf.space`)
- `-user-agent` / `-ua` — custom User-Agent sent to the upstream

Endpoints served:

- `GET  /v1/models`
- `POST /v1/chat/completions`

Example request with curl:

```
curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"hy3","messages":[{"role":"user","content":"Hello"}],"stream":false}'
```

## FAQ

### Does this need an API key?

No. The gateway proxies directly to the public Gradio space and does not require authentication.

### Why proxy this particular model?

Even through the Gradio API, Tencent Hy3 is a very fast and performant model when it comes to agentic tasks. Unfortunately, it still is too big for most people to run locally, at decent speed or at all. This gateway solves this problem for them.

### Which models are reported?

A single model, `hy3`, is advertised via `/v1/models`.

### Are token usage counts returned?

No. The `usage` field is always zero, since the upstream Gradio API does not expose token counts.

### Can the upstream endpoint be changed?

Yes, with the `-endpoint` flag. Any HuggingFace Gradio space hosting the compatible `/chat` endpoint will work.

### Is it compatible with the [Dynagate](https://code.luxferre.top/luxferre/dynagate) LLM gateway?

Absolutely. Just run Hygate on a separate port (e.g. 8899) and then add the following line to the Dynagate's `models.csv` file:
```
hy3,-,http://localhost:8899,
```

## Credits

Created by Luxferre in 2026, released into the public domain with no warranties.