Field Brain

An auditable AI workspace for complex oilfield data. Every numeric answer is computed by registered tools, linked to a receipt, and independently checked before it reaches the user.

Built for OpenAI Build Week 2026 in the Work & Productivity track.

Field Brain turns the Equinor Volve dataset into a persistent field workspace with an evidence atlas, streamed analysis, field-scoped chat, source inspection, and replayable provenance. Volve is the connected reference field; new fields can be created as honest empty workspaces until data is attached.

Why Field Brain

Traditional dashboards present values but rarely explain where they came from. General-purpose AI can explain results fluently, but it may also invent values or lose the connection to the source. Field Brain separates reasoning from computation:

• GPT-5.6 plans which registered tools to use, but does not author displayed numbers.
• The server executes read-only, schema-validated tools against processed field data.
• Every execution produces a receipt containing its operation, inputs, source, and result.
• An independent checker reruns the underlying operation before accepting a factual claim.
• The UI streams the plan, tool activity, verification result, answer, and provenance to the user.
• Unsupported questions are refused with answerable alternatives instead of guessed answers.

Quick start

Requirements

• Node.js 20 or newer
• npm 10 or newer
• Python is optional for the standard demo; it is required only for data re-extraction and the controlled RMS processing workflow

Run the key-free demo

npm ci
npm run demo

Open http://localhost:3000.

npm run demo always uses deterministic planning, even if an ignored .env file contains an API key. The questions, tool execution, receipts, checker, streaming UI, and replay system are real; only the model planning step is replaced by committed Playbooks so the complete product remains reproducible without API access.

Judge walkthrough

The repository contains the processed Volve data products and a small RMS upload fixture. A judge does not need the team Drive or an OpenAI API key.

1. Start the app with npm run demo and open http://localhost:3000.
2. Select Add Field and enter Volve as the field name.
3. Choose the folder data/fixtures/rms-export/.
4. Confirm that the picker reports 52 extractor inputs ready, then select Create Field.
5. Open the Volve dashboard and select one of the verified example questions in the analyst.
6. Inspect the streamed activity, verdicts, and receipt drawer, or open a saved replay.

Chrome normally includes Fault_model/.faultlist when it reads the folder. If a browser reports only 51 extractor inputs, use the displayed fallback file picker to add data/fixtures/rms-export/Fault_model/.faultlist separately.

What the demo proves

• A 13-section Volve evidence atlas with maps, production history, simulation comparisons, RMS structure, waterflood analysis, risks, source evidence, and limitations
• 46 factual or interpretive claims connected to 25 execution receipts and 12 evidence records
• Four verified analysis journeys covering water cut, well performance, injection, and RMS geology
• One deliberately incorrect claim that the independent checker visibly rejects
• Progressive Server-Sent Events for planning, tool execution, verification, and cancellation
• Persistent field-scoped chats, replayable JSONL case files, saved analyses, and source inspection
• An honest empty state for fields that do not yet have a connected data product
• A controlled RMS upload flow with staging, deterministic extraction, review, and atomic publish

Technology stack

Layer	Technology
Languages	TypeScript, TSX, Python, SQL, YAML
Frontend	Next.js 15, React 19, Tailwind CSS 4
Visualization	Apache ECharts, Leaflet, React Leaflet
Backend	Node.js, Express 4, native Server-Sent Events
OpenAI	GPT-5.6 through the streaming Responses API with strict JSON Schema output
Contracts and validation	Zod schemas shared across the browser, API, planner, tools, and tests
Analytical storage	DuckDB, Apache Parquet, JSON, JSONL
Data pipeline	pandas, PyArrow, PyMuPDF, resdata, NumPy, Matplotlib, Pillow
Search	MiniSearch over the committed evidence register
Testing	Vitest, Supertest, pytest, Playwright
Repository	npm workspaces monorepo

System architecture

flowchart LR
    U[Browser] -->|HTTP + SSE| W[Next.js application]
    W -->|same-origin BFF| A[Express API]
    A --> P{Planner mode}
    P -->|demo| M[Committed Playbook]
    P -->|live| G[GPT-5.6 Responses API]
    M --> R[Deterministic agent runner]
    G -->|strict Playbook JSON| R
    R --> T[Registered read-only tools]
    T --> D[(DuckDB / Parquet / Atlas JSON)]
    T --> L[Receipt ledger]
    R --> V[Independent checker]
    V -->|reruns tool operation| T
    L --> C[Replayable case file]
    R -->|normalized event stream| A

The model is outside the trusted computation boundary. It selects registered tools and presentation structure; the runner owns execution, value resolution, receipt creation, verification, and the final event stream.

How GPT-5.6 is used

Live mode makes one streaming Responses API request per question. GPT-5.6 receives the user question, bounded field context, and a strict Playbook schema. It can choose only registered tools and schema-shaped arguments.

The live planner is deliberately constrained:

• no raw source files or filesystem paths are sent to the model;
• the model cannot submit SQL, code, panel data, or value overrides;
• displayed numeric values must resolve from server-side tool receipts;
• the returned plan is validated again with Zod before any tool executes;
• API, timeout, refusal, or schema failures become a visible safe refusal;
• store: false is used for the planning request;
• cancellation aborts the upstream request and prevents later tool execution.

To run the GPT-5.6 path:

cp .env.example .env
# Add OPENAI_API_KEY to .env
npm run dev:live

The configured default model is gpt-5.6-sol; OPENAI_MODEL can override it. Live mode requires a non-empty API key and never silently falls back to deterministic planning.

How Codex was used

Codex was the primary implementation environment and engineering control plane for the project. The main session converted the product brief into six dependency-ordered workstreams, delegated bounded implementation tasks to fresh codex exec agents, and accepted work only after rerunning the relevant type, unit, browser, provenance, runtime, and live-model checks.

Codex performed the majority of repository implementation and verification, including:

• profiling the Volve source corpus and building deterministic extraction pipelines;
• designing shared Playbook, tool, receipt, claim, panel, and event contracts;
• implementing the receipted tool layer, agent runner, verifier, and streaming API;
• building the field workspace, evidence atlas, analyst chat, replay, and ingest interfaces;
• generating unit, API, browser, adversarial, accessibility, and visual-regression coverage;
• reviewing failures, correcting invalid assumptions, and running scoped repair loops;
• maintaining an auditable build log and release gates instead of accepting agent output on trust.

The human team retained the product and safety decisions: Volve as the reference field, refusal over guessing, no model-authored numbers, mandatory receipts, independent re-derivation, and a clear separation between deterministic demo mode and live GPT-5.6 planning.

Primary Codex build Session ID:

019f73f9-17f5-77e2-a7b1-a150f4ede175

The corresponding engineering trail is recorded in BUILD_LOG.md and the Git history. In the Codex interface, /status displays the Session ID required by the Build Week submission form; no /feedback report is required.

Data sources and provenance

The dashboard was built from the selected Volve working corpus under:

drive/Data_Oilfield/

That local, gitignored corpus contains the source material used during development. It is not the same thing as the committed upload fixture.

Source group	Principal inputs	Committed product
Production	Volve production data.xlsx	data/volve.duckdb, dashboard summaries, receipts
Reports	Volve PUD .pdf, Discovery_report.pdf	page-anchored indexes, report previews, evidence
RMS model	surfaces, fault sticks, fault list, LAS well logs	RMS summary, plot data, maps, receipts
Eclipse model	GRID/INIT/UNRST/UNSMRY and history-match inputs	Parquet series, simulation maps, comparisons
Review deck	Volve Sim model and HM per jan-16.pptx	slide index, source previews, review evidence

The full raw working corpus is not committed. Instead, the repository contains approximately 18 MB of processed runtime artifacts under data/, including DuckDB, Parquet, evidence JSON, receipts, report images, atlas assets, and deterministic replay files. This is why a clean clone can run the dashboard without Drive.

What data/fixtures/rms-export/ is

The fixture is a 3.35 MB, 52-file subset of the 372-file RMS export containing only the inputs required by the supported deterministic parsers: selected ASCII surfaces and fault sticks, the fault list, and three LAS files. It supports the browser upload and canonical ingest demonstration. It did not replace the full production, report, RMS, Eclipse, and review-deck corpus used to build the dashboard.

The fixture and processed artifacts are attributed under the Equinor Open Data Licence. See NOTICE for the data notice and LICENSE for the software licence.

Repository structure

apps/web/           Next.js product UI and same-origin API proxy
apps/server/        Express API, planner clients, tools, ledger, verifier, ingest
packages/shared/    Shared TypeScript types and Zod contracts
pipeline/           Deterministic Python extraction, rendering, and QA
data/               Committed processed artifacts, fixtures, and replay seeds
semantic/           Metric definitions, units, roles, and name mappings
verified/           Verified questions and expected values
e2e/                Playwright product and judge journeys
scripts/            Demo boot, release verification, runtime safety utilities

Analysis lifecycle

1. The planner returns a schema-constrained Playbook.
2. The runner fans out the requested specialist steps.
3. Registered tools query DuckDB, Parquet, or the active atlas through validated arguments.
4. The receipt ledger records the operation, arguments, source metadata, and result.
5. Claims and panels resolve their values from receipt references.
6. The checker independently reruns each factual operation and emits a verdict.
7. The normalized event stream is persisted as a replayable case file and rendered progressively.

Tests and release gates

npm test                       # shared, server, and web unit/API tests
./.venv/bin/pytest pipeline/   # committed-artifact QA; raw-source checks skip if unavailable
npm run build -w apps/web      # production Next.js build
npm run e2e                    # complete non-visual Playwright suite
npm run e2e:visual             # visual regression suite
npm run verify:runtime         # runtime pointer, version, pin, field, and ingest integrity
npm run verify:atlas-data      # schemas, hashes, manifests, and data QA
npm run verify:atlas-ui        # type, unit, build, browser, and visual UI gates
npm run verify:atlas           # fail-fast aggregate release oracle
npm run smoke:live             # opt-in GPT-5.6 HTTP/SSE smoke test

Node and Playwright upload tests use the committed RMS fixture and run without drive/. Pipeline tests always validate the committed artifacts; checks that truly require the original PDFs or Eclipse binaries are explicitly skipped when the optional raw corpus is unavailable.

Deployment

Field Brain runs as two Node processes: an Express API on an internal port and a Next.js server on the public port. On a single-service host with a writable filesystem:

# Build command
npm ci && npm run build -w apps/web

# Start command
FIELD_BRAIN_WEB_PORT="$PORT" FIELD_BRAIN_API_PORT=4000 npm run demo

Expose only the Next.js port. The demo command connects the Next.js backend-for-frontend to the internal API and forces key-free deterministic planning.

Runtime fields, chats, pins, and ingest jobs are written under gitignored data/runtime/. They survive a local restart but reset when an ephemeral deployment is replaced. A persistent disk is optional for judging and required only if deployed user state must survive redeployments.

For a remote deployment, the folder picker reads files from the visitor's computer—not from the server. To test the upload interaction, the judge can clone or download this repository locally and choose data/fixtures/rms-export/ while using the deployed application.

Rebuilding processed data from the original corpus

Rebuilding is optional; the committed products are sufficient to run and judge the application. To reproduce extraction, make the Volve working directory available as drive/Data_Oilfield/ and install the Python pipeline dependencies:

ln -s "/path/to/the/team-data-root" drive
python3 -m venv .venv
./.venv/bin/pip install pandas openpyxl duckdb pymupdf resdata pyarrow pytest numpy pillow matplotlib

./.venv/bin/python pipeline/extract_production.py
./.venv/bin/python pipeline/extract_report.py
./.venv/bin/python pipeline/extract_sim.py
./.venv/bin/python pipeline/extract_discovery.py
./.venv/bin/python pipeline/extract_deck.py
./.venv/bin/python pipeline/extract_rms.py
./.venv/bin/python pipeline/extract_sim_maps.py
./.venv/bin/python pipeline/build_atlas_data.py
npm run seed -w apps/server

The extraction code treats the raw source tree as read-only. Generated data is written under data/, and the raw corpus remains gitignored.

Current limitations

• Volve is the only fully connected field; additional fields remain honest shells until a data adapter and verified semantic model are supplied.
• The committed RMS reference values are marked pending domain review even though their extraction and tolerances are deterministic.
• The controlled ingest supports the registered RMS ASCII/fault/LAS subset, not arbitrary file formats or the excluded large Resque payload.
• Demo planning is deterministic. Live GPT-5.6 planning is nondeterministic and makes one bounded API call per question.
• Runtime persistence is filesystem-based and is not yet designed for multi-tenant production use.
• Field Brain is an analytical demonstration, not operational advice for a producing asset.

Licence and attribution

The Field Brain source code is released under the MIT License.

Volve source material and derived data are used under the Equinor Open Data Licence. The data licence is separate from the MIT software licence. See NOTICE for attribution and redistribution details.