create_sequence
Add a sequence element to HNPX fiction documents by specifying location, summary, time, and point-of-view within a chapter structure.
Instructions
Create a new sequence element
Args: file_path (str): Path to the HNPX document parent_id (str): ID of the parent chapter element location (str): Location description summary (str): Sequence summary text time (Optional[str]): Time indicator (e.g., "night", "next day", "flashback") pov (Optional[str]): Point-of-view character identifier
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes | ||
| parent_id | Yes | ||
| location | Yes | ||
| summary | Yes | ||
| time | No | ||
| pov | No |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |
Implementation Reference
- src/hnpx_sdk/tools.py:291-321 (handler)The handler function that implements the create_sequence tool. It parses the HNPX document, builds attributes for the new sequence element, uses the _create_element helper to add it under the specified parent, saves the document, and returns the new element's ID.
def create_sequence( file_path: str, parent_id: str, location: str, summary: str, time: Optional[str] = None, pov: Optional[str] = None, ) -> str: """Create a new sequence element Args: file_path (str): Path to the HNPX document parent_id (str): ID of the parent chapter element location (str): Location description summary (str): Sequence summary text time (Optional[str]): Time indicator (e.g., "night", "next day", "flashback") pov (Optional[str]): Point-of-view character identifier """ tree = hnpx.parse_document(file_path) attributes = {"location": location} if time: attributes["time"] = time if pov: attributes["pov"] = pov new_id = _create_element(tree, parent_id, "sequence", attributes, summary) hnpx.save_document(tree, file_path) return f"Created sequence with id {new_id}" - src/hnpx_sdk/server.py:19-19 (registration)Registers the create_sequence function as an MCP tool in the FastMCP application.
app.tool()(tools.create_sequence) - src/hnpx_sdk/tools.py:227-264 (helper)Shared helper function called by create_sequence (and other create_* functions) to perform hierarchy validation, generate unique ID, create the element with attributes and summary, and return the new ID.
def _create_element( tree: etree.ElementTree, parent_id: str, element_tag: str, attributes: dict, summary_text: str, ) -> str: """Generic element creation helper""" parent = hnpx.find_node(tree, parent_id) if parent is None: raise NodeNotFoundError(parent_id) # Check hierarchy valid_hierarchy = { "book": ["chapter"], "chapter": ["sequence"], "sequence": ["beat"], "beat": ["paragraph"], } if ( parent.tag not in valid_hierarchy or element_tag not in valid_hierarchy[parent.tag] ): raise InvalidHierarchyError(parent.tag, element_tag) # Generate unique ID existing_ids = hnpx.get_all_ids(tree) new_id = hnpx.generate_unique_id(existing_ids) attributes["id"] = new_id # Create element element = etree.SubElement(parent, element_tag, **attributes) summary = etree.SubElement(element, "summary") summary.text = summary_text return new_id