flowapy 0.1.0__tar.gz

flowapy-0.1.0/.env.example

@@ -0,0 +1,8 @@
+# Local setup example
+OPENAI_API_KEY=dummy
+OPENAI_BASE_URL=http://localhost:61234/v1
+OPENAI_MODEL=gpt-oss-120b
+TIMEZONE=Australia/Sydney
+
+# Optional: Only required if using Mastermind as literature source
+# MASTERMIND_API_TOKEN=your_token_here

flowapy-0.1.0/.github/dependabot.yml

@@ -0,0 +1,91 @@
+# Dependabot configuration for flowa.
+#
+# Strategy:
+# - Weekly version-update PRs per ecosystem, grouped so minor/patch bumps land
+#   in a single PR. Majors still get individual PRs so they can be reviewed in
+#   isolation.
+# - Security-update PRs (opened as soon as an advisory drops) use the same
+#   per-ecosystem groups; that switch is toggled separately at
+#   Settings -> Code security -> "Dependabot security updates" and is wired up
+#   alongside this file.
+# - 7-day cooldown matches the local supply-chain hygiene policy
+#   (`min-release-age=7d` in pnpm's global config, `exclude-newer = "7 days"`
+#   in each uv project). Without it Dependabot would happily open PRs that CI
+#   then rejects because the new version is too fresh.
+# - The reviewer assignment notifies @lgruen-vcgs on each PR; the weekly
+#   cadence keeps the inbox manageable.
+
+version: 2
+
+updates:
+  # npm / pnpm — covers the root pnpm-lock.yaml and every workspace package
+  # (packages/*, examples/*). Dependabot follows the workspace graph
+  # automatically; one entry here is enough.
+  - package-ecosystem: "npm"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 10
+    reviewers:
+      - "lgruen-vcgs"
+    labels:
+      - "dependencies"
+      - "npm"
+    commit-message:
+      prefix: "deps"
+    cooldown:
+      default-days: 7
+    groups:
+      npm-non-major:
+        patterns:
+          - "*"
+        update-types:
+          - "minor"
+          - "patch"
+
+  # uv / Python — the flowa library project at the repo root.
+  - package-ecosystem: "uv"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 10
+    reviewers:
+      - "lgruen-vcgs"
+    labels:
+      - "dependencies"
+      - "python"
+    commit-message:
+      prefix: "deps"
+    cooldown:
+      default-days: 7
+    groups:
+      python-non-major:
+        patterns:
+          - "*"
+        update-types:
+          - "minor"
+          - "patch"
+
+  # uv / Python — examples/demo-gateway is its own uv project with its own
+  # uv.lock, so it needs its own entry.
+  - package-ecosystem: "uv"
+    directory: "/examples/demo-gateway"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 10
+    reviewers:
+      - "lgruen-vcgs"
+    labels:
+      - "dependencies"
+      - "python"
+    commit-message:
+      prefix: "deps"
+    cooldown:
+      default-days: 7
+    groups:
+      python-non-major:
+        patterns:
+          - "*"
+        update-types:
+          - "minor"
+          - "patch"

flowapy-0.1.0/.github/workflows/dependabot-auto-merge.yml

@@ -0,0 +1,39 @@
+# Auto-merge non-major Dependabot PRs.
+#
+# Branch protection on `main` requires the `lint` + `test` checks from
+# lint.yaml to pass; this workflow just flips the auto-merge switch on
+# qualifying PRs so GitHub merges them once those checks go green.
+#
+# Major version bumps are skipped — they land as regular PRs and need a
+# human to review the changelog before merging.
+#
+# Uses `pull_request_target` so the workflow runs in the base repo's
+# context and can use the GITHUB_TOKEN (Dependabot PRs run with a
+# read-only token by default). The `github.actor == 'dependabot[bot]'`
+# guard is what keeps random forks from triggering this with elevated
+# permissions.
+
+name: Dependabot auto-merge
+
+on:
+  pull_request_target:
+    branches: [main]
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  auto-merge:
+    runs-on: ubuntu-latest
+    if: github.actor == 'dependabot[bot]'
+    steps:
+      - name: Fetch Dependabot metadata
+        id: meta
+        uses: dependabot/fetch-metadata@v2
+
+      - name: Enable auto-merge for non-major updates
+        if: steps.meta.outputs.update-type != 'version-update:semver-major'
+        run: gh pr merge --auto --squash "${{ github.event.pull_request.html_url }}"
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

flowapy-0.1.0/.github/workflows/lint.yaml

@@ -0,0 +1,49 @@
+name: Lint
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: astral-sh/setup-uv@v7
+        with:
+          python-version: "3.13"
+
+      - uses: pnpm/action-setup@v4
+
+      - uses: actions/setup-node@v5
+        with:
+          node-version-file: .nvmrc
+          cache: "pnpm"
+
+      - run: uv sync --all-extras --group dev --frozen
+
+      - run: pnpm install --frozen-lockfile
+
+      # All lint checks (ruff, mypy, prettier, …) live in
+      # .pre-commit-config.yaml so local pre-commit and CI stay in lockstep.
+      - uses: actions/cache@v5
+        with:
+          path: ~/.cache/pre-commit
+          key: pre-commit-${{ hashFiles('.pre-commit-config.yaml') }}
+
+      - run: uv run pre-commit run --all-files --show-diff-on-failure
+
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: astral-sh/setup-uv@v7
+        with:
+          python-version: "3.13"
+
+      - run: uv sync --all-extras --group dev --frozen
+
+      - run: uv run pytest tests/

flowapy-0.1.0/.github/workflows/release-chat-service.yaml

@@ -0,0 +1,81 @@
+# Tag-driven release of @flowajs/chat-service to npm via OIDC trusted publishing.
+#
+# Trigger: `git tag chat-service-v$VERSION && git push origin chat-service-v$VERSION`.
+# Gating: the `npm-publish` GitHub environment requires manual approval before
+# the publish step runs.
+#
+# Setup mirrors @flowajs/react-viewer's release workflow — same `npm-publish`
+# environment, same approver list, same tag-protection ruleset (extended with
+# `chat-service-v*`). Per-package work needed before the first OIDC publish:
+# bootstrap publish 0.0.1 with a granular token, deprecate it, configure the
+# trusted publisher on npmjs.com (workflow filename: release-chat-service.yaml,
+# environment: npm-publish), then enable "Require 2FA and disallow tokens".
+#
+# Action versions are pinned to major-version tags here, matching lint.yaml /
+# release-react-viewer.yaml. Switch to SHA pins via Dependabot before going
+# to production.
+
+name: Release @flowajs/chat-service
+
+on:
+  push:
+    tags:
+      - "chat-service-v*"
+
+permissions:
+  contents: read
+  id-token: write # Required for OIDC trusted publishing.
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: npm-publish # Must match the trusted-publisher config on npmjs.com.
+    timeout-minutes: 15
+
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - uses: pnpm/action-setup@v4
+
+      - uses: actions/setup-node@v5
+        with:
+          node-version: "22"
+          registry-url: "https://registry.npmjs.org"
+          cache: "pnpm"
+
+      # Trusted publishing requires npm >= 11.5.1; Node 22.x ships npm 10.9.x.
+      # Install to a fresh prefix to sidestep `npm install -g npm@X` clobbering
+      # its own node_modules mid-upgrade.
+      - name: Pin npm
+        run: |
+          mkdir -p "$RUNNER_TEMP/npm-pin"
+          npm install -g --prefix="$RUNNER_TEMP/npm-pin" npm@11.13.0
+          echo "$RUNNER_TEMP/npm-pin/bin" >> "$GITHUB_PATH"
+
+      - name: Verify npm version
+        run: npm --version
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile --ignore-scripts
+
+      - name: Build
+        run: pnpm --filter @flowajs/chat-service build
+
+      - name: Test
+        run: pnpm --filter @flowajs/chat-service test
+
+      - name: Typecheck
+        run: pnpm --filter @flowajs/chat-service typecheck
+
+      - name: Verify tarball contents
+        working-directory: packages/chat-service
+        run: pnpm pack --dry-run
+
+      - name: Publish
+        working-directory: packages/chat-service
+        run: npm publish --provenance --access=public
+        env:
+          NPM_CONFIG_PROVENANCE: true

flowapy-0.1.0/.github/workflows/release-flowapy.yaml

@@ -0,0 +1,94 @@
+# Tag-driven release of flowapy to PyPI via OIDC trusted publishing.
+#
+# Trigger: `git tag flowapy-v$VERSION && git push origin flowapy-v$VERSION`.
+# Gating: the `pypi` GitHub environment requires manual approval before the
+# publish step runs.
+#
+# The PyPI distribution is named `flowapy` (the `flowa` name was already
+# taken on PyPI by an unrelated owner). Import name and CLI command stay
+# `flowa`; only the install line and the URL below carry the distinct
+# distribution name.
+#
+# Per-package setup needed once before the first OIDC publish:
+#   1. Configure a pending publisher on pypi.org under your account
+#      (https://pypi.org/manage/account/publishing/) — PyPI Project Name:
+#      flowapy, Owner: populationgenomics, Repository: flowa, Workflow:
+#      release-flowapy.yaml, Environment: pypi. Pending publishers reserve
+#      the name and let the first OIDC publish create the project; no
+#      bootstrap API token is needed.
+#   2. Create the `pypi` GitHub environment with required reviewers + a
+#      deployment-branch-policy that matches `flowapy-v*` tags.
+#   3. Extend the `release-tag protection` ruleset to also match `flowapy-v*`,
+#      mirroring the `react-viewer-v*` / `chat-service-v*` patterns.
+#   4. Toggle PyPI's project setting to disallow API tokens once the first
+#      OIDC publish has been verified end-to-end.
+#
+# Setup is documented in specs/flowa_demo.md and the publishing guide it
+# references.
+#
+# Action versions are pinned to major-version tags here, matching lint.yaml
+# and the npm release workflows. Switch to SHA pins via Dependabot before
+# going to production.
+
+name: Release flowapy
+
+on:
+  push:
+    tags:
+      - "flowapy-v*"
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/flowapy
+    permissions:
+      id-token: write # Required for PyPI OIDC trusted publishing.
+    timeout-minutes: 15
+
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - uses: astral-sh/setup-uv@v7
+        with:
+          python-version: "3.13"
+
+      - name: Verify tag matches pyproject version
+        run: |
+          tag="${GITHUB_REF_NAME#flowapy-v}"
+          ver="$(python -c 'import tomllib; print(tomllib.load(open("pyproject.toml","rb"))["project"]["version"])')"
+          if [ "$tag" != "$ver" ]; then
+            echo "::error::Tag flowapy-v${tag} does not match pyproject.toml version ${ver}"
+            exit 1
+          fi
+
+      - name: Install dependencies
+        run: uv sync --all-extras --group dev --frozen
+
+      - name: Lint
+        run: uv run ruff check src/
+
+      - name: Format check
+        run: uv run ruff format --check src/
+
+      - name: Typecheck
+        run: uv run mypy src/
+
+      - name: Test
+        run: uv run pytest tests/
+
+      - name: Build distribution
+        run: uv build
+
+      - name: List built artifacts
+        run: ls -l dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

flowapy-0.1.0/.github/workflows/release-react-viewer.yaml

@@ -0,0 +1,78 @@
+# Tag-driven release of @flowajs/react-viewer to npm via OIDC trusted publishing.
+#
+# Trigger: `git tag react-viewer-v$VERSION && git push origin react-viewer-v$VERSION`.
+# Gating: the `npm-publish` GitHub environment requires manual approval before
+# the publish step runs.
+#
+# Setup is documented in specs/flowa_demo.md (§6.1, §16.3) and the publishing
+# guide it references — scope reservation, trusted-publisher binding, branch
+# and tag protection, environment reviewers all need to be configured on
+# npmjs.com / GitHub before this workflow can publish successfully.
+#
+# Action versions are pinned to major-version tags here, matching lint.yaml.
+# Switch to SHA pins via Dependabot before going to production.
+
+name: Release @flowajs/react-viewer
+
+on:
+  push:
+    tags:
+      - "react-viewer-v*"
+
+permissions:
+  contents: read
+  id-token: write # Required for OIDC trusted publishing.
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: npm-publish # Must match the trusted-publisher config on npmjs.com.
+    timeout-minutes: 15
+
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - uses: pnpm/action-setup@v4
+
+      - uses: actions/setup-node@v5
+        with:
+          node-version: "22"
+          registry-url: "https://registry.npmjs.org"
+          cache: "pnpm"
+
+      # Trusted publishing requires npm >= 11.5.1; Node 22.x ships npm 10.9.x.
+      # Install to a fresh prefix to sidestep `npm install -g npm@X` clobbering
+      # its own node_modules mid-upgrade.
+      - name: Pin npm
+        run: |
+          mkdir -p "$RUNNER_TEMP/npm-pin"
+          npm install -g --prefix="$RUNNER_TEMP/npm-pin" npm@11.13.0
+          echo "$RUNNER_TEMP/npm-pin/bin" >> "$GITHUB_PATH"
+
+      - name: Verify npm version
+        run: npm --version
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile --ignore-scripts
+
+      - name: Build
+        run: pnpm --filter @flowajs/react-viewer build
+
+      - name: Test
+        run: pnpm --filter @flowajs/react-viewer test
+
+      - name: Typecheck
+        run: pnpm --filter @flowajs/react-viewer typecheck
+
+      - name: Verify tarball contents
+        working-directory: packages/react-viewer
+        run: pnpm pack --dry-run
+
+      - name: Publish
+        working-directory: packages/react-viewer
+        run: npm publish --provenance --access=public
+        env:
+          NPM_CONFIG_PROVENANCE: true

flowapy-0.1.0/.gitignore

@@ -0,0 +1,161 @@
+# Python codebase default gitignore (github template)
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# local irrelevant files
+.idea
+.DS_Store
+CLAUDE.md
+specs/
+
+# Only the public generic prompt set is tracked.
+prompts/*/
+!prompts/generic/
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+build.d/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+# /lib/ and /lib64/ are anchored to the repo root so they don't shadow
+# unrelated `lib/` directories nested under packages or examples.
+/lib/
+/lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+data/
+reports/
+
+# Docker
+docker/.env
+docker/config/
+docker/plugins/
+docker/logs/
+
+# Node / TypeScript workspace
+node_modules/
+.next/
+.turbo/
+demo-data/
+*.tsbuildinfo
+pnpm-debug.log*

flowapy-0.1.0/.markdownlint.json

@@ -0,0 +1,14 @@
+// https://github.com/DavidAnson/markdownlint#optionsconfig
+// Disabling some rules here as we find them too restrictive.
+{
+  "default": true, // Include all rules by defauls
+  "line-length": false, // To allow working with soft wraps in editors
+  "no-inline-html": {
+    // Sometimes we need to use <img> html tags in GitHub markdown,
+    // as it doesn't allow setting the image size with markdown tags
+    "allowed_elements": ["details", "img"]
+  },
+  "ul-indent": false, // To allow indenting the whole list to distinguish it visually
+  "no-multiple-blanks": false // To allow multiple blank lines between a header and
+  // the previous paragraph
+}

flowapy-0.1.0/.nvmrc

@@ -0,0 +1 @@
+24

flowapy-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,64 @@
+# Single source of truth for pre-commit + CI lint. .github/workflows/lint.yaml
+# invokes `uv run pre-commit run --all-files`, so adding a check here
+# automatically runs it locally and in CI.
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.5.0
+    hooks:
+      - id: check-yaml
+        exclude: '\.*conda/.*'
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+        exclude: '\.txt$|\.tsv$'
+      - id: check-case-conflict
+      - id: check-merge-conflict
+      - id: detect-private-key
+      - id: debug-statements
+      - id: check-added-large-files
+        # Demo fixture PDFs (real published CC-BY papers) run up to ~5MB
+        # for figure-heavy articles (Sci Rep, Front Cardiovasc Med); set a
+        # 6MB ceiling that fits the current corpus with some headroom.
+        args: ["--maxkb=6144"]
+
+  - repo: https://github.com/igorshubovych/markdownlint-cli
+    rev: v0.38.0
+    hooks:
+      - id: markdownlint
+        # Demo fixture markdown is extracted by the pipeline from real PDFs;
+        # it isn't authored content the project owns the style of.
+        exclude: ^examples/demo/fixtures/
+
+  - repo: https://github.com/populationgenomics/pre-commits
+    rev: "v0.1.3"
+    hooks:
+      - id: cpg-id-checker
+
+  # Use the project's pinned tools via uv / pnpm so pre-commit and CI checks
+  # match what runs locally — no separate version pinning here.
+  - repo: local
+    hooks:
+      - id: ruff-format
+        name: ruff format
+        entry: uv run --no-sync ruff format --check src/
+        language: system
+        pass_filenames: false
+        always_run: true
+      - id: ruff-check
+        name: ruff check
+        entry: uv run --no-sync ruff check src/
+        language: system
+        pass_filenames: false
+        always_run: true
+      - id: mypy
+        name: mypy
+        entry: uv run --no-sync mypy src/
+        language: system
+        pass_filenames: false
+        always_run: true
+      # markdownlint owns markdown above, so prettier stays out of .md.
+      - id: prettier
+        name: prettier --check
+        entry: pnpm exec prettier --check
+        language: system
+        files: \.(ts|tsx|js|jsx|mjs|cjs|json|yaml|yml)$
+        exclude: ^pnpm-lock\.yaml$