mathstore 0.1.0__py3-none-any.whl

mathstore/__init__.py

@@ -0,0 +1,38 @@
+from mathstore.algebra.solver import EquationSolver
+from mathstore.calculus.analyzer import CalculusAnalyzer
+from mathstore.core.matrix import MatrixAnalyzer
+from mathstore.reference import get_reference, list_topics
+from mathstore.statistics.analyzer import StatsAnalyzer
+from mathstore.study import (
+    PracticeQuestion,
+    PracticeSession,
+    generate_question,
+    get_derivative_steps,
+    get_equation_steps,
+    get_integral_steps,
+)
+
+
+def main() -> None:
+    print("Hello from mathstore!")
+
+
+__all__ = [
+    "CalculusAnalyzer",
+    "EquationSolver",
+    "MatrixAnalyzer",
+    "PracticeQuestion",
+    "PracticeSession",
+    "StatsAnalyzer",
+    "generate_question",
+    "get_derivative_steps",
+    "get_equation_steps",
+    "get_integral_steps",
+    "get_reference",
+    "list_topics",
+    "main",
+]
+
+
+
+

mathstore/algebra/__init__.py

@@ -0,0 +1,3 @@
+from mathstore.algebra.solver import EquationSolver
+
+__all__ = ["EquationSolver"]

mathstore/algebra/solver.py

@@ -0,0 +1,73 @@
+import sympy as sp
+
+from mathstore.core.safe import safe_sympify
+
+
+class EquationSolver:
+    """Handles algebraic equation solving isolating the sympy implementation."""
+
+    def __init__(self):
+        self.x, self.y, self.z = sp.symbols("x y z")
+
+    def solve_linear(self, equation_str: str, variable: str = "x") -> list:
+        """Solves an equation like '2*x + 4 = 10'."""
+        try:
+            var = sp.Symbol(variable)
+            if "=" not in equation_str:
+                raise ValueError("Equation must contain '=' separating left and right sides.")
+            parts = equation_str.split("=")
+            if len(parts) != 2:
+                raise ValueError("Equation must contain exactly one '=' sign.")
+            left, right = parts
+            eq = sp.Eq(safe_sympify(left.strip()), safe_sympify(right.strip()))
+
+            return sp.solve(eq, var)
+        except Exception as e:  # noqa: BLE001
+            raise ValueError(f"Failed to parse or solve the equation: {e}") from e
+
+    def simplify_expression(self, expression_str: str) -> str:
+        """Simplifies algebraic expressions."""
+        try:
+            expr = safe_sympify(expression_str)
+            return str(sp.simplify(expr))
+        except Exception as e:  # noqa: BLE001
+            raise ValueError(f"Failed to parse or simplify the expression: {e}")
+
+    def format_solution(self, solutions: list, variable: str = "x", format: str = "str") -> str:
+        """
+        Formats equation solutions into standard text, LaTeX, or pretty Unicode.
+
+        Args:
+            solutions: List of solutions returned by solve_linear.
+            variable: The variable solved for (default: 'x').
+            format: Output format ('str', 'latex', or 'pretty').
+        """
+        if format == "latex":
+            if not solutions:
+                return r"\emptyset"
+            if len(solutions) == 1:
+                return f"{variable} = {sp.latex(solutions[0])}"
+            inner = ", ".join(sp.latex(s) for s in solutions)
+            return f"{variable} \\in \\left\\{{ {inner} \\right\\}}"
+
+        if format == "pretty":
+            if not solutions:
+                return "No solution (∅)"
+            if len(solutions) == 1:
+                return f"{variable} = {sp.pretty(solutions[0], use_unicode=True)}"
+            inner = ", ".join(sp.pretty(s, use_unicode=True) for s in solutions)
+            return f"{variable} ∈ {{{inner}}}"
+
+        return f"Solution: {variable} = {solutions}"
+
+    def solve_steps(self, equation_str: str, variable: str = "x") -> list[str]:
+        """
+        Returns step-by-step algebraic isolation and solution breakdown for an equation.
+
+        Args:
+            equation_str: The equation to solve (e.g., '2*x + 4 = 10').
+            variable: The variable to isolate (default: 'x').
+        """
+        from mathstore.study.steps import get_equation_steps
+
+        return get_equation_steps(equation_str, variable=variable)

mathstore/api/__init__.py

@@ -0,0 +1,3 @@
+from mathstore.api.main import app, create_app, run
+
+__all__ = ["app", "create_app", "run"]

mathstore/api/main.py

@@ -0,0 +1,140 @@
+from typing import Any
+
+import uvicorn
+from fastapi import APIRouter, FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+
+from mathstore.api.routes import (
+    algebra_router,
+    calculus_router,
+    matrix_router,
+    statistics_router,
+    study_router,
+)
+
+
+def create_app() -> FastAPI:
+    """Creates and configures the MathStore FastAPI application."""
+    app = FastAPI(
+        title="MathStore API",
+        description=(
+            "Clean, modular mathematical API toolkit for university students, educators, "
+            "and STEM applications. Provides symbolic calculus, step-by-step derivations, "
+            "linear algebra, probability, statistics, reference cheat sheets, and active-recall practice."
+        ),
+        version="0.1.0",
+        docs_url="/docs",
+        redoc_url="/redoc",
+        openapi_url="/openapi.json",
+        swagger_ui_oauth2_redirect_url="/docs/oauth2-redirect",
+    )
+
+    # Enable CORS for cross-origin and remote frontend calling
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=["*"],
+        allow_credentials=True,
+        allow_methods=["*"],
+        allow_headers=["*"],
+    )
+
+    # Core math router with all mathematical endpoints
+    math_router = APIRouter()
+
+    # Register sub-routers
+    math_router.include_router(calculus_router)
+    math_router.include_router(algebra_router)
+    math_router.include_router(matrix_router)
+    math_router.include_router(statistics_router)
+    math_router.include_router(study_router)
+
+    def math_root_info() -> dict[str, Any]:
+        """Root API metadata index for the Math API prefix."""
+        return {
+            "name": "MathStore API",
+            "description": "Mathematical Toolkit API for university study and revision",
+            "version": "0.1.0",
+            "prefix": "/math",
+            "docs_url": "/math/docs",
+            "redoc_url": "/math/redoc",
+            "openapi_url": "/math/openapi.json",
+            "health_url": "/math/health",
+        }
+
+    def math_health_info() -> dict[str, Any]:
+        """Health check endpoint for the Math API prefix."""
+        return {
+            "status": "healthy",
+            "service": "mathstore",
+            "prefix": "/math",
+            "version": "0.1.0",
+        }
+
+    # Math prefix health and index endpoints
+    @app.get("/math/health", summary="Math API health check")
+    @app.get("/api/v1/math/health", summary="API v1 Math health check", include_in_schema=False)
+    @app.get("/api/v1/health", summary="API v1 health check", include_in_schema=False)
+    def math_health() -> dict[str, Any]:
+        return math_health_info()
+
+    @app.get("/math", summary="Math API Index", include_in_schema=False)
+    @app.get("/math/", summary="Math API Index")
+    @app.get("/api/v1/math", summary="API v1 Math Index", include_in_schema=False)
+    @app.get("/api/v1/math/", summary="API v1 Math Index", include_in_schema=False)
+    def math_root() -> dict[str, Any]:
+        return math_root_info()
+
+    # Documentation and schema endpoints for /math prefix
+    @app.get("/math/docs", include_in_schema=False)
+    def math_docs():
+        from fastapi.openapi.docs import get_swagger_ui_html
+        return get_swagger_ui_html(
+            openapi_url="/math/openapi.json",
+            title=app.title + " - Swagger UI",
+            oauth2_redirect_url="/docs/oauth2-redirect",
+        )
+
+
+    @app.get("/math/redoc", include_in_schema=False)
+    def math_redoc():
+        from fastapi.openapi.docs import get_redoc_html
+        return get_redoc_html(openapi_url="/math/openapi.json", title=app.title + " - ReDoc")
+
+    @app.get("/math/openapi.json", include_in_schema=False)
+    def math_openapi():
+        from fastapi.responses import JSONResponse
+        return JSONResponse(content=app.openapi())
+
+    # Mount mathematical endpoints directly at root: /diff, /integrate, etc.
+    app.include_router(math_router)
+
+    # Mount mathematical endpoints under /math: /math/diff, /math/integrate, etc.
+    app.include_router(math_router, prefix="/math")
+
+    # Maintain backward compatibility for /api/v1/math and /api/v1 callers
+    app.include_router(math_router, prefix="/api/v1/math", include_in_schema=False)
+    app.include_router(math_router, prefix="/api/v1", include_in_schema=False)
+
+    # Root informational routes
+    @app.get("/", summary="Root API Index", include_in_schema=False)
+    def root() -> dict[str, Any]:
+        return math_root_info()
+
+    @app.get("/health", summary="Global health check", include_in_schema=False)
+    def global_health() -> dict[str, Any]:
+        return {"status": "ok", "service": "mathstore", "version": "0.1.0"}
+
+
+    return app
+
+
+app = create_app()
+
+
+def run(host: str = "0.0.0.0", port: int = 8000, reload: bool = False) -> None:
+    """Runs the FastAPI server using uvicorn."""
+    uvicorn.run("mathstore.api.main:app", host=host, port=port, reload=reload)
+
+
+if __name__ == "__main__":
+    run()

mathstore/api/routes/__init__.py

@@ -0,0 +1,13 @@
+from mathstore.api.routes.algebra import router as algebra_router
+from mathstore.api.routes.calculus import router as calculus_router
+from mathstore.api.routes.matrix import router as matrix_router
+from mathstore.api.routes.statistics import router as statistics_router
+from mathstore.api.routes.study import router as study_router
+
+__all__ = [
+    "algebra_router",
+    "calculus_router",
+    "matrix_router",
+    "statistics_router",
+    "study_router",
+]

mathstore/api/routes/algebra.py

@@ -0,0 +1,74 @@
+from fastapi import APIRouter, HTTPException, Query
+
+from mathstore.algebra.solver import EquationSolver
+from mathstore.api.schemas import (
+    SimplifyRequest,
+    SimplifyResponse,
+    SolveRequest,
+    SolveResponse,
+)
+
+router = APIRouter(tags=["Algebra"])
+solver = EquationSolver()
+
+
+@router.post("/solve", response_model=SolveResponse, summary="Solve an algebraic equation")
+def solve_post(req: SolveRequest) -> SolveResponse:
+    """Solves linear and polynomial equations with optional step-by-step breakdown."""
+    try:
+        steps_list = (
+            solver.solve_steps(req.equation, variable=req.variable)
+            if req.steps
+            else None
+        )
+        solutions = solver.solve_linear(req.equation, variable=req.variable)
+        formatted = solver.format_solution(
+            solutions, variable=req.variable, format=req.format
+        )
+        return SolveResponse(
+            equation=req.equation,
+            variable=req.variable,
+            solutions=[str(s) for s in solutions],
+            formatted=formatted,
+            format=req.format,
+            steps=steps_list,
+        )
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e)) from e
+
+
+@router.get("/solve", response_model=SolveResponse, summary="Solve an equation (GET query)")
+def solve_get(
+    equation: str = Query(..., description="Equation to solve (e.g. 2*x + 4 = 10)"),
+    variable: str = Query("x", description="Variable to isolate"),
+    steps: bool = Query(False, description="Include steps"),
+    format: str = Query("str", description="Output format"),
+) -> SolveResponse:
+    return solve_post(
+        SolveRequest(
+            equation=equation,
+            variable=variable,
+            steps=steps,
+            format=format,
+        )
+    )
+
+
+@router.post("/simplify", response_model=SimplifyResponse, summary="Simplify an algebraic expression")
+def simplify_post(req: SimplifyRequest) -> SimplifyResponse:
+    """Simplifies mathematical expressions."""
+    try:
+        res = solver.simplify_expression(req.expression)
+        return SimplifyResponse(
+            expression=req.expression,
+            simplified=res,
+        )
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e)) from e
+
+
+@router.get("/simplify", response_model=SimplifyResponse, summary="Simplify (GET query)")
+def simplify_get(
+    expression: str = Query(..., description="Expression to simplify"),
+) -> SimplifyResponse:
+    return simplify_post(SimplifyRequest(expression=expression))

mathstore/api/routes/calculus.py

@@ -0,0 +1,137 @@
+from fastapi import APIRouter, HTTPException, Query
+
+from mathstore.api.schemas import (
+    DiffRequest,
+    DiffResponse,
+    IntegrateRequest,
+    IntegrateResponse,
+    LimitRequest,
+    LimitResponse,
+)
+from mathstore.calculus.analyzer import CalculusAnalyzer
+
+router = APIRouter(tags=["Calculus"])
+analyzer = CalculusAnalyzer()
+
+
+@router.post("/diff", response_model=DiffResponse, summary="Differentiate a mathematical expression")
+def differentiate_post(req: DiffRequest) -> DiffResponse:
+    """Calculates the nth derivative of an algebraic expression with optional steps."""
+    try:
+        steps_list = (
+            analyzer.differentiate_steps(req.expression, variable=req.variable, order=req.order)
+            if req.steps
+            else None
+        )
+        res = analyzer.differentiate(
+            req.expression, variable=req.variable, order=req.order, format=req.format
+        )
+        return DiffResponse(
+            expression=req.expression,
+            variable=req.variable,
+            order=req.order,
+            derivative=str(res),
+            format=req.format,
+            steps=steps_list,
+        )
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e)) from e
+
+
+@router.get("/diff", response_model=DiffResponse, summary="Differentiate (GET query)")
+def differentiate_get(
+    expression: str = Query(..., description="Expression to differentiate"),
+    variable: str = Query("x", description="Variable of differentiation"),
+    order: int = Query(1, ge=1, description="Derivative order"),
+    steps: bool = Query(False, description="Include steps"),
+    format: str = Query("str", description="Output format"),
+) -> DiffResponse:
+    return differentiate_post(
+        DiffRequest(
+            expression=expression,
+            variable=variable,
+            order=order,
+            steps=steps,
+            format=format,
+        )
+    )
+
+
+@router.post("/integrate", response_model=IntegrateResponse, summary="Integrate an expression")
+def integrate_post(req: IntegrateRequest) -> IntegrateResponse:
+    """Calculates indefinite or definite integrals with optional step derivations."""
+    try:
+        steps_list = (
+            analyzer.integrate_steps(req.expression, variable=req.variable, limits=req.limits)
+            if req.steps
+            else None
+        )
+        res = analyzer.integrate(
+            req.expression, variable=req.variable, limits=req.limits, format=req.format
+        )
+        return IntegrateResponse(
+            expression=req.expression,
+            variable=req.variable,
+            limits=req.limits,
+            integral=str(res),
+            format=req.format,
+            steps=steps_list,
+        )
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e)) from e
+
+
+@router.get("/integrate", response_model=IntegrateResponse, summary="Integrate (GET query)")
+def integrate_get(
+    expression: str = Query(..., description="Expression to integrate"),
+    variable: str = Query("x", description="Variable of integration"),
+    lower_limit: float | None = Query(None, description="Lower bound for definite integral"),
+    upper_limit: float | None = Query(None, description="Upper bound for definite integral"),
+    steps: bool = Query(False, description="Include steps"),
+    format: str = Query("str", description="Output format"),
+) -> IntegrateResponse:
+    limits = (lower_limit, upper_limit) if lower_limit is not None and upper_limit is not None else None
+    return integrate_post(
+        IntegrateRequest(
+            expression=expression,
+            variable=variable,
+            limits=limits,
+            steps=steps,
+            format=format,
+        )
+    )
+
+
+@router.post("/limit", response_model=LimitResponse, summary="Evaluate a limit")
+def limit_post(req: LimitRequest) -> LimitResponse:
+    """Calculates the limit of an expression approaching a target value."""
+    try:
+        res = analyzer.get_limit(
+            req.expression, limits=req.target, variable=req.variable, format=req.format
+        )
+        return LimitResponse(
+            expression=req.expression,
+            target=req.target,
+            variable=req.variable,
+            limit=str(res),
+            format=req.format,
+        )
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e)) from e
+
+
+@router.get("/limit", response_model=LimitResponse, summary="Evaluate a limit (GET query)")
+def limit_get(
+    expression: str = Query(..., description="Expression to evaluate"),
+    target: str = Query(..., description="Target value, e.g. 0, oo, -oo"),
+    variable: str = Query("x", description="Limit variable"),
+    format: str = Query("str", description="Output format"),
+) -> LimitResponse:
+    return limit_post(
+        LimitRequest(
+            expression=expression,
+            target=target,
+            variable=variable,
+            format=format,
+        )
+    )

mathstore/api/routes/matrix.py

@@ -0,0 +1,49 @@
+from typing import Any
+
+from fastapi import APIRouter, HTTPException
+
+from mathstore.api.schemas import MatrixRequest, MatrixResponse
+from mathstore.core.matrix import MatrixAnalyzer
+
+router = APIRouter(prefix="/matrix", tags=["Linear Algebra / Matrix"])
+analyzer = MatrixAnalyzer()
+
+VALID_OPERATIONS = {
+    "det": analyzer.determinant,
+    "inv": analyzer.inverse,
+    "rref": analyzer.rref,
+    "eigen": analyzer.eigenvalues,
+    "eigenvects": analyzer.eigenvectors,
+    "rank": analyzer.rank,
+    "nullity": analyzer.nullity,
+    "trace": analyzer.trace,
+    "transpose": analyzer.transpose,
+    "charpoly": analyzer.characteristic_polynomial,
+}
+
+
+@router.post("/{operation}", response_model=MatrixResponse, summary="Perform matrix operation")
+def matrix_operation(operation: str, req: MatrixRequest) -> MatrixResponse:
+    """Executes a linear algebra operation on a given matrix string."""
+    op_lower = operation.lower().strip()
+    if op_lower not in VALID_OPERATIONS:
+        raise HTTPException(
+            status_code=400,
+            detail=f"Unsupported matrix operation '{operation}'. Choose from: {list(VALID_OPERATIONS.keys())}",
+        )
+    try:
+        fn = VALID_OPERATIONS[op_lower]
+        # rank and nullity do not accept format parameter
+        if op_lower in ("rank", "nullity"):
+            res: Any = fn(req.matrix)
+        else:
+            res = fn(req.matrix, format=req.format)
+
+        return MatrixResponse(
+            operation=op_lower,
+            matrix=req.matrix,
+            result=res,
+            format=req.format,
+        )
+    except (ValueError, TypeError) as e:
+        raise HTTPException(status_code=400, detail=str(e)) from e