diff --git a/advanced_cnc_copilot/FEATURE_IMPLEMENTATION_BLUEPRINT.md b/advanced_cnc_copilot/FEATURE_IMPLEMENTATION_BLUEPRINT.md new file mode 100644 index 00000000..436d1d75 --- /dev/null +++ b/advanced_cnc_copilot/FEATURE_IMPLEMENTATION_BLUEPRINT.md @@ -0,0 +1,179 @@ +# FANUC RISE Feature Implementation Blueprint + +This document turns the project roadmaps into an executable delivery plan. It is meant to be used with: +- `ROADMAP_TO_ARCHITECTURE.md` +- `IMPLEMENTATION_STRATEGY_PHASE2.md` +- `cms/theories/PROJECT_STATE_AND_ROADMAP.md` +- `NEXT_STEPS_OVERVIEW.md` + +## 0) Roadmap Source Crosswalk (MD -> Implementation) + +| Source document | What it contributes | Implemented as track | +|---|---|---| +| `ROADMAP_TO_ARCHITECTURE.md` | Macro architecture phases and target platform shape | A, B, E | +| `IMPLEMENTATION_STRATEGY_PHASE2.md` | Mid-phase delivery and integration sequencing | B, C, D | +| `cms/theories/PROJECT_STATE_AND_ROADMAP.md` | Current-state inventory + quarterly objectives | A, C, E | +| `NEXT_STEPS_OVERVIEW.md` | Tactical next actions and commercialization flow | C, D, E | + +This crosswalk exists so every roadmap statement is traceable to an engineering workstream. + +## 1) Dependency Baseline (must pass first) + +### Required runtime layers +1. **Python backend** (FastAPI + orchestration + simulator/HAL) +2. **Database** (PostgreSQL / TimescaleDB) +3. **Optional cache/bus** (Redis) +4. **Frontend clients** (React / Vue / dashboard HTML) + +### One-command bootstrap +Use: +```bash +./tools/bootstrap_and_audit.sh +``` + +The script creates `.venv`, installs Python deps, installs Node deps in all frontend workspaces, and prints npm/pip diagnostics. + +--- + +## 2) Feature Delivery Tracks (from MD roadmaps) + +## Track A — Hardware + HAL Reliability +**Goal**: production-safe telemetry and command path. + +### A1. FOCAS bridge hardening +- Implement circuit breaker retries + timeout budgets in HAL adapters. +- Add machine profile registry (`Fanuc`, `Siemens`, `Mock`) to avoid hardcoded assumptions. +- Acceptance: + - Graceful degradation to simulator when hardware unavailable. + - 0 unhandled exceptions on adapter disconnect/reconnect chaos test. + +### A2. Latency pipeline +- Move high-frequency shared state to Redis streams or Arrow IPC. +- Add p50/p95/p99 telemetry pipeline timing metrics. +- Acceptance: + - p95 ingestion-to-dashboard < 100ms in simulator load tests. + +## Track B — Shadow Council Safety Governance +**Goal**: AI suggestions never bypass deterministic guardrails. + +### B1. Auditor policy engine +- Encode hard constraints for load/vibration/thermal/curvature bounds. +- Expose policy decisions + reasoning traces over API. +- Acceptance: + - Any violating proposal is blocked with explicit reasons. + +### B2. Creator + Accountant integration +- Creator generates strategy candidates. +- Accountant scores economics/time/risk. +- Auditor performs final deterministic gate. +- Acceptance: + - Decision packet contains proposal, economics score, and pass/fail rationale. + +## Track C — Probability Canvas + Fleet UX +**Goal**: roadmap-aligned multi-machine operations. + +### C1. Fleet switching +- Keep machine-specific websocket route as primary (`/ws/telemetry/{machine_id}`) with fallback. +- Add machine selector and persisted last-machine state. +- Acceptance: + - Operator can switch among 3+ machines without page refresh. + +### C2. Fleet health overview +- Add hub-level card metrics (status, load trend, alert count) per machine. +- Acceptance: + - Hub view updates in near real-time and highlights critical nodes. + +## Track D — Simulator-to-LLM Training Loop +**Goal**: improve model quality safely offline. + +### D1. Scenario generation service +- Generate normal + fault scenarios (chatter, thermal drift, stall). +- Persist traces in consistent schema. + +### D2. Dataset builder +- Build SFT examples and pairwise preference data. +- Include auditor verdicts and economics outcomes. + +### D3. Shadow deployment gate +- Model can propose only; deterministic systems decide execution. +- Acceptance: + - Safety violation rate and rejection rate dashboards available. + +## Track E — Multi-site Cloud + ERP Integration +**Goal**: roadmap Q2/Q3 scalability. + +### E1. Fleet registry + tenancy +- Add site and machine tenancy boundaries. +- Implement RBAC scoped by site/role. + +### E2. Event-driven sync +- Broadcast relevant learnings across machines (with policy controls). +- Acceptance: + - Cross-machine strategy propagation with audit trail. + +--- + +## 3) Suggested Sprint Plan (12-week template) + +### Sprint 1-2 +- Dependency baseline, CI checks, API health hardening. +- Deliverables: repeatable local bootstrap, passing lints/checks. + +### Sprint 3-4 +- HAL resiliency + telemetry latency instrumentation. +- Deliverables: circuit breaker + latency dashboard. + +### Sprint 5-6 +- Shadow Council decision packet + deterministic policy traceability. +- Deliverables: pass/fail auditor API with reason codes. + +### Sprint 7-8 +- Fleet UX (machine selector, hub rollup metrics, alerts). +- Deliverables: live multi-node dashboard. + +### Sprint 9-10 +- Simulator scenario generation + dataset pipeline. +- Deliverables: exportable SFT/preference datasets. + +### Sprint 11-12 +- Shadow deployment and go/no-go gates for pilot. +- Deliverables: pilot checklist + rollback plan. + +--- + +## 4) Engineering Definition of Done + +A feature is done only if all conditions hold: +1. Unit/integration checks pass. +2. Feature has monitoring signals (health, latency, error rate). +3. Auditor safety constraints are applied where relevant. +4. Docs updated (README + architecture + API notes). +5. Simulator regression scenarios pass. + +--- + +## 5) Immediate next actions + +1. Run `./tools/bootstrap_and_audit.sh`. +2. Bring up backend and verify `/api/health` and websocket routes. +3. Implement Fleet selector persistence in dashboard UI. +4. Add Auditor reason-code schema and include in websocket payload. +5. Create simulator dataset export command for SFT + preference data. + + +## 6) Documentation Standards Used + +This blueprint follows documentation conventions commonly used in mature industrial software projects: +- **Traceability**: each workstream references roadmap sources. +- **Acceptance criteria**: every feature track has measurable outcomes. +- **Operational readiness**: runability and fallback behavior are first-class requirements. +- **Safety by design**: deterministic controls are explicit and mandatory. +- **Lifecycle clarity**: includes implementation sequence, DoD, and immediate actions. + +For low-level operational and contract details, see `docs/TECHNICAL_REFERENCE.md`. + +Contributor workflow docs: +- `docs/DEVELOPER_EDITING_GUIDE.md` +- `docs/METHODOLOGY_OF_ANALOGY.md` +- `docs/CODER_LEXICON.md` + diff --git a/advanced_cnc_copilot/README.md b/advanced_cnc_copilot/README.md index 011f66ba..40fd7e15 100644 --- a/advanced_cnc_copilot/README.md +++ b/advanced_cnc_copilot/README.md @@ -139,6 +139,112 @@ A three-agent system ensuring safe AI integration: - Interface topology approach for connecting disparate systems - Nightmare Training for offline learning through simulation + +## Documentation Set (Complete) + +- `README.md`: project entrypoint, setup, and quickstart. +- `SYSTEM_ARCHITECTURE.md`: architecture and data-flow map. +- `FEATURE_IMPLEMENTATION_BLUEPRINT.md`: roadmap-driven delivery blueprint. +- `docs/TECHNICAL_REFERENCE.md`: production-style technical contracts, NFRs, safety and release criteria. +- `docs/DEVELOPER_EDITING_GUIDE.md`: safe code editing workflow and PR checklist. +- `docs/METHODOLOGY_OF_ANALOGY.md`: analogy methodics and validation protocol. +- `docs/CODER_LEXICON.md`: canonical project vocabulary for consistent implementation language. +- `docs/COMPONENT_COMPLETION_REPORT.md`: evidence-based status of what is done vs in progress. +- `docs/NEXT_WEEK_DEVELOPMENT_PLAN.md`: concrete next-week implementation commitments. +- `docs/MONETIZATION_ARTICLE_PRODUCTIZED_AI_CNC.md`: monetization strategy for product tiers and outcome-based pricing. +- `docs/MONETIZATION_ARTICLE_SERVICES_AND_ECOSYSTEM.md`: services/ecosystem-led commercialization strategy. + +## Delivery Blueprint (Roadmap -> Execution) + +- **Feature execution plan**: `FEATURE_IMPLEMENTATION_BLUEPRINT.md` (maps roadmap docs into tracks, sprints, DoD, and acceptance criteria). +- **Bootstrap + dependency audit script**: `tools/bootstrap_and_audit.sh` (creates Python env, installs dependencies across workspaces, runs quick diagnostics). + +## Dependency Bootstrap & Environment Debugging + +To avoid mixed environments, use one Python environment and install frontend dependencies per app folder. + +### 1) Python backend environment +```bash +cd advanced_cnc_copilot +python -m venv .venv +source .venv/bin/activate +pip install -U pip +pip install -r flask_service/requirements.txt +``` + +If you prefer conda: +```bash +conda env create -f environment.yml +conda activate fanuc-rise +``` + +### 2) Frontend dependencies +```bash +cd advanced_cnc_copilot/frontend-react && npm install +cd ../frontend-vue && npm install +``` + +### 3) Quick dependency diagnostics +```bash +python --version +pip check +npm --version +npm ls --depth=0 +``` + +### 4) Runtime connectivity checks +```bash +# API health +curl -s http://localhost:8000/api/health + +# Dashboard websocket (machine-scoped) +# ws://localhost:8000/ws/telemetry/CNC-001 +``` + +If machine-scoped telemetry is unavailable in your current backend mode, the dashboard now falls back to the global stream endpoint (`/ws/telemetry`). + +## How to Train the LLM with the Simulator (Practical Loop) + +Use this loop to improve planning quality without risking hardware: + +1. **Generate scenario batches** + - Use simulator variants (normal, chatter, thermal drift, spindle stall) to create trajectories. + - Save each run as `{input_intent, telemetry_trace, action_trace, outcome, safety_flags}`. + +2. **Build supervised preference data** + - For each scenario, keep: + - `creator_proposal` (candidate plan) + - `auditor_verdict` (pass/fail + rule trace) + - `accountant_score` (time/cost impact) + - Convert this into preference pairs (`good_plan`, `bad_plan`) for fine-tuning or ranking. + +3. **Train in phases** + - **SFT phase**: train on accepted plans and corrective rewrites. + - **Reward/ranking phase**: train a scorer on safety + economics labels. + - **Policy improvement phase**: optimize for high reward under strict safety constraints. + +4. **Gate with deterministic safety** + - Keep Physics Auditor and hard constraints outside the model. + - Reject any proposal violating vibration/load/curvature bounds even if model confidence is high. + +5. **Deploy as shadow mode first** + - Run the model in recommendation-only mode. + - Compare proposed actions vs executed actions and measure regret/safety deltas before enabling active control. + +### Suggested training metrics +- Safety violation rate +- Auditor rejection rate +- Cycle-time improvement +- Surface finish proxy / quality score +- Recovery latency after injected fault + +## Additional Critical Recommendations + +- **Do not remove deterministic guardrails** when increasing model autonomy. +- **Version telemetry schemas** so training data stays compatible over time. +- **Record full reasoning traces** for post-incident audits. +- **Keep a simulator parity suite** that replays historical failure windows before each release. + ## Usage Examples ### Starting the Application diff --git a/advanced_cnc_copilot/SYSTEM_ARCHITECTURE.md b/advanced_cnc_copilot/SYSTEM_ARCHITECTURE.md index cb1d3335..118d60b6 100644 --- a/advanced_cnc_copilot/SYSTEM_ARCHITECTURE.md +++ b/advanced_cnc_copilot/SYSTEM_ARCHITECTURE.md @@ -93,3 +93,60 @@ graph TD * Real-time telemetry (Load/Vibration) feeds the **Dopamine Engine**. * Post-job quality (Vision) feeds the **Reinforcement Learning** model. * The system updates its "Risk Tolerance" weights for the next cycle. + +## Operational Debug Playbook (Dependencies + Runtime) + +### Dependency layers +- **Python services**: FastAPI backend, orchestration core, simulator and HAL adapters. +- **Frontend services**: dashboard clients (React/Vue/HTML) consuming REST + WebSocket. +- **Data services**: Postgres/TimescaleDB and optional Redis. + +### Minimal boot order +1. Install Python dependencies and activate environment. +2. Install frontend dependencies in each UI package. +3. Start backend API (`uvicorn backend.main:app --reload`). +4. Open dashboard and verify `/api/health` + websocket stream. + +### Failure isolation checklist +- If REST works but live widgets do not update: inspect WebSocket route mismatch first. +- If machine-specific stream fails: verify `/ws/telemetry/{machine_id}` and then fallback to `/ws/telemetry`. +- If optimization endpoints fail: validate model/agent initialization and dependency imports before checking UI. + +## LLM Training Architecture on Simulator + +```mermaid +graph LR + A[Scenario Generator\n(normal/fault/thermal/chatter)] --> B[Telemetry + Action Dataset] + B --> C[SFT Dataset Builder\n(prompt->plan)] + B --> D[Preference Dataset Builder\n(good vs bad plan)] + C --> E[Policy Model (Creator)] + D --> F[Reward/Rank Model] + E --> G[Shadow Deployment] + F --> G + G --> H[Auditor + Physics Constraints] + H --> I[Accepted Actions + Outcomes] + I --> B +``` + +### Safety-first training contract +- Creator model can **propose**, never unilaterally execute. +- Auditor/physics layer remains deterministic and blocks out-of-bounds actions. +- Training data must include both successful and failed episodes to avoid optimism bias. + +### Recommended dataset schema +- `intent_text` +- `machine_context` (tool, material, wear state) +- `telemetry_window` (time-series) +- `proposed_action` +- `auditor_result` + `reasoning_trace` +- `execution_outcome` (cycle time, quality, fault/no-fault) +- `economic_score` + +### Deployment maturity gates +1. Offline simulator benchmark pass. +2. Shadow mode acceptance thresholds met. +3. Controlled pilot on non-critical operations. +4. Progressive rollout with rollback triggers. + +## Further Reading +- Operational and contract details: `docs/TECHNICAL_REFERENCE.md`. diff --git a/advanced_cnc_copilot/cms/dashboard/app.js b/advanced_cnc_copilot/cms/dashboard/app.js index c1965c47..e305c0be 100644 --- a/advanced_cnc_copilot/cms/dashboard/app.js +++ b/advanced_cnc_copilot/cms/dashboard/app.js @@ -3,10 +3,19 @@ * Connects to Python Backend via REST API. */ -const API_URL = "http://localhost:8000"; +const DEFAULT_API_URL = "http://localhost:8000"; class DashboardApp { constructor() { + this.machineId = this.getMachineIdFromQuery(); + this.apiUrl = this.getApiUrl(); + this.wsBaseUrl = this.apiUrl.replace(/^http/i, "ws"); + this.wsRetryDelayMs = 5000; + this.wsAttemptOrder = [ + `/ws/telemetry/${encodeURIComponent(this.machineId)}`, + "/ws/telemetry" + ]; + this.statusEl = document.getElementById("system-status"); this.consoleEl = document.getElementById("console-output"); this.pollingInterval = null; @@ -15,9 +24,41 @@ class DashboardApp { this.init(); } + getMachineIdFromQuery() { + const params = new URLSearchParams(window.location.search); + const rawMachineId = (params.get("machine_id") || "CNC-001").trim(); + return this.sanitizeMachineId(rawMachineId); + } + + sanitizeMachineId(machineId) { + const safeMachineId = machineId.replace(/[^a-zA-Z0-9_-]/g, ""); + return safeMachineId || "CNC-001"; + } + + getApiUrl() { + const params = new URLSearchParams(window.location.search); + const apiBase = params.get("api_base"); + + if (apiBase) { + try { + return new URL(apiBase, window.location.origin).origin; + } catch (err) { + console.warn("Invalid api_base query parameter, falling back to origin/default.", err); + } + } + + if (window.location.protocol.startsWith("http")) { + return window.location.origin; + } + + return DEFAULT_API_URL; + } + init() { - this.log("Initializing Dashboard..."); - this.connectWebSocket(); + this.log(`Initializing Dashboard for ${this.machineId}...`); + this.log(`API Base: ${this.apiUrl}`); + this.statusEl.innerText = `CONNECTING ${this.machineId}`; + this.connectWebSocket(0); } log(msg) { @@ -28,15 +69,22 @@ class DashboardApp { this.consoleEl.scrollTop = this.consoleEl.scrollHeight; } - connectWebSocket() { - const wsUrl = API_URL.replace("http", "ws") + "/ws/telemetry"; + connectWebSocket(attemptIndex = 0) { + const wsPath = this.wsAttemptOrder[Math.min(attemptIndex, this.wsAttemptOrder.length - 1)]; + const wsUrl = `${this.wsBaseUrl}${wsPath}`; + const usingFallback = wsPath === "/ws/telemetry"; + let opened = false; + this.log(`Connecting to WebSocket: ${wsUrl}`); this.socket = new WebSocket(wsUrl); this.socket.onopen = () => { - this.log("Connected to Real-time Stream"); - this.statusEl.innerText = "SYSTEM ONLINE (LIVE)"; + opened = true; + this.log(usingFallback + ? "Connected to fallback real-time stream" + : "Connected to machine-scoped real-time stream"); + this.statusEl.innerText = `SYSTEM ONLINE (LIVE) • ${this.machineId}`; this.statusEl.style.borderColor = "var(--neon-green)"; }; @@ -46,10 +94,16 @@ class DashboardApp { }; this.socket.onclose = () => { - this.log("WebSocket Disconnected. Retrying in 5s..."); - this.statusEl.innerText = "RECONNECTING..."; + if (!opened && attemptIndex < this.wsAttemptOrder.length - 1) { + this.log("Machine stream unavailable. Switching to fallback websocket endpoint..."); + this.connectWebSocket(attemptIndex + 1); + return; + } + + this.log("WebSocket disconnected. Retrying in 5s..."); + this.statusEl.innerText = `RECONNECTING ${this.machineId}...`; this.statusEl.style.borderColor = "var(--neon-red)"; - setTimeout(() => this.connectWebSocket(), 5000); + setTimeout(() => this.connectWebSocket(0), this.wsRetryDelayMs); }; this.socket.onerror = (err) => { @@ -59,13 +113,9 @@ class DashboardApp { } updateUIFromSocket(data) { - // Map backend WebSocket data to existing UI update logic - // We simulate the neuro_state and action if not present in socket yet - // In the next step we will update the backend to send these - const neuro_state = data.neuro_state || { dopamine: 50, cortisol: 10, serotonin: 70 }; + const neuroState = data.neuro_state || { dopamine: 50, cortisol: 10, serotonin: 70 }; const action = data.action || "MONITORING_LIVE"; - // 1. Update HAL Panel if (data.spindle_rpm || data.rpm) { const rpm = data.spindle_rpm || data.rpm; this.setBar("bar-rpm", "val-rpm", rpm.toFixed(0), rpm / 20000 * 100); @@ -78,26 +128,23 @@ class DashboardApp { this.setBar("bar-vib", "val-vib", data.vibration.toFixed(2) + "g", data.vibration * 100); } - // 2. Update Neuro Panel - this.setBar("neuro-dopamine", null, null, neuro_state.dopamine); - this.setBar("neuro-cortisol", null, null, neuro_state.cortisol); - this.setBar("neuro-serotonin", null, null, neuro_state.serotonin); + this.setBar("neuro-dopamine", null, null, neuroState.dopamine); + this.setBar("neuro-cortisol", null, null, neuroState.cortisol); + this.setBar("neuro-serotonin", null, null, neuroState.serotonin); document.getElementById("ai-action").innerText = action; - // 3. Logic Node Updates const nodeSensory = document.getElementById("node-sensory"); if (nodeSensory) nodeSensory.querySelector(".node-val").innerText = "LIVE"; const nodeDopamine = document.getElementById("node-dopamine"); - if (nodeDopamine) nodeDopamine.querySelector(".node-val").innerText = neuro_state.dopamine.toFixed(0); + if (nodeDopamine) nodeDopamine.querySelector(".node-val").innerText = neuroState.dopamine.toFixed(0); } generateMockTelemetry() { - // Simulate a running machine for the visualizer return { fanuc_data: { - load: Math.random() * 80, // 0-80% + load: Math.random() * 80, rpm: 5000 + Math.random() * 2000, vibration: Math.random() * 0.3 }, @@ -112,17 +159,14 @@ class DashboardApp { const brain = apiResponse.neuro_state; const action = apiResponse.recommended_action; - // 1. Update HAL Panel this.setBar("bar-rpm", "val-rpm", telemetry.rpm.toFixed(0), telemetry.rpm / 20000 * 100); this.setBar("bar-load", "val-load", telemetry.load.toFixed(1) + "%", telemetry.load); this.setBar("bar-vib", "val-vib", telemetry.vibration.toFixed(2) + "g", telemetry.vibration * 100); - // 2. Update Neuro Panel this.setBar("neuro-dopamine", null, null, brain.dopamine); this.setBar("neuro-cortisol", null, null, brain.cortisol); this.setBar("neuro-serotonin", null, null, brain.serotonin); - // 3. Update Digital Twin (Creative Canvas) const curve = inputs.sw_data.curvature; const curveEl = document.getElementById("val-curve"); if (curveEl) curveEl.innerText = curve.toFixed(3); @@ -140,7 +184,6 @@ class DashboardApp { document.getElementById("ai-action").innerText = action; - // Log critical events if (brain.cortisol > 50) this.log("WARNING: High Cortisol!"); } @@ -164,7 +207,7 @@ class DashboardApp { resultEl.innerText = "Analyzing Topology & Intent..."; try { - const response = await fetch(`${API_URL}/conduct`, { + const response = await fetch(`${this.apiUrl}/conduct`, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ name: "User_Intent", prompt: prompt }) @@ -184,11 +227,10 @@ class DashboardApp { this.log(`OPTIMIZING FOR: ${mat} [${mode}]`); - // Mock GCode from UI const gcode = ["G01 X100 F1000", "G01 X200 F2000"]; try { - const response = await fetch(`${API_URL}/optimize?material=${mat}`, { + const response = await fetch(`${this.apiUrl}/optimize?material=${mat}`, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(gcode) @@ -202,5 +244,4 @@ class DashboardApp { } } -// Start window.app = new DashboardApp(); diff --git a/advanced_cnc_copilot/cms/dashboard/hub.html b/advanced_cnc_copilot/cms/dashboard/hub.html index 5966b4c9..2a25716b 100644 --- a/advanced_cnc_copilot/cms/dashboard/hub.html +++ b/advanced_cnc_copilot/cms/dashboard/hub.html @@ -32,7 +32,7 @@ .hub-grid { display: grid; - grid-template-columns: 1fr 1fr 1fr; + grid-template-columns: repeat(auto-fit, minmax(240px, 1fr)); gap: 40px; z-index: 2; text-align: center; @@ -123,7 +123,7 @@
- + 🧠 OPERATIONAL CORTEX

@@ -157,6 +157,29 @@ "Understand the Why behind the How."

+ + + + 🛰️ + FLEET VIEW: CNC-002 +

+ Open the Operational Cortex for a second machine node. + Validate multi-machine telemetry switching directly from the hub. +

+ "One portal, many machine minds." +

+ + + + 🌐 + FLEET VIEW: CNC-003 +

+ Spin up another live node to compare stress, reward, and action streams + across the fleet during synchronized operations. +

+ "Watch the swarm think in parallel." +

+
diff --git a/advanced_cnc_copilot/docs/CODER_LEXICON.md b/advanced_cnc_copilot/docs/CODER_LEXICON.md new file mode 100644 index 00000000..a763c4f1 --- /dev/null +++ b/advanced_cnc_copilot/docs/CODER_LEXICON.md @@ -0,0 +1,89 @@ +# Coder Lexicon + +A shared vocabulary for contributors. Use these terms consistently in code, docs, and PRs. + +## A + +- **Action Trace**: Ordered list of actions proposed/applied during a scenario. +- **Auditor Verdict**: Deterministic pass/fail decision on a proposed action set. + +## B + +- **Blueprint Track**: A feature workstream in `FEATURE_IMPLEMENTATION_BLUEPRINT.md`. +- **Boundary Validation**: Input normalization and schema checks at API/WS edges. + +## C + +- **Creator**: Agent that proposes strategies or mutations. +- **Contract Field**: A payload field with defined semantics and compatibility expectations. + +## D + +- **Decision Packet**: Structured unit containing proposal, scores, and reasoned decision. +- **Deterministic Safety Gate**: Hard constraint layer that blocks unsafe actions. + +## E + +- **Execution Plane**: HAL/hardware/simulator domain where commands become physical effects. + +## F + +- **Fallback Stream**: Global websocket stream (`/ws/telemetry`) used if machine-scoped stream is unavailable. + +## H + +- **HAL**: Hardware Abstraction Layer connecting software to CNC hardware/simulator. +- **Hub**: Dashboard entry view linking operational and fleet pages. + +## I + +- **Interface Layer**: HTTP/WebSocket layer; translation only, minimal logic. + +## L + +- **Lexicon Term**: Canonical project term expected to remain stable across docs. + +## M + +- **Machine-Scoped Stream**: WebSocket endpoint `/ws/telemetry/{machine_id}`. +- **Methodics**: Repeatable procedural method for implementing or validating a concept. + +## N + +- **NFR**: Non-Functional Requirement (reliability, performance, security, observability). + +## O + +- **Operational Readiness**: State where monitoring, safety, and runbook criteria are met. + +## P + +- **Preference Pair**: LLM training sample comparing good vs bad plan. +- **Primary Path**: Preferred runtime path before fallback logic. + +## R + +- **Reason Code**: Machine-readable explanation for pass/fail/block decisions. +- **Rollback Trigger**: Condition requiring reversion to safer prior behavior. + +## S + +- **Shadow Mode**: Recommendation-only deployment with no autonomous execution. +- **Shadow Council**: Creator + Auditor + Accountant decision framework. + +## T + +- **Telemetry Window**: Time-series slice used for decision and training. +- **Traceability Crosswalk**: Mapping from roadmap source docs to implementation tracks. + +## U + +- **Upgrade Safety**: Principle of additive/compatible changes in contracts. + +## V + +- **Validation Gate**: Any explicit checkpoint that must pass before progression. + +## W + +- **Workstream**: Cohesive implementation track with acceptance criteria. diff --git a/advanced_cnc_copilot/docs/COMPONENT_COMPLETION_REPORT.md b/advanced_cnc_copilot/docs/COMPONENT_COMPLETION_REPORT.md new file mode 100644 index 00000000..1a322b7a --- /dev/null +++ b/advanced_cnc_copilot/docs/COMPONENT_COMPLETION_REPORT.md @@ -0,0 +1,45 @@ +# Component Completion Report + +This report documents what is already implemented in-repo and what remains. "Done" indicates available implementation artifacts and/or integrated docs in the repository. + +## Legend +- ✅ Done (artifact exists and is documented) +- 🟨 In Progress (partial implementation or prototype-level integration) +- ⏭ Next (planned, not yet implemented end-to-end) + +## 1) Completion Matrix + +| Component | Status | Evidence in repo | Notes | +|---|---|---|---| +| Dashboard runtime + telemetry UI | ✅ | `cms/dashboard/index.html`, `cms/dashboard/app.js` | Includes machine-scoped + fallback websocket behavior in current frontend client. | +| Hub fleet navigation | ✅ | `cms/dashboard/hub.html` | Fleet links and responsive grid entries exist. | +| FastAPI backend entrypoint | ✅ | `backend/main.py` | Includes API routes and telemetry websocket endpoints. | +| Core API prototype | ✅ | `cms/fanuc_api.py` | Includes health/perceive/optimize/conduct flow endpoints. | +| Shadow Council conceptual architecture | ✅ | `SYSTEM_ARCHITECTURE.md`, `docs/TECHNICAL_REFERENCE.md` | Defined across architecture and technical contracts docs. | +| Bootstrap/audit setup flow | ✅ | `tools/bootstrap_and_audit.sh` | Repeatable local env setup and dependency diagnostics. | +| Technical standards documentation | ✅ | `docs/TECHNICAL_REFERENCE.md`, `docs/DEVELOPER_EDITING_GUIDE.md`, `docs/CODER_LEXICON.md` | Contributor and operational guidance now present. | +| HAL resiliency hardening (prod-grade) | 🟨 | `cms/hal*`, architecture docs | Circuit breaker pattern documented; production hardening still ongoing. | +| Multi-site tenancy/RBAC refinement | 🟨 | `backend/core/security*`, roadmap docs | Baseline role model exists; full multi-site governance remains. | +| Simulator-to-LLM dataset pipeline automation | 🟨 | training methodology docs | Method documented; export/automation pipeline still to be built fully. | +| Marketplace/policy-pack monetization tooling | ⏭ | monetization docs | Commercial blueprint defined; product modules pending implementation. | + +## 2) Proven "Done" Scope + +The following are demonstrably present and can be referenced immediately by developers: +1. Frontend operational dashboards and hub navigation. +2. Backend API + websocket surfaces. +3. Dependency bootstrap and diagnostics script. +4. Documentation stack for architecture, technical contracts, contributor methodics, and lexicon. + +## 3) Risks in Current State + +- Prototype and production concerns are still mixed in places. +- End-to-end measurable acceptance tests are not yet standardized for every track. +- Some roadmap items are documented but not yet fully encoded as deployable services. + +## 4) Immediate Engineering Recommendation + +Adopt this rule for planning boards: every roadmap line item must map to +- a code artifact, +- a measurable acceptance criterion, +- and an operational owner. diff --git a/advanced_cnc_copilot/docs/DEVELOPER_EDITING_GUIDE.md b/advanced_cnc_copilot/docs/DEVELOPER_EDITING_GUIDE.md new file mode 100644 index 00000000..ad1adc37 --- /dev/null +++ b/advanced_cnc_copilot/docs/DEVELOPER_EDITING_GUIDE.md @@ -0,0 +1,76 @@ +# Developer Editing Guide + +This guide explains **how to safely edit code in FANUC RISE** while preserving architecture, safety, and documentation standards. + +## 1) Working Agreement (before editing) + +1. Identify the layer you are touching: + - **Repository/Data layer**: storage access only. + - **Service layer**: business logic and domain rules. + - **Interface layer**: HTTP/WebSocket translation only. + - **HAL layer**: hardware/simulator interaction. +2. Keep changes scoped to one concern per commit. +3. If behavior changes, update documentation in the same PR. +4. Safety logic must remain deterministic and explicit. + +## 2) Standard Edit Workflow + +### Step 1 — Locate ownership +- Confirm which module owns behavior before changing anything. +- Avoid adding logic to transport/controller files when it belongs in services. + +### Step 2 — Make minimal delta +- Prefer focused edits over broad refactors. +- Preserve public contracts unless explicitly versioning them. + +### Step 3 — Validate locally +- Syntax check changed language files. +- Run basic smoke checks for impacted entrypoints. +- Verify machine-scoped and fallback telemetry paths if touching dashboard/ws code. + +### Step 4 — Document and annotate +- Update one of: + - `README.md` (entry-level impact) + - `SYSTEM_ARCHITECTURE.md` (flow/architecture impact) + - `docs/TECHNICAL_REFERENCE.md` (contract/NFR impact) + +## 3) Editing Rules by Layer + +### Interface Layer (FastAPI/WS/UI) +- Keep handlers thin; no hidden business rules. +- Validate and normalize inputs at boundaries. +- Include reason codes for safety-relevant outcomes. + +### Service Layer +- Keep deterministic policy checks explicit and testable. +- Separate AI proposal generation from safety decision logic. + +### HAL Layer +- Use circuit breakers and bounded retries. +- Always provide simulator fallback path for non-hardware environments. + +### Data Layer +- Keep schema evolution backward-compatible where possible. +- Prefer additive migration strategy for minor versions. + +## 4) Pull Request Checklist for Editors + +- [ ] Change is scoped and explained. +- [ ] Contracts impacted are documented. +- [ ] Safety model unchanged or explicitly strengthened. +- [ ] Bootstrap/runbook instructions still valid. +- [ ] Feature blueprint or roadmap mapping updated (if relevant). + +## 5) Anti-Patterns to Avoid + +- Embedding domain logic in route/controller files. +- Treating LLM confidence as a safety gate. +- Adding hardcoded hostnames/ports where runtime-derived config is needed. +- Changing websocket payload shape without documenting compatibility implications. + +## 6) Recommended Commit Style + +Use intent-first commit messages: +- `harden ws fallback for machine-scoped telemetry` +- `document api reason_code contract for auditor decisions` +- `refactor service-layer policy checks into deterministic validator` diff --git a/advanced_cnc_copilot/docs/METHODOLOGY_OF_ANALOGY.md b/advanced_cnc_copilot/docs/METHODOLOGY_OF_ANALOGY.md new file mode 100644 index 00000000..66b1af1e --- /dev/null +++ b/advanced_cnc_copilot/docs/METHODOLOGY_OF_ANALOGY.md @@ -0,0 +1,66 @@ +# Methodology of Analogy + +This project uses analogy as a **design reasoning method** (not as proof). The goal is to convert complex systems into understandable engineering decisions while keeping validation deterministic. + +## 1) Why analogy is used + +Manufacturing intelligence spans hardware, data systems, and decision engines. Analogy helps teams: +- communicate intent across disciplines, +- reason about architecture boundaries, +- teach concepts quickly, +- preserve a shared mental model. + +## 2) Core rule: Analogy guides design, metrics validate design + +- Analogy can propose a model. +- Tests, telemetry, and safety constraints accept or reject the model. + +## 3) Reusable analogy patterns in this repo + +### A) Nervous System Analogy +- Interface layer = sensory nerves. +- Service layer = brain processing. +- HAL = motor/physical actuation. +- Use when deciding where logic belongs. + +### B) Shadow Council Analogy +- Creator = proposal engine. +- Auditor = deterministic law. +- Accountant = trade-off scorer. +- Use when implementing safe AI workflow. + +### C) Economic Translation Analogy +- SaaS metrics (churn/CAC) mapped to manufacturing costs/risks. +- Use for optimization and reporting semantics. + +## 4) Analogy-to-Implementation Protocol + +1. **Name the analogy** (e.g., "nervous system"). +2. **Map entities to concrete modules**. +3. **Define constraints that cannot be violated**. +4. **Define measurable outcomes**. +5. **Run simulation or controlled validation**. +6. **Accept/reject based on evidence**. + +## 5) Failure modes and mitigations + +- **Failure mode**: treating metaphor as implementation detail. + - **Mitigation**: maintain explicit contracts and tests. +- **Failure mode**: analogy drift across teams. + - **Mitigation**: use shared lexicon and architecture docs. +- **Failure mode**: narrative over safety. + - **Mitigation**: deterministic policy layer always precedes execution. + +## 6) Example conversion template + +Use this template when introducing a new analogy: + +- Analogy name: +- Problem it clarifies: +- Module mapping: +- Hard constraints: +- Success metrics: +- Validation plan: +- Rollback criteria: + +This keeps analogy usage operational, measurable, and safe. diff --git a/advanced_cnc_copilot/docs/MONETIZATION_ARTICLE_PRODUCTIZED_AI_CNC.md b/advanced_cnc_copilot/docs/MONETIZATION_ARTICLE_PRODUCTIZED_AI_CNC.md new file mode 100644 index 00000000..db7b2961 --- /dev/null +++ b/advanced_cnc_copilot/docs/MONETIZATION_ARTICLE_PRODUCTIZED_AI_CNC.md @@ -0,0 +1,75 @@ +# Monetization Article: Productizing Cognitive CNC Intelligence + +## Executive Thesis + +FANUC RISE can be monetized as a layered product where deterministic safety and measurable manufacturing outcomes are the core value drivers. The commercial strategy should package value by **risk reduction**, **throughput improvement**, and **fleet learning effects**. + +## 1) Monetizable Value Units + +### A. Safety Assurance Unit +- Includes deterministic auditor policy packs, reason-code traceability, and safety regression suites. +- Buyer value: reduced incident risk and better auditability. + +### B. Productivity Unit +- Includes optimization proposals, adaptive strategy ranking, and cycle-time analytics. +- Buyer value: improved throughput and lower setup waste. + +### C. Fleet Intelligence Unit +- Includes multi-machine telemetry orchestration, cross-site learning propagation, and fleet dashboards. +- Buyer value: standardized best practices and lower variance across plants. + +## 2) Packaging Model + +### Community (Entry) +- Core dashboard and simulation workflows. +- Basic safety policies. +- Single-site mode. + +### Professional (Growth) +- Advanced auditor policy bundles. +- Fleet-wide dashboards and machine-scoped telemetry controls. +- Dataset export for simulator-based training. + +### Enterprise (Scale) +- Multi-site tenancy + RBAC. +- SLA-backed integrations and compliance reporting. +- Decision trace archival and release-readiness policy gates. + +## 3) Revenue Architecture + +- **Subscription**: per site, per machine, or hybrid. +- **Usage add-on**: premium analytics compute and long-term trace retention. +- **Services**: rollout, policy tuning, simulator calibration. +- **Partner channel**: OEM/system integrator deployment bundles. + +## 4) Pricing Anchors (Outcome-Based) + +Use outcome anchors instead of feature-only pricing: +- Downtime prevented per month. +- Scrap/rework reduction. +- Cycle-time savings per part family. +- Operator ramp-up time reduction. + +## 5) Go-to-Market Sequencing + +1. Start with simulation-first pilot (low-risk proof). +2. Transition to shadow mode in live plants. +3. Expand to deterministic guarded execution in constrained operations. +4. Scale to multi-site with policy standardization and ROI dashboarding. + +## 6) Commercial Risks and Controls + +- **Risk**: overpromising AI autonomy. + - **Control**: enforce deterministic safety-first positioning. +- **Risk**: long enterprise sales cycles. + - **Control**: pilot templates with measurable 6–12 week KPIs. +- **Risk**: integration friction. + - **Control**: bootstrap + architecture docs + reference runbooks. + +## 7) KPI Set for Monetization Health + +- Pilot conversion rate. +- Net revenue retention (NRR). +- Payback period by plant. +- Gross margin by deployment tier. +- Support ticket rate per deployed machine. diff --git a/advanced_cnc_copilot/docs/MONETIZATION_ARTICLE_SERVICES_AND_ECOSYSTEM.md b/advanced_cnc_copilot/docs/MONETIZATION_ARTICLE_SERVICES_AND_ECOSYSTEM.md new file mode 100644 index 00000000..48a6f7fd --- /dev/null +++ b/advanced_cnc_copilot/docs/MONETIZATION_ARTICLE_SERVICES_AND_ECOSYSTEM.md @@ -0,0 +1,58 @@ +# Monetization Article: Services, Ecosystem, and Expansion Strategy + +## Positioning + +Beyond software licensing, FANUC RISE can create durable revenue through service-led onboarding, domain policy content, and partner distribution. + +## 1) Service Lines + +### A. Launch Services +- Dependency/bootstrap setup. +- Production architecture review. +- Safety policy baseline definition. + +### B. Optimization Services +- Material/process-specific policy tuning. +- Shadow Council scoring calibration. +- Telemetry quality and sensor confidence audits. + +### C. Training Services +- Operator enablement for dashboard + prompt workflows. +- Engineering training for contributor methodics and deterministic safety patterns. + +## 2) Content-as-a-Product + +Create paid policy/content modules: +- Material-specific auditor packs. +- Industry templates (aerospace, medical, automotive). +- Failure scenario simulation packs for model training. + +## 3) Partner Ecosystem + +### OEM + SI Partnerships +- Certified deployment bundles with CNC OEMs and integrators. +- Revenue share for deployment and maintenance contracts. + +### Data and Tooling Partners +- Time-series storage optimization bundles. +- CAD/CAM integration templates and premium connectors. + +## 4) Expansion Playbook + +1. **Land** with pilot + services package. +2. **Adopt** with dashboard and safety workflow standardization. +3. **Expand** to fleet and multi-site policy governance. +4. **Scale** via ecosystem integrations and specialized packs. + +## 5) Commercial Governance + +- Define clear support SLAs by tier. +- Maintain contract-level definitions for deterministic safety boundaries. +- Tie renewal discussions to measured operational gains and incident reduction. + +## 6) What to Build Next for Revenue Enablement + +- ROI calculator embedded in dashboards. +- Usage + policy compliance reporting exports. +- Packaged onboarding runbooks and certification curriculum. +- Marketplace-style catalog of policy packs and simulation scenarios. diff --git a/advanced_cnc_copilot/docs/NEXT_WEEK_DEVELOPMENT_PLAN.md b/advanced_cnc_copilot/docs/NEXT_WEEK_DEVELOPMENT_PLAN.md new file mode 100644 index 00000000..cd701018 --- /dev/null +++ b/advanced_cnc_copilot/docs/NEXT_WEEK_DEVELOPMENT_PLAN.md @@ -0,0 +1,67 @@ +# Next Week Development Plan (Execution Focus) + +## Goal for the week +Ship one full vertical slice that improves real execution confidence: **auditor reason-code contract + fleet selector persistence + simulator dataset export command**. + +## Scope (Week Window) + +### 1) Auditor reason-code contract (Backend + Docs) +- Add standardized reason-code enum for policy decisions. +- Return reason codes in relevant API and websocket payloads. +- Update technical reference with schema examples. + +**Definition of done** +- Reason codes appear in both REST decision responses and live telemetry/decision stream where applicable. +- Backward-compatible payload extension. + +### 2) Fleet selector persistence (Frontend) +- Add explicit machine selector in dashboard UI. +- Persist selected machine in URL + local storage. +- Keep machine-scoped websocket as primary with fallback behavior. + +**Definition of done** +- User can switch between 3 machines without full app restart. +- Reopening page restores previous machine selection. + +### 3) Simulator dataset export command (Training Enabler) +- Add CLI/script to export scenario traces into training-ready schema. +- Include intent, telemetry window, proposal, auditor verdict, reason codes, and outcomes. + +**Definition of done** +- Produces deterministic JSONL output with documented schema. +- At least one sample dataset generated via simulator mode. + +## Day-by-Day Plan + +### Day 1 +- Finalize reason-code schema and update docs contract section. +- Add backend model fields and serialization paths. + +### Day 2 +- Wire reason codes into websocket/decision payload streams. +- Add compatibility guard for clients that ignore new fields. + +### Day 3 +- Implement fleet selector UI + persistence behavior. +- Validate switching and reconnect behavior. + +### Day 4 +- Build simulator dataset export command. +- Generate sample JSONL and verify schema. + +### Day 5 +- Integration smoke checks. +- Documentation update and release notes. +- Prepare demo script for stakeholder review. + +## Weekly Risks + +- API payload drift across backend/frontend versions. +- Dataset schema ambiguity if simulator traces vary by mode. +- Scope creep into full policy engine refactor. + +## Risk Controls + +- Keep payload changes additive. +- Freeze schema by mid-week and publish examples. +- Timebox changes to defined vertical slice only. diff --git a/advanced_cnc_copilot/docs/TECHNICAL_REFERENCE.md b/advanced_cnc_copilot/docs/TECHNICAL_REFERENCE.md new file mode 100644 index 00000000..e66bafe9 --- /dev/null +++ b/advanced_cnc_copilot/docs/TECHNICAL_REFERENCE.md @@ -0,0 +1,95 @@ +# Technical Reference (Production-Style Documentation) + +> This document follows common standards used in industrial software projects: system context, component contracts, operational runbook, non-functional requirements, and release gates. + +## 1. System Context + +FANUC RISE consists of five technical planes: +1. **Control plane**: APIs, auth, orchestration, RBAC. +2. **Data plane**: telemetry ingestion, storage, query and aggregation. +3. **Decision plane**: Shadow Council agents (Creator, Auditor, Accountant). +4. **Execution plane**: HAL/FOCAS bridge, simulator fallback. +5. **Experience plane**: dashboard/hub/fleet UX. + +## 2. Core Interfaces (contracts) + +### REST interfaces +- `GET /api/health`: liveness/readiness summary. +- `POST /api/manufacturing/request`: unified orchestration entrypoint. +- `POST /conduct`: creative scenario endpoint. +- `POST /optimize`: optimization endpoint with material context. + +### WebSocket interfaces +- Primary machine-scoped stream: `/ws/telemetry/{machine_id}`. +- Global fallback stream: `/ws/telemetry`. + +### Contract requirements +- Payloads must include `timestamp`, machine identity, and typed telemetry fields. +- Safety-related actions must include a machine-readable `reason_code`. +- Backward compatibility policy: additive changes only for minor versions. + +## 3. Non-Functional Requirements (NFR) + +### Reliability +- Circuit breaker in HAL path. +- Simulator fallback when hardware path is degraded. +- Explicit retry strategy for websocket reconnection. + +### Performance +- Telemetry pipeline objective: p95 ingest->UI under 100ms in simulation. +- API p95 latency budget defined per endpoint class (read/write/control). + +### Security +- RBAC-scoped access for operator/engineer/admin roles. +- Token-based authentication for control endpoints. +- Audit logs for all policy-overridden or blocked actions. + +### Observability +- Health, error rate, and throughput per subsystem. +- Decision traces for AI + deterministic auditor outcomes. +- Alerting for telemetry stalls and repeated fallback events. + +## 4. Safety Model (critical technical details) + +Safety is deterministic-first: +1. Creator can propose only. +2. Auditor validates against hard physics/policy limits. +3. Accountant score is advisory and never bypasses constraints. +4. Execution only after deterministic pass. + +**Important:** model confidence is not considered a safety signal; only policy conformance and measured machine state are valid safety gates. + +## 5. Data and Training Pipeline + +### Dataset minimum schema +- `intent_text` +- `machine_id` +- `telemetry_window` +- `candidate_actions` +- `auditor_verdict` +- `reason_codes` +- `execution_outcome` +- `economic_score` + +### Training pipeline stages +1. Scenario generation (normal/fault/adversarial). +2. Supervised fine-tuning dataset assembly. +3. Preference/ranking dataset assembly. +4. Offline benchmark and safety scoring. +5. Shadow deployment with rejection telemetry. + +## 6. Release Readiness Checklist + +A release candidate is acceptable only if: +- Dependency bootstrap script passes in clean environment. +- API health/readiness checks pass. +- Websocket primary/fallback behavior is validated. +- Safety policy regression suite passes. +- Documentation updates are complete and versioned. + +## 7. Recommended Documentation Set (for this repo) + +- `README.md`: entry-level setup and links. +- `SYSTEM_ARCHITECTURE.md`: conceptual and flow architecture. +- `FEATURE_IMPLEMENTATION_BLUEPRINT.md`: delivery execution plan. +- `docs/TECHNICAL_REFERENCE.md` (this file): contracts, NFRs, runbook-grade guidance. diff --git a/advanced_cnc_copilot/tools/bootstrap_and_audit.sh b/advanced_cnc_copilot/tools/bootstrap_and_audit.sh new file mode 100755 index 00000000..266c219c --- /dev/null +++ b/advanced_cnc_copilot/tools/bootstrap_and_audit.sh @@ -0,0 +1,72 @@ +#!/usr/bin/env bash +set -euo pipefail + +ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" +PY_ENV_DIR="${ROOT_DIR}/.venv" + +log() { + echo "[bootstrap] $*" +} + +require_cmd() { + if ! command -v "$1" >/dev/null 2>&1; then + echo "[bootstrap][error] required command not found: $1" >&2 + exit 1 + fi +} + +setup_python() { + require_cmd python3 + log "Creating venv at ${PY_ENV_DIR}" + python3 -m venv "${PY_ENV_DIR}" + # shellcheck disable=SC1091 + source "${PY_ENV_DIR}/bin/activate" + log "Upgrading pip/setuptools/wheel" + python -m pip install --upgrade pip setuptools wheel + + if [[ -f "${ROOT_DIR}/flask_service/requirements.txt" ]]; then + log "Installing flask service requirements" + python -m pip install -r "${ROOT_DIR}/flask_service/requirements.txt" + fi + + if [[ -f "${ROOT_DIR}/dist/requirements.txt" ]]; then + log "Installing dist requirements" + python -m pip install -r "${ROOT_DIR}/dist/requirements.txt" + fi + + log "Running pip check" + python -m pip check || true +} + +setup_node_project() { + local dir="$1" + if [[ -f "${dir}/package.json" ]]; then + require_cmd npm + log "Installing npm deps in ${dir}" + (cd "${dir}" && npm install) + log "Dependency tree (${dir})" + (cd "${dir}" && npm ls --depth=0 || true) + fi +} + +print_next_steps() { + cat <