# SCX Parts Catalogue and Controlled AI Costing

## Purpose

The Bill of Materials Creator now includes a shared database catalogue for reusable parts and price history. It accepts CSV or JSON parts lists, matches approved prices into future BOMs, and can research current public internet prices using the configured OpenAI Responses API web-search tool.

## Generating a BOM from a crane layout

Use the layout import controls when the BOM should be generated from runway, bridge and trolley geometry:

1. In the Manual Layout Planner, select **Export Project**. The normal file name is `scx_manual_crane_layout_project.json`.
2. Open the Bill of Materials Creator.
3. In **Generate BOM from an SCX crane layout or project**, select **Load Layout / Project JSON**.
4. Choose the exported manual planner JSON, a saved SCX project JSON or a Digital Twin layout JSON.
5. Review the generated runway, bridge, trolley/hoist, electrical, controls, safety, mechanical and installation lines before costing or committing the BOM.

The BOM Creator reads `settings.cellM`, `runways`, `bridges`, `trolleys`, `stations` and `heightSetup` from manual planner project exports. Runway records generate rails, beams, clips, supports, end stops and conductor-bar items. Bridge records generate girders, end carriages, travel wheels, motors, buffers, VFDs, collectors, panels, remotes, limits, warnings and festoon items. Trolley/hoist records generate trolley frames, hoist units, rope, hook blocks, drives, VFDs, overload protection and travel/hoist limits.

Use **Use Current SCX Layout** only when the layout is already loaded in the running web app and available from `/api/layout`. For a standalone manual planner export, use **Load Layout / Project JSON**. The separate **Import CSV / JSON** button in the BOM table imports existing BOM item rows; it does not convert crane geometry into a BOM.

## Importing a parts list

1. Open the Bill of Materials Creator.
2. Select **Import Parts & Costs to Database**.
3. Choose a CSV or JSON file.
4. Review the import count and errors, then refresh the catalogue.

Recognised columns include:

- Part Number, Description, Manufacturer, Category and Unit.
- Unit Cost, Currency, Supplier and Price Date.
- Lead Time Weeks and Minimum Quantity.
- Price Basis, Source URL and Notes.

Common headings such as `Part No`, `SKU`, `Unit Price`, `Vendor`, `MOQ` and `UOM` are also recognised. Supported currencies are GBP, EUR and USD. Imported prices are treated as authenticated, human-supplied approved data and retain their import provenance and price history.

An example is available at `downloads/SCX_Parts_Catalog_Import_Example.csv`.

## Reusing prices

Select **Apply Approved Prices to BOM**. Automatic application requires:

- an exact normalised part-number match;
- an approved catalogue price;
- the same currency as the current BOM.

Description-only matches are reported but not automatically applied. Existing non-zero BOM prices are preserved unless **Overwrite existing BOM prices** is selected.

## AI and internet price research

Select **AI + Internet Research BOM Costs**. The server synchronises the BOM part definitions into the catalogue and asks the configured OpenAI model to search current public supplier or manufacturer pages. Research is limited to 50 unique parts per request.

The research policy requires a direct public product-page URL, explicit currency, supplier, price date, price basis and confidence. It does not perform currency conversion. Results without a defensible price, matching currency, catalogue part or valid HTTP/HTTPS source are rejected rather than stored.

Every accepted research result is stored with `proposed` status and cannot be applied to a BOM. An engineer must inspect the source link and approve or reject it with a mandatory comment. The decision, reviewer, date and source remain in the database audit trail.

OpenAI web search is a billable API tool and requires `OPENAI_API_KEY` on the server. The API key is never sent to the browser. See the official OpenAI web-search documentation at `https://developers.openai.com/api/docs/guides/tools-web-search` for current platform behaviour and charges.

## Procurement limitations

Public web prices are budgetary evidence, not supplier quotations. Always confirm configuration, pack quantity, minimum order, tax, delivery, installation, warranty, geographic availability, validity period and commercial terms. Safety-critical and engineered components require technical compliance review in addition to cost approval.