Skip to main content
Glama
paint-line-toolkit

paint-line-toolkit

README.md
# 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

B3.1/5.0

Scored across 15 tools

Disambiguation4/5

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.

Naming Consistency4/5

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.

Tool Count5/5

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.

Completeness4/5

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.