Set symbolic assumptions (affecting subsequent math() calculations)

    Assumptions are recorded in MathContext and passed to SymPy, and also written
    to the current session's multi-level assumption engine (session level).

    Args:
        variables: Mapping from variable to properties
                   e.g., {"x": "positive real", "n": "integer"}

    Returns:
        All current assumptions

    Example:
        assume({"x": "positive", "t": "real"})
        # Afterwards, math("simplify", "sqrt(x**2)") returns x instead of Abs(x)
    

    📋 Set assumptions for the current derivation step only.

    Args:
        *args: Alternating symbol and property strings
               (e.g., "x", "positive", "y", "real")

    Returns:
        Updated step-level assumptions and any conflicts
    

    ⚠️ Detect conflicts across all assumption levels.

    A conflict occurs when a symbol is assigned contradictory properties
    (e.g., both positive and negative).

    Returns:
        Conflict report
    

    ⚠️ Check for ambiguous symbols in the current session.

    A conflict occurs when the same symbol name has multiple meanings
    or appears in multiple domains.

    Returns:
        Conflict report with suggested disambiguation
    

    🧹 Clear step-level assumptions.

    Useful when moving to a new sub-derivation or branch.

    Returns:
        Operation result
    

    🚀 High-level derivation entry point — start a derivation from a goal.

    Args:
        goal: Natural-language description of what to derive
        given: Base formulas or expressions to load as starting points
        assumptions: List of assumptions (e.g., ["rho is positive"])
        domain: Math/physics domain (e.g., "fluid_dynamics")
        pattern: Derivation pattern. If None, auto-selected from goal.
        target_expression: Expected final SymPy expression (optional)
        auto_load: If True, load the given formulas into the session
        external_sources: External formula sources to include in recommendations
            (e.g., ["wikidata", "biomodels", "scipy"] or ["all"]).
            Defaults to all sources; network failures are silently ignored.

    Returns:
        Session info + goal + derivation plan + recommended formulas + next steps
    

    This lets you (and the LLM) extend the local formula collection manually.
    Formulas are persisted as YAML files under ``formulas/library/<category>/``.

    Args:
        id: Unique identifier for the formula (e.g., "custom_drag_force").
           Used as the file name and lookup key.
        name: Human-readable formula name.
        sympy_str: SymPy-compatible expression, e.g. "F_d == 1/2 * rho * v**2 * C_d * A".
        latex: LaTeX representation, e.g. "F_d = \frac{1}{2} \rho v^2 C_d A".
        variables: Mapping of symbol names to metadata, e.g.
                   {"rho": {"description": "density", "unit": "kg/m^3"}}.
        domain: Optional domain tag (e.g., "fluid_dynamics").
        category: Optional category folder name (e.g., "fluid_dynamics").
        description: Optional longer description of the formula.
        aliases: Optional list of alternative names.
        tags: Optional list of tags.
        references: Optional list of references / URLs.
        library_path: Optional custom library directory. Defaults to ``formulas/library``.

    Returns:
        {
            "success": true,
            "formula_id": "custom_drag_force",
            "file_path": "formulas/library/fluid_dynamics/custom_drag_force.yaml",
            "message": "Formula added to local library."
        }

    Example:
        formula_add(
            id="custom_drag_force",
            name="Drag force",
            sympy_str="F_d == 1/2 * rho * v**2 * C_d * A",
            latex="F_d = \frac{1}{2} \rho v^2 C_d A",
            domain="fluid_dynamics",
            category="fluid_dynamics",
            description="Drag force on a body in a fluid.",
            variables={
                "F_d": {"description": "drag force", "unit": "N"},
                "rho": {"description": "density", "unit": "kg/m^3"},
                "v": {"description": "velocity", "unit": "m/s"},
                "C_d": {"description": "drag coefficient"},
                "A": {"description": "reference area", "unit": "m^2"}
            },
            aliases=["drag force", "fluid drag"],
            tags=["drag", "force"],
        )
    

    Get the categories currently present in the local formula library.

    Args:
        source: Data source
               - "local": Local YAML library (default)
               - "all": Local + legacy sources
               - "wikidata", "biomodels", "scipy": Legacy source only

    Returns:
        {
            "success": true,
            "categories": {
                "local": ["fluid_dynamics", "mechanics", "thermodynamics"],
                "wikidata": [...]
            }
        }
    

    Args:
        formula_id: Formula identifier (e.g., "reynolds_number")
        source: Data source
               - "local": Local YAML library (default, recommended)
               - "wikidata", "biomodels", "scipy": Legacy sources
        load_into_session: If True, load the formula into the current derivation session.
                          Requires an active session started with session_start().

    Returns:
        {
            "success": true,
            "formula": {
                "id": "reynolds_number",
                "name": "Reynolds number",
                "latex": "Re = \frac{\rho v L}{\mu}",
                "sympy_str": "rho * v * L / mu",
                "variables": {...},
                "source": "local"
            },
            "session_loaded": true
        }

    Example:
        # Get a local formula
        formula_get("reynolds_number")

        # Get and immediately load into a derivation session
        formula_get("reynolds_number", load_into_session=True)
    

    Retrieve accurate mathematical/physical formulas from the local, editable
    YAML library. This is deterministic, fast, and does not require network
    access.

    The query and domain are normalized automatically, so you can pass
    free-form text such as "Navier–Stokes equations" or "fluid_dynamics".

    Args:
        query: Search keyword
               - English name: "Reynolds number", "Arrhenius equation"
               - Domain terms: "fluid dynamics", "quantum", "thermodynamics"
        source: Data source
               - "local": Local YAML library (default, recommended)
               - "scipy": Physical constants only (no local search)
               - "legacy": Search local, then Wikidata, BioModels, SciPy
               - "all": Alias for "legacy" (kept for compatibility)
               - "wikidata", "biomodels", "scipy": Legacy source only
        domain: Restrict domain (optional)
               - "mechanics", "thermodynamics", "electromagnetism"
               - "fluid_dynamics", "fluid_mechanics", "quantum_mechanics"
        limit: Maximum number of results to return

    Returns:
        {
            "success": true,
            "results": [...],
            "total": 1,
            "query": "navier-stokes equations",
            "domain": "fluid",
            "sources_searched": ["local"],
            "next_steps": [...]
        }

    Example:
        # Search the local library
        formula_search("Reynolds number")

        # Search by domain
        formula_search("diffusion", domain="thermodynamics")

    Correct workflow for derivation:
        1. formula_search("<concept>", domain="<domain>")
        2. formula_get(result["id"])
        3. session_load_formula(formula["sympy_str"] or formula["latex"], ...)
        4. math(..., session=True) to derive or transform
    

    Generate a complete derivation report in Markdown.

    Args:
        problem: Problem description
        given: Given parameters {"symbol": "value with unit"}
        steps: Derivation steps
        results: Final results {"symbol": "expression"}
        verification: Optional verification status

    Returns:
        Markdown report
    

    Generate LaTeX documentation for a derivation.

    Args:
        title: Derivation title
        steps: List of {"description": str, "latex": str}
        final_result: Final result in LaTeX

    Returns:
        LaTeX document string
    

    Generate a Python function from VERIFIED derivation steps.

    ═══════════════════════════════════════════════════════════════════════
    ⚠️ PREREQUISITE: All expressions must be verified with SymPy-MCP first!
    ═══════════════════════════════════════════════════════════════════════

    Correct workflow:
    1. Use SymPy-MCP to derive and verify each expression
    2. Use print_latex_expression() to show results to user
    3. User confirms the derivation is correct
    4. Call this tool with the verified expressions

    The generated code assembles the provided expressions into a Python
    function; it does not perform new symbolic calculations. The expressions
    must already be verified before calling this tool.

    Args:
        name: Function name (e.g., "calculate_seatbelt_tension")
        description: Function docstring description
        parameters: List of {"name": str, "type": str, "description": str}
        steps: List of {"description": str, "expression": str, "result_var": str}
        return_vars: Variables to return

    Returns:
        dict with keys ``success``, ``code`` (the generated Python function),
        ``function_name``, ``parameters``, and ``returns``.

    Example:
        generate_python_function(
            name="calculate_tension",
            description="Calculate seatbelt tension from collision",
            parameters=[
                {"name": "M1", "type": "float", "description": "Vehicle 1 mass (kg)"},
                {"name": "M2", "type": "float", "description": "Vehicle 2 mass (kg)"},
                {"name": "v", "type": "float", "description": "Initial velocity (m/s)"},
                {"name": "m", "type": "float", "description": "Person mass (kg)"},
                {"name": "k", "type": "float", "description": "Seatbelt constant (N/m)"},
            ],
            steps=[
                {"description": "Final velocity after collision",
                 "expression": "M1 * v / (M1 + M2)",
                 "result_var": "v_f"},
                {"description": "Velocity change",
                 "expression": "v - v_f",
                 "result_var": "delta_v"},
                {"description": "Maximum tension",
                 "expression": "delta_v * sqrt(m * k)",
                 "result_var": "T_max"},
            ],
            return_vars=["v_f", "delta_v", "T_max"]
        )
    

    Generate a standalone SymPy script for a computation.

    This generates a complete, runnable Python script that can be
    executed independently to reproduce the derivation.

    Args:
        expressions: List of {"name": str, "expr": str, "description": str}
        operations: List of operations to perform
            {"op": "simplify|solve|diff|integrate", "input": str, ...}

    Returns:
        Complete Python script

    Example:
        generate_sympy_script(
            expressions=[
                {"name": "momentum", "expr": "m1*v1 + m2*v2", "description": "Total momentum"},
            ],
            operations=[
                {"op": "solve", "input": "momentum = (m1+m2)*v_f", "for": "v_f"},
            ]
        )
    

    🎯 Natural-language intent router — map a request to the right tool chain.

    Understands common math/derivation intents and returns the recommended
    tool(s) to call. The agent can then execute the recommended tool(s) directly.

    Args:
        intent: Natural language request
                (e.g., "derive NS equations", "simplify this", "verify derivative", "solve for x")
        expression: Optional expression to operate on
        variable: Optional variable for differentiation/solving
        session: Whether to use session-based derivation (default True)

    Returns:
        intent_type, recommended tool chain, and examples

    Example:
        intent_execute("derive the temperature corrected elimination rate",
                       expression="C0 * exp(-k*t)")
    

    📐 List assumptions at a specific level or merged across all levels.

    Args:
        level: "global", "domain", "session", "step", or None for merged

    Returns:
        Assumptions at the requested level
    

    📋 List default symbols for a given domain.

    Args:
        domain: Domain name

    Returns:
        List of symbols with meanings and units
    

    📋 List all available derivation patterns.

    Returns:
        Descriptions, typical steps, and suggested operations for each pattern.
    

    🔍 Look up the semantic meaning of a symbol.

    Args:
        name: Symbol name
        domain: Optional domain to prefer

    Returns:
        Symbol meaning and all known definitions
    

    Run mathematical operations (unified Mathematica-style tool)

    ═══════════════════════════════════════════════════════════════════════
    SymKit's core tool — supports ~25 mathematical operations.
    One tool handles derivation, calculation, solving, and transformation.
    ═══════════════════════════════════════════════════════════════════════

    **Supported operations (operation):**

    | Category | Operation | Description |
    |------|------|------|
    | Parse | `parse` | Parse expression and extract symbols |
    | Simplify | `simplify` | General simplification |
    | | `expand` | Expand polynomial |
    | | `factor` | Factorization |
    | | `collect` | Collect like terms (requires variable) |
    | | `cancel` | Cancel rational function |
    | | `apart` | Partial fraction expansion (requires variable) |
    | | `together` | Combine over common denominator |
    | | `trigsimp` | Trigonometric simplification |
    | | `powsimp` | Power simplification |
    | | `radsimp` | Radical simplification |
    | | `combsimp` | Combinatorial simplification |
    | Solve | `solve` | Solve for variable (requires variable) |
    | Substitute | `substitute` | Substitute variables (requires substitution dict) |
    | Calculus | `diff` | Differentiate (requires variable; order optional) |
    | | `integrate` | Integrate (variable, lower/upper optional) |
    | | `limit` | Limit (variable, point, direction) |
    | | `series` | Series expansion (variable, point, order) |
    | ODE | `dsolve` | Solve ODE (variable=function name, with_respect_to=independent variable) |
    | Vector | `gradient` | Gradient (variable="x,y,z" comma-separated coordinates) |
    | | `divergence` | Divergence |
    | | `curl` | Curl |
    | | `laplacian` | Laplacian |
    | Matrix | `det` | Determinant |
    | | `inv` | Inverse matrix |
    | | `eigenvals` | Eigenvalues |
    | | `eigenvects` | Eigenvectors |
    | Transform | `laplace` | Laplace transform (variable=time, with_respect_to=s) |
    | | `ilaplace` | Inverse Laplace transform (variable=s, with_respect_to=t) |
    | | `fourier` | Fourier transform |
    | | `ifourier` | Inverse Fourier transform |

    Args:
        operation: Operation name (see table above)
        expression: Mathematical expression (SymPy or LaTeX format)
        variable: Differentiation/integration/solving variable (for vector operations can be comma-separated like "x,y,z")
        with_respect_to: Second variable (independent variable for ODE, target variable for transforms)
        substitution: Substitution mapping {"var": "replacement", ...}
        point: Limit point / series expansion point (default "0")
        direction: Limit direction "+-", "+", "-"
        order: Differentiation order / number of series terms (default 1)
        lower: Definite integral lower bound
        upper: Definite integral upper bound
        assumptions: Symbolic assumptions ["x is positive", "t is real"]
        method: Simplification method "auto", "trig", "radical", "expand_then_simplify"
        session: True=record to derivation session, False=stateless computation
        description: Description of this step (used when recording to session)
        notes: Human insight (used when recording to session)

    Returns:
        Result dict containing expression, latex, operation

    Examples:
        # Stateless quick calculation
        math("diff", "x**3", variable="x")
        → {"expression": "3*x**2", "latex": "3 x^{2}"}

        # Substitute
        math("substitute", "m*a", substitution={"m": "2", "a": "9.8"})
        → {"expression": "19.6", ...}

        # Laplace transform
        math("laplace", "exp(-k*t)", variable="t", with_respect_to="s")
        → {"expression": "1/(k + s)", ...}

        # Vector calculus
        math("gradient", "x**2 + y**2 + z**2", variable="x,y,z")
        → gradient in vector form

        # Solve ODE
        math("dsolve", "diff(y,t) - k*y", variable="y", with_respect_to="t")
    

    🏷️ Register the semantic meaning of a symbol in the current session.

    Args:
        name: Symbol name (e.g., "R", "hbar", "k")
        meaning: Human-readable meaning (e.g., "Universal gas constant")
        domain: Domain this meaning belongs to
        unit: Default physical unit
        assumptions: Common assumptions (e.g., ["positive"])
        aliases: Alternative names for this symbol

    Returns:
        Registration result
    

    Suspend the current derivation (session is saved to disk)

    Returns:
        Operation result
    

    Add a human knowledge note to the derivation (non-computational step)

    Args:
        note: Note content
        note_type: "assumption", "limitation", "observation",
                   "correction", "interpretation", "application", "reference"
        related_variables: Related variables

    Returns:
        Record result
    

    Complete the derivation and auto-save

    Args:
        description: Formula description (physical/mathematical meaning)
        application_context: Usage context (when to use this formula)
        assumptions: Derivation assumptions
        limitations: Usage limitations
        references: References
        tags: Tags
        auto_save: Whether to auto-save (default True)
        require_target_match: If True, the derivation will only be saved as
            completed when the current expression matches the goal target.
            Default is False for backward compatibility, but a warning is
            still returned if the target is not reached.

    Returns:
        Complete derivation record
    

    🗣️ Explain the current derivation in natural language.

    Generates a human-readable summary of the derivation so far, including:
    - The overall goal (session name/description)
    - What formulas were loaded
    - What operations were performed and why
    - Key assumptions and limitations recorded
    - The current result

    Args:
        level: Detail level — "short", "medium" (default), or "detailed"
        focus: Optional aspect to focus on ("assumptions", "steps", "result")

    Returns:
        Natural-language summary and structured metadata
    

    Returns:
        List of steps with metadata.
    

    Correct workflow for derivation from an external source:
        1. formula_search("<concept>", domain="<domain>")
        2. formula_get(result["id"], source=result["source"], load_into_session=True)
        3. math(..., session=True) to derive or transform
        4. session_complete(...) to finalize and save

    Args:
        expression: Formula or expression string (e.g. "rho * v * L / mu" or
                   a LaTeX string). For formulas loaded via formula_get, you can
                   pass formula["sympy_str"] or formula["latex"].
        formula_id: Optional custom formula ID.
        source: Source label (e.g. "user_input", "scipy", "wikidata").

    Returns:
        Load result with formula_id, expression and LaTeX.
    

    The ``expression`` argument is parsed through the unified parser, which
    supports SymPy strings, natural equations (``A = B``), Leibniz derivative
    notation (``dX/dY``), Greek/Unicode math, and LaTeX.

    Args:
        expression: Result expression string (SymPy or LaTeX).
        description: Human-readable step description.
        operation: Ignored. Manual steps are always recorded as OperationType.CUSTOM
            to prevent a user-supplied operation label (e.g. "simplify") from being
            falsely reported as automatically verified.
        notes: Human insight / observation.
        assumptions: Step-specific assumptions.
        limitations: Step-specific limitations.

    Returns:
        Recorded step details.
    

    Resume a suspended derivation session

    Args:
        session_id: Session ID

    Returns:
        Session status
    

    Roll back to the specified step

    Keep steps up to and including the specified step, and delete steps after it.
    After rolling back, you can continue the derivation from that step (taking a different path).

    Args:
        to_step: Step number to roll back to (1-based); 0 = clear all

    Returns:
        Rollback result
    

    Args:
        goal: Natural-language goal text.
        target_expression: Optional explicit target expression (e.g.
            "v = sqrt(2*G*M/R)").  When provided, it overrides the
            automatically-extracted target expression.

    Returns:
        Parsed goal and session status.
    

    Show the current derivation state and formula

    ⚠️ Must be called after each derivation operation to show the user the result!

    Args:
        show_steps: Whether to show all step history

    Returns:
        Current formula LaTeX and derivation state
    

    Start a new derivation session

    Args:
        name: Derivation name
        description: Derivation description
        domain: Math/physics domain tag
        pattern: Derivation pattern
        goal: Natural-language goal (optional)
        author: Author

    Returns:
        Session information
    

    Args:
        top_k: Maximum number of suggestions.

    Returns:
        List of recommended formulas with rationale.
    

    Returns:
        Summary with total, verified, failed and inconclusive counts.
    

    Args:
        step_number: 1-based step number. Defaults to -1 (last step).

    Returns:
        Verification result.
    

    Show all symbolic assumptions in the current scope

    Returns:
        Assumptions in the current MathContext
    

    🧰 List SymKit tools organized by category.

    Returns:
        Categorized tool index with descriptions and examples.
    

    💡 Recommend the best tool(s) for a given task.

    Args:
        task: Brief description of what you want to do
        domain: Optional domain context

    Returns:
        Recommended tool with rationale and example