# SCAL Digital Assistant Suite v5.0

**Multi-method Special Core Analysis — Relative Permeability & Capillary Pressure**  
Eclipse-ready `.INC` · Cydar-aligned QC · LangGraph agent · Streamlit UI · FastAPI · **MCP Server**

---

## What Is This?

A complete engineering toolkit for generating, quality-controlling, and exporting relative permeability and capillary pressure curves for reservoir simulation. Starting from laboratory endpoint measurements, you choose a Kr model, set parameters, and the suite produces:

- A validated `SWOF` or `SGOF` Eclipse `.INC` file ready to `INCLUDE` in your DATA deck
- A `.zip` package (INC + Excel report + CSV + QC log + manifest)
- A structured Cydar-aligned physics QC report (25+ checks across KR/PC/XC/CD categories)
- A LLM engineering assessment via the LangGraph agent

---

## What's New in v5.0

| Feature | Detail |
|---|---|
| **MCP Server v2024-11-05** | Full JSON-RPC 2.0 stdio transport; 6 tools; Claude Desktop ready |
| **Pc-LET model** | Lomeland SCA 2008 / Cydar manual p.47; selectable alongside Brooks-Corey |
| **Petroleum Office LET example** | Default LET values cross-checked against `po.scal.let.relperm` blueprint |
| **Brooks-Corey equiv. Corey** | nw_equiv = (2+3λ)/λ shown in CLI, INC header, API response |
| **`/api/v1/mcp-manifest`** | HTTP endpoint returns full MCP tool schema for discovery |
| **Pc model field** | `pc_model: BC | LET | none` replaces the old `include_pc` boolean |
| **Philliec459 alignment** | Corey formulation cross-checked against Panel implementation |

---

## Supported Kr Methods

| Method | Reference | Key Params | Best For |
|---|---|---|---|
| **Corey** | Corey (1954); Philliec459 Panel | nw, no | Clean sands, baseline, screening |
| **LET** | Lomeland et al. SCA2005-32; PO Blueprint | Lw/Ew/Tw, Lp/Ep/Tp | Mixed-wet, heterogeneous, S-shaped |
| **Brooks-Corey** | Brooks & Corey (1964) | λ (linked kr + Pc) | Physically grounded; tight formations |
| **Burdine** | Burdine (1953) Trans. AIME 198 | λ | Pore-bundle theory |
| **Chierici** | Chierici (1984) SPEJ 24(3) | aw/bw, ap/bp | Fractured/vuggy carbonates |
| **Cydar Modified Corey** | CYDAR-SCAL Manual (2025) p.48 | α, H, V | Endpoint slope control; CYDAR HM |

## Supported Pc Models

| Model | Formula | When to Use |
|---|---|---|
| **Brooks-Corey** | `Pc = Pe × Sw*^(−1/λ)` | Default; standard drainage |
| **Pc-LET** | `Pc = Pc_max × (1−Sw*)^L / [(1−Sw*)^L + E×Sw*^T]` | Sigmoidal shape; Cydar recommended |
| **None** | Pc = 0 | Kr-only export |

---

## Key Equations (cross-referenced)

### Normalised Saturation
```
Sw* = (Sw − Swi) / (1 − Swi − Sor)     [Petroleum Office convention]
So* = 1 − Sw*
```

### Corey (1954)
```
krw = krw_end × Sw*^nw
kro = kro_end × (1−Sw*)^no
```
*Reference: Philliec459 Panel; Petroleum Office scal-corey-let*

### LET (Lomeland et al. 2005)
```
krw = krw_end × Sw*^Lw / [Sw*^Lw + Ew×(1−Sw*)^Tw]
kro = kro_end × (1−Sw*)^Lo / [(1−Sw*)^Lo + Eo×Sw*^To]
```
*Petroleum Office example (po.scal.let.relperm): Lo=2.5, Eo=2.0, To=1.5 | Lw=3.0, Ew=1.5, Tw=2.0*

### Brooks-Corey (1964)
```
krw = krw_end × Sw*^((2+3λ)/λ)
kro = kro_end × (1−Sw*)^2 × [1 − Sw*^((2+λ)/λ)]
Pc  = Pe × Sw*^(−1/λ)
Equivalent Corey nw = (2+3λ)/λ    [Petroleum Office relationship]
```

### Cydar Modified Corey (manual p.48)
```
krw = krw_end × [Sw*^(2α)/(2α) + Sw*^α/α + H×Sw*] / norm
kro = kro_end × [(1−Sw*)^(2α)/(2α) + (1−Sw*)^α/α + V×(1−Sw*)] / norm
H = krw slope at Swi  (0 = flat, water-wet)
V = kro slope at 1-Sor
```

### Pc-LET (Cydar manual p.47; Lomeland SCA 2008)
```
Pc(Sw*) = Pc_max × (1−Sw*)^L / [(1−Sw*)^L + E×Sw*^T]
L ≥ 1  (lower curvature)   E > 0  (elevation)   T ≥ 0.5  (upper curvature)
```

---

## Architecture

```
scal-suite-pro/
├── corey_engine.py                 All 6 Kr models + Pc models + Excel + INC export
├── scal_qc.py                      Cydar-aligned QC: KR/PC/XC/CD check suites
├── agents.py                       LangGraph: PhysicsQC → EngineeringQA → ReportSynthesis
├── mcp_scal_server.py              MCP stdio server (JSON-RPC 2.0) + interactive CLI
├── main.py                         FastAPI: /compute-scal /methods /mcp-manifest
├── seria_correlations.py           BSP badin USman empirical correlations
├── Home.py                         Streamlit multi-page entry point
├── pages/
│   ├── app_ui.py                   SCAL engine UI
│   └── seria_ui.py                 badin correlations UI
├── claude_desktop_config_example.json  MCP config for Claude Desktop
├── .env.example
├── Dockerfile
├── docker-compose.yml
└── requirements.txt
```

---

## Quick Start (Local)

```bash
git clone <repo>
cd scal-suite-pro
cp .env.example .env          # add OPENAI_API_KEY (optional — for LLM QA)
pip install -r requirements.txt

# Terminal 1 — FastAPI backend
uvicorn main:app --reload --port 8000

# Terminal 2 — Streamlit frontend
streamlit run Home.py
```

Open http://localhost:8501 | API docs http://localhost:8000/docs

---

## MCP Server Integration

### Run as stdio server
```bash
python mcp_scal_server.py --mcp
```

### Interactive CLI (no LLM required)
```bash
python mcp_scal_server.py
```

### Connect to Claude Desktop
Edit your Claude Desktop config file:
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "scal-suite": {
      "command": "python",
      "args": ["mcp_scal_server.py", "--mcp"],
      "cwd": "C:/path/to/scal-suite-pro"
    }
  }
}
```
See `claude_desktop_config_example.json` for the annotated version.

### MCP Tools

| Tool | Description |
|---|---|
| `list_kr_methods` | Full catalogue: models, equations, typical ranges, wettability guide |
| `compute_scal` | Run Kr+Pc simulation → saturation table + Cydar QC report |
| `export_eclipse_deck` | Raw SWOF/SGOF .INC text from a supplied table |
| `export_zip_package` | Build .zip: INC + XLSX + CSV + QC log + manifest |
| `run_qc_only` | QC suite against any external saturation table |
| `get_seria_correlation` | BSP badin Seria/West Anduki empirical values |

### Test a single call
```bash
python mcp_scal_server.py --mcp '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
python mcp_scal_server.py --mcp '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"list_kr_methods","arguments":{}}}'
```

---

## Docker

```bash
cp .env.example .env
docker-compose up --build
```
Frontend: http://localhost:8501 | Backend docs: http://localhost:8000/docs | MCP manifest: http://localhost:8000/api/v1/mcp-manifest

---

## Eclipse Output

| Fluid System | Keyword | Column Order |
|---|---|---|
| Oil-Water | `SWOF` | Sw  Krw  Kro  Pc_ow (bar) |
| Gas-Water | `SGOF` | Sg  Krg  Krw  Pc_gw (bar) — ascending Sg |

```eclipse
INCLUDE
  'SCAL_FUNCTIONS.INC' /
```

---

## .zip Package Contents

| File | Description |
|---|---|
| `SCAL_FUNCTIONS.INC` | Eclipse E100/E300 SWOF/SGOF keyword table |
| `SCAL_Report.xlsx` | Saturation table + embedded Kr and Pc line charts |
| `saturation_table.csv` | Raw Sw/Kr/Pc values |
| `agent_qc_report.txt` | Cydar-aligned QC log (25+ checks) |
| `PACKAGE_MANIFEST.json` | Method, endpoints, Pc model, QC status, timestamp, references |

---

## QC Checks (Cydar-SCAL aligned)

| Category | Codes | Checks |
|---|---|---|
| Kr physical | KR-01 → KR-14 | Endpoints, monotonicity, crossover, exponent ranges, wettability |
| Pc physical | PC-01 → PC-07 | Monotonicity, sign convention, entry pressure, Leverett J |
| Cross-checks | XC-01 → XC-03 | Amott-Harvey wettability, Rapoport-Leas, capillary number |
| Cydar-specific | CD-01 → CD-04 | LET params, Pc-LET params, Modified Corey H/V/α, dimensionless numbers |

---

## API Reference

**POST** `/api/v1/compute-scal`
```json
{
  "method":        "LET",
  "system":        "Oil-Water",
  "swc":           0.20,
  "s_res":         0.25,
  "krw_end":       0.30,
  "kr_phase_end":  0.80,
  "pc_model":      "LET",
  "n_points":      30,
  "let_params":    { "Lw": 3.0, "Ew": 1.5, "Tw": 2.0, "Lp": 2.5, "Ep": 2.0, "Tp": 1.5 },
  "pc_let_params": { "pc_max": 5.0, "L": 2.0, "E": 1.0, "T": 2.0 }
}
```

**GET** `/api/v1/methods` — method catalogue with equations  
**GET** `/api/v1/mcp-manifest` — MCP tool schema + Claude Desktop config snippet

---

## References

- Corey, A.T. (1954). The interrelation between gas and oil relative permeabilities. *Producers Monthly*.
- Burdine, N.T. (1953). Relative permeability calculations from pore-size distribution data. *Trans. AIME*, 198.
- Brooks, R.H. & Corey, A.T. (1964). *Hydraulic Properties of Porous Media*. Colorado State University.
- Lomeland, F., Ebeltoft, E. & Thomas, W.H. (2005). A new versatile relative permeability correlation. *SPE-SCA2005-32*.
- Lomeland, F., Ebeltoft, E. & Thomas, W.H. (2008). A new versatile capillary pressure correlation. *SCA2008-18*.
- Chierici, G.L. (1984). Novel relations for drainage and imbibition curves. *SPEJ*, 24(3).
- Cydarex (2025). *CYDAR-SCAL User Manual*. http://cydarex.fr/files/CYDAR_SCAL.pdf
- Petroleum Office. *Corey and LET Kr Models*. https://petroleumoffice.com/doc/scal-corey-let
- Petroleum Office. *LET Relative Permeability Curves Blueprint*. https://petroleumoffice.com/blueprint/po.scal.let.relperm
- Philliec459. *Panel for Corey Relative Permeability Curves*. https://github.com/Philliec459/Panel-used-to-Create-Relative-Permeability-Curves-using-the-Corey-Technique
- Dake, L.P. (1978). *Fundamentals of Reservoir Engineering*. Elsevier.
- Anthropic (2024). *Model Context Protocol Specification 2024-11-05*. https://spec.modelcontextprotocol.io