# 🚀 Publishing Nexus to PyPI — Step-by-Step Guide

## Prerequisites

```bash
# Install build tools
uv pip install --python .venv/bin/python build twine
```

## Step 1: Register on PyPI

1. Go to https://pypi.org/account/register/
2. Create an account
3. Enable 2FA (required)
4. Go to https://pypi.org/manage/account/token/
5. Create an API token with scope "Entire account" (first time)
6. Save the token — it starts with `pypi-`

## Step 2: Configure Authentication

Create `~/.pypirc`:

```ini
[distutils]
index-servers =
    pypi
    testpypi

[pypi]
username = __token__
password = pypi-YOUR_TOKEN_HERE

[testpypi]
repository = https://test.pypi.org/legacy/
username = __token__
password = pypi-YOUR_TEST_TOKEN_HERE
```

Or use environment variables (recommended for CI):
```bash
export TWINE_USERNAME=__token__
export TWINE_PASSWORD=pypi-YOUR_TOKEN_HERE
```

## Step 3: Test on TestPyPI First

```bash
cd /Users/songtianye/workspace/python/github/myself/nexus

# Build
.venv/bin/python -m build

# Upload to TestPyPI
.venv/bin/python -m twine upload --repository testpypi dist/*

# Test install from TestPyPI
pip install --index-url https://test.pypi.org/simple/ nexus-agents
```

## Step 4: Publish to PyPI

```bash
# Clean previous builds
rm -rf dist/ build/ *.egg-info

# Build fresh
.venv/bin/python -m build

# Upload to PyPI (the real one)
.venv/bin/python -m twine upload dist/*
```

## Step 5: Verify

```bash
pip install nexus-agents
python -c "import nexus; print(nexus.__version__)"
```

## Automated: GitHub Actions (Recommended)

The file `.github/workflows/publish.yml` is already set up.
Just push a tag:

```bash
git tag v0.1.0
git push origin v0.1.0
```

This will automatically build and publish to PyPI.

---

## ⚠️ Important Notes

1. **Package name `nexus-agents`** — Check availability on PyPI first:
   https://pypi.org/project/nexus-agents/
   If taken, consider alternatives: `nexus-multi-agent`, `nexus-agentic`, etc.

2. **Version bumping** — Update version in:
   - `pyproject.toml` → `version = "x.y.z"`
   - `nexus/__init__.py` → `__version__ = "x.y.z"`

3. **First release checklist**:
   - [ ] README looks good on PyPI (check with `twine check dist/*`)
   - [ ] All dependencies are correct in pyproject.toml
   - [ ] License file is included
   - [ ] Test install works in a clean environment
