# Publishing kgentik SDK to PyPI

This document describes the complete workflow for publishing the kgentik SDK to PyPI using git subtree and automated scripts.

## Prerequisites

1. **PyPI Account**: Create an account at [pypi.org](https://pypi.org) and [test.pypi.org](https://test.pypi.org)
2. **API Token**: Generate an API token from your PyPI account settings
3. **Public Repository**: Create `kgentik/kgentik-sdk` on GitHub
4. **API Key File**: Create `.pypi_api_key` at project root with your PyPI API token

## Setup

### 1. Create API Key File

Create `.pypi_api_key` at the project root:

```bash
echo "your-pypi-api-token-here" > .pypi_api_key
```

**Important**: This file is already added to `.gitignore` and should never be committed.

### 2. Initial Git Subtree Setup

Add the public repository as a remote:

```bash
git remote add kgentik-sdk https://github.com/kgentik/kgentik-sdk.git
```

Push the SDK directory to the public repository:

```bash
git subtree push --prefix=sdk kgentik-sdk main
```

## Publishing Workflow

### 1. Version Management

Before publishing, update the version in two places:

**`sdk/pyproject.toml`:**
```toml
[project]
version = "0.1.1"  # Increment version number
```

**`sdk/kgentik/__init__.py`:**
```python
__version__ = "0.1.1"  # Must match pyproject.toml
```

### 2. Local Testing

Test the package locally before publishing:

```bash
# Clean previous builds
make sdk-clean

# Build the package
make sdk-build

# Validate the package
make sdk-check
```

### 3. Publish to TestPyPI

Always test on TestPyPI first:

```bash
make sdk-test-publish
```

This will:
- Clean previous builds
- Build the package
- Validate the package
- Upload to TestPyPI

### 4. Test Installation from TestPyPI

Verify the package works:

```bash
pip install -i https://test.pypi.org/simple/ kgentik
```

Test the installation:

```python
from kgentik.tools import KgentikTools
print("SDK imported successfully!")
```

### 5. Publish to Production PyPI

Once TestPyPI testing is successful:

```bash
make sdk-publish
```

### 6. Sync to Public Repository

After successful publication, sync changes to the public repository:

```bash
git subtree push --prefix=sdk kgentik-sdk main
```

## Available Make Commands

- `make sdk-build` - Build the SDK package
- `make sdk-clean` - Clean build artifacts
- `make sdk-check` - Validate the package
- `make sdk-test-publish` - Publish to TestPyPI
- `make sdk-publish` - Publish to production PyPI

## Manual Publishing (Alternative)

If you prefer manual control:

```bash
# Build
cd sdk
python -m pip install build twine
python -m build

# Check
python -m twine check dist/*

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

# Upload to production PyPI
python -m twine upload dist/*
```

## Troubleshooting

### Common Issues

1. **Version Already Exists**
   - PyPI doesn't allow republishing the same version
   - Increment the version number and try again

2. **API Key Issues**
   - Ensure `.pypi_api_key` exists and contains a valid token
   - Check that the token has the correct permissions

3. **Build Failures**
   - Run `make sdk-clean` to remove old artifacts
   - Check that all dependencies are installed

4. **Git Subtree Issues**
   - Ensure the public repository exists and is accessible
   - Check that you have push permissions

### Error Messages

- `No kgentik.yaml found` - This is expected when testing the SDK outside a kgentik project
- `Tool 'xyz' not found` - This is expected when testing without proper tool files

## Security Notes

- Never commit `.pypi_api_key` to version control
- Use different API tokens for TestPyPI and production PyPI if desired
- Rotate API tokens regularly for security

## Version Numbering

Follow [Semantic Versioning](https://semver.org/):

- **MAJOR** (1.0.0): Breaking changes
- **MINOR** (0.1.0): New features, backward compatible
- **PATCH** (0.0.1): Bug fixes, backward compatible

## Release Checklist

- [ ] Update version in `pyproject.toml` and `__init__.py`
- [ ] Update CHANGELOG.md (if applicable)
- [ ] Test locally with `make sdk-build && make sdk-check`
- [ ] Publish to TestPyPI with `make sdk-test-publish`
- [ ] Test installation from TestPyPI
- [ ] Publish to production PyPI with `make sdk-publish`
- [ ] Sync to public repository with `git subtree push --prefix=sdk kgentik-sdk main`
- [ ] Create GitHub release (optional)
- [ ] Update documentation (if needed)

## Future Improvements

- Automated version bumping
- GitHub Actions for CI/CD
- Automated changelog generation
- Pre-release versions (alpha, beta, rc)
- Automated dependency updates
