graph-doc: automate subgraph documentation generation

[denverbaumgartner]

graphdoc

graphdoc, see repository here, is a system for automating the generation of subgraph documentation through the utilization of Large Language Models. A production server, running an instance of graphdoc, can be found at the following endpoint: here. To receive a documented subgraph, one must simply provide a valid GraphQL schema to the /inference endpoint. An example can be ran through the swagger frontend linked above.

Proposal

The current subgraph development flow, utilizing the graph-cli, is as follows:

1. graph init: Initializes the subgraph.
2. Update your subgraph.yaml, schema.graphql, and write your mapping.ts files
3. graph codegen && graph build: Generate types and other build artifacts.
4. graph auth <DEPLOY_KEY>: Authenticate through the Subgraph Studio.
5. graph deploy <SUBGRAPH_SLUG>: Deploy to the Subgraph Studio.

It would be ideal if we could add an additional optional step, step 2.5:
2.5: graph doc: The schema.graphql is passed to the graphdoc server, and returned with documentation to the user.

This would involve:

1. Parsing the schema.graphql to a string.
2. Submitting a request to the server:

curl -X 'POST' \
  'https://graphdoc-371862096075.us-central1.run.app/inference' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "database_schema": "type UserEntity @entity { id: Bytes! first_name: String! last_name: String! email: String! } type PersonEntity @entity { id: Bytes! first_name: String! last_name: String! email: String! }"
}'

3. Replacing the schema.graphql file with the prediction field of the returned object:

{
  "prediction": "\"Represents a user with identifiable attributes.\"\ntype UserEntity @entity {\n  \"Unique identifier for the user, stored as a byte array.\"\n  id: Bytes!\n  \"The first name of the user.\"\n  first_name: String!\n  \"The last name of the user.\"\n  last_name: String!\n  \"The email address of the user.\"\n  email: String!\n}\n\n\"Represents a person with identifiable attributes.\"\ntype PersonEntity @entity {\n  \"Unique identifier for the person.\"\n  id: Bytes!\n  \"The first name of the person.\"\n  first_name: String!\n  \"The last name of the person.\"\n  last_name: String!\n  \"The email address of the person.\"\n  email: String!\n}",
  "status": "success"
}

Internally, graphdoc does validation to ensure that the schema is not mutated, and solely supplemented with useful documentation. Quality checks are in place to attempt to mitigate hallucinations. It is recommended that users still validate returned documentation.

Please do reach out with any questions, concerns, or suggestions. Thanks!