> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Calculator

> Perform mathematical calculations

## Overview

Calculator tool for performing mathematical calculations including basic arithmetic, scientific functions, and expression evaluation.

The user asks a math question; the agent evaluates the expression with the calculator and returns the result.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    subgraph "CalculatorTool Flow"
        User[👤 User] --> Agent[🤖 Agent]
        Agent --> Tool[🔧 CalculatorTool]
        Tool --> Result[✅ Result]
        Result --> Agent
    end

    classDef agent fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef tool fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef output fill:#10B981,stroke:#7C90A0,color:#fff

    class User,Agent agent
    class Tool tool
    class Result output
```

## Installation

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
pip install "praisonai[tools]"
```

No API key required!

## Quick Start

<Steps>
  <Step title="Simple Usage">
    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    from praisonai_tools import CalculatorTool

    # Initialize
    calc = CalculatorTool()

    # Calculate
    result = calc.calculate("2 + 2 * 3")
    print(result)  # 8
    ```
  </Step>

  <Step title="With Configuration">
    Use the same tool with an agent — see **Usage with Agent** below, or pass env vars and options from the sections above.
  </Step>
</Steps>

## Usage with Agent

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent
from praisonai_tools import CalculatorTool

agent = Agent(
    name="MathHelper",
    instructions="You are a math assistant. Use the calculator for computations.",
    tools=[CalculatorTool()]
)

response = agent.chat("What is 15% of 250?")
print(response)
```

## Available Methods

### calculate(expression)

Evaluate a mathematical expression.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonai_tools import CalculatorTool

calc = CalculatorTool()

# Basic arithmetic
calc.calculate("10 + 5")      # 15
calc.calculate("100 / 4")     # 25.0
calc.calculate("2 ** 10")     # 1024

# Percentages
calc.calculate("250 * 0.15")  # 37.5

# Complex expressions
calc.calculate("(10 + 5) * 2 - 3")  # 27
```

### Scientific Functions

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import math

calc = CalculatorTool()

# Trigonometry (radians)
calc.calculate("sin(3.14159 / 2)")  # ~1.0
calc.calculate("cos(0)")            # 1.0

# Logarithms
calc.calculate("log(100)")          # 2.0 (base 10)
calc.calculate("log(2.718)")        # ~1.0 (natural log)

# Square root
calc.calculate("sqrt(144)")         # 12.0
```

## Function-Based Usage

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonai_tools import calculate

# Quick calculation without instantiating class
result = calculate("(100 + 50) * 1.1")
print(result)  # 165.0
```

## CLI Usage

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Use with praisonai
praisonai --tools CalculatorTool "Calculate compound interest on $1000 at 5% for 3 years"
```

## Supported Operations

| Operation      | Symbol | Example       |
| -------------- | ------ | ------------- |
| Addition       | `+`    | `5 + 3`       |
| Subtraction    | `-`    | `10 - 4`      |
| Multiplication | `*`    | `6 * 7`       |
| Division       | `/`    | `20 / 4`      |
| Power          | `**`   | `2 ** 8`      |
| Modulo         | `%`    | `17 % 5`      |
| Parentheses    | `()`   | `(2 + 3) * 4` |

## Supported Functions

* `sin`, `cos`, `tan` - Trigonometric
* `asin`, `acos`, `atan` - Inverse trigonometric
* `sqrt` - Square root
* `log`, `log10` - Logarithms
* `exp` - Exponential
* `abs` - Absolute value
* `round`, `floor`, `ceil` - Rounding

## Error Handling

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonai_tools import CalculatorTool

calc = CalculatorTool()
result = calc.calculate("10 / 0")

if "error" in str(result).lower():
    print("Calculation error")
else:
    print(f"Result: {result}")
```

## Common Errors

| Error              | Cause                | Solution                |
| ------------------ | -------------------- | ----------------------- |
| `Division by zero` | Dividing by 0        | Check divisor           |
| `Invalid syntax`   | Malformed expression | Check expression format |
| `Unknown function` | Unsupported function | Use supported functions |

## How It Works

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
    participant User
    participant Agent
    participant Tool as Tool
    participant Svc as Calculator

    User->>Agent: Request
    Agent->>Tool: Call tool
    Tool->>Svc: Query
    Svc-->>Tool: Data
    Tool-->>Agent: Result
    Agent-->>User: Response
```

***

## Best Practices

<AccordionGroup>
  <Accordion title="Prefer the calculator over the LLM for math">
    LLMs approximate arithmetic. Route numeric work through the calculator tool for exact answers.
  </Accordion>

  <Accordion title="Guard against division by zero">
    Wrap `calculate` in error handling so a bad expression returns a message instead of crashing the agent.
  </Accordion>

  <Accordion title="Use parentheses for clarity">
    Explicit parentheses make the agent's intended order of operations unambiguous.
  </Accordion>
</AccordionGroup>

***

## Related Tools

<CardGroup cols={2}>
  <Card title="Python" icon="book" href="/docs/tools/external/python">
    Execute Python code
  </Card>

  <Card title="Pandas" icon="book" href="/docs/tools/external/pandas">
    Data analysis
  </Card>
</CardGroup>