create_beat
Add a narrative beat to a hierarchical fiction document by specifying parent sequence and summary text for structured story development.
Instructions
Create a new beat element
Args: file_path (str): Path to the HNPX document parent_id (str): ID of the parent sequence element summary (str): Beat summary text
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes | ||
| parent_id | Yes | ||
| summary | Yes |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |
Implementation Reference
- src/hnpx_sdk/tools.py:324-338 (handler)The main handler function that parses the HNPX document, creates a new 'beat' element under the specified parent using the _create_element helper, saves the document, and returns the new beat's ID.
def create_beat(file_path: str, parent_id: str, summary: str) -> str: """Create a new beat element Args: file_path (str): Path to the HNPX document parent_id (str): ID of the parent sequence element summary (str): Beat summary text """ tree = hnpx.parse_document(file_path) new_id = _create_element(tree, parent_id, "beat", {}, summary) hnpx.save_document(tree, file_path) return f"Created beat with id {new_id}" - src/hnpx_sdk/server.py:20-20 (registration)Registers the create_beat function as a tool in the FastMCP application.
app.tool()(tools.create_beat) - src/hnpx_sdk/tools.py:227-263 (helper)Shared helper function used by create_beat (and other create_* functions) to validate hierarchy, 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