genai-otel-instrument 0.1.27__tar.gz

genai_otel_instrument-0.1.27/.claude/settings.local.json

@@ -0,0 +1,9 @@
+{
+  "permissions": {
+    "allow": [
+
+    ],
+    "deny": [],
+    "ask": []
+  }
+}

genai_otel_instrument-0.1.27/.github/RELEASE_GUIDE.md

@@ -0,0 +1,179 @@
+# Release Guide
+
+This guide explains how to publish new versions of `genai-otel-instrument` to PyPI.
+
+## Automated Publishing Workflow
+
+The repository is configured to automatically publish to PyPI when you create a GitHub release. The workflow:
+
+1. ✅ Runs full test suite
+2. ✅ Checks code quality (black, isort)
+3. ✅ Builds the package
+4. ✅ Tests package installation
+5. 📦 Publishes to Test PyPI
+6. ✅ Verifies Test PyPI upload
+7. 📦 Publishes to production PyPI
+8. 📋 Creates release summary
+
+## Prerequisites
+
+Before creating a release, ensure:
+
+- [ ] All tests pass: `pytest tests/ -v`
+- [ ] Code is properly formatted: `black genai_otel tests && isort genai_otel tests`
+- [ ] CHANGELOG.md is updated with release notes
+- [ ] Version is bumped (handled by `setuptools_scm` based on git tags)
+- [ ] All changes are committed and pushed to `main` branch
+
+## Creating a Release
+
+### Method 1: GitHub UI (Recommended)
+
+1. Navigate to https://github.com/YOUR_ORG/genai-otel-instrument/releases/new
+
+2. Click "Choose a tag" and create a new tag:
+   - Format: `v{MAJOR}.{MINOR}.{PATCH}` (e.g., `v0.1.14`)
+   - Target: `main` branch
+
+3. Fill in release details:
+   - **Release title**: Same as tag (e.g., `v0.1.14`)
+   - **Description**: Copy relevant section from CHANGELOG.md
+
+4. Click "Publish release"
+
+5. Monitor the workflow:
+   - Go to Actions tab
+   - Watch "Publish to PyPI" workflow
+
+### Method 2: GitHub CLI
+
+```bash
+# Create and push a tag
+git tag -a v0.1.14 -m "Release v0.1.14: Added LangChain chat model support"
+git push origin v0.1.14
+
+# Create release from tag
+gh release create v0.1.14 \
+  --title "v0.1.14" \
+  --notes-file CHANGELOG.md \
+  --target main
+```
+
+### Method 3: Manual Trigger (Testing)
+
+For testing the workflow without creating a release:
+
+1. Go to Actions tab
+2. Select "Publish to PyPI" workflow
+3. Click "Run workflow"
+4. Select branch and click "Run workflow"
+
+**Note**: Manual triggers will run tests but won't publish to PyPI (only releases trigger publishing).
+
+## Versioning Strategy
+
+This project uses `setuptools_scm` for automatic versioning:
+
+- **Version source**: Git tags
+- **Format**: Semantic Versioning (MAJOR.MINOR.PATCH)
+- **Pre-releases**: Add suffix like `-alpha.1`, `-beta.1`, `-rc.1`
+
+### Version Bumping Guidelines
+
+- **MAJOR**: Breaking changes, incompatible API changes
+- **MINOR**: New features, backward-compatible additions
+- **PATCH**: Bug fixes, backward-compatible improvements
+
+### Examples
+
+```bash
+# Patch release (bug fixes)
+git tag v0.1.14
+
+# Minor release (new features)
+git tag v0.2.0
+
+# Major release (breaking changes)
+git tag v1.0.0
+
+# Pre-release
+git tag v0.2.0-rc.1
+```
+
+## Secrets Configuration
+
+The workflow uses these GitHub secrets (already configured):
+
+- `TEST_PYPI_API_TOKEN`: Token for https://test.pypi.org
+- `PYPI_API_TOKEN`: Token for https://pypi.org
+
+### Rotating Tokens
+
+If tokens need rotation:
+
+1. Generate new tokens:
+   - TestPyPI: https://test.pypi.org/manage/account/token/
+   - PyPI: https://pypi.org/manage/account/token/
+
+2. Update GitHub secrets:
+   - Go to repository Settings → Secrets and variables → Actions
+   - Update `TEST_PYPI_API_TOKEN` and `PYPI_API_TOKEN`
+
+## Manual Publishing (Fallback)
+
+If automated workflow fails, publish manually:
+
+```bash
+# Install build tools
+pip install build twine
+
+# Build package
+python -m build
+
+# Publish to Test PyPI
+python -m twine upload --verbose --repository testpypi --username __token__ --password YOUR_TEST_PYPI_TOKEN dist/*
+
+# Verify Test PyPI installation
+pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ genai-otel-instrument
+
+# Publish to PyPI
+python -m twine upload --verbose dist/* --username __token__ --password YOUR_PYPI_TOKEN
+```
+
+## Post-Release Checklist
+
+After publishing:
+
+- [ ] Verify package on PyPI: https://pypi.org/project/genai-otel-instrument/
+- [ ] Test installation: `pip install genai-otel-instrument --upgrade`
+- [ ] Update documentation if needed
+- [ ] Announce release (if major version)
+- [ ] Monitor GitHub issues for installation problems
+
+## Troubleshooting
+
+### Workflow fails on test step
+- Review test failures in Actions logs
+- Fix issues locally and create new release
+
+### "File already exists" error on PyPI
+- Package version already published
+- Bump version number and create new release
+- **Note**: Cannot overwrite existing PyPI versions
+
+### Test PyPI upload succeeds but PyPI fails
+- Check PyPI token is valid
+- Verify package metadata
+- Check for naming conflicts
+
+### Secrets not working
+- Verify secrets are set in repository settings
+- Check secret names match workflow file exactly
+- Ensure tokens have correct permissions
+
+## References
+
+- [Python Packaging Guide](https://packaging.python.org/)
+- [Twine Documentation](https://twine.readthedocs.io/)
+- [GitHub Actions](https://docs.github.com/en/actions)
+- [Semantic Versioning](https://semver.org/)

genai_otel_instrument-0.1.27/.github/RELEASE_QUICKSTART.md

@@ -0,0 +1,112 @@
+# Quick Release Guide
+
+## TL;DR - Release Checklist
+
+```bash
+# 1. Update CHANGELOG.md with release notes
+# 2. Commit changes
+git add .
+git commit -m "chore: Prepare release v0.1.14"
+git push origin main
+
+# 3. Create and push tag
+git tag v0.1.14
+git push origin v0.1.14
+
+# 4. Create GitHub release (triggers auto-publish)
+gh release create v0.1.14 --title "v0.1.14" --notes-file <(sed -n '/## \[0.1.14\]/,/## \[/p' CHANGELOG.md | head -n -1)
+```
+
+## What Happens Automatically?
+
+When you create a GitHub release:
+
+1. ✅ **Tests run** - Full pytest suite with coverage
+2. ✅ **Quality checks** - black, isort formatting validation
+3. ✅ **Package builds** - Creates wheel and source distribution
+4. ✅ **Installation test** - Verifies package can be installed
+5. 📦 **Publishes to TestPyPI** - Test environment first
+6. ⏳ **Waits 30s** - Allows TestPyPI to process
+7. ✅ **Verifies TestPyPI** - Attempts installation from test server
+8. 📦 **Publishes to PyPI** - Production release
+9. 📋 **Creates summary** - Release report in GitHub Actions
+
+## Version Format
+
+```
+v{MAJOR}.{MINOR}.{PATCH}[-{PRE-RELEASE}]
+
+Examples:
+  v0.1.14          # Patch release
+  v0.2.0           # Minor release
+  v1.0.0           # Major release
+  v0.2.0-rc.1      # Release candidate
+  v0.2.0-beta.2    # Beta release
+```
+
+## Common Commands
+
+```bash
+# Check current version
+git describe --tags --abbrev=0
+
+# List all tags
+git tag -l
+
+# Delete local tag (if mistake)
+git tag -d v0.1.14
+
+# Delete remote tag (if mistake)
+git push origin :refs/tags/v0.1.14
+
+# View workflow status
+gh run list --workflow=publish.yml
+
+# View workflow logs
+gh run view --log
+
+# Manual workflow trigger (for testing)
+gh workflow run publish.yml
+```
+
+## Quick Fixes
+
+### "Tests failed" in workflow
+```bash
+# Run tests locally first
+pytest tests/ -v
+
+# Fix issues and recommit
+git add .
+git commit -m "fix: Address test failures"
+git push
+
+# Delete and recreate tag
+git tag -d v0.1.14
+git push origin :refs/tags/v0.1.14
+git tag v0.1.14
+git push origin v0.1.14
+```
+
+### "Package already exists" error
+```bash
+# Can't overwrite published versions
+# Must increment version
+git tag v0.1.15
+git push origin v0.1.15
+gh release create v0.1.15 --title "v0.1.15" --notes "Hotfix release"
+```
+
+### View published packages
+- TestPyPI: https://test.pypi.org/project/genai-otel-instrument/
+- PyPI: https://pypi.org/project/genai-otel-instrument/
+
+## Secrets Location
+
+GitHub Repository Settings → Secrets and variables → Actions:
+- `TEST_PYPI_API_TOKEN` - For test.pypi.org
+- `PYPI_API_TOKEN` - For pypi.org
+
+---
+
+**For detailed information, see [RELEASE_GUIDE.md](RELEASE_GUIDE.md)**

genai_otel_instrument-0.1.27/.github/workflows/README.md

@@ -0,0 +1,203 @@
+# CI/CD Workflows
+
+This directory contains GitHub Actions workflows for automated testing, validation, and publishing.
+
+## Workflows
+
+### 1. `test.yml` - Continuous Integration Tests
+
+**Triggers:**
+- Push to `main` or `develop` branches
+- Pull requests to `main` or `develop` branches
+
+**Jobs:**
+
+#### `test` job
+- **Matrix:** Runs on Ubuntu, macOS, and Windows with Python 3.8-3.12
+- **Steps:**
+  1. Lint with pylint
+  2. Check formatting with black
+  3. Check import sorting with isort
+  4. Type check with mypy
+  5. Run pytest with coverage
+  6. Upload coverage to Codecov
+
+#### `build-and-install-test` job
+- **Matrix:** Runs on Ubuntu and Windows with Python 3.9 and 3.12
+- **Purpose:** Validates that the package can be built and installed correctly
+- **Steps:**
+  1. Build the package using `python -m build`
+  2. Check package with `twine check`
+  3. Install in isolated virtual environment
+  4. Test core imports
+  5. Verify CLI tool works (`genai-instrument --help`)
+
+#### `security` job
+- **Platform:** Ubuntu with Python 3.11
+- **Steps:**
+  1. Run safety check for dependency vulnerabilities
+  2. Run bandit security scan
+
+### 2. `publish.yml` - PyPI Publication
+
+**Triggers:**
+- Release published on GitHub
+- Manual workflow dispatch (for testing)
+
+**Steps:**
+1. **Test Suite:** Runs full pytest suite to ensure all tests pass
+2. **Code Quality:** Validates formatting and import sorting
+3. **Build:** Creates wheel and sdist packages
+4. **Validation:** Checks package with twine
+5. **Installation Test:** Tests package installation in clean environment
+6. **Publish to Test PyPI:** Uploads to Test PyPI (if release event)
+7. **Publish to PyPI:** Uploads to production PyPI (if release event)
+
+**Required Secrets:**
+- `TEST_PYPI_API_TOKEN`: API token for Test PyPI
+- `PYPI_API_TOKEN`: API token for production PyPI
+
+### 3. `pre-release-check.yml` - Pre-Release Validation
+
+**Triggers:**
+- Manual workflow dispatch
+- Push of version tags (`v*`)
+
+**Purpose:** Comprehensive validation before creating a release (mimics `scripts/test_release.sh`)
+
+**Matrix:** Runs on Ubuntu, Windows, and macOS with Python 3.9 and 3.12
+
+**Steps:**
+1. Display environment information
+2. Install development dependencies
+3. Auto-format code (isort + black)
+4. Run full test suite with coverage
+5. Perform code quality checks
+6. Build package
+7. Validate package with twine
+8. Test installation in isolated environment
+9. Verify CLI functionality
+10. Upload build artifacts (Ubuntu + Python 3.12 only)
+
+**Use this workflow:**
+- Before creating a new release
+- To validate your changes work across all platforms
+- As a final check that everything is ready for publication
+
+## Usage Examples
+
+### Running Pre-Release Validation Manually
+
+1. Go to "Actions" tab in GitHub
+2. Select "Pre-Release Validation" workflow
+3. Click "Run workflow"
+4. Select branch and click "Run workflow"
+
+This will run all validation checks across all platforms.
+
+### Creating a Release
+
+1. **Run Pre-Release Validation:**
+   ```bash
+   # Locally, you can use:
+   ./scripts/test_release.sh
+
+   # Or trigger the GitHub Action manually
+   ```
+
+2. **Ensure all checks pass**
+
+3. **Create and push a version tag:**
+   ```bash
+   git tag v0.2.0
+   git push origin v0.2.0
+   ```
+   This triggers the pre-release-check workflow.
+
+4. **Create GitHub Release:**
+   - Go to "Releases" → "Draft a new release"
+   - Select the tag you created
+   - Fill in release notes
+   - Click "Publish release"
+
+   This triggers the publish workflow which will:
+   - Run tests
+   - Build package
+   - Publish to Test PyPI
+   - Publish to PyPI
+
+### Manual Testing Before Release
+
+Use the local script for faster iteration:
+
+```bash
+# From project root
+./scripts/test_release.sh
+```
+
+This script provides colored output and validates:
+- Project structure
+- Python environment
+- Code formatting (auto-applies)
+- Full test suite
+- Package build
+- Package validation
+- Installation in isolated environment
+- CLI functionality
+
+## Workflow Dependencies
+
+All workflows require these tools (automatically installed):
+- `pytest` - Testing framework
+- `pytest-cov` - Coverage plugin
+- `black` - Code formatter
+- `isort` - Import sorter
+- `pylint` - Linter
+- `mypy` - Type checker
+- `build` - Package builder
+- `twine` - Package uploader
+
+## Best Practices
+
+1. **Before committing:**
+   - Run `black genai_otel tests`
+   - Run `isort genai_otel tests`
+   - Run `pytest tests/`
+
+2. **Before creating a PR:**
+   - Ensure all CI checks pass
+   - Review coverage report
+
+3. **Before releasing:**
+   - Run `./scripts/test_release.sh` locally
+   - Trigger "Pre-Release Validation" workflow
+   - Verify all platforms pass
+   - Update CHANGELOG.md
+   - Update version in `genai_otel/__version__.py`
+
+4. **After releasing:**
+   - Test installation from PyPI: `pip install genai-otel-instrument`
+   - Verify functionality with example code
+   - Monitor for any user-reported issues
+
+## Troubleshooting
+
+### Tests fail only on specific OS
+- Check for platform-specific path handling
+- Review file permission issues (especially on Windows)
+- Check line ending differences (CRLF vs LF)
+
+### Package build fails
+- Ensure `pyproject.toml` is valid
+- Check MANIFEST.in includes all necessary files
+- Verify dependencies are correctly specified
+
+### Installation test fails
+- Check entry points in `pyproject.toml`
+- Verify all required files are included in the package
+- Test locally with: `pip install dist/*.whl`
+
+### CLI tool not found after installation
+- Verify `[project.scripts]` section in `pyproject.toml`
+- Check that console_scripts entry point is correct
+- Test with: `python -m genai_otel.cli`

genai_otel_instrument-0.1.27/.github/workflows/pre-release-check.yml

@@ -0,0 +1,128 @@
+name: Pre-Release Validation
+
+# This workflow mimics the manual test_release.sh script
+# Run it before creating a release to validate everything works
+
+on:
+  workflow_dispatch:  # Manual trigger only
+  push:
+    tags:
+      - 'v*'  # Trigger on version tags
+
+jobs:
+  pre-release-validation:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python-version: ["3.9", "3.12"]
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+
+    - name: Display environment info
+      run: |
+        echo "=========================================="
+        echo "Pre-Release Validation"
+        echo "=========================================="
+        python --version
+        python -c "import sys; print(f'Python path: {sys.executable}')"
+
+    - name: Install development dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install -e ".[dev]"
+
+    - name: Auto-format code
+      run: |
+        echo "→ Auto-formatting code with isort and black..."
+        isort genai_otel tests
+        black genai_otel tests
+        echo "✓ Code formatting applied"
+
+    - name: Run full test suite
+      run: |
+        echo "→ Running tests..."
+        pytest tests/ -v --cov=genai_otel --cov-report=term --cov-report=html --cov-report=term-missing
+        echo "✓ All tests passed"
+
+    - name: Code quality checks
+      run: |
+        echo "→ Running code quality checks..."
+        black --check genai_otel tests --exclude='__version__\.py'
+        isort --check-only --skip-glob='*/__version__.py' genai_otel tests
+        pylint genai_otel --rcfile=.pylintrc --exit-zero || true
+        echo "✓ Code quality checks complete"
+
+    - name: Build package
+      run: |
+        echo "→ Building package..."
+        pip install build twine
+        python -m build
+        echo "✓ Package built successfully"
+
+    - name: Check package with twine
+      run: |
+        echo "→ Checking package with twine..."
+        twine check dist/*
+        echo "✓ Package check passed"
+
+    - name: Test installation in isolated environment
+      shell: bash
+      run: |
+        echo "→ Testing installation in temporary environment..."
+
+        # Create temporary virtual environment
+        python -m venv test_release_env
+
+        # Activate based on OS
+        if [[ "$RUNNER_OS" == "Windows" ]]; then
+          source test_release_env/Scripts/activate
+        else
+          source test_release_env/bin/activate
+        fi
+
+        # Install the built wheel
+        pip install dist/*.whl
+
+        # Test imports
+        python -c 'import genai_otel; print(f"Successfully imported genai_otel version: {genai_otel.__version__}")'
+        python -c 'from genai_otel.config import OTelConfig; from genai_otel.cost_calculator import CostCalculator; from genai_otel.auto_instrument import setup_auto_instrumentation; print("All core components imported successfully")'
+
+        # Test CLI tool
+        genai-instrument --help > /dev/null 2>&1
+        echo "✓ CLI tool works"
+
+        # Cleanup
+        deactivate
+
+    - name: Upload build artifacts
+      uses: actions/upload-artifact@v4
+      if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.12'
+      with:
+        name: dist-packages
+        path: dist/
+
+    - name: Summary
+      if: success()
+      run: |
+        echo ""
+        echo "=========================================="
+        echo "✓ All Pre-Release Checks Passed!"
+        echo "=========================================="
+        echo ""
+        echo "Release Checklist:"
+        echo "✅ All tests passing"
+        echo "✅ Code formatting applied"
+        echo "✅ Import sorting applied"
+        echo "✅ Package builds successfully"
+        echo "✅ Installation tested"
+        echo "✅ CLI tool works"
+        echo ""
+        echo "Ready for release! 🚀"