textflowkit 0.1.4__tar.gz → 0.1.6__tar.gz

textflowkit-0.1.6/.dockerignore

@@ -0,0 +1,54 @@
+# What the container image build must not receive.
+#
+# The image is built from this repository root, so anything not named here lands
+# in the build context. Only local state and secrets are named: the licence, the
+# source, the docs, and the packaging metadata stay in, because the wheel build
+# reads them (`license-files` and `readme` in pyproject.toml) and because a
+# context that quietly dropped them would produce an image that builds but is not
+# this project.
+
+# Version control, environments, caches, build output.
+.git
+.venv
+venv
+__pycache__
+*.py[cod]
+*.egg-info
+.pytest_cache
+.ruff_cache
+.mypy_cache
+build
+dist
+
+# Local work products and media, as in .gitignore. The one exception below is
+# load-bearing: pyproject.toml's `artifacts` packs `src/textflowkit/assets/*.wav`
+# into the wheel, so a media filter without the negation would ship an image
+# whose asset directory is silently empty.
+work
+out
+outputs
+*.wav
+!src/textflowkit/assets/selftest-speech.wav
+*.mp3
+*.m4a
+*.mp4
+*.webm
+*.srt
+*.vtt
+
+# Secrets and local configuration. The production token comes from the operator's
+# environment at run time, never from the image.
+.env
+.env.*
+*.local.toml
+
+# Host-side media for the Compose example, if the operator placed it in-tree.
+# Anchored: only the repository-root `data/` the Compose file mounts, not any
+# fixture directory a package might legitimately ship.
+/data
+
+# OS and editor debris.
+.DS_Store
+Thumbs.db
+.vscode
+.idea

textflowkit-0.1.6/.env.example

@@ -0,0 +1,20 @@
+# Template for the Compose example. Copy it to `.env`, which is git-ignored:
+#
+#   cp .env.example .env
+#
+# There is no default token, and Compose will not start without one. Generate a
+# value and paste it in:
+#
+#   openssl rand -hex 32
+#
+# An environment variable keeps the token out of the command line, so it does not
+# appear in `ps`. That is all it buys. Docker records the value in the container's
+# configuration, where `docker inspect` and `docker compose config` render it for
+# anyone who can reach the daemon; inside the container it is readable through
+# `/proc/<pid>/environ`; and here it sits in plain text in `.env`, which git
+# ignores but does not encrypt. Restrict access to the daemon, this Compose file,
+# and this env file, and do not mistake one shared token for secret-store
+# isolation - a real secret store is a separate decision this example does not
+# make for you. Keep the value out of the repository and out of any image layer.
+
+TEXTFLOWKIT_API_TOKEN=

{textflowkit-0.1.4 → textflowkit-0.1.6}/.gitattributes

@@ -1,22 +1,22 @@
-# Normalise line endings so a build is the same on every platform.
-#
-# Without this, core.autocrlf rewrites text files on Windows checkout, so a
-# wheel built from a Windows clone differs byte-for-byte from one built on
-# Linux - same code, different bytes - and a published hash cannot be
-# reproduced. Text is stored as LF in the repository and in every build.
-* text=auto eol=lf
-
-# Binary assets must never be rewritten.
-*.png binary
-*.jpg binary
-*.jpeg binary
-*.gif binary
-*.ico binary
-*.pdf binary
-*.docx binary
-*.whl binary
-*.gz binary
-
-# Windows-only scripts keep CRLF.
-*.bat text eol=crlf
-*.cmd text eol=crlf
+# Normalise line endings so a build is the same on every platform.
+#
+# Without this, core.autocrlf rewrites text files on Windows checkout, so a
+# wheel built from a Windows clone differs byte-for-byte from one built on
+# Linux - same code, different bytes - and a published hash cannot be
+# reproduced. Text is stored as LF in the repository and in every build.
+* text=auto eol=lf
+
+# Binary assets must never be rewritten.
+*.png binary
+*.jpg binary
+*.jpeg binary
+*.gif binary
+*.ico binary
+*.pdf binary
+*.docx binary
+*.whl binary
+*.gz binary
+
+# Windows-only scripts keep CRLF.
+*.bat text eol=crlf
+*.cmd text eol=crlf

{textflowkit-0.1.4 → textflowkit-0.1.6}/.github/workflows/ci.yml

@@ -57,7 +57,8 @@ jobs:
         shell: bash
         run: |
           python -m pip install --upgrade pip
-          python -m pip install -e ".[dev,mcp,http]"
+          python -m pip install ./packages/textflowkit-fonts
+          python -m pip install -e ".[dev,mcp,http,export]"
 
       - name: Show ffmpeg version
         shell: bash
@@ -84,6 +85,7 @@ jobs:
         run: |
           python -m pip install "setuptools>=83" "build>=1.2"
           python -m build --wheel
+          python -m build --wheel --outdir dist packages/textflowkit-fonts
       - name: Smoke all three installed entry points
         shell: bash
-        run: python scripts/smoke_installed_wheel.py dist/*.whl
+        run: python scripts/smoke_installed_wheel.py dist/textflowkit-*.whl dist/textflowkit_fonts-*.whl

textflowkit-0.1.6/.github/workflows/publish-pypi.yml

@@ -0,0 +1,211 @@
+name: Publish PyPI
+
+on:
+  push:
+    tags: ['v*']
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    if: github.repository == 'scottconverse/textflowkit'
+    runs-on: ubuntu-latest
+    # Actions read is needed to verify that this exact commit passed main CI.
+    # It is granted to this job only: no upload job can read run results.
+    permissions:
+      contents: read
+      actions: read
+    outputs:
+      # The upload jobs act on this: only a new fonts version may be uploaded.
+      fonts_mode: ${{ steps.fonts_release.outputs.fonts_mode }}
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+          fetch-depth: 0
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: '3.12'
+      - run: python -m pip install packaging
+      - name: Verify release tag and package versions
+        env:
+          RELEASE_TAG: ${{ github.ref_name }}
+        run: |
+          python scripts/verify_release_versions.py
+          git merge-base --is-ancestor "$GITHUB_SHA" origin/main || {
+            echo 'Release tag is not merged into main' >&2
+            exit 1
+          }
+      # A distribution's long description is built from the README at this commit
+      # and frozen on upload, so a README that still names an older tag publishes
+      # a permanently wrong version claim - the v0.1.5 mistake. This runs before
+      # anything is built or uploaded.
+      - name: Require the README to name the release being published
+        env:
+          RELEASE_TAG: ${{ github.ref_name }}
+        run: python scripts/verify_readme_release.py
+      - name: Require successful CI for this exact commit
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+        run: python scripts/verify_release_ci.py
+      # The fonts package is versioned on its own contract: when the version this
+      # commit declares is already on PyPI, the release reuses those published
+      # files instead of rebuilding them, and the fonts upload job is skipped.
+      # The script decides, downloads and verifies, and stops the release on
+      # anything it cannot verify. It runs before the build so a reuse can never
+      # be overwritten by a local build, and before any upload.
+      - name: Resolve the fonts release
+        id: fonts_release
+        run: |
+          python scripts/fetch_published_fonts.py \
+            --package-dir packages/textflowkit-fonts \
+            --out-dir dist/fonts \
+            --github-output "$GITHUB_OUTPUT"
+      - name: Build distributions
+        env:
+          FONTS_MODE: ${{ steps.fonts_release.outputs.fonts_mode }}
+        run: |
+          python -m pip install --upgrade build packaging
+          python -m build --sdist --wheel --outdir dist/main .
+          case "$FONTS_MODE" in
+            new)
+              # The declared fonts version is not on PyPI, so this release
+              # publishes it.
+              python -m build --sdist --wheel --outdir dist/fonts packages/textflowkit-fonts
+              ;;
+            reuse)
+              # dist/fonts holds the published files, fetched and verified
+              # against PyPI above. Rebuilding here would replace them with
+              # different bytes and break the hashes the manifest publishes.
+              echo "reusing the textflowkit-fonts files fetched from PyPI"
+              ;;
+            *)
+              echo "no fonts mode was resolved; refusing to build" >&2
+              exit 1
+              ;;
+          esac
+          python -m pip install twine
+          python -m twine check dist/main/* dist/fonts/*
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: distributions
+          path: dist/
+          if-no-files-found: error
+
+  publish-fonts:
+    needs: build
+    # Only a new fonts version is uploaded. A reused one is already on PyPI, and
+    # PyPI rejects a duplicate filename; this workflow deliberately does not
+    # skip such an upload, so the job must not run at all.
+    if: needs.build.outputs.fonts_mode == 'new'
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: distributions
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
+        with:
+          packages-dir: dist/fonts/
+
+  publish-main:
+    # The core upload needs the build as well as the fonts job. On a reuse the
+    # fonts job is *skipped*, and GitHub skips a job whose `needs:` job was
+    # skipped unless the job's `if` uses a status check function - `cancelled()`
+    # below. That is why the condition is written out instead of left implicit:
+    # an implicit `success()` would lose to the skip propagation and the reuse
+    # path would upload nothing and publish no release.
+    #
+    # `always()` would also defeat the skip propagation, but it runs the job in
+    # a cancelled run too, so it is not used.
+    #
+    # Core may continue past the fonts job only when that job uploaded a new
+    # fonts version or was skipped because the release reuses published files. A
+    # failed or cancelled fonts upload, a failed build, a cancelled run, and a
+    # skipped fonts job that was not a reuse all leave core unpublished, so a
+    # core release cannot advertise a fonts version that is not on PyPI.
+    needs: [build, publish-fonts]
+    if: >-
+      ${{ !cancelled()
+          && needs.build.result == 'success'
+          && (needs.publish-fonts.result == 'success'
+              || (needs.publish-fonts.result == 'skipped'
+                  && needs.build.outputs.fonts_mode == 'reuse')) }}
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: distributions
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
+        with:
+          packages-dir: dist/main/
+
+  publish-github-release:
+    # Deliberately no `if:` here. The implicit `success()` plus the default skip
+    # propagation is the gate that matters: a core upload that failed or was
+    # skipped for any reason skips this job too, so a failed release cannot end
+    # in a public GitHub release. Adding a status check function here would
+    # weaken that, not strengthen it.
+    needs: publish-main
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      # The manifest step runs this repository's own script, so the tagged
+      # commit must be present. Its bytes are the ones already required to have
+      # passed CI on main, and `gh` takes the token from the environment, not
+      # from git credentials.
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: distributions
+          path: dist/
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: '3.12'
+      # The manifest pins each project's own version. Core is the tag; fonts is
+      # the version the tagged commit declares, which is the version of the
+      # files in dist/fonts whether they were built or fetched.
+      - name: Read the declared fonts version
+        id: fonts_version
+        run: |
+          python - <<'PY' >> "$GITHUB_OUTPUT"
+          import tomllib
+          from pathlib import Path
+
+          project = tomllib.loads(
+              Path('packages/textflowkit-fonts/pyproject.toml').read_text(encoding='utf-8')
+          )['project']
+          print(f"version={project['version']}")
+          PY
+      - name: Hash the downloaded distributions
+        env:
+          RELEASE_TAG: ${{ github.ref_name }}
+          FONTS_VERSION: ${{ steps.fonts_version.outputs.version }}
+        run: |
+          python scripts/write_release_manifest.py \
+            --output SHA256SUMS --version "$RELEASE_TAG" --fonts-version "$FONTS_VERSION" \
+            dist/main/* dist/fonts/*
+      - name: Create draft with the exact PyPI distributions
+        env:
+          GH_TOKEN: ${{ github.token }}
+          RELEASE_TAG: ${{ github.ref_name }}
+        run: |
+          gh release create "$RELEASE_TAG" dist/main/* dist/fonts/* SHA256SUMS \
+            --repo "$GITHUB_REPOSITORY" --verify-tag --draft \
+            --title "$RELEASE_TAG" --generate-notes
+      - name: Publish complete GitHub release
+        env:
+          GH_TOKEN: ${{ github.token }}
+          RELEASE_TAG: ${{ github.ref_name }}
+        run: gh release edit "$RELEASE_TAG" --repo "$GITHUB_REPOSITORY" --draft=false

{textflowkit-0.1.4 → textflowkit-0.1.6}/.gitignore

@@ -16,7 +16,10 @@ venv/
 work/
 out/
 outputs/
+# Host-side media for the Compose example (`compose.yaml` mounts ./data/input).
+data/
 *.wav
+!src/textflowkit/assets/selftest-speech.wav
 *.mp3
 *.m4a
 *.mp4
@@ -34,4 +37,3 @@ Thumbs.db
 .vscode/
 .idea/
 board/
-

{textflowkit-0.1.4 → textflowkit-0.1.6}/.pre-commit-config.yaml

@@ -15,4 +15,4 @@ repos:
       - id: check-yaml
       - id: check-toml
       - id: check-added-large-files
-        args: [--maxkb=1024]
+        args: [--maxkb=1024]

{textflowkit-0.1.4 → textflowkit-0.1.6}/CONTRIBUTING.md

@@ -13,7 +13,8 @@ cd textflowkit
 python -m venv .venv
 # Windows: .venv\Scripts\activate
 # POSIX:   source .venv/bin/activate
-pip install -e ".[dev,mcp,http]"
+pip install ./packages/textflowkit-fonts  # local optional PDF font companion
+pip install -e ".[dev,mcp,http,export]"
 ```
 
 ## Test and lint — the commands CI runs
@@ -60,6 +61,8 @@ mark it so it can be skipped in CI.
 - Add a test for a bug fix. If you cannot, say why in the PR description.
 - Run `ruff check .` and `python -m pytest` before opening the PR.
 - Do not commit media files, transcripts, or scratch output. `work/` is gitignored.
+  The bundled `src/textflowkit/assets/selftest-speech.wav` is an intentional,
+  small synthetic speech fixture; do not replace it with private recordings.
 
 ## Evidence language
 

textflowkit-0.1.6/Dockerfile

@@ -0,0 +1,115 @@
+# syntax=docker/dockerfile:1
+#
+# Optional Linux deployment surface for the JSON HTTP adapter. The product stays
+# native Windows; nothing here is needed for a local install, and the Compose
+# file beside this one is the supported way to run it.
+#
+# What this image does NOT provide, and cannot:
+#
+#   * A public service. `compose.yaml` publishes the host port to 127.0.0.1 only,
+#     so the container is reachable from its own host and nowhere else.
+#     Terminating TLS, authenticating callers beyond the Bearer token, and
+#     enforcing an independent rate and egress policy belong to a trusted gateway
+#     in front of it. The built-in limiter is per process, not a distributed
+#     quota.
+#   * A working URL-job path on its own. Production URL acquisition requires an
+#     SSRF-filtering TEXTFLOWKIT_EGRESS_PROXY and refuses to run without one, so
+#     URL jobs fail closed until an operator supplies a proxy that blocks
+#     private/loopback destinations and DNS rebinding. No proxy is bundled. Local
+#     files and /health need no egress.
+#   * More than one process. The durable SQLite store has one owning process; a
+#     second one sharing TEXTFLOWKIT_DB would reap the first one's live jobs.
+#
+# The token is deliberately not here. The server fails at startup with a named
+# error when TEXTFLOWKIT_API_TOKEN is missing, which is better than an
+# image-embedded default that every puller would share.
+
+# Pinned to a Python the CI matrix covers (3.10-3.13, linted on 3.12) and to a
+# named Debian release rather than to `latest`, which would move under a rebuild.
+# Not a digest pin: resolving a digest needs a registry lookup that could not be
+# performed where this was written, and an invented one would be worse than an
+# honest tag.
+FROM python:3.12-slim-bookworm
+
+# ffmpeg is required in every profile: decode, and the ffprobe duration bound the
+# production profile enforces before a full decode.
+# ca-certificates is the trust store URL acquisition needs.
+# libstdc++6 is installed unconditionally so the Node binary copied below has a
+# C++ runtime to link against whatever the slim base happens to carry; the gate
+# below would fail the build if that binary could not run at all.
+RUN set -eux; \
+    apt-get update; \
+    apt-get install -y --no-install-recommends ca-certificates ffmpeg libstdc++6; \
+    rm -rf /var/lib/apt/lists/*
+
+# The JavaScript runtime yt-dlp uses to solve some YouTube player challenges.
+# It comes from the official Node image rather than from the base distribution,
+# because the installed yt-dlp requires Node >= 22 (yt_dlp/utils/_jsruntime.py,
+# `NodeJsRuntime.MIN_SUPPORTED_VERSION`) and the version the base distribution
+# carries was not measured here. Taking the runtime from a tag that names the
+# major version does not by itself prove the floor either, which is why the gate
+# below runs the binary and fails the build rather than trusting a tag name.
+COPY --from=node:22-bookworm-slim /usr/local/bin/node /usr/local/bin/node
+
+# yt-dlp's Node floor, taken from the installed package and re-checked against it
+# by tests/test_container_example.py, so a yt-dlp upgrade that raises the floor
+# fails the suite rather than only the build.
+ARG NODE_MIN_MAJOR=22
+RUN set -eux; \
+    node --version; \
+    node -e "const v = parseInt(process.versions.node, 10); if (v < ${NODE_MIN_MAJOR}) { console.error('node ' + process.versions.node + ' is below the yt-dlp Node floor of ${NODE_MIN_MAJOR}.0.0 (yt_dlp/utils/_jsruntime.py); use a newer node image, or raise NODE_MIN_MAJOR deliberately'); process.exit(1) }"; \
+    ffmpeg -version | head -n 1; \
+    ffprobe -version | head -n 1
+
+# Nonroot runtime. The uid and gid are fixed so the Compose file can name them
+# and the volumes below initialize with the right ownership.
+RUN set -eux; \
+    groupadd --gid 10001 textflowkit; \
+    useradd --uid 10001 --gid 10001 --create-home --shell /usr/sbin/nologin textflowkit; \
+    install -d -o textflowkit -g textflowkit \
+        /srv/textflowkit \
+        /srv/textflowkit/input \
+        /srv/textflowkit/output \
+        /srv/textflowkit/work \
+        /srv/textflowkit/state \
+        /home/textflowkit/.cache
+
+WORKDIR /app
+COPY pyproject.toml README.md LICENSE ./
+COPY src ./src
+# The base dependencies are yt-dlp and openai-whisper, so this image is large:
+# openai-whisper pulls a torch build. That is the product's own requirement, not
+# something this file adds.
+RUN python -m pip install --no-cache-dir --upgrade pip \
+ && python -m pip install --no-cache-dir ".[http]"
+
+# Non-secret defaults only. The roots are the directories created above; Compose
+# repeats them so the volumes it mounts land on the paths the service reads.
+# Concurrency stays at the documented default of 1: the store has one owner.
+ENV PYTHONUNBUFFERED=1 \
+    PYTHONDONTWRITEBYTECODE=1 \
+    PIP_NO_CACHE_DIR=1 \
+    TEXTFLOWKIT_PROFILE=production \
+    TEXTFLOWKIT_INPUT_ROOT=/srv/textflowkit/input \
+    TEXTFLOWKIT_OUTPUT_ROOT=/srv/textflowkit/output \
+    TEXTFLOWKIT_WORK_ROOT=/srv/textflowkit/work \
+    TEXTFLOWKIT_DB=/srv/textflowkit/state/jobs.db \
+    TEXTFLOWKIT_MAX_CONCURRENCY=1
+
+USER 10001:10001
+
+# Liveness only, and it has to carry the Bearer token: the production middleware
+# covers /health like every other route. The token is read from the process
+# environment, never passed as an argument, so `ps` cannot show it. That is not
+# secrecy: Docker records an environment variable in the container's
+# configuration (`docker inspect`), and `/proc/<pid>/environ` exposes it inside
+# the container to anything running as the same user. A missing token makes this
+# probe fail rather than pass - the same fail-closed direction as the server.
+HEALTHCHECK --interval=30s --timeout=5s --start-period=40s --retries=3 \
+    CMD ["python", "-c", "import os, urllib.request; request = urllib.request.Request('http://127.0.0.1:8767/health', headers={'Authorization': 'Bearer ' + os.environ['TEXTFLOWKIT_API_TOKEN']}); body = urllib.request.urlopen(request, timeout=3).read(); assert b'status' in body, body"]
+
+# 0.0.0.0 inside the container, so the published host port reaches the server;
+# `--allow-remote` is the explicit opt-in the adapter requires for a bind beyond
+# loopback, and the host side of that publication stays loopback-only in Compose.
+EXPOSE 8767
+CMD ["textflowkit-http", "--host", "0.0.0.0", "--port", "8767", "--allow-remote"]

{textflowkit-0.1.4 → textflowkit-0.1.6}/LEGAL.md

@@ -7,9 +7,18 @@ This document is plain-language guidance, not legal advice.
 textflowkit is distributed under the **Apache License 2.0**, which includes:
 
 - **§7 — Disclaimer of Warranty:** the work is provided on an "AS IS" BASIS,
-  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-- **§8 — Limitation of Liability:** in no event shall any contributor be liable for
-  damages arising from use of the work.
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied —
+  unless required by applicable law or agreed to in writing.
+- **§8 — Limitation of Liability:** in no event shall any contributor be liable
+  for damages arising from use of the work — unless required by applicable law
+  (deliberate and grossly negligent acts are the example the license gives) or
+  agreed to in writing.
+
+Neither of those is an absolute rule: the license sets aside the disclaimer and
+the liability limit where applicable law requires otherwise, or where a separate
+written agreement says otherwise. This section is a plain-language summary; the
+[`LICENSE`](LICENSE) file is the controlling text and is what you should read for
+the terms that apply to you.
 
 The project ships no warranty of accuracy. **Transcripts produced by speech-to-text
 models contain errors.** Do not rely on output for legal, medical, safety-critical,
@@ -41,4 +50,4 @@ outside the intended use of this project.
 
 "textflowkit" is an independent open-source project. It is not affiliated with,
 endorsed by, or connected to any other product or organisation using a similar
-name.
+name.

{textflowkit-0.1.4 → textflowkit-0.1.6}/LICENSE

@@ -200,4 +200,4 @@
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
    limitations under the License.
-
+