factorysemantics-mes 0.1.2__tar.gz → 0.3.0__tar.gz

factorysemantics_mes-0.3.0/.dockerignore

@@ -0,0 +1,78 @@
+# What never goes into an image's build context.
+#
+# Every `docker build` here reads this file, and `docker/Dockerfile` copies
+# named paths rather than the whole tree, so this is about the context that is
+# sent to the builder, not about what ends up in the image. Two reasons it is
+# worth having: a plant's own data must never be able to reach a published
+# image by accident, and the generated replay under `labs/multiplant/*/out/` is
+# 9.7 MB for bottling alone - it is generated from the seed in `line.json` on
+# first start and is never shipped.
+#
+# What this excludes:
+#
+#   */out/, .data/        generated line data and plant state, written at run
+#                         time, regenerated from a seed, never shipped
+#   *.db, *.sqlite, *-wal a plant's own database, in every spelling the code
+#                         writes, plus its write-ahead files
+#   logs/, *.log          a plant's logs
+#   .env, *.pem, *.key,   credentials and certificates. `.env.*` as well as
+#   certs/, .secrets/     `.env`, because an editor's `.env.bak` is a
+#                         committable copy of a credentials file
+#   .venv/, __pycache__/, a developer machine's build leavings, which are for
+#   *.egg-info/, .git/    this platform and this interpreter, not the image's
+#   lab-results/,         evidence from one machine on one day
+#   backups/
+#
+# Wholesale rules rather than an enumerated list of directories, for the reason
+# `.gitignore` gives at the same place: an enumerated rule goes stale silently
+# the first time the code writes somewhere new.
+#
+# Nothing here may match a path `docker/Dockerfile` copies, and nothing here
+# may match a path `pyproject.toml` force-includes into the wheel. The day one
+# does, the image loses a plant pack and `pip install` inside it fails - which
+# is what happened on 2026-10-12 for the other reason, and is why
+# `tests/test_the_docker_image_carries_the_packs.py` reads this file too.
+
+# Generated line data and plant state
+**/out/
+**/.data/
+lab-results/
+backups/
+
+# A plant's own database and logs
+**/*.db
+**/*.db-wal
+**/*.db-shm
+**/*.sqlite
+**/*.sqlite3
+**/*.parquet
+**/logs/
+**/*.log
+
+# Credentials and certificates
+.env
+.env.*
+!.env.example
+**/.secrets/
+**/certs/
+**/*.pem
+**/*.key
+**/*.token
+
+# This machine's build leavings
+.git/
+.venv/
+venv/
+**/__pycache__/
+**/*.py[cod]
+**/*.egg-info/
+build/
+dist/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+htmlcov/
+.coverage
+site/
+skills-dist/
+*.zip

factorysemantics_mes-0.3.0/.env.example

@@ -0,0 +1,112 @@
+# FactorySemantics MES configuration. Copy to .env and adjust; every value has a sane default.
+# All settings are read from environment variables prefixed MES_ (or this file).
+
+# --- Database -------------------------------------------------------------
+# SQLite (default, zero-setup):
+MES_DATABASE_URL=sqlite:///fsmes.db
+# PostgreSQL (scale deployment, matches docker-compose):
+# MES_DATABASE_URL=postgresql+psycopg://mes:mes@localhost:5432/mes_twin
+
+# --- Which plant is this --------------------------------------------------
+# The shape of this deployment: laptop | plant | fleet. `laptop` is the
+# evaluation profile - `fsmes demo` and the labs - and needs nothing else set
+# here. Anything else refuses to start without a plant name.
+MES_PLANT_PROFILE=laptop
+# What this plant is called. It appears on every screen, in /health, on every
+# metric, in every backup and on every namespace event, so a person looking
+# at two plants can tell which one they are looking at. Letters, digits and
+# _ . : @ = - only: it is published as one segment of the namespace topic.
+# MES_PLANT_NAME=northgate
+# The zone this plant works in, as an IANA name. It decides where a shift
+# starts, when a gauge falls due, and what time every screen shows. Left out,
+# the MES uses this machine's own zone and says "defaulted" wherever it
+# reports it. On Windows the zone database comes from `pip install tzdata`.
+# MES_PLANT_TIMEZONE=America/Chicago
+
+# --- Shadow mode ----------------------------------------------------------
+# The MES watches a real plant and can change nothing in it: no PLC
+# write-back, no live ERP, no MQTT publish, nothing about this plant off the
+# box. This is how you run it beside the MES already in charge on a line.
+# Read once at start-up; leaving it is a restart, recorded in the audit
+# trail. With it on, MES_ERP_MODE may only be off or file and MES_UNS_MODE
+# only off or log - anything else refuses to start and says which variable.
+# See docs/operate/shadow-mode.md.
+MES_SHADOW=false
+
+# --- Logging --------------------------------------------------------------
+MES_LOG_LEVEL=INFO
+MES_LOG_DIR=logs
+
+# --- API ------------------------------------------------------------------
+MES_API_HOST=127.0.0.1
+MES_API_PORT=8000
+
+# --- OPC UA ---------------------------------------------------------------
+# Endpoint the agent connects to. Points at the bundled simulator by default;
+# change to your real PLC/gateway endpoint to leave twin mode.
+MES_OPC_ENDPOINT=opc.tcp://127.0.0.1:4840/mes-twin/sim
+MES_OPC_NAMESPACE=urn:mes-twin:sim
+MES_TAG_MAP_FILE=config/tag_map.json
+# The KepSim six-station line instead of the two demo machines:
+#   config/tag_map_kepsim.json   played back by `fsmes run-opc-sim --replay`
+#   config/tag_map_kepware.json  read from a real KEPServerEX (see labs/kepsim)
+
+# Client security. Empty = anonymous and unencrypted, which is all the bundled
+# simulator needs. A real server usually offers only SignAndEncrypt with a named
+# user — Kepware does. The certificate is minted on first use.
+# MES_OPC_SECURITY=Basic256Sha256,SignAndEncrypt
+# MES_OPC_USER=Administrator
+# MES_OPC_PASSWORD=
+MES_OPC_CERT_DIR=certs
+MES_OPC_APPLICATION_URI=urn:mes-twin:agent
+
+# Where `fsmes run-opc-sim --replay` reads the generated KepSim tables from.
+MES_REPLAY_DIR=labs/kepsim/out
+
+# --- ERP integration ------------------------------------------------------
+# rest = poll an ERP REST API (mock ERP by default) | file = B2MML-style file
+# exchange via the inbox/outbox folders | erpnext = a real ERPNext/Frappe
+# instance | off = no ERP sync
+MES_ERP_MODE=rest
+MES_ERP_BASE_URL=http://127.0.0.1:8001
+MES_ERP_INBOX=erp_exchange/inbox
+MES_ERP_OUTBOX=erp_exchange/outbox
+MES_ERP_ARCHIVE=erp_exchange/archive
+MES_ERP_POLL_SECONDS=5
+
+# --- ERPNext (MES_ERP_MODE=erpnext) ---------------------------------------
+# One bench can serve several sites on one port; the site is chosen by the Host
+# header. Leave MES_ERPNEXT_SITE empty only if the bench serves a single site —
+# on a shared one, the default site is somebody else's company.
+MES_ERPNEXT_BASE_URL=http://localhost:8090
+MES_ERPNEXT_SITE=mes.localhost
+MES_ERPNEXT_USER=Administrator
+MES_ERPNEXT_PASSWORD=admin   # the Frappe dev-bench default; a real site uses the API key below
+# Preferred for a long-running worker (ERPNext: User -> API Access -> generate):
+# MES_ERPNEXT_API_KEY=
+# MES_ERPNEXT_API_SECRET=
+# Which company's work orders to import. Empty (the default) imports every
+# company's; a bench serving more than one company must set this.
+# MES_ERPNEXT_COMPANY=Your Company
+# Post finished quantities as real Manufacture stock entries. Off records what
+# the MES counted without moving ERPNext's stock.
+MES_ERPNEXT_POST_STOCK_ENTRY=true
+
+# --- Simulator ------------------------------------------------------------
+# >1.0 makes the simulated plant run faster than real time (demo uses 4).
+MES_SIM_SPEED=1.0
+
+# --- The judgment model (development build loop only) ---------------------
+# A hosted model asked fixed, typed questions about a simulated run's log,
+# beside the local model's open-ended pass. Nothing in the product asks it
+# anything, and shadow mode refuses the call outright (register: llm.jev).
+# Unset — the normal case — and the run record says it was not asked.
+# The key belongs in this file or the environment, never in the repository.
+# MES_JEV_API_KEY=
+# Pinned, never a moving alias: an answer stored against `-latest` cannot be
+# read again. The version actually served is stored with every answer.
+# `fsmes jev models --resolve` says which concrete version answers today.
+# MES_JEV_MODEL=jev-1.13.0
+# Empty uses the client's own endpoint.
+# MES_JEV_BASE_URL=
+# MES_JEV_TIMEOUT_SECONDS=5.0

factorysemantics_mes-0.3.0/.github/dependabot.yml

@@ -0,0 +1,35 @@
+version: 2
+updates:
+  # Python updates run through the `uv` ecosystem, not `pip`, because this
+  # repository has a lockfile and CI requires it to be current.
+  #
+  # `pip` edits the version constraints in `pyproject.toml` and has no
+  # concept of `uv.lock` — it never regenerates it. Since #74 made
+  # `uv lock --check` a required check, that combination meant every
+  # Python bump Dependabot opened arrived with a stale lock and failed
+  # `lockfile` on arrival; #86 (ruff 0.16.7 → 0.16.8) is the one that made
+  # it obvious. The `uv` ecosystem reads `pyproject.toml` and `uv.lock`
+  # together and writes both in the same commit, so the required check
+  # passes without anyone running `uv lock` by hand.
+  #
+  # The group below is carried over unchanged. It groups on `patterns`,
+  # which `uv` supports; the one grouping key `uv` does not support is
+  # `dependency-type`, and this repository never used it. `uv` also treats
+  # every declared dependency as a production one — it draws no dev/prod
+  # line — which changes nothing here, because `patterns: ["*"]` already
+  # puts the runtime dependencies and the `dev`, `docs`, `postgres`,
+  # `mcp`, `agent`, `mqtt` and `jev` extras in one pull request.
+  - package-ecosystem: uv
+    directory: /
+    schedule:
+      interval: weekly
+    groups:
+      python:
+        patterns: ["*"]
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    groups:
+      actions:
+        patterns: ["*"]

factorysemantics_mes-0.3.0/.github/scripts/demo_from_wheel.sh

@@ -0,0 +1,64 @@
+#!/usr/bin/env bash
+# Prove a built wheel runs the demo, with nothing but the wheel to run it from.
+#
+# 0.1.0 installed cleanly from PyPI and did not work: the wheel carried no
+# config/tag_map.json, so the simulator had no line, nothing was ever booked,
+# and `fsmes demo` exited 0 regardless. The Release Checklist's clean-machine
+# install was the line that would have caught it, and it was skipped for
+# speed. This is that line, automated, so speed cannot skip it.
+#
+# Usage: demo_from_wheel.sh <wheel> [duration-seconds]
+set -euo pipefail
+
+wheel_arg="${1:?usage: demo_from_wheel.sh <wheel> [duration-seconds]}"
+wheel="$(cd "$(dirname "$wheel_arg")" && pwd)/$(basename "$wheel_arg")"
+# The demo stops watching after this many seconds; it exits as soon as the
+# order completes, so a generous number costs nothing when the wheel is good.
+duration="${2:-300}"
+
+# An empty directory containing none of the repository's files. That is the
+# whole point: no config/, no .env, no fsmes.db, no src/ to import instead of
+# the installed package.
+work="$(mktemp -d)"
+trap 'rm -rf "$work"' EXIT
+cd "$work"
+
+python -m venv .venv
+.venv/bin/python -m pip install --quiet --upgrade pip
+.venv/bin/python -m pip install --quiet "$wheel"
+# What the wheel says it is, asked two ways: the distribution metadata pip
+# installed, and the answer a user gets from the command line. These were a
+# version apart in 0.1.2 — the metadata said 0.1.2, `fsmes --version` said
+# 0.1.0 — because the number was written down twice. It is written down once
+# now (src/fsmes/__init__.py, which hatchling stamps the metadata from), and
+# this is the line that keeps it that way: a wheel whose two answers disagree
+# never reaches PyPI.
+echo "wheel: $(basename "$wheel")"
+metadata_version="$(.venv/bin/python -c "from importlib.metadata import version; print(version('factorysemantics-mes'))")"
+reported_version="$(.venv/bin/fsmes --version)"
+echo "installed: ${metadata_version}"
+echo "fsmes --version: ${reported_version}"
+if [ "$reported_version" != "fsmes ${metadata_version}" ]; then
+    echo "::error::the wheel's metadata says ${metadata_version} but 'fsmes --version' says '${reported_version}'"
+    exit 1
+fi
+
+set +e
+timeout 900 .venv/bin/fsmes demo --duration "$duration" 2>&1 | tee demo.log
+exit_code="${PIPESTATUS[0]}"
+set -e
+
+# Two separate questions, and both have to be asked. The exit code only became
+# meaningful when the demo learned to fail; an older wheel exits 0 while
+# booking nothing, and only the output tells you which one you have.
+if [ "$exit_code" -ne 0 ]; then
+    echo "::error::fsmes demo exited ${exit_code} from the built wheel"
+    exit 1
+fi
+
+if ! grep -q "Demo result: full loop closed" demo.log; then
+    echo "::error::the wheel installed but the demo never closed its loop"
+    exit 1
+fi
+
+echo "The wheel ran the demo to a closed loop."

factorysemantics_mes-0.3.0/.github/scripts/lab_starters.sh

@@ -0,0 +1,138 @@
+#!/usr/bin/env bash
+# Run the lab's starter experiments and prove each one produced a readable run.
+#
+# The instrument is the thing being tested here, not the plant: an experiment
+# that stops running is an experiment nobody notices has stopped, because it is
+# only ever run by hand. So every starter runs on every pull request, and the
+# check is that the directory it leaves behind holds what the page says it
+# holds - a plan, the truth, what each plant recorded, the scores and a report.
+#
+# It does NOT assert any particular measurement. A scored run is an instrument
+# reading and not a test: withholding a verdict because the runner fell behind
+# is the harness working, and failing CI on it would teach everyone to stop
+# reading the number. What fails this script is a run that did not happen.
+#
+# Usage: lab_starters.sh [plan ...]     (default: every plan in labs/experiments)
+set -euo pipefail
+
+plans=("$@")
+if [ ${#plans[@]} -eq 0 ]; then
+  mapfile -t plans < <(ls labs/experiments/*.toml)
+fi
+
+results="$(pwd)/lab-results"
+rm -rf "$results"
+
+# The design store this run's plants and notes use. Pointed at the results
+# directory so a scripted run proves the feedback loop without writing into
+# anybody's real notes, and so the store travels with the runs as an artifact.
+export MES_DESIGN_STORE="$results/design.db"
+mkdir -p "$results"
+
+for plan in "${plans[@]}"; do
+  echo "::group::fsmes lab run $plan"
+  fsmes lab run "$plan" --results "$results"
+  echo "::endgroup::"
+done
+
+fsmes lab list --results "$results"
+
+# The feedback loop, end to end and with no model anywhere: a note left
+# against a run appears in that run's report beside the screen it names, and
+# `fsmes lab review` rolls every run up into one cited findings.md.
+# The note is left against a run that measured `booking`, because the check
+# below is that it renders *beside the booking numbers* - a run whose plan
+# asked for other measurements has no such section for it to sit beside, and
+# asserting against one is a check about which starter happens to sort first.
+first_run="$(python - "$results" <<'PICK'
+import json
+import sys
+from pathlib import Path
+
+for run in sorted(p for p in Path(sys.argv[1]).iterdir() if (p / "scores.json").is_file()):
+    scores = json.loads((run / "scores.json").read_text(encoding="utf-8"))
+    if "booking" in scores.get("measurements_asked_for", []):
+        print(run)
+        break
+else:
+    sys.exit("no run measured booking, so the feedback check has nothing to sit beside.")
+PICK
+)/"
+plant="$(python -c "import json,sys; print(json.load(open(sys.argv[1]))['plants'][0]['plant'])" \
+         "${first_run}scores.json")"
+note="the orders list does not say how many orders there are"
+fsmes lab note "${first_run%/}" "$note" --screen /dashboard/orders --plant "$plant"
+fsmes lab review --results "$results" --no-model --out "$results/findings.md"
+
+python - "$results" "${#plans[@]}" "$note" <<'PY'
+import json
+import os
+import sys
+from pathlib import Path
+
+results, expected, note = Path(sys.argv[1]), int(sys.argv[2]), sys.argv[3]
+runs = sorted(p for p in results.iterdir() if (p / "scores.json").is_file())
+if len(runs) != expected:
+    sys.exit(f"{expected} plan(s) ran and {len(runs)} run directory(ies) appeared in {results}.")
+
+summary = ["| Run | Plants | Withheld | Measurements |", "|---|---|---|---|"]
+for run in runs:
+    scores = json.loads((run / "scores.json").read_text(encoding="utf-8"))
+    missing = [name for name in ("plan.toml", "truth.json", "scores.json",
+                                 "report.html", "notes.md", "recorded",
+                                 "feedback/conversations.jsonl")
+               if not (run / name).exists()]
+    if missing:
+        sys.exit(f"{run.name} is missing {', '.join(missing)}.")
+    if scores["plants_run"] != scores["plants_total"]:
+        sys.exit(f"{run.name}: {scores['plants_run']} of {scores['plants_total']} plants ran.")
+    # A measurement is either about one plant or about the run. Both count;
+    # what does not count is a plan asking for one and the directory holding
+    # neither, which is how a report comes to say less than it was asked for.
+    run_wide = scores.get("measurements") or {}
+    for name in scores["measurements_asked_for"]:
+        if name in run_wide:
+            continue
+        for plant in scores["plants"]:
+            if name not in plant["measurements"]:
+                sys.exit(f"{run.name}: {plant['plant']} has no {name} measurement, and the plan "
+                         f"asked for one.")
+    page = (run / "report.html").read_text(encoding="utf-8")
+    if "http://" in page or "https://" in page:
+        sys.exit(f"{run.name}: report.html fetches something from the network. A results "
+                 f"directory has to open on a machine that has none.")
+    withheld = sum(1 for p in scores["plants"] if p["verdict_withheld"])
+    summary.append(f"| {run.name} | {scores['plants_run']} | {withheld} | "
+                   f"{', '.join(scores['measurements_asked_for'])} |")
+    print(f"{run.name}: {scores['plants_run']} plant(s), {withheld} verdict(s) withheld")
+
+# The note went to the first run that measured booking; it has to be in that
+# run's report, under the section for the screen it names rather than in an
+# appendix somewhere.
+first = next(run for run in runs
+             if "booking" in json.loads(
+                 (run / "scores.json").read_text(encoding="utf-8")
+             ).get("measurements_asked_for", []))
+page = (first / "report.html").read_text(encoding="utf-8")
+if note not in page:
+    sys.exit(f"{first.name}: the note left with `fsmes lab note` is not in report.html.")
+if page.index("Booking honesty") > page.index(note):
+    sys.exit(f"{first.name}: the note is not rendered beside the booking numbers it is about.")
+
+findings = results / "findings.md"
+if not findings.is_file():
+    sys.exit("`fsmes lab review` wrote no findings.md.")
+rolled = findings.read_text(encoding="utf-8")
+for run in runs:
+    if run.name not in rolled:
+        sys.exit(f"findings.md does not cite {run.name}.")
+if f"> {note}" not in rolled:
+    sys.exit("findings.md does not quote the note verbatim.")
+print(f"feedback: the note is in {first.name}'s report and findings.md cites "
+      f"{len(runs)} run(s)")
+
+step = os.environ.get("GITHUB_STEP_SUMMARY")
+if step:
+    with Path(step).open("a", encoding="utf-8") as handle:
+        handle.write("\n".join(summary) + "\n")
+PY