math-ai-agent 0.0.1__py3-none-any.whl

math_ai_agent/__init__.py

@@ -0,0 +1,39 @@
+# General Disclaimer
+#
+# **AI Generated Content**
+#
+# This project's source code and documentation were generated predominantly
+# by an Artificial Intelligence Large Language Model (AI LLM). The project
+# lead, [Rubens Gomes](https://rubensgomes.com), provided initial prompts,
+# reviewed, and made refinements to the generated output. While human review and
+# refinement have occurred, users should be aware that the output may contain
+# inaccuracies, errors, or security vulnerabilities
+#
+# **Third-Party Content Notice**
+#
+# This software may include components or snippets derived from third-party
+# sources. The software's users and distributors are responsible for ensuring
+# compliance with any underlying licenses applicable to such components.
+#
+# **Copyright Status Statement**
+#
+# Copyright protection, if any, is limited to the original
+# human contributions and modifications made to this project.
+# The AI-generated portions of the code and
+# documentation are not subject to copyright and are considered to be in the
+# public domain.
+#
+# **Limitation of liability**
+#
+# IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+# DAMAGES, OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT, OR
+# OTHERWISE, ARISING FROM, OUT OF, OR IN CONNECTION WITH THE SOFTWARE OR THE USE
+# OR OTHER DEALINGS IN THE SOFTWARE.
+#
+# **No-Warranty Disclaimer**
+#
+# THIS SOFTWARE IS PROVIDED 'AS IS,' WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT.
+
+"""math_ai_agent — Math AI Agent package."""

math_ai_agent/app.py

@@ -0,0 +1,109 @@
+# General Disclaimer
+#
+# **AI Generated Content**
+#
+# This project's source code and documentation were generated predominantly
+# by an Artificial Intelligence Large Language Model (AI LLM). The project
+# lead, [Rubens Gomes](https://rubensgomes.com), provided initial prompts,
+# reviewed, and made refinements to the generated output. While human review and
+# refinement have occurred, users should be aware that the output may contain
+# inaccuracies, errors, or security vulnerabilities
+#
+# **Third-Party Content Notice**
+#
+# This software may include components or snippets derived from third-party
+# sources. The software's users and distributors are responsible for ensuring
+# compliance with any underlying licenses applicable to such components.
+#
+# **Copyright Status Statement**
+#
+# Copyright protection, if any, is limited to the original
+# human contributions and modifications made to this project.
+# The AI-generated portions of the code and
+# documentation are not subject to copyright and are considered to be in the
+# public domain.
+#
+# **Limitation of liability**
+#
+# IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+# DAMAGES, OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT, OR
+# OTHERWISE, ARISING FROM, OUT OF, OR IN CONNECTION WITH THE SOFTWARE OR THE USE
+# OR OTHER DEALINGS IN THE SOFTWARE.
+#
+# **No-Warranty Disclaimer**
+#
+# THIS SOFTWARE IS PROVIDED 'AS IS,' WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT.
+
+"""The FastAPI web server app.
+
+Launches a FastAPI web server with the following endpoints:
+    - `GET /` returns the index.html page.
+    - `POST /prompt/` submits user prompt and returns AI response.
+
+From the project root folder run::
+
+    poetry run uvicorn math_ai_agent.app:app --reload
+"""
+
+import json
+import logging
+from pathlib import Path
+
+from fastapi import FastAPI
+from fastapi.responses import HTMLResponse
+from fastapi.staticfiles import StaticFiles
+
+from math_ai_agent.config.config import configure_logging
+from math_ai_agent.llm import agent_loop
+from math_ai_agent.prompt import Prompt
+
+configure_logging()
+logger = logging.getLogger(__name__)
+
+# folder to HTML file
+_STATIC_DIR = Path(__file__).parent / "static"
+
+# -------------------------------------------------
+# Create the FastAPI app instance
+# -------------------------------------------------
+app = FastAPI()
+app.mount("/static", StaticFiles(directory=_STATIC_DIR), name="static")
+
+
+# -------------------------------------------------
+# Routes
+# -------------------------------------------------
+@app.get("/", response_class=HTMLResponse)
+async def root() -> str:
+    """Serve the main HTML page.
+
+    Returns:
+        The HTML content of the index page.
+    """
+    logger.debug("Serving root HTML page: %s%s", _STATIC_DIR, "/index.html")
+    return (_STATIC_DIR / "index.html").read_text()
+
+
+@app.post("/prompt/")
+async def prompt(payload: Prompt) -> dict[str, str]:
+    """Accept a prompt text from the user and return an answer.
+
+    Args:
+        payload: The validated question from the request body.
+
+    Returns:
+        A dict containing the `answer` key with the response.
+
+    Raises:
+        RuntimeError: If the agent loop encounters a token limit
+            or content filter error.
+        ValueError: If the LLM returns an unknown finish reason.
+    """
+    logger.debug("Received prompt: %s", payload.text)
+    prompt_text = payload.text.strip()
+    logger.debug("Calling LLM with user prompt: %s", prompt_text)
+    output = await agent_loop(prompt_text)
+    logger.debug("Output:\n%s", json.dumps(output, indent=2))
+    return {"answer": output}

math_ai_agent/config/__init__.py

@@ -0,0 +1,39 @@
+# General Disclaimer
+#
+# **AI Generated Content**
+#
+# This project's source code and documentation were generated predominantly
+# by an Artificial Intelligence Large Language Model (AI LLM). The project
+# lead, [Rubens Gomes](https://rubensgomes.com), provided initial prompts,
+# reviewed, and made refinements to the generated output. While human review and
+# refinement have occurred, users should be aware that the output may contain
+# inaccuracies, errors, or security vulnerabilities
+#
+# **Third-Party Content Notice**
+#
+# This software may include components or snippets derived from third-party
+# sources. The software's users and distributors are responsible for ensuring
+# compliance with any underlying licenses applicable to such components.
+#
+# **Copyright Status Statement**
+#
+# Copyright protection, if any, is limited to the original
+# human contributions and modifications made to this project.
+# The AI-generated portions of the code and
+# documentation are not subject to copyright and are considered to be in the
+# public domain.
+#
+# **Limitation of liability**
+#
+# IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+# DAMAGES, OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT, OR
+# OTHERWISE, ARISING FROM, OUT OF, OR IN CONNECTION WITH THE SOFTWARE OR THE USE
+# OR OTHER DEALINGS IN THE SOFTWARE.
+#
+# **No-Warranty Disclaimer**
+#
+# THIS SOFTWARE IS PROVIDED 'AS IS,' WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT.
+
+"""config — configuration sub-package for math_ai_agent."""

math_ai_agent/config/config.py

@@ -0,0 +1,148 @@
+# General Disclaimer
+#
+# **AI Generated Content**
+#
+# This project's source code and documentation were generated predominantly
+# by an Artificial Intelligence Large Language Model (AI LLM). The project
+# lead, [Rubens Gomes](https://rubensgomes.com), provided initial prompts,
+# reviewed, and made refinements to the generated output. While human review and
+# refinement have occurred, users should be aware that the output may contain
+# inaccuracies, errors, or security vulnerabilities
+#
+# **Third-Party Content Notice**
+#
+# This software may include components or snippets derived from third-party
+# sources. The software's users and distributors are responsible for ensuring
+# compliance with any underlying licenses applicable to such components.
+#
+# **Copyright Status Statement**
+#
+# Copyright protection, if any, is limited to the original
+# human contributions and modifications made to this project.
+# The AI-generated portions of the code and
+# documentation are not subject to copyright and are considered to be in the
+# public domain.
+#
+# **Limitation of liability**
+#
+# IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+# DAMAGES, OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT, OR
+# OTHERWISE, ARISING FROM, OUT OF, OR IN CONNECTION WITH THE SOFTWARE OR THE USE
+# OR OTHER DEALINGS IN THE SOFTWARE.
+#
+# **No-Warranty Disclaimer**
+#
+# THIS SOFTWARE IS PROVIDED 'AS IS,' WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT.
+
+"""Configuration helpers — loads config.yaml and configures logging."""
+
+import functools
+import logging
+import logging.config
+import os
+from importlib.resources import files
+from pathlib import Path
+from typing import Any, Literal
+
+import yaml
+from pydantic import BaseModel
+
+logger = logging.getLogger(__name__)
+
+
+class LLMConfig(BaseModel):
+    """The ``llm`` section of config.yaml."""
+
+    api_style: Literal["chat", "responses"] = "chat"
+    model_base_url: str
+    model: str
+    api_key_env: str
+    system_instructions: str
+
+
+class CalculatorMCPConfig(BaseModel):
+    """The ``server.calculator_mcp`` section of config.yaml."""
+
+    url: str
+    is_oauth: bool = False
+    token_dir: str
+    callback_port: int
+
+
+class ServerConfig(BaseModel):
+    """The ``server`` section of config.yaml."""
+
+    calculator_mcp: CalculatorMCPConfig
+
+
+class AppConfig(BaseModel):
+    """The full config.yaml; ``logging`` is a ``dictConfig`` mapping."""
+
+    llm: LLMConfig
+    server: ServerConfig
+    logging: dict[str, Any]
+
+
+def _resolve_config_path() -> Path:
+    """Return the config.yaml path.
+
+    Resolution order:
+
+    1. The ``MATHAIAGENT_CONFIG`` environment variable, when set.
+    2. The ``config.yaml`` bundled inside the
+       ``math_ai_agent.config`` package.
+
+    Returns:
+        The resolved path to config.yaml.
+    """
+    env_path = os.environ.get("MATHAIAGENT_CONFIG")
+    if env_path:
+        return Path(env_path)
+    return Path(str(files("math_ai_agent.config").joinpath("config.yaml")))
+
+
+def load_config(path: Path) -> AppConfig:
+    """Parse and validate the config file at ``path``.
+
+    Raises:
+        pydantic.ValidationError: If the file does not match the models.
+    """
+    with open(path, encoding="utf-8") as f:
+        return AppConfig.model_validate(yaml.safe_load(f))
+
+
+@functools.cache
+def get_config() -> AppConfig:
+    """Return the application config, loaded once on first call."""
+    return load_config(_resolve_config_path())
+
+
+def configure_logging() -> None:
+    """Apply the logging configuration from config.yaml."""
+    logging.config.dictConfig(get_config().logging)
+    logger.debug("Loaded config from %s", _resolve_config_path())
+
+
+def get_api_key() -> str:
+    """Return the LLM API key from the environment.
+
+    The config.yaml ``llm.api_key_env`` setting names the environment
+    variable holding the key; the key value itself is never stored in
+    config.yaml.  Only the variable name is logged, never the key.
+
+    Returns:
+        The API key read from the configured environment variable.
+
+    Raises:
+        RuntimeError: If the environment variable is not set or empty.
+    """
+    env_name = get_config().llm.api_key_env
+    logger.info("LLM API key environment variable: %s", env_name)
+    api_key = os.environ.get(env_name)
+    if not api_key:
+        error = f"{env_name} environment variable is not set."
+        logger.error(error)
+        raise RuntimeError(error)
+    return api_key

math_ai_agent/config/config.yaml

@@ -0,0 +1,143 @@
+# =============================================================================
+# LLM Configuration
+# =============================================================================
+llm:
+    # Which OpenAI API the LLM client uses:
+    #   "responses" -> POST /v1/responses         (primary OpenAI API)
+    #   "chat"      -> POST /v1/chat/completions  (legacy, still supported)
+    # Both work against NVIDIA nemotron models
+    api_style: "responses"
+    # Base NVIDIA LLM models URL
+    model_base_url: "https://integrate.api.nvidia.com/v1"
+    # Nemotron frontier NVIDIA models for agentic workflows, coding and tool use
+    # See list of NVIDIA models: https://integrate.api.nvidia.com/v1/models
+    model: "nvidia/nemotron-3-super-120b-a12b"
+    # Name of the environment variable holding the API key.
+    # Get a key from https://build.nvidia.com (keys start with "nvapi-").
+    api_key_env: "NVIDIA_API_KEY"
+    # System prompt sent to the **stateless** LLM on every request.
+    system_instructions: >-
+        You are a careful math assistant tutor helping solve math problems.
+        Always write a short plan first. Do NOT do arithmetic in your head.
+        For every math operation, request a tool call to the calculator.
+        After tool results, continue. Provide final answer with explanation.
+        Respond in plain text only. Do NOT use LaTeX, Markdown, or any other
+        special formatting: no backslashes, no asterisks, no dollar-sign or
+        parenthesis math delimiters. Write math inline, like 4 x 3 = 12.
+        Your answer is shown in a plain text box that cannot render
+        formatting.
+
+    # OpenRouter alternative. Its free tier allows only 50 requests per
+    # day, after which requests fail with 429 free-models-per-day. The
+    # ":free" suffix is OpenRouter slug syntax and is not a valid model
+    # id on any other provider.
+    #   model_base_url: "https://openrouter.ai/api/v1"
+    #   model: "nvidia/nemotron-3-super-120b-a12b:free"
+    #   api_key_env: "OPENROUTER_API_KEY"
+    # Local Ollama alternative (see OLLAMA.md):
+    #   model_base_url: "http://localhost:11434/v1"
+    #   model: "phi"
+
+# =============================================================================
+# Calculator MCP Server Configuration
+# =============================================================================
+server:
+    calculator_mcp:
+        # URL of the Calculator MCP Server End-Point
+        # url: "http://127.0.0.1:8080/mcp"
+        # Hosted, deployed and running for free at Prefect
+        #   https://www.prefect.io/horizon
+        url: "https://rubens-calculator-mcp.fastmcp.app/mcp"
+        # is_oauth: false
+        # Prefect requires OAuth authentication. Currently only Rubens is able
+        # to authorize using his personal GitHub account.
+        is_oauth: true
+        # location to store OAuth token
+        token_dir: "~/.mathaiagent"
+        # local port temporarily used by the OAuth callback server during
+        # OAuth handshaking.
+        callback_port: 10000
+
+# =============================================================================
+# Logging Configuration
+# =============================================================================
+logging:
+    version: 1
+    disable_existing_loggers: false
+    formatters:
+        # Colors level name and message; plain if stderr is not a TTY or NO_COLOR
+        # set environment variable NO_COLOR=true for plain text with no color.
+        standard:
+            (): colorlog.ColoredFormatter
+            fmt: "%(asctime)s %(log_color)s[%(levelname)s]%(reset)s %(fg_147)s%(name)s %(filename)s:%(lineno)d%(reset)s: %(log_color)s%(message)s%(reset)s"
+            datefmt: "%H:%M:%S"
+            log_colors:
+                DEBUG: cyan
+                INFO: light_green
+                WARNING: yellow
+                ERROR: red
+                CRITICAL: bold_red
+            stream: ext://sys.stderr
+    handlers:
+        console:
+            class: logging.StreamHandler
+            formatter: standard
+            stream: ext://sys.stderr
+    loggers:
+        math_ai_agent:
+            level: DEBUG
+            handlers:
+                - console
+            propagate: false
+        # MCP protocol tracing — set to DEBUG to see full JSON-RPC messages
+        mcp.client.streamable_http:
+            level: INFO
+            handlers:
+                - console
+            propagate: false
+        # HTTP request/response summaries — set to DEBUG for detail
+        httpx:
+            level: INFO
+            handlers:
+                - console
+            propagate: false
+        # OpenAI SDK logging — set to DEBUG for request/response detail
+        openai:
+            level: INFO
+            handlers:
+                - console
+            propagate: false
+        # HTTP wire-level tracing (headers, TCP) — set to DEBUG for detail
+        httpcore:
+            level: INFO
+            handlers:
+                - console
+            propagate: false
+        # Server: startup, shutdown, and errors
+        uvicorn:
+            level: INFO
+            handlers:
+                - console
+            propagate: false
+        # Server: HTTP request lines (method, path, status)
+        uvicorn.access:
+            level: INFO
+            handlers:
+                - console
+            propagate: false
+        # Integration tests (via pytest)
+        tests:
+            level: DEBUG
+            handlers:
+                - console
+            propagate: false
+        # Integration tests (run standalone)
+        __main__:
+            level: DEBUG
+            handlers:
+                - console
+            propagate: false
+    root:
+        level: WARNING
+        handlers:
+            - console

math_ai_agent/llm/__init__.py

@@ -0,0 +1,47 @@
+# General Disclaimer
+#
+# **AI Generated Content**
+#
+# This project's source code and documentation were generated predominantly
+# by an Artificial Intelligence Large Language Model (AI LLM). The project
+# lead, [Rubens Gomes](https://rubensgomes.com), provided initial prompts,
+# reviewed, and made refinements to the generated output. While human review and
+# refinement have occurred, users should be aware that the output may contain
+# inaccuracies, errors, or security vulnerabilities
+#
+# **Third-Party Content Notice**
+#
+# This software may include components or snippets derived from third-party
+# sources. The software's users and distributors are responsible for ensuring
+# compliance with any underlying licenses applicable to such components.
+#
+# **Copyright Status Statement**
+#
+# Copyright protection, if any, is limited to the original
+# human contributions and modifications made to this project.
+# The AI-generated portions of the code and
+# documentation are not subject to copyright and are considered to be in the
+# public domain.
+#
+# **Limitation of liability**
+#
+# IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+# DAMAGES, OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT, OR
+# OTHERWISE, ARISING FROM, OUT OF, OR IN CONNECTION WITH THE SOFTWARE OR THE USE
+# OR OTHER DEALINGS IN THE SOFTWARE.
+#
+# **No-Warranty Disclaimer**
+#
+# THIS SOFTWARE IS PROVIDED 'AS IS,' WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT.
+
+"""llm — LLM sub-package for math_ai_agent.
+
+Re-exports ``agent_loop`` so callers can use
+``from math_ai_agent.llm import agent_loop``.
+"""
+
+from math_ai_agent.llm.agent import agent_loop
+
+__all__ = ["agent_loop"]