Skip to content

m6r-ai/m6rclib

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

37 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

m6rclib API Documentation

m6rclib is a Python package that provides a parser and prompt compiler for the Metaphor language, a structured text format for defining roles, contexts, and actions.

Installation

pip install m6rclib

Basic Usage

from m6rclib import MetaphorParser

# Create a parser instance
parser = MetaphorParser()

# Parse a Metaphor string
input_text = """
Role:
    You are a helpful assistant.
Context:
    The user needs help with Python.
Action:
    Provide clear Python examples.
"""

# Parse the input with search paths for Include: directives
syntax_tree = parser.parse(input_text, "example.m6r", ["/path/to/includes"])

Core Classes

MetaphorParser

The main class for parsing Metaphor documents.

Methods

  • parse(input_text: str, filename: str, search_paths: List[str], embed_path: Optional[str]) -> MetaphorASTNode

    • Parses a string containing Metaphor content
    • Args:
      • input_text: The Metaphor content to parse
      • filename: Name to use for error reporting
      • search_paths: List of paths to search for included files
      • embed_path: Path used to search for embedded files
    • Returns: The root of the abstract syntax tree
    • Raises:
      • MetaphorParserError: If there are syntax errors
      • FileNotFoundError: If a required file cannot be found
  • parse_file(filename: str, search_paths: List[str]) -> MetaphorASTNode

    • Parses a Metaphor file
    • Args:
      • filename: Path to the file to parse
      • search_paths: List of paths to search for included files
    • Returns: The root of the abstract syntax tree
    • Raises:
      • MetaphorParserError: If there are syntax errors
      • FileNotFoundError: If the file cannot be found

MetaphorASTNode

Represents a node in the abstract syntax tree (AST).

Properties

  • node_type: MetaphorASTNodeType

    • The type of the node
    • Read-only
  • value: str

    • The raw text value of the node
    • Read-only
  • parent: Optional[MetaphorASTNode]

    • The parent node, if any
    • Read-only
  • children: List[MetaphorASTNode]

    • The node's child nodes (returns a shallow copy)
    • Read-only

Methods

  • attach_child(child: MetaphorASTNode) -> None

    • Adds a child node to this node
    • Args:
      • child: The node to attach as a child
  • detach_child(child: MetaphorASTNode) -> None

    • Removes a child node from this node
    • Args:
      • child: The node to detach
    • Raises:
      • ValueError: If the node is not a child of this node
  • get_children_of_type(self, node_type: MetaphorASTNodeType) -> List['MetaphorASTNode']

    • Returns a list of all immediate children that match the specified node type.
    • Args:
      • node_type (MetaphorASTNodeType): The type of nodes to filter for
    • Returns:List of child nodes matching the specified type

MetaphorASTNodeType

An enumeration of possible AST node types.

Values

  • ROOT (0): Root node of the AST
  • TEXT (1): Text content node
  • ROLE (2): Role definition node
  • CONTEXT (3): Context definition node
  • ACTION (4): Action definition node

Formatting Functions

Helper functions for formatting nodes and errors.

  • format_ast(node: MetaphorASTNode) -> str

    • Format an AST node and its children as a string
    • Args:
      • node: The root node to format
    • Returns: Formatted string representation of the AST
  • format_errors(errors: List[MetaphorParserSyntaxError]) -> str

    • Format a list of syntax errors as a string
    • Args:
      • errors: List of syntax errors to format
    • Returns: Formatted error string with each error on separate lines

Exceptions

MetaphorParserError

Main exception wrapper for parser errors.

  • Attributes:
    • errors: List[MetaphorParserSyntaxError]: List of syntax errors encountered

MetaphorParserSyntaxError

Detailed syntax error information.

  • Attributes:
    • message: str: Error description
    • filename: str: File where error occurred
    • line: int: Line number of error
    • column: int: Column number of error
    • input_text: str: Input line containing error

File Format

Metaphor files use the following format:

Role:
    Description of the role
    Additional role details

Context:
    Description of the context
    Context details
    Context: Subsection
        More detailed context information

Action:
    Description of the action
    Step-by-step actions to take

Special Directives

  • Include: filename

    • Includes another Metaphor file
    • File is searched for in the provided search paths
  • Embed: pattern

    • Embeds the contents of matching files
    • Supports glob patterns
    • Use **/ for recursive matching