MineOps

MineOps is an AI-native mining operations platform built on a reliable industrial telemetry foundation. It combines two end-to-end loops:

Data loop:
Fleet simulator -> MQTT -> ingestion -> PostgreSQL -> FastAPI

Decision loop:
Operator goal -> Operations Copilot -> read-only tools -> evidence
              -> structured findings -> approval-gated action

The project is intentionally more than a chatbot over sensor data. The model participates in the operational workflow, but deterministic services remain the source of truth and people retain authority over consequential actions.

What works now

The telemetry platform provides:

• schema-validated mining fleet events
• idempotent ingestion using a stable event_id
• protection against out-of-order events regressing latest device state
• in-memory demo and PostgreSQL/MQTT service profiles
• REST endpoints for latest state and device history

The Operations Copilot provides:

• natural-language investigation goals
• model-selected, read-only fleet and history tools
• evidence IDs attached to every finding and proposed action
• Pydantic-validated structured output
• explicit human approval or rejection for operational actions
• run metadata for provider, model, latency, tool traces, and token usage
• deterministic regression evals that run without network access
• optional GPT-5.5 integration through the OpenAI Responses API

Run the local AI-native demo

make setup
make demo

Open:

• API documentation: http://127.0.0.1:8000/docs
• health and event count: http://127.0.0.1:8000/health
• latest device state: http://127.0.0.1:8000/api/v1/devices

Create an investigation:

curl -s http://127.0.0.1:8000/api/v1/copilot/investigations \
  -H 'content-type: application/json' \
  -d '{"goal":"Find unsafe equipment and recommend the next action."}'

The default deterministic provider keeps the full workflow runnable in CI and portfolio demos. It uses the same tools, evidence contract, report schema, and approval boundary as the hosted model path.

Use GPT-5.5

Set these environment variables before starting the API:

export MINEOPS_COPILOT_PROVIDER=openai
export MINEOPS_OPENAI_API_KEY=your_api_key
export MINEOPS_OPENAI_MODEL=gpt-5.5
export MINEOPS_OPENAI_REASONING_EFFORT=low
make demo

The model can decide which read-only tool to call and in what order. It cannot directly isolate equipment, shut down a process, dispatch a worker, or create a maintenance ticket. It can only propose those actions for a separate human decision endpoint.

Do not commit API keys or place them in telemetry, prompts, or tool outputs.

Why this is AI-native

MineOps treats AI as a bounded decision component rather than a presentation feature:

1. The input is an operator goal, not a fixed query form.
2. The agent chooses tools against live operational state.
3. Deterministic tools own calculations and data access.
4. Findings must cite tool-produced evidence.
5. Output is a typed contract, not free-form prose.
6. Consequential actions stop at a human approval boundary.
7. Traces and evals measure behavior across model or prompt changes.
8. The system still degrades to a useful local provider when the model is unavailable.

See AI-native scorecard and ADR 0002.

Learn the project from zero

Use the Chinese step-by-step learning guide as the main study entry. It teaches the non-AI telemetry path first, then the AI tools, agent orchestration, evidence validation, approval workflow, and evaluations.

The learning guide is for understanding the current code. The roadmap is for building future milestones after the current system is understood.

Run tests

make test
make lint

The copilot regression suite covers critical, warning, and normal fleet scenarios. Online model evals are deliberately separate because they incur cost and require credentials.

Run the infrastructure stack

After installing Docker Desktop:

docker compose up --build

This starts:

• simulator: publishes mine fleet telemetry
• mqtt: Eclipse Mosquitto broker
• ingest: validates and writes MQTT events
• postgres: stores event history and latest device state
• api: exposes telemetry queries and the copilot workflow

The local Mosquitto configuration is intentionally unauthenticated for development. Do not deploy it to a public network.

Repository layout

src/mineops/
  api.py                 FastAPI service and workflow endpoints
  copilot/
    agent.py             local and OpenAI agent providers
    models.py            typed reports, evidence, traces, and approvals
    service.py           run state and human decision boundary
    tools.py             deterministic read-only operations tools
  ingest.py              MQTT ingestion service
  models.py              telemetry contract
  repository.py          in-memory and PostgreSQL persistence
  simulator.py           deterministic fleet simulator
  db/schema.sql          initial database schema
tests/                   unit, API, and copilot regression evals
docs/                    roadmap, scorecard, and architecture decisions

Next milestones

1. Persist copilot runs, evidence, and approval decisions in PostgreSQL.
2. Add authenticated operator/supervisor roles and policy-configured actions.
3. Build a larger eval dataset and compare model quality, latency, and cost.
4. Add TimescaleDB, PostGIS, geofences, and trajectory tools.
5. Add edge buffering, replay, and network-failure investigations.
6. Deploy to Azure with OpenTelemetry, GitHub Actions, and Terraform.

Start with the step-by-step learning guide, then use the roadmap for future milestones. Resume claims should describe only completed and verified behavior.