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 client requires Python 3.10 or later and uses only the standard library. It converts English text into character graphs, reads and writes graph files, and calls the API.

Download robocrunch.py

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")

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.