halo-engine 0.1.1__tar.gz

halo_engine-0.1.1/.githooks/pre-commit

@@ -0,0 +1,11 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+REPO_ROOT="$(git rev-parse --show-toplevel)"
+export GIT_WORK_TREE="$REPO_ROOT"
+
+HOOK="$REPO_ROOT/scripts/git-hooks/pre-commit"
+
+if [[ -x "$HOOK" ]]; then
+  "$HOOK"
+fi

halo_engine-0.1.1/.githooks/pre-push

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+REPO_ROOT="$(git rev-parse --show-toplevel)"
+export GIT_WORK_TREE="$REPO_ROOT"
+
+REFS_FILE="$(mktemp)"
+
+cleanup() {
+  rm -f "$REFS_FILE"
+}
+
+trap cleanup EXIT
+cat > "$REFS_FILE"
+
+REMOTE="${1:-}"
+URL="${2:-}"
+HOOK="$REPO_ROOT/scripts/git-hooks/pre-push"
+
+if [[ -x "$HOOK" ]]; then
+  "$HOOK" "$REMOTE" "$URL" < "$REFS_FILE"
+fi

halo_engine-0.1.1/.github/workflows/engine--e2e-tests.yml

@@ -0,0 +1,88 @@
+name: "[Engine] E2E Tests"
+
+on:
+  workflow_dispatch:
+  workflow_call:
+    secrets:
+      INFISICAL_CLIENT_ID:
+        required: true
+      INFISICAL_CLIENT_SECRET:
+        required: true
+
+env:
+  PYTHON_VERSION: "3.12"
+  INFISICAL_CLI_VERSION: "0.41.2"
+  INFISICAL_PROJECT_ID: "822ab0ec-ad72-4b7d-9f49-93b43be4eda0"
+
+permissions:
+  checks: write
+  contents: read
+
+jobs:
+  e2e-tests:
+    name: E2E Tests
+    runs-on: depot-ubuntu-latest
+    timeout-minutes: 45
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+
+      - name: Install go-task
+        uses: arduino/setup-task@v2
+        with:
+          version: 3.x
+
+      - name: Install Infisical CLI
+        run: |
+          curl -fsSL "https://github.com/Infisical/infisical/releases/download/infisical-cli%2Fv${INFISICAL_CLI_VERSION}/infisical_${INFISICAL_CLI_VERSION}_linux_amd64.deb" -o /tmp/infisical.deb
+          sudo dpkg -i /tmp/infisical.deb
+          rm /tmp/infisical.deb
+
+      - name: Install engine dependencies
+        run: task ci:setup
+
+      - name: Authenticate Infisical
+        env:
+          INFISICAL_CLIENT_ID: ${{ secrets.INFISICAL_CLIENT_ID }}
+          INFISICAL_CLIENT_SECRET: ${{ secrets.INFISICAL_CLIENT_SECRET }}
+        run: |
+          TOKEN=$(infisical login --method=universal-auth \
+            --client-id="$INFISICAL_CLIENT_ID" \
+            --client-secret="$INFISICAL_CLIENT_SECRET" \
+            --silent --plain)
+          echo "::add-mask::$TOKEN"
+          echo "INFISICAL_TOKEN=$TOKEN" >> "$GITHUB_ENV"
+
+      - name: Run E2E tests
+        run: task test:e2e
+
+      - name: Publish Test Report
+        uses: mikepenz/action-junit-report@v5
+        if: always()
+        with:
+          report_paths: "test-results/e2e/junit.xml"
+          update_check: true
+          detailed_summary: true
+          include_passed: true
+          include_time_in_summary: true
+          fail_on_failure: true
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: engine-e2e-test-results
+          path: test-results/e2e/
+          retention-days: 14

halo_engine-0.1.1/.github/workflows/engine--integration-tests-live.yml

@@ -0,0 +1,92 @@
+name: "[Engine] Integration Tests (Live)"
+
+# Live integration tests hit a real LLM provider, so this workflow is gated
+# behind Infisical credentials and never auto-triggers on PR or push. It runs
+# on demand via ``workflow_dispatch`` and is invoked from
+# ``engine--release.yml`` via ``workflow_call``.
+on:
+  workflow_dispatch:
+  workflow_call:
+    secrets:
+      INFISICAL_CLIENT_ID:
+        required: true
+      INFISICAL_CLIENT_SECRET:
+        required: true
+
+env:
+  PYTHON_VERSION: "3.12"
+  INFISICAL_CLI_VERSION: "0.41.2"
+  INFISICAL_PROJECT_ID: "822ab0ec-ad72-4b7d-9f49-93b43be4eda0"
+
+permissions:
+  checks: write
+  contents: read
+
+jobs:
+  live-integration-tests:
+    name: Live Integration Tests
+    runs-on: depot-ubuntu-latest
+    timeout-minutes: 30
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+
+      - name: Install go-task
+        uses: arduino/setup-task@v2
+        with:
+          version: 3.x
+
+      - name: Install Infisical CLI
+        run: |
+          curl -fsSL "https://github.com/Infisical/infisical/releases/download/infisical-cli%2Fv${INFISICAL_CLI_VERSION}/infisical_${INFISICAL_CLI_VERSION}_linux_amd64.deb" -o /tmp/infisical.deb
+          sudo dpkg -i /tmp/infisical.deb
+          rm /tmp/infisical.deb
+
+      - name: Install engine dependencies
+        run: task ci:setup
+
+      - name: Authenticate Infisical
+        env:
+          INFISICAL_CLIENT_ID: ${{ secrets.INFISICAL_CLIENT_ID }}
+          INFISICAL_CLIENT_SECRET: ${{ secrets.INFISICAL_CLIENT_SECRET }}
+        run: |
+          TOKEN=$(infisical login --method=universal-auth \
+            --client-id="$INFISICAL_CLIENT_ID" \
+            --client-secret="$INFISICAL_CLIENT_SECRET" \
+            --silent --plain)
+          echo "::add-mask::$TOKEN"
+          echo "INFISICAL_TOKEN=$TOKEN" >> "$GITHUB_ENV"
+
+      - name: Run live integration tests
+        run: task test:integration:live
+
+      - name: Publish Test Report
+        uses: mikepenz/action-junit-report@v5
+        if: always()
+        with:
+          report_paths: "test-results/integration-live.xml"
+          update_check: true
+          detailed_summary: true
+          include_passed: true
+          include_time_in_summary: true
+          fail_on_failure: true
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: engine-live-integration-test-results
+          path: test-results/
+          retention-days: 14

halo_engine-0.1.1/.github/workflows/engine--integration-tests.yml

@@ -0,0 +1,89 @@
+name: "[Engine] Integration Tests"
+
+on:
+  pull_request:
+    branches: [main]
+    paths:
+      - "engine/**"
+      - "tests/**"
+      - "scripts/**"
+      - "pyproject.toml"
+      - "uv.lock"
+      - "Taskfile.yml"
+      - "pyrightconfig.json"
+      - ".github/workflows/engine--integration-tests.yml"
+  push:
+    branches: [main]
+    paths:
+      - "engine/**"
+      - "tests/**"
+      - "scripts/**"
+      - "pyproject.toml"
+      - "uv.lock"
+      - "Taskfile.yml"
+      - "pyrightconfig.json"
+      - ".github/workflows/engine--integration-tests.yml"
+  workflow_dispatch:
+  workflow_call:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: false
+
+env:
+  PYTHON_VERSION: "3.12"
+
+permissions:
+  checks: write
+  contents: read
+
+jobs:
+  integration-tests:
+    name: Integration Tests
+    runs-on: depot-ubuntu-latest
+    timeout-minutes: 15
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+
+      - name: Install go-task
+        uses: arduino/setup-task@v2
+        with:
+          version: 3.x
+
+      - name: Install engine dependencies
+        run: task ci:setup
+
+      - name: Run integration tests (excludes ``-m live``)
+        run: task test:integration
+
+      - name: Publish Test Report
+        uses: mikepenz/action-junit-report@v5
+        if: always()
+        with:
+          report_paths: "test-results/integration.xml"
+          update_check: true
+          detailed_summary: true
+          include_passed: true
+          include_time_in_summary: true
+          fail_on_failure: true
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: engine-integration-test-results
+          path: test-results/
+          retention-days: 14

halo_engine-0.1.1/.github/workflows/engine--lint-format-typecheck.yml

@@ -0,0 +1,76 @@
+name: "[Engine] Lint, Format & Typecheck"
+
+on:
+  pull_request:
+    branches: [main]
+    paths:
+      - "engine/**"
+      - "tests/**"
+      - "scripts/**"
+      - "pyproject.toml"
+      - "uv.lock"
+      - "Taskfile.yml"
+      - "pyrightconfig.json"
+      - ".github/workflows/engine--lint-format-typecheck.yml"
+  push:
+    branches: [main]
+    paths:
+      - "engine/**"
+      - "tests/**"
+      - "scripts/**"
+      - "pyproject.toml"
+      - "uv.lock"
+      - "Taskfile.yml"
+      - "pyrightconfig.json"
+      - ".github/workflows/engine--lint-format-typecheck.yml"
+  workflow_call:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: false
+
+env:
+  PYTHON_VERSION: "3.12"
+
+permissions:
+  contents: read
+
+jobs:
+  lint-format-typecheck:
+    name: Lint, Format & Typecheck
+    runs-on: depot-ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+
+      - name: Install go-task
+        uses: arduino/setup-task@v2
+        with:
+          version: 3.x
+
+      - name: Install engine dependencies
+        run: task ci:setup
+
+      - name: Validate pinned versions
+        run: task pinned-versions
+
+      - name: Lint (ruff)
+        run: task lint
+
+      - name: Format check (ruff)
+        run: task format
+
+      - name: Type check (basedpyright)
+        run: task typecheck

halo_engine-0.1.1/.github/workflows/engine--release.yml

@@ -0,0 +1,269 @@
+name: "[Engine] Release"
+
+on:
+  workflow_dispatch:
+    inputs:
+      semver_action:
+        description: "Semantic version bump"
+        required: true
+        default: patch
+        type: choice
+        options:
+          - patch
+          - minor
+          - major
+      dry_run:
+        description: "Dry run (build only; skip commit, push, and PyPI publish)"
+        required: true
+        default: true
+        type: boolean
+
+concurrency:
+  group: engine-release-${{ github.ref_name }}
+  cancel-in-progress: false
+
+env:
+  PYTHON_VERSION: "3.12"
+  CI_BOT_GITHUB_APP_ID: "1281730"
+
+  INFISICAL_IDENTITY_ID: "dc1d9282-7640-471d-bc3e-926297a5ef85" # halo-github-ci
+
+permissions:
+  contents: write # tag-and-push pushes the version commit + tag
+  checks: write # called workflows publish JUnit reports via checks API
+  id-token: write # Required for OIDC-based Infisical auth and PyPI trusted publishing
+
+jobs:
+  lint-format-typecheck:
+    name: Lint, Format & Typecheck
+    uses: ./.github/workflows/engine--lint-format-typecheck.yml
+    secrets: inherit
+
+  unit-tests:
+    name: Unit Tests
+    uses: ./.github/workflows/engine--unit-tests.yml
+    secrets: inherit
+
+  integration-tests:
+    name: Integration Tests
+    needs: [lint-format-typecheck, unit-tests]
+    uses: ./.github/workflows/engine--integration-tests.yml
+    secrets: inherit
+
+  integration-tests-live:
+    name: Integration Tests (Live)
+    needs: [lint-format-typecheck, unit-tests]
+    uses: ./.github/workflows/engine--integration-tests-live.yml
+    secrets: inherit
+
+  e2e-tests:
+    name: E2E Tests
+    needs: [integration-tests, integration-tests-live]
+    uses: ./.github/workflows/engine--e2e-tests.yml
+    secrets: inherit
+
+  bump-version:
+    name: Bump Version
+    needs: [e2e-tests]
+    runs-on: depot-ubuntu-latest
+    outputs:
+      new_version: ${{ steps.bump.outputs.new_version }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+
+      - name: Bump engine version
+        id: bump
+        run: |
+          NEW_VERSION=$(uv version --bump "${{ inputs.semver_action }}" --short --no-sync)
+          echo "Bumped engine version to ${NEW_VERSION}"
+          echo "new_version=${NEW_VERSION}" >> "$GITHUB_OUTPUT"
+          # Refresh uv.lock so the version inside it matches the bumped
+          # pyproject.toml. ``--no-sync`` above skips reinstall but also
+          # skips the lock refresh — without this, the release commit
+          # would push a uv.lock that lags pyproject.toml.
+          uv lock
+
+      - name: Upload bumped manifests
+        uses: actions/upload-artifact@v4
+        with:
+          name: engine-release-manifests
+          path: |
+            pyproject.toml
+            uv.lock
+          retention-days: 1
+
+  build:
+    name: Build
+    needs: [bump-version]
+    runs-on: depot-ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Download bumped manifests
+        uses: actions/download-artifact@v4
+        with:
+          name: engine-release-manifests
+          path: .
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+
+      - name: Build distributions
+        run: uv build
+
+      - name: Upload distribution artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: halo-engine-dist
+          path: dist/*
+          retention-days: 14
+
+  publish:
+    name: Publish to PyPI
+    needs: [bump-version, build]
+    if: ${{ inputs.dry_run == false }}
+    runs-on: depot-ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    environment:
+      name: pypi
+      url: https://pypi.org/project/halo-engine/${{ needs.bump-version.outputs.new_version }}/
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+
+      - name: Download distribution artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: halo-engine-dist
+          path: dist
+
+      - name: Publish to PyPI
+        run: uv publish --trusted-publishing always
+
+  tag-and-push:
+    name: Tag & Push Version Bump
+    needs: [bump-version, publish]
+    if: ${{ inputs.dry_run == false }}
+    runs-on: depot-ubuntu-latest
+    permissions:
+      contents: write
+      id-token: write # Required for OIDC-based Infisical auth
+    steps:
+      - name: Load Infisical secrets
+        uses: Infisical/secrets-action@v1.0.15
+        with:
+          method: "oidc"
+          identity-id: ${{ env.INFISICAL_IDENTITY_ID }}
+          project-slug: "halo-0ys-z"
+          env-slug: "dev"
+          secret-path: "/ci"
+          include-imports: true
+
+      - name: Mint CI Bot token
+        uses: actions/create-github-app-token@v1
+        id: app-token
+        with:
+          app-id: ${{ env.CI_BOT_GITHUB_APP_ID }}
+          private-key: ${{ env.CI_BOT_GITHUB_APP_PRIVATE_KEY }}
+
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          token: ${{ steps.app-token.outputs.token }}
+
+      - name: Download bumped manifests
+        uses: actions/download-artifact@v4
+        with:
+          name: engine-release-manifests
+          path: .
+
+      - name: Commit, tag, and push version bump
+        env:
+          NEW_VERSION: ${{ needs.bump-version.outputs.new_version }}
+        run: |
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git config user.name "github-actions[bot]"
+          git add pyproject.toml uv.lock
+          git commit -m "Release engine v${NEW_VERSION}"
+          git tag "engine-v${NEW_VERSION}"
+          git push origin "HEAD:${GITHUB_REF_NAME}"
+          git push origin "engine-v${NEW_VERSION}"
+
+  summary:
+    name: Release Summary
+    needs:
+      - lint-format-typecheck
+      - unit-tests
+      - integration-tests
+      - integration-tests-live
+      - e2e-tests
+      - bump-version
+      - build
+      - publish
+      - tag-and-push
+    if: always()
+    runs-on: depot-ubuntu-latest
+    steps:
+      - name: Generate summary
+        env:
+          DRY_RUN: ${{ inputs.dry_run }}
+          SEMVER_ACTION: ${{ inputs.semver_action }}
+          NEW_VERSION: ${{ needs.bump-version.outputs.new_version }}
+          LINT_RESULT: ${{ needs.lint-format-typecheck.result }}
+          UNIT_RESULT: ${{ needs.unit-tests.result }}
+          INTEGRATION_RESULT: ${{ needs.integration-tests.result }}
+          INTEGRATION_LIVE_RESULT: ${{ needs.integration-tests-live.result }}
+          E2E_RESULT: ${{ needs.e2e-tests.result }}
+          BUMP_RESULT: ${{ needs.bump-version.result }}
+          BUILD_RESULT: ${{ needs.build.result }}
+          PUBLISH_RESULT: ${{ needs.publish.result }}
+          TAG_PUSH_RESULT: ${{ needs.tag-and-push.result }}
+        run: |
+          {
+            echo "## Engine Release Summary"
+            echo ""
+            echo "**Semver action:** ${SEMVER_ACTION}"
+            echo "**New version:** ${NEW_VERSION:-unknown}"
+            echo "**Dry run:** ${DRY_RUN}"
+            echo ""
+            echo "**Lint/Format/Typecheck:**  ${LINT_RESULT}"
+            echo "**Unit Tests:**             ${UNIT_RESULT}"
+            echo "**Integration:**            ${INTEGRATION_RESULT}"
+            echo "**Integration (Live):**     ${INTEGRATION_LIVE_RESULT}"
+            echo "**E2E:**                    ${E2E_RESULT}"
+            echo "**Version Bump:**           ${BUMP_RESULT}"
+            echo "**Build:**                  ${BUILD_RESULT}"
+            echo "**Publish:**                ${PUBLISH_RESULT}"
+            echo "**Tag & Push:**             ${TAG_PUSH_RESULT}"
+          } >> "$GITHUB_STEP_SUMMARY"