# GeoAgent-MVP

A human-supervised geological modelling agent that inspects borehole data,
validates it with deterministic geological rules, pauses for human approval,
and then builds an implicit 3D model with
[GemPy](https://www.gempy.org/).

![Cross-section through the computed model](docs/example_section.png)

*Example cross-section generated from nine synthetic boreholes. The workflow
converted logged intervals into contact points, fitted surface orientations,
and constructed the model only after human approval.*

> **Scope:** GeoAgent-MVP is a research and portfolio prototype. It demonstrates
> a supervised agentic workflow over a real geological modelling engine; it is
> not a production geomodelling platform.

---

## Why this project exists

Engineering agents should not allow a language model to invent calculations,
silently repair data, or bypass consequential decisions.

GeoAgent-MVP separates orchestration, explanation, and computation:

| Component | Responsibility |
| --- | --- |
| LangGraph | Persists workflow state, applies deterministic routing, and enforces the human approval interrupt |
| Optional LLM narrator | Explains structured findings in plain language |
| Deterministic Python tools | Inspect data, validate geology, extract contacts, fit orientations, build the GemPy model, compute uncertainty, and write the report |
| Human supervisor | Approves, modifies, or cancels the proposed modelling configuration |
| MCP server | Exposes the same capabilities as reusable resources, tools, and a prompt |

The LLM does **not** calculate geological values or decide whether invalid data
should be accepted. The complete workflow runs without an API key by using a
deterministic narration fallback.

---

## Workflow

```text
Borehole CSV
     |
     v
Inspect data -------------------- unreadable input ----> halt
     |
     v
Validate geology ---------------- blocking errors -----> halt + report
     |
     v
Propose configuration
     |
     v
+--------------------------------------------------+
| HUMAN APPROVAL GATE                              |
| approve / modify / cancel                        |
| LangGraph interrupt() persists the graph state   |
+--------------------------------------------------+
     |
     | approve
     v
Revalidate before build --------- new errors ----------> halt + report
     |
     v
Build GemPy model --------------- tool failure --------> report; invent nothing
     |
     v
Optional uncertainty ensemble
     |
     v
Markdown report + figures + audit trail
```

The approval gate is a real LangGraph `interrupt()`. The graph pauses before
model construction, and its state is stored by a checkpointer. Nothing
downstream runs until a human decision resumes the same thread.

---

## Geological validation

The validator distinguishes between a **blocking data fault** and a
**geological warning requiring interpretation**.

### Blocking errors

| Code | Meaning |
| --- | --- |
| `MISSING_COLUMN` | A required field is absent |
| `MISSING_COORDINATE` | A record cannot be located in space |
| `MISSING_DEPTH` | An interval cannot be positioned downhole |
| `MISSING_LITHOLOGY` | The unit is missing and will not be guessed |
| `DUPLICATE_RECORD` | An interval record is exactly duplicated |
| `NEGATIVE_DEPTH` | Downhole depth is negative |
| `REVERSED_INTERVAL` | `depth_from >= depth_to` |
| `OVERLAPPING_INTERVAL` | One depth belongs to multiple logged intervals |
| `UNKNOWN_LITHOLOGY` | A unit is absent from the declared stratigraphic column |

### Warnings for human review

| Code | Meaning |
| --- | --- |
| `STRATIGRAPHIC_ORDER_CONFLICT` | A borehole contradicts the majority sequence; this may indicate structure or a logging problem |
| `INCONSISTENT_LITHOLOGY_LABEL` | Equivalent spelling variants were normalized |
| `DEPTH_GAP` | An unlogged interval weakens contact constraints |
| `ISOLATED_BOREHOLE` | The borehole constrains no contact |
| `SPARSE_CONTACT_SUPPORT` | A surface has fewer than three supporting points |

Lithology identifiers are normalized internally. For example, `Unit-A`,
`UNIT_A`, and `unit a` map to the stable key `unit_a`.

---

## From boreholes to GemPy

GemPy requires surface points and orientations rather than interval tables.
GeoAgent-MVP performs this conversion explicitly.

1. For consecutive intervals where unit `T` overlies unit `U`, the shared
   boundary is extracted at:

   ```text
   Z = z_collar - contact_depth
   ```

2. The contact is assigned to the **upper unit `T`**, because it represents the
   base boundary of that unit in the GemPy structural model.

3. The deepest unit is represented as basement rather than as another
   interpolated surface.

4. Where measured structural orientations are unavailable, a plane is fitted
   through each surface's contact points and its pole is used as the model
   orientation.

The fitted orientation is an assumption, not a field measurement. It is shown
in the approval configuration and recorded in the final report.

---

## Uncertainty analysis

The optional ensemble perturbs contact elevations using Gaussian noise,
rebuilds the model for multiple realizations, and calculates normalized
information entropy for each grid cell:

```text
H = -sum_k(p_k * log(p_k)) / log(K)
```

- `H = 0`: all realizations agree.
- Larger `H`: greater disagreement between realizations.
- The entropy figure highlights the areas most sensitive to contact-elevation
  uncertainty.

This analysis propagates uncertainty in contact elevations only. It does not
represent uncertainty in structural interpretation, fault geometry, or model
topology.

![Uncertainty entropy](docs/example_entropy.png)

*Example entropy section. The displayed section is selected where the ensemble
contains the strongest uncertainty signal.*

---

## MCP interface

`mcp_server/server.py` exposes GeoAgent through the Model Context Protocol.

### Resources

- `borehole://datasets`
- `borehole://dataset/{name}`

### Tools

- `inspect_dataset`
- `validate_dataset`
- `propose_modelling_config`
- `build_model`
- `analyse_uncertainty`

### Prompt

- `supervised_validate_and_model`

The MCP layer confines file access to the `data/` directory, rejects unsafe
filenames, validates datasets before modelling, and requires explicit approval
for consequential modelling and uncertainty operations.

Launch the MCP Inspector with:

```bash
npx -y @modelcontextprotocol/inspector python mcp_server/server.py
```

On Windows, using the virtual-environment interpreter explicitly is also
supported:

```cmd
npx -y @modelcontextprotocol/inspector .venv\Scripts\python.exe mcp_server\server.py
```

---

## Quick start

### Windows Command Prompt

```cmd
git clone https://github.com/<your-username>/geoagent-mvp.git
cd geoagent-mvp

python -m venv .venv
.venv\Scripts\activate.bat

python -m pip install --upgrade pip
pip install -r requirements.txt
python data\make_datasets.py
```

### Linux or macOS

```bash
git clone https://github.com/<your-username>/geoagent-mvp.git
cd geoagent-mvp

python -m venv .venv
source .venv/bin/activate

python -m pip install --upgrade pip
pip install -r requirements.txt
python data/make_datasets.py
```

### Run the workflow

Interactive approval:

```bash
python run_demo.py --dataset data/valid_boreholes.csv
```

Approved run with uncertainty:

```bash
python run_demo.py \
  --dataset data/valid_boreholes.csv \
  --approve \
  --realisations 10
```

Approved run without uncertainty:

```bash
python run_demo.py \
  --dataset data/valid_boreholes.csv \
  --approve \
  --no-uncertainty
```

Blocking-data demonstration:

```bash
python run_demo.py --dataset data/incomplete_boreholes.csv
```

Cancellation demonstration:

```bash
python run_demo.py \
  --dataset data/valid_boreholes.csv \
  --cancel
```

An `ANTHROPIC_API_KEY` is optional. Without it, the explanation node uses a
deterministic fallback while all modelling behaviour remains unchanged.

---

## Outputs

A successful run writes artifacts under `outputs/`, including:

```text
outputs/
├── figures/
│   ├── model cross-section
│   └── uncertainty entropy section
└── reports/
    └── timestamped Markdown modelling report
```

The report records:

- dataset summary;
- validation errors and warnings;
- normalized stratigraphic order;
- proposed modelling extent and resolution;
- assumptions presented to the human supervisor;
- approval decision;
- GemPy model metadata;
- uncertainty statistics;
- generated figure paths;
- tool-call audit history and timings;
- limitations and outstanding warnings.

---

## Testing

Run the complete suite:

```bash
pytest -q
```

The current test suite contains **29 tests** covering:

- valid and invalid schema handling;
- missing coordinates and depths;
- duplicate and overlapping intervals;
- lithology normalization;
- unknown units;
- stratigraphic conflicts and sparse support;
- contact extraction and fitted orientations;
- proposed extent;
- workflow halting;
- genuine human interruption;
- approval, modification, invalid modification, and cancellation;
- audit history;
- repeated-run reproducibility;
- explicit model failure handling;
- rejection of unrecognized approval decisions.

Before publishing a release, record the actual local result rather than a
hard-coded historical timing:

```text
29 passed in <environment-dependent time>
```

---

## Repository layout

```text
geoagent-mvp/
├── run_demo.py
├── requirements.txt
├── README.md
├── SETUP.md
├── data/
│   ├── make_datasets.py
│   ├── valid_boreholes.csv
│   ├── incomplete_boreholes.csv
│   └── inconsistent_boreholes.csv
├── geoagent/
│   ├── graph.py
│   ├── state.py
│   ├── schemas.py
│   └── explain.py
├── tools/
│   ├── data_inspection.py
│   ├── geological_validation.py
│   ├── gempy_modelling.py
│   ├── uncertainty.py
│   └── report_generator.py
├── mcp_server/
│   └── server.py
├── outputs/
│   ├── figures/
│   └── reports/
└── tests/
    ├── test_validation.py
    └── test_agent_workflow.py
```

---

## Limitations

- The prototype assumes one conformable stratigraphic series.
- Faults, unconformities, intrusions, and overturned structures are not
  modelled.
- Orientations are inferred from contact geometry when measurements are
  unavailable.
- The included datasets are synthetic.
- Real projects commonly require separate collar, survey, and lithology tables.
- Deviated boreholes require desurveying, which is not implemented.
- The uncertainty ensemble perturbs contact elevation independently and is not
  a Bayesian inversion.
- Model quality still depends on data coverage, geological assumptions, and
  human interpretation.

---

## Planned extensions

- ingest separate collar, survey, and lithology tables;
- desurvey deviated boreholes;
- accept measured dip and azimuth;
- use fitted orientations only as a documented fallback;
- add spatially correlated contact perturbations;
- support faults and unconformities through GemPy structural groups;
- add a lightweight web interface for reviewing the approval payload;
- persist production runs in a durable database-backed checkpointer.

---

## Responsible-use statement

GeoAgent-MVP is a decision-support prototype. Human approval does not guarantee
geological correctness, and model outputs should not be used for engineering
design, safety-critical decisions, resource estimation, or investment decisions
without qualified professional review and validation against project data.

---

## Licence

MIT.