mnesis 0.1.0__tar.gz

mnesis-0.1.0/.github/dependabot.yml

@@ -0,0 +1,16 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for all configuration options:
+# https://docs.github.com/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file
+
+version: 2
+updates:
+  - package-ecosystem: "uv"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"

mnesis-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,95 @@
+name: CI
+permissions:
+  contents: read
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "src/**"
+      - "tests/**"
+      - "pyproject.toml"
+  pull_request:
+    branches: [main]
+    paths:
+      - "src/**"
+      - "tests/**"
+      - "pyproject.toml"
+
+jobs:
+  lint:
+    name: Lint & Format
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@eac588ad8def6316056a12d4907a9d4d84ff7a3b # v7.3.0
+        with:
+          enable-cache: true
+          cache-dependency-glob: "**/pyproject.toml"
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: uv sync --dev
+
+      - name: Ruff lint
+        run: uv run ruff check src/ tests/
+
+      - name: Ruff format check
+        run: uv run ruff format --check src/ tests/
+
+  typecheck:
+    name: Type Check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@eac588ad8def6316056a12d4907a9d4d84ff7a3b # v7.3.0
+        with:
+          enable-cache: true
+          cache-dependency-glob: "**/pyproject.toml"
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: uv sync --dev
+
+      - name: mypy
+        run: uv run mypy src/mnesis
+
+  test:
+    name: Tests (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@eac588ad8def6316056a12d4907a9d4d84ff7a3b # v7.3.0
+        with:
+          enable-cache: true
+          cache-dependency-glob: "**/pyproject.toml"
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --dev
+
+      - name: Run tests
+        env:
+          MNESIS_MOCK_LLM: "1"
+        run: uv run pytest
+
+      - name: Upload coverage report
+        if: matrix.python-version == '3.12'
+        uses: codecov/codecov-action@671740ac38dd9b0130fbe1cec585b89eea48d3de # v5
+        with:
+          files: coverage.xml
+          fail_ci_if_error: false
+          use_oidc: true

mnesis-0.1.0/.github/workflows/dependency-review.yml

@@ -0,0 +1,24 @@
+name: Dependency Review
+
+on:
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+  pull-requests: write  # post inline comments on vulnerable deps
+
+jobs:
+  dependency-review:
+    name: Dependency Review
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Dependency Review
+        uses: actions/dependency-review-action@ce3cf9537a52e8119d91fd484ab5b8a807627bf8 # v4.6.0
+        with:
+          # Fail on any vulnerability severity
+          fail-on-severity: low
+          # Post a summary comment on the PR
+          comment-summary-in-pr: always

mnesis-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,67 @@
+name: Docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+      - "src/**"
+  pull_request:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+      - "src/**"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Only one deployment at a time; don't cancel in-progress runs
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: Build Docs
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@eac588ad8def6316056a12d4907a9d4d84ff7a3b # v7.3.0
+        with:
+          enable-cache: true
+          cache-dependency-glob: "**/pyproject.toml"
+          python-version: "3.12"
+
+      - name: Install docs dependencies
+        run: uv sync --group docs
+
+      - name: Build docs
+        run: uv run mkdocs build
+
+      - name: Upload pages artifact
+        if: github.event_name != 'pull_request'
+        uses: actions/upload-pages-artifact@7b1f4a764d45c48632c6b24a0339c27f5614fb0b # v4.0.0
+        with:
+          path: site/
+
+  deploy:
+    name: Deploy to GitHub Pages
+    if: github.event_name != 'pull_request'
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy
+        id: deployment
+        uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4

mnesis-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,309 @@
+name: Publish
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "Version to release (e.g. 0.2.0)"
+        required: true
+        type: string
+      notes:
+        description: "Release notes (markdown bullet points). Leave blank to auto-generate from git log."
+        required: false
+        type: string
+
+permissions:
+  contents: read
+  id-token: write      # PyPI OIDC + Sigstore signing
+  attestations: write  # build provenance attestations
+
+jobs:
+  # ── 1. Validate inputs ────────────────────────────────────────────────────
+  validate:
+    name: Validate version
+    runs-on: ubuntu-latest
+    outputs:
+      version: ${{ steps.check.outputs.version }}
+      tag: ${{ steps.check.outputs.tag }}
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          fetch-depth: 0
+
+      - name: Check version format, ordering, and uniqueness
+        id: check
+        run: |
+          VERSION="${{ inputs.version }}"
+
+          # Must be X.Y.Z (no leading v)
+          if ! echo "$VERSION" | grep -Eq '^[0-9]+\.[0-9]+\.[0-9]+$'; then
+            echo "::error::Version '$VERSION' is not valid semver (expected X.Y.Z)"
+            exit 1
+          fi
+
+          TAG="v${VERSION}"
+
+          # Tag must not already exist
+          if git rev-parse "$TAG" >/dev/null 2>&1; then
+            echo "::error::Tag '$TAG' already exists"
+            exit 1
+          fi
+
+          # Changelog must not already have an entry for this version
+          if grep -q "^## ${VERSION}" docs/changelog.md; then
+            echo "::error::docs/changelog.md already has an entry for ${VERSION}"
+            exit 1
+          fi
+
+          # Version must be strictly greater than the latest release tag
+          LAST_TAG=$(git tag --sort=-version:refname | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+$' | head -1)
+          if [ -n "$LAST_TAG" ]; then
+            LAST_VERSION="${LAST_TAG#v}"
+            python3 - <<PYEOF
+          import sys
+
+          def parse(v):
+              return tuple(int(x) for x in v.split('.'))
+
+          new  = parse("${VERSION}")
+          last = parse("${LAST_VERSION}")
+          if new <= last:
+              print(f"::error::Version ${VERSION} is not greater than last release ${LAST_VERSION}")
+              sys.exit(1)
+          print(f"Version ${VERSION} > ${LAST_VERSION} ✓")
+          PYEOF
+          fi
+
+          echo "version=${VERSION}" >> "$GITHUB_OUTPUT"
+          echo "tag=${TAG}"         >> "$GITHUB_OUTPUT"
+
+  # ── 2. Full CI gate ───────────────────────────────────────────────────────
+  lint:
+    name: Lint & Format
+    needs: validate
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@eac588ad8def6316056a12d4907a9d4d84ff7a3b # v7.3.0
+        with:
+          enable-cache: true
+          cache-dependency-glob: "**/pyproject.toml"
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: uv sync --dev
+
+      - name: Ruff lint
+        run: uv run ruff check src/ tests/
+
+      - name: Ruff format check
+        run: uv run ruff format --check src/ tests/
+
+  typecheck:
+    name: Type Check
+    needs: validate
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@eac588ad8def6316056a12d4907a9d4d84ff7a3b # v7.3.0
+        with:
+          enable-cache: true
+          cache-dependency-glob: "**/pyproject.toml"
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: uv sync --dev
+
+      - name: mypy
+        run: uv run mypy src/mnesis
+
+  test:
+    name: Tests (Python ${{ matrix.python-version }})
+    needs: validate
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@eac588ad8def6316056a12d4907a9d4d84ff7a3b # v7.3.0
+        with:
+          enable-cache: true
+          cache-dependency-glob: "**/pyproject.toml"
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --dev
+
+      - name: Run tests
+        env:
+          MNESIS_MOCK_LLM: "1"
+        run: uv run pytest
+
+  # ── 3. Release ────────────────────────────────────────────────────────────
+  release:
+    name: Release v${{ needs.validate.outputs.version }}
+    needs: [validate, lint, typecheck, test]
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - name: Generate release token
+        id: app-token
+        uses: actions/create-github-app-token@29824e69f54612133e76f7eaac726eef6c875baf # v2.2.1
+        with:
+          app-id: ${{ secrets.RELEASE_APP_ID }}
+          private-key: ${{ secrets.RELEASE_APP_PRIVATE_KEY }}
+
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          fetch-depth: 0
+          token: ${{ steps.app-token.outputs.token }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@eac588ad8def6316056a12d4907a9d4d84ff7a3b # v7.3.0
+        with:
+          enable-cache: true
+          cache-dependency-glob: "**/pyproject.toml"
+          python-version: "3.12"
+
+      - name: Configure git identity
+        run: |
+          git config user.name  "Mnesis Release Bot"
+          git config user.email "mnesis-release-bot[bot]@users.noreply.github.com"
+
+      # ── 3a. Resolve release notes ────────────────────────────────────────
+      - name: Resolve release notes
+        id: notes
+        run: |
+          NOTES="${{ inputs.notes }}"
+
+          if [ -z "$NOTES" ]; then
+            LAST_TAG=$(git tag --sort=-version:refname | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+$' | head -1)
+            if [ -n "$LAST_TAG" ]; then
+              NOTES=$(git log "${LAST_TAG}..HEAD" --pretty=format:"- %s" --no-merges)
+            else
+              NOTES=$(git log HEAD --pretty=format:"- %s" --no-merges)
+            fi
+          fi
+
+          printf '%s' "$NOTES" > /tmp/release_notes.md
+
+          echo "notes<<EOF" >> "$GITHUB_OUTPUT"
+          printf '%s\n' "$NOTES" >> "$GITHUB_OUTPUT"
+          echo "EOF" >> "$GITHUB_OUTPUT"
+
+      # ── 3b. Bump version in pyproject.toml ──────────────────────────────
+      - name: Bump version in pyproject.toml
+        run: |
+          VERSION="${{ needs.validate.outputs.version }}"
+          sed -i "s/^version = \".*\"/version = \"${VERSION}\"/" pyproject.toml
+          grep '^version = ' pyproject.toml
+
+      # ── 3c. Prepend changelog entry ──────────────────────────────────────
+      - name: Update docs/changelog.md
+        env:
+          VERSION: ${{ needs.validate.outputs.version }}
+          NOTES: ${{ steps.notes.outputs.notes }}
+        run: |
+          python3 - <<'PYEOF'
+          import pathlib, os, datetime
+
+          path    = pathlib.Path("docs/changelog.md")
+          text    = path.read_text()
+          lines   = text.splitlines(keepends=True)
+          version = os.environ["VERSION"]
+          date    = datetime.date.today().strftime("%Y-%m-%d")
+          notes   = os.environ["NOTES"].strip()
+
+          insert = 1
+          for i, line in enumerate(lines):
+              if i == 0:
+                  continue
+              if line.strip() == "" and i == 1:
+                  insert = 2
+                  break
+
+          new_section = f"## {version} — {date}\n\n{notes}\n\n"
+          lines.insert(insert, new_section)
+          path.write_text("".join(lines))
+          print(f"Prepended changelog entry for {version}")
+          PYEOF
+
+      # ── 3d. Build distribution ───────────────────────────────────────────
+      # Build before pushing so a build failure leaves the repo untouched.
+      - name: Build package
+        run: uv build
+
+      # ── 3e. Attest build provenance ──────────────────────────────────────
+      # Generates a Sigstore-signed SLSA provenance attestation for the
+      # built artifacts. Attestations are stored in GitHub's attestation
+      # store and uploaded to PyPI alongside the package. Users can verify
+      # with: gh attestation verify <wheel> --repo Lucenor/mnesis
+      - name: Attest build provenance
+        uses: actions/attest-build-provenance@e8998f949152b193b063cb0ec769d69d929409be # v2
+        with:
+          subject-path: dist/*
+
+      # ── 3f. Generate and attest SBOM ─────────────────────────────────────
+      # Generates an SPDX SBOM listing every dependency in the release
+      # artifacts, then attests it with Sigstore. Complements provenance
+      # ("who built it") with a full dependency inventory ("what's in it").
+      - name: Generate SBOM
+        uses: anchore/sbom-action@28d71544de8eaf1b958d335707167c5f783590ad # v0.17.0
+        with:
+          path: dist/
+          format: spdx-json
+          output-file: sbom.spdx.json
+          upload-artifact: false
+
+      - name: Attest SBOM
+        uses: actions/attest-sbom@bd218ad0dbcb3e146bd073d1d9c6d78e08aa8a0b # v2.0.0
+        with:
+          subject-path: dist/*
+          sbom-path: sbom.spdx.json
+
+      # ── 3g. Commit, tag, push ────────────────────────────────────────────
+      - name: Commit and tag release
+        run: |
+          VERSION="${{ needs.validate.outputs.version }}"
+          TAG="${{ needs.validate.outputs.tag }}"
+
+          git add pyproject.toml docs/changelog.md
+          git commit -m "chore: release ${VERSION}"
+          git tag -a "$TAG" -m "Release ${VERSION}"
+          git push origin main
+          git push origin "$TAG"
+
+      # ── 3h. Create GitHub Release (draft) ───────────────────────────────
+      # Created as a draft so it is not subject to release immutability rules.
+      # Promoted to published only after PyPI succeeds.
+      - name: Create GitHub Release (draft)
+        env:
+          GH_TOKEN: ${{ steps.app-token.outputs.token }}
+        run: |
+          TAG="${{ needs.validate.outputs.tag }}"
+          gh release create "$TAG" dist/* \
+            --title "mnesis ${TAG}" \
+            --notes-file /tmp/release_notes.md \
+            --draft
+
+      # ── 3i. Publish to PyPI ──────────────────────────────────────────────
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@ed0c53931b1dc9bd32cbe73a98c7f6766f8a527e # release/v1
+        with:
+          packages-dir: dist/
+
+      # ── 3j. Publish GitHub Release ───────────────────────────────────────
+      - name: Publish GitHub Release
+        env:
+          GH_TOKEN: ${{ steps.app-token.outputs.token }}
+        run: |
+          TAG="${{ needs.validate.outputs.tag }}"
+          gh release edit "$TAG" --draft=false

mnesis-0.1.0/.github/workflows/scorecard.yml

@@ -0,0 +1,46 @@
+name: OpenSSF Scorecard
+
+on:
+  push:
+    branches: [main]
+  schedule:
+    # Weekly on Monday at 06:00 UTC
+    - cron: "0 6 * * 1"
+
+# Restrict default token to read-only; scorecard job elevates as needed.
+permissions: read-all
+
+jobs:
+  scorecard:
+    name: Scorecard analysis
+    runs-on: ubuntu-latest
+    permissions:
+      security-events: write  # upload SARIF to GitHub code scanning
+      id-token: write         # publish results to OpenSSF database
+      contents: read
+      actions: read
+
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+
+      - name: Run Scorecard analysis
+        uses: ossf/scorecard-action@4eaacf0543bb3f2c246792bd56e8cdeffafb205a # v2.4.3
+        with:
+          results_file: scorecard.sarif
+          results_format: sarif
+          # Publish results to OpenSSF database for the badge to work
+          publish_results: true
+
+      - name: Upload SARIF artifact
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.4.3
+        with:
+          name: scorecard-sarif
+          path: scorecard.sarif
+          retention-days: 5
+
+      - name: Upload SARIF to GitHub code scanning
+        uses: github/codeql-action/upload-sarif@f5c2471be782132e47a6e6f9c725e56730d6e9a3 # v3.25.10
+        with:
+          sarif_file: scorecard.sarif