phrase-gym 0.2.0__tar.gz

phrase_gym-0.2.0/.coveragerc

@@ -0,0 +1,17 @@
+[run]
+relative_files = true
+omit =
+    */tests/*
+    */*_check.py
+    */__init__.py
+    */conftest.py
+    */.tox/*
+    */.venv/*
+    */.eggs/*
+    */docs/*
+    */build/*
+    */dist/*
+    */.git/*
+    */.github/*
+    */.vscode/*
+    */.pytest_cache/*

phrase_gym-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,117 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_call:
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  server:
+    name: Server (Linux)
+    runs-on: ubuntu-24.04
+    concurrency:
+      group: github-pages
+      cancel-in-progress: false
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          version: 0.11.7
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.13'
+      - run: uv sync --frozen
+      - run: >-
+          uv run pytest --junitxml=pytest.xml --alluredir=allure-results
+          --cov=phrase_gym --cov-report=term-missing --cov-report=xml --cov-report=html
+      - name: Upload test and coverage results
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: server-test-results
+          path: |
+            pytest.xml
+            coverage.xml
+            htmlcov/
+            allure-results/
+      - name: Load Allure history
+        if: always() && github.event_name == 'push' && github.ref == 'refs/heads/main'
+        uses: actions/checkout@v4
+        continue-on-error: true
+        with:
+          ref: gh-pages
+          path: gh-pages-dir
+      - name: Generate Allure report
+        if: always() && github.event_name == 'push' && github.ref == 'refs/heads/main'
+        uses: andgineer/allure-report@v3.6
+        id: allure-report
+        with:
+          allure-results: allure-results
+          website: gh-pages-dir
+          reports-site-path: builds/tests
+      - name: Publish Allure report
+        if: always() && steps.allure-report.outcome == 'success'
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_branch: gh-pages
+          publish_dir: ${{ steps.allure-report.outputs.reports-site }}
+          destination_dir: ${{ steps.allure-report.outputs.reports-site-path }}
+      - name: Coverage comment
+        if: always() && (github.event_name == 'pull_request' || github.ref == 'refs/heads/main')
+        id: coverage-comment
+        uses: py-cov-action/python-coverage-comment-action@v3
+        with:
+          GITHUB_TOKEN: ${{ github.token }}
+          MINIMUM_GREEN: 85
+          MINIMUM_ORANGE: 70
+      - name: Store coverage comment
+        if: steps.coverage-comment.outputs.COMMENT_FILE_WRITTEN == 'true'
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-coverage-comment-action
+          path: python-coverage-comment-action.txt
+      - name: Coveralls
+        if: always() && github.event_name != 'workflow_call'
+        continue-on-error: true
+        uses: coverallsapp/github-action@v2
+      - name: Codecov
+        if: always() && github.event_name != 'workflow_call'
+        continue-on-error: true
+        uses: codecov/codecov-action@v4.0.1
+        with:
+          fail_ci_if_error: true
+          token: ${{ secrets.CODECOV_TOKEN }}
+  checks:
+    name: Full checks (macOS)
+    runs-on: macos-15
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          version: 0.11.7
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.13'
+      - uses: actions/setup-node@v4
+        with:
+          node-version-file: .nvmrc
+          cache: npm
+          cache-dependency-path: frontend/package-lock.json
+      - run: uv sync --frozen
+      - run: npm --prefix frontend ci
+      - run: npx playwright install --with-deps chromium webkit
+        working-directory: frontend
+      - run: uv run inv pre
+      - run: uv run inv test
+      - uses: actions/upload-artifact@v4
+        if: failure()
+        with:
+          name: browser-test-results
+          path: frontend/test-results/
+          if-no-files-found: ignore

phrase_gym-0.2.0/.github/workflows/docs.yml

@@ -0,0 +1,43 @@
+name: docs
+on:
+  push:
+    branches: [main]
+  pull_request:
+permissions:
+  contents: write
+jobs:
+  deploy:
+    runs-on: ubuntu-24.04
+    concurrency:
+      group: github-pages
+      cancel-in-progress: false
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          version: 0.11.7
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.13'
+      - run: uv sync --frozen --all-extras
+      - run: uv run inv build-docs
+      - name: Load existing reports
+        if: github.event_name == 'push'
+        uses: actions/checkout@v4
+        continue-on-error: true
+        with:
+          ref: gh-pages
+          path: gh-pages
+      - name: Preserve test reports
+        if: github.event_name == 'push'
+        run: |
+          if [ -d gh-pages/builds ]; then
+            cp -r gh-pages/builds build/docs/site/builds
+          fi
+      - name: Publish documentation
+        if: github.event_name == 'push'
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_branch: gh-pages
+          publish_dir: build/docs/site

phrase_gym-0.2.0/.github/workflows/pip_publish.yml

@@ -0,0 +1,63 @@
+name: Upload Python Package
+on:
+  push:
+    tags: ['v*.*.*']
+permissions:
+  contents: write
+  pull-requests: write
+jobs:
+  check-tag:
+    runs-on: ubuntu-24.04
+    outputs:
+      version: ${{ steps.version.outputs.version }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.13'
+      - name: Validate release tag and package version
+        id: version
+        env:
+          RELEASE_TAG: ${{ github.ref_name }}
+        run: |
+          python - <<'PY'
+          import os
+          from scripts.release import validate_tag
+          version = validate_tag(os.environ['RELEASE_TAG'])
+          with open(os.environ['GITHUB_OUTPUT'], 'a') as output:
+              output.write(f'version={version}\n')
+          PY
+  checks:
+    needs: check-tag
+    uses: ./.github/workflows/ci.yml
+    secrets: inherit
+  publish:
+    needs: [check-tag, checks]
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          version: 0.11.7
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.13'
+      - uses: actions/setup-node@v4
+        with:
+          node-version-file: .nvmrc
+          cache: npm
+          cache-dependency-path: frontend/package-lock.json
+      - run: uv run inv build
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          user: ${{ secrets.PYPI_USERNAME }}
+          password: ${{ secrets.PYPI_PASSWORD }}
+          packages-dir: dist
+      - name: Create release
+        uses: softprops/action-gh-release@v2
+        with:
+          name: Release ${{ needs.check-tag.outputs.version }}
+          tag_name: ${{ github.ref_name }}
+          target_commitish: ${{ github.sha }}
+          body: https://pypi.org/project/phrase-gym/${{ needs.check-tag.outputs.version }}/

phrase_gym-0.2.0/.github/workflows/static.yml

@@ -0,0 +1,24 @@
+name: static source code checks
+on:
+  push:
+    branches: [main]
+  pull_request:
+jobs:
+  static:
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          version: 0.11.7
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.13'
+      - uses: actions/setup-node@v4
+        with:
+          node-version-file: .nvmrc
+          cache: npm
+          cache-dependency-path: frontend/package-lock.json
+      - run: uv sync --frozen --all-extras
+      - run: npm --prefix frontend ci
+      - run: uv run inv pre

phrase_gym-0.2.0/.gitignore

@@ -0,0 +1,40 @@
+.DS_Store
+.env
+.idea/
+
+# Local tool environments and caches
+.venv/
+**/__pycache__
+**/.pytest_cache
+.ruff_cache/
+.coverage
+build/
+dist/
+site/
+**/*.egg-info
+pytest.xml
+pytest-coverage.txt
+.dmypy.json
+*.py-e
+**/.setup-scripts/
+allure-results/
+htmlcov/
+coverage.xml
+
+# Client dependencies
+**/node_modules/
+
+# Production client build and local application data
+frontend/dist/
+frontend/test-results/
+frontend/playwright-report/
+.data/
+*.sqlite3
+*.sqlite3-wal
+*.sqlite3-shm
+
+# Rust build output
+/target/
+
+# Private local Coach attempts and diagnostics
+.phrase-gym-coach/

phrase_gym-0.2.0/.nvmrc

@@ -0,0 +1 @@
+22

phrase_gym-0.2.0/.pre-commit-config.yaml

@@ -0,0 +1,60 @@
+exclude: ^(src/phrase_gym/server/static/|frontend/src/api.generated.ts|frontend/openapi.json|build/|dist/)
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: check-yaml
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.14.2
+    hooks:
+      - id: ruff-check
+        exclude: ^tests/
+        args:
+          - --fix
+          - --line-length=100
+          - --target-version=py313
+          - --select=PL,A001,ARG,B,BLE,C,COM,E,F,G,I,ISC,N,PIE,Q,RET,S,SIM,SLF,TID,TRY,UP,W
+          - --ignore=B019,S101,G004,TRY003,TRY300,TRY301,TRY400
+          # Development commands resolve trusted tools from the operator's PATH.
+          - --per-file-ignores=scripts/**:S603,scripts/**:S607
+      - id: ruff-check
+        name: ruff check tests
+        files: ^tests/
+        args: [--fix, --line-length=100, --target-version=py313, '--select=E,F,I,UP,B,SIM']
+      - id: ruff-format
+        args: [--line-length=100, --target-version=py313]
+  - repo: https://github.com/facebook/pyrefly-pre-commit
+    rev: 0.50.0
+    hooks:
+      - id: pyrefly-check
+        language: system
+        entry: uv run pyrefly check
+        pass_filenames: false
+  - repo: local
+    hooks:
+      - id: uv-lock
+        name: Dependency lock
+        entry: uv lock --check
+        language: system
+        pass_filenames: false
+        always_run: true
+      - id: module-sizes
+        name: Production module sizes
+        entry: uv run inv check-sizes
+        language: system
+        pass_filenames: false
+        always_run: true
+      - id: client-format
+        name: Client formatting
+        entry: npm --prefix frontend run format:check
+        language: system
+        pass_filenames: false
+        always_run: true
+      - id: api-contract
+        name: Generated API contract
+        entry: uv run inv check-api
+        language: system
+        pass_filenames: false
+        always_run: true

phrase_gym-0.2.0/.python-version

@@ -0,0 +1 @@
+3.13.13

phrase_gym-0.2.0/AGENTS.md

@@ -0,0 +1,102 @@
+# Phrase Gym — agent instructions
+
+Read [specs/START-HERE.md](specs/START-HERE.md) and [remaining work](specs/plan/implementation-plan.md). Specs retain current decisions and hard-to-infer design constraints; code and tests describe implemented behavior. The application is a small local Python service with the retained Vue client in `frontend/`. Earlier Python and Rust code in Git are prototypes, not parity requirements.
+
+For a root-session request to implement the next stage, follow the [orchestration handout](specs/plan/orchestration-handout.md) before making changes or delegating. Delegated agents follow their assigned scope and the regular rules below.
+
+`CLAUDE.md` links to this file; keep one instruction source.
+
+## Architecture and file structure
+
+- Keep architecture under active review in every batch. Each module and service has one coherent responsibility. Split unrelated workflows before adding more methods; do not grow a catch-all service or application component.
+- Aim for no more than 250 lines of handwritten production code per file; review and split before 300. Generated contracts and migrations may be longer. A shorter file does not justify circular dependencies, meaningless wrappers or fragmented invariants.
+- Dependencies point inward: transport and UI adapters use contracts/domain services; domain services never import HTTP routers, application startup or UI modules. Python owns the generated API contract. Construct services at the application boundary. Keep Phrase Gym lightweight and Coach separate under the [application boundary](specs/architecture.md#application-boundary); do not recreate the prototype's general distributed worker or native Coach GUI.
+- Keep validation, publication transactions and library reads separate. One workflow owns each transaction; helpers receive that transaction instead of opening hidden writes. Keep all package publication atomic.
+- Vue views render state. Route orchestration, preferences and audio effects belong in focused composables/adapters; the practice reducer stays pure. Generated API types are the client contract.
+- Preserve the original Vue shell, practice card, microphone control and responsive styling as the Python backend grows. Adapt or hide controls for unavailable workflows; do not replace the interface with a new design.
+- When moving a symbol, update all importers and tests. No re-export compatibility shims. Shared helpers are preferable to duplicated logic.
+
+## Commands and environment
+
+| Task | Command |
+|---|---|
+| Python lint, format, types, module size, client format and contract drift | `uv run inv pre` |
+| Python tests, client typecheck/unit/build and both browser engines | `uv run inv test` |
+| Python iteration | `uv run pytest` |
+| Client iteration | `npm --prefix frontend test` |
+| Browser iteration | `npm --prefix frontend run test:browser` |
+| Refresh OpenAPI and generated client types | `uv run python scripts/generate_api.py && npm --prefix frontend run api-types` |
+| Build the retained client | `npm --prefix frontend run build` |
+| Run the local application on 127.0.0.1:8000 | `uv run phrase-gym run` |
+| Build the frontend and run the local application | `uv run inv run --build` |
+| Install the pre-commit hooks (once per clone) | `uv run pre-commit install` |
+| Scaffold tasks and release commands | `uv run inv --list` |
+| Build documentation | `uv run inv build-docs` |
+| Build the client and Python distributions | `uv run inv build` |
+
+Use `uv sync --frozen` and `npm --prefix frontend ci`; install browser binaries from `frontend/` with `npx playwright install chromium webkit`. Python 3.13 and application dependencies are pinned in `uv.lock`. Use Node 22.12+ on an LTS release (`.nvmrc`). The pre-commit framework runs the pre gate and needs uv, Python, Node and the client dependencies; `inv pre` runs the same hooks manually. Dependency changes update their committed lockfiles. Piper uses its separately pinned private environment described in [the import guide](docs/importing-phrases.md#piper-voice). Missing dependencies or browsers are environment failures to fix, not reasons to skip suites.
+
+Preserve the repository scaffold: pre-commit, Invoke tasks, version/tag helpers, package metadata, environment/build scripts, documentation publishing, test/coverage reports and PyPI release workflows. Extend these for the application instead of replacing or deleting them. Only application/documentation boilerplate should be replaced with real implementation and documentation. Follow [development and release operations](docs/development.md).
+
+Pre-commit owns the static checks and all Ruff settings. Use Pyrefly for Python type checking; do not add a duplicate mypy gate or a wrapper that reruns the same tools. Invoke owns repository development, build, test and release tasks; the packaged CLI owns user runtime and deployment commands, which Invoke may wrap. Keep root-level executable scripts limited to the retained environment activation script.
+
+Run the full browser/audio gate on macOS and retain the separate Linux Python server job in CI, following the [platform boundary](specs/architecture.md#application-boundary). Do not skip native recorder tests to accommodate Linux WebKit's missing API.
+
+## Done gate
+
+Choose the gate from the complete change, including staged and unstaged files.
+
+**CI results are always part of verification:** inspect GitHub Actions for the current remote commit before making changes. After the local gate passes, commit and push under the standing authorization below, then wait for the workflows on the exact pushed commit to finish and inspect every result before delivery. Inspect failed jobs and their logs, fix failures, and repeat the applicable checks and push until CI passes. Local checks do not establish that CI passed. Report the commit, run link and outcome separately from local checks. Missing, pending, cancelled or inaccessible runs are unverified, never passing; report any actual block explicitly.
+
+**Documentation-only changes:** when the change contains only prose in specs, plans, README, docs or agent instructions, do not run application builds or Python/client/browser suites; the installed pre-commit hooks still run. Run `git diff --check` and `git diff --cached --check`, inspect the full diff, verify changed local links/anchors and check consistency with related decisions and plans. Report these documentation checks without claiming application tests passed. Documentation describing future behavior does not require implementing or testing that behavior.
+
+**Implementation or mixed changes:** changes to production code, tests, runtime prompts, generated contracts, migrations, dependencies, executable scripts, build configuration, hooks or CI require the full gate, even when accompanied by specs. Before describing such a milestone as done, ready, fixed, landed or green, run these in order and inspect their complete results:
+
+1. `uv run inv pre`: pre-commit hygiene, Python formatting/lint/types, module-size, client formatting and generated-contract drift checks all pass.
+2. `uv run inv test`: Python, client and both real-backend browser suites pass; frontend checks must run rather than skip.
+
+Use focused checks during iteration. Run the full ordered gate once per coherent implementation deliverable before commit or delivery, rather than after every internal edit. Rerun relevant checks for review fixes and the full gate after substantive changes; a narrow subset cannot replace it. Use the documentation-only gate for prose-only changes. Never bypass commit hooks with `--no-verify`.
+
+Fix findings even when they appear pre-existing. Deferral requires evidence that the same failure exists on the committed baseline and the user's agreement in the current turn. Never silently report a failing tree as passing. If execution or approval infrastructure blocks a check, describe that block explicitly and do not claim the gate passed.
+
+## Tests
+
+- New modules/functions ship meaningful behavioral coverage in the same commit. Keep tests with the responsibility they verify; do not grow one catch-all test file.
+- Behavior that only exists in the browser needs a real-browser test against the real server and built client. Assert provisional/error states deterministically; do not race an artificial delay.
+- For implementation changes, iterate with subsets if useful, then verify the full suite. Documentation-only changes use the done gate above.
+- Never launch system dialogs or native popup paths automatically. If setup, login, permission or a native check needs attended interaction, ask the user directly and report the unresolved acceptance instead of opening it.
+- Before a full browser suite in a restricted environment, run one existing test per browser engine with `--max-failures=1` to verify startup. Stop immediately if browser launch is denied or crashes; do not let the suite repeatedly launch failing browsers and flood the desktop with crash dialogs. Report the environment block and leave the full gate incomplete until it is resolved. Do not rerun browser checks after the user asks to stop them.
+- Automated tests must emit no sound on the host. Mute every browser context, including manually created contexts, while preserving native decoding, playback clocks and events. Synthetic capture feeds a media stream, never the speaker destination. Live listening and physical microphone checks require attended learner interaction and are separate from automated tests.
+- Tests make no real provider, TTS, source mutation or external delivery calls. Fake those boundaries; never read the operator's `.env` or private recordings into fixtures or logs.
+- Never leave a failing test. Diagnose clock, ordering, race and environment causes; do not skip, xfail, delete or weaken the assertion to hide a failure.
+- Software checks are not language-content, speech-quality or actual-device acceptance. Keep Safari/headset, iPhone and content gaps explicit.
+- Prototype fixtures in Git are not replacement compatibility requirements ([architecture](specs/architecture.md#releases-and-data-compatibility)). Preserve meaningful coverage, and replace obsolete expectations only for an intended spec change. The Python application uses library integrations with focused tests rather than carrying forward numerical-port equivalence.
+
+## Code conventions
+
+- Python passes Ruff and Pyrefly; Vue passes Prettier and TypeScript checking. The executable pre gate enforces the handwritten production module-size boundary and generated-contract drift.
+- English only in comments, docstrings, plans and repository documentation. Follow the project's English communication rule. Learning data, language names and voice IDs retain their original language/script as quoted, searchable literals.
+- All imports at module top level, none inside functions and none to break cycles; fix the dependency structure.
+- No re-export shims when moving symbols. Import shared helpers directly from their owner.
+- Comments/docstrings explain a non-obvious why in one or two lines: a hidden constraint, library workaround or invariant. Do not restate the code, argue architectural decisions there, or cite phase/plan names; decisions belong in `specs/`.
+
+## Specs and plans
+
+- `specs/` contains current decisions, their rationale and substantial design constraints that are difficult to infer from code. Code, tests and generated contracts document implemented behavior; usage and operational commands belong in README or `docs/`.
+- Keep one authoritative home per decision. Do not retain historical references, superseded sketches, review logs, implementation inventories or completed plans in specs. Git preserves earlier versions.
+- The implementation plan contains only remaining work. Delete completed entries and plans; retain any lasting decision in its focused spec. Correct contradictory text in the same commit and keep acceptance gaps concise.
+
+## Model integration
+
+- When local AI preparation is used, Codex uses the normal user home and Phrase Gym repository as its working directory, as requested by the learner. Never copy login tokens. Existing private attempt files stay ignored under `.phrase-gym-coach/`; retain subscription-only login, bounded execution and an allowlisted child environment. Deny repository `.env` reads and keep application stores/recordings outside the permitted model workspace. Normal-home instructions/skills may load; do not claim customization isolation. The first MVP imports externally prepared content and needs no internal LLM adapter.
+
+Follow the [standing local English demo authorization](specs/plan/implementation-plan.md#standing-authorization-for-the-local-english-demo): routine demo runs and continuations require no separate budget, temporary authentication workspace or login approval. Existing runtime bounds govern prototype runs; they do not require reproducing its distributed infrastructure. Preserve learner data and recordings during replacement.
+
+When changing prompts, provider payloads or interpretation of real model answers, mocks alone cannot establish model behavior. Plan representative fixtures and real-provider measurements before execution; inspect availability and every concrete result. Record semantic review separately from automated conformance. A fresh reviewer is required for those model-result measurements, not for ordinary refactors. Do not create learner effectiveness experiments or unrequested general review loops.
+
+## Git, secrets and deployment
+
+- Commit authorized work directly to `main` and push it to `origin/main` after the applicable local gate passes, then verify CI as required by the done gate. This is standing authorization; do not ask for separate push approval unless the user explicitly requests local-only work. Do not create branches or PRs by default, and never force-push.
+- Publishing releases and deployment still require the user's explicit request for that action.
+- Keep `.env`, provider keys, learner data and recordings ignored, private and server-side. Never bundle or print secrets.
+- Source repositories, vaults, echo-words, legacy trainers and Anki stay read-only unless separately authorized. Real deployment must be reproducible from committed code and must verify its actual health/access boundary; no one-off server edits.

phrase_gym-0.2.0/CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

phrase_gym-0.2.0/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2026 Andrey Sorokin (andrey@sorokin.engineer)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the “Software”), to deal in
+the Software without restriction, including without limitation the rights to use,
+copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
+Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.

phrase_gym-0.2.0/PKG-INFO

@@ -0,0 +1,139 @@
+Metadata-Version: 2.4
+Name: phrase-gym
+Version: 0.2.0
+Summary: A small local trainer for bringing useful phrases into speech.
+Project-URL: Homepage, https://andgineer.github.io/phrase-gym/
+Project-URL: Documentation, https://andgineer.github.io/phrase-gym/
+Project-URL: Repository, https://github.com/andgineer/phrase-gym
+Author-email: Andrey Sorokin <andrey@sorokin.engineer>
+License: Copyright (c) 2026 Andrey Sorokin (andrey@sorokin.engineer)
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy of
+        this software and associated documentation files (the “Software”), to deal in
+        the Software without restriction, including without limitation the rights to use,
+        copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
+        Software, and to permit persons to whom the Software is furnished to do so,
+        subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND,
+        EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+        OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+        NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+        HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+        WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+        FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+        OTHER DEALINGS IN THE SOFTWARE.
+License-File: LICENSE
+Keywords: language-learning,phrases,spoken-retrieval
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: <3.14,>=3.13
+Requires-Dist: fastapi==0.119.1
+Requires-Dist: platformdirs==4.5.0
+Requires-Dist: pydantic==2.12.3
+Requires-Dist: uvicorn==0.38.0
+Provides-Extra: coach
+Provides-Extra: deploy
+Description-Content-Type: text/markdown
+
+# Phrase Gym
+
+[![CI](https://github.com/andgineer/phrase-gym/workflows/CI/badge.svg)](https://github.com/andgineer/phrase-gym/actions)
+[![Coverage](https://raw.githubusercontent.com/andgineer/phrase-gym/python-coverage-comment-action-data/badge.svg)](https://htmlpreview.github.io/?https://github.com/andgineer/phrase-gym/blob/python-coverage-comment-action-data/htmlcov/index.html)
+
+Phrase Gym is a small local Python/Vue application for studying useful English phrases and
+keeping private learner recordings. This checkpoint supports package import, ungraded first
+study, reference playback, optional recording, comparison, and saved replay. Later recall and
+scheduling remain the next stage.
+
+## Install and launch
+
+The server runs on macOS and Linux. Use a macOS browser for the MVP media player and recording;
+Linux browser audio support is planned after the MVP.
+
+For a source checkout, use Python 3.13, [uv](https://docs.astral.sh/uv/), Node 22.12+ and a
+configured English Piper voice for Coach synthesis. Install the pinned environments and build the client once:
+
+```bash
+uv sync --frozen
+npm --prefix frontend ci
+npm --prefix frontend run build
+```
+
+Start Phrase Gym without any Piper installation:
+
+```bash
+uv run phrase-gym run
+```
+
+For private iPhone access on your existing tailnet, use `uv run inv run --build --tailscale`. This points Tailscale Serve at the new server
+and allows its exact HTTPS machine hostname. Open the HTTPS URL printed by Tailscale on the
+iPhone with Tailscale connected.
+
+The built wheel contains the Vue client. A lean installed package runs `phrase-gym run`.
+Coach runs separately: set `PHRASE_GYM_PIPER_CONFIG` to the private voice file in
+[the import guide](docs/importing-phrases.md#piper-voice), then run
+`uv run phrase-gym coach` in another terminal. The private Piper environment belongs to Coach;
+the server needs only core dependencies. Service registration and deployment commands remain
+unavailable.
+
+Open <http://127.0.0.1:8000> on the Mac. The app listens only on loopback and stores its database,
+references, and recordings in the operating system's Phrase Gym application-data directory.
+For a separate data directory, add `--data-dir /absolute/path`.
+
+## Add and study material
+
+Open **Add material**, paste a package or choose its UTF-8 JSON file, and select **Import**.
+The app saves the request before acknowledging it. A text-only package stays pending while Coach
+is offline; Coach prepares reference audio and returns it through the API. An external agent can
+submit the same package with complete WAV references in one API request, without Coach. The server
+validates and publishes all cards and references together. A preparation error remains visible
+for explicit retry. Exact package
+retries return the existing result; a changed package ID or repeated source/item identity is
+rejected without overwriting learned material.
+
+Study shows the full phrase and meaning/use help. Reference playback and recording are optional.
+Every stopped take is retained separately and saved automatically; pending uploads remain in the
+browser for retry. **Next** records ungraded study completion. The finish screen deliberately does
+not invent a recall grade or schedule before the later-recall stage exists.
+
+See [the package schema, example, and external-agent instruction](docs/importing-phrases.md).
+
+## Development
+
+```bash
+. ./activate.sh
+uv run pre-commit install
+inv --list
+uv run inv pre
+uv run inv test
+```
+
+`inv test` runs Python tests, client typechecking/unit/build checks, and silent real-backend
+browser tests in Chromium and WebKit on macOS. CI runs the full gate on macOS and separately
+runs all Python server tests on Linux. For server-only iteration, use `uv run pytest`.
+Install browser binaries from `frontend/` with
+`npx playwright install chromium webkit`. If migrating from the temporary custom hook, run
+`git config --unset core.hooksPath` before `pre-commit install`.
+
+The scaffold's `inv pre`, `inv reqs`, `inv docs-en`, `inv build-docs`, `inv version`, and
+`inv ver-bug` / `inv ver-feature` / `inv ver-release` commands are available.
+`uv run inv build` builds the client and Python distributions. A version command checks and commits the
+version update, then pushes its release tag; the tag workflow publishes to PyPI only after CI passes.
+See [development and release operations](docs/development.md) for setup and dry-run commands.
+
+Use `uv run inv run --build` to rebuild the frontend and start the server, or `uv run inv run`
+to start it with the existing client build.
+
+[Documentation](https://andgineer.github.io/phrase-gym/),
+[Allure reports](https://andgineer.github.io/phrase-gym/builds/tests/),
+[Codecov](https://app.codecov.io/gh/andgineer/phrase-gym), and
+[Coveralls](https://coveralls.io/github/andgineer/phrase-gym) retain the scaffold's reporting links.
+
+Created using [cookiecutter-python-package](https://github.com/andgineer/cookiecutter-python-package).
+
+Current decisions and remaining work start at [specs/START-HERE.md](specs/START-HERE.md).