paint-line-toolkit
# paint-line-toolkit
**Preliminary sizing math for industrial finishing lines, packaged for AI agents.**
This is a Python library, a CLI and an [MCP](https://modelcontextprotocol.io) server. It covers
the physics and code-cited relationships behind paint and powder booths, cure ovens, air make-up
units (AMUs) and overhead conveyors. An agent such as Claude can size a line by calling tested
engineering functions instead of guessing numbers.
> ⚠️ **Preliminary sizing aid only.** It is not a substitute for equipment-vendor engineering, a
> licensed engineer's design, or review by the authority having jurisdiction (AHJ) against the
> code editions in force (NFPA 33, NFPA 86, OSHA 29 CFR 1910.94 / 1910.107, local fire and gas codes).
## Why this exists
Sizing a finishing line means juggling four things that depend on each other:
- **Throughput.** Production rate and part pitch set the line speed.
- **Air.** Booth airflow sets the make-up air, and the make-up air sets a large share of the winter gas bill.
- **Heat.** Line speed and the cure schedule set the oven length, and the oven length sets its heat load.
- **Building.** Openings, truss heights and stack heights decide whether the line fits at all.
A language model asked to size a line will produce confident numbers with no basis. This toolkit
writes the relationships down as small, typed, unit-labelled functions, and every number in a
result carries its **basis**:
| basis | meaning |
|---|---|
| `code` | value tabulated in a published code or standard (verify the edition your AHJ enforces) |
| `physics` | a physical relationship or physical property |
| `public_data` | published reference data (e.g. heating value of natural gas) |
| `user_input` | supplied by the caller |
| `advisor` | supplied by an installed `SizingAdvisor` plug-in (see below) |
## Design principle: public math, user-supplied design basis
The package contains **only textbook physics and code-cited relationships**. It ships **no design
defaults**. Velocities for cases no public table covers, margins, efficiencies, allowances, part
spacing and booth/oven geometry are all **required inputs**, gathered in a `DesignBasis`.
In real projects those values come from the equipment vendor, the coating's technical data sheet,
the site and the engineer's own experience. A tool that hides them behind defaults gives answers
that look more certain than they are. When a value is missing, the agent asks for it.
The design basis can come from two places:
1. **You.** Fill in a `DesignBasis`. `examples/design_basis.example.json` shows the shape, with
illustrative inputs that are not recommendations.
2. **A `SizingAdvisor` plug-in.** This is a separately installed package that holds proprietary or
empirical sizing rules and turns a `SizingRequest` into a `DesignBasis`. **No advisor is
included.** Without one, `suggest_design_basis` and `plt size --advisor` fail with
"not included". See [Plugging in sizing rules](#plugging-in-sizing-rules).
## What's inside
| module | contents |
|---|---|
| `booth` | Exhaust airflow Q = A × V for crossdraft, open-face, downdraft and enclosed booths; controlling area per booth type; OSHA Table G-10 velocities for liquid spray booths |
| `amu` | Make-up air; burner input from Q = 1.08 × cfm × ΔT; altitude correction; gas flow |
| `oven` | Dwell = path length ÷ speed; check against heat-up + cure schedule; required path length; steady-state heat balance (product + hangers + chain + exhaust + walls); NFPA 86 solvent-ventilation screen |
| `conveyor` | Throughput, required line speed, carrier pitch, carrier/hook load check, index-conveyor cycle |
| `clearance` | Part vs silhouette opening; equipment vs bottom of truss; stack discharge vs roof |
| `advisor` | `SizingRequest`, `DesignBasis`, the `SizingAdvisor` protocol and the not-included stub |
| `line` | `size_line()` chains all of the above into one report with every assumption and warning |
| `mcp_server` | Everything above as MCP tools, with JSON-schema inputs and structured outputs |
| `cli` | `plt size ...`, `plt basis-schema` |
Units are US customary, as on most North American equipment data sheets. Every field name carries
its unit (`_ft`, `_fpm`, `_cfm`, `_btuh`, `_f`, `_lb`), and results also report SI (m³/h, kW, °C, m/min).
## Install
```bash
pip install -e ".[dev]" # library, CLI, MCP server, test tools
pip install -e ".[agent]" # + Anthropic SDK for examples/agent_demo.py
```
Python 3.11+.
## Worked example
> *A liquid line: 120 parts/hour; parts 4 × 4 × 1 ft (length along the line × height × width),
> 60 lb, steel. Bake 20 min at 325 °F metal temperature. Near Toronto.*
```bash
plt size --rate 120 --part 4x4x1 --weight 60 --coating liquid \
--cure 20 --cure-temp 325 --basis examples/design_basis.example.json
```
The example design basis uses these **illustrative inputs, not recommendations**:
- 2 ft gap between parts; all carriers loaded.
- 8 lb hanger; 200 lb carrier rating; 2.5 lb/ft chain.
- Crossdraft booth with a 14 × 8 ft face (112 ft²) at **100 fpm**. The velocity is from OSHA Table
G-10: large booth, air-operated guns, crossdraft up to 50 fpm.
- 12 min heat-up; 350 °F oven air; 3,000 ft² oven envelope at U = 0.12.
- Oven exhaust from the NFPA 86 screen at 2 gal/h of solvent.
- No design margin; burner efficiencies 0.85 (oven) and 0.9 (AMU).
- −4 °F winter design; 65 °F supply air; 570 ft elevation.
| step | calculation | result |
|---|---|---|
| carrier pitch | 4 ft part + 2 ft gap | **6 ft** |
| line speed | 120 parts/h × 6 ft ÷ 60 | **12 fpm** (3.66 m/min) |
| carrier load | 60 + 8 lb vs 200 lb rating | **68 lb** (34 %) |
| booth | 112 ft² × 100 fpm | **11,200 cfm** (19,029 m³/h) |
| oven path | 12 fpm × (12 + 20) min | **384 ft** heated path, 32 min dwell |
| oven exhaust | 10,000 scf/gal × 2 gal/h ÷ 60 | **333 scfm** (NFPA 86 screen) |
| oven heat balance | product 220,320 + hangers 29,376 + chain 55,080 + exhaust 100,800 + walls 100,800 | **506,376 BTU/h** (148 kW) |
| oven burner | ÷ 0.85 | **595,736 BTU/h** |
| AMU | 1.08 × 11,533 cfm × 69 °F × 0.983 (altitude) | **845,220 BTU/h** to the air; 939,134 BTU/h gas input (275 kW) |
| stack | proposed top at 34 ft vs roof 26 ft + 10 ft | **flagged: 2 ft short** |
The report lists 31 assumptions, each with its basis, and the warnings. The stack check catches
that the proposed stack top is 2 ft lower than the input requires.
## Use it from an AI agent (MCP)
The MCP server exposes these tools:
- **Whole line:** `size_line`, `suggest_design_basis`.
- **Booth:** `osha_g10_velocity`, `booth_exhaust_airflow`.
- **AMU and oven:** `amu_sizing`, `oven_dwell_check`, `oven_heat_load`, `nfpa86_solvent_ventilation`.
- **Conveyor:** `conveyor_throughput`, `conveyor_required_speed`, `hook_load_check`, `index_cycle`.
- **Clearances:** `part_clearance_check`, `building_clearance_check`.
- **Sources:** `list_references`.
The server's instructions tell the agent never to invent design values.
**Claude Desktop.** Add this to `claude_desktop_config.json`, using the Python that has the package installed:
```json
{
"mcpServers": {
"paint-line-toolkit": {
"command": "C:/path/to/venv/Scripts/python.exe",
"args": ["-m", "paint_line_toolkit.mcp_server"]
}
}
}
```
**Claude Code:**
```bash
claude mcp add paint-line-toolkit -- python -m paint_line_toolkit.mcp_server
```
or commit a project `.mcp.json`:
```json
{ "mcpServers": { "paint-line-toolkit": { "command": "plt-mcp" } } }
```
**Docker** (stdio): `docker build -t paint-line-toolkit .`, then
`{"command": "docker", "args": ["run", "-i", "--rm", "paint-line-toolkit"]}`.
### Example agent session
This is an illustrative transcript. The tool calls and responses are what the server returns, and
the assistant's text is condensed.
> **User:** I need to powder-coat 120 parts/hour, parts 4×4×1 ft, max 60 lb each; size the booth,
> oven, AMU and conveyor. Cure is 10 min at 400 °F. We're near Toronto.
```text
-> suggest_design_basis({"request": {"rate_parts_per_hour": 120, "part_length_ft": 4, ...,
"coating": "powder", "cure_metal_temp_f": 400, "cure_time_min": 10}})
<- error: Sizing advisor not included. This public package ships no proprietary or empirical
sizing rules. Supply a DesignBasis yourself ...
-> conveyor_required_speed({"target_parts_per_hour": 120, "spacing_ft": 6})
<- required_speed_fpm 12.0 (assuming a 2 ft gap, to be confirmed)
-> oven_dwell_check({"path_length_ft": 240, "line_speed_fpm": 12, "cure_time_at_temp_min": 10,
"heat_up_min": 10})
<- dwell_min 20.0, meets_schedule true
```
> **Assistant:** I can do the kinematics now. With a 2 ft gap (please confirm), the line runs at
> **12 fpm**. A 240 ft heated path gives 20 min dwell, which covers 10 min heat-up plus 10 min at
> 400 °F, if your parts really heat up in 10 min.
>
> To size the booth, oven heat and AMU I need values the toolkit deliberately does not assume:
> 1. **Booth.** Booth type and open area, plus the powder-booth design velocity from your booth
> vendor. OSHA Table G-10 only covers liquid spray.
> 2. **Booth air.** Whether the booth exhausts outdoors or returns filtered air to the plant.
> 3. **Oven.** Oven exhaust (the vendor's NFPA 86 value), envelope area and panel U-value, your
> design margin, and the burner efficiency.
> 4. **Site.** Winter design temperature (ASHRAE data for your site), AMU supply temperature and
> burner efficiency.
> 5. **Conveyor.** Carrier rating, hanger weight and chain weight.
>
> *Preliminary sizing aid, not a substitute for vendor engineering or code review.*
`examples/agent_demo.py` runs this loop for real. It starts the MCP server over stdio and gives
its tools to Claude through the Anthropic API. It reads only `ANTHROPIC_API_KEY` from the
environment, never a `.env` file, and skips cleanly if the key is not set.
## Plugging in sizing rules
Empirical or proprietary rules plug in through the `SizingAdvisor` protocol. These are rules that
turn a part and a rate into booth geometry, velocities, margins and allowances.
```python
class SizingAdvisor(Protocol):
name: str
def suggest(self, request: SizingRequest) -> DesignBasis: ...
```
Implement it in **your own package** (`examples/advisor_template.py` is a skeleton with no rules)
and register it:
```toml
[project.entry-points."paint_line_toolkit.advisors"]
my-rules = "my_private_rules.advisor:MyAdvisor"
```
Once it is installed, `plt size ... --advisor`, the `suggest_design_basis` MCP tool and
`size_line_with_advisor()` use it. Reports mark that design basis as `advisor`, so a reader always
knows which numbers came from public math and which from your rules. Without a plug-in, the stub
raises `AdvisorNotIncludedError`.
## Library use
```python
from paint_line_toolkit import DesignBasis, LineSpec, SizingRequest, size_line, amu_sizing
request = SizingRequest(
rate_parts_per_hour=120,
part_length_ft=4,
part_height_ft=4,
part_width_ft=1,
part_weight_lb=60,
coating="liquid",
cure_metal_temp_f=325,
cure_time_min=20,
)
basis = DesignBasis.model_validate_json(open("examples/design_basis.example.json").read())
report = size_line(LineSpec(request=request, basis=basis))
amu = amu_sizing(exhaust_cfm=10_000, design_outdoor_temp_f=0, supply_temp_f=70, burner_efficiency=0.9)
# 1.08 × 10,000 × 70 = 756,000 BTU/h to the air
```
## What is in the math, and what is not
**Implemented (public sources):**
- Q = A × V, and the controlling area per booth type (ACGIH, OSHA definitions).
- OSHA 1910.94(c)(6) Table G-10 minimum velocities for liquid spray booths.
- NFPA 33 performance criteria: 25 % of LFL for vapours, 50 % of MEC for powder.
- Sensible heat Q = 1.08 × cfm × ΔT and the standard-atmosphere density ratio (ASHRAE).
- m·cp·ΔT product heating and U·A·ΔT wall losses (physics), with metal specific heats from property tables.
- NFPA 86 solvent-ventilation screen: 10,000 scf per gallon.
- Natural gas ≈ 1,000 BTU/scf, overridable (EIA averages about 1,030–1,040).
- Conveyor and index kinematics, carrier statics, and clearance geometry.
**Not implemented, by design:**
- Transient part heat-up. It is an input; measure it with an oven data logger.
- Powder-booth velocity tables (no public table) and the NFPA 33 MEC calculation (vendor).
- Door and opening losses (cover them with your design margin), and chain-pull analysis.
## References
These are listed in `references.py`, and assumptions cite them by id. Always check the edition
your AHJ enforces.
- OSHA 29 CFR 1910.94(c)(6), Table G-10: minimum maintained velocities into spray booths
- OSHA 29 CFR 1910.107: spray finishing using flammable and combustible materials
- NFPA 33: Spray Application Using Flammable or Combustible Materials
- NFPA 86: Ovens and Furnaces
- ASHRAE Handbook: Fundamentals
- ACGIH: Industrial Ventilation, A Manual of Recommended Practice for Design
- U.S. EIA: heat content of natural gas
## Development
```bash
pip install -e ".[dev]"
pytest # worked examples, property tests (hypothesis), CLI, advisor interface, MCP round-trip
ruff check . && ruff format --check .
mypy # strict
```
## License
MIT © Maximiliano Gomez Montero
TDQS
Scored across 15 tools
Most tools target clearly separate calculations: AMU sizing, booth airflow, oven heat load, conveyor throughput/speed, hook load, clearances, and code checks. The main ambiguity is between size_line and the individual sizing tools, though size_line is described as whole-line preliminary sizing. part_clearance_check and building_clearance_check could be momentarily confused but operate on different objects.
All names use snake_case consistently. Most are noun-based calculation labels (amu_sizing, conveyor_throughput, oven_heat_load), while a few are verb-led commands (size_line, suggest_design_basis, list_references); this is a minor deviation but still predictable.
Fifteen tools is well within a reasonable range for a specialized engineering toolkit. Each tool covers a distinct calculation or support function, and none appears redundant or filler.
The surface covers the core paint-line sizing workflow: conveyor, booth exhaust, OSHA/NFPA checks, oven dwell and heat load, AMU, hook/part/building clearances, whole-line sizing, and references. Minor domain gaps remain, such as duct/fan sizing, cooling or flash-off zones, and emissions beyond NFPA screening, but agents can work around them.