Syntactic Engine API

For grammar writers and researchers: provide a RuleBase directory URL and an input graph. RoboCrunch runs the Engine and returns the resulting graph.

POST https://robocrunch.net/api/run

Current operation: Tau / Comprehension. Other Level/Direction settings return an error.

Call the API from Python

The Python tools require Python 3.10 or later and use only the standard library. Download the three files and place them in one folder:

robocrunch.py converts text into character graphs, reads and writes graph files, and calls the API. robocrunch_paths.py displays full Token paths. robocrunch_examples.py runs three examples and saves their graphs and paths.

On Windows, run:

py robocrunch.py --text "a" --save-input InputGraph.txt --output OutputGraph.txt

On macOS or Linux, use python3 in place of py.

You can also import the client into your own Python program:

from robocrunch import Graph, RoboCrunchClient

graph = Graph.from_text(text="a")
client = RoboCrunchClient(api_url="https://robocrunch.net/api/run")
result = client.run(rule_base_url="https://symsuper.com/grammars/english-tau-c/", graph=graph)
result.write_file(path="OutputGraph.txt")

Read the output paths

With robocrunch.py and robocrunch_paths.py in the same folder, read the output file:

py robocrunch_paths.py OutputGraph.txt

The reader prints the node and edge counts, each Label sequence, and its Token IDs. It follows Token edges from begin to end, retaining distinct Token paths. Each Token is visited at most once within a path.

The graph is read without modification. The default limit is 10,000 paths; use --max-paths to change it. Exceeding the limit reports an error.

Several alternatives can legitimately remain in one graph. Read the path explanation for the three alternatives produced by the input a.

Run the three examples

With all three Python files in the same folder, run cat, a cat, and cat?:

py robocrunch_examples.py
py robocrunch_paths.py examples/cat-question-OutputGraph.txt

The runner creates an examples folder. For each input, it saves three UTF-8 files: the input graph, the complete output graph, and a readable list of output paths with Token IDs.

See the verified result counts and the English RuleBase examples.

Provide a RuleBase directory

The directory must expose these two UTF-8 text files:

Level=Tau
Direction=Comprehension

Sample directory: https://symsuper.com/grammars/english-tau-c/

View sample rules · View sample settings

Grammar writers can host these files on their own public servers. API.txt is reserved and is currently ignored.

Send an API request

Send a POST request with Content-Type: application/json. Supply ruleBaseUrl and exactly one of inputGraph or inputGraphUrl.

This example supplies the character graph for a directly:

{
  "ruleBaseUrl": "https://symsuper.com/grammars/english-tau-c/",
  "inputGraph": "[[]]\n## begin\n## Lower-A\n## end\n[[token]]\n## 1\n:begin\ntoken:2\n## 2\n:Lower-A\ntoken:3\n## 3\n:end\n"
}

Alternatively, provide a public graph-file URL:

{
  "ruleBaseUrl": "https://symsuper.com/grammars/english-tau-c/",
  "inputGraphUrl": "https://robocrunch.net/clients/InputGraph-a.txt"
}

View the sample input graph. You can replace its URL with the public URL of your own graph file.

Pass ordinary multiline strings to the Python client. JSON serialization represents their line breaks as \n or \r\n; decoding restores the actual line breaks.

Read the response

A successful request returns a JSON object containing:

The Python client exposes the parsed graph as result.output_graph, the original graph text as result.output_graph_text, and the response JSON as result.metadata.

Graph format

[[class]] declares a class. ## id declares a node. Subsequent class:id lines identify its outgoing targets. A target without a colon belongs to the current class.

Label nodes have an empty class name: use [[]] for their class and addresses such as :begin. Token nodes use [[token]].

Each input Token must point to exactly one Label node. Include Tokens labeled begin and end. Token sequence is determined by edges, independently of node declaration order.

HTTP results

Input graphs and RuleBase files are limited to 1 MiB each. Graph size is measured in UTF-8 bytes. Remote files must be available through public HTTP or HTTPS URLs.