arkennemasis Sheet Probe (read a client sheet)

The arkennemasis variation pipeline starts with a client's spreadsheet: rows of variants, columns nobody named the same way twice. ArkSheetProbe is the front door - it reads the sheet without interpreting it, and hands you three things: the raw rows, a human/LLM-readable description of the columns, and a heuristic column mapping you can accept or hand-write. It's the difference between "please send us your spreadsheet in our format" and "we'll read whatever you have."

What it actually does

One required input: sheet_path - a CSV, TSV or JSON export of the client's sheet. XLSX works only if openpyxl happens to be installed; otherwise it fails with a one-line "export as CSV instead" message, because every spreadsheet tool exports CSV. The optional sample_rows (default 8) controls how many example rows go into the column report - enough for a model to see the sheet's shape, not so many that the whole sheet gets pasted into a prompt.

Behind the scenes it sniffs the file's encoding from its first bytes before reading - UTF-16 with a BOM (Excel's "Unicode Text" export), UTF-8-sig, cp1252 for Windows-saved files, latin-1 as a last resort. That's the kind of detail that saves you from 'utf-8' codec can't decode byte 0xff in position 0, which tells an operator nothing about the file they actually have.

Four outputs:

• raw_json - the rows as JSON, for the intake node downstream.
• columns_report - the column names plus sample rows, formatted for a human or an LLM to read.
• suggested_mapping - the heuristic mapping. Headers that already say filename or axis:finish map themselves; WooCommerce exports prefixed meta:attribute_pa_ are recognised by convention.
• row_count - how many rows you're dealing with, so you can sanity-check before spending anything.

The workflow it feeds

The intended flow: Sheet Probe → (optionally) an LLM refines the mapping using columns_report → Variation Intake normalises it into the pipeline's canonical VARIANTS/SPECS/PRODUCT tables. The probe's own heuristic mapping often means no model is needed at all - a well-named sheet maps itself. If a column isn't obvious, that's exactly when you feed the report to a vision/text LLM and let it propose the mapping, then eyeball the result.

Install

ArkSheetProbe is part of the 61-node comfyui-arkennemasis pack, in the arkennemasis/Variation menu:

cd ComfyUI/custom_nodes
git clone https://github.com/Hishamahmer/comfyui-arkennemasis
pip install -r comfyui-arkennemasis/requirements.txt   # then restart ComfyUI

Or ComfyUI Manager → Install via Git URL with the repo URL. No API key for this node itself - it's local file reading. (The LLM refinement step, if you use it, goes through the pack's Replicate or Codex LLM nodes, which do need credentials.)

The philosophy is worth internalising: the probe deliberately does not interpret the sheet, because a downstream node that has to understand one client's layout is a node contaminated by that client's layout. Read first, map second, normalise third - and keep each client's quirks out of the core pipeline. That separation is the whole reason this pipeline stays serviceable when the client's spreadsheet changes shape.