SAGE — Solver-Augmented Grounding Engine

SAGE grounds AI in mathematical truth. It is a local MCP server that gives Claude Desktop — and any MCP-compatible agent — the ability to formulate, solve, and certify mathematical optimization problems using production-grade open-source solvers.

Status: v0.1.3 — Alpha · Author: Peter Pragnakar Atreides

Why SAGE Exists

Large Language Models are probabilistic text generators. When you ask an LLM to allocate a budget, design a schedule, optimize a route, or balance a portfolio, it generates text that resembles a solution. No simplex method runs underneath. No branch-and-bound search. No constraint check. The model cannot prove optimality, certify feasibility, or — critically — declare with certainty that no feasible solution exists.

One of the most valuable outcomes in decision-making is a mathematically certified statement of infeasibility. It tells decision-makers their goals conflict, their assumptions are inconsistent, or their constraints must be renegotiated. LLMs have no native mechanism to produce this. SAGE provides it.

SAGE introduces a hybrid intelligence architecture: LLMs handle language and ambiguity; solvers handle optimality and feasibility. Each component does what it is best suited for.

The Runtime Advantage

LLMs operate as single-pass inference systems — token generation stops when the response is done. Optimization solvers work differently: they are inherently iterative and stateful, designed to run for minutes, hours, or days while continuously improving. At any point they can return the best solution found so far, a bound on the optimal objective, and a certificate of optimality or infeasibility.

This "anytime" property enables SAGE to:

• Decompose large problems using Benders decomposition, column generation, or Lagrangian relaxation
• Run long-horizon solves asynchronously while the LLM remains conversationally responsive
• Checkpoint, pause, and resume optimization without losing progress

The result: AI shifts from immediate but approximate to sustained and mathematically grounded.

What it does

Quick Start

1. Install

# From PyPI (once published)
pip install sage-solver-mcp

# From source (development)
git clone https://github.com/pragnakar/Project_Sage
cd sage
pip install -e sage-solver-core/
pip install -e sage-solver-mcp/

2. Configure Claude Desktop

Find your config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Add the SAGE server:

{
  "mcpServers": {
    "sage": {
      "command": "uvx",
      "args": ["sage-solver-mcp"]
    }
  }
}

What is uvx? It is a command from the uv Python toolchain that runs a PyPI package ephemerally — no manual pip install required. If you have uv installed (brew install uv on macOS), uvx sage-solver-mcp fetches and runs SAGE automatically. If Claude Desktop cannot find uvx on your PATH, use the full path: "/opt/homebrew/bin/uvx" (macOS) or the output of which uvx.

Restart Claude Desktop and you will see the SAGE tools in the toolbar.

3. Try it

Ask Claude:

"Solve this LP: maximize 3x + 5y subject to x + 2y ≤ 12, x ≤ 8, y ≤ 5, x,y ≥ 0"

Or with a file:

"Read examples/portfolio_5_assets.xlsx and solve it as a portfolio optimization"

MCP Tools

Usage Examples

Each example shows the user prompt, which tool is called, a representative input payload, and the output SAGE returns.

Example 1 — Solve a staffing LP

User prompt: I need to figure out how many full-time and part-time employees to schedule to minimize cost. Full-time costs $200/day and covers 8 hours, part-time costs $100/day and covers 4 hours. I need at least 40 hours covered each day and at most 6 full-time staff.

Tool: solve_optimization

{
  "problem_type": "lp",
  "name": "staffing",
  "variables": [
    {"name": "ft", "lb": 0, "ub": 6},
    {"name": "pt", "lb": 0}
  ],
  "constraints": [
    {"name": "coverage", "expression": {"ft": 8, "pt": 4}, "sense": ">=", "rhs": 40}
  ],
  "objective": {"sense": "minimize", "coefficients": {"ft": 200, "pt": 100}}
}

Output: Optimal: ft=2, pt=6, cost=$1,000/day. The coverage constraint is binding. Sensitivity: each additional required hour costs $25.

Example 2 — Diagnose an infeasible schedule

User prompt: My shift schedule says workers need at least 3 people on Monday AND no more than 2 people total — is that solvable?

Tool: check_feasibility

{
  "problem_type": "lp",
  "name": "schedule_check",
  "variables": [{"name": "workers", "lb": 0}],
  "constraints": [
    {"name": "min_staff", "expression": {"workers": 1}, "sense": ">=", "rhs": 3},
    {"name": "max_staff", "expression": {"workers": 1}, "sense": "<=", "rhs": 2}
  ],
  "objective": {"sense": "minimize", "coefficients": {"workers": 0}}
}

Output: INFEASIBLE. Conflicting constraints: min_staff (≥3) and max_staff (≤2) are mutually exclusive. Suggestion: relax max_staff to ≥3 (+50%) or reduce min_staff to ≤2 (−33%).

Example 3 — Portfolio optimization from Excel

User prompt: I have a portfolio spreadsheet with expected returns and a covariance matrix. Optimize it for a target return of 8% while minimizing risk.

Tools: read_data_file → solve_from_file

read_data_file output: Detected sheets: assets (5 rows, columns: ticker, expected_return), covariance (5×5 matrix). Preview looks correct.

solve_from_file output: Optimal allocation — AAPL: 32%, MSFT: 28%, GOOGL: 18%, BND: 22%, CASH: 0%. Portfolio variance: 0.0042 (σ=6.5%). Results written to portfolio_optimized.xlsx.

Example 4 — Generate a template, solve, then explain in detail

User prompt: Can you create a scheduling template I can fill in? Then after I solve it, give me a detailed explanation.

Step 1 — Tool: generate_template with problem_type: "scheduling"

Output: Template written to scheduling_template.xlsx with sheets: workers (name, availability, cost), shifts (name, start, end, required_count), instructions.

Step 2 — Tool: explain_solution with detail_level: "detailed"

Output: "The optimal schedule assigns Alice and Bob to the morning shift (cost: $480) and Carlos to the evening shift (cost: $220). The evening minimum-staffing constraint has a shadow price of $45 — each additional required worker increases cost by $45. The morning capacity constraint has 1 unit of slack."

Example 5 — Integer programming with relaxation suggestions

User prompt: I want to buy whole units of 3 products to maximize profit, but I can only spend $500 and store 20 cubic feet. Product A: $80, 3 ft³, $120 profit. Product B: $50, 5 ft³, $70 profit. Product C: $120, 2 ft³, $200 profit.

Tool: solve_optimization (MIP with integer variables A, B, C; budget ≤ 500; storage ≤ 20; maximize 120A + 70B + 200C)

Tool: suggest_relaxations (called automatically on infeasible sub-problem)

Output: Optimal integer solution: A=2, B=0, C=3, profit=$840. If the budget constraint is binding, suggest_relaxations ranks options: relax budget by $20 (+4%) to $520, or drop 1 unit of C and add 1 unit of A for $760 profit within the original $500 limit.

Example Files

Architecture

Project_Sage/
├── sage-solver-core/          # Pure optimization engine — solver, models, fileio, explainer
│   └── sage_solver_core/
│       ├── models.py   # Pydantic models (LPModel, MIPModel, PortfolioModel, SchedulingModel)
│       ├── solver.py   # HiGHS + OSQP solver adapters
│       ├── builder.py  # JSON → SolverInput builders
│       ├── fileio.py   # Excel/CSV read/write, template generation
│       └── explainer.py# Natural language solution narration + IIS explanation
├── sage-solver-mcp/           # Local MCP server (this package — v0.1)
├── sage-solver-cloud/  # Cloud API (future — v0.2)
└── examples/           # Ready-to-use example files

Data flow:

Claude Desktop → stdio JSON-RPC → sage-solver-mcp → sage-solver-core → HiGHS/OSQP
                                                               ↓
                                                    SolverResult + IIS + Sensitivity

Supported Problem Types

Linear Program (LP)

Variables with continuous bounds, linear objective, linear constraints (<=, >=, =).