<div align="center">

# Decisify

### *Autonomous Mathematical Optimization & Multi-Agent Graphs via Model Context Protocol (MCP)*

[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
[![FastMCP](https://img.shields.io/badge/FastMCP-0.4+-green.svg)](https://github.com/jlowin/fastmcp)
[![Strands Multi-Agent](https://img.shields.io/badge/Strands-Multi--Agent_Graph-purple.svg)](https://strandsagents.com)
[![PySCIPOpt](https://img.shields.io/badge/PySCIPOpt-SCIP_Solver-orange.svg)](https://github.com/scipopt/PySCIPOpt)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Tests Passing](https://img.shields.io/badge/tests-55%20passed-brightgreen.svg)](tests/)

<p align="center">
  <b>Decisify</b> transforms unstructured natural language operational problems into rigorously formulated, validated, and solved Mixed-Integer Linear Programming (MILP) models. Built on the <b>Strands Multi-Agent Graph</b> orchestration engine, <b>PySCIPOpt</b> solver, and <b>FastMCP</b>, Decisify brings autonomous, closed-loop Operations Research capabilities directly to your LLM chat assistants, IDEs, and agentic workflows.
</p>

[Key Features](#-key-features) • [Architecture](#-multi-agent-architecture--topology) • [Quickstart](#-quickstart) • [Running Server](#-running-the-mcp-server) • [Client Setup](#-connecting-to-mcp-clients) • [Tool Catalog](#-mcp-catalog-tools-resources--prompts) • [Contributing](#-contributing)

---

</div>

## 🌟 Key Features

- 🔄 **Autonomous Closed-Loop Feedback Cycles**: Specialized reviewer agents rigorously audit mathematical formulations, PySCIPOpt code syntax, and runtime solver status (optimal, infeasible, unbounded), automatically cycling back to upstream agents for self-correction.
- 🧩 **Dual Operating Paradigm**:
  - **Modular MCP Tools**: Call standalone micro-agents for individual tasks (e.g., query clarification, mathematical formulation, sandbox code execution).
  - **Autonomous End-to-End Workflow**: Execute the entire multi-agent graph deterministically from a single high-level prompt.
- 📐 **Structured Pydantic Intermediate Representations**: Outputs are strictly validated using Pydantic schemas (`FormulationIR`, `ExecutableModelCode`), eliminating fragile regex and markdown parsing errors.
- 🛡️ **Subprocess Sandbox Execution**: PySCIPOpt models execute in isolated, timeout-protected subprocess environments to ensure host safety and stability.
- 🐳 **Zero-Configuration Docker Deployment**: Pre-built Docker container bundled with Debian Slim, SCIP solver, and FastMCP transport support (`stdio`, `sse`, `streamable-http`).
- 🌐 **Native MCP Compatibility**: Seamlessly integrates with Claude Desktop, Cursor, VS Code (Cline/Roo-Code), LibreChat, and the official Model Context Protocol Inspector.

---

## 🏗️ Multi-Agent Architecture & Topology

Decisify organizes Operations Research modeling into a directed, cyclic multi-agent graph with specialized generator and reviewer personas. When an error or inconsistency is detected, the graph dynamically backtracks to the appropriate reasoning stage.

```mermaid
graph TD
    User([User / MCP Client]) --> MCP[Decisify FastMCP Server]
    
    subgraph "FastMCP Interface Layer"
        MCP --> Decomp[decompose_optimization_query]
        MCP --> Tools[Modular Agent Tools]
        MCP --> Sandbox[execute_pyscipopt_sandbox]
        MCP --> Workflow[run_end_to_end_workflow]
    end

    subgraph "Autonomous Multi-Agent Graph (Strands Engine)"
        ReqClar[Requirements Clarifier Agent] --> ReqRev[Requirements Reviewer Agent]
        ReqRev -- "Needs Clarification" --> ReqClar
        ReqRev -- "Requirements Validated" --> MathProp[Math Model Proposer Agent]
        
        MathProp --> MathRev[Math Model Reviewer Agent]
        MathRev -- "Formulation Errors" --> MathProp
        MathRev -- "Math Model Approved" --> CodeGen[PySCIPOpt Model Coder Agent]
        
        CodeGen --> CodeRev[Model Code Reviewer Agent]
        CodeRev -- "Syntax / Logic Issue" --> MathProp
        CodeRev -- "Code Approved" --> CodeExec[Sandbox Code Executor Agent]
        
        CodeExec --> ExecRev[Execution Reviewer Agent]
        ExecRev -- "Runtime / Infeasible Error" --> CodeGen
        ExecRev -- "Optimal Solution Found" --> Output([Validated Solution & Report])
    end

    Workflow --> ReqClar
    Tools -.-> ReqClar
    Tools -.-> MathProp
    Tools -.-> CodeGen
    Tools -.-> CodeExec
```

### Self-Correction & Routing Logic

1. **Requirements Phase**: `Requirements Clarifier` structures fuzzy user requests into decision variables, sets, parameters, and constraints. `Requirements Reviewer` verifies completeness.
2. **Formulation Phase**: `Math Model Proposer` writes formal algebraic specifications (LaTeX/Formulation IR). `Math Model Reviewer` checks constraint consistency and objective sense.
3. **Implementation Phase**: `PySCIPOpt Model Coder` generates structured Python code with typed variables (`C`, `I`, `B`) and solver constraints. `Model Code Reviewer` inspects code quality and SCIP API compatibility.
4. **Execution & Diagnostics Phase**: `Sandbox Code Executor` executes the model in a subprocess sandbox with timeout limits. `Execution Reviewer` evaluates solver status and diagnoses infeasibilities or unbound solutions.

---

## 🚀 Quickstart

### Prerequisites

- Python 3.12 or higher
- An OpenAI-compatible API key (OpenAI, OpenRouter, Azure AI Foundry, or local vLLM/Ollama)

### Installation

#### Using `uv` (Recommended)

```bash
# Clone the repository
git clone https://github.com/your-org/decisify.git
cd decisify

# Create and activate virtual environment
uv venv
source .venv/bin/activate

# Install dependencies
uv pip install -e ".[dev]"
```

#### Using standard `pip`

```bash
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
```

### Environment Configuration

Configure your LLM provider credentials in a `.env` file or export them directly:

```bash
# For OpenAI / OpenRouter
export OPENAI_API_KEY="your-api-key"
export BASE_URL="https://openrouter.ai/api/v1"  # Optional override

# For Azure AI Foundry / Azure OpenAI
export BASE_URL="https://<your-resource-name>.openai.azure.com/openai/v1"
export OPENAI_API_KEY="your-azure-key"
```

---

## 🖥️ Running the MCP Server

Decisify supports **stdio**, **SSE (Server-Sent Events)**, and **Streamable HTTP** transports.

### 1. Local CLI Execution

```bash
# Run over stdio (default)
fastmcp run server.py:mcp

# Run as SSE server on port 8000
fastmcp run server.py:mcp --transport sse --host 0.0.0.0 --port 8000

# Run as Streamable HTTP server on port 8000
fastmcp run server.py:mcp --transport streamable-http --host 0.0.0.0 --port 8000
```

### 2. Docker Container Execution

Pre-configured Docker container with built-in SCIP libraries and FastMCP:

```bash
# Build the image
docker build -t decisify:latest .

# Run with stdio transport
docker run -i --rm -e OPENAI_API_KEY="$OPENAI_API_KEY" decisify:latest

# Run with Streamable HTTP transport (Port 8000)
docker run -i --rm \
  -p 8000:8000 \
  -e OPENAI_API_KEY="$OPENAI_API_KEY" \
  decisify:latest \
  --transport streamable-http \
  --host 0.0.0.0 \
  --port 8000

# Run with SSE transport (Port 8000)
docker run -i --rm \
  -p 8000:8000 \
  -e OPENAI_API_KEY="$OPENAI_API_KEY" \
  decisify:latest \
  --transport sse \
  --host 0.0.0.0 \
  --port 8000
```

---

## 🔌 Connecting to MCP Clients

### Claude Desktop

Add Decisify to your `claude_desktop_config.json`:

#### Via Local `uv`
```json
{
  "mcpServers": {
    "decisify": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "fastmcp",
        "fastmcp",
        "run",
        "/absolute/path/to/decisify/server.py:mcp"
      ],
      "env": {
        "OPENAI_API_KEY": "your-api-key",
        "BASE_URL": "https://openrouter.ai/api/v1"
      }
    }
  }
}
```

#### Via Docker
```json
{
  "mcpServers": {
    "decisify": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", "OPENAI_API_KEY",
        "decisify:latest"
      ]
    }
  }
}
```

---

### Cursor & VS Code (Cline / Roo-Code)

Configure via your IDE's `mcp.json` or MCP settings panel:

#### For SSE / Streamable HTTP:
```json
{
  "mcpServers": {
    "decisify": {
      "type": "sse",
      "url": "http://localhost:8000/sse"
    }
  }
}
```

#### For stdio:
```json
{
  "mcpServers": {
    "decisify": {
      "command": "fastmcp",
      "args": ["run", "/absolute/path/to/decisify/server.py:mcp"],
      "env": {
        "OPENAI_API_KEY": "your-api-key"
      }
    }
  }
}
```

---

### LibreChat

Add to your `librechat.yaml`:

```yaml
mcpServers:
  decisify:
    type: sse
    url: "http://localhost:8000/sse"
```

---

### MCP Inspector (Interactive Web UI)

Debug and inspect tools, resources, and prompts:

```bash
npx @modelcontextprotocol/inspector
```
1. Open the inspector in your browser.
2. Select **Transport**: `SSE` (or `Streamable HTTP`).
3. Connect to `http://localhost:8000/sse` (or `http://localhost:8000/mcp`).

---

## 📦 MCP Catalog: Tools, Resources & Prompts

### 🛠️ Modular Tools

| Tool Name | Type | Description |
| :--- | :--- | :--- |
| `decompose_optimization_query` | Decomposer Agent | Breaks open-ended optimization queries into modular tool steps. |
| `clarify_requirements` | Generator Agent | Extracts structured sets, parameters, variables, bounds, and constraints. |
| `review_requirements` | Reviewer Agent | Validates requirements completeness and structural integrity. |
| `formulate_math_model` | Generator Agent | Generates formal algebraic MILP equations and Formulation IR. |
| `review_math_model` | Reviewer Agent | Checks formulation validity, constraint dimensions, and linearity. |
| `generate_model_code` | Generator Agent | Generates typed PySCIPOpt Python code complying with `ExecutableModelCode`. |
| `review_model_code` | Reviewer Agent | Audits PySCIPOpt code for syntax, variable types, and solver methods. |
| `execute_model_code` | Generator Agent | Executes PySCIPOpt model code via the isolated execution sandbox. |
| `review_execution_result` | Reviewer Agent | Evaluates solver outputs, objective values, feasibility, and bounds. |
| `execute_pyscipopt_sandbox` | Execution Runner | Isolated subprocess runner executing PySCIPOpt code with timeout protection. |
| `run_end_to_end_workflow` | Autonomous Graph | Runs the complete cyclic multi-agent graph with self-correction loops. |

---

### 📚 MCP Resources

| URI | MIME Type | Description |
| :--- | :--- | :--- |
| `optimization://catalog` | `text/markdown` | Full reference catalog of tools, agents, schemas, and usage examples. |
| `optimization://workflow-topology` | `text/vnd.mermaid` | Mermaid diagram of the multi-agent graph with cyclic review loops. |
| `optimization://schema/executable-code` | `application/json` | JSON Schema for `ExecutableModelCode` structured code objects. |
| `optimization://schema/formulation-ir` | `application/json` | JSON Schema for `FormulationIR` mathematical formulation objects. |

---

### 💬 Built-in Prompt Templates

| Prompt Template | Arguments | Purpose |
| :--- | :--- | :--- |
| `clarify_problem` | `problem_description` | Guides user through structured requirements extraction for an optimization query. |
| `formulate_optimization_model` | `specification` | Guides the formulation of sets, parameters, variables, and constraints. |
| `implement_pyscipopt_code` | `math_formulation` | Directs the generation of clean, structured PySCIPOpt Python code. |
| `audit_optimization_model` | `formulation`, `code` | Performs a dual-stage mathematical and code correctness audit. |
| `diagnose_execution_error` | `code`, `execution_output` | Diagnoses runtime errors, solver infeasibility, or unbounded objective values. |

---

## 🧪 Development & Testing

Decisify features a comprehensive test suite covering schema serialization, agent tool registration, controller condition transitions, and isolated sandbox execution.

```bash
# Run complete test suite with verbose output
pytest -v

# Run tests with coverage
pytest --cov=src --cov-report=term-missing
```

### Project Structure

```text
decisify/
├── src/
│   ├── agents.py         # 9 Strands modular agent definitions & prompts
│   ├── controllers.py    # Cyclic graph builder & conditional routing logic
│   ├── llms.py           # LLM client configuration & environment mappings
│   ├── models.py         # Pydantic schemas (FormulationIR, ExecutableModelCode)
│   ├── server.py         # FastMCP server registration (tools, resources, prompts)
│   └── tools.py          # Subprocess sandbox code execution runner
├── tests/
│   ├── test_agents.py       # Agent definition and tool binding tests
│   ├── test_controllers.py  # Graph topology, condition evaluation & routing tests
│   ├── test_models.py       # Pydantic schema validation & serialization tests
│   ├── test_server.py       # FastMCP tools, resources & prompt template tests
│   └── test_tools.py        # Sandbox execution & code extraction tests
├── Dockerfile            # Container definition with SCIP and FastMCP
├── pyproject.toml        # Build configuration, dependencies & metadata
├── server.py             # Server export entrypoint
├── CONTRIBUTING.md       # Contribution guidelines
└── LICENSE               # MIT License
```

---

## 🤝 Contributing

Contributions are warmly welcomed! Please read our [CONTRIBUTING.md](CONTRIBUTING.md) for details on code style, pytest guidelines, adding new agents, and submitting pull requests.

---

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.