Amy - Agentic Mathematical Engine

An intelligent computational reasoning system for scientific research

Note: This project is an experiment and a work in progress. All contributions are welcome!

The Problem

Scientists and engineers face a gap between what they want to compute and how to compute it:

• Traditional tools require specifying exact operations: "Differentiate x² + 2x"
• But researchers think in goals: "Find where this function has extrema"
• Complex problems require chaining multiple tools across domains
• Manual verification is tedious and error-prone
• Results lack reasoning traces for reproducibility

The Solution

Agentic Mathematical Engine bridges this gap with an intelligent agent that:

• Understands natural language mathematical queries
• Plans multi-step solutions automatically
• Executes computations across seven mathematical domains
• Verifies results for correctness and physical validity
• Explains reasoning traces for full transparency

How It Works

1. Describe your goal in natural language
2. Agent decomposes the problem into sub-goals
3. Tools execute the required computations
4. Verification ensures correctness
5. Explanation provides reasoning trace

using AgenticMathematicalEngine

# Natural language query
response = solve("Design a Hohmann transfer from Earth to Mars with minimum fuel")

# Get results with full explanation
println(response.result)       # Δv = 5.59 km/s, transfer time = 259 days
println(response.explanation)  # Step-by-step reasoning
println(response.confidence)   # 0.95

Features

Seven Mathematical Domains

Domain	Capabilities
Symbolic	Algebra, calculus, equation solving, simplification
Numerical	ODEs, PDEs, integration, optimization, N-body simulation
Tensor	General relativity, differential geometry, index manipulation
Coordinate	Reference frames, orbital mechanics, unit conversion
Propulsion	Rocket equations, delta-v budgets, trajectory optimization
Linear Algebra	Eigenanalysis, decompositions, matrix calculus
Physics	Electromagnetism, thermodynamics, fluids, quantum mechanics

Intelligent Agent Capabilities

• Dynamic Planning — Automatically decomposes complex problems
• Tool Selection — Chooses appropriate methods for each sub-goal
• Verification — Checks units, conservation laws, physical bounds
• Replanning — Adapts when approaches fail
• Explanation — Generates reasoning traces for reproducibility

Built-in Knowledge

• Solar system body data (planets, moons)
• Physical constants with units
• Material properties
• Reference values for verification

Installation

Prerequisites

• Julia 1.9 or higher
• ~2GB disk space for dependencies

Install from Source

git clone https://github.com/agenisea/agentic-mathematical-engine.git
cd agentic-mathematical-engine
julia --project=. -e 'using Pkg; Pkg.instantiate()'

LLM Configuration

Amy uses Ollama with DeepSeek-R1 for LLM-powered reasoning. Ensure Ollama is running locally:

# Install Ollama (macOS)
brew install ollama

# Pull the DeepSeek-R1 model
ollama pull deepseek-r1:latest

# Start Ollama server (runs on localhost:11434 by default)
ollama serve

Usage

Basic Usage

using AgenticMathematicalEngine

# Simple query
response = solve("What is the derivative of x³ + 2x²?")
println(response.result)  # 3x² + 4x

# Trajectory design
response = solve("Design a Hohmann transfer from LEO (400km) to GEO")
println(response.result.delta_v_total)  # ~3.9 km/s

# Stability analysis
response = solve("Is the L4 Lagrange point stable for the Sun-Earth system?")
println(response.result)  # STABLE (with eigenvalue analysis)

Multi-turn Conversations

agent = Agent()

response1 = agent("Set up a simple harmonic oscillator with ω = 5 rad/s")
response2 = agent("Now add damping with ζ = 0.3")
response3 = agent("Find the damped natural frequency")

Configuration

config = AgentConfig(
    max_tool_calls = 50,
    verification_level = :thorough,  # :minimal, :standard, :thorough
    explanation_detail = :verbose,   # :brief, :standard, :verbose
    timeout_seconds = 300,
)

response = solve("Complex multi-step problem...", config=config)

Examples

The examples/ directory contains comprehensive demonstrations:

Example	Description
llm_demo.jl	Interactive LLM demo with real-time event streaming
trajectory_design.jl	Orbital mechanics, mission design, gravity assists
stability_analysis.jl	Eigenvalue analysis, Lagrange points, control systems
physics_simulation.jl	Heat transfer, E&M, quantum mechanics, N-body
symbolic_derivation.jl	Calculus, series expansions, tensor calculus

Run an example:

julia --project=. examples/trajectory_design.jl

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                         USER QUERY                              │
│  "Design a Hohmann transfer from Earth to Mars"                 │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                      REASONING AGENT                            │
│  ┌────────────┐  ┌────────────┐  ┌────────────┐  ┌───────────┐  │
│  │ UNDERSTAND │→ │   PLAN     │→ │  EXECUTE   │→ │  VERIFY   │  │
│  │            │  │            │  │            │  │           │  │
│  │ Parse      │  │ Decompose  │  │ Run tools  │  │ Check     │  │
│  │ intent     │  │ into goals │  │ Get results│  │ results   │  │
│  └────────────┘  └────────────┘  └────────────┘  └───────────┘  │
│                                                                 │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │                    WORKING MEMORY                        │   │
│  │  • Goal stack  • Intermediate results  • Confidence      │   │
│  └──────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌────────────────────────────────────────────────────────────────┐
│                        TOOL SUITE                              │
│  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌──────────┐  │
│  │SYMBOLIC │ │NUMERICAL│ │ TENSOR  │ │COORD    │ │PROPULSION│  │
│  │         │ │         │ │         │ │         │ │          │  │
│  │simplify │ │solve_ode│ │riemann  │ │kepler   │ │hohmann   │  │
│  │diff     │ │optimize │ │geodesic │ │ephemeris│ │lambert   │  │
│  │integrate│ │nbody    │ │contract │ │transform│ │delta_v   │  │
│  └─────────┘ └─────────┘ └─────────┘ └─────────┘ └──────────┘  │
│  ┌─────────┐ ┌─────────┐ ┌────────────────────────────────┐    │
│  │ MATRIX  │ │ PHYSICS │ │         VERIFICATION           │    │
│  │         │ │         │ │                                │    │
│  │eigen    │ │maxwell  │ │ check_units  check_conservation│    │
│  │decompose│ │heat     │ │ check_bounds numerical_verify  │    │
│  │jacobian │ │quantum  │ │                                │    │
│  └─────────┘ └─────────┘ └────────────────────────────────┘    │
└────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                          OUTPUT                                 │
│  Result: Δv_total = 5.59 km/s, Transfer time = 259 days         │
│  Reasoning: Decomposed into orbital parameters, vis-viva...     │
│  Confidence: 0.95 (verified against reference data)             │
└─────────────────────────────────────────────────────────────────┘

Multi-Agent LLM Pipeline

Amy uses 5 specialized LLM agents orchestrated by a supervisor:

┌─────────────────────────────────────────────────────────────────────────────┐
│                           LLM AGENT PIPELINE                                │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐                      │
│  │ INTERPRETER │───▶│   PLANNER   │───▶│  EXECUTOR   │                      │
│  │             │    │             │    │             │                      │
│  │ Parse query │    │ Decompose   │    │ Map goals   │                      │
│  │ Extract     │    │ into goal   │    │ to tools    │                      │
│  │ intent      │    │ DAG         │    │ Execute     │                      │
│  └─────────────┘    └─────────────┘    └──────┬──────┘                      │
│                                               │                             │
│                      ┌────────────────────────┴────────────────────┐        │
│                      │                                             │        │
│                      ▼                                             ▼        │
│               ┌─────────────┐                              ┌─────────────┐  │
│               │  VERIFIER   │                              │  EXPLAINER  │  │
│               │             │                              │             │  │
│               │ Validate    │                              │ Generate    │  │
│               │ results     │                              │ natural     │  │
│               │ Check units │                              │ language    │  │
│               │ & bounds    │                              │ explanation │  │
│               └─────────────┘                              └─────────────┘  │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

Agent	Role	Output Format
INTERPRETER	Parse natural language, extract intent & entities	Structured JSON intent
PLANNER	Decompose problem into goal DAG	Goal nodes with dependencies
EXECUTOR	Map goals to tools, prepare parameters	Tool call specifications
VERIFIER	Validate results against physical laws	Pass/Warn/Fail verdict
EXPLAINER	Generate human-readable explanations	Summary with LaTeX equations

Parallel Execution Architecture (Fan-Out/Fan-In)

Amy uses a DAG-based parallel execution model to maximize throughput when goals are independent:

                         ┌─────────────────────────────────────┐
                         │           PLANNER                   │
                         │   Creates Goal DAG with deps        │
                         └──────────────┬──────────────────────┘
                                        │
                                        ▼
                    ┌───────────────────────────────────────────┐
                    │          PARALLEL SCHEDULER               │
                    │   Identifies independent goals            │
                    │   Groups into execution batches           │
                    └───────────────────┬───────────────────────┘
                                        │
          ┌─────────────────────────────┼─────────────────────────────┐
          │                             │                             │
          ▼                             ▼                             ▼
   ══════════════════════════════════════════════════════════════════════
                              FAN-OUT PHASE
   ══════════════════════════════════════════════════════════════════════
          │                             │                             │
          ▼                             ▼                             ▼
   ┌─────────────┐               ┌─────────────┐               ┌─────────────┐
   │   GOAL 1    │               │   GOAL 2    │               │   GOAL 3    │
   │   (no deps) │               │   (no deps) │               │   (no deps) │
   │             │               │             │               │             │
   │  Execute    │               │  Execute    │               │  Execute    │
   │  Tool A     │               │  Tool B     │               │  Tool C     │
   └──────┬──────┘               └──────┬──────┘               └──────┬──────┘
          │                             │                             │
          ▼                             ▼                             ▼
   ┌─────────────┐               ┌─────────────┐               ┌─────────────┐
   │  VERIFIER   │               │  VERIFIER   │               │  VERIFIER   │
   │  (parallel) │               │  (parallel) │               │  (parallel) │
   └──────┬──────┘               └──────┬──────┘               └──────┬──────┘
          │                             │                             │
          └─────────────────────────────┼─────────────────────────────┘
                                        │
   ══════════════════════════════════════════════════════════════════════
                               FAN-IN PHASE
   ══════════════════════════════════════════════════════════════════════
                                        │
                                        ▼
                         ┌─────────────────────────────────────┐
                         │       THREAD-SAFE MEMORY            │
                         │   Collects results from all goals   │
                         │   Tracks verification status        │
                         └──────────────┬──────────────────────┘
                                        │
                                        ▼
                         ┌─────────────────────────────────────┐
                         │          NEXT BATCH                 │
                         │   Goals with satisfied deps         │
                         └──────────────┬──────────────────────┘
                                        │
          ┌─────────────────────────────┼─────────────────────────────┐
          │                             │                             │
          ▼                             ▼                             ▼
   ┌─────────────┐               ┌─────────────┐               ┌─────────────┐
   │   GOAL 4    │               │   GOAL 5    │               │   GOAL 6    │
   │ (deps: 1,2) │               │ (deps: 2,3) │               │ (deps: 1)   │
   └─────────────┘               └─────────────┘               └─────────────┘
                                        │
                                        ▼
                         ┌─────────────────────────────────────┐
                         │          EXPLAINER                  │
                         │   Generates unified explanation     │
                         └─────────────────────────────────────┘

Key Features of Parallel Execution

Feature	Description
DAG Scheduling	Goals form a directed acyclic graph; independent goals run concurrently
Batch Execution	Goals grouped into batches based on dependency satisfaction
Thread-Safe Memory	Concurrent writes protected with ReentrantLock
Parallel Verification	Each goal verified independently, can run alongside next batch
Automatic Fallback	Falls back to sequential execution for single-goal plans
Budget Management	Token budgets tracked per-agent with atomic counters

Execution Modes

# Automatic mode selection based on goal count and dependencies
config = PipelineConfig(
    enable_parallel_execution = true,   # Enable parallel when beneficial
    max_concurrent_goals = 4,           # Max parallel goals
    enable_parallel_verification = true # Verify concurrently
)

When Parallel Execution is Used:

• Plan has 2+ goals
• Goals have independent dependencies (can run in parallel batches)
• Budget permits concurrent LLM calls

When Sequential Execution is Used:

• Single goal plans
• Strictly linear dependencies (each goal depends on previous)
• Fallback mode (budget/circuit breaker constraints)

Project Structure

agentic-mathematical-engine/
├── Project.toml              # Julia package manifest
├── Manifest.toml             # Dependency lock file
├── README.md                 # This file
├── CONTRIBUTING.md           # Contribution guidelines
├── CODE_OF_CONDUCT.md        # Community standards
├── SECURITY.md               # Security policy
│
├── src/
│   ├── AgenticMathematicalEngine.jl  # Main module
│   │
│   ├── types/                # Core type definitions
│   │   ├── goals.jl          # Goal & GoalStatus
│   │   ├── plans.jl          # Plan & PlanStatus
│   │   ├── memory.jl         # WorkingMemory
│   │   ├── tools.jl          # ToolDefinition
│   │   └── results.jl        # AgentResponse, Explanation
│   │
│   ├── agent/                # Agent components
│   │   ├── core.jl           # Main agent loop
│   │   ├── understanding.jl  # Intent parsing
│   │   ├── planning.jl       # Problem decomposition
│   │   ├── execution.jl      # Tool invocation
│   │   ├── verification.jl   # Result checking
│   │   └── explanation.jl    # Reasoning traces
│   │
│   ├── tools/                # Mathematical tools
│   │   ├── registry.jl       # Tool registry
│   │   ├── symbolic.jl       # Symbolic math
│   │   ├── numerical.jl      # Numerical methods
│   │   ├── tensor.jl         # Tensor algebra
│   │   ├── coordinate.jl     # Coordinate systems
│   │   ├── propulsion.jl     # Propulsion tools
│   │   ├── matrix.jl         # Linear algebra
│   │   ├── physics.jl        # Physics tools
│   │   └── verification.jl   # Verification tools
│   │
│   ├── strategies/           # Problem-solving strategies
│   │   ├── base.jl           # Strategy interface
│   │   ├── trajectory.jl     # Trajectory design
│   │   ├── stability.jl      # Stability analysis
│   │   ├── derivation.jl     # Mathematical derivation
│   │   ├── simulation.jl     # Physics simulation
│   │   └── optimization.jl   # Optimization problems
│   │
│   ├── knowledge/            # Built-in knowledge
│   │   ├── constants.jl      # Physical constants
│   │   ├── bodies.jl         # Celestial body data
│   │   ├── materials.jl      # Material properties
│   │   └── references.jl     # Reference values
│   │
│   ├── util/                 # Utilities
│   │   ├── units.jl          # Unit handling
│   │   ├── latex.jl          # LaTeX generation
│   │   └── logging.jl        # Logging utilities
│   │
│   ├── llm/                  # LLM Integration Layer
│   │   ├── client.jl         # Ollama client
│   │   ├── events.jl         # Event streaming
│   │   ├── parser.jl         # Response parsing
│   │   ├── prompts.jl        # Agent prompts
│   │   └── fallback.jl       # Fallback handlers
│   │
│   ├── orchestration/        # Multi-Agent Orchestration
│   │   ├── supervisor.jl     # Pipeline supervisor
│   │   ├── parallel.jl       # Parallel execution
│   │   ├── budget.jl         # Token budget management
│   │   └── resilience.jl     # Circuit breakers
│   │
│   └── prompts/              # Agent System Prompts
│       ├── interpreter.md    # Intent parsing prompt
│       ├── planner.md        # Goal decomposition prompt
│       ├── executor.md       # Tool invocation prompt
│       ├── verifier.md       # Result validation prompt
│       └── explainer.md      # Explanation generation prompt
│
├── examples/                 # Example scripts
│   ├── trajectory_design.jl
│   ├── stability_analysis.jl
│   ├── physics_simulation.jl
│   └── symbolic_derivation.jl
│
└── test/                     # Test suite
    ├── runtests.jl
    ├── unit/
    ├── integration/
    └── validation/

Tech Stack

• Julia 1.9+ — High-performance scientific computing
• Symbolics.jl — Computer algebra system
• DifferentialEquations.jl — ODE/PDE solvers
• Unitful.jl — Physical units with type safety
• Optim.jl — Optimization algorithms
• LinearAlgebra — Matrix operations
• ForwardDiff.jl — Automatic differentiation

Design Artifacts

This repo includes the original planning and agent-design docs used to architect the system—shared intentionally for transparency and reuse. These documents are optional; the engine runs independently of them.

• docs/blueprompt.md — App design spec (blueprompt.app)
• docs/agenisea.md — Multi-agent architecture spec

Roadmap

• Core agent architecture
• Seven mathematical domains
• Verification system
• Comprehensive examples
• LLM integration (Ollama/DeepSeek-R1)
• Multi-agent orchestration (5 specialized agents)
• Parallel execution with fan-out/fan-in
• Token budget management
• Circuit breaker resilience
• Web interface
• Jupyter notebook integration
• GPU acceleration for N-body
• More physics domains (plasma, relativity)

Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

Quick Start for Contributors

# Clone and setup
git clone https://github.com/agenisea/agentic-mathematical-engine.git
cd agentic-mathematical-engine
julia --project=. -e 'using Pkg; Pkg.instantiate()'

# Run tests
julia --project=. -e 'using Pkg; Pkg.test()'

# Run examples
julia --project=. examples/trajectory_design.jl

License

MIT License - see LICENSE for details.

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions

---

Built by Agenisea™ 🪼