https://github.com/agenisea/agentic-mathematical-engine
An intelligent Julia agent for scientific computing with natural language queries and multi-domain mathematical reasoning.
https://github.com/agenisea/agentic-mathematical-engine
agentic deepseek-r1 julia julia-language julialang multi-agent-system reasoning-agent scientific
Last synced: 18 days ago
JSON representation
An intelligent Julia agent for scientific computing with natural language queries and multi-domain mathematical reasoning.
- Host: GitHub
- URL: https://github.com/agenisea/agentic-mathematical-engine
- Owner: agenisea
- License: mit
- Created: 2025-12-13T07:33:55.000Z (30 days ago)
- Default Branch: main
- Last Pushed: 2025-12-14T01:53:12.000Z (29 days ago)
- Last Synced: 2025-12-15T18:57:56.176Z (27 days ago)
- Topics: agentic, deepseek-r1, julia, julia-language, julialang, multi-agent-system, reasoning-agent, scientific
- Language: Julia
- Homepage:
- Size: 152 KB
- Stars: 2
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
Awesome Lists containing this project
README
# Amy - Agentic Mathematical Engine
**An intelligent computational reasoning system for scientific research**
[](https://opensource.org/licenses/MIT)
> **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
```julia
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
```bash
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:
```bash
# 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
```julia
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
```julia
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
```julia
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:
```bash
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
```julia
# 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`](docs/blueprompt.md) — App design spec ([blueprompt.app](https://blueprompt.app))
- [`docs/agenisea.md`](docs/agenisea.md) — Multi-agent architecture spec
## Roadmap
- [x] Core agent architecture
- [x] Seven mathematical domains
- [x] Verification system
- [x] Comprehensive examples
- [x] LLM integration (Ollama/DeepSeek-R1)
- [x] Multi-agent orchestration (5 specialized agents)
- [x] Parallel execution with fan-out/fan-in
- [x] Token budget management
- [x] 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](CONTRIBUTING.md) for guidelines.
### Quick Start for Contributors
```bash
# 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](LICENSE) for details.
## Support
- **Issues**: [GitHub Issues](https://github.com/agenisea/agentic-mathematical-engine/issues)
- **Discussions**: [GitHub Discussions](https://github.com/agenisea/agentic-mathematical-engine/discussions)
---
Built by Agenisea™ 🪼