PYPI_SETUP.md

🚀 PyPI Publishing Setup Complete!

The agentcoach package is now ready for publishing to PyPI. Here's what has been set up:

✅ What's Been Added

1. Updated pyproject.toml

• ✅ Added comprehensive metadata (keywords, classifiers, URLs)
• ✅ Added all Python 3.9-3.12 classifiers
• ✅ Added project URLs (homepage, docs, issues, changelog)
• ✅ Added missing dependency (jsonschema)
• ✅ Configured package data inclusion

2. MANIFEST.in

• ✅ Includes documentation files
• ✅ Includes schemas and examples
• ✅ Excludes development files

3. PUBLISHING.md

• ✅ Complete step-by-step publishing guide
• ✅ TestPyPI and PyPI instructions
• ✅ Troubleshooting section
• ✅ Best practices
• ✅ Version management guide

4. Streamlit Publishing Assistant (publish_assistant.py)

• ✅ Interactive GUI for publishing workflow
• ✅ Pre-flight checks (tests, git status, files)
• ✅ Version management with auto-calculation
• ✅ Build package with validation
• ✅ Upload to TestPyPI
• ✅ Upload to PyPI
• ✅ Auto-create git tags

5. GitHub Actions Workflow (.github/workflows/publish.yml)

• ✅ Auto-publish on version tags (v*)
• ✅ Manual workflow dispatch for TestPyPI/PyPI
• ✅ Multi-Python version testing (3.9-3.12)
• ✅ Trusted publishing with OIDC
• ✅ Auto-create GitHub releases

6. Version Management (.bumpversion.cfg)

• ✅ Automated version bumping
• ✅ Auto-commit and tag
• ✅ Updates pyproject.toml and init.py

🎯 Quick Start

Option 1: Using Streamlit Assistant (Recommended for First-Time)

# Install streamlit
pip install streamlit toml

# Run the assistant
streamlit run publish_assistant.py

The assistant will guide you through:

1. Pre-flight checks
2. Version management
3. Building the package
4. Testing on TestPyPI
5. Publishing to PyPI

Option 2: Manual Publishing

# 1. Install tools
pip install build twine bump2version

# 2. Run tests
pytest

# 3. Bump version
bumpversion patch  # or minor, or major

# 4. Build
python -m build

# 5. Check
twine check dist/*

# 6. Upload to TestPyPI (test first!)
twine upload --repository testpypi dist/*

# 7. Test installation
pip install --index-url https://test.pypi.org/simple/ \
    --extra-index-url https://pypi.org/simple/ \
    agentcoach

# 8. Upload to PyPI
twine upload dist/*

# 9. Push tags
git push origin --tags

Option 3: GitHub Actions (Automated)

# For TestPyPI
# Go to GitHub Actions → Publish to PyPI → Run workflow → Select testpypi

# For PyPI (via tag)
git tag v0.1.0
git push origin v0.1.0
# Workflow runs automatically

📋 Pre-Publishing Checklist

Before publishing, ensure:

• All tests pass (pytest)
• No uncommitted changes (git status)
• Version bumped in pyproject.toml
• CHANGELOG.md updated
• README.md is up to date
• All dependencies listed in pyproject.toml
• Package builds successfully (python -m build)
• Package passes checks (twine check dist/*)
• Tested on TestPyPI
• GitHub repository URL updated in pyproject.toml

🔑 Required Accounts & Tokens

PyPI Account

1. Create account at https://pypi.org
2. Enable 2FA
3. Create API token at https://pypi.org/manage/account/token/
4. Save token securely

TestPyPI Account (Recommended)

1. Create account at https://test.pypi.org
2. Create API token at https://test.pypi.org/manage/account/token/
3. Save token securely

GitHub (for automated publishing)

1. Go to repository Settings → Secrets and variables → Actions
2. Add secrets:
   • PYPI_API_TOKEN (for PyPI)
   • TEST_PYPI_API_TOKEN (for TestPyPI)

Or use Trusted Publishing (recommended):

1. Go to PyPI → Account settings → Publishing
2. Add GitHub repository
3. No tokens needed!

📦 Package Structure

agentcoach/
├── .github/
│   └── workflows/
│       └── publish.yml          # Auto-publish workflow
├── agentcoach/                  # Main package
├── schemas/                     # JSON schemas (included)
├── examples/                    # Examples (included)
├── tests/                       # Test suite
├── pyproject.toml              # Package metadata
├── MANIFEST.in                 # Package data config
├── PUBLISHING.md               # Publishing guide
├── publish_assistant.py        # Streamlit GUI
├── .bumpversion.cfg           # Version management
└── README.md                   # Main documentation

🎨 Streamlit Assistant Features

The publish_assistant.py provides:

Tab 1: Pre-flight Checks

• ✅ Verify required files exist
• ✅ Check git status
• ✅ Run tests
• ✅ Display results with ✅/❌

Tab 2: Version Management

• 📊 Show current version
• 🔢 Calculate new version (patch/minor/major)
• ✏️ Manual version override
• 📝 Update pyproject.toml
• 📋 Changelog template

Tab 3: Build Package

• 🧹 Clean previous builds
• 🔨 Build source + wheel
• ✅ Validate with twine check
• 📦 Show built files

Tab 4: Test on TestPyPI

• 🔐 Secure token input
• 📤 Upload to TestPyPI
• 📝 Installation instructions
• 🔗 Link to TestPyPI page

Tab 5: Publish to PyPI

• ⚠️ Confirmation required
• 🔐 Secure token input
• 🚀 Upload to PyPI
• 🎉 Success with balloons!
• 🏷️ Auto-create git tag
• 🔗 Link to PyPI page

🔄 Version Management

Using bump2version

# Install
pip install bump2version

# Bump version
bumpversion patch  # 0.1.0 → 0.1.1
bumpversion minor  # 0.1.0 → 0.2.0
bumpversion major  # 0.1.0 → 1.0.0

# This automatically:
# - Updates version in pyproject.toml
# - Updates version in agentcoach/__init__.py
# - Commits the change
# - Creates a git tag

Manual Version Update

Edit pyproject.toml:

version = "0.1.1"

And agentcoach/__init__.py:

__version__ = "0.1.1"

🤖 GitHub Actions Workflow

Trigger Methods

1. Push a version tag:

git tag v0.1.0
git push origin v0.1.0

→ Automatically publishes to PyPI

2. Manual workflow dispatch:

• Go to Actions → Publish to PyPI
• Click "Run workflow"
• Select environment (testpypi or pypi)
• Click "Run workflow"

Workflow Steps

1. Build: Creates source distribution and wheel
2. Test: Runs tests on Python 3.9, 3.10, 3.11, 3.12
3. Publish: Uploads to TestPyPI or PyPI
4. Release: Creates GitHub release (for tags)

🔒 Security Best Practices

1. Never commit tokens to git
2. Use API tokens, not passwords
3. Enable 2FA on PyPI account
4. Use project-scoped tokens after first upload
5. Rotate tokens periodically
6. Use Trusted Publishing (OIDC) when possible
7. Store tokens in environment variables or secrets manager

📚 Resources

• PyPI
• TestPyPI
• Python Packaging Guide
• Semantic Versioning
• Twine Documentation
• GitHub Actions for PyPI

🆘 Troubleshooting

"Package already exists"

You cannot re-upload the same version. Bump the version number.

"Invalid distribution"

twine check dist/*

"Import errors after install"

Check package structure:

unzip -l dist/agentcoach-0.1.0-py3-none-any.whl

"Missing dependencies"

Ensure all dependencies are in pyproject.toml.

Streamlit app won't start

pip install streamlit toml

🎉 First Release Checklist

• Update GitHub URLs in pyproject.toml
• Update author email in pyproject.toml
• Review and update README.md
• Review and update CHANGELOG.md
• Run all tests
• Build package locally
• Test on TestPyPI
• Verify installation from TestPyPI
• Publish to PyPI
• Verify installation from PyPI
• Create GitHub release
• Announce release

📝 Next Steps

1. Update GitHub URLs in pyproject.toml with your actual repository
2. Update author email in pyproject.toml
3. Test locally: python -m build && twine check dist/*
4. Test on TestPyPI: Use Streamlit assistant or manual commands
5. Publish to PyPI: Once everything works on TestPyPI
6. Set up GitHub Actions: Add secrets or configure Trusted Publishing
7. Announce: Share your package with the community!

---

Ready to publish? Run streamlit run publish_assistant.py to get started! 🚀