echo-words 0.0.1__tar.gz

echo_words-0.0.1/.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/*

echo_words-0.0.1/.github/workflows/ci.yml

@@ -0,0 +1,132 @@
+
+# This workflow will install Python dependencies, run tests and lint with a variety of Python versions
+# For more information see: https://help.github.com/actions/language-and-framework-guides/using-python-with-github-actions
+#
+name: CI
+
+env:
+  PRIMARY_PYTHON_VERSION: '3.13'
+  PRIMARY_PLATFORM: 'ubuntu-latest'
+  PYTEST_CMD: >-
+    python -m pytest
+    --junitxml=pytest.xml
+    --cov-report=term-missing:skip-covered
+    --cov=src
+    tests/
+
+on:
+  push:
+    branches: [ master, main ]
+  pull_request:
+    branches: [ master, main ]
+
+permissions:
+  pull-requests: write
+  contents: write
+
+jobs:
+  # Test compatibility with the matrix of Python versions and platforms
+  matrix-build:
+    strategy:
+      matrix:
+        python-version: [3.12, 3.13]
+        platform: [ubuntu-latest, macos-latest, windows-latest]
+    runs-on: ${{ matrix.platform }}
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+
+
+    - name: Install uv environment
+      uses: andgineer/uv-venv@v3
+
+    - name: Install dependencies
+      run: uv sync --frozen --all-extras
+
+    - name: Test with pytest
+      run: ${{ env.PYTEST_CMD }}
+
+# Build with publishing Allure report, coverage report
+  primary-build:
+    runs-on: ubuntu-latest
+    concurrency:
+      group: github-pages
+      cancel-in-progress: false
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python ${{ env.PRIMARY_PYTHON_VERSION }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ env.PRIMARY_PYTHON_VERSION }}
+
+
+    - name: Install uv environment
+      uses: andgineer/uv-venv@v3
+
+    - name: Install dependencies
+      run: uv sync --frozen --all-extras
+
+    - name: Test with pytest and Allure report
+      run: "${{ env.PYTEST_CMD }} --alluredir=./allure-results"
+
+    - name: Load Allure test report history
+      uses: actions/checkout@v4
+      if: always()
+      continue-on-error: true
+      with:
+        ref: gh-pages
+        path: gh-pages-dir
+
+    - name: Generate Allure test report
+      uses: andgineer/allure-report@v3.6
+      id: allure-report
+      if: always()
+      with:
+        allure-results: allure-results
+        website: gh-pages-dir
+        reports-site-path: builds/tests
+
+    - name: Publish Allure test report
+      uses: peaceiris/actions-gh-pages@v3
+      if: ${{ always() && (steps.allure-report.outcome == 'success') }}
+      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
+      id: coverage_comment
+      if: always()
+      uses: py-cov-action/python-coverage-comment-action@v3
+      with:
+        GITHUB_TOKEN: ${{ github.token }}
+        MINIMUM_GREEN: 85
+        MINIMUM_ORANGE: 70
+
+    - name: Store Pull Request comment to be posted
+      uses: actions/upload-artifact@v4
+      if: steps.coverage_comment.outputs.COMMENT_FILE_WRITTEN == 'true'
+      with:
+        name: python-coverage-comment-action
+        path: python-coverage-comment-action.txt
+
+    - name: Upload coverage data to coveralls.io
+      if: always()
+      continue-on-error: true
+      uses: coverallsapp/github-action@v2
+
+    - name: Upload Coverage to Codecov
+      if: always()
+      continue-on-error: true
+      uses: codecov/codecov-action@v4.0.1
+      with:
+        fail_ci_if_error: true
+        token: ${{ secrets.CODECOV_TOKEN }}

echo_words-0.0.1/.github/workflows/docs.yml

@@ -0,0 +1,63 @@
+
+# build docs from docstrings and markdown-file in folder docs
+# publish them as github pages
+#
+#note for myself
+#
+# Do not forget to set git branch `gh-pages` as source for github pages.
+# This branch auto-updated by `mkdocs gh-deploy`
+#
+name: docs
+on:
+  push:
+    branches:
+      - main
+      - master
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    env:
+      PRIMARY_PYTHON_VERSION: '3.13'
+    runs-on: ubuntu-latest
+    concurrency:
+      group: github-pages
+      cancel-in-progress: false
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Checkout gh-pages to backup Allure test reports
+        uses: actions/checkout@v4
+        with:
+          ref: gh-pages
+          path: gh-pages
+        continue-on-error: true
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ env.PRIMARY_PYTHON_VERSION  }}
+
+
+      - name: Install uv environment
+        uses: andgineer/uv-venv@v3
+
+      - name: Install dependencies
+        run: |
+          uv sync --frozen --all-extras
+          uv pip install ghp-import
+
+
+      - name: Build documentation
+        run: inv build-docs
+
+      - name: Restore Allure test reports into build output
+        run: |
+          if [ -d gh-pages/builds ]; then
+            cp -r gh-pages/builds build/docs/site/builds
+          fi
+
+      - name: Deploy to GitHub Pages
+        run: |
+          ghp-import --no-jekyll --push --force build/docs/site

echo_words-0.0.1/.github/workflows/pip_publish.yml

@@ -0,0 +1,91 @@
+
+# This workflows will upload a Python Package using build system from pyproject.toml - when version
+# tag is pushed and CI workflow is successful.
+#
+# To push the tag use `inv ver-release/feature/bag`.
+#
+# Put you pypi credentials (PYPI_USERNAME, PYPI_PASSWORD) into the github repository secrets
+
+name: Upload Python Package
+
+on:
+  workflow_run:
+    workflows: ["CI"]
+    types: [completed]
+    branches:
+      - master
+      - main
+
+permissions:
+  contents: write
+
+jobs:
+  check_tag:
+    runs-on: ubuntu-latest
+    outputs:
+      has_tag: ${{ steps.check_tag.outputs.has_tag }}
+      version_tag: ${{ steps.check_tag.outputs.version_tag }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Check for version tag
+        id: check_tag
+        run: |
+          # Only accept semver tags like v1.2.3
+          TAG=$(git tag --points-at HEAD | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+$' || true)
+          if [ -n "$TAG" ]; then
+            echo "has_tag=true" >> $GITHUB_OUTPUT
+            # Strip leading 'v' for use in the workflow
+            echo "version_tag=${TAG#v}" >> $GITHUB_OUTPUT
+          else
+            echo "has_tag=false" >> $GITHUB_OUTPUT
+          fi
+
+  publish:
+    needs: check_tag
+    # Skip entire job unless a valid semver tag was found
+    if: needs.check_tag.outputs.has_tag == 'true'
+    env:
+      RELEASE_VERSION: ${{ needs.check_tag.outputs.version_tag }}
+      PRIMARY_PYTHON_VERSION: '3.13'
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ env.PRIMARY_PYTHON_VERSION }}
+
+
+      - name: Install uv environment
+        uses: andgineer/uv-venv@v3
+
+      - name: Install dependencies
+        run: uv sync --frozen --all-extras
+
+      - name: Build package
+        run: uv 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
+        id: create_release
+        uses: softprops/action-gh-release@v2
+        with:
+          name: Release ${{ env.RELEASE_VERSION }}
+          tag_name: ${{ env.RELEASE_VERSION }}
+
+          body: https://pypi.org/project/echo-words/${{ env.RELEASE_VERSION }}/
+          draft: false
+          prerelease: false

echo_words-0.0.1/.github/workflows/static.yml

@@ -0,0 +1,34 @@
+
+# build docs from docstrings and markdown-file in folder docs
+# publish them as github pages
+#
+#note for myself
+#
+# Do not forget to set git branch `gh-pages` as source for github pages.
+# This branch auto-updated by `mkdocs gh-deploy`
+#
+name: static source code checks
+on:
+  push:
+    branches: [ master, main ]
+  pull_request:
+    branches: [ master, main ]
+
+jobs:
+  static:
+    env:
+      PRIMARY_PYTHON_VERSION: '3.13'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ env.PRIMARY_PYTHON_VERSION  }}
+
+
+      - name: Install uv environment
+        uses: andgineer/uv-venv@v3
+
+      - name: Install dependencies
+        run: uv sync --frozen --all-extras
+      - run: pre-commit run --verbose --all-files

echo_words-0.0.1/.gitignore

@@ -0,0 +1,15 @@
+.DS_Store
+.idea/
+.venv/
+build/
+dist/
+**/__pycache__
+**/.pytest_cache
+**/*.egg-info
+pytest.xml
+.coverage
+.dmypy.json
+pytest-coverage.txt
+*.py-e
+**/.setup-scripts/
+allure-results/

echo_words-0.0.1/.pre-commit-config.yaml

@@ -0,0 +1,74 @@
+exclude: |
+    (?x)(
+      .venv/|
+      tasks.py|
+      resources/
+    )
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: check-yaml
+      - id: end-of-file-fixer
+        exclude_types: [ python ]
+      - id: trailing-whitespace
+        exclude_types: [ python ]
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.16.0
+    hooks:
+      - id: ruff
+        exclude: ^tests/
+        args: [
+          --fix,
+          --line-length=100,
+          --select=PL,    # All Pylint rules
+          --select=A001,  # Shadowing Python builtins
+          --select=ARG,   # Unused function arguments
+          --select=B,     # Bugbear rules (B002,B006,etc)
+          --select=BLE,   # Blind except
+          --select=C,     # Complexity
+          --select=COM,   # Comma placement
+          --select=E,     # pycodestyle errors
+          --select=F,     # Pyflakes
+          --select=G,     # Logging format
+          --select=I,     # Import ordering
+          --select=ISC,   # Implicit string concatenation
+          --select=N,     # Naming
+          --select=PIE,   # Misc rules
+          --select=Q,     # Quotes
+          --select=RET,   # Return statement
+          --select=S,     # Security
+          --select=SIM,   # Code simplification
+          --select=SLF,   # Private member access
+          --select=TID,   # Tidy imports
+          --select=TRY,   # Exception handling
+          --select=UP,    # Upgrade syntax
+          --select=W,     # Warnings
+          '--ignore=B019,S101,G004,TRY003,TRY300,TRY301,TRY400'  # Ignore docstring and `assert` detection
+        ]
+      - id: ruff
+        name: ruff-format-tests
+        files: ^tests/
+        args: [
+          --fix-only,
+          --line-length=100
+        ]
+      - id: ruff-format
+        args: [
+          --line-length=100
+        ]
+
+
+
+  - repo: https://github.com/facebook/pyrefly-pre-commit
+    rev: 1.2.0.dev2
+    hooks:
+      - id: pyrefly-check
+        name: pyrefly check
+        language: system
+        args: [
+#          "--ignore=missing-import",
+#          "--ignore=missing-source-for-stubs",
+          "--project-excludes=tests",
+          "--python-interpreter-path=.venv/bin/python"
+        ]

echo_words-0.0.1/AGENTS.md

@@ -0,0 +1,26 @@
+# wordgram — agent instructions
+
+## Where the specification lives
+
+- `spec/functional-description.md` — WHAT to build. The source of
+  truth: on any conflict with other documents, it wins.
+- `spec/implementation-plan.md` — HOW to build it: milestones M0–M8.
+  Work is driven by its "Execution protocol" section — one milestone
+  per session, strictly in order.
+- `spec/decision-*.md` — background for settled decisions (chat
+  interface, spaced repetition, TTS). Do not re-open them.
+
+## Hard rules
+
+- Python 3.12+, `src` layout, hatchling packaging — do not restructure
+  the packaging.
+- Dependencies via `uv`; run `uv lock` when adding any (CI uses
+  `--frozen`).
+- Every new module ships its tests in the same commit. A milestone is
+  done only when `uv run pytest` and `ruff check` (line-length 99) are
+  green.
+- No real network, Telegram, Anki sync, or LLM/agent calls in tests —
+  fake or mock every boundary. The M0 harness in `experiments/` is the
+  sanctioned exception and stays out of CI.
+- English-only comments and docs. All imports at module top level (the
+  one sanctioned exception is marked in the plan, M6).

echo_words-0.0.1/CLAUDE.md

@@ -0,0 +1 @@
+Project rules and the pointer to the specification: @AGENTS.md

echo_words-0.0.1/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.

echo_words-0.0.1/PKG-INFO

@@ -0,0 +1,81 @@
+Metadata-Version: 2.4
+Name: echo-words
+Version: 0.0.1
+Summary: Turns words into rich linguistic insights and automatically adds them to your spaced repetition system.
+Project-URL: Homepage, https://andgineer.github.io/echo-words/
+Project-URL: Documentation, https://andgineer.github.io/echo-words/
+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: one,two
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.12
+Requires-Dist: click>=8.2.0
+Requires-Dist: rich-click>=1.8.8
+Description-Content-Type: text/markdown
+
+[![Build Status](https://github.com/andgineer/echo-words/workflows/CI/badge.svg)](https://github.com/andgineer/echo-words/actions)
+[![Coverage](https://raw.githubusercontent.com/andgineer/echo-words/python-coverage-comment-action-data/badge.svg)](https://htmlpreview.github.io/?https://github.com/andgineer/echo-words/blob/python-coverage-comment-action-data/htmlcov/index.html)
+# echo-words
+
+Turns words into rich linguistic insights and automatically adds them to your spaced repetition system.
+
+# Documentation
+
+[Echo Words](https://andgineer.github.io/echo-words/)
+
+
+
+# Developers
+
+Do not forget to run `. ./activate.sh`.
+
+For work it need [uv](https://github.com/astral-sh/uv) installed.
+
+Use [pre-commit](https://pre-commit.com/#install) hooks for code quality:
+
+    pre-commit install
+
+## Allure test report
+
+* [Allure report](https://andgineer.github.io/echo-words/builds/tests/)
+
+# Scripts
+Install [invoke](https://docs.pyinvoke.org/en/stable/) preferably with [uv tool](https://docs.astral.sh/uv/):
+
+    uv tool install invoke
+
+For a list of available scripts run:
+
+    invoke --list
+
+For more information about a script run:
+
+    invoke <script> --help
+
+## Coverage report
+* [Codecov](https://app.codecov.io/gh/andgineer/echo-words/tree/main/src%2Fecho_words)
+* [Coveralls](https://coveralls.io/github/andgineer/echo-words)
+
+> Created with cookiecutter using [template](https://github.com/andgineer/cookiecutter-python-package)

echo_words-0.0.1/README.md

@@ -0,0 +1,44 @@
+[![Build Status](https://github.com/andgineer/echo-words/workflows/CI/badge.svg)](https://github.com/andgineer/echo-words/actions)
+[![Coverage](https://raw.githubusercontent.com/andgineer/echo-words/python-coverage-comment-action-data/badge.svg)](https://htmlpreview.github.io/?https://github.com/andgineer/echo-words/blob/python-coverage-comment-action-data/htmlcov/index.html)
+# echo-words
+
+Turns words into rich linguistic insights and automatically adds them to your spaced repetition system.
+
+# Documentation
+
+[Echo Words](https://andgineer.github.io/echo-words/)
+
+
+
+# Developers
+
+Do not forget to run `. ./activate.sh`.
+
+For work it need [uv](https://github.com/astral-sh/uv) installed.
+
+Use [pre-commit](https://pre-commit.com/#install) hooks for code quality:
+
+    pre-commit install
+
+## Allure test report
+
+* [Allure report](https://andgineer.github.io/echo-words/builds/tests/)
+
+# Scripts
+Install [invoke](https://docs.pyinvoke.org/en/stable/) preferably with [uv tool](https://docs.astral.sh/uv/):
+
+    uv tool install invoke
+
+For a list of available scripts run:
+
+    invoke --list
+
+For more information about a script run:
+
+    invoke <script> --help
+
+## Coverage report
+* [Codecov](https://app.codecov.io/gh/andgineer/echo-words/tree/main/src%2Fecho_words)
+* [Coveralls](https://coveralls.io/github/andgineer/echo-words)
+
+> Created with cookiecutter using [template](https://github.com/andgineer/cookiecutter-python-package)

echo_words-0.0.1/activate.sh

@@ -0,0 +1,61 @@
+#!/usr/bin/env bash
+#
+# "Set-ups or/and activates development environment"
+#
+
+VENV_FOLDER=".venv"
+
+PRIMARY_PYTHON_VERSION="3.13"  # sync with .github/workflows/docs.yml&static.yml
+
+RED='\033[1;31m'
+GREEN='\033[1;32m'
+CYAN='\033[1;36m'
+NC='\033[0m' # No Color
+
+if ! (return 0 2>/dev/null) ; then
+    # If return is used in the top-level scope of a non-sourced script,
+    # an error message is emitted, and the exit code is set to 1
+    echo
+    echo -e $RED"This script should be sourced like"$NC
+    echo "    . ./activate.sh"
+    echo
+    exit 1
+fi
+
+
+if [[ ! -d ${VENV_FOLDER} ]] ; then
+    unset CONDA_PREFIX  # if conda is installed, it will mess with the virtual env
+
+    echo -e $CYAN"Creating virtual environment for python in ${VENV_FOLDER}"$NC
+    START_TIME=$(date +%s)
+
+    # Check if the required Python version is installed
+    if ! command -v python${PRIMARY_PYTHON_VERSION} &> /dev/null; then
+        echo -e $RED"Error: Python ${PRIMARY_PYTHON_VERSION} is not installed."$NC
+        echo -e $YELLOW"Please install Python ${PRIMARY_PYTHON_VERSION} before proceeding."$NC
+        echo -e $YELLOW"You can download it from https://www.python.org/downloads/"$NC
+        return 1
+    fi
+
+    if command -v uv &> /dev/null; then
+        if uv venv ${VENV_FOLDER} --python=python${PRIMARY_PYTHON_VERSION}; then
+
+            . ${VENV_FOLDER}/bin/activate
+            uv sync --frozen --all-extras
+            END_TIME=$(date +%s)
+            echo "Environment created in $((END_TIME - $START_TIME)) seconds"
+        else
+            echo -e $RED"Error creating virtual environment. Please check the output above for more details."$NC
+            return 1
+        fi
+    else
+
+        echo -e $RED"Error: Astral's UV is not installed."$NC
+        echo -e $YELLOW"Please install UV from https://github.com/astral-sh/uv before proceeding."$NC
+
+        return 1
+    fi
+else
+    echo -e $CYAN"Activating virtual environment ..."$NC
+    . ${VENV_FOLDER}/bin/activate
+fi

echo_words-0.0.1/build.sh

@@ -0,0 +1,21 @@
+#! /usr/bin/env bash
+# Builds dev version of the container(s)
+# Pass all args to docker compose
+#
+# Examples:
+# build.sh --no-cache
+
+cleanup() {
+  # Function to clean up the .setup-scripts folder
+  rm -rf .setup-scripts
+}
+
+# Trap signals and execute the cleanup function
+trap cleanup EXIT INT TERM ERR
+cp -r ../../docker-scripts .setup-scripts
+./compose.sh \
+  build \
+  "$@"
+
+# Cleanup the .setup-scripts folder (redundant, but ensures cleanup)
+cleanup