@vention/vention-skills 0.1.0

package/skills/vention-machine-logic-hmi/examples/indexing-station-hmi/proto/app.proto

@@ -0,0 +1,192 @@
+syntax = "proto3";
+package vention.app.v1;
+
+import "google/protobuf/empty.proto";
+
+
+message StartRequest {
+  int32 recipe_id = 1;
+}
+
+message CommandResponse {
+  bool accepted = 1;
+  string message = 2;
+}
+
+message StateResponse {
+  string state = 1;
+  string last_state = 2;
+}
+
+message HistoryEntry {
+  string timestamp = 1;
+  string state = 2;
+  int32 duration_ms = 3;
+}
+
+message HistoryResponse {
+  repeated HistoryEntry history = 1;
+  int32 buffer_size = 2;
+}
+
+message TriggerResponse {
+  string result = 1;
+  string previous_state = 2;
+  string new_state = 3;
+}
+
+message CrudListRequest {
+  bool include_deleted = 1;
+  int32 limit = 2;
+  int32 offset = 3;
+  string order_by = 4;
+  bool order_desc = 5;
+}
+
+message Recipe {
+  int32 id = 1;
+  string name = 2;
+  double index_distance_mm = 3;
+  double speed_mm_s = 4;
+  int32 dwell_ms = 5;
+  int32 cycle_count = 6;
+}
+
+message RecipeListResponse {
+  repeated Recipe records = 1;
+}
+
+message FilterCondition {
+  string field = 1;
+  string operation = 2;
+  string value = 3;
+}
+
+message CrudFindRequest {
+  repeated FilterCondition filters = 1;
+  bool include_deleted = 2;
+  int32 limit = 3;
+  int32 offset = 4;
+  string order_by = 5;
+  bool order_desc = 6;
+}
+
+message CrudGetRequest {
+  int32 record_id = 1;
+  bool include_deleted = 2;
+}
+
+message RecipeGetResponse {
+  Recipe record = 1;
+}
+
+message RecipeCreateRequest {
+  Recipe record = 1;
+  string actor = 2;
+}
+
+message RecipeCreateResponse {
+  Recipe record = 1;
+}
+
+message RecipeUpdateRequest {
+  int32 record_id = 1;
+  Recipe record = 2;
+  string actor = 3;
+}
+
+message RecipeUpdateResponse {
+  Recipe record = 1;
+}
+
+message CrudDeleteRequest {
+  int32 record_id = 1;
+  string actor = 2;
+}
+
+message RecipeStatusResponse {
+  string status = 1;
+}
+
+message CrudRestoreRequest {
+  int32 record_id = 1;
+  string actor = 2;
+}
+
+message RecipeRestoreResponse {
+  Recipe record = 1;
+}
+
+message HealthResponse {
+  string status = 1;
+}
+
+message AuditQueryRequest {
+  string component = 1;
+  int32 record_id = 2;
+  string actor = 3;
+  string operation = 4;
+  string since = 5;
+  string until = 6;
+  int32 limit = 7;
+  int32 offset = 8;
+}
+
+message AuditListResponse {
+  repeated string records = 1;
+}
+
+message FileResponse {
+  string filename = 1;
+  bytes bytes = 2;
+}
+
+message DatabaseRestoreRequest {
+  bytes bytes = 1;
+  string filename = 2;
+  bool integrity_check = 3;
+  bool dry_run = 4;
+}
+
+message DatabaseRestoreResponse {
+  bool ok = 1;
+  string message = 2;
+}
+
+message StationStatus {
+  string state = 1;
+  string recipe_name = 2;
+  int32 cycle = 3;
+  int32 cycle_count = 4;
+  double last_cycle_seconds = 5;
+  string fault = 6;
+}
+
+message Event {
+  string timestamp = 1;
+  string level = 2;
+  string message = 3;
+  string detail = 4;
+}
+
+service IndexingStationService {
+  rpc Start (StartRequest) returns (CommandResponse);
+  rpc GetState (google.protobuf.Empty) returns (StateResponse);
+  rpc GetHistory (google.protobuf.Empty) returns (HistoryResponse);
+  rpc Trigger_Stop (google.protobuf.Empty) returns (TriggerResponse);
+  rpc Trigger_Reset (google.protobuf.Empty) returns (TriggerResponse);
+  rpc Recipe_ListRecords (CrudListRequest) returns (RecipeListResponse);
+  rpc Recipe_FindRecords (CrudFindRequest) returns (RecipeListResponse);
+  rpc Recipe_GetRecord (CrudGetRequest) returns (RecipeGetResponse);
+  rpc Recipe_CreateRecord (RecipeCreateRequest) returns (RecipeCreateResponse);
+  rpc Recipe_UpdateRecord (RecipeUpdateRequest) returns (RecipeUpdateResponse);
+  rpc Recipe_DeleteRecord (CrudDeleteRequest) returns (RecipeStatusResponse);
+  rpc Recipe_RestoreRecord (CrudRestoreRequest) returns (RecipeRestoreResponse);
+  rpc Database_Health (google.protobuf.Empty) returns (HealthResponse);
+  rpc Database_ReadAudit (AuditQueryRequest) returns (AuditListResponse);
+  rpc Database_ExportZip (google.protobuf.Empty) returns (FileResponse);
+  rpc Database_BackupSqlite (google.protobuf.Empty) returns (FileResponse);
+  rpc Database_RestoreSqlite (DatabaseRestoreRequest) returns (DatabaseRestoreResponse);
+  rpc Status (google.protobuf.Empty) returns (stream StationStatus);
+  rpc Events (google.protobuf.Empty) returns (stream Event);
+}

package/skills/vention-machine-logic-hmi/examples/indexing-station-hmi/requirements.txt

@@ -0,0 +1,5 @@
+machine-logic-sdk==3.1.0
+vention-communication==0.15.6
+vention-state-machine==0.15.6
+vention-storage==0.18.6
+uvicorn==0.35.0

package/skills/vention-machine-logic-hmi/examples/indexing-station-hmi/server.py

@@ -0,0 +1,242 @@
+"""Indexing station with an operator HMI: index, clamp, prove the clamp, dwell, release, per recipe cycle.
+
+Needs actuator "Conveyor", output "Clamp" and input "Clamp Closed"; customui/ calls it only through the generated client.
+"""
+
+import asyncio
+import time
+from contextlib import asynccontextmanager
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import AsyncIterator, Optional
+
+from fastapi import FastAPI
+from pydantic import BaseModel
+
+from communication.app import VentionApp
+from communication.decorators import action, stream
+from machinelogic import Machine, MotionProfile
+from state_machine.core import BaseStates, BaseTriggers, StateMachine
+from state_machine.decorators import on_enter_state, on_state_change
+from state_machine.defs import State, StateGroup, Trigger
+from state_machine.vention_communication import build_state_machine_rpc_bundle
+from storage.accessor import ModelAccessor
+from storage.bootstrap import bootstrap
+from storage.vention_communication import build_storage_rpc_bundle
+
+from models import Recipe
+
+CLAMP_SETTLE_S = 0.3
+CLAMP_PROOF_TIMEOUT_S = 2.0
+CLAMP_POLL_S = 0.05
+# The HMI treats a Status stream that stays silent for three heartbeats as dropped.
+STATUS_HEARTBEAT_S = 2.0
+ACCELERATION_MM_S2 = 400.0
+DATA_DIR = Path(__file__).parent / "data"
+
+
+class Station(StateGroup):
+    running: State = State()
+    stopping: State = State()
+
+
+class States:
+    station = Station()
+
+
+class Triggers:
+    run = Trigger("run")
+    stop = Trigger("stop")
+    finished = Trigger("finished")
+
+
+TRANSITIONS = [
+    Triggers.run.transition(BaseStates.READY.value, States.station.running),
+    Triggers.stop.transition(States.station.running, States.station.stopping),
+    Triggers.finished.transition(States.station.running, BaseStates.READY.value),
+    Triggers.finished.transition(States.station.stopping, BaseStates.READY.value),
+]
+
+
+class StationStatus(BaseModel):
+    state: str
+    recipe_name: str
+    cycle: int
+    cycle_count: int
+    last_cycle_seconds: float
+    fault: str
+
+
+class Event(BaseModel):
+    timestamp: str
+    level: str
+    message: str
+    detail: str
+
+
+class StartRequest(BaseModel):
+    recipe_id: int
+
+
+class CommandResponse(BaseModel):
+    accepted: bool
+    message: str
+
+
+class IndexingStation(StateMachine):
+    def __init__(self) -> None:
+        super().__init__(states=States, transitions=TRANSITIONS)
+        self.machine: Optional[Machine] = None
+        self.recipe: Optional[Recipe] = None
+        self.cycle = 0
+        self.last_cycle_seconds = 0.0
+        self.fault_message = ""
+        self.stop_requested = False
+
+    def snapshot(self) -> StationStatus:
+        recipe = self.recipe
+        return StationStatus(
+            state=str(self.state),
+            recipe_name=recipe.name if recipe else "",
+            cycle=self.cycle,
+            cycle_count=recipe.cycle_count if recipe else 0,
+            last_cycle_seconds=self.last_cycle_seconds,
+            fault=self.fault_message,
+        )
+
+    @on_state_change
+    def publish_state_change(self, _old_state: str, _new_state: str, _trigger: str) -> None:
+        self.spawn(publish_status())
+
+    @on_enter_state(BaseStates.READY.value)
+    def enter_ready(self, _: object) -> None:
+        self.fault_message = ""
+
+    @on_enter_state(States.station.running)
+    def enter_running(self, _: object) -> None:
+        self.stop_requested = False
+        self.spawn(self.run_cycles())
+
+    @on_enter_state(States.station.stopping)
+    def enter_stopping(self, _: object) -> None:
+        self.stop_requested = True
+
+    def connected_machine(self) -> Machine:
+        if self.machine is None:
+            raise RuntimeError("the machine is not connected")
+        return self.machine
+
+    def index_part(self, recipe: Recipe) -> None:
+        conveyor = self.connected_machine().get_actuator("Conveyor")
+        conveyor.move_relative(recipe.index_distance_mm, MotionProfile(velocity=recipe.speed_mm_s, acceleration=ACCELERATION_MM_S2))
+
+    def clamp_part(self) -> None:
+        machine = self.connected_machine()
+        clamp_closed = machine.get_input("Clamp Closed")
+        machine.get_output("Clamp").write(True)
+        time.sleep(CLAMP_SETTLE_S)
+        deadline = time.monotonic() + CLAMP_PROOF_TIMEOUT_S
+        while not clamp_closed.state.value:
+            if time.monotonic() > deadline:
+                raise RuntimeError(f"clamp never proved closed within {CLAMP_PROOF_TIMEOUT_S} s")
+            time.sleep(CLAMP_POLL_S)
+
+    def release(self) -> None:
+        if self.machine is not None:
+            self.machine.get_output("Clamp").write(False)
+
+    async def release_safely(self) -> None:
+        try:
+            await asyncio.to_thread(self.release)
+        except Exception as error:
+            await publish_event("error", "Clamp release failed", f"{error}. Check the clamp is open before the next run.")
+
+    async def run_cycles(self) -> None:
+        recipe = self.recipe
+        if recipe is None:
+            return
+        try:
+            for cycle in range(1, recipe.cycle_count + 1):
+                if self.stop_requested:
+                    break
+                started = time.monotonic()
+                self.cycle = cycle
+                await publish_status()
+                await asyncio.to_thread(self.index_part, recipe)
+                if self.stop_requested:
+                    break
+                await asyncio.to_thread(self.clamp_part)
+                if self.stop_requested:
+                    break
+                await asyncio.sleep(recipe.dwell_ms / 1000)
+                await asyncio.to_thread(self.release)
+                self.last_cycle_seconds = time.monotonic() - started
+                await publish_status()
+                await publish_event("info", f"Cycle {cycle}/{recipe.cycle_count} done", f"Took {self.last_cycle_seconds:.1f} s.")
+            await asyncio.to_thread(self.release)
+            self.trigger(Triggers.finished.name)
+        except asyncio.CancelledError:
+            await self.release_safely()
+            raise
+        except Exception as error:
+            await self.release_safely()
+            self.fault_message = f"cycle {self.cycle}: {error}"
+            await publish_event("error", f"Cycle {self.cycle} faulted", f"{error}. Clear the cause, then press Reset on the Run page.")
+            self.trigger(BaseTriggers.TO_FAULT.value)
+
+
+DATA_DIR.mkdir(exist_ok=True)
+bootstrap(database_url=f"sqlite:///{DATA_DIR / 'recipes.db'}")
+recipe_accessor = ModelAccessor(Recipe, "recipe")
+station = IndexingStation()
+
+
+async def repeat_status() -> None:
+    while True:
+        await asyncio.sleep(STATUS_HEARTBEAT_S)
+        await publish_status()
+
+
+@asynccontextmanager
+async def lifespan(_: FastAPI) -> AsyncIterator[None]:
+    try:
+        station.machine = await asyncio.to_thread(Machine)
+    except Exception as error:
+        station.fault_message = f"cannot reach the controller: {error}"
+    await publish_status()
+    heartbeat = asyncio.create_task(repeat_status())
+    yield
+    heartbeat.cancel()
+
+
+app = VentionApp(name="IndexingStation", emit_proto=True, proto_path="proto/app.proto", lifespan=lifespan)
+
+
+@stream(name="Status", payload=StationStatus, replay=True, queue_maxsize=1, policy="latest")
+async def publish_status() -> StationStatus:
+    return station.snapshot()
+
+
+@stream(name="Events", payload=Event, replay=False, queue_maxsize=100, policy="fifo")
+async def publish_event(level: str, message: str, detail: str) -> Event:
+    return Event(timestamp=datetime.now(timezone.utc).isoformat(), level=level, message=message, detail=detail)
+
+
+@action("Start")
+async def start(request: StartRequest) -> CommandResponse:
+    if station.machine is None:
+        return CommandResponse(accepted=False, message="the machine is not connected")
+    if station.state != BaseStates.READY.value:
+        return CommandResponse(accepted=False, message=f"cannot start from {station.state}")
+    recipe = recipe_accessor.get(request.recipe_id)
+    if recipe is None:
+        return CommandResponse(accepted=False, message=f"no recipe {request.recipe_id}")
+    station.recipe = recipe
+    station.cycle = 0
+    station.trigger(Triggers.run.name)
+    return CommandResponse(accepted=True, message=f"running {recipe.name}")
+
+
+app.register_rpc_plugin(build_state_machine_rpc_bundle(station, triggers=[Triggers.stop.name, BaseTriggers.RESET.value]))
+app.register_rpc_plugin(build_storage_rpc_bundle(accessors=[recipe_accessor], max_records_per_model=None))
+app.finalize()

package/skills/vention-monitoring/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: vention-monitoring
+description: Diagnose deployed Vention machines from controller state, history, health, and activity data. Use when the user reports a machine that is down, faulted, offline, slow, or underperforming, asks why a cycle time regressed, wants to interpret MachineMotion event data or drive and brake status, asks about OEE or uptime, or wants to know which machine in a fleet needs attention. Trigger on a MachineMotion serial number plus any complaint.
+license: MIT
+metadata:
+  version: "0.1.0"
+  author: Vention
+---
+
+# Troubleshooting Deployed Vention Machines
+
+Diagnose machines in the field through the Vention MCP server.
+
+## Get the serial number first
+
+Every tool here needs a MachineMotion serial number, for example `6060009`. Ask for it
+before doing anything else. Do not diagnose from a description alone and do not guess a
+serial number.
+
+## Tools
+
+| Tool | Use it for |
+| --- | --- |
+| `machine_status` | Current state — always start here, it is cheap |
+| `machine_history` | State changes, run time, cycle data, counter deltas over a window |
+| `machine_health` | CPU load and temperature, memory, disk, per-drive temperature |
+| `machine_activity_log` | Readable event feed — brake released, drive ready, state changed |
+| `machine_metric` | Raw series for one numeric metric key, including custom counters |
+| `machine_logs_request` / `machine_logs_ready` | Full log archive when the above is not enough |
+
+Time windows are 24h, 7d, 30d, 90d, or 1y, in UTC. `machine_activity_log` is the
+exception: it supports 15 minutes to 2 days only, and longer windows return nothing.
+`machine_metric` accepts numeric keys only — a state key will fail.
+
+## Read timestamps before concluding anything
+
+`machine_status` is a snapshot, not a history. **Every key carries its own timestamp;
+there is no shared "as of" moment.** A value can be hours or months old.
+
+- An old timestamp means the controller stopped reporting that key — not that the state
+  just changed.
+- If machine state is `offline`, the controller is not connected right now and every
+  other value is simply the last one it sent. Say this explicitly rather than reporting
+  stale values as current.
+
+## Triage order
+
+1. `machine_status` — is it online, are drives ready, what is the application doing?
+2. If offline → check comms route, then network and power at the site.
+3. If drives not ready → check E-stop state, then drive faults.
+4. If the application is not running → `machine_activity_log` over a short window.
+5. If it runs but underperforms → `machine_history` for cycle and run-time trends, then
+   `machine_metric` for the specific number in question.
+6. If nothing explains it → `machine_logs_request`.
+
+## Rules
+
+- Distinguish "the controller reports X" from "the cause is X". Never state a cause the
+  data does not support.
+- A snapshot cannot tell you when something changed, how often, or how the machine
+  behaved over time. Do not infer any of those from `machine_status`.
+- Report what the data shows, what it does not show, and what you would check next.
+- Known discrepancy: run-time e-stop duration and the machine-state stream do not always
+  reconcile, and either can be wrong. Treat stream-derived e-stop time as a floor, and
+  say so if it matters to the conclusion.
+
+## Safety
+
+- Never instruct anyone to bypass a safety device or clear a fault they cannot see.
+- Never suggest re-enabling or restarting a machine remotely. Someone may be inside the
+  cell. If remediation needs physical access, say that a qualified person must confirm
+  the cell is clear first.
+- When the data is ambiguous and the machine is down, escalate to Vention support rather
+  than guessing.
+
+## Common mistakes
+
+- Reading stale timestamps as current state.
+- Diagnosing an offline machine from its last-known values.
+- Confusing application state with machine state.
+- Requesting a 7-day `machine_activity_log` window and reporting "no events" when the
+  call simply exceeded the supported range.