cn5apinet - ConceptNet5 API Library

• Download CNAPINetDemo source project - 730.4 KB
• Download cn5apinet_demo (binaries) - 332.17 KB

(Note: cn5apinet.dll has Newtonsoft.Json.dll (Json40r5) dependency for json handling.) Download and Install yEd Graph Editor so you can display the .graphml files the demo creates. For the Demo to run, Please make certain you have Microsoft .Net 4 Runtime . Open CNAPINetDemo\CNAPINetDemo\CNAPINetDemo.sln after exctracting the source

Introduction

UPDATE 2015-11-27: Please note that as of November 11th 2015, ConceptNet5 API is now version 5.4.2 upgraded from previous 5.x releases; "ConceptNet 5.4 presents the same API as 5.x. Because we host only one version of the knowledge base at a time, all URLs with /5.1/ now redirect to the equivalent /5.2/ URLs." - Official Doc. To get the source project to work properly, just update the url lines in the public class Common file replacing "5.1" with "5.4"(or current release of ConceptNet). 

ConceptNet¹ is a commonsense knowledgebase, composed mainly from the Open Mind Project, written and maintained by Massachusetts Institute of Technology (MIT). This library is something I threw together to communicate with ConceptNet 5 (beta at the time of this writing). It uses a Representational state transfer (REST) API, like ConceptNet 4, but has a different structure and design. ConceptNet 5 "is a graph; To be precise, it's a hypergraph, meaning it has edges about edges. Each statement in ConceptNet has justfications pointing to it, explaining where it comes from and how reliable the information seems to be."

The .NET C# ConceptNet API Class Library (cn5apinet)

cn5apinet can provide an interface to ConceptNet 5 REST API. Use the API to receive back Lists and objects of a ConceptNet 5 hypergraph. What is new from cnapinet (from ConceptNet4) is a new namespace for auto-creating GraphML xml files. This name space is quickly explained below. The demo displays how to assemble the cn5apinet.GraphML.GraphMLFile

ConceptNet 5.1 API has three methods to retrieve its edge data: Lookup, Search, and Association. Like the ConceptNet documentation states, "Lookup is for when you know the URI of an object in ConceptNet, and want to see a list of edges that include it. Search finds a list of edges that match certain criteria. Association is for finding concepts similar to a particular concept or a list of concepts." cn5apinet now has three functions to perform these methods:

public Lookup Lookup(LANG language, String concept_name)

public Search Search(LANG language, String rel, String start, String end, String
text, int limit)

public Association Associations(LANG language, String word, String filter, int limit,
bool multipleterms, int weight)

cn5apinet Namespace

(click to make larger)

The Demo

[Please make certain you have Microsoft .Net 4 Runtime]

The demo app has three to represent the three different query methods:"Lookup", "Search/Test Commonsense" and "Association". "Lookup" performs a basic query with one word or phrase; after the initial lookup, it will populate the dropdownbox with relationships that were found in the query. You may then press the 'lookup relationship' button to just display the graph with that selected relationship.

Next is the "Search/Test Commonsense" tab which allows you to query the ConceptNet 5 (CN5) hypergraph's knowledge and results in an answer of "Yes", "No", "Maybe"; it basically tells you if it thinks your statement is true, false, or perhaps true. Pressing the 'Ask' button doesn't really perform the Search function but is just in the demo to display a practical use of CN5 and was left in from the original demo. This is based off the scores in the CN5 hypergraph [0 <= is false, 1 = maybe, 2 > is true]. For example, a score of 42.39 has a higher confidence score than a score of 3.87. Pressing the 'Search and open Graph!' button actually performs a CN5.1 Search method.

The third tab "Association", performs an Association lookup which is for finding concepts similar to a particular concept or a list of concepts.

Download and Install yEd Graph Editor so you can display the .graphml files the demo creates. This tab was mainly based off of ConceptNet5's Web API documentation. Sometimes, screenshots are the best to explain things so please take a look below.

cn5apinet Implementation

1. Add cn5apinet.dll to your project 'References' via Solution Explorer. (For cn5apinet.dll v1.6.x.x make sure that Newtonsoft.Json.dll (Json40r5) resides in the same folder as cn5apinet.dll) .
2. Add 'using cn5apinet;', etc to your source code to use the namespace.
3. Create the main API engine with 'ConceptNetAPI CNClient = new ConceptNetAPI();', etc.
4. Below are the methods in ConceptNetAPI

Performing the three lookups:

/// <summary>
/// Lookup is for when you know the URI of an object in ConceptNet, and want to see a list of edges that include it.
/// </summary>
/// <param name="language" />language
/// <param name="concept_name" />Expects entirely built suffix for url. For example, '/contributor/omcs/rspeer', 'toast?offset=5&limit=5', etc.
/// <returns>Lookup object</returns>
public Lookup Lookup(LANG language, String concept_name)......

/// <summary>
/// Search finds a list of edges that match certain criteria.
/// </summary>
/// <param name="language" />language
/// <param name="rel" />relationship
/// <param name="start" />start
/// <param name="end" />end
/// <param name="text" />text=word: matches any of startLemmas, endLemmas, or relLemmas.
/// <param name="limit" />limit=n: change the number of results from the default of 50.
/// <returns>Search object</returns>
public Search Search(LANG language, String rel, String start, String end, String text, int limit)...

/// <summary>
/// Association is for finding concepts similar to a particular concept or a list of concepts.
/// </summary>
/// <param name="language" />language
/// <param name="word" />If you wish multi, start with use ',' between each word. ie: 'toast,cereal,juice,egg'.
/// <param name="filter" />filter=URI: return only results that start with the given URI. For example, filter=/c/en returns results in English.
/// <param name="limit" />limit=n: change the number of results from the default of 10.
/// <param name="multipleterms" />If true, then expecting a list like 'toast,cereal,juice,egg' etc.
/// <returns>Association object</returns>
public Association Associations(LANG language, String word, String filter, int limit, bool multipleterms, int weight)...

Creating the .graphml

List<cn5apinet.GraphML.GraphMLNode> nodeList = new List<cn5apinet.GraphML.GraphMLNode>();
List<cn5apinet.GraphML.GraphMLEdge> edgeList = new List<cn5apinet.GraphML.GraphMLEdge>();
List<edge_arg> edge_argList = new List<edge_arg>();

#region GraphML
if (cBoxGraphML.Checked)
{
    //let's look at the edges, nodes and create a graphML

    //Create the seed node...
    GraphMLNode node0 = new GraphMLNode(0, new Geometry(30.0, 50.0, 1, 1));//customize the node...
    node0.Text = tbGetKey.Text.Trim();
    node0.FillColor = "#00FF00";//Green
    //Add this node to list
    nodeList.Add(node0);
    int i = 1;
    if ((List<Object>)raw_concept.incoming_edges != null)
    {
        foreach (object o in (List<Object>)raw_concept.incoming_edges)
        {
            string s = o.GetType().Name;
            if (o.GetType().Name == "edge_arg")
            {
                //need Json to convert o;
                Dictionary<String, String> startDict = new Dictionary<string, string>();
                String[] spiltstart = Convert.ToString(((edge_arg)o).start).Split(',');
                // [0] = "/assertion//relation/AtLocation/"
                // [1] = "/concept/en/book/"
                // [2] = "/concept/en/shelf/"

                //= Convert.ToString(((edge_arg)o).key);
                //Create the connecting Edge...
                //Add this node
                GraphMLNode nodeX = new GraphMLNode(i, new Geometry(30.0, 50.0, 1, 0));
                string[] nodetext = spiltstart[2].Split(seperatorsForwardSlash, StringSplitOptions.RemoveEmptyEntries);
                nodeX.Text = nodetext[nodetext.Length - 1];
                nodeList.Add(nodeX);
                edge_argList.Add((edge_arg)o);//add to edge_argList

                //Add this edge to list
                string[] edgetext = spiltstart[0].Split(seperatorsForwardSlash, StringSplitOptions.RemoveEmptyEntries);
                GraphMLEdge edge0 = new GraphMLEdge(i, node0.NodeID, nodeX.NodeID, edgetext[edgetext.Length - 1] + " " + Convert.ToString(((edge_arg)o).score));
                edgeList.Add(edge0);
                i = i + 1;
            }
        }
    }
    //Re-arrange the nodes
    int numofNodes = nodeList.Count;
    int g = 1;
    //Draw the nodes around first node[0] in a circle
    double radius = 100.0;
    if (numofNodes > 10)
        radius = (nodeList[0].Geometry.height * 0.45) * numofNodes / 2;

    for (double h = 0.0; h < 360.0; h += (360 / numofNodes))
    {
        if (g >= numofNodes)
            break;
        double angle = h * System.Math.PI / 180;
        if (cBoxQChildren.Checked == true && g < 4)
        {
            //push out the top 3 nodes, they should be returned by score in the json
            nodeList[g].Geometry.x = (int)(nodeList[0].Geometry.x + radius * System.Math.Cos(angle)) * 2;
            nodeList[g].Geometry.y = (int)(nodeList[0].Geometry.y + radius * System.Math.Sin(angle)) * 2;
        }
        else
        {
            nodeList[g].Geometry.x = (int)(nodeList[0].Geometry.y + radius * System.Math.Cos(angle));
            nodeList[g].Geometry.y = (int)(nodeList[0].Geometry.y + radius * System.Math.Sin(angle));
        }
        g = g + 1;
    }

    graphFile = new cn5apinet.GraphML.GraphMLFile(Application.StartupPath + "//" + node0.Text + ".graphml");
    graphFile.Create(nodeList, edgeList, Application.ProductName);

    System.Diagnostics.Process.Start(graphFile.FullPathLocation);
}
#endregion GraphML

Conclusion

ConceptNet REST API Continues to evolve and having a .Net interface is nice to explore ConceptNet with. It isn't the most efficient way to perform lookups [if you explore the ConceptNet5 website you can find alternative methods to perform queries (MongoDB 2.0 database and 24GB file of the json, etc)] but it is handy to code some proof of concept apps or just fiddling around in .Net learning about ConceptNet.

References

• The ConceptNet Web API, Massachusetts Institute of Technology [^]
• Newtonsoft.Json.dll, Json.NET Copyright (c) 2007 James Newton-King [^]
• Open Mind Common Sense Project [^]

Updates

• 12/17/11
  • Uploaded CNAPINetDemo v1.6.0.0 Microsoft Visual C# Express 2010 project files
  • Uploaded cn5apinet.dll v1.6.0.0 and necessary files. 
• 12/18/11
  • Uploaded CNAPINetDemo v1.6.0.0 Microsoft Visual C# Express 2010 project files with Json40r5 dll so manual download and reference add is no longer needed.
  • Misc article image tweaks.
• 06/20/12
  • Posted ConceptNet API 5.1 note that cn5apinet is broken; working on update.
• 06/28/12
  • Updated article to support ConceptNet API 5.1. Uploaded CNAPINetDemo v1.9.0.0. Uploaded cn5apinet.dll v1.9.0.0 and necessary files. 
• 03/28/14 
  • Added ConceptNet API upgrade note from 5.1 to 5.2 per email list and documentation.
  • Tested demo with new API version.