{
  "markdown": "# SAGE — Solver-Augmented Grounding Engine\n\n**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.\n\n> Status: **v0.1.3 — Alpha** · Author: Peter Pragnakar Atreides\n\n---\n\n## Why SAGE Exists\n\nLarge 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.\n\n> **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.\n\nSAGE introduces a hybrid intelligence architecture: LLMs handle language and ambiguity; solvers handle optimality and feasibility. Each component does what it is best suited for.\n\n### The Runtime Advantage\n\nLLMs 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.\n\nThis \"anytime\" property enables SAGE to:\n- Decompose large problems using Benders decomposition, column generation, or Lagrangian relaxation\n- Run long-horizon solves asynchronously while the LLM remains conversationally responsive\n- Checkpoint, pause, and resume optimization without losing progress\n\nThe result: AI shifts from *immediate but approximate* to *sustained and mathematically grounded*.\n\n---\n\n## What it does\n\n| Capability | Detail |\n|---|---|\n| Problem types | LP, MIP, Portfolio Optimization (QP), Workforce Scheduling |\n| Solvers | HiGHS (LP/MIP), OSQP (QP) |\n| File I/O | Read/write Excel (.xlsx) and CSV |\n| Infeasibility | IIS detection + ranked relaxation suggestions |\n| Sensitivity | Dual values, reduced costs, allowable ranges |\n| Explanation | Plain-language narration of every result |\n\n---\n\n## Quick Start\n\n### 1. Install\n\n```bash\n# From PyPI (once published)\npip install sage-solver-mcp\n\n# From source (development)\ngit clone https://github.com/pragnakar/Project_Sage\ncd sage\npip install -e sage-solver-core/\npip install -e sage-solver-mcp/\n```\n\n### 2. Configure Claude Desktop\n\nFind your config file:\n- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n- **Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\nAdd the SAGE server:\n```json\n{\n  \"mcpServers\": {\n    \"sage\": {\n      \"command\": \"uvx\",\n      \"args\": [\"sage-solver-mcp\"]\n    }\n  }\n}\n```\n\n> **What is `uvx`?** It is a command from the [uv](https://github.com/astral-sh/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`.\n\nRestart Claude Desktop and you will see the SAGE tools in the toolbar.\n\n### 3. Try it\n\nAsk Claude:\n> \"Solve this LP: maximize 3x + 5y subject to x + 2y ≤ 12, x ≤ 8, y ≤ 5, x,y ≥ 0\"\n\nOr with a file:\n> \"Read examples/portfolio_5_assets.xlsx and solve it as a portfolio optimization\"\n\n---\n\n## MCP Tools\n\n| Tool | Description |\n|---|---|\n| `solve_optimization` | Solve LP / MIP / portfolio / scheduling from JSON |\n| `read_data_file` | Read an Excel or CSV file and return a preview |\n| `solve_from_file` | Read + solve + write results in one step |\n| `explain_solution` | Narrate the most recent solve result |\n| `check_feasibility` | Check feasibility; if infeasible, compute IIS |\n| `generate_template` | Create a blank Excel template for a problem type |\n| `suggest_relaxations` | Rank constraint relaxations for the last infeasible result |\n\n---\n\n## Usage Examples\n\nEach example shows the user prompt, which tool is called, a representative input payload, and the output SAGE returns.\n\n---\n\n### Example 1 — Solve a staffing LP\n\n**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.\n\n**Tool:** `solve_optimization`\n\n```json\n{\n  \"problem_type\": \"lp\",\n  \"name\": \"staffing\",\n  \"variables\": [\n    {\"name\": \"ft\", \"lb\": 0, \"ub\": 6},\n    {\"name\": \"pt\", \"lb\": 0}\n  ],\n  \"constraints\": [\n    {\"name\": \"coverage\", \"expression\": {\"ft\": 8, \"pt\": 4}, \"sense\": \">=\", \"rhs\": 40}\n  ],\n  \"objective\": {\"sense\": \"minimize\", \"coefficients\": {\"ft\": 200, \"pt\": 100}}\n}\n```\n\n**Output:** Optimal: ft=2, pt=6, cost=$1,000/day. The coverage constraint is binding. Sensitivity: each additional required hour costs $25.\n\n---\n\n### Example 2 — Diagnose an infeasible schedule\n\n**User prompt:** My shift schedule says workers need at least 3 people on Monday AND no more than 2 people total — is that solvable?\n\n**Tool:** `check_feasibility`\n\n```json\n{\n  \"problem_type\": \"lp\",\n  \"name\": \"schedule_check\",\n  \"variables\": [{\"name\": \"workers\", \"lb\": 0}],\n  \"constraints\": [\n    {\"name\": \"min_staff\", \"expression\": {\"workers\": 1}, \"sense\": \">=\", \"rhs\": 3},\n    {\"name\": \"max_staff\", \"expression\": {\"workers\": 1}, \"sense\": \"<=\", \"rhs\": 2}\n  ],\n  \"objective\": {\"sense\": \"minimize\", \"coefficients\": {\"workers\": 0}}\n}\n```\n\n**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%).\n\n---\n\n### Example 3 — Portfolio optimization from Excel\n\n**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.\n\n**Tools:** `read_data_file` → `solve_from_file`\n\n`read_data_file` output: Detected sheets: `assets` (5 rows, columns: ticker, expected_return), `covariance` (5×5 matrix). Preview looks correct.\n\n`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`.\n\n---\n\n### Example 4 — Generate a template, solve, then explain in detail\n\n**User prompt:** Can you create a scheduling template I can fill in? Then after I solve it, give me a detailed explanation.\n\n**Step 1 — Tool:** `generate_template` with `problem_type: \"scheduling\"`\n\nOutput: Template written to `scheduling_template.xlsx` with sheets: `workers` (name, availability, cost), `shifts` (name, start, end, required_count), `instructions`.\n\n**Step 2 — Tool:** `explain_solution` with `detail_level: \"detailed\"`\n\nOutput: \"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.\"\n\n---\n\n### Example 5 — Integer programming with relaxation suggestions\n\n**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.\n\n**Tool:** `solve_optimization` (MIP with integer variables A, B, C; budget ≤ 500; storage ≤ 20; maximize 120A + 70B + 200C)\n\n**Tool:** `suggest_relaxations` (called automatically on infeasible sub-problem)\n\n**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.\n\n---\n\n## Example Files\n\n| File | Problem | Result |\n|---|---|---|\n| `examples/portfolio_5_assets.xlsx` | Portfolio QP — 5 assets (equity + bonds) | Optimal allocation |\n| `examples/nurse_scheduling.xlsx` | Scheduling MIP — 8 nurses, 3 shifts, 7 days | Infeasible: IIS computed |\n| `examples/transport_routing.xlsx` | Transport LP — 3 warehouses → 5 stores | Optimal routes, $2,472 cost |\n| `examples/blending_problem.xlsx` | Blending LP — 6 ingredients, nutrient constraints | Optimal blend, $23.47/100kg |\n\n---\n\n## Architecture\n\n```\nProject_Sage/\n├── sage-solver-core/          # Pure optimization engine — solver, models, fileio, explainer\n│   └── sage_solver_core/\n│       ├── models.py   # Pydantic models (LPModel, MIPModel, PortfolioModel, SchedulingModel)\n│       ├── solver.py   # HiGHS + OSQP solver adapters\n│       ├── builder.py  # JSON → SolverInput builders\n│       ├── fileio.py   # Excel/CSV read/write, template generation\n│       └── explainer.py# Natural language solution narration + IIS explanation\n├── sage-solver-mcp/           # Local MCP server (this package — v0.1)\n├── sage-solver-cloud/  # Cloud API (future — v0.2)\n└── examples/           # Ready-to-use example files\n```\n\n**Data flow:**\n```\nClaude Desktop → stdio JSON-RPC → sage-solver-mcp → sage-solver-core → HiGHS/OSQP\n                                                               ↓\n                                                    SolverResult + IIS + Sensitivity\n```\n\n---\n\n## Supported Problem Types\n\n### Linear Program (LP)\nVariables with continuous bounds, linear objective, linear constraints (<=, >=, =).\n\n### Mixed-Integer Program (MIP)\nSame as LP but variables can be `continuous`, `integer`, or `binary`.\n\n### Portfolio Optimization (QP)\nMarkowitz mean-variance: minimize risk (quadratic) for a target return, with optional sector and weight constraints.\n\n### Workforce Scheduling\nAssign workers to shifts over a planning horizon. Constraints: min/max workers per shift, rest periods, skill requirements.\n\n---\n\n## Roadmap\n\n| Phase | Focus |\n|---|---|\n| v0.1 (now) | LP, MIP, Portfolio QP, Scheduling — 7 MCP tools, local stdio server |\n| v0.2 | sage-solver-cloud FastAPI — remote deployment, async long-running solves |\n| v0.3 | Simulation — Monte Carlo, discrete-event, stochastic programming |\n| v1.0 | Decision Intelligence Platform — industry templates, solver marketplace |\n\nThe long-term ambition is a planetary-scale optimization fabric: interconnected, federated models that co-optimize transportation, energy, supply chains, and infrastructure across institutions — turning SAGE from a single-user tool into shared decision infrastructure.\n\n---\n\n## Development\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for dev setup, test instructions, and branch conventions.\n\n393 tests · 0 failures · sage-solver-core 0.1.3 · sage-solver-mcp 0.1.3\n\n---\n\n## License\n\nMIT — Copyright (c) 2026 Peter Pragnakar Atreides\n",
  "bytes": 11252,
  "sha": "52c3d6370ac1908c712cad6588d5a40f79d8dcb2c6be2830f364b0ddb45208f7",
  "repo_slug": "pragnakar/project_sage",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_pragnakar_sage_solver_mcp_b7ff2267/readme"
}