КМГ Геоархив, GeoArchive

Project Overview

GeoArchive is an on-prem document-AI pipeline that turns scanned, Soviet-era geological archives into a queryable spatial map and a cited knowledge base. It was built for the 2nd KMG Digital Hackathon (sponsored by KazMunayGas / ҚазМұнайГаз, Atyrau), on the Geology track, "recognize geological documents → structured data → AI knowledge base." This is a hackathon proof-of-concept, preserved as a portfolio piece.

Live demo →. Runs entirely in the browser on seeded demo data. All content is fabricated; no real KazMunayGas data is used.

The Challenge

Kazakhstan's legacy oil province, Mangystau and the Pre-Caspian basin, sits on decades of paper geological records: well logs, core descriptions, lithology columns, much of it scanned but never structured. Industry data puts the failure rate of oil-and-gas AI projects at roughly 80%, with data quality as the root cause. Digitizing brownfield archives is the data-readiness layer that has to come first.

The defining constraint: this is state-energy data. It cannot be sent to a hosted LLM API. Anything that touches it has to run inside the operator's perimeter.

The Solution

A four-stage pipeline, modelled end-to-end:

• VLM parse, a local vision-language model reads each scanned page; no cloud API.
• Schema extract, structured facts (coordinates, formation tops, porosity, permeability, total depth, dates) pulled against a strict schema, each with a confidence score.
• Geo + index, facts land in PostGIS (spatial) and pgvector (semantic); wells and fields become points on a map.
• Ask, natural-language questions answered with citations back to the source page and bounding box.

Three design choices make it defensible for a regulated, state-energy buyer:

• On-prem by design. The VLM runs locally, "интернет выключен, данные никуда не уходят." This kills the single biggest procurement objection before it's raised.
• Provenance, not vibes. Every value links to document → page → bounding box → confidence. Low-confidence extractions route to a human review queue instead of silently entering the record.
• Append-only audit. Every edit is signed (who / when / old → new) on an immutable log; the source scan is never mutated. Built for an environment where "nothing silently changed" is itself a trust requirement.

Technical Implementation

Frontend (apps/web)

• Next.js 16 + React 19 + TypeScript
• Bilingual, dark-first operator UI: spatial map, import pipeline, review queue, archive, and a command-bar RAG query surface
• A fit-to-bounds map projection so a regional dataset spreads across the canvas instead of collapsing to a single point

Backend (apps/api)

• FastAPI (Python), chosen deliberately: the local VLM and the RAG layer are Python-native, and the on-prem rule forbids hosted model APIs, so a Python process is required regardless. FastAPI collapses the whole stack to one language and one container.
• A swappable OCR/VLM engine behind an adapter interface, config selects the implementation, so a "clean digital LAS instead of scans" scenario swaps the engine without touching the pipeline.
• PostGIS spatial queries on a GIST-indexed geometry column; pgvector with an HNSW index for semantic search.
• Append-only audit enforced at two layers: a SQLAlchemy before_flush listener plus a Postgres BEFORE UPDATE/DELETE trigger.
• Alembic migrations and a two-tier test suite (fast SQLite lane + a Postgres-backed migration test that gates the real PostGIS/pgvector/trigger stack).

The portfolio demo

The live link runs apps/web only, in demo mode: a client-side mock stands in for the FastAPI backend so the entire UX is explorable with zero infrastructure. Upload any file and the staged pipeline (parse → extract → geocode) runs, then the newly "extracted" well drops onto the map. The backend is real and tested, but isn't part of the public demo. Its defining feature, the local VLM, is on-prem by design and can't run in a serverless preview.

Lessons Learned

• Constraints are the moat. The on-prem requirement looked like a limitation, but it was the whole pitch. It's the one thing a hosted competitor structurally cannot copy. Designing to the constraint produced a stronger product than designing around it.
• Provenance beats accuracy for trust. In a state-corp context, a slightly-wrong value you can trace to a page and a person is worth more than a confident black-box answer. The audit log and citation trail were features, not overhead.
• Pick the demo's wow before the architecture. The spatial map was always going to be the three-minute hook, so the data model was shaped to make the map effortless and the knowledge graph optional, not the other way around.
• A test backend that can't model production types proves nothing. The API suite was "all green" on SQLite while never exercising the PostGIS/pgvector types or the raw-SQL migrations. Surfacing that, and adding a Postgres-backed lane, was a sharper lesson than any feature.