factorysemantics-mes 0.1.0__tar.gz

factorysemantics_mes-0.1.0/.env.example

@@ -0,0 +1,69 @@
+# 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
+
+# --- 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=
+MES_ERPNEXT_COMPANY=ACME Beverages
+# 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

factorysemantics_mes-0.1.0/.github/CODEOWNERS

@@ -0,0 +1,2 @@
+# Until module maintainers exist, everything is reviewed by the founding maintainer.
+* @kalwei

factorysemantics_mes-0.1.0/.github/ISSUE_TEMPLATE/bug.yml

@@ -0,0 +1,49 @@
+name: Bug
+description: Something the MES did that it should not have, or did not do that it should have.
+labels: [bug]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks. Please use the simulator to reproduce where you can, and never paste real plant data, tag names that identify a customer, or screenshots with company names.
+  - type: textarea
+    id: info
+    attributes:
+      label: fsmes info
+      description: Paste the output of `fsmes info` (version, install location, modules).
+      render: text
+    validations:
+      required: true
+  - type: dropdown
+    id: plant
+    attributes:
+      label: Simulated or real?
+      options:
+        - Simulated (fsmes demo, fsmes plant, fsmes score)
+        - Real plant (no data in this report)
+    validations:
+      required: true
+  - type: textarea
+    id: steps
+    attributes:
+      label: Steps to reproduce
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: What you expected
+    validations:
+      required: true
+  - type: textarea
+    id: actual
+    attributes:
+      label: What happened instead
+    validations:
+      required: true
+  - type: textarea
+    id: logs
+    attributes:
+      label: Logs
+      description: Relevant lines from `logs/`, with anything identifying removed.
+      render: text

factorysemantics_mes-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,11 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Question
+    url: https://github.com/factorysemantics/factorysemantics-mes/discussions/categories/q-a
+    about: Ask in Discussions — searchable, and someone else probably had it too.
+  - name: Idea or design change
+    url: https://github.com/factorysemantics/factorysemantics-mes/discussions/categories/ideas
+    about: Propose it in Ideas first; accepted ideas become decision records.
+  - name: Security vulnerability
+    url: https://github.com/factorysemantics/factorysemantics-mes/security/advisories/new
+    about: Never in a public issue. Use private reporting or security@factorysemantics.com.

factorysemantics_mes-0.1.0/.github/ISSUE_TEMPLATE/integration.yml

@@ -0,0 +1,31 @@
+name: Integration problem
+description: The MES and another system (ERPNext, Kepware, an OPC UA server, an MCP client) do not agree.
+labels: [integration]
+body:
+  - type: input
+    id: partner
+    attributes:
+      label: The other system and its version
+      placeholder: ERPNext v16.3 / KEPServerEX 6.17 / Claude Desktop 1.x
+    validations:
+      required: true
+  - type: textarea
+    id: info
+    attributes:
+      label: fsmes info
+      render: text
+    validations:
+      required: true
+  - type: textarea
+    id: fails
+    attributes:
+      label: What fails, exactly
+      description: The request or message on our side, and what came back. No credentials, no real data.
+    validations:
+      required: true
+  - type: textarea
+    id: config
+    attributes:
+      label: Relevant configuration
+      description: The MES_… settings involved, with secrets removed.
+      render: text

factorysemantics_mes-0.1.0/.github/ISSUE_TEMPLATE/plant-pack.yml

@@ -0,0 +1,26 @@
+name: A plant needed a code change
+description: House rule 4 says adding a plant is configuration, not code. If yours needed code, that is a bug — tell us which.
+labels: [bug, from-the-field]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Describe the plant in the abstract (line shape, number of stations, what the PLCs expose). No company names, no real tag names.
+  - type: textarea
+    id: plant
+    attributes:
+      label: The plant, in the abstract
+    validations:
+      required: true
+  - type: textarea
+    id: change
+    attributes:
+      label: The code change it needed
+      description: What you had to edit under `src/` and why the tag map or plant pack could not express it.
+    validations:
+      required: true
+  - type: textarea
+    id: info
+    attributes:
+      label: fsmes info
+      render: text

factorysemantics_mes-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,18 @@
+## What
+<!-- one paragraph: what a user notices -->
+
+## House rules touched
+- [ ] Never invent production — counters, resets, stale notifications handled
+- [ ] Unknown ≠ zero — every KPI that can't be computed returns null with a reason
+- [ ] Unlabelled stays unlabelled
+- [ ] Config not code at plant boundaries — no plant literals in `src/`
+- [ ] Tests named as prose
+- [ ] Charts looked at with real (simulated) data
+
+## Simulated or real?
+<!-- which plant this was run against (`fsmes score <plant>` / `fsmes demo`), and at what speed -->
+
+## Checklist
+- [ ] `ruff check .` and `pytest` pass locally
+- [ ] Every commit is signed off (`git commit -s`)
+- [ ] No real plant data, employer or customer names anywhere in the change

factorysemantics_mes-0.1.0/.github/dependabot.yml

@@ -0,0 +1,16 @@
+version: 2
+updates:
+  - package-ecosystem: pip
+    directory: /
+    schedule:
+      interval: weekly
+    groups:
+      python:
+        patterns: ["*"]
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    groups:
+      actions:
+        patterns: ["*"]

factorysemantics_mes-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,55 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_call:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        # Windows is a first-class target, not an afterthought: this MES is
+        # expected to run on plant PCs, and the single-writer lock exists in
+        # its O_EXCL form precisely because there is no fcntl there.
+        os: [ubuntu-latest, windows-latest]
+        python-version: ["3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install
+        run: python -m pip install --upgrade pip && python -m pip install -e ".[dev,mcp,agent]"
+
+      - name: Lint
+        run: python -m ruff check .
+
+      - name: Test
+        run: python -m pytest
+
+  audit:
+    # Known-vulnerable pins. Advisory until the first public release has
+    # shaken it out; then it becomes required.
+    runs-on: ubuntu-latest
+    continue-on-error: true
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      # Editable install and --skip-editable, without --strict: the package
+      # under test is not on PyPI at the version being built (or at all,
+      # before the first release), and pip-audit must not count that as a
+      # finding. Vulnerabilities in the dependencies still fail the job.
+      - run: python -m pip install --upgrade pip pip-audit && python -m pip install -e ".[mcp,agent,postgres]"
+      - run: python -m pip_audit --skip-editable

factorysemantics_mes-0.1.0/.github/workflows/dco.yml

@@ -0,0 +1,26 @@
+name: DCO
+
+on:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  signoff:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Every commit carries a Signed-off-by line
+        run: |
+          set -euo pipefail
+          missing=0
+          for sha in $(git rev-list ${{ github.event.pull_request.base.sha }}..${{ github.event.pull_request.head.sha }}); do
+            if ! git show -s --format=%B "$sha" | grep -qE '^Signed-off-by: .+ <.+@.+>$'; then
+              echo "::error::commit $sha has no Signed-off-by line (git commit -s)"
+              missing=1
+            fi
+          done
+          exit $missing

factorysemantics_mes-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,39 @@
+name: Docs
+
+on:
+  push:
+    branches: [main]
+    tags: ["v*"]
+  pull_request:
+
+permissions:
+  contents: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - name: Install
+        run: python -m pip install --upgrade pip && python -m pip install -e ".[docs,mcp]"
+      - name: Build (strict — a broken link fails)
+        run: mkdocs build --strict
+      - name: Publish dev docs
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+        run: |
+          git config user.name github-actions
+          git config user.email github-actions@github.com
+          mike deploy --push --update-aliases dev
+      - name: Publish release docs
+        if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
+        run: |
+          git config user.name github-actions
+          git config user.email github-actions@github.com
+          v="${GITHUB_REF_NAME#v}"; mm="${v%.*}"
+          mike deploy --push --update-aliases "$mm" latest
+          mike set-default --push latest

factorysemantics_mes-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,104 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    uses: ./.github/workflows/ci.yml
+
+  build:
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - run: python -m pip install --upgrade pip build
+      - run: python -m build
+      - name: The tag and the package agree
+        run: |
+          v="${GITHUB_REF_NAME#v}"
+          ls dist/ | grep -q "factorysemantics_mes-${v}-" || { echo "::error::tag $GITHUB_REF_NAME but wheel is $(ls dist/)"; exit 1; }
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  pypi:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+
+  image:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: docker/setup-qemu-action@v3
+      - uses: docker/setup-buildx-action@v3
+      - uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      - id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ghcr.io/factorysemantics/fsmes
+          tags: |
+            type=semver,pattern={{version}}
+            type=raw,value=latest
+      - uses: docker/build-push-action@v6
+        with:
+          context: .
+          file: docker/Dockerfile
+          platforms: linux/amd64,linux/arm64
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+      - uses: sigstore/cosign-installer@v3
+      - name: Sign the image (keyless)
+        run: cosign sign --yes ghcr.io/factorysemantics/fsmes:${GITHUB_REF_NAME#v}
+      - uses: anchore/sbom-action@v0
+        with:
+          image: ghcr.io/factorysemantics/fsmes:${{ github.ref_name }}
+          artifact-name: sbom.spdx.json
+
+  github-release:
+    needs: [pypi, image]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Release notes from CHANGELOG
+        run: |
+          v="${GITHUB_REF_NAME#v}"
+          awk -v v="$v" '$0 ~ "^## \\["v"\\]" {p=1; next} /^## \[/ {if(p) exit} p' CHANGELOG.md > notes.md
+          test -s notes.md || echo "See CHANGELOG.md." > notes.md
+      - uses: softprops/action-gh-release@v2
+        with:
+          body_path: notes.md
+          files: dist/*

factorysemantics_mes-0.1.0/.github/workflows/scorecard.yml

@@ -0,0 +1,28 @@
+name: Scorecard
+
+on:
+  schedule:
+    - cron: "17 4 * * 1"
+  push:
+    branches: [main]
+
+permissions: read-all
+
+jobs:
+  analysis:
+    runs-on: ubuntu-latest
+    permissions:
+      security-events: write
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+      - uses: ossf/scorecard-action@v2.4.4
+        with:
+          results_file: results.sarif
+          results_format: sarif
+          publish_results: true
+      - uses: github/codeql-action/upload-sarif@v3
+        with:
+          sarif_file: results.sarif

factorysemantics_mes-0.1.0/.github/workflows/welcome.yml

@@ -0,0 +1,23 @@
+name: Welcome
+
+on:
+  issues:
+    types: [opened]
+  pull_request_target:
+    types: [opened]
+
+permissions:
+  issues: write
+  pull-requests: write
+
+jobs:
+  first-interaction:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/first-interaction@v1
+        with:
+          repo-token: ${{ secrets.GITHUB_TOKEN }}
+          issue-message: |
+            Thanks for the first issue. The maintainer reads everything and answers within a few days. If this is about a real plant, please make sure nothing in it identifies the plant or its owner — the simulator is the place to reproduce.
+          pr-message: |
+            Thanks for the first pull request. Checks: every commit signed off (`git commit -s`), `ruff` and `pytest` green, and the house-rules checklist in the template. The maintainer reviews within a few days.

factorysemantics_mes-0.1.0/.gitignore

@@ -0,0 +1,67 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.venv/
+venv/
+
+# Tooling caches
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+
+# Claude Code worktrees
+.claude/worktrees/
+.claude/settings.local.json
+
+# ---------------------------------------------------------------------------
+# Plant data and secrets. These rules are deliberately WHOLESALE rather than an
+# enumerated list of subdirectories: an enumerated rule goes stale silently the
+# first time the code writes somewhere new. Learned on factorysemantics.com,
+# where `drops/ curated/ mlflow/` were listed and the node had since started
+# writing archive/ and audit/ that nothing covered.
+# ---------------------------------------------------------------------------
+data/
+*.db
+*.db-wal
+*.db-shm
+*.sqlite
+*.sqlite3
+*.parquet
+logs/
+*.log
+
+# Secrets. `.env*` (not just `.env`) because a plain `.env` rule does not match
+# an editor's `.env.bak` — which is a committable copy of a credentials file.
+.env
+.env.*
+!.env.example
+.secrets/
+*.token
+certs/
+*.pem
+*.key
+
+# Generated simulator output
+sim/out/
+
+# ---------------------------------------------------------------------------
+# Carried in from MES-TWIN at the merge. Same wholesale-over-enumerated rule as
+# above: labs/**/out/ rather than naming each lab, because the enumerated form
+# went stale the moment labs/multiplant/ started generating its own CSVs.
+# ---------------------------------------------------------------------------
+erp_exchange/
+labs/**/out/
+labs/**/certs/
+labs/multiplant/.data/
+labs/megafactory/.data/
+labs/cutlery/.data/
+
+# Docs site: generated reference pages and the built site
+docs/reference/
+docs/llms.txt
+site/

factorysemantics_mes-0.1.0/CHANGELOG.md

@@ -0,0 +1,53 @@
+# Changelog
+
+All notable changes to FactorySemantics MES. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versions follow
+SemVer, where `0.x` means the API may change with a note here.
+
+Sections: **Added**, **Changed**, **Fixed**, and **Honesty** — anything that
+changed what a number *means* (a KPI formula, a state mapping, a counter rule)
+goes under Honesty with a migration line, so plant people can find it.
+
+## [Unreleased]
+
+## [0.1.0] — first public release
+
+The first public version. The code was developed privately from 2026-08-28
+to 2026-09-07 in 34 pull requests; [docs/history/private-era.md](docs/history/private-era.md)
+lists them. Everything below is what a stranger gets on day one, and every
+number in it comes from a simulated plant.
+
+### Added
+- Kernel: master data, routings, work orders, dispatch, execution with lot
+  genealogy, an append-only audit trail, users and roles with capabilities.
+- OPC UA connectivity: tag maps from an engineering worksheet, `opc-browse`
+  and `opc-verify`, a replay server for simulated lines, triggers as data, a
+  write-back *recommendation* queue with three guards, and certificates of
+  analysis at the end of the line.
+- Downtime and OEE with an explicit *unknown* segment; shift calendars.
+- Quality: inspections, holds, non-conformances, SPC with capability withheld
+  when the data cannot support it, a gauge register with calibration.
+- Maintenance-lite, finite-capacity scheduling with promised dates,
+  serialisation and genealogy at ten million pieces a day (the cutlery lab).
+- ERP: a typed per-operation contract with an outbox, a REST adapter, a
+  B2MML-flavoured file adapter, and an ERPNext connector registered as a
+  module (`fsmes.modules` entry point `erpnext`).
+- The agent surface: an MCP server with 85 tools that go through the HTTP API
+  as the `AGENT` role, dry-run on every write, `on_behalf_of` and idempotency
+  keys; the floor assistant in the operator UI; recorded walkthroughs; agent
+  evals that ask whether an agent given only the tools can answer what the
+  plant knows.
+- Operations: plants from a registry (`fsmes plant`), scored runs
+  (`fsmes score`) against the simulator's scripted truth, sweeps, a Docker
+  image and Compose file, systemd units for test and promoted environments.
+- Documentation site (MkDocs), decision records, security policy, code of
+  conduct, governance.
+
+### Honesty
+- Counters book production by delta only; a counter falling toward zero is a
+  reset and books nothing. OEE reports *unknown* rather than zero when the
+  MES was not watching. Unlabelled downtime is reported as unlabelled. These
+  are the house rules and they are tested.
+
+[Unreleased]: https://github.com/factorysemantics/factorysemantics-mes/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/factorysemantics/factorysemantics-mes/releases/tag/v0.1.0

factorysemantics_mes-0.1.0/CITATION.cff

@@ -0,0 +1,12 @@
+cff-version: 1.2.0
+title: FactorySemantics MES
+message: If you use this software in research, please cite it as below.
+type: software
+authors:
+  - family-names: Kalwei
+    given-names: Scott
+repository-code: https://github.com/factorysemantics/factorysemantics-mes
+url: https://factorysemantics.com
+license: Apache-2.0
+version: 0.1.0
+abstract: An open-source, modular, agent-native Manufacturing Execution System with OPC UA connectivity, honest OEE, quality with SPC and gauges, scheduling, traceability, an ERPNext connector and an MCP agent surface.