HNPX SDK

Instructions

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