Semiconductor Particle Workbench

This repository implements a sustainable reference architecture for a semiconductor particle-analysis dashboard.

What is included

• typed ViewSpec / LayoutPatch / StylePatch / AnalysisSpec models
• a mock semiconductor particle repository with wafer, particle, SEM-like image, and EDX-like spectrum data
• separate Search / Wafer Detail / Trend / ML services
• a patch engine that enforces locked zones and component guardrails
• a deterministic prompt router that converts Japanese/English UI requests into structured actions
• a Dash app prototype with a fixed dashboard canvas, sub-pages inside dense workspaces, and a hidden left drawer for navigation, filters, prompt input, and context
• an optional Vizro shell that shows how the stable page skeleton can stay declarative
• an optional MCP server with resources, prompts, and whitelisted tools

Package layout

src/semiparticle_workbench/
  core/           # reusable typed schemas, registries, patch engine, prompt router
  domain/         # semiconductor-specific field catalog, mock data, metrics, chart presets, standard views
  services/       # search/detail/trend/ml adapters; replace these with production APIs
  runtime/        # service container wiring
  ui/             # Dash shell, page render modules, and Vizro shell
  ui/pages/       # Search/Wafer/Trend/ML page rendering and shared UI helpers
  mcp/            # optional MCP server

Additional handoff docs live under docs/, especially docs/rest_data_contract.md for REST integration. The normalization test reads docs/rest_payload_particle_dashboard_v1.json, so update that fixture and the REST contract doc together when the real payload is finalized.

Extension map

Most feature work should stay inside one of these boundaries:

• Data source changes: implement ParticleRepository, then wire it through runtime.service_container.
• Search/Wafer UI changes: edit ui/pages/search.py or ui/pages/wafer.py; keep ui/dash_app.py focused on stores, callbacks, shell navigation, and prompt handling.
• Trend/ML analysis changes: prefer service-level changes first, then update the related chart preset if the visual contract changes.
• Prompt behavior changes: update the typed router, patch schemas, or whitelisted analysis specs; do not generate raw Python or raw Plotly code from prompts.

This split keeps data-science logic, data access, page rendering, and prompt safety separable enough for different developers to work without sharing a large UI file.

Quick start

1) Install the core package

pip install -e .

2) Export static Plotly previews

python -m semiparticle_workbench.demo

3) Run the Dash prototype

pip install -e .[ui]
python -m semiparticle_workbench.app

Equivalent installed command:

semiparticle-workbench

3b) Production-like run settings

The app reads deployment settings from environment variables. Defaults use the mock repository.

SEMIPARTICLE_DATA_SOURCE=mock
SEMIPARTICLE_HOST=127.0.0.1
SEMIPARTICLE_PORT=8050
SEMIPARTICLE_DEBUG=false
python -m semiparticle_workbench.app

Run a preflight check without starting Dash:

python -m semiparticle_workbench.app --smoke-check

For a WSGI server, use the exposed Flask server:

semiparticle_workbench.wsgi:server

3c) Run with a REST data source

SEMIPARTICLE_DATA_SOURCE=rest
SEMIPARTICLE_REST_BASE_URL=http://127.0.0.1:8010
SEMIPARTICLE_REST_BEARER_TOKEN=
SEMIPARTICLE_REST_TIMEOUT_SEC=10
SEMIPARTICLE_REST_VERIFY_SSL=true
python -m semiparticle_workbench.app --smoke-check
python -m semiparticle_workbench.app

The REST adapter is intentionally small. It only needs wafer search, wafer particles, SEM asset, and EDX spectrum endpoints, and it normalizes those payloads into the same DataFrame columns used by the mock repository. See docs/rest_data_contract.md for endpoint payloads and normalized columns.

4) Build the Vizro shell

pip install -e .[vizro]
python -c "from semiparticle_workbench.ui.vizro_shell import build_vizro_dashboard; build_vizro_dashboard().run()"

5) Start the MCP server

pip install -e .[mcp]
python -c "from semiparticle_workbench.mcp.server import create_mcp_server; create_mcp_server().run()"

Design choices

• Vizro is limited to the stable page shell and standard workbench layout.
• Dash owns dynamic interaction, drawer state, prompt handling, temporary analysis panels, and callbacks.
• Plotly is the charting standard.
• Prompt handling never generates raw Python or raw Plotly figures; it only produces typed patches or whitelisted analysis specs.
• Services isolate the front-end from databases and analysis code.
• Repositories isolate services from mock data or REST data sources.
• User customization is stored as patches instead of full copied pages.
• UX shell keeps the primary dashboard fixed on screen; filters, navigation, and LLM actions live in a hidden left drawer so the main canvas behaves like a real operations dashboard instead of a long report page.

Tests

pytest