Metadata-Version: 2.4
Name: math-ai-agent
Version: 0.0.9
Summary: Math AI Agent that uses LLM + Rubens calculator-mcp.
License-Expression: MIT
License-File: LICENSE
Keywords: ai,math,llm,mcp,agentic
Author: Rubens Gomes
Author-email: rubens.s.gomes@gmail.com
Maintainer: Rubens Gomes
Maintainer-email: rubens.s.gomes@gmail.com
Requires-Python: >=3.14,<4.0.0
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python :: 3.14
Requires-Dist: colorlog (>=6.12.0,<7.0.0)
Requires-Dist: cryptography (>=50.0.1,<51.0.0)
Requires-Dist: fastapi (>=0.141.1,<1.0.0)
Requires-Dist: fastmcp (>=4.0.10,<5.0.0)
Requires-Dist: key-value (>=0.1.2,<1.0.0)
Requires-Dist: mcp (>=2.2.0,<3.0.0)
Requires-Dist: openai (>=3.19.1,<4.0.0)
Requires-Dist: py-key-value-aio (>=0.4.6,<1.0.0)
Requires-Dist: pydantic (>=2.13.5,<3.0.0)
Requires-Dist: pyyaml (>=6.0.3,<7.0.0)
Requires-Dist: uvicorn (>=0.53.0,<1.0.0)
Project-URL: Documentation, https://github.com/rubensgomes/math-ai-agent/blob/main/README.md
Project-URL: Homepage, https://github.com/rubensgomes/math-ai-agent/
Project-URL: Repository, https://github.com/rubensgomes/math-ai-agent/
Description-Content-Type: text/markdown

[![python](https://img.shields.io/badge/python-3.14.7-0969da)](https://www.python.org/downloads/release/python-3147/)
[![License](https://img.shields.io/badge/License-MIT-0969da)](https://github.com/rubensgomes-org/math-ai-agent/blob/main/LICENSE)
[![AI--Assisted](https://img.shields.io/badge/AI--Assisted-Development-8250df)](https://github.com/rubensgomes-org/math-ai-agent/blob/main/AI_DISCLAIMER.md)

# Math AI Agent

A prompt chat webapp that drives an LLM call inside an agentic loop using
the `calculator_mcp` MCP server for arithmetic operations. The key constraint is
that the LLM is given explicit system instructions to use the `calculator_mcp`
for any arithmetic operations.

## Features

- **FastAPI web UI** — simple form-based interface for submitting prompts
- **MCP client** — connects to a remote calculator MCP server with optional
  OAuth authentication
- **Configurable** — MCP server URL, OAuth settings, LLM endpoint and model,
  and logging are all driven by `config.yaml`
- **Plain-text answers** — the model is instructed to reply without LaTeX or
  Markdown, since the web UI renders answers in a plain `<textarea>`

## Non-Supported Features

- **Server-sent events (SSE)** are not supported for either LLM or MCP
  communication.
- **Streaming communication channels**, such as HTTP Streamable, are not
  supported. In other words, both the LLM model and the MCP server are expected
  to generate the entire output before sending it.
- **Stateful Responses API** communication may not be supported, depending on
  the LLM model selected in the configuration.
- **Input types** such as images and videos are not supported. Only text
  input is supported.
- **Tools** available to the LLM are limited to the `Calculator MCP` only. Other
  tool types, such as `built-in tools` (for example, web search and file search)
  and `function calls`, are not supported.

Bear in mind that support for the features listed above also depends on the
capabilities of the selected LLM model. For example, the default configurable
model, NVIDIA Nemotron 3 Super, does not support storing conversation history
and supports only text input.

## AI Disclaimer

This project includes code and documentation created with the assistance of AI
tools. For details on usage, limits, and review practices, please see the
[AI Disclaimer](https://github.com/rubensgomes-org/math-ai-agent/blob/main/AI_DISCLAIMER.md).

## Installation

### Prerequisites

- UNIX OS (e.g., macOS, Linux)
- curl 8.7+
- pip 26.2+
- poetry 2.4+
- python 3.14+

### PyPI Package Installation

**IMPORTANT**: release versioning was recently reset to start again at
version 0.0.1. Uninstall any previously installed version first.

1. Uninstall any previously installed release

```bash
pip uninstall math-ai-agent
pip cache purge
```

2. Install into the user's home environment. **NOTE**: use --no-cache-dir to
   avoid issues with an earlier cached version

```bash
pip --no-cache-dir install -U --user math-ai-agent
```

3. Confirm the installed version matches the latest GitHub release at
   [math-ai-agent/releases](https://github.com/rubensgomes-org/math-ai-agent/releases)

```bash
pip show math-ai-agent
```

### Git Clone Installation

1. `git` clone and install local project package using `poetry`

```bash
# use local `dev` folder to install the project
mkdir -p ~/dev || exit; cd ~/dev
git clone https://github.com/rubensgomes-org/math-ai-agent.git
# change to project git local directory
cd math-ai-agent
# ensure we are at the project git local root folder
cd $(git rev-parse --show-toplevel) || exit
poetry install
```

## Usage

### Configuration

The server ships with a default
[config.yaml](https://github.com/rubensgomes-org/math-ai-agent/blob/main/src/math_ai_agent/config/config.yaml)
bundled inside the PyPI package. To override it, set the `MATHAIAGENT_CONFIG`
environment variable to the absolute path of your custom configuration file:

```bash
# assuming config_local.yaml placed in my home folder
export MATHAIAGENT_CONFIG="${HOME}/cfg/math-ai-agent/config_local.yaml"
```

### Running Using PyPI Package - Calculator MCP Server Local

**NOTE:** requires `calculator-mcp` running locally.

1. Make a copy of
   [config_local.yaml](https://github.com/rubensgomes-org/math-ai-agent/blob/main/config/config_local.yaml)
   to a local home directory (e.g.,
   `${HOME}/cfg/math-ai-agent/config_local.yaml`).

2. Launch the PyPI-installed `math-ai-agent` package:

```bash
export MATHAIAGENT_CONFIG="${HOME}/cfg/math-ai-agent/config_local.yaml"
math-ai-agent
```

3. Health check

```bash
# port is set by web.port in config_local.yaml
curl -v http://localhost:9090/health
# Expect: OK
```

4. To stop, go to the running terminal and press `Ctrl+C`

### Running Using PyPI Package - Calculator MCP Server Remote

**NOTE:** The `calculator-mcp` is deployed
at https://rubens-calculator-mcp.fastmcp.app/mcp hosted on Prefect Horizon.
Horizon puts OAuth in front of the server, and the sign-in is through GitHub.

1. Make a copy of
   [config_remote.yaml](https://github.com/rubensgomes-org/math-ai-agent/blob/main/config/config_remote.yaml)
   to a local home directory (e.g.,
   `${HOME}/cfg/math-ai-agent/config_remote.yaml`).

2. Delete any previously stored OAuth tokens:

```bash
rm -fr "${HOME}/.calc-mcp-token"
```

3. Launch the PyPI-installed `math-ai-agent` package:

```bash
export MATHAIAGENT_CONFIG="${HOME}/cfg/math-ai-agent/config_remote.yaml"
math-ai-agent
```

4. Authenticate with GitHub -- currently only Rubens can grante this access

5. Health check

```bash
# port is set by web.port in config_local.yaml
curl -v http://localhost:9090/health
# Expect: OK
```

6. To stop, go to the running terminal and press `Ctrl+C`

### Running Using Git Cloned Project - Calculator MCP Server Local

**NOTE:** requires the `calculator_mcp` running locally as per instructions at
[calculator-mcp](https://github.com/rubensgomes-org/calculator-mcp)

1. Make a copy of
   [config_local.yaml](https://github.com/rubensgomes-org/math-ai-agent/blob/main/config/config_local.yaml)
   to a local home directory (e.g.,
   `${HOME}/cfg/math-ai-agent/config_local.yaml`).

2. Launch `math-ai-agent` from the local Git repo folder

```bash
# On my machine the project is installed here:
pushd ~/github/rubens/dev/python/math-ai-agent/
# ensure we are at the project git local root folder
cd $(git rev-parse --show-toplevel) || exit
# config_local.yaml placed in my home folder
export MATHAIAGENT_CONFIG="${HOME}/cfg/math-ai-agent/config_local.yaml"
# ensure below port does not conflict with locally running MCP server.
poetry run math-ai-agent
```

3. Health check

```bash
curl -v http://localhost:9090/health
# Expect: OK
```

4. To stop, go to the running terminal and press `Ctrl+C`

### Calculator MCP Server Running Remotely - OAuth Authentication

**NOTE:** requires OAuth authentication which currently only Rubens is able to
authorize using his personal GitHub account.

1. Make a copy of
   [config_remote.yaml](https://github.com/rubensgomes-org/math-ai-agent/blob/main/config/config_remote.yaml)
   to a local home directory (e.g.,
   `${HOME}/cfg/math-ai-agent/config_remote.yaml`).

2. Launch `math-ai-agent` from the local Git repo folder

```bash
# On my machine the project is installed here:
pushd ~/github/rubens/dev/python/math-ai-agent/
# ensure we are at the project git local root folder
cd $(git rev-parse --show-toplevel) || exit
# config_remote.yaml placed in my home folder
export MATHAIAGENT_CONFIG="${HOME}/cfg/math-ai-agent/config_remote.yaml"
# clean up previously created OAuth tokens
rm -fr ~/.calc-mcp-token
poetry run math-ai-agent
```

3. Health check

```bash
curl -v http://localhost:9090/health
# Expect: OK
```

4. To stop, go to the running terminal and press `Ctrl+C`

## License

The project is licensed under
[MIT License](https://github.com/rubensgomes-org/math-ai-agent/blob/main/LICENSE).

---
Author: [Rubens Gomes](https://rubensgomes.com/)

