Metadata-Version: 2.3
Name: mathstore
Version: 0.1.0
Summary: A clean, modular mathematical toolkit.
Keywords: math,calculus,linear-algebra,statistics,fastapi,education,active-recall,edtech,sympy,cli
Author: mark
Author-email: mark <munenevictor577@gmail.com>
License: MIT
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Education
Requires-Dist: fastapi>=0.141.1
Requires-Dist: numpy>=2.5.3
Requires-Dist: pydantic>=2.13.5
Requires-Dist: sympy>=1.14.0
Requires-Dist: uvicorn[standard]>=0.53.0
Requires-Python: >=3.12
Project-URL: Homepage, https://github.com/munenevictor577-blip/mathstore
Project-URL: Documentation, https://github.com/munenevictor577-blip/mathstore#readme
Project-URL: Repository, https://github.com/munenevictor577-blip/mathstore
Project-URL: Issues, https://github.com/munenevictor577-blip/mathstore/issues
Project-URL: Changelog, https://github.com/munenevictor577-blip/mathstore/blob/main/RELEASE_NOTES.md
Description-Content-Type: text/markdown

# MathStore 🎓

[![Tests](https://img.shields.io/badge/tests-257%20passed-success)](https://github.com/munenevictor577-blip/mathstore)
[![Coverage](https://img.shields.io/badge/coverage-91%25-brightgreen)](https://github.com/munenevictor577-blip/mathstore)
[![Python](https://img.shields.io/badge/python-3.12%2B-blue)](https://python.org)
[![Code Style: Ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)

**MathStore** is a clean, modular mathematical toolkit and interactive CLI designed for university students, educators, and STEM practitioners. It covers **symbolic calculus**, **step-by-step derivations**, **linear algebra**, **probability & statistics**, **formula cheat sheets**, and an **active-recall practice quizzer**.

---

## Table of Contents

- [Installation & Setup](#installation--setup)
- [Command-Line Interface (CLI)](#command-line-interface-cli)
  - [Step-by-Step Derivations (`--steps`)](#1-step-by-step-derivations---steps)
  - [Active-Recall Practice Quizzer (`mathstore practice`)](#2-active-recall-practice-quizzer-mathstore-practice)
  - [Calculus & Limits (`diff`, `integrate`, `limit`)](#3-calculus--limits-diff-integrate-limit)
  - [Linear Algebra (`matrix`)](#4-linear-algebra-matrix)
  - [Statistics & Hypothesis Testing (`stats`)](#5-statistics--hypothesis-testing-stats)
  - [Formula Reference Cheat Sheets (`ref`)](#6-formula-reference-cheat-sheets-ref)
- [FastAPI Remote Server (`/math`)](#fastapi-remote-server-math)
  - [Starting the Server](#starting-the-server)
  - [API Endpoints Overview](#api-endpoints-overview)
  - [cURL Examples](#curl-examples)
- [Python Library Usage](#python-library-usage)
  - [Calculus & Derivations](#calculus--derivations)
  - [Equation Solving](#equation-solving)
  - [Matrix Analysis](#matrix-analysis)
  - [Statistics & Inference](#statistics--inference)
  - [Practice & Revision API](#practice--revision-api)
- [Project Architecture](#project-architecture)
- [Development & Testing](#development--testing)

---

## Installation & Setup

### Prerequisites

- Python 3.12 or newer
- [`uv`](https://github.com/astral-sh/uv) (recommended) or `pip`

### Install with `uv`

```bash
# Clone the repository
git clone https://github.com/munenevictor577-blip/mathstore.git
cd mathstore

# Sync virtual environment and dependencies
uv sync

# Run the CLI directly
uv run mathstore --help
```

### Install with `pip`

```bash
pip install -e .
mathstore --help
```

---

## Command-Line Interface (CLI)

### 1. Step-by-Step Derivations (`--steps`)

Add the `--steps` flag to `diff`, `integrate`, or `solve` to view full human-readable derivation trees explaining each mathematical rule applied.

```bash
# Step-by-step differentiation (Sum, Product, Quotient, Chain & Power rules)
mathstore diff "x**2 * sin(x)" --steps

# Multi-order differentiation breakdown
mathstore diff "x**3" --order 2 --steps

# Step-by-step integration (Substitution, Parts, Power, Trig forms)
mathstore integrate "x * exp(x)" --steps

# Definite integration with Fundamental Theorem of Calculus (FTC) evaluation
mathstore integrate "x**2" --limits 0 2 --steps

# Step-by-step linear and quadratic equation solving
mathstore solve "2*x + 4 = 10" --steps
mathstore solve "x**2 - 5*x + 6 = 0" --steps
```

**Example output for `mathstore diff "x**2 \* sin(x)" --steps`:\*\*

```text
Step-by-step differentiation of x**2 * sin(x):
  1. Apply Product Rule to (x**2*sin(x)): (u*v)' = u'*v + u*v' with u = x**2, v = sin(x)
  2.   Differentiate u = x**2: Apply Power Rule: d/dx[x^2] = 2*x^1 = 2*x
  3.   Differentiate v = sin(x): Standard derivative of sin(x): cos(x)
  4. Substitute into product formula: (2*x)*(sin(x)) + (x**2)*(cos(x)) = x*(x*cos(x) + 2*sin(x))
Derivative (order 1): x**2*cos(x) + 2*x*sin(x)
```

---

### 2. Active-Recall Practice Quizzer (`mathstore practice`)

Interactive quizzer designed for exam preparation and active revision with randomized problems, hints, symbolic equivalence verification, and step-by-step solution reveals.

- **Topics**: `derivatives` (alias: `calc`, `diff`), `integrals` (alias: `int`), `algebra` (alias: `solve`), `matrix` (alias: `linalg`), `stats`, or `all`
- **Difficulties**: `easy`, `medium`, `hard`
- **Smart Equivalence**: Accepts standard math inputs (`^` or `**`, `+ C`, arbitrary constants, permuted products, multi-root sets e.g. `2, 3` or `[2, 3]`).

#### Interactive Mode

```bash
# Launch interactive 5-question session across all topics
mathstore practice

# Target specific subject and difficulty
mathstore practice derivatives --difficulty medium
mathstore practice matrix --difficulty hard -n 3
```

During an interactive quiz:

- Type your mathematical answer (e.g. `6*x**2`, `x^2/2 + C`, `2, 3`)
- Type `hint` for a formula clue
- Type `skip` to reveal the answer and step-by-step derivation
- Type `quit` to exit early with score summary

#### Non-Interactive Generation (`--generate` / `-g`)

Generate practice question cards with hints, answers, and solutions for problem sets or worksheets:

```bash
# Generate 3 practice problems with full solutions
mathstore practice --generate --topic algebra -n 3 --seed 42
```

---

### 3. Calculus & Limits (`diff`, `integrate`, `limit`)

```bash
# Differentiate expressions
mathstore diff "sin(x) * exp(x)"
mathstore diff "x**4" --order 3 --var x

# Indefinite integration
mathstore integrate "cos(x)"

# Definite integration with bounds [a, b]
mathstore integrate "x**2" --limits 0 3

# Compute limits
mathstore limit "sin(x)/x" 0
mathstore limit "1/x" oo
```

---

### 4. Linear Algebra (`mathstore matrix`)

Perform matrix operations by passing row-separated strings (`"1, 2; 3, 4"` or `"[[1, 2], [3, 4]]"`):

| Operation    | Command Example                             | Description                                     |
| ------------ | ------------------------------------------- | ----------------------------------------------- |
| `det`        | `mathstore matrix det "1, 2; 3, 4"`         | Determinant                                     |
| `inv`        | `mathstore matrix inv "1, 2; 3, 4"`         | Matrix Inverse                                  |
| `rref`       | `mathstore matrix rref "1, 2, -1; 2, 4, 3"` | Reduced Row Echelon Form                        |
| `eigen`      | `mathstore matrix eigen "2, 0; 0, 3"`       | Eigenvalues & algebraic multiplicities          |
| `eigenvects` | `mathstore matrix eigenvects "2, 0; 0, 3"`  | Eigenvectors & eigenspaces                      |
| `rank`       | `mathstore matrix rank "1, 2; 2, 4"`        | Matrix Rank                                     |
| `nullity`    | `mathstore matrix nullity "1, 2; 2, 4"`     | Dimension of null space                         |
| `trace`      | `mathstore matrix trace "5, 1; 2, 3"`       | Sum of diagonal entries                         |
| `transpose`  | `mathstore matrix transpose "1, 2; 3, 4"`   | Matrix Transpose                                |
| `charpoly`   | `mathstore matrix charpoly "1, 2; 3, 4"`    | Characteristic polynomial $\det(\lambda I - A)$ |

---

### 5. Statistics & Hypothesis Testing (`mathstore stats`)

```bash
# Five-number summary & distribution statistics (Mean, Median, Std, IQR, Skewness, Kurtosis)
mathstore stats summary "10, 12, 14, 15, 18, 20, 22"

# Normal distribution PDF, CDF, and z-score
mathstore stats normal 1.96 --mu 0 --sigma 1

# Binomial distribution PMF: P(X = k) and CDF: P(X <= k)
mathstore stats binomial 3 --n 10 --p 0.5

# Poisson distribution PMF & CDF
mathstore stats poisson 2 --lam 3.0

# Confidence Interval for sample mean
mathstore stats ci "22, 25, 27, 24, 26, 28" --confidence 0.95

# One-sample Student's t-test (two-sided, greater, or less)
mathstore stats ttest "10.2, 9.8, 10.5, 10.1, 9.9" --pop-mean 10.0 --alt two-sided
```

---

### 6. Formula Reference Cheat Sheets (`ref`)

Lookup high-yield formula cheat sheets directly in the terminal:

```bash
# List all available reference cheat sheets
mathstore ref --list

# View specific cheat sheet
mathstore ref derivatives
mathstore ref integrals
mathstore ref trig
mathstore ref limits
mathstore ref series

# Export reference cheat sheet in LaTeX format
mathstore ref derivatives --latex
```

---

### 7. Formatting: LaTeX & Unicode (`--latex`, `--pretty`)

All analytical commands (`diff`, `integrate`, `limit`, `solve`, `matrix`, `stats`) support `--latex` and `--pretty` output flags for homework, lab reports, and LaTeX documents:

```bash
# LaTeX output for report insertion
mathstore diff "sin(x)/x" --latex
mathstore matrix inv "1, 2; 3, 4" --latex
mathstore stats summary "10, 12, 14, 15, 18" --latex

# Pretty Unicode formatting for clean terminal viewing
mathstore diff "x**3 + 2*x" --pretty
mathstore matrix rref "1, 2; 3, 4" --pretty
```

---

## FastAPI Remote Server (`/math`)

MathStore includes a production-ready FastAPI server with CORS support and OpenAPI documentation, enabling remote calling over HTTP from web applications, mobile clients, and microservices.

### Starting the Server

```bash
# Using uvicorn directly
uv run uvicorn mathstore.api.main:app --host 0.0.0.0 --port 8000

# Using the registered script command
uv run mathstore-server

# Or using the top-level api alias
uv run uvicorn api.main:app --host 0.0.0.0 --port 8000
```

- **Interactive Swagger UI**: [http://localhost:8000/math/docs](http://localhost:8000/math/docs)
- **ReDoc Documentation**: [http://localhost:8000/math/redoc](http://localhost:8000/math/redoc)
- **OpenAPI Schema**: [http://localhost:8000/math/openapi.json](http://localhost:8000/math/openapi.json)
- **Health Check**: [http://localhost:8000/math/health](http://localhost:8000/math/health)
- **API Index**: [http://localhost:8000/math](http://localhost:8000/math)

### API Endpoints Overview

All mathematical endpoints are mounted under the `/math` prefix (with `/api/v1/math` preserved for backward compatibility):

| Category | Method & Path | Description |
|---|---|---|
| **Calculus** | `POST, GET /math/diff` | Differentiate with optional steps & formatting |
| | `POST, GET /math/integrate` | Indefinite / definite integral with steps |
| | `POST, GET /math/limit` | Evaluate limits |
| **Algebra** | `POST, GET /math/solve` | Solve equations with optional steps |
| | `POST, GET /math/simplify` | Simplify expressions |
| **Matrix** | `POST /math/matrix/{operation}` | Matrix ops: `det`, `inv`, `rref`, `eigen`, `rank`, `trace`, etc. |
| **Statistics**| `POST /math/stats/summary` | Descriptive summary statistics |
| | `POST, GET /math/stats/normal` | Normal distribution PDF, CDF, z-score |
| | `POST, GET /math/stats/binomial`| Binomial PMF and CDF |
| | `POST, GET /math/stats/poisson` | Poisson PMF and CDF |
| | `POST /math/stats/ci` | Confidence intervals |
| | `POST /math/stats/ttest` | One-sample Student's t-test |
| **Steps** | `POST, GET /math/steps/diff` | Step-by-step differentiation |
| | `POST, GET /math/steps/integrate` | Step-by-step integration |
| | `POST, GET /math/steps/solve` | Step-by-step equation solving |
| **Practice** | `GET /math/practice/question` | Generate randomized revision question |
| | `POST /math/practice/check` | Validate answer with symbolic equivalence |
| **Reference**| `GET /math/ref` | List formula cheat sheet topics |
| | `GET /math/ref/{topic}` | Get cheat sheet (text or LaTeX) |
| **Health** | `GET /math/health` | Service health status |

### cURL Examples

```bash
# Differentiate with step-by-step breakdown
curl -X POST http://localhost:8000/math/diff \
  -H "Content-Type: application/json" \
  -d '{"expression": "x**2 * sin(x)", "steps": true}'

# Definite integration
curl -X POST http://localhost:8000/math/integrate \
  -H "Content-Type: application/json" \
  -d '{"expression": "x**2", "limits": [0, 2], "steps": true}'

# Solve an equation
curl -X POST http://localhost:8000/math/solve \
  -H "Content-Type: application/json" \
  -d '{"equation": "2*x + 4 = 10", "steps": true}'

# Calculate 2x2 matrix determinant
curl -X POST http://localhost:8000/math/matrix/det \
  -H "Content-Type: application/json" \
  -d '{"matrix": "1, 2; 3, 4"}'

# Normal distribution calculation
curl -X POST http://localhost:8000/math/stats/normal \
  -H "Content-Type: application/json" \
  -d '{"x": 1.96, "mu": 0, "sigma": 1}'

# Generate practice question
curl http://localhost:8000/math/practice/question?topic=derivatives
```

---

## Python Library Usage

MathStore is built as a modular Python library. You can import any analyzer, step generator, or quiz component directly into your scripts or Jupyter notebooks.

### Calculus & Derivations

```python
from mathstore.calculus import CalculusAnalyzer
from mathstore.study import get_derivative_steps, get_integral_steps

calc = CalculusAnalyzer()

# Basic differentiation and integration
deriv = calc.differentiate("x**2 * sin(x)", variable="x", order=1)
integral = calc.integrate("x * exp(x)", variable="x")
lim = calc.get_limit("sin(x)/x", limits=0, variable="x")

# Step-by-step differentiation breakdown
diff_steps = calc.differentiate_steps("x**2 * sin(x)", variable="x")
for step in diff_steps:
    print(step)

# Step-by-step definite integration with FTC evaluation
int_steps = calc.integrate_steps("x**2", variable="x", limits=(0, 2))
for step in int_steps:
    print(step)
```

### Equation Solving

```python
from mathstore.algebra import EquationSolver

solver = EquationSolver()

# Solve linear or quadratic equations
solutions = solver.solve_linear("x**2 - 5*x + 6 = 0", variable="x")
print("Roots:", solutions)  # [2, 3]

# Step-by-step derivation
steps = solver.solve_steps("2*x + 4 = 10", variable="x")
for step in steps:
    print(step)

# Format solution as LaTeX
latex_str = solver.format_solution(solutions, variable="x", format="latex")
print(latex_str)  # x \in \left\{ 2, 3 \right\}
```

### Matrix Analysis

```python
from mathstore.core import MatrixAnalyzer

matrix_analyzer = MatrixAnalyzer()
mat_str = "1, 2; 3, 4"

det = matrix_analyzer.determinant(mat_str)
inv = matrix_analyzer.inverse(mat_str)
rref_mat, pivots = matrix_analyzer.rref("1, 2, -1; 2, 4, 3")
eigenvalues = matrix_analyzer.eigenvalues("2, 0; 0, 3")
rank_val = matrix_analyzer.rank(mat_str)
trace_val = matrix_analyzer.trace(mat_str)

print("Det:", det)
print("Trace:", trace_val)
```

### Statistics & Inference

```python
from mathstore.statistics import StatsAnalyzer

stats = StatsAnalyzer()
data = [10.2, 11.5, 12.1, 9.8, 10.9, 11.2]

# Summary statistics dictionary
summary = stats.summary(data)
print("Mean:", summary["mean"], "Std Dev:", summary["std_dev"])

# Confidence interval
ci_lower, ci_upper, margin = stats.confidence_interval(data, confidence=0.95)
print(f"95% CI: [{ci_lower:.2f}, {ci_upper:.2f}] ± {margin:.2f}")

# Hypothesis testing (One-sample Student's t-test)
test_results = stats.one_sample_t_test(data, pop_mean=10.0, alternative="two-sided")
print(f"t-stat: {test_results['t_statistic']:.4f}, p-value: {test_results['p_value']:.4f}")
```

### Practice & Revision API

```python
from mathstore.study import (
    generate_question,
    check_answer,
    format_question_card,
    PracticeSession,
)

# Generate a randomized question with hint and steps
question = generate_question(topic="derivatives", difficulty="medium", seed=42)
print("Prompt:", question.prompt)
print("Hint:", question.hint)
print("Expected:", question.expected_answer)

# Verify a student's answer using symbolic equivalence
is_correct, feedback = check_answer("2*cos(2*x)", question)
print("Correct?", is_correct, "-", feedback)

# Format as printable problem card
print(format_question_card(question))

# Run an interactive practice session programmatically
session = PracticeSession(topic="all", count=5, difficulty="medium")
results = session.run()
print("Score:", results["percentage"], "%")
```

---

## Project Architecture

```text
mathstore/
├── pyproject.toml              # Build & dependency configuration
├── README.md                   # Documentation & usage guide
├── api/                        # Top-level API alias package
│   ├── __init__.py
│   └── main.py                 # uvicorn api.main:app entrypoint
├── src/mathstore/
│   ├── __init__.py             # Public top-level exports
│   ├── cli.py                  # Argparse CLI interface
│   ├── algebra/
│   │   └── solver.py           # Linear & polynomial equation solver
│   ├── api/
│   │   ├── __init__.py
│   │   ├── main.py             # FastAPI application & server runner
│   │   ├── schemas.py          # Pydantic request & response models
│   │   └── routes/             # Route modules (/math)
│   ├── calculus/
│   │   └── analyzer.py         # Differentiation, integration, and limits
│   ├── core/
│   │   └── matrix.py           # Matrix operations, RREF, eigenvalues
│   ├── reference/
│   │   └── sheets.py           # Formula cheat sheets (derivatives, trig, etc.)
│   ├── statistics/
│   │   └── analyzer.py         # Descriptive stats, distributions, CI, t-tests
│   └── study/
│       ├── steps.py            # Step-by-step derivation generators
│       └── practice.py         # Active-recall quizzer & answer verification
└── tests/                      # Pytest test suites (257 tests, 91% coverage)
    ├── test_algebra.py
    ├── test_api.py
    ├── test_calculus.py
    ├── test_cli.py
    ├── test_matrix.py
    ├── test_practice.py
    ├── test_reference.py
    ├── test_statistics.py
    └── test_steps.py
```

---

## Development & Testing

Run all unit tests, coverage reports, and linter checks with `uv`:

```bash
# Run all unit tests
uv run pytest

# Run tests with terminal coverage report
uv run pytest --cov=mathstore --cov-report=term-missing

# Run code style & linting checks
uvx ruff check .

# Auto-format code
uvx ruff format .
```

---

## Roadmap & Cloud Service

MathStore is under active development. Upcoming milestones include:
- **Managed Cloud API**: Hosted high-availability API with API keys and rate limiting for EdTech platforms and LMS integrations.
- **Web & Mobile Interface**: Interactive active-recall study companion with visual step-by-step derivations.
- **Extended Solvers**: Support for ordinary differential equations (ODEs), vector calculus, and LaTeX export templates.

If you are interested in early access to the managed cloud API or want to request features for your institution, feel free to open an [Issue](https://github.com/munenevictor577-blip/mathstore/issues) or reach out to the maintainers.

## License

This project is licensed under the MIT License.
