crossrs 0.1.0__tar.gz

crossrs-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Danylo Mysak
+
+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.

crossrs-0.1.0/PKG-INFO

@@ -0,0 +1,90 @@
+Metadata-Version: 2.4
+Name: crossrs
+Version: 0.1.0
+Summary: Command-line tool for learning foreign languages through reverse translation of word-based sentences
+Home-page: https://github.com/danmysak/crossrs
+Author: Danylo Mysak
+Author-email: danmysak@gmail.com
+Project-URL: Bug Tracker, https://github.com/danmysak/crossrs/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: openai
+Requires-Dist: prompt_toolkit
+Requires-Dist: pydantic
+Requires-Dist: regex
+Requires-Dist: rich
+Requires-Dist: SQLAlchemy
+Requires-Dist: tqdm
+Requires-Dist: typer
+Dynamic: license-file
+
+# CrossRS
+
+CrossRS is a command-line tool for improving language **production** skills through reverse translation exercises. Given a corpus in your target language, CrossRS translates sentences into a source language you already know and asks you to translate them back, reinforcing vocabulary and grammar through word-based spaced repetition. Because CrossRS uses GPT under the hood, you must have a paid [OpenAI account](https://platform.openai.com/) and an [API key](https://platform.openai.com/api-keys) to run it.
+
+## How It Works
+
+CrossRS focuses on **words** sorted by their frequency in the corpus. You learn the most common ones first. Each study round:
+
+1. CrossRS picks a sentence containing the next word to learn.
+2. The sentence is translated into your source language and shown to you.
+3. You translate it back into the target language.
+4. CrossRS evaluates your translation and provides feedback — either a ✅ confirmation or a ❌ with a highlighted diff showing the minimal corrections needed.
+
+Sentences you translate correctly on the first try are scheduled for a single review in **29 days 20 hours**. Otherwise, they enter a spaced-repetition queue with reviews at **20 hours**, **6 days 20 hours**, and **29 days 20 hours** before being marked as learned.
+
+## Installation
+
+Install [Python](https://www.python.org/downloads/) **3.13 or later** and [pipx](https://pipx.pypa.io/stable/installation/), then run:
+
+```bash
+pipx install crossrs       # install
+pipx upgrade crossrs       # upgrade
+pipx uninstall crossrs     # uninstall
+```
+
+## Initialize a New Language
+
+Prepare a plain-text file that contains **one sentence per line** in the language you want to learn. For example, you can download a monolingual corpus from [OPUS](https://opus.nlpl.eu/). Then run:
+
+```bash
+crossrs init <target-lang> <corpus>
+```
+
+`<target-lang>` is a language code (e.g., `de`, `fr`, `uk`), and `<corpus>` is the path to the corpus file.
+
+## Study a Language
+
+```bash
+crossrs study <target-lang> <source-lang> [--threshold T] [--model <GPT_MODEL>] [--api-key <OPENAI_KEY>]
+```
+
+* **`<target-lang>`** — the language code you initialized earlier.
+* **`<source-lang>`** — the language you want sentences translated into (e.g., `en`).
+* **`--threshold` / `-t`** — the learnedness threshold for words (default: 3). A word is considered fully learned once it has appeared in this many learned sentences.
+* **`--model`** — the GPT model to use for translation and evaluation.
+* **`--api-key`** — your OpenAI API key.
+
+Instead of passing `--model` and `--api-key` each time, you can set the environment variables `CROSSRS_MODEL` and `CROSSRS_API_KEY`.
+
+## View Your Progress
+
+```bash
+crossrs stats <target-lang> [--threshold T]
+```
+
+Displays:
+- **Sentences**: learned + in queue / total
+- **Words**: learned / total, with word-level coverage
+- **Total rounds**: the number of translation attempts so far
+
+## Other Commands
+
+```bash
+crossrs path <target-lang>               # show the path to the language data file
+crossrs delete <target-lang> [--force]   # delete the language data file; use --force to skip the confirmation prompt
+```

crossrs-0.1.0/README.md

@@ -0,0 +1,66 @@
+# CrossRS
+
+CrossRS is a command-line tool for improving language **production** skills through reverse translation exercises. Given a corpus in your target language, CrossRS translates sentences into a source language you already know and asks you to translate them back, reinforcing vocabulary and grammar through word-based spaced repetition. Because CrossRS uses GPT under the hood, you must have a paid [OpenAI account](https://platform.openai.com/) and an [API key](https://platform.openai.com/api-keys) to run it.
+
+## How It Works
+
+CrossRS focuses on **words** sorted by their frequency in the corpus. You learn the most common ones first. Each study round:
+
+1. CrossRS picks a sentence containing the next word to learn.
+2. The sentence is translated into your source language and shown to you.
+3. You translate it back into the target language.
+4. CrossRS evaluates your translation and provides feedback — either a ✅ confirmation or a ❌ with a highlighted diff showing the minimal corrections needed.
+
+Sentences you translate correctly on the first try are scheduled for a single review in **29 days 20 hours**. Otherwise, they enter a spaced-repetition queue with reviews at **20 hours**, **6 days 20 hours**, and **29 days 20 hours** before being marked as learned.
+
+## Installation
+
+Install [Python](https://www.python.org/downloads/) **3.13 or later** and [pipx](https://pipx.pypa.io/stable/installation/), then run:
+
+```bash
+pipx install crossrs       # install
+pipx upgrade crossrs       # upgrade
+pipx uninstall crossrs     # uninstall
+```
+
+## Initialize a New Language
+
+Prepare a plain-text file that contains **one sentence per line** in the language you want to learn. For example, you can download a monolingual corpus from [OPUS](https://opus.nlpl.eu/). Then run:
+
+```bash
+crossrs init <target-lang> <corpus>
+```
+
+`<target-lang>` is a language code (e.g., `de`, `fr`, `uk`), and `<corpus>` is the path to the corpus file.
+
+## Study a Language
+
+```bash
+crossrs study <target-lang> <source-lang> [--threshold T] [--model <GPT_MODEL>] [--api-key <OPENAI_KEY>]
+```
+
+* **`<target-lang>`** — the language code you initialized earlier.
+* **`<source-lang>`** — the language you want sentences translated into (e.g., `en`).
+* **`--threshold` / `-t`** — the learnedness threshold for words (default: 3). A word is considered fully learned once it has appeared in this many learned sentences.
+* **`--model`** — the GPT model to use for translation and evaluation.
+* **`--api-key`** — your OpenAI API key.
+
+Instead of passing `--model` and `--api-key` each time, you can set the environment variables `CROSSRS_MODEL` and `CROSSRS_API_KEY`.
+
+## View Your Progress
+
+```bash
+crossrs stats <target-lang> [--threshold T]
+```
+
+Displays:
+- **Sentences**: learned + in queue / total
+- **Words**: learned / total, with word-level coverage
+- **Total rounds**: the number of translation attempts so far
+
+## Other Commands
+
+```bash
+crossrs path <target-lang>               # show the path to the language data file
+crossrs delete <target-lang> [--force]   # delete the language data file; use --force to skip the confirmation prompt
+```

crossrs-0.1.0/pyproject.toml

@@ -0,0 +1,6 @@
+[build-system]
+requires = [
+    "setuptools>=42",
+    "wheel"
+]
+build-backend = "setuptools.build_meta"

crossrs-0.1.0/setup.cfg

@@ -0,0 +1,42 @@
+[metadata]
+name = crossrs
+version = 0.1.0
+author = Danylo Mysak
+author_email = danmysak@gmail.com
+description = Command-line tool for learning foreign languages through reverse translation of word-based sentences
+long_description = file: README.md
+long_description_content_type = text/markdown
+url = https://github.com/danmysak/crossrs
+project_urls = 
+	Bug Tracker = https://github.com/danmysak/crossrs/issues
+classifiers = 
+	Programming Language :: Python :: 3
+	License :: OSI Approved :: MIT License
+	Operating System :: OS Independent
+
+[options]
+package_dir = 
+	=src
+packages = find:
+python_requires = >=3.13
+install_requires = 
+	openai
+	prompt_toolkit
+	pydantic
+	regex
+	rich
+	SQLAlchemy
+	tqdm
+	typer
+
+[options.entry_points]
+console_scripts = 
+	crossrs = crossrs.crossrs:app
+
+[options.packages.find]
+where = src
+
+[egg_info]
+tag_build = 
+tag_date = 0
+

crossrs-0.1.0/src/crossrs/__init__.py

@@ -0,0 +1 @@
+

crossrs-0.1.0/src/crossrs/app/__init__.py

@@ -0,0 +1,6 @@
+from . import commands  # Register commands with Typer
+from .app import app
+
+__all__ = [
+    'app',
+]

crossrs-0.1.0/src/crossrs/app/app.py

@@ -0,0 +1,7 @@
+import typer
+
+__all__ = [
+    'app',
+]
+
+app = typer.Typer(pretty_exceptions_enable=False)

crossrs-0.1.0/src/crossrs/app/commands/__init__.py

@@ -0,0 +1,13 @@
+from .delete import delete
+from .init import init
+from .path import path
+from .stats import stats
+from .study import study
+
+__all__ = [
+    'delete',
+    'init',
+    'path',
+    'stats',
+    'study',
+]

crossrs-0.1.0/src/crossrs/app/commands/delete.py

@@ -0,0 +1,40 @@
+from typing import Annotated
+
+from typer import Argument, Option
+
+from crossrs.app.app import app
+from crossrs.db import get_path
+from crossrs.utils.typer import typer_raise
+
+__all__ = [
+    'delete',
+]
+
+
+@app.command()
+def delete(
+        language: Annotated[
+            str,
+            Argument(help='Target language code whose data should be removed.'),
+        ],
+        force: Annotated[
+            bool | None,
+            Option(
+                '--force',
+                '-f',
+                help='Skip the confirmation prompt and delete immediately.',
+            ),
+        ] = False,
+) -> None:
+    """Delete all stored data for `language`."""
+    path = get_path(language)
+    if not path.exists():
+        typer_raise(f'Language "{language}" is not initialized.')
+
+    if not force and not input(
+            f'Are you sure you want to delete all data for "{language}"? (y/N): ',
+    ).lower().startswith('y'):
+        typer_raise('Operation canceled.')
+
+    path.unlink(missing_ok=True)
+    print(f'Deleted all data for "{language}".')

crossrs-0.1.0/src/crossrs/app/commands/init.py

@@ -0,0 +1,118 @@
+from __future__ import annotations
+from collections import Counter
+from pathlib import Path
+from typing import Annotated, Generator
+
+from sqlalchemy import text
+from tqdm import tqdm
+from typer import Argument
+
+from crossrs.app.app import app
+from crossrs.db import get_session, Session
+from crossrs.db.models import Metadata, Word, Sentence, SentenceWord
+from crossrs.diff.tokenizer import tokenize
+from crossrs.utils.typer import typer_raise
+
+__all__ = [
+    'init',
+]
+
+
+def get_sentences(corpus: Path) -> Generator[str, None, None]:
+    """Yield sentences from the corpus file."""
+    with corpus.open('r', encoding='utf-8') as file:
+        for line in file:
+            if sentence := line.strip():
+                yield sentence
+
+
+def extract_tokens(sentence: str) -> list[str]:
+    """Extract normalized tokens from a sentence."""
+    return [token.normalized for token in tokenize(sentence)]
+
+
+def extract_words(tokens: list[str]) -> list[str]:
+    """Extract words from a list of tokens."""
+    return list(tokens)
+
+
+def process_corpus(corpus: Path) -> tuple[dict[str, set[str]], Counter[str]]:
+    """Process the corpus and return unique words by sentence and word frequencies."""
+    words_by_sentence: dict[str, set[str]] = {}
+    word_frequencies: Counter[str] = Counter()
+
+    for sentence in tqdm(get_sentences(corpus), desc='Processing sentences'):
+        if sentence not in words_by_sentence:
+            tokens = extract_tokens(sentence)
+            if tokens:
+                words = extract_words(tokens)
+                words_by_sentence[sentence] = set(words)
+                word_frequencies.update(words)
+
+    return words_by_sentence, word_frequencies
+
+
+def add_words(session: Session, frequencies: Counter[str]) -> dict[str, int]:
+    """Add words to the database sorted by frequency and return a mapping of words to their IDs."""
+    ids_by_word: dict[str, int] = {}
+    for word, occurrences in tqdm(frequencies.most_common(), desc='Adding words'):
+        word_obj = Word(
+            word=word,
+            occurrences=occurrences,
+            learnedness=0,
+        )
+        session.add(word_obj)
+        session.flush()
+        ids_by_word[word] = word_obj.id
+    return ids_by_word
+
+
+def add_sentences(session: Session, words_by_sentence: dict[str, set[str]],
+                  ids_by_word: dict[str, int]) -> None:
+    """Add sentences to the database with their word associations."""
+    for sentence_text, words in tqdm(words_by_sentence.items(), desc='Adding sentences'):
+        sentence_obj = Sentence(sentence=sentence_text)
+        session.add(sentence_obj)
+        session.flush()
+        for word in words:
+            session.add(SentenceWord(
+                sentence_id=sentence_obj.id,
+                word_id=ids_by_word[word],
+            ))
+        session.flush()
+
+
+@app.command()
+def init(
+        language: Annotated[
+            str,
+            Argument(help='Target language code (e.g., "de", "fr", "uk").'),
+        ],
+        corpus: Annotated[
+            Path,
+            Argument(
+                dir_okay=False,
+                exists=True,
+                readable=True,
+                resolve_path=True,
+                help='Plain-text file containing one sentence per line.',
+            ),
+        ],
+) -> None:
+    """Initialize CrossRS for a new target language."""
+    with get_session(language) as session:
+        if session.query(Sentence).limit(1).first():
+            typer_raise(f'CrossRS is already initialized for language "{language}".')
+        words_by_sentence, word_frequencies = process_corpus(corpus)
+        if not word_frequencies:
+            typer_raise('No valid sentences found in the corpus.')
+        ids_by_word = add_words(session, word_frequencies)
+        add_sentences(session, words_by_sentence, ids_by_word)
+        session.add(Metadata(id=1, total_rounds=0))
+        print('Committing changes to the database...')
+        session.commit()
+        print('Optimizing the database...')
+        session.execute(text('vacuum'))
+    print(f'Initialized CrossRS for language "{language}" '
+          f'with {len(words_by_sentence)} unique sentences '
+          f'and {len(word_frequencies)} unique words.')

crossrs-0.1.0/src/crossrs/app/commands/path.py

@@ -0,0 +1,26 @@
+from typing import Annotated
+
+from typer import Argument
+
+from crossrs.app.app import app
+from crossrs.db import get_path
+from crossrs.utils.typer import typer_raise
+
+__all__ = [
+    'path',
+]
+
+
+@app.command()
+def path(
+        language: Annotated[
+            str,
+            Argument(help='Target language code whose data file should be printed.'),
+        ],
+) -> None:
+    """Print the absolute path to CrossRS's data file for `language`."""
+    language_path = get_path(language)
+    if language_path.exists():
+        print(language_path.absolute())
+    else:
+        typer_raise(f'Language "{language}" is not initialized.')

crossrs-0.1.0/src/crossrs/app/commands/stats.py

@@ -0,0 +1,138 @@
+from __future__ import annotations
+from typing import Annotated
+
+from dataclasses import dataclass
+from rich.console import Console
+from rich.text import Text
+from sqlalchemy import func, case
+from typer import Argument, Option
+
+from crossrs.app.app import app
+from crossrs.db import get_session, Session
+from crossrs.db.models import Metadata, Word, Sentence
+
+__all__ = [
+    'stats',
+]
+
+DEFAULT_THRESHOLD = 3
+
+
+@dataclass
+class WordStatsItem:
+    learned: int = 0
+    total: int = 0
+    learned_occurrences: int = 0
+    total_occurrences: int = 0
+
+
+@dataclass
+class SentenceStatsData:
+    learned: int = 0
+    in_queue: int = 0
+    total: int = 0
+    total_rounds: int = 0
+    targeted_words: int = 0
+
+
+def compute_word_stats(session: Session, threshold: int) -> WordStatsItem:
+    """Compute word statistics using SQL aggregation."""
+    row = session.query(
+        func.count(Word.id),
+        func.sum(Word.occurrences),
+        func.sum(case((Word.learnedness >= threshold, 1), else_=0)),
+        func.sum(case((Word.learnedness >= threshold, Word.occurrences), else_=0)),
+    ).one()
+
+    return WordStatsItem(
+        learned=int(row[2] or 0),
+        total=int(row[0] or 0),
+        learned_occurrences=int(row[3] or 0),
+        total_occurrences=int(row[1] or 0),
+    )
+
+
+def compute_sentence_stats(session: Session, threshold: int) -> SentenceStatsData:
+    """Compute sentence statistics using SQL aggregation."""
+    row = session.query(
+        func.count(Sentence.id),
+        func.sum(case((Sentence.status == 2, 1), else_=0)),
+        func.sum(case((Sentence.status == 1, 1), else_=0)),
+    ).one()
+
+    meta = session.get(Metadata, 1)
+    total_rounds = meta.total_rounds if meta else 0
+
+    targeted_words = session.query(
+        func.count(func.distinct(Sentence.target_word_id)),
+    ).filter(
+        Sentence.status == 1,
+        Sentence.target_word_id.is_not(None),
+    ).join(Word, Sentence.target_word_id == Word.id).filter(
+        Word.learnedness < threshold,
+    ).scalar()
+
+    return SentenceStatsData(
+        total=int(row[0]),
+        total_rounds=total_rounds,
+        learned=int(row[1] or 0),
+        in_queue=int(row[2] or 0),
+        targeted_words=int(targeted_words or 0),
+    )
+
+
+def format_section_title(title: str) -> Text:
+    return Text(title, style='bold underline')
+
+
+def format_stats_label(title: str) -> Text:
+    return Text(f'{title}:', style='bold')
+
+
+@app.command()
+def stats(
+        language: Annotated[
+            str,
+            Argument(help='Target language code to show statistics for.'),
+        ],
+        threshold: Annotated[
+            int,
+            Option(
+                '--threshold', '-t',
+                help='Learnedness threshold for words to be considered fully learned.',
+            ),
+        ] = DEFAULT_THRESHOLD,
+) -> None:
+    """Display study statistics for the given language."""
+    with get_session(language) as session:
+        word_stats = compute_word_stats(session, threshold)
+        sentence_stats = compute_sentence_stats(session, threshold)
+
+    console = Console(highlight=False)
+
+    # Sentence statistics
+    console.print(format_section_title('Sentence Statistics'))
+    console.print(
+        format_stats_label('Sentences'),
+        Text(f'{sentence_stats.learned} learned + {sentence_stats.in_queue} in queue '
+             f'/ {sentence_stats.total} total'),
+    )
+    console.print()
+
+    # Word statistics
+    console.print(format_section_title('Word Statistics'))
+    text = Text(f'{word_stats.learned} learned / {word_stats.total} total')
+    if word_stats.total_occurrences > 0:
+        coverage = word_stats.learned_occurrences / word_stats.total_occurrences
+        text.append(f' ')
+        text.append(Text(f'(coverage: {coverage:.1%})', style='dim'))
+    console.print(format_stats_label('Words'), text)
+    if sentence_stats.targeted_words > 0:
+        console.print(
+            format_stats_label('Targeted'),
+            Text(f'{sentence_stats.targeted_words} unlearned words in queue'),
+        )
+    console.print()
+
+    # Total rounds
+    console.print(format_stats_label('Total rounds'), sentence_stats.total_rounds)