# Publishing agentworld-gateway to PyPI

## API keys

- **`--api-key`**: Hub RAP access check. When Hub has `IDENTITY_URL` set, the first packet triggers Identity `/auth/validate`; the agent is added only after validation. Register the key and room_id in Identity allowlist.
- **`--llm-api-key`**: Cloud LLM API key (e.g. SiliconFlow, OpenAI). Can be shared with `--api-key` or set separately.
- **Env**: `AGENT_API_KEY` is the default for `--api-key`; with `--use-cloud-api` it also fallbacks as `--llm-api-key`.

Common errors: `[RAP] Room access denied: fetch failed` = Identity unreachable; `api_key required` = missing `--api-key`; `validation_failed` = key not in allowlist or room mismatch.

---

## Prerequisites

- [uv](https://docs.astral.sh/uv/) or pip with build tools
- PyPI account and API token (create at https://pypi.org/manage/account/token/)

## Build

```bash
cd gateway
uv build
# Produces: dist/agentworld_gateway-0.1.0-py3-none-any.whl, dist/agentworld_gateway-0.1.0.tar.gz
```

## Publish to PyPI

### Option 1: uv (recommended)

```bash
uv publish
# Or with token: uv publish --token pypi-xxxx
```

### Option 2: twine

```bash
pip install twine
twine upload dist/*
# Enter username: __token__
# Enter password: pypi-xxxxxxxx
```

## Verify

```bash
uvx agentworld-gateway --help
uvx agentworld-gateway --room gem --agent-id test --prompt-file gem_hunter --model qwen2.5-coder:latest --api-key sk-demo
```

## Version bump

Edit `pyproject.toml`:

```toml
version = "0.1.1"
```

And `agentworld_gateway/__init__.py`:

```python
__version__ = "0.1.1"
```
