making this more convenient for builder
better error reporting
making it really more like a builder
updated to reflect changes Vivek made to these APIs