osl-edu-math 0.2.1__tar.gz

osl_edu_math-0.2.1/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Open Science Labs Incubator
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

osl_edu_math-0.2.1/PKG-INFO

@@ -0,0 +1,86 @@
+Metadata-Version: 2.4
+Name: osl-edu-math
+Version: 0.2.1
+Summary: Python tools for math education workflows.
+License-Expression: BSD-3-Clause
+License-File: LICENSE
+Keywords: education,math,python,open-science
+Author: Open Science Labs Incubator
+Requires-Python: >=3.10,<4
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Education
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Provides-Extra: dev
+Provides-Extra: docs
+Requires-Dist: ipython (>=7)
+Requires-Dist: ipywidgets (>=6)
+Requires-Dist: makim (==1.29.0) ; extra == "dev"
+Requires-Dist: matplotlib (>=2)
+Requires-Dist: mypy (>=1.10) ; extra == "dev"
+Requires-Dist: numpy (>=2)
+Requires-Dist: pre-commit (>=3) ; extra == "dev"
+Requires-Dist: pytest (>=8) ; extra == "dev"
+Requires-Dist: pytest-cov (>=5) ; extra == "dev"
+Requires-Dist: ruff (>=0.6) ; extra == "dev"
+Requires-Dist: sympy (>=1)
+Project-URL: Documentation, https://osl-incubator.github.io/edu-math/
+Project-URL: Homepage, https://github.com/osl-incubator/edu-math
+Project-URL: Issues, https://github.com/osl-incubator/edu-math/issues
+Project-URL: Repository, https://github.com/osl-incubator/edu-math
+Description-Content-Type: text/markdown
+
+# edu-math
+
+![CI](https://img.shields.io/github/actions/workflow/status/osl-incubator/edu-math/ci.yml?logo=github&label=CI)
+[![Python Versions](https://img.shields.io/pypi/pyversions/osl-edu-math)](https://pypi.org/project/osl-edu-math/)
+[![Package Version](https://img.shields.io/pypi/v/osl-edu-math?color=blue)](https://pypi.org/project/osl-edu-math/)
+![License](https://img.shields.io/pypi/l/osl-edu-math?color=blue)
+
+`edu-math` is a Python package for math education workflows.
+
+The PyPI distribution is `osl-edu-math`; the import package remains `edumath`.
+
+The project is in its initial scaffold stage. The repository includes packaging,
+testing, linting, documentation, release automation, and GitHub workflow
+infrastructure adapted from the Open Science Labs Incubator Python package
+template used by `prisma-flow`.
+
+## Installation
+
+```bash
+pip install osl-edu-math
+```
+
+## Development
+
+```bash
+conda env create -f conda/dev.yaml
+conda activate edumath
+poetry config virtualenvs.create false
+poetry install --extras "dev"
+```
+
+Run checks through Makim:
+
+```bash
+makim tests.linter
+makim tests.unit
+makim package.build
+makim docs.build
+```
+
+## Project layout
+
+- `src/edumath/`: Python package source
+- `tests/`: pytest test suite
+- `docs/`: Quarto documentation website
+- `conda/`: development and release environment files
+- `.github/`: issue templates and GitHub Actions workflows
+

osl_edu_math-0.2.1/README.md

@@ -0,0 +1,47 @@
+# edu-math
+
+![CI](https://img.shields.io/github/actions/workflow/status/osl-incubator/edu-math/ci.yml?logo=github&label=CI)
+[![Python Versions](https://img.shields.io/pypi/pyversions/osl-edu-math)](https://pypi.org/project/osl-edu-math/)
+[![Package Version](https://img.shields.io/pypi/v/osl-edu-math?color=blue)](https://pypi.org/project/osl-edu-math/)
+![License](https://img.shields.io/pypi/l/osl-edu-math?color=blue)
+
+`edu-math` is a Python package for math education workflows.
+
+The PyPI distribution is `osl-edu-math`; the import package remains `edumath`.
+
+The project is in its initial scaffold stage. The repository includes packaging,
+testing, linting, documentation, release automation, and GitHub workflow
+infrastructure adapted from the Open Science Labs Incubator Python package
+template used by `prisma-flow`.
+
+## Installation
+
+```bash
+pip install osl-edu-math
+```
+
+## Development
+
+```bash
+conda env create -f conda/dev.yaml
+conda activate edumath
+poetry config virtualenvs.create false
+poetry install --extras "dev"
+```
+
+Run checks through Makim:
+
+```bash
+makim tests.linter
+makim tests.unit
+makim package.build
+makim docs.build
+```
+
+## Project layout
+
+- `src/edumath/`: Python package source
+- `tests/`: pytest test suite
+- `docs/`: Quarto documentation website
+- `conda/`: development and release environment files
+- `.github/`: issue templates and GitHub Actions workflows

osl_edu_math-0.2.1/pyproject.toml

@@ -0,0 +1,119 @@
+[project]
+name = "osl-edu-math"
+version = "0.2.1"  # semantic-release
+description = "Python tools for math education workflows."
+readme = "README.md"
+requires-python = ">=3.10,<4"
+license = "BSD-3-Clause"
+authors = [
+  { name = "Open Science Labs Incubator" }
+]
+keywords = [
+  "education",
+  "math",
+  "python",
+  "open-science",
+]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Education",
+  "Intended Audience :: Science/Research",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Education",
+  "Topic :: Scientific/Engineering :: Mathematics",
+]
+dependencies = [
+  "matplotlib>=2",
+  "numpy>=2",
+  "ipywidgets>=6",
+  "ipython>=7",
+  "sympy>=1"
+]
+
+[project.urls]
+Homepage = "https://github.com/osl-incubator/edu-math"
+Repository = "https://github.com/osl-incubator/edu-math"
+Issues = "https://github.com/osl-incubator/edu-math/issues"
+Documentation = "https://osl-incubator.github.io/edu-math/"
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8",
+  "pytest-cov>=5",
+  "ruff>=0.6",
+  "mypy>=1.10",
+  "pre-commit>=3",
+  "makim==1.29.0",
+]
+docs = []
+
+[tool.poetry.group.dev.dependencies]
+quarto-cli = ">=1.9.0"
+pytest = ">=8"
+pytest-cov = ">=5"
+ruff = ">=0.6"
+mypy = ">=1.10"
+pre-commit = ">=3"
+makim = "==1.29.0"
+click = "^8.4.1"
+
+[build-system]
+requires = ["poetry-core>=2"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.poetry]
+packages = [
+  { include = "edumath", from = "src" },
+]
+include = [
+  "src/edumath/py.typed",
+]
+
+[tool.ruff]
+line-length = 88
+target-version = "py310"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = [
+  "E",
+  "F",
+  "I",
+  "UP",
+  "B",
+  "RUF",
+]
+ignore = [
+  "D203",
+  "D213",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["D"]
+
+[tool.ruff.format]
+quote-style = "double"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra"
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+warn_unused_ignores = true
+warn_redundant_casts = true
+warn_unused_configs = true
+show_error_codes = true
+
+[[tool.mypy.overrides]]
+module = [
+  "IPython.*",
+  "ipywidgets.*",
+  "sympy.*",
+]
+ignore_missing_imports = true

osl_edu_math-0.2.1/src/edumath/__init__.py

@@ -0,0 +1,5 @@
+"""Public package interface for edu-math."""
+
+__version__ = "0.2.1"  # semantic-release
+
+__all__ = ["__version__"]

osl_edu_math-0.2.1/src/edumath/algebra/__init__.py

@@ -0,0 +1,34 @@
+"""Algebra learning tools."""
+
+from edumath.algebra.concepts import COLLEGE_ALGEBRA_PATH
+from edumath.algebra.exercises import (
+    expand_expression_exercise,
+    linear_equation_exercise,
+)
+from edumath.algebra.plots import compare_functions_scene, function_scene
+from edumath.algebra.quizes import (
+    GuessingQuiz,
+    GuessingQuizWidget,
+    GuessQuestion,
+    GuessResult,
+    SympyGuessGame,
+)
+from edumath.algebra.validators import (
+    validate_expression_equivalence,
+    validate_numeric_solution,
+)
+
+__all__ = [
+    "COLLEGE_ALGEBRA_PATH",
+    "GuessQuestion",
+    "GuessResult",
+    "GuessingQuiz",
+    "GuessingQuizWidget",
+    "SympyGuessGame",
+    "compare_functions_scene",
+    "expand_expression_exercise",
+    "function_scene",
+    "linear_equation_exercise",
+    "validate_expression_equivalence",
+    "validate_numeric_solution",
+]

osl_edu_math-0.2.1/src/edumath/algebra/concepts.py

@@ -0,0 +1,131 @@
+"""College algebra concept metadata."""
+
+from __future__ import annotations
+
+from edumath.core import LearningObjective, Lesson, LessonSection, StudyPath
+
+EXPRESSIONS_AND_EQUATIONS = Lesson(
+    title="Expressions and equations",
+    slug="expressions-and-equations",
+    objectives=(
+        LearningObjective("Distinguish expressions from equations."),
+        LearningObjective("Evaluate algebraic expressions by substitution."),
+        LearningObjective("Solve one-variable linear equations."),
+    ),
+    sections=(
+        LessonSection(
+            title="Expressions",
+            body=(
+                "An expression is a mathematical phrase that can be simplified "
+                "or evaluated, such as 3*x + 2."
+            ),
+        ),
+        LessonSection(
+            title="Equations",
+            body=(
+                "An equation states that two expressions are equal. Solving an "
+                "equation means finding values that make the statement true."
+            ),
+        ),
+    ),
+    tags=("algebra", "equations"),
+)
+
+FUNCTIONS_AND_GRAPHS = Lesson(
+    title="Functions and graphs",
+    slug="functions-and-graphs",
+    objectives=(
+        LearningObjective("Interpret a function as an input-output rule."),
+        LearningObjective("Identify slope, intercepts, domain, and range."),
+        LearningObjective("Connect symbolic functions to their graphs."),
+    ),
+    sections=(
+        LessonSection(
+            title="Functions",
+            body="A function assigns each input exactly one output.",
+        ),
+        LessonSection(
+            title="Graphs",
+            body=("A graph shows the ordered pairs (x, f(x)) produced by a function."),
+        ),
+    ),
+    tags=("algebra", "functions", "graphs"),
+)
+
+POLYNOMIALS = Lesson(
+    title="Polynomials",
+    slug="polynomials",
+    objectives=(
+        LearningObjective("Recognize polynomial degree and leading coefficient."),
+        LearningObjective("Factor common polynomial forms."),
+        LearningObjective("Use roots to interpret polynomial graphs."),
+    ),
+    sections=(
+        LessonSection(
+            title="Polynomial structure",
+            body=(
+                "A polynomial is a sum of constant multiples of non-negative "
+                "integer powers of a variable."
+            ),
+        ),
+    ),
+    tags=("algebra", "polynomials"),
+)
+
+EXPONENTIALS_AND_LOGARITHMS = Lesson(
+    title="Exponentials and logarithms",
+    slug="exponentials-and-logarithms",
+    objectives=(
+        LearningObjective("Recognize exponential growth and decay."),
+        LearningObjective("Use logarithms as inverse operations for exponentials."),
+        LearningObjective("Solve basic exponential and logarithmic equations."),
+    ),
+    sections=(
+        LessonSection(
+            title="Inverse relationship",
+            body="A logarithm answers the question: what exponent produced this value?",
+        ),
+    ),
+    tags=("algebra", "exponentials", "logarithms"),
+)
+
+SYSTEMS_OF_EQUATIONS = Lesson(
+    title="Systems of equations",
+    slug="systems-of-equations",
+    objectives=(
+        LearningObjective("Interpret a solution as a point satisfying all equations."),
+        LearningObjective("Solve small linear systems by substitution or elimination."),
+        LearningObjective("Connect systems to line intersections."),
+    ),
+    sections=(
+        LessonSection(
+            title="Shared solutions",
+            body=(
+                "A system asks for values that make every equation true at the "
+                "same time."
+            ),
+        ),
+    ),
+    tags=("algebra", "systems"),
+)
+
+COLLEGE_ALGEBRA_PATH = StudyPath(
+    title="College Algebra",
+    lessons=(
+        EXPRESSIONS_AND_EQUATIONS,
+        FUNCTIONS_AND_GRAPHS,
+        POLYNOMIALS,
+        EXPONENTIALS_AND_LOGARITHMS,
+        SYSTEMS_OF_EQUATIONS,
+    ),
+)
+
+
+__all__ = [
+    "COLLEGE_ALGEBRA_PATH",
+    "EXPONENTIALS_AND_LOGARITHMS",
+    "EXPRESSIONS_AND_EQUATIONS",
+    "FUNCTIONS_AND_GRAPHS",
+    "POLYNOMIALS",
+    "SYSTEMS_OF_EQUATIONS",
+]

osl_edu_math-0.2.1/src/edumath/algebra/exercises.py

@@ -0,0 +1,81 @@
+"""College algebra exercise builders."""
+
+from __future__ import annotations
+
+from random import Random
+from typing import SupportsFloat, cast
+
+import sympy as sp
+
+from edumath.core import (
+    AnswerCheck,
+    Exercise,
+    check_expression_answer,
+    check_numeric_answer,
+)
+
+
+def linear_equation_exercise(
+    *,
+    seed: int | None = None,
+) -> Exercise:
+    """Generate a one-variable linear equation exercise."""
+
+    rng = Random(seed)
+    x = sp.Symbol("x")
+    solution = rng.randint(-8, 8)
+    coefficient = _nonzero_int(rng, -6, 6)
+    constant = rng.randint(-10, 10)
+    equation = sp.Eq(coefficient * x + constant, coefficient * solution + constant)
+    expected = float(solution)
+
+    def validator(received: object) -> AnswerCheck:
+        return check_numeric_answer(float(cast(SupportsFloat, received)), expected)
+
+    return Exercise(
+        prompt=f"Solve for x: {sp.sstr(equation)}",
+        expected=expected,
+        validator=validator,
+        explanation=(
+            "Undo the addition/subtraction first, then divide by the coefficient of x."
+        ),
+        tags=("algebra", "linear-equations"),
+    )
+
+
+def expand_expression_exercise(
+    *,
+    seed: int | None = None,
+) -> Exercise:
+    """Generate a polynomial expansion exercise."""
+
+    rng = Random(seed)
+    x = sp.Symbol("x")
+    a = _nonzero_int(rng, -5, 5)
+    b = rng.randint(-6, 6)
+    expression = (x + a) * (x + b)
+    expected = sp.expand(expression)
+
+    return Exercise(
+        prompt=f"Expand: {sp.sstr(expression)}",
+        expected=expected,
+        validator=lambda received: check_expression_answer(
+            str(received),
+            expected,
+        ),
+        explanation=(
+            "Use distribution: multiply each term in the first factor by each "
+            "term in the second."
+        ),
+        tags=("algebra", "polynomials"),
+    )
+
+
+def _nonzero_int(rng: Random, start: int, stop: int) -> int:
+    value = 0
+    while value == 0:
+        value = rng.randint(start, stop)
+    return value
+
+
+__all__ = ["expand_expression_exercise", "linear_equation_exercise"]

osl_edu_math-0.2.1/src/edumath/algebra/plots.py

@@ -0,0 +1,76 @@
+"""College algebra plotting helpers."""
+
+from __future__ import annotations
+
+import sympy as sp
+
+from edumath.core import (
+    ExplicitFunction2D,
+    PlotRange,
+    PlotScene2D,
+    PlotStyle,
+    Viewport2D,
+)
+
+
+def function_scene(
+    expression: str | sp.Expr,
+    *,
+    x_min: float = -10,
+    x_max: float = 10,
+    y_min: float = -10,
+    y_max: float = 10,
+    title: str | None = None,
+    color: str = "#1a73e8",
+) -> PlotScene2D:
+    """Create a reusable scene for a single algebraic function."""
+
+    return PlotScene2D(
+        elements=(
+            ExplicitFunction2D(
+                expression,
+                domain=PlotRange(x_min, x_max),
+                style=PlotStyle(color=color, label=f"y = {expression}"),
+            ),
+        ),
+        viewport=Viewport2D(
+            x=PlotRange(x_min, x_max),
+            y=PlotRange(y_min, y_max),
+        ),
+        title=title or f"y = {expression}",
+    )
+
+
+def compare_functions_scene(
+    expressions: tuple[str | sp.Expr, ...],
+    *,
+    x_min: float = -10,
+    x_max: float = 10,
+    y_min: float = -10,
+    y_max: float = 10,
+    title: str = "Function comparison",
+) -> PlotScene2D:
+    """Create a scene comparing several functions."""
+
+    colors = ("#1a73e8", "#d93025", "#137333", "#9334e6")
+    return PlotScene2D(
+        elements=tuple(
+            ExplicitFunction2D(
+                expression,
+                domain=PlotRange(x_min, x_max),
+                style=PlotStyle(
+                    color=colors[index % len(colors)],
+                    label=f"y = {expression}",
+                ),
+            )
+            for index, expression in enumerate(expressions)
+        ),
+        viewport=Viewport2D(
+            x=PlotRange(x_min, x_max),
+            y=PlotRange(y_min, y_max),
+        ),
+        title=title,
+    )
+
+
+__all__ = ["compare_functions_scene", "function_scene"]