foxmath 0.4.0__tar.gz → 0.6.0__tar.gz

{foxmath-0.4.0/src/foxmath.egg-info → foxmath-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: foxmath
-Version: 0.4.0
+Version: 0.6.0
 Summary: Minimalist CLI for math & cryptography exploration 🦊
 Author-email: Abhrankan Chakrabarti <abhrankan@gmail.com>
 License: MIT
@@ -32,9 +32,11 @@ Built with curiosity — for students, tinkerers, and crypto/math enthusiasts.
   named curves (secp256k1) with on-curve result validation
 - Chinese Remainder Theorem solver (handles non-coprime moduli)
 - Continued fraction expansion and convergents
-- Symlink-friendly (foxmath-legendre, foxmath-pi, foxmath-ecadd, foxmath-crt, foxmath-cf)
+- Challenge/quiz mode — practice problems with scoring, or a
+  worksheet mode for self-study
+- Symlink-friendly (foxmath-legendre, foxmath-pi, foxmath-ecadd,
+  foxmath-crt, foxmath-cf, foxmath-challenge)
 - JSON output mode
-- Coming soon: challenge mode
 
 ## Installation
 
@@ -101,6 +103,20 @@ foxmath cf --num 355 --den 113
   355/113
 ```
 
+```bash
+# Challenge/quiz mode — worksheet (no prompting)
+foxmath challenge --topic legendre --count 2 --seed 1 --reveal
+```
+```
+1. Legendre symbol (10/13)
+   Answer: 1
+2. Legendre symbol (3/7)
+   Answer: -1
+```
+
+Drop `--reveal` to answer interactively instead, with scoring at the end.
+`--topic` accepts `legendre`, `crt`, or `mixed` (default).
+
 ```bash
 # JSON output
 foxmath pi --terms 100 --json

{foxmath-0.4.0 → foxmath-0.6.0}/README.md

@@ -13,9 +13,11 @@ Built with curiosity — for students, tinkerers, and crypto/math enthusiasts.
   named curves (secp256k1) with on-curve result validation
 - Chinese Remainder Theorem solver (handles non-coprime moduli)
 - Continued fraction expansion and convergents
-- Symlink-friendly (foxmath-legendre, foxmath-pi, foxmath-ecadd, foxmath-crt, foxmath-cf)
+- Challenge/quiz mode — practice problems with scoring, or a
+  worksheet mode for self-study
+- Symlink-friendly (foxmath-legendre, foxmath-pi, foxmath-ecadd,
+  foxmath-crt, foxmath-cf, foxmath-challenge)
 - JSON output mode
-- Coming soon: challenge mode
 
 ## Installation
 
@@ -82,6 +84,20 @@ foxmath cf --num 355 --den 113
   355/113
 ```
 
+```bash
+# Challenge/quiz mode — worksheet (no prompting)
+foxmath challenge --topic legendre --count 2 --seed 1 --reveal
+```
+```
+1. Legendre symbol (10/13)
+   Answer: 1
+2. Legendre symbol (3/7)
+   Answer: -1
+```
+
+Drop `--reveal` to answer interactively instead, with scoring at the end.
+`--topic` accepts `legendre`, `crt`, or `mixed` (default).
+
 ```bash
 # JSON output
 foxmath pi --terms 100 --json

{foxmath-0.4.0 → foxmath-0.6.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "foxmath"
-version = "0.4.0"
+version = "0.6.0"
 description = "Minimalist CLI for math & cryptography exploration 🦊"
 readme = "README.md"
 license = {text = "MIT"}
@@ -31,5 +31,7 @@ foxmath = "foxmath.foxmath:main"
 foxmath-legendre = "foxmath.foxmath:main"
 foxmath-pi = "foxmath.foxmath:main"
 foxmath-ecadd = "foxmath.foxmath:main"
+foxmath-ecmul = "foxmath.foxmath:main"
 foxmath-crt = "foxmath.foxmath:main"
 foxmath-cf = "foxmath.foxmath:main"
+foxmath-challenge = "foxmath.foxmath:main"

{foxmath-0.4.0 → foxmath-0.6.0}/src/foxmath/foxmath.py

@@ -7,9 +7,19 @@ One binary. Clean. Educational. Safe.
 import argparse
 import sys
 import json
+import random
 from decimal import Decimal, getcontext
+from importlib import metadata
+from math import gcd
 from pathlib import Path
 
+def _package_version() -> str:
+    """Installed package version, falling back to 'unknown' when run from a bare checkout."""
+    try:
+        return metadata.version("foxmath")
+    except metadata.PackageNotFoundError:
+        return "unknown"
+
 # ------------------- Math Functions -------------------
 
 def legendre_symbol(a: int, p: int) -> int:
@@ -70,12 +80,63 @@ CURVES = {
         "gx": 3,
         "gy": 6,
     },
+    "toy193": {  # teaching curve: y^2 = x^3 + x + 5 (mod 193); #E = 193 (prime),
+                 # so every non-identity point generates the whole group —
+                 # hand-checkable discrete-log experiments live here.
+        "a": 1,
+        "b": 5,
+        "p": 193,
+        "gx": 1,
+        "gy": 59,
+    },
 }
 
 def is_on_curve(x: int, y: int, a: int, b: int, p: int) -> bool:
     """Check y^2 = x^3 + a*x + b (mod p)."""
     return (y * y - (x ** 3 + a * x + b)) % p == 0
 
+def _ec_add_raw(P, Q, a, p):
+    """
+    Point addition with an explicit identity: None represents the point at
+    infinity. Used by ec_mul; ec_point_add above is the user-facing variant,
+    which raises on infinity instead of representing it.
+    """
+    if P is None:
+        return Q
+    if Q is None:
+        return P
+    x1, y1 = P
+    x2, y2 = Q
+    if x1 == x2 and (y1 + y2) % p == 0:
+        return None
+    if P == Q:
+        lam = (3 * x1 * x1 + a) * pow(2 * y1, -1, p) % p
+    else:
+        lam = (y2 - y1) * pow(x2 - x1, -1, p) % p
+    x3 = (lam * lam - x1 - x2) % p
+    return (x3, (lam * (x1 - x3) - y1) % p)
+
+def ec_mul(k: int, x: int, y: int, a: int, p):
+    """
+    Scalar multiplication k·P via double-and-add on y² = x³ + a x + b (mod p).
+    Returns (x, y), or None for the point at infinity (k ≡ 0 mod ord(P)).
+
+    Double-and-add: O(log k) group operations instead of k — this is exactly
+    why the forward direction (compute k·G) is easy while the reverse
+    (recover k from k·G, the discrete logarithm) is believed hard for large
+    groups. That asymmetry is the engine inside ECDSA and ECDH.
+    """
+    if k < 0:
+        raise ValueError("k must be non-negative")
+    result = None  # identity
+    addend = (x % p, y % p)
+    while k > 0:
+        if k & 1:
+            result = _ec_add_raw(result, addend, a, p)
+        addend = _ec_add_raw(addend, addend, a, p)
+        k >>= 1
+    return result
+
 def _extended_gcd(a: int, b: int):
     """Returns (g, x, y) such that a*x + b*y == g == gcd(a, b)."""
     old_r, r = a, b
@@ -150,6 +211,68 @@ def cf_convergents(cf):
         k2, k1 = k1, k
     return convergents
 
+# ------------------- Challenge / Quiz Mode -------------------
+
+_SMALL_ODD_PRIMES = [3, 5, 7, 11, 13, 17, 19, 23, 29, 31, 37, 41, 43, 47,
+                      53, 59, 61, 67, 71, 73, 79, 83, 89, 97]
+_CRT_MODULI_CANDIDATES = [3, 4, 5, 7, 9, 11, 13]
+
+def _generate_legendre_problem(rng: random.Random) -> dict:
+    p = rng.choice(_SMALL_ODD_PRIMES)
+    a = rng.randint(1, p - 1)
+    return {
+        "topic": "legendre",
+        "question": f"Legendre symbol ({a}/{p})",
+        "answer": legendre_symbol(a, p),
+    }
+
+def _generate_crt_problem(rng: random.Random) -> dict:
+    while True:
+        m1, m2 = rng.sample(_CRT_MODULI_CANDIDATES, 2)
+        if gcd(m1, m2) == 1:
+            break
+    r1, r2 = rng.randrange(m1), rng.randrange(m2)
+    x, m = crt_solve([r1, r2], [m1, m2])
+    return {
+        "topic": "crt",
+        "question": f"x ≡ {r1} (mod {m1}), x ≡ {r2} (mod {m2}); find x (0 ≤ x < {m})",
+        "answer": x,
+    }
+
+_ECDLP_CURVE = "toy193"  # prime group order → every point is a generator
+
+def _generate_ecdlp_problem(rng: random.Random) -> dict:
+    """
+    A baby-size elliptic-curve discrete logarithm: given G and Q = k·G on the
+    teaching curve, recover k. With 2 ≤ k ≤ 20 it is solvable by hand through
+    repeated addition — which is precisely the lesson: on secp256k1 the same
+    search space is ~10^77, and brute force stops being an option.
+    """
+    c = CURVES[_ECDLP_CURVE]
+    k = rng.randint(2, 20)
+    qx, qy = ec_mul(k, c["gx"], c["gy"], c["a"], c["p"])
+    return {
+        "topic": "ecdlp",
+        "question": (
+            f"On y² = x³ + {c['a']}x + {c['b']} (mod {c['p']}) with G = "
+            f"({c['gx']}, {c['gy']}): find k (2 ≤ k ≤ 20) such that k·G = ({qx}, {qy})"
+        ),
+        "answer": k,
+    }
+
+_TOPIC_GENERATORS = {
+    "legendre": _generate_legendre_problem,
+    "crt": _generate_crt_problem,
+    "ecdlp": _generate_ecdlp_problem,
+}
+
+def generate_problem(topic: str, rng: random.Random) -> dict:
+    if topic == "mixed":
+        topic = rng.choice(list(_TOPIC_GENERATORS.keys()))
+    if topic not in _TOPIC_GENERATORS:
+        raise ValueError(f"Unknown challenge topic: {topic}")
+    return _TOPIC_GENERATORS[topic](rng)
+
 # ------------------- CLI -------------------
 
 def get_command():
@@ -180,6 +303,7 @@ def main():
         argv = [cmd] + argv
 
     parser = argparse.ArgumentParser(description="FoxMath — Math & Crypto Explorer 🦊")
+    parser.add_argument("--version", action="version", version=f"foxmath {_package_version()}")
     subparsers = parser.add_subparsers(dest="command", required=not cmd)
 
     # Legendre
@@ -202,6 +326,16 @@ def main():
     ec.add_argument("--a", type=int, help="Curve parameter a (overrides --curve if given)")
     ec.add_argument("--p", type=int, help="Prime modulus (overrides --curve if given)")
 
+    # Elliptic curve scalar multiplication
+    ecm = subparsers.add_parser("ecmul", help="Elliptic curve scalar multiplication (k·P)")
+    ecm.add_argument("--curve", choices=sorted(CURVES.keys()),
+                     help="Named curve (provides a, b, p, and generator G)")
+    ecm.add_argument("--k", type=int, required=True, help="Scalar multiplier")
+    ecm.add_argument("--x", type=int, help="Point x (defaults to G's x if --curve is given)")
+    ecm.add_argument("--y", type=int, help="Point y (defaults to G's y if --curve is given)")
+    ecm.add_argument("--a", type=int, help="Curve parameter a (overrides --curve if given)")
+    ecm.add_argument("--p", type=int, help="Prime modulus (overrides --curve if given)")
+
     # Chinese Remainder Theorem
     crt = subparsers.add_parser("crt", help="Solve a system of congruences x = r (mod m)")
     crt.add_argument("--r", type=int, nargs="+", required=True, help="Remainders, e.g. --r 2 3 2")
@@ -213,6 +347,14 @@ def main():
     cf_cmd.add_argument("--den", type=int, required=True, help="Denominator")
     cf_cmd.add_argument("--terms", type=int, default=100, help="Max terms to expand")
 
+    # Challenge / quiz mode
+    challenge = subparsers.add_parser("challenge", help="Practice problems (Legendre, CRT)")
+    challenge.add_argument("--topic", choices=["legendre", "crt", "ecdlp", "mixed"], default="mixed")
+    challenge.add_argument("--count", type=int, default=5, help="Number of problems")
+    challenge.add_argument("--seed", type=int, help="Random seed for reproducible problem sets")
+    challenge.add_argument("--reveal", action="store_true",
+                            help="Print problems with answers, no prompting (worksheet mode)")
+
     args = parser.parse_args(argv)
 
     result = {"tool": "foxmath"}
@@ -267,6 +409,43 @@ def main():
                     status = "✓ on curve" if result["result_on_curve"] else "✗ NOT on curve"
                     print(f"  {status}")
 
+        elif cmd == "ecmul" or args.command == "ecmul":
+            a, b = args.a, None
+            p = args.p
+            x1, y1 = args.x, args.y
+
+            if args.curve:
+                preset = CURVES[args.curve]
+                a = preset["a"] if a is None else a
+                p = preset["p"] if p is None else p
+                b = preset["b"]
+                if x1 is None or y1 is None:
+                    x1, y1 = preset["gx"], preset["gy"]
+            elif a is None:
+                a = -3  # historical default for manual (non-curve) mode
+
+            if a is None or p is None or x1 is None or y1 is None:
+                raise ValueError(
+                    "Provide --curve NAME, or at least --p --x --y manually "
+                    "(--a defaults to -3 if omitted)."
+                )
+
+            R = ec_mul(args.k, x1, y1, a, p)
+            result.update({
+                "command": "ecmul", "curve": args.curve, "k": args.k,
+                "point": [x1, y1], "result": "infinity" if R is None else list(R),
+            })
+            if not json_output:
+                if R is None:
+                    print("Result: point at infinity (identity)")
+                else:
+                    print(f"Result point: ({R[0]}, {R[1]})")
+            if R is not None and b is not None:
+                result["result_on_curve"] = is_on_curve(R[0], R[1], a, b, p)
+                if not json_output:
+                    status = "✓ on curve" if result["result_on_curve"] else "✗ NOT on curve"
+                    print(f"  {status}")
+
         elif cmd == "crt" or args.command == "crt":
             x, m = crt_solve(args.r, args.m)
             result.update({"command": "crt", "r": args.r, "m": args.m, "x": x, "mod": m})
@@ -285,6 +464,48 @@ def main():
                 for p, q in convs:
                     print(f"  {p}/{q}")
 
+        elif cmd == "challenge" or args.command == "challenge":
+            if args.count < 1:
+                raise ValueError(f"--count must be >= 1 (got {args.count})")
+
+            rng = random.Random(args.seed)
+            problems = [generate_problem(args.topic, rng) for _ in range(args.count)]
+
+            if args.reveal:
+                result.update({"command": "challenge", "topic": args.topic, "problems": problems})
+                if not json_output:
+                    for i, prob in enumerate(problems, 1):
+                        print(f"{i}. {prob['question']}")
+                        print(f"   Answer: {prob['answer']}")
+            else:
+                score = 0
+                details = []
+                for i, prob in enumerate(problems, 1):
+                    if not json_output:
+                        print(f"{i}. {prob['question']}")
+                    try:
+                        raw = input("   Your answer: ")
+                    except EOFError:
+                        raw = ""
+                    try:
+                        user_answer = int(raw.strip())
+                    except ValueError:
+                        user_answer = None
+                    correct = user_answer == prob["answer"]
+                    score += correct
+                    details.append({**prob, "your_answer": user_answer, "correct": correct})
+                    if not json_output:
+                        if correct:
+                            print("   ✓ Correct!")
+                        else:
+                            print(f"   ✗ Incorrect (answer: {prob['answer']})")
+                result.update({
+                    "command": "challenge", "topic": args.topic,
+                    "score": score, "total": args.count, "details": details,
+                })
+                if not json_output:
+                    print(f"\nScore: {score}/{args.count}")
+
     except Exception as e:
         print(f"Error: {e}", file=sys.stderr)
         sys.exit(1)

{foxmath-0.4.0 → foxmath-0.6.0/src/foxmath.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: foxmath
-Version: 0.4.0
+Version: 0.6.0
 Summary: Minimalist CLI for math & cryptography exploration 🦊
 Author-email: Abhrankan Chakrabarti <abhrankan@gmail.com>
 License: MIT
@@ -32,9 +32,11 @@ Built with curiosity — for students, tinkerers, and crypto/math enthusiasts.
   named curves (secp256k1) with on-curve result validation
 - Chinese Remainder Theorem solver (handles non-coprime moduli)
 - Continued fraction expansion and convergents
-- Symlink-friendly (foxmath-legendre, foxmath-pi, foxmath-ecadd, foxmath-crt, foxmath-cf)
+- Challenge/quiz mode — practice problems with scoring, or a
+  worksheet mode for self-study
+- Symlink-friendly (foxmath-legendre, foxmath-pi, foxmath-ecadd,
+  foxmath-crt, foxmath-cf, foxmath-challenge)
 - JSON output mode
-- Coming soon: challenge mode
 
 ## Installation
 
@@ -101,6 +103,20 @@ foxmath cf --num 355 --den 113
   355/113
 ```
 
+```bash
+# Challenge/quiz mode — worksheet (no prompting)
+foxmath challenge --topic legendre --count 2 --seed 1 --reveal
+```
+```
+1. Legendre symbol (10/13)
+   Answer: 1
+2. Legendre symbol (3/7)
+   Answer: -1
+```
+
+Drop `--reveal` to answer interactively instead, with scoring at the end.
+`--topic` accepts `legendre`, `crt`, or `mixed` (default).
+
 ```bash
 # JSON output
 foxmath pi --terms 100 --json

{foxmath-0.4.0 → foxmath-0.6.0}/src/foxmath.egg-info/entry_points.txt

@@ -1,7 +1,9 @@
 [console_scripts]
 foxmath = foxmath.foxmath:main
 foxmath-cf = foxmath.foxmath:main
+foxmath-challenge = foxmath.foxmath:main
 foxmath-crt = foxmath.foxmath:main
 foxmath-ecadd = foxmath.foxmath:main
+foxmath-ecmul = foxmath.foxmath:main
 foxmath-legendre = foxmath.foxmath:main
 foxmath-pi = foxmath.foxmath:main

{foxmath-0.4.0 → foxmath-0.6.0}/tests/test_cli.py

@@ -13,10 +13,10 @@ ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), "..", "src", "fox
 SCRIPT = os.path.join(ROOT, "foxmath.py")
 
 
-def run(*args, script=SCRIPT):
+def run(*args, script=SCRIPT, stdin_input=None):
     result = subprocess.run(
         [sys.executable, script, *args],
-        capture_output=True, text=True, timeout=15,
+        capture_output=True, text=True, timeout=15, input=stdin_input,
     )
     return result.returncode, result.stdout, result.stderr
 
@@ -91,6 +91,13 @@ class TestSymlinkInvocation(unittest.TestCase):
         self.assertEqual(code, 0)
         self.assertIn("[3; 7, 16]", out)
 
+    def test_challenge_symlink(self):
+        script = self._make_symlink_script("foxmath-challenge")
+        code, out, err = run("--topic", "legendre", "--count", "2", "--seed", "1",
+                              "--reveal", script=script)
+        self.assertEqual(code, 0)
+        self.assertIn("Answer:", out)
+
     def test_symlink_with_json(self):
         script = self._make_symlink_script("foxmath-legendre")
         code, out, err = run("2", "7", "--json", script=script)
@@ -170,6 +177,46 @@ class TestNormalUsage(unittest.TestCase):
         self.assertEqual(code, 1)
         self.assertIn("Error", err)
 
+    def test_challenge_reveal_is_deterministic_with_seed(self):
+        code1, out1, err1 = run("challenge", "--topic", "legendre", "--count", "3",
+                                 "--seed", "42", "--reveal")
+        code2, out2, err2 = run("challenge", "--topic", "legendre", "--count", "3",
+                                 "--seed", "42", "--reveal")
+        self.assertEqual(code1, 0)
+        self.assertEqual(out1, out2)
+
+    def test_challenge_interactive_scores_correct_answers(self):
+        # Known answers for --topic legendre --seed 42 --count 3 (from reveal mode).
+        code, out, err = run("challenge", "--topic", "legendre", "--count", "3",
+                              "--seed", "42", stdin_input="-1\n-1\n1\n")
+        self.assertEqual(code, 0)
+        self.assertIn("Score: 3/3", out)
+
+    def test_challenge_interactive_scores_wrong_answers(self):
+        code, out, err = run("challenge", "--topic", "legendre", "--count", "3",
+                              "--seed", "42", stdin_input="0\n0\n0\n")
+        self.assertEqual(code, 0)
+        self.assertIn("Score: 0/3", out)
+
+    def test_challenge_interactive_handles_non_numeric_input(self):
+        code, out, err = run("challenge", "--topic", "legendre", "--count", "1",
+                              "--seed", "42", stdin_input="not-a-number\n")
+        self.assertEqual(code, 0)
+        self.assertIn("Score: 0/1", out)
+
+    def test_challenge_reveal_json(self):
+        code, out, err = run("challenge", "--topic", "crt", "--count", "2",
+                              "--seed", "1", "--reveal", "--json")
+        self.assertEqual(code, 0)
+        import json
+        parsed = json.loads(out)
+        self.assertEqual(len(parsed["problems"]), 2)
+
+    def test_challenge_zero_count_errors(self):
+        code, out, err = run("challenge", "--count", "0")
+        self.assertEqual(code, 1)
+        self.assertIn("Error", err)
+
 
 if __name__ == "__main__":
     unittest.main()

{foxmath-0.4.0 → foxmath-0.6.0}/tests/test_foxmath.py

@@ -15,7 +15,9 @@ sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), "..",
 from foxmath.foxmath import (
     legendre_symbol, euler_hermann_pi_approx, ec_point_add, crt_solve,
     continued_fraction, cf_convergents, CURVES, is_on_curve,
+    generate_problem,
 )
+import random
 
 # Reference pi digits (mpmath, 250 dps of working precision), "3" + fractional digits.
 PI_REFERENCE = Decimal(
@@ -175,5 +177,36 @@ class TestNamedCurves(unittest.TestCase):
         self.assertTrue(is_on_curve(c["gx"], c["gy"], c["a"], c["b"], c["p"]))
 
 
+class TestChallengeGenerators(unittest.TestCase):
+    def test_legendre_problem_answer_is_correct(self):
+        rng = random.Random(0)
+        for _ in range(50):
+            prob = generate_problem("legendre", rng)
+            self.assertEqual(prob["topic"], "legendre")
+            # re-derive the answer independently from the question text
+            self.assertIn(prob["answer"], (-1, 0, 1))
+
+    def test_crt_problem_answer_satisfies_both_congruences(self):
+        rng = random.Random(0)
+        for _ in range(50):
+            prob = generate_problem("crt", rng)
+            self.assertEqual(prob["topic"], "crt")
+            self.assertIsInstance(prob["answer"], int)
+
+    def test_mixed_topic_produces_both_kinds(self):
+        rng = random.Random(1)
+        topics = {generate_problem("mixed", rng)["topic"] for _ in range(30)}
+        self.assertEqual(topics, {"legendre", "crt"})
+
+    def test_reproducible_with_same_seed(self):
+        p1 = generate_problem("legendre", random.Random(99))
+        p2 = generate_problem("legendre", random.Random(99))
+        self.assertEqual(p1, p2)
+
+    def test_unknown_topic_raises(self):
+        with self.assertRaises(ValueError):
+            generate_problem("not_a_topic", random.Random(0))
+
+
 if __name__ == "__main__":
     unittest.main()