retina-api-java-sdk - A Java Client for the Cortical.io Retina API
Cortical.io's Retina API allows the user to perform semantic operations on text. One can for example:
- measure the semantic similarity between two written entities
- create a semantic classifier based on positive and negative example texts
- extract keywords from a text
- divide a text into sub-sections corresponding to semantic changes
- extract terms from text based on part-of-speech tags
The meaning of terms and text is stored in a sparse binary representation that allows the user to apply logical operators to refine the semantic representation of a concept.
You can read more about the technology at the documentation page.
To access the API, you will need to register for an API key.
If you just need the JAR file, this can be downloaded directly from the Sonatype Central Repository directly or by adding this dependency to a Maven pom.xml:
<dependency> <groupId>io.cortical</groupId> <artifactId>retina-api-java-sdk</artifactId> <version>1.0.2</version> </dependency>
For non-Maven projects you need to use the
retina-api-java-sdk-1.0.1-jar-with-dependencies (e.g. when directly calling the java client).
If you want to build the jar, you will need to:
- Clone the Github repository
- Install Maven 3.x
- Navigate to the main directory (retina-api-java-sdk) and build the project by typing on the command line:
mvn clean install -DapiKey=YourAPIKey
- The jar file produced by the client api project (found in the target directory) can then be imported into any project.
- The client is compatible with Java version: 1.7 and above.
- It is compatible with all 2.x.x versions of cortical.io's API.
- To use the API you will need to obtain an API key.
retina-api-java-sdk offers two abstractions of the Cortical.io Retina API, a lightweight module that offers simplified access to the most common and useful API functions available and a full version module that gives the user complete control over various parameter settings and complete access to all API endpoints.
The LiteClient module is sufficient for most applications and offers the ability to quickly and easily compute keywords for a text, semantically compare two texts, retrieve similar terms, create category filters for semantic filtering and generate semantic fingerprints of a given text. To get started, create an instance of the lightweight client by passing your API key as follows:
// Create "lightweight" LiteClient instance LiteClient lite = new io.cortical.retina.client.LiteClient(your_api_key);
Once you've created a client instance, you can start using it to make calls to the Retina API. Here some examples, the last comment in each block shows a print of the last variable assigned:
The FullClient module provides complete access to the entire Retina API and allows for more flexibility in configuring request parameters than the LiteClient module. Some functionality included with the FullClient not available in the LiteClient are operations on expressions, images and bulk requests.
As with the LiteClient, the FullClient must be instantiated with a valid Cortical.io API key:
// Create FullClient instance FullClient fullClient = new FullClient(your_api_key);
Additional parameters can also be passed when creating a FullClient instance to specify the host address (in case you have access to your own Retina API service, for example by running your own AWS or Azure instance) and Retina name, so you can configure a specific Retina for subsequent calls.
// Create FullClient instance with explicit server address and Retina name FullClient fullClient = new FullClient("your_api_key", "http://api.cortical.io/rest/", "en_associative");
The semantic fingerprint is the basic unit within the Retina API. A text or a term can be resolved into a fingerprint using the API. Fingerprints can also be combined in expressions, and a number of methods expect input in our expression language. This is explained in more detail here.
Expressions are represented internally as json strings with reserved keys: term, text, and positions. In the Java client, this formatting is abstracted away, by letting the user work with Term and Text objects. The client offers a static helper class io.cortical.retina.model.ExpressionFactory which has convenience methods for creating Term and Text objects as well as methods (and, or, sub, and, xor) to assist in building expressions.
For instance, to create a Term object for the term brain you can use the static method term:
Term term = ExpressionFactory.term("brain");
And to AND two terms together you can use the ExpressionFactory.and static method. This method returns an Expression (an object of type ExpressionModel).
ExpressionModel andExpression = ExpressionFactory.and(ExpressionFactory.term("brain"), ExpressionFactory.term("cortex"));
Expression operators can take multiple input types. For instance, you can OR a Term object with a Text object. We can now get the most similar terms for such an expression:
ExpressionModel orExpression = ExpressionFactory.or(ExpressionFactory.term("brain"), ExpressionFactory.text("a region of the cerebral cortex")); List<Term> terms = fullClient.getSimilarTermsForExpression(orExpression);
(In reality the Expression operation is performed on the semantic fingerprints of the respective input types).
For further documentation about the Retina API and information about Cortical.io's 'Retina' technology please see our
Knowledge Base. Also the
src/test/java folder contains more examples of how to use the
If you have any questions or problems please visit our forum.
- Corrected POS tag values.
- Improved image handling.
- Initial release.
- Refactoring and migrating project from previous GitHub repo.