llmtivo 0.1.1__tar.gz

llmtivo-0.1.1/.bandit

@@ -0,0 +1,26 @@
+# Bandit configuration for LLMTivo project
+[bandit]
+exclude_dirs = [
+    "tests",
+    ".venv",
+    "build",
+    "dist"
+]
+
+# Skip certain tests that are not relevant for our use case or are false positives
+skips = [
+    "B101",  # Test for use of assert
+    "B110",  # Test for a try/except pass - used for optional dependency handling
+    "B404",  # Test for subprocess import - we use subprocess securely with absolute paths
+    "B601",  # paramiko calls (not used)
+    "B602",  # subprocess popen with shell=true (controlled usage)
+    "B603",  # subprocess without shell equals true (controlled usage)
+]
+
+# Severity level
+# LOW, MEDIUM, HIGH
+severity = MEDIUM
+
+# Confidence level
+# LOW, MEDIUM, HIGH
+confidence = MEDIUM

llmtivo-0.1.1/.github/badges/llmtivo.json

@@ -0,0 +1,7 @@
+{
+  "schemaVersion": 1,
+  "label": "MFCQI",
+  "message": "0.84 (excellent)",
+  "color": "brightgreen",
+  "cacheSeconds": 3600
+}

llmtivo-0.1.1/.github/workflows/ci.yml

@@ -0,0 +1,125 @@
+name: CI
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+  workflow_dispatch:
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        # the project declares requires-python = ">=3.11"; 3.10 was inherited from another
+        # project's config and could never have resolved
+        python-version: ['3.11', '3.12', '3.13']
+
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+
+    - name: Install UV
+      uses: astral-sh/setup-uv@v3
+      with:
+        enable-cache: true
+
+    - name: Install dependencies
+      run: |
+        uv sync --group dev --group integration
+        uv run python -c "import llmtivo; print('LLMTivo installed successfully')"
+
+    - name: Check formatting and types
+      shell: bash
+      run: |
+        uv run ruff format --check src/ tests/
+        uv run ruff check src/ tests/
+        uv run mypy --strict src/llmtivo/
+
+    # `pytest --cov` UNDER-REPORTS this project specifically: llmtivo registers a pytest11 plugin,
+    # so the package is imported while pytest loads plugins — before pytest-cov starts tracing.
+    # Every line executed at import time is then invisible (it measured 59% against a real 93%).
+    # Running coverage as the OUTER process starts tracing first and measures the truth.
+    # The integration tests run HERE, in replay, with no keys and no network: they are committed
+    # tapes of real OpenAI / Anthropic / Gemini / DeepSeek / Tavily / MCP traffic. Excluding them
+    # from CI is how a suite stops noticing that a provider changed a response shape.
+    - name: Run the suite under coverage
+      shell: bash
+      env:
+        ANTHROPIC_API_KEY: ""
+        OPENAI_API_KEY: ""
+      run: |
+        uv run coverage run --source=src/llmtivo -m pytest tests/ -v
+        uv run coverage xml
+        uv run coverage report --fail-under=85
+
+    - name: Upload coverage reports to Codecov
+      if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.12'
+      uses: codecov/codecov-action@v5
+      with:
+        token: ${{ secrets.CODECOV_TOKEN }}
+        files: ./coverage.xml
+        flags: unittests
+        name: codecov-${{ matrix.os }}-py${{ matrix.python-version }}
+        fail_ci_if_error: false
+
+    # A quality gate that only prints a warning is not a gate. `--min-score` exits non-zero, so
+    # this fails the build rather than narrating the number and passing anyway.
+    - name: MFCQI quality gate
+      if: matrix.os == 'ubuntu-latest'
+      run: uv run mfcqi-py analyze src/llmtivo --skip-llm --min-score 0.75
+
+    - name: Upload test results
+      uses: actions/upload-artifact@v4
+      if: always()
+      with:
+        name: test-results-${{ matrix.os }}-py${{ matrix.python-version }}
+        path: |
+          coverage.xml
+          htmlcov/
+
+  security:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+    - uses: astral-sh/setup-uv@v3
+    - name: Install dependencies
+      run: uv sync --group dev
+    - name: Bandit
+      run: uv run bandit -r src/ -q
+
+  build:
+    runs-on: ubuntu-latest
+    needs: test
+
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.12'
+
+    - name: Install build dependencies
+      run: pip install build twine
+
+    - name: Build package
+      run: python -m build
+
+    - name: Check package
+      run: python -m twine check dist/*
+
+    - name: Upload build artifacts
+      uses: actions/upload-artifact@v4
+      with:
+        name: python-package
+        path: dist/

llmtivo-0.1.1/.github/workflows/llmtivo-badge.yml

@@ -0,0 +1,115 @@
+name: Update LLMTivo Badge
+
+on:
+  push:
+    branches: [ main, master ]
+    paths:
+      - 'src/**'
+      - 'tests/**'
+      - 'pyproject.toml'
+  pull_request:
+    branches: [ main, master ]
+  workflow_dispatch:  # Allow manual trigger
+
+jobs:
+  update-badge:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write  # Required for git push to update badge file
+      issues: write    # Required for PR comments
+      pull-requests: write
+
+    steps:
+    - uses: actions/checkout@v3
+      with:
+        token: ${{ secrets.GITHUB_TOKEN }}
+
+    - name: Set up Python
+      uses: actions/setup-python@v4
+      with:
+        python-version: '3.13'
+
+    - name: Install UV
+      uses: astral-sh/setup-uv@v3
+      with:
+        enable-cache: true
+
+    - name: Install dependencies
+      run: |
+        uv sync --frozen
+
+    - name: Calculate LLMTivo Score
+      id: llmtivo
+      env:
+        LLMTivo_DISABLE_KEYRING: "1"
+      run: |
+        # Save old score if badge exists
+        mkdir -p .github/badges
+        if [ -f .github/badges/llmtivo.json ]; then
+          OLD_SCORE=$(python -c "import json; data=json.load(open('.github/badges/llmtivo.json')); print(data['message'].split()[0])" 2>/dev/null || echo "0.0")
+        else
+          OLD_SCORE="0.0"
+        fi
+        echo "old_score=$OLD_SCORE" >> $GITHUB_OUTPUT
+
+        # Calculate new score and save to JSON
+        uv run mfcqi-py badge src/llmtivo -f json -o .github/badges/llmtivo.json
+
+        # Extract new score
+        NEW_SCORE=$(python -c "import json; data=json.load(open('.github/badges/llmtivo.json')); print(data['message'].split()[0])")
+        echo "score=$NEW_SCORE" >> $GITHUB_OUTPUT
+
+        # Calculate delta and determine arrow
+        DELTA=$(python -c "print(f'{float('$NEW_SCORE') - float('$OLD_SCORE'):.3f}')")
+        echo "delta=$DELTA" >> $GITHUB_OUTPUT
+
+        # Determine arrow and format delta
+        if (( $(echo "$DELTA > 0" | bc -l) )); then
+          echo "arrow=↑" >> $GITHUB_OUTPUT
+          echo "delta_formatted=(+$DELTA)" >> $GITHUB_OUTPUT
+        elif (( $(echo "$DELTA < 0" | bc -l) )); then
+          echo "arrow=↓" >> $GITHUB_OUTPUT
+          echo "delta_formatted=($DELTA)" >> $GITHUB_OUTPUT
+        else
+          echo "arrow=→" >> $GITHUB_OUTPUT
+          echo "delta_formatted=(±0.000)" >> $GITHUB_OUTPUT
+        fi
+
+        # Determine if this is good enough
+        if (( $(echo "$NEW_SCORE >= 0.75" | bc -l) )); then
+          echo "status=passing" >> $GITHUB_OUTPUT
+        else
+          echo "status=failing" >> $GITHUB_OUTPUT
+        fi
+
+    - name: Commit badge update
+      if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+      run: |
+        git config --local user.email "github-actions[bot]@users.noreply.github.com"
+        git config --local user.name "github-actions[bot]"
+        git add .
+        git diff --quiet && git diff --staged --quiet || (git commit -m "chore: Update LLMTivo badge: ${{ steps.llmtivo.outputs.score }} ${{ steps.llmtivo.outputs.arrow }} ${{ steps.llmtivo.outputs.delta_formatted }}" && git push)
+
+    - name: Comment on PR
+      if: github.event_name == 'pull_request'
+      uses: actions/github-script@v6
+      with:
+        script: |
+          const score = '${{ steps.llmtivo.outputs.score }}';
+          const oldScore = '${{ steps.llmtivo.outputs.old_score }}';
+          const arrow = '${{ steps.llmtivo.outputs.arrow }}';
+          const deltaFormatted = '${{ steps.llmtivo.outputs.delta_formatted }}';
+          const status = '${{ steps.llmtivo.outputs.status }}';
+          const emoji = status === 'passing' ? '✅' : '⚠️';
+          const trendEmoji = arrow === '↑' ? '📈' : arrow === '↓' ? '📉' : '➡️';
+
+          try {
+            await github.rest.issues.createComment({
+              issue_number: context.issue.number,
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              body: `## ${emoji} LLMTivo Score: ${score} ${arrow} ${deltaFormatted}\n\n${trendEmoji} **Previous:** ${oldScore}\n\nCode quality ${status === 'passing' ? 'meets' : 'does not meet'} the minimum threshold (0.75).`
+            });
+          } catch (error) {
+            core.warning(`Unable to post LLMTivo PR comment: ${error.message}`);
+          }

llmtivo-0.1.1/.github/workflows/pages.yml

@@ -0,0 +1,37 @@
+name: Deploy Docs Site
+
+# Publishes the static landing page in docs/ to GitHub Pages. No build step — it's hand-crafted
+# HTML/CSS/JS (see docs/). The install commands are version-less (pip/pipx/uv resolve the latest
+# from PyPI), so nothing needs to be injected at deploy time.
+on:
+  push:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - ".github/workflows/pages.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow one concurrent deployment; let an in-progress run finish rather than cancel it.
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/configure-pages@v5
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs
+      - id: deployment
+        uses: actions/deploy-pages@v4

llmtivo-0.1.1/.github/workflows/release.yml

@@ -0,0 +1,337 @@
+name: Release to PyPI
+
+on:
+  release:
+    types: [published]
+
+env:
+  PYTHON_VERSION: "3.12"
+
+jobs:
+  # Verify version matches release tag (fail fast)
+  verify-version:
+    runs-on: ubuntu-latest
+    outputs:
+      version: ${{ steps.get-version.outputs.version }}
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install tomli for version parsing
+        run: pip install tomli
+
+      - name: Get package version
+        id: get-version
+        run: |
+          VERSION=$(python -c "
+          try:
+              import tomllib
+          except ModuleNotFoundError:
+              import tomli as tomllib
+          print(tomllib.load(open('pyproject.toml', 'rb'))['project']['version'])
+          ")
+          echo "version=$VERSION" >> $GITHUB_OUTPUT
+          echo "Package version: $VERSION"
+
+      - name: Verify version matches release tag
+        if: github.event_name == 'release'
+        env:
+          VERSION: ${{ steps.get-version.outputs.version }}
+        run: |
+          RELEASE_TAG=${GITHUB_REF#refs/tags/}
+          RELEASE_VERSION=${RELEASE_TAG#v}
+
+          echo "Package version: $VERSION"
+          echo "Release tag: $RELEASE_TAG"
+          echo "Release version: $RELEASE_VERSION"
+
+          if [ "$VERSION" != "$RELEASE_VERSION" ]; then
+            echo "❌ Error: Package version ($VERSION) does not match release version ($RELEASE_VERSION)"
+            echo "Please update the version in pyproject.toml to match the release tag"
+            exit 1
+          fi
+
+          echo "✅ Version verification passed"
+
+  # Test the release on Test PyPI
+  test-release:
+    needs: verify-version
+    uses: ./.github/workflows/test-release.yml
+    permissions: write-all
+    secrets: inherit
+
+  # Run comprehensive pre-release validation
+  pre-release-checks:
+    needs:
+      - verify-version
+      - test-release
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ['3.11', '3.12', '3.13']
+        os: [ubuntu-latest, macos-latest]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      # No caching - we want to catch any dependency issues
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install UV
+        uses: astral-sh/setup-uv@v3
+
+      - name: Upgrade setuptools with UV
+        run: |
+          uv pip install --system "setuptools>=40.8.0" wheel
+
+      - name: Install from Test PyPI
+        env:
+          VERSION: ${{ needs.test-release.outputs.version }}
+        run: |
+          uv pip install --system \
+            --index-strategy unsafe-best-match \
+            --extra-index-url https://test.pypi.org/simple/ \
+            "llmtivo==$VERSION" || \
+          ( \
+            sleep 5 && \
+            uv pip install --system \
+              --index-strategy unsafe-best-match \
+              --extra-index-url https://test.pypi.org/simple/ \
+              "llmtivo==$VERSION" \
+          )
+
+      - name: Install test dependencies
+        run: uv sync --group dev --group integration
+
+      - name: Reinstall package from Test PyPI
+        env:
+          VERSION: ${{ needs.test-release.outputs.version }}
+        run: |
+          uv pip install --system \
+            --extra-index-url https://test.pypi.org/simple/ \
+            --force-reinstall --no-deps \
+            "llmtivo==$VERSION"
+
+      - name: Run full test suite
+        env:
+          ANTHROPIC_API_KEY: ""
+          OPENAI_API_KEY: ""
+        run: |
+          uv run pytest tests/ -v --tb=short
+          echo "✅ All tests passed on Python ${{ matrix.python-version }}"
+
+      - name: Run type checking
+        run: |
+          uv run mypy --strict src/llmtivo/
+          echo "✅ Type checking passed"
+
+      - name: Run linting
+        run: |
+          uv run ruff check src/
+          echo "✅ Linting passed"
+
+      # `--min-score` exits non-zero. The previous version printed a warning and released anyway,
+      # which is a gate that cannot fail — worse than none, because the log says it was checked.
+      - name: MFCQI quality gate
+        run: uv run mfcqi-py analyze src/llmtivo --skip-llm --min-score 0.75
+
+  # Get minimum dependency versions and test with them
+  test-min-versions:
+    needs:
+      - verify-version
+      - test-release
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ env.PYTHON_VERSION }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
+
+      - name: Install UV
+        uses: astral-sh/setup-uv@v3
+
+      - name: Upgrade setuptools with UV
+        run: |
+          uv pip install --system "setuptools>=40.8.0" wheel
+
+      - name: Install from Test PyPI
+        env:
+          VERSION: ${{ needs.test-release.outputs.version }}
+        run: |
+          uv pip install --system \
+            --index-strategy unsafe-best-match \
+            --extra-index-url https://test.pypi.org/simple/ \
+            "llmtivo==$VERSION"
+
+      - name: Install tomli for pyproject parsing
+        run: uv pip install --system tomli
+
+      - name: Get minimum versions from pyproject.toml
+        id: min-versions
+        run: |
+          # Extract minimum versions from dependencies
+          python -c "
+          try:
+              import tomllib
+          except ModuleNotFoundError:
+              import tomli as tomllib
+          import re
+
+          with open('pyproject.toml', 'rb') as f:
+              data = tomllib.load(f)
+
+          deps = data['project']['dependencies']
+          min_versions = []
+
+          for dep in deps:
+              # Parse 'package>=1.2.3' -> 'package==1.2.3'
+              match = re.match(r'([a-zA-Z0-9_-]+)>=([0-9.]+)', dep)
+              if match:
+                  pkg, ver = match.groups()
+                  # Skip some packages that have complex version constraints
+                  if pkg not in ['networkx', 'scipy']:
+                      min_versions.append(f'{pkg}=={ver}')
+
+          print(' '.join(min_versions))
+          " > /tmp/min_versions.txt
+
+          MIN_VERSIONS=$(cat /tmp/min_versions.txt)
+          echo "min-versions=$MIN_VERSIONS" >> $GITHUB_OUTPUT
+          echo "Minimum versions: $MIN_VERSIONS"
+
+      - name: Install test dependencies
+        run: uv sync --group dev --group integration
+
+      - name: Install minimum dependency versions
+        if: steps.min-versions.outputs.min-versions != ''
+        env:
+          MIN_VERSIONS: ${{ steps.min-versions.outputs.min-versions }}
+        run: |
+          if [ -n "$MIN_VERSIONS" ]; then
+            uv pip install --system $MIN_VERSIONS
+            echo "✅ Installed minimum versions"
+          fi
+
+      - name: Run tests with minimum versions
+        if: steps.min-versions.outputs.min-versions != ''
+        env:
+          ANTHROPIC_API_KEY: ""
+          OPENAI_API_KEY: ""
+        run: |
+          uv run pytest tests/ -v --tb=short
+          echo "✅ Tests passed with minimum dependency versions"
+
+  # Only publish to production PyPI after all validations pass
+  publish-pypi:
+    needs:
+      - verify-version
+      - test-release
+      - pre-release-checks
+      - test-min-versions
+    runs-on: ubuntu-latest
+    environment: release
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Download build artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: test-dist
+          path: dist/
+
+      - name: Publish to production PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}
+          verbose: true
+          print-hash: true
+          attestations: false
+
+  # Create or update GitHub release
+  mark-release:
+    needs:
+      - verify-version
+      - test-release
+      - pre-release-checks
+      - test-min-versions
+      - publish-pypi
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Download build artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: test-dist
+          path: dist/
+
+      - name: Update release with PyPI links
+        uses: actions/github-script@v7
+        env:
+          VERSION: ${{ needs.verify-version.outputs.version }}
+        with:
+          script: |
+            const version = process.env.VERSION;
+            const packageName = 'llmtivo';
+
+            // Get the release (either from the release event or find by tag)
+            let release;
+            if (context.eventName === 'release') {
+              release = context.payload.release;
+            } else {
+              // For workflow_dispatch, find the latest release
+              const { data: releases } = await github.rest.repos.listReleases({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                per_page: 1
+              });
+              release = releases[0];
+            }
+
+            if (!release) {
+              console.log('No release found, skipping update');
+              return;
+            }
+
+            const pypiLinks = `
+
+            ## 📦 PyPI Release
+
+            This release is now available on PyPI:
+
+            - **PyPI Package**: https://pypi.org/project/${packageName}/${version}/
+            - **Installation**: \`pip install ${packageName}==${version}\`
+            - **Upgrade**: \`pip install --upgrade ${packageName}\`
+
+            ### Quick Start
+
+            \`\`\`bash
+            pip install ${packageName}[pytest]
+            pytest                      # replay — CI-safe, costs nothing
+            pytest --llmtivo=record-new # record only the tests with no tape yet
+            \`\`\`
+
+            ### What's New in v${version}
+
+            See the full changelog above for details.
+            `;
+
+            await github.rest.repos.updateRelease({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              release_id: release.id,
+              body: (release.body || '') + pypiLinks
+            });
+
+            console.log('✅ Updated release with PyPI links');