foreman

What it is

Production lines generate data non-stop — sensor readings, PLC states, maintenance records, operator notes. Classic monitoring systems show the current state and raise an alarm when a threshold is crossed. What they lack is memory. They don't know that the same bearing temperature preceded a failure three weeks ago, or that a slow drift has been building for days.

FOREMAN closes that gap. It lays a reasoning layer with long-term memory over the production environment and answers questions that snapshots can't:

• Which chain of events led to this failure?
• Is a process slowly drifting out of its normal range?
• When is this component likely to fail?
• What load has this machine actually carried — and where were its limits?

The name says it all: a foreman is the experienced supervisor who has known the shop floor for years — and that institutional experience is exactly what FOREMAN provides as a system.

Context: FOREMAN is the capstone project of the MSIT AI track. It combines an industrial background (workshop management, field service, PLC programming) with applied AI architecture.

Try it live

A public demo instance is available — no registration, no request. The credentials below are
deliberately shared so anyone can look around.

The login is the plant manager profile: it sees the whole fleet, writes shift notes, triggers
the reasoners and acknowledges alarms — every capability is reachable from this one account, with
no role switching.

Where to start: the fleet cockpit gives you the overall picture; a machine card shows live
sensor values with an honest status per data point; the archive searches notes, maintenance
records, alarms and the memory together, and marks a result that two of them found
independently. The reasoners are on demand — reconstructing an event chain or
requesting a recommendation is a deliberate click, never automatic.

A few honest notes before you click:

• The interface is German. FOREMAN speaks the language of the shop floor it was designed for.
• The data is simulated. No real plant is connected. Every prediction carries a visible
  simulation caveat — that is a deliberate design rule, not a placeholder.
• It is a shared instance. Anything you enter is visible to everyone else trying the demo,
  and it stays in the database. Please do not enter real personal data. Worker notes are
  run through name redaction before they are stored, but that is a safety net, not a guarantee.
• AI analyses are rate-limited. The reasoners call a language model, and the demo runs on a
  capped budget. If an analysis is temporarily unavailable, the rest of the system keeps working
  — alarms, trends and the archive are unaffected.
• Nothing here switches anything. FOREMAN explains, it does not actuate. There is no path
  from this interface to a machine.

Architecture

Three cleanly decoupled layers. Industry delivers the data, FOREMAN reasons, operators act.

flowchart TB
    subgraph L1["① Industrial Environment"]
        direction LR
        SPS[PLC / OPC UA] 
        MQTT[MQTT / Modbus]
        LOGS[Logs & Maintenance History]
    end

    subgraph L2["② FOREMAN Reasoning Platform"]
        direction TB
        ING[Ingestion Service]
        subgraph R["Four Reasoners"]
            direction LR
            R1[Event-Chain\nReconstruction]
            R2[Drift\nDetection]
            R3[Failure\nPrediction]
            R4[Maintenance\nCycle Analysis\n— planned]
        end
        GW[Model Gateway\nlocal + cloud]
    end

    subgraph L3["③ Output Channels"]
        direction LR
        DASH[Operator Dashboard]
        MCP[MCP Interface\nfor third-party systems]
    end

    MEM[(Memory Substrate\nexternal service)]

    L1 --> ING --> R
    R <--> GW
    R <--> MEM
    R --> DASH
    R --> MCP

The four reasoners

Load data, not load simulation. FOREMAN does not run its own load simulation — a real one needs parameters outside FOREMAN's observation boundary (machine timing, tool/material behaviour, environment) that the platform never sees. Instead it exposes the observed load profiles and limits read-only over the MCP interface, for an external simulation tool to build on. See GROUND_TRUTH.md §2 / §17.

The memory substrate

FOREMAN builds on an external, biologically inspired memory substrate that it consumes like a database. The substrate manages semantic events over time, consolidates recurring patterns, and monitors stability automatically. For FOREMAN it is a black-box dependency behind an HTTP API — the substrate code is not part of this repository.

Tech stack

Project structure

foreman/
├── README.md              ← you are here
├── GROUND_TRUTH.md        ← the specification (single source of truth)
├── CLAIMS.md              ← generated view of the claims register (what may be said, with evidence)
├── SECURITY.md            ← threat model, deployment profiles, what counts as a finding
├── DEPLOY.md              ← the public demo on Railway, step by step
├── AGENTS.md · REVIEW.md  ← the same context for coding agents and reviewers
├── pyproject.toml         ← deps + strict typing/lint/test config
├── docker-compose.yml     ← TimescaleDB + app for local development
├── Dockerfile             ← backend runtime image (incl. NER model)
├── railway.toml · railway.worker.toml · frontend/railway.toml ← Railway config-as-code
├── src/foreman/           ← application package (api · core · db · reasoners · llm · embeddings · mcp · substrate · …)
├── migrations/            ← Alembic migrations (schema + TimescaleDB setup)
├── tests/                 ← unit + integration tests
├── frontend/              ← Next.js operator dashboard (BFF, bespoke SVG, 3D line view)
├── claims/                ← claims register source + word lists
├── compliance/            ← machine-checkable regulatory scope, retention policy, SoA
├── security/              ← findings register (pre-triaged, verified in CI)
├── scripts/ · tools/      ← register checks run by CI and before anything leaves the house
├── docs/
│   ├── WALKTHROUGH.md     ← plain-language explanation of every building block (German)
│   ├── research/          ← binding implementation references
│   ├── compliance/        ← EU AI Act + GDPR assessments (the reasoning behind compliance/)
│   ├── models/            ← model card of the failure-prediction demonstrator
│   └── messungen/         ← measurement protocols behind the register entries
├── .env.example           ← configuration contract (no secrets)
└── .gitignore             ← protects secrets & the memory connection

Code is added module by module. See GROUND_TRUTH.md for the binding state and docs/WALKTHROUGH.md for the plain-language explanation.

Documentation principle

This project deliberately maintains two documents in parallel:

• GROUND_TRUTH.md — the truth. What holds: schema, routes, stack, conventions. Machine-near and concise.
• docs/WALKTHROUGH.md — the explanation. Why and how, in plain language. Per building block: what it does and where it sits in the architecture. (Written in German.)

Both are updated in the same commit as the code. That reduces drift; it does not
abolish it. Where documentation and code disagree, the documentation is the defect — and
it is worth reporting. Two such drifts were found and closed on 2026-08-26, recorded as
F-007 and F-008 in security/findings.yaml.

Engineering standards

This platform is built to rigorous, reviewable standards — not vibe-coded.
Every change passes defined gates before it reaches main:

• Type safety — mypy --strict / tsc --noEmit, zero errors
• Lint & complexity — ruff / eslint, clean; cyclomatic complexity capped at 12 in
  application code (ruff C90; the check scripts are exempt, with the reason in pyproject.toml)
• Tests — pytest, ≥ 85 % coverage, a mandatory test block per feature
• Security — OWASP Web & LLM Top 10 (2025); gitleaks over the full history and pip-audit / npm audit run as gates in CI, with Dependabot security alerts as a second source
• Privacy by design — GDPR Art. 25: worker data pseudonymized at the adapter layer (HMAC tokens; free-text names NER-masked)
• EU AI Act — risk classification documented before code is written (Phase 0)
• Observability — structured per-reasoner logs + Prometheus metrics (OWASP A09)
• Human-in-the-loop — safety-critical recommendations require operator acknowledgment (BSI)
• Bounded consumption — rate-limiting + pinned model versions (LLM10 / LLM03)
• Living docs — GROUND_TRUTH + WALKTHROUGH updated in the same commit; where they
  disagree with the code, the documentation is the defect and gets reported as one
• Agent governance (AEOS) — the code is written with AI coding agents under AEOS, a
  private rule-and-guard layer between the agent and the shell. Blocking rules refuse,
  among others, direct pushes to main, force pushes, recursive deletes, pushes with a
  red linter, f-string SQL, and any read or transfer of secret files; every decision is
  written to .claude/aeos-log.jsonl with the rule that made
  it. The guards enforce the process — they do not replace the review

See GROUND_TRUTH.md §10 for the binding definition.

Testing

Every push and pull request runs three CI jobs (see the CI badge at the top). The
backend job is mypy --strict, ruff check, ruff format --check and pytest
against a real TimescaleDB/pgvector service, not mocks, followed by the three register
checks (regulatory scope, findings, claims) and pip-audit. Alongside it, gitleaks scans the full history in its own job,
and the frontend job runs token sync, tsc --noEmit, eslint, vitest, npm audit and
a production build. The backend suite is layered:

Current state (measured 2026-09-07, own run against a real TimescaleDB): 1579 backend tests green (2 skipped — they need a local model — and 9 opt-in tests deselected: 7 NER, 2 release checks that run against a live counterpart), plus 995 frontend tests across 165 files. 94.33 % branch coverage in the CI run of 2026-08-22 (94.39 % in the run above). mypy --strict 0 errors across 155 source files, ruff check and format clean over 367 files, tsc --noEmit and eslint clean. The coverage gate fails the build under 85 % — enforced in pyproject.toml, not just claimed. Each feature ships a mandatory test block (happy path · error · auth · edge), and docs (GROUND_TRUTH + WALKTHROUGH) move in the same commit as the code.

Numbers in this README are entries in the claims register — each one carries its measurement conditions, its evidence status, and the date it was taken. A measurement without a register entry counts as not having happened (see GROUND_TRUTH.md §23).

uv run mypy && uv run ruff check && uv run ruff format --check && uv run pytest   # the same gate CI runs

Local development

Requirements: Python 3.12, uv, Docker.

# 1. Dependencies (isolated environment)
uv venv --python 3.12
uv pip install -e ".[dev]"

# 2. NER model for worker-note redaction (~560 MB)
uv run python -m spacy download de_core_news_lg

# 3. Configuration — copy and fill in (never commit real secrets)
cp .env.example .env

# 3b. Guard hooks — keeps the guard log current and scans it before each commit
git config core.hooksPath .githooks

# 4. Database + app
docker compose up -d timescaledb
uv run alembic upgrade head            # schema + TimescaleDB setup
uv run uvicorn foreman.main:app --reload

# 5. Quality gates
uv run mypy && uv run ruff check && uv run ruff format --check && uv run pytest

Integration tests run against a real TimescaleDB (timescale/timescaledb-ha:pg16). Point FOREMAN_TEST_DATABASE_URL at a test database; without a reachable database the integration tests skip automatically.

Status

🚧 Active development. In main: the foundation (F2 — schema, TimescaleDB migrations, JWT auth, CRUD + batch ingestion, pseudonymization + NER), data adapters with a synthetic simulation (F3), the drift reasoner (F4 — ADWIN over river), the model gateway (F-LLM — own LLMGateway abstraction over LiteLLM, local-first), the event-chain reasoner (F6 — the first LLM free-text reasoner, with a sharp prompt-injection red-team), semantic note search (F-SEM — embeddings + HNSW), the failure-prediction reasoner (F-PRED — an honestly declared method demonstrator on simulation data, see its model card) with its LLM explanation layer (F-REC), the read-only MCP interface (F7), and the operator dashboard (F5 — eight of ten sections built, the platform/audit view among them; a 3D line view of the plant and a memory-only mode of the archive were added in August/September 2026).

Three of the four reasoners are built. Still open: maintenance-cycle analysis (reasoner #4 — data-dependent, it needs a real maintenance history) and the two remaining dashboard sections (maintenance, load), which are marked placeholders in the demo. Roadmap and binding state live in the GROUND_TRUTH; what may be claimed about any of it lives in CLAIMS.md.

Reviewing this repository

FOREMAN is published so it can be looked at, and it is built in the open while it is
still being built. Two things follow from that, and both are written down rather than
left to be inferred.

The public demo and the target deployment are different on purpose. The demo is
internet-reachable, runs on synthetic data and hands out its credentials in this README.
The platform is designed for an on-premises plant network with real data and per-user
accounts. Several controls sit at the network boundary in the second picture and are
genuinely absent in the first. Which one a finding refers to changes what it means.

A repository shows the application layer. Configuration values, TLS, network
segmentation, secrets storage and the external memory service are not in it —
.env.example lists which variables exist, not what they are set to.

• SECURITY.md — threat model, trust boundaries, the two deployment
  profiles, and what does and does not count as a vulnerability here
• security/findings.yaml — twenty-three findings a review is likely
  to surface, each with the observation, whether it is correct, the deployment assumption
  behind any acceptance, and its status. Six are accepted risks with that condition
  recorded, three are open work, thirteen are already closed, one is a documented false
  positive. Verified in CI by scripts/check_findings.py, including these counts.
• REVIEW.md · AGENTS.md — the same context for automated
  reviewers and coding agents
• SECURITY-INSIGHTS.yml — machine-readable posture
  (OpenSSF Security Insights)
• .claude/aeos-log.jsonl — the guard log. One line per tool call
  a coding agent made in this repository: which rule applied, whether it was allowed or
  blocked, and how long the check took. It is committed by a pre-commit hook rather than
  curated, so it shows the ordinary days as well as the interesting ones. The schema carries
  no command text — reason holds the rule that fired, not the input that triggered it — and
  the same hook runs gitleaks over the file before every commit and refuses the commit if
  either that scan or the tool itself is missing.

None of these ask a reviewer to omit anything. They exist so that the step between a
finding and a verdict is written down instead of improvised — and a finding that
contradicts what they claim is the most useful report this project can receive.

Author

Patric Zeller — AI architect · patric-zeller.de · GitHub · LinkedIn

License

© 2026 Patric Zeller. All rights reserved. This repository is published publicly as a showcase for evaluation only and is not licensed for reuse. See LICENSE for the full terms.