H3 Constrained Semantic Planning:
This node records a model-free semantic-planning decision and materializes the accepted planning chain for the next stage of an H3 Context workflow. Although its name refers to semantic planning, this implementation explicitly records that model-based enrichment is unavailable rather than calling an AI model to generate additional interpretations or creative revisions. Its purpose is to make that limitation explicit while maintaining a structured planning handoff, so your workflow can distinguish an accepted planning chain from an AI-enriched proposal. It also acts as a validation boundary: if the supplied planning data causes a recognized validation, type, or value error, execution stops instead of passing along a potentially invalid result. This makes it useful when you need a clearly recorded, model-free planning path rather than automatic semantic enhancement.
H3 Constrained Semantic Planning Input Parameters:
reduction
A required connection of type H3_HIERARCHICAL_EVIDENCE_REDUCTION, represented internally as a ReconstructionReductionStage. This supplies the hierarchical evidence-reduction stage used when constructing the semantic-planning disposition. In practical terms, it carries structured information from an earlier reduction step, rather than an image, a text prompt, or a numeric setting. The node processes this information together with the planning context to produce its model-free planning record and accepted planning chain. The supplied code does not expose the reduction stage’s individual fields or specify how each field affects acceptance, so you should provide the compatible upstream stage object rather than manually substitute unrelated data. Minimum, maximum, default values, and selectable options are not defined; this is a required typed connection.
plan
A required connection of type H3_CONTEXT_PLAN, represented internally as a ContextPlan. This supplies the planning context used alongside the evidence-reduction stage to construct the semantic-planning disposition and materialize the accepted planning chain. It is structured workflow data, not a free-form prompt or an editable model configuration. Its contents therefore affect the planning context processed by the node, but the supplied implementation does not establish whether the accepted plan will be identical to this incoming object or how individual plan fields are handled. Use the appropriate context plan for the reduction stage you are processing. Minimum, maximum, default values, and selectable options are not defined; this is a required typed connection.
H3 Constrained Semantic Planning Output Parameters:
semantic_planning
An output of type H3_CONSTRAINED_SEMANTIC_PLANNING, represented internally as a ReconstructionSemanticStage. This is the structured stage produced by the model-free semantic-planning boundary. It records the disposition associated with unavailable enrichment and contains the accepted plan that the node also exposes separately. Interpret it as a workflow planning record, not as generated artwork, an enriched prompt, or proof that a language or vision model has run. It is useful for downstream components that require the semantic-planning stage rather than only the accepted context plan. The supplied node source does not show its complete field structure or exact status values.
accepted_plan
An output of type H3_CONTEXT_PLAN containing the semantic stage’s accepted_plan. This is the materialized planning chain made available for subsequent processing, allowing you to continue with a context-plan connection without extracting it from the semantic stage yourself. Its importance is that it exposes the plan accepted by this boundary, rather than requiring downstream nodes to reuse the incoming plan independently. The code explicitly returns the plan stored in the generated stage; it does not establish that this plan is an unchanged copy of the input or that it contains model-generated improvements. This output is returned only when the stage is constructed successfully.
H3 Constrained Semantic Planning Usage Tips:
- Use this node when you want an explicit model-free planning handoff. Do not expect it to generate semantic additions, rewrite prompts, or invoke a language or vision model.
- Connect a compatible
H3_HIERARCHICAL_EVIDENCE_REDUCTIONstage toreductionand a compatibleH3_CONTEXT_PLANtoplan. Prefer data from the same intended planning workflow to avoid combining unrelated planning context and reduction results. - Connect
accepted_planto downstream nodes that require anH3_CONTEXT_PLAN. Usesemantic_planningwhen the next component specifically expects the completeH3_CONSTRAINED_SEMANTIC_PLANNINGstage. - Configure your source planning and evidence-reduction stages upstream. This node exposes no model selector, seed, policy, budget, numeric controls, or optional settings, even though the broader semantic-planning code includes related concepts.
- If execution fails, inspect the upstream planning data and the underlying exception in the ComfyUI logs before changing unrelated generation settings. The node intentionally stops on recognized validation, type, and value errors.
H3 Constrained Semantic Planning Common Errors and Solutions:
semantic_planning_failed: semantic planning boundary failed closed
- Explanation: The source explicitly supplies the error identifier
semantic_planning_failedand messagesemantic planning boundary failed closedwhen stage construction raises aContractValidationError,TypeError, orValueError. “Failed closed” means the node stops rather than returning a potentially invalid planning result. The precise formatting of the displayed error depends on the pipeline error helper. - Solution: Check that both required connections contain valid, compatible H3 Context data. Review the ComfyUI traceback for the original exception, which is preserved as the cause, then correct or regenerate the affected upstream stage.
ContractValidationError during stage construction
- Explanation: This is one of the exception types explicitly caught by the node and wrapped in the semantic-planning failure message. It indicates that construction encountered data that did not satisfy a required contract, but the supplied source does not identify the individual validation rules or their exact messages.
- Solution: Re-run the upstream nodes that produce the reduction and context plan, and ensure you are using compatible components from the same installation. Use the underlying validation message in the logs to identify the specific data that needs correction.
TypeError or ValueError during stage construction
- Explanation: These exception types are also explicitly caught and wrapped in the semantic-planning failure message. They can indicate an unexpected object type or an unacceptable value during processing; the supplied code does not identify which individual fields could cause them.
- Solution: Confirm that
reductionreceives a hierarchical evidence-reduction stage andplanreceives a context plan, rather than manually supplied text, dictionaries, or unrelated objects. If the connections appear correct, inspect the original exception in the logs and check for incompatible custom-node versions or malformed upstream results.
Missing or incompatible required connection
- Explanation: Both
reductionandplanare required typed inputs. Leaving either disconnected, or attempting to connect an incompatible socket type, can prevent workflow validation or execution before this node’s planning method runs. This is a connection issue rather than an exact error string shown in the supplied source. - Solution: Connect
H3_HIERARCHICAL_EVIDENCE_REDUCTIONdata toreductionandH3_CONTEXT_PLANdata toplan. If the expected sockets are unavailable, verify that the appropriate upstream nodes are installed and loaded, then reconnect the workflow.
