From 06c4c97fcc92945543849e5cfecba80530ca582f Mon Sep 17 00:00:00 2001 From: Dan Selman Date: Mon, 20 May 2024 16:10:56 +0100 Subject: [PATCH] docs Signed-off-by: Dan Selman --- README.md | 6 +- docs/README.md | 74 ++++++------------------ docs/classes/GraphModel.md | 36 ++++++------ docs/functions/getObjectChecksum.md | 4 +- docs/functions/getOpenAiEmbedding.md | 4 +- docs/functions/getTextChecksum.md | 4 +- docs/functions/textToCypher.md | 4 +- docs/globals.md | 28 --------- docs/type-aliases/Context.md | 4 +- docs/type-aliases/GraphModelOptions.md | 4 +- docs/type-aliases/GraphNodeProperties.md | 4 +- docs/type-aliases/SimilarityResult.md | 4 +- docs/variables/ROOT_MODEL.md | 4 +- docs/variables/ROOT_NAMESPACE.md | 4 +- typedoc.json | 3 +- 15 files changed, 62 insertions(+), 125 deletions(-) delete mode 100644 docs/globals.md diff --git a/README.md b/README.md index 0ed25ab..73010d2 100644 --- a/README.md +++ b/README.md @@ -70,4 +70,8 @@ Runtime result: - NEO4J_USER: defaults to `neo4j` ### Text Embeddings -- OPENAI_API_KEY: the OpenAI API key. If not set embeddings are not computed and written to the agreement graph and similarity search, natural language to Cypher generation ("chat with data") is not possible. \ No newline at end of file +- OPENAI_API_KEY: the OpenAI API key. If not set embeddings are not computed and written to the agreement graph and similarity search, natural language to Cypher generation ("chat with data") is not possible. + +## API Documentation + +API documentation is available [here](./docs/README.md). \ No newline at end of file diff --git a/docs/README.md b/docs/README.md index cc38f99..aae0b9f 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,68 +1,28 @@ -**@accordproject/concerto-graph** • [**Docs**](globals.md) +**@accordproject/concerto-graph** • **Docs** *** -# Concerto Graph +# @accordproject/concerto-graph -This project uses a [Concerto model](https://concerto.accordproject.org) to define the nodes and edges in a Neo4J graph database and uses the model to validate the properties on the nodes. +## Classes -![demo](demo.png) -[Demo](src/demo/index.ts) +- [GraphModel](classes/GraphModel.md) -In a few lines of code you can define a Concerto data model validated graph and perform a vector similarity search over -nodes with text content. +## Type Aliases -Concerto model (snippet): +- [Context](type-aliases/Context.md) +- [GraphModelOptions](type-aliases/GraphModelOptions.md) +- [GraphNodeProperties](type-aliases/GraphNodeProperties.md) +- [SimilarityResult](type-aliases/SimilarityResult.md) -``` -concept Movie extends GraphNode { - @vector_index("summary", 1536, "COSINE") - o Double[] embedding optional - @embedding - o String summary optional - @label("IN_GENRE") - --> Genre[] genres optional -} -``` +## Variables -TypeScript code: +- [ROOT\_MODEL](variables/ROOT_MODEL.md) +- [ROOT\_NAMESPACE](variables/ROOT_NAMESPACE.md) -```typescript - await graphModel.mergeNode(transaction, `${NS}.Movie`, {identifier: 'Brazil', summary: 'The film centres on Sam Lowry, a low-ranking bureaucrat trying to find a woman who appears in his dreams while he is working in a mind-numbing job and living in a small apartment, set in a dystopian world in which there is an over-reliance on poorly maintained (and rather whimsical) machines'} ); - - await graphModel.mergeNode(transaction, `${NS}.Genre`, {identifier: 'Comedy'} ); - - await graphModel.mergeRelationship(transaction, `${NS}.Movie`, 'Brazil', `${NS}.Genre`, 'Comedy', 'genres' ); - - await graphModel.mergeNode(transaction, `${NS}.Director`, {identifier: 'Terry Gilliam'} ); - await graphModel.mergeRelationship(transaction, `${NS}.Director`, 'Terry Gilliam', `${NS}.Movie`, 'Brazil', 'directed' ); - - await graphModel.mergeNode(transaction, `${NS}.Actor`, {identifier: 'Jonathan Pryce'} ); - await graphModel.mergeRelationship(transaction, `${NS}.Actor`, 'Jonathan Pryce', `${NS}.Movie`, 'Brazil', 'actedIn' ); - - const search = 'Working in a boring job and looking for love.'; - const results = await graphModel.similarityQuery(`${NS}.Movie`, 'embedding', search, 3); -``` +## Functions -Runtime result: - -```json -[ - { - identifier: 'Brazil', - content: 'The film centres on Sam Lowry, a low-ranking bureaucrat trying to find a woman who appears in his dreams while he is working in a mind-numbing job and living in a small apartment, set in a dystopian world in which there is an over-reliance on poorly maintained (and rather whimsical) machines', - score: 0.901830792427063 - } -] -``` - -## Environment Variables - -### GraphDB - -- NEO4J_URL: the NEO4J URL. E.g. `neo4j+s://.databases.neo4j.io` if you are using AuraDB. -- NEO4J_PASS: your neo4j password. -- NEO4J_USER: defaults to `neo4j` - -### Text Embeddings -- OPENAI_API_KEY: the OpenAI API key. If not set embeddings are not computed and written to the agreement graph and similarity search, natural language to Cypher generation ("chat with data") is not possible. +- [getObjectChecksum](functions/getObjectChecksum.md) +- [getOpenAiEmbedding](functions/getOpenAiEmbedding.md) +- [getTextChecksum](functions/getTextChecksum.md) +- [textToCypher](functions/textToCypher.md) diff --git a/docs/classes/GraphModel.md b/docs/classes/GraphModel.md index 2b00449..2d6a684 100644 --- a/docs/classes/GraphModel.md +++ b/docs/classes/GraphModel.md @@ -2,7 +2,7 @@ *** -[@accordproject/concerto-graph](../globals.md) / GraphModel +[@accordproject/concerto-graph](../README.md) / GraphModel # Class: GraphModel @@ -31,7 +31,7 @@ Creates a new instance of GraphModel #### Source -[graphmodel.ts:252](https://github.com/accordproject/lab-concerto-graph/blob/cefc9be4fd1dac498d9d3b8abf33d069293dcc53/src/graphmodel.ts#L252) +[graphmodel.ts:252](https://github.com/accordproject/lab-concerto-graph/blob/0563543f1fdc8f8f027cd4b4eb91d11b07eff3b4/src/graphmodel.ts#L252) ## Properties @@ -65,7 +65,7 @@ the query results #### Source -[graphmodel.ts:662](https://github.com/accordproject/lab-concerto-graph/blob/cefc9be4fd1dac498d9d3b8abf33d069293dcc53/src/graphmodel.ts#L662) +[graphmodel.ts:662](https://github.com/accordproject/lab-concerto-graph/blob/0563543f1fdc8f8f027cd4b4eb91d11b07eff3b4/src/graphmodel.ts#L662) *** @@ -87,7 +87,7 @@ Closes a database context. #### Source -[graphmodel.ts:295](https://github.com/accordproject/lab-concerto-graph/blob/cefc9be4fd1dac498d9d3b8abf33d069293dcc53/src/graphmodel.ts#L295) +[graphmodel.ts:295](https://github.com/accordproject/lab-concerto-graph/blob/0563543f1fdc8f8f027cd4b4eb91d11b07eff3b4/src/graphmodel.ts#L295) *** @@ -103,7 +103,7 @@ Connects to Neo4J #### Source -[graphmodel.ts:266](https://github.com/accordproject/lab-concerto-graph/blob/cefc9be4fd1dac498d9d3b8abf33d069293dcc53/src/graphmodel.ts#L266) +[graphmodel.ts:266](https://github.com/accordproject/lab-concerto-graph/blob/0563543f1fdc8f8f027cd4b4eb91d11b07eff3b4/src/graphmodel.ts#L266) *** @@ -119,7 +119,7 @@ Create Neo4J constraints for the model #### Source -[graphmodel.ts:410](https://github.com/accordproject/lab-concerto-graph/blob/cefc9be4fd1dac498d9d3b8abf33d069293dcc53/src/graphmodel.ts#L410) +[graphmodel.ts:410](https://github.com/accordproject/lab-concerto-graph/blob/0563543f1fdc8f8f027cd4b4eb91d11b07eff3b4/src/graphmodel.ts#L410) *** @@ -133,7 +133,7 @@ Create Neo4J constraints for the model #### Source -[graphmodel.ts:447](https://github.com/accordproject/lab-concerto-graph/blob/cefc9be4fd1dac498d9d3b8abf33d069293dcc53/src/graphmodel.ts#L447) +[graphmodel.ts:447](https://github.com/accordproject/lab-concerto-graph/blob/0563543f1fdc8f8f027cd4b4eb91d11b07eff3b4/src/graphmodel.ts#L447) *** @@ -149,7 +149,7 @@ Create vector indexes for the model #### Source -[graphmodel.ts:427](https://github.com/accordproject/lab-concerto-graph/blob/cefc9be4fd1dac498d9d3b8abf33d069293dcc53/src/graphmodel.ts#L427) +[graphmodel.ts:427](https://github.com/accordproject/lab-concerto-graph/blob/0563543f1fdc8f8f027cd4b4eb91d11b07eff3b4/src/graphmodel.ts#L427) *** @@ -165,7 +165,7 @@ Delete all nodes/edges in the graph #### Source -[graphmodel.ts:469](https://github.com/accordproject/lab-concerto-graph/blob/cefc9be4fd1dac498d9d3b8abf33d069293dcc53/src/graphmodel.ts#L469) +[graphmodel.ts:469](https://github.com/accordproject/lab-concerto-graph/blob/0563543f1fdc8f8f027cd4b4eb91d11b07eff3b4/src/graphmodel.ts#L469) *** @@ -181,7 +181,7 @@ Drop all Neo4J indexes for the model. #### Source -[graphmodel.ts:382](https://github.com/accordproject/lab-concerto-graph/blob/cefc9be4fd1dac498d9d3b8abf33d069293dcc53/src/graphmodel.ts#L382) +[graphmodel.ts:382](https://github.com/accordproject/lab-concerto-graph/blob/0563543f1fdc8f8f027cd4b4eb91d11b07eff3b4/src/graphmodel.ts#L382) *** @@ -207,7 +207,7 @@ the items #### Source -[graphmodel.ts:693](https://github.com/accordproject/lab-concerto-graph/blob/cefc9be4fd1dac498d9d3b8abf33d069293dcc53/src/graphmodel.ts#L693) +[graphmodel.ts:693](https://github.com/accordproject/lab-concerto-graph/blob/0563543f1fdc8f8f027cd4b4eb91d11b07eff3b4/src/graphmodel.ts#L693) *** @@ -236,7 +236,7 @@ the graph node #### Source -[graphmodel.ts:543](https://github.com/accordproject/lab-concerto-graph/blob/cefc9be4fd1dac498d9d3b8abf33d069293dcc53/src/graphmodel.ts#L543) +[graphmodel.ts:543](https://github.com/accordproject/lab-concerto-graph/blob/0563543f1fdc8f8f027cd4b4eb91d11b07eff3b4/src/graphmodel.ts#L543) *** @@ -265,7 +265,7 @@ the source node #### Source -[graphmodel.ts:569](https://github.com/accordproject/lab-concerto-graph/blob/cefc9be4fd1dac498d9d3b8abf33d069293dcc53/src/graphmodel.ts#L569) +[graphmodel.ts:569](https://github.com/accordproject/lab-concerto-graph/blob/0563543f1fdc8f8f027cd4b4eb91d11b07eff3b4/src/graphmodel.ts#L569) *** @@ -290,7 +290,7 @@ a promise to a Context for the database. #### Source -[graphmodel.ts:283](https://github.com/accordproject/lab-concerto-graph/blob/cefc9be4fd1dac498d9d3b8abf33d069293dcc53/src/graphmodel.ts#L283) +[graphmodel.ts:283](https://github.com/accordproject/lab-concerto-graph/blob/0563543f1fdc8f8f027cd4b4eb91d11b07eff3b4/src/graphmodel.ts#L283) *** @@ -316,7 +316,7 @@ the query results #### Source -[graphmodel.ts:516](https://github.com/accordproject/lab-concerto-graph/blob/cefc9be4fd1dac498d9d3b8abf33d069293dcc53/src/graphmodel.ts#L516) +[graphmodel.ts:516](https://github.com/accordproject/lab-concerto-graph/blob/0563543f1fdc8f8f027cd4b4eb91d11b07eff3b4/src/graphmodel.ts#L516) *** @@ -343,7 +343,7 @@ an array of similar nodes, up to the count limit #### Source -[graphmodel.ts:628](https://github.com/accordproject/lab-concerto-graph/blob/cefc9be4fd1dac498d9d3b8abf33d069293dcc53/src/graphmodel.ts#L628) +[graphmodel.ts:628](https://github.com/accordproject/lab-concerto-graph/blob/0563543f1fdc8f8f027cd4b4eb91d11b07eff3b4/src/graphmodel.ts#L628) *** @@ -368,7 +368,7 @@ Performs a similarity search on nodes with text content #### Source -[graphmodel.ts:485](https://github.com/accordproject/lab-concerto-graph/blob/cefc9be4fd1dac498d9d3b8abf33d069293dcc53/src/graphmodel.ts#L485) +[graphmodel.ts:485](https://github.com/accordproject/lab-concerto-graph/blob/0563543f1fdc8f8f027cd4b4eb91d11b07eff3b4/src/graphmodel.ts#L485) *** @@ -392,4 +392,4 @@ the Cypher query #### Source -[graphmodel.ts:651](https://github.com/accordproject/lab-concerto-graph/blob/cefc9be4fd1dac498d9d3b8abf33d069293dcc53/src/graphmodel.ts#L651) +[graphmodel.ts:651](https://github.com/accordproject/lab-concerto-graph/blob/0563543f1fdc8f8f027cd4b4eb91d11b07eff3b4/src/graphmodel.ts#L651) diff --git a/docs/functions/getObjectChecksum.md b/docs/functions/getObjectChecksum.md index ebdce6c..4441a6b 100644 --- a/docs/functions/getObjectChecksum.md +++ b/docs/functions/getObjectChecksum.md @@ -2,7 +2,7 @@ *** -[@accordproject/concerto-graph](../globals.md) / getObjectChecksum +[@accordproject/concerto-graph](../README.md) / getObjectChecksum # Function: getObjectChecksum() @@ -24,4 +24,4 @@ the identifier as a string ## Source -[graphmodel.ts:165](https://github.com/accordproject/lab-concerto-graph/blob/cefc9be4fd1dac498d9d3b8abf33d069293dcc53/src/graphmodel.ts#L165) +[graphmodel.ts:165](https://github.com/accordproject/lab-concerto-graph/blob/0563543f1fdc8f8f027cd4b4eb91d11b07eff3b4/src/graphmodel.ts#L165) diff --git a/docs/functions/getOpenAiEmbedding.md b/docs/functions/getOpenAiEmbedding.md index 1ed5f49..acadc58 100644 --- a/docs/functions/getOpenAiEmbedding.md +++ b/docs/functions/getOpenAiEmbedding.md @@ -2,7 +2,7 @@ *** -[@accordproject/concerto-graph](../globals.md) / getOpenAiEmbedding +[@accordproject/concerto-graph](../README.md) / getOpenAiEmbedding # Function: getOpenAiEmbedding() @@ -25,4 +25,4 @@ a promise to an array of numbers ## Source -[graphmodel.ts:53](https://github.com/accordproject/lab-concerto-graph/blob/cefc9be4fd1dac498d9d3b8abf33d069293dcc53/src/graphmodel.ts#L53) +[graphmodel.ts:53](https://github.com/accordproject/lab-concerto-graph/blob/0563543f1fdc8f8f027cd4b4eb91d11b07eff3b4/src/graphmodel.ts#L53) diff --git a/docs/functions/getTextChecksum.md b/docs/functions/getTextChecksum.md index dfcf5f9..f499e42 100644 --- a/docs/functions/getTextChecksum.md +++ b/docs/functions/getTextChecksum.md @@ -2,7 +2,7 @@ *** -[@accordproject/concerto-graph](../globals.md) / getTextChecksum +[@accordproject/concerto-graph](../README.md) / getTextChecksum # Function: getTextChecksum() @@ -24,4 +24,4 @@ the checksum ## Source -[graphmodel.ts:178](https://github.com/accordproject/lab-concerto-graph/blob/cefc9be4fd1dac498d9d3b8abf33d069293dcc53/src/graphmodel.ts#L178) +[graphmodel.ts:178](https://github.com/accordproject/lab-concerto-graph/blob/0563543f1fdc8f8f027cd4b4eb91d11b07eff3b4/src/graphmodel.ts#L178) diff --git a/docs/functions/textToCypher.md b/docs/functions/textToCypher.md index 5c84e16..2cb687e 100644 --- a/docs/functions/textToCypher.md +++ b/docs/functions/textToCypher.md @@ -2,7 +2,7 @@ *** -[@accordproject/concerto-graph](../globals.md) / textToCypher +[@accordproject/concerto-graph](../README.md) / textToCypher # Function: textToCypher() @@ -26,4 +26,4 @@ a promise to the Cypher query or null ## Source -[graphmodel.ts:70](https://github.com/accordproject/lab-concerto-graph/blob/cefc9be4fd1dac498d9d3b8abf33d069293dcc53/src/graphmodel.ts#L70) +[graphmodel.ts:70](https://github.com/accordproject/lab-concerto-graph/blob/0563543f1fdc8f8f027cd4b4eb91d11b07eff3b4/src/graphmodel.ts#L70) diff --git a/docs/globals.md b/docs/globals.md deleted file mode 100644 index 76ae5c5..0000000 --- a/docs/globals.md +++ /dev/null @@ -1,28 +0,0 @@ -[**@accordproject/concerto-graph**](README.md) • **Docs** - -*** - -# @accordproject/concerto-graph - -## Classes - -- [GraphModel](classes/GraphModel.md) - -## Type Aliases - -- [Context](type-aliases/Context.md) -- [GraphModelOptions](type-aliases/GraphModelOptions.md) -- [GraphNodeProperties](type-aliases/GraphNodeProperties.md) -- [SimilarityResult](type-aliases/SimilarityResult.md) - -## Variables - -- [ROOT\_MODEL](variables/ROOT_MODEL.md) -- [ROOT\_NAMESPACE](variables/ROOT_NAMESPACE.md) - -## Functions - -- [getObjectChecksum](functions/getObjectChecksum.md) -- [getOpenAiEmbedding](functions/getOpenAiEmbedding.md) -- [getTextChecksum](functions/getTextChecksum.md) -- [textToCypher](functions/textToCypher.md) diff --git a/docs/type-aliases/Context.md b/docs/type-aliases/Context.md index 874e6c1..7f24269 100644 --- a/docs/type-aliases/Context.md +++ b/docs/type-aliases/Context.md @@ -2,7 +2,7 @@ *** -[@accordproject/concerto-graph](../globals.md) / Context +[@accordproject/concerto-graph](../README.md) / Context # Type alias: Context @@ -18,4 +18,4 @@ Runtime context ## Source -[graphmodel.ts:25](https://github.com/accordproject/lab-concerto-graph/blob/cefc9be4fd1dac498d9d3b8abf33d069293dcc53/src/graphmodel.ts#L25) +[graphmodel.ts:25](https://github.com/accordproject/lab-concerto-graph/blob/0563543f1fdc8f8f027cd4b4eb91d11b07eff3b4/src/graphmodel.ts#L25) diff --git a/docs/type-aliases/GraphModelOptions.md b/docs/type-aliases/GraphModelOptions.md index 6884fb3..22eb99e 100644 --- a/docs/type-aliases/GraphModelOptions.md +++ b/docs/type-aliases/GraphModelOptions.md @@ -2,7 +2,7 @@ *** -[@accordproject/concerto-graph](../globals.md) / GraphModelOptions +[@accordproject/concerto-graph](../README.md) / GraphModelOptions # Type alias: GraphModelOptions @@ -38,4 +38,4 @@ Graph model options, used to configure Concerto Graph ## Source -[graphmodel.ts:208](https://github.com/accordproject/lab-concerto-graph/blob/cefc9be4fd1dac498d9d3b8abf33d069293dcc53/src/graphmodel.ts#L208) +[graphmodel.ts:208](https://github.com/accordproject/lab-concerto-graph/blob/0563543f1fdc8f8f027cd4b4eb91d11b07eff3b4/src/graphmodel.ts#L208) diff --git a/docs/type-aliases/GraphNodeProperties.md b/docs/type-aliases/GraphNodeProperties.md index d5b6160..de1cea8 100644 --- a/docs/type-aliases/GraphNodeProperties.md +++ b/docs/type-aliases/GraphNodeProperties.md @@ -2,7 +2,7 @@ *** -[@accordproject/concerto-graph](../globals.md) / GraphNodeProperties +[@accordproject/concerto-graph](../README.md) / GraphNodeProperties # Type alias: GraphNodeProperties @@ -12,4 +12,4 @@ The properties allowed on graph nodes ## Source -[graphmodel.ts:190](https://github.com/accordproject/lab-concerto-graph/blob/cefc9be4fd1dac498d9d3b8abf33d069293dcc53/src/graphmodel.ts#L190) +[graphmodel.ts:190](https://github.com/accordproject/lab-concerto-graph/blob/0563543f1fdc8f8f027cd4b4eb91d11b07eff3b4/src/graphmodel.ts#L190) diff --git a/docs/type-aliases/SimilarityResult.md b/docs/type-aliases/SimilarityResult.md index 51aec3c..6e22e98 100644 --- a/docs/type-aliases/SimilarityResult.md +++ b/docs/type-aliases/SimilarityResult.md @@ -2,7 +2,7 @@ *** -[@accordproject/concerto-graph](../globals.md) / SimilarityResult +[@accordproject/concerto-graph](../README.md) / SimilarityResult # Type alias: SimilarityResult @@ -26,4 +26,4 @@ Result of a vector similarity search ## Source -[graphmodel.ts:41](https://github.com/accordproject/lab-concerto-graph/blob/cefc9be4fd1dac498d9d3b8abf33d069293dcc53/src/graphmodel.ts#L41) +[graphmodel.ts:41](https://github.com/accordproject/lab-concerto-graph/blob/0563543f1fdc8f8f027cd4b4eb91d11b07eff3b4/src/graphmodel.ts#L41) diff --git a/docs/variables/ROOT_MODEL.md b/docs/variables/ROOT_MODEL.md index d85210d..af51b57 100644 --- a/docs/variables/ROOT_MODEL.md +++ b/docs/variables/ROOT_MODEL.md @@ -2,7 +2,7 @@ *** -[@accordproject/concerto-graph](../globals.md) / ROOT\_MODEL +[@accordproject/concerto-graph](../README.md) / ROOT\_MODEL # Variable: ROOT\_MODEL @@ -12,4 +12,4 @@ The concerto graph model, defines internal nodes ## Source -[graphmodel.ts:225](https://github.com/accordproject/lab-concerto-graph/blob/cefc9be4fd1dac498d9d3b8abf33d069293dcc53/src/graphmodel.ts#L225) +[graphmodel.ts:225](https://github.com/accordproject/lab-concerto-graph/blob/0563543f1fdc8f8f027cd4b4eb91d11b07eff3b4/src/graphmodel.ts#L225) diff --git a/docs/variables/ROOT_NAMESPACE.md b/docs/variables/ROOT_NAMESPACE.md index 7ebb8c4..818de4b 100644 --- a/docs/variables/ROOT_NAMESPACE.md +++ b/docs/variables/ROOT_NAMESPACE.md @@ -2,7 +2,7 @@ *** -[@accordproject/concerto-graph](../globals.md) / ROOT\_NAMESPACE +[@accordproject/concerto-graph](../README.md) / ROOT\_NAMESPACE # Variable: ROOT\_NAMESPACE @@ -12,4 +12,4 @@ The concerto graph namespaces, used for internal nodes ## Source -[graphmodel.ts:220](https://github.com/accordproject/lab-concerto-graph/blob/cefc9be4fd1dac498d9d3b8abf33d069293dcc53/src/graphmodel.ts#L220) +[graphmodel.ts:220](https://github.com/accordproject/lab-concerto-graph/blob/0563543f1fdc8f8f027cd4b4eb91d11b07eff3b4/src/graphmodel.ts#L220) diff --git a/typedoc.json b/typedoc.json index f5c36b2..adb5da6 100644 --- a/typedoc.json +++ b/typedoc.json @@ -9,6 +9,7 @@ "parametersFormat": "table", "enumMembersFormat": "list", "typeDeclarationFormat": "list", - "indexFormat": "list" + "indexFormat": "list", + "readme": "none" } \ No newline at end of file