{"id":16815356,"url":"https://github.com/dalelane/extract-relationships","last_synced_at":"2025-04-11T01:53:26.219Z","repository":{"id":26348424,"uuid":"29797325","full_name":"dalelane/extract-relationships","owner":"dalelane","description":"A client library for the Watson Relationship Extraction service on IBM Bluemix.","archived":false,"fork":false,"pushed_at":"2015-03-13T12:57:53.000Z","size":256,"stargazers_count":5,"open_issues_count":0,"forks_count":7,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-24T23:23:56.551Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://dalelane.co.uk/blog/?p=3272","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dalelane.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-01-25T00:35:51.000Z","updated_at":"2023-05-22T04:30:20.000Z","dependencies_parsed_at":"2022-08-28T00:36:19.026Z","dependency_job_id":null,"html_url":"https://github.com/dalelane/extract-relationships","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dalelane%2Fextract-relationships","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dalelane%2Fextract-relationships/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dalelane%2Fextract-relationships/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dalelane%2Fextract-relationships/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dalelane","download_url":"https://codeload.github.com/dalelane/extract-relationships/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247818986,"owners_count":21001385,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-13T10:34:07.337Z","updated_at":"2025-04-11T01:53:26.200Z","avatar_url":"https://github.com/dalelane.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# extract-relationships\n\n## What is this for?\n\nIdentifying things mentioned in unstructured text. \n\nYou provide text, and it'll extract: \n\n - the entities mentioned in that text\n - the different mentions of each entity\n - the relationships between the entities contained in the text\n\n## Contents\n- [How this works](#how-this-works)\n- [Usage](#usage)\n    - [Install](#install)\n    - [Basic](#basic)\n    - [Demo](#demo)\n- [Options](#options)\n- [Interpreting the output](#interpreting-the-output)\n- [Authentication](#authentication)\n    - [Bluemix](#bluemix)\n    - [Running outside Bluemix](#running-outside-bluemix)\n- [Usage and trademarks](#usage-and-trademarks)\n\n\n## How this works\n\nThis package is a thin library around the [IBM Watson Relationship Extraction](http://www.ibm.com/smarterplanet/us/en/ibmwatson/developercloud/relationship-extraction.html) service on [IBM Bluemix](http://bluemix.net/). All the natural language processing stuff is happening in that hosted service. This package just formats the request for you, and parses and cleans up the response to make it easier to consume in a node.js / Javascript application. \n\nThere is nothing here that you couldn't get by driving those APIs yourself, but hopefully using this thin wrapper will be quicker and easier. \n\nThis means:\n- You **don't** need to run your application on Bluemix - the APIs are accessible over the web\n- You **do** need an Internet connection - this package sends HTTP requests to an API hosted on IBM's Bluemix platform. It is not doing the NLP locally. \n- You **do** need to sign up for an account with Bluemix first - the API it's using is authenticated, but this is quick and relatively painless\n\n## Usage\n\n### Install\n```\nnpm install extract-relationships --save\n```\n\n### Basic \nUsing default options \n[examples/bluemix.js](https://github.com/dalelane/extract-relationships/tree/master/examples/bluemix.js)\n```\nvar watson = require('extract-relationships');\nwatson.extract(yourtext, function (err, response) {\n    if (err) {\n        return console.error(err);\n    }\n\n    // output is contained in response\n});\n```\n\nUsing custom options\n[examples/detailed.js](https://github.com/dalelane/extract-relationships/tree/master/examples/detailed.js)\n```\nvar watson = require('extract-relationships');\nwatson.extract(yourtext, options, function (err, response) {\n    if (err) {\n        return console.error(err);\n    }\n\n    // output is contained in response\n});\n```\n\n### Demo\nGrab the contents of a news story, and use the Watson Relationship Extraction service to pick out the names of the people mentioned in that news story.\n\nFull working source in [examples/newspeople.js](https://github.com/dalelane/extract-relationships/tree/master/examples/newspeople.js)\n\nSnippet here:\n```\nasync.waterfall([\n    // \n    // download the contents of a BBC news story\n    function (callback) {\n        request(bbcNewsStoryUrl, callback); \n    }, \n\n    //\n    // get the text contents out of the story\n    function (response, body, callback) {\n        var contents = unfluff(body).text;\n\n        callback(null, contents);\n    }, \n\n    //\n    // submit the story text to the Relationship Extraction service\n    function (text, callback) {\n        watson.extract(text, bluemixoptions, callback);\n    },\n\n    //\n    // get the names of people from the response\n    function (storyinfo, callback) {\n        // filter the responses to pick out the people entities\n        var people = storyinfo.entities.filter(function (entity) {            \n            return entity.type === 'PERSON' \u0026\u0026 \n                   entity.level === 'NAM' \u0026\u0026 \n                   // add a threshold so we ignore entities \n                   //  with a very low confidence score\n                   entity.score \u003e= 0.5;\n        });\n\n        // get the names out of those responses\n        var names = people.map(function (person) {\n\n            var personnames = [];\n\n            // Look through each mention of this person\n            //   as some of the mentions could refer to their occupation or job title\n            //   and some of the mentions will be 'he', 'she', 'they', etc.\n            // We're just interested in the names\n            person.mentions.forEach(function (mention) {\n                if (mention.role === 'PERSON' \u0026\u0026 mention.mtype === 'NAM') {\n                    personnames.push(mention.text);\n                }\n            });\n\n            return personnames;\n        });\n\n        callback(null, names);\n    }\n], function(err, result){\n    // print out the names we found\n    console.log(result);\n});\n```\n\n## Options\n```\n{\n    // If true, entities found in the text are returned, with the \n    //   mentions of each entity.\n    // Defaults to true if not provided.\n    includeMentions : true, \n\n    // If true, relationships found between entities in the text\n    //   are returned, with the mention of each relationship.\n    // Defaults to false if not provided.\n    includeRelationships : false, \n\n    // If true, the locations of items found in the text are \n    //   returned, as offsets into the input text.\n    // Defaults to false if not provided\n    includeLocations : false,\n\n    // If true, the confidence scores in each item returned by the\n    //   API are included in the response (as doubles between \n    //   0.0 and 1.0). \n    // Defaults to true if not provided\n    includeScores : true,\n\n    // if true, unique IDs will be included with objects returned\n    //  in the response\n    includeIds : false,\n\n\n\n    // Language \u0026 corpus profile to use to process text\n    //   'ie-en-news' is based on English news sources\n    //   'ie-es-news' is based on Spanish news sources\n    // see http://www.ibm.com/smarterplanet/us/en/ibmwatson/developercloud/apis/#!/relationship-extraction/extract\n    // Defaults to 'ie-en-news'\n    dataset : 'ie-en-news', \n\n\n    // URL to send requests to, and the username and password\n    //  This is not required if running in Bluemix\n    //  see 'Authentication' below\n    api : {\n        url : 'https://...',\n        user : 'your-relationship-extraction-username',\n        pass : 'your-relationship-extraction-password'\n    }\n}\n```\n\n## Interpreting the output\n\nThe official documentation can be found in the [Watson Developer Cloud Documentation](http://www.ibm.com/smarterplanet/us/en/ibmwatson/developercloud/doc/sireapi) and is the definitive guide to the meaning of the values returned by the API. \n\nAn example of what the output looks like can be found [here](https://gist.github.com/dalelane/223500f2eae708fe34ef) and in the comments in each of the [examples](https://github.com/dalelane/extract-relationships/tree/master/examples). \n\nThe structure of the output returned by this client library is outlined here:\n\n```\n{\n    //\n    // a list of the entities found \n    //\n\n    entities : [\n        // see http://www.ibm.com/smarterplanet/us/en/ibmwatson/developercloud/doc/sireapi/#outputEntities\n        //  for the meaning of these values\n        {\n            // type of the entity\n            //   see http://www.ibm.com/smarterplanet/us/en/ibmwatson/developercloud/doc/sireapi/#outputEntityTypes \n            type : 'ORGANIZATION',\n            subtype : 'EDUCATIONAL',\n\n            // class of the entity\n            //  SPC means a reference to a specific thing\n            //  NEG means a negated reference to a specific thing\n            //  GEN means a generic reference, such as a metaphorical reference\n            class : 'SPC',\n\n            // level of the entity\n            //  e.g. NAM for a named entity as a proper name, PRO for pronoun, etc.\n            level : 'NAM', \n\n            // confidence level in the accuracy of this entity annotation\n            score : 0.9819,\n\n            // a list of each of the mentions of this entity\n            mentions : [\n                // see http://www.ibm.com/smarterplanet/us/en/ibmwatson/developercloud/doc/sireapi/#outputMentions\n                //  for the meaning of these values\n                {\n                    // type and class of the mention\n                    mtype : 'NAM', \n                    class : 'SPC',\n\n                    // context-sensitive role of the entity within this mention\n                    role : 'ORGANIZATION',\n\n                    // the covered text for this mention\n                    text : 'University', \n\n                    // location of the mention in the provided text\n                    location : {\n                        // character offsets for the start and end of the mention text\n                        begin : 123, end : 133, \n\n                        // character offsets for the head word of a phrase in the mention\n                        head-begin : 123, head-end : 133\n                    },\n\n                    scores : {\n                        // confidence level for the accuracy of this mention\n                        score : 0.8271,\n                        // confidence level for the accuracy that this refers\n                        //  to the other mentions \n                        coref : 0.9912\n                    }\n                }\n            ]\n        }\n    ],\n\n\n    //\n    // a list of the relationships found between entities\n    //\n\n    relationships : [\n        // see http://www.ibm.com/smarterplanet/us/en/ibmwatson/developercloud/doc/sireapi/#outputRelations\n        //  for the meaning of these values\n        {\n            // type of the relationship\n            //  see http://www.ibm.com/smarterplanet/us/en/ibmwatson/developercloud/doc/sireapi/#outputRelationTypes\n            //   for the list of possible types\n            type : 'educatedAt', \n\n            // the two entities that this is a relationship between\n            entities : {\n                // the entity that this is a relationship from\n                one : { \n                    type : 'PERSON', \n                    class : 'SPC', \n                    level : 'NAM'\n                },\n\n                // the entity that this is a relationship to\n                two : {\n                    type : 'ORGANIZATION', \n                    subtype : 'EDUCATIONAL', \n                    class : 'SPC', \n                    level : 'NAM'\n                }\n            },\n\n            // the instances of this relationship found in the text\n            //  see http://www.ibm.com/smarterplanet/us/en/ibmwatson/developercloud/doc/sireapi/#outputRelations\n            //  for the meaning of these values\n            mentions : [\n                // each instance of the relationship\n                {\n                    // specificity of the relation mention \n                    //  e.g. SPECIFIC, NEG etc.\n                    class : 'SPECIFIC', \n\n                    // nature of the relation mention\n                    modality : 'ASSERTED', \n\n                    // time of the relation mention relative to the publication of the text\n                    //  e.g. PAST, PRESENT, FUTURE\n                    tense : 'UNSPECIFIED', \n\n                    // confidence level for the accuracy of the relation\n                    score : 0.7231, \n\n                    // the mention of the entity that this is a relationship from\n                    one : {\n                        // type and class of the mention\n                        mtype : 'NAM', \n                        class : 'SPC',\n\n                        // type of the entity \n                        etype : 'PERSON', \n\n                        // context-sensitive role of the entity within this mention\n                        role : 'PERSON',\n\n                        // the covered text for this mention\n                        text : 'John Smith', \n\n                        // location of the mention in the provided text\n                        location : {\n                            // character offsets for the start and end of the mention text\n                            begin : 223, end : 233, \n\n                            // character offsets for the head word of a phrase in the mention\n                            head-begin : 223, head-end : 233\n                        }\n                    },\n\n                    // the mention of the entity that this is a relationship from\n                    two : {\n                        // type and class of the mention\n                        mtype : 'NAM', \n                        class : 'SPC',\n\n                        // type of the entity \n                        etype : 'ORGANIZATION', \n\n                        // context-sensitive role of the entity within this mention\n                        role : 'ORGANIZATION',\n\n                        // the covered text for this mention\n                        text : 'University', \n\n                        // location of the mention in the provided text\n                        location : {\n                            // character offsets for the start and end of the mention text\n                            begin : 123, end : 133, \n\n                            // character offsets for the head word of a phrase in the mention\n                            head-begin : 123, head-end : 133\n                        }\n                    }\n                }\n            ]\n        }\n    ]\n}\n```\n\n## Authentication\n\nThe package submits HTTP requests to an API which requires a username and password. \n\n### Bluemix \n\nIf you are running your code on the Bluemix platform:\n\n 1. Add the \"Watson Relationship Extraction\" service and bind it to your app\n 2. That's it - the client library will pick up the credentials needed for the API from the Bluemix environment\n\n### Running outside Bluemix\n\nIf you are running your code anywhere else, outside of Bluemix, you'll first need to provision yourself a Relationship Extraction service. \n\nThere is a [more detailed walkthrough on the blog post](http://dalelane.co.uk/blog/?p=3272) about this, but in short:\n\n 1. Go to [bluemix.net](http://bluemix.net)\n 2. Sign in with your IBM ID (creating one if you've not already got one)\n 3. Go to the Bluemix Dashboard\n 4. Create an app\n 5. Create a web app\n 6. Choose SDK for Node.js\n 7. Give it a name \n 8. 'Add a service' and choose \"Watson Relationship Extraction\"\n 9. From the App view, click on the 'Show Credentials' link for the bound Relationship Extraction service\n 10. Copy the 'url', 'username' and 'password' values shown\n\nCommand-line equivalents of these steps can be found in the [Watson Developer Cloud documentation](http://www.ibm.com/smarterplanet/us/en/ibmwatson/developercloud/doc/getting_started/#usage-1). \n\nOnce created, you can get the url, username and password using:\n```\ncf env \u003capplication-name\u003e\n```\n\n## Usage and trademarks\n\nBluemix and Watson come from, and are trademarks of, IBM. This client library is not provided or supported by IBM. It aims to make it easier to use a Bluemix API, but makes no claims over what you can or cannot do with that API. It is your responsibility to conform to any terms and conditions for usage of the API that are part of signing up for an account on Bluemix.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdalelane%2Fextract-relationships","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdalelane%2Fextract-relationships","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdalelane%2Fextract-relationships/lists"}