A Ruby Wrapper for IBM® Personality Insights service.
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


Build Status Code Climate Test Coverage Issue Count Made with Love by Icalia Labs

Pythia is an open source ruby gem that acts as a wrapper for IBM Watson's Personality Insights service API.


Add this line to your application's Gemfile:

gem 'pythia'

And then execute:

$ bundle

Or install it yourself as:

$ gem install pythia



In order for Pythia to work correctly, it is important that you set up an IBM Bluemix account of your own and that your trial period hasn't ended (or, for that matter, that you've registered for a paid account)

First require pythia in your file:

require 'pythia'

Then add the following configuration block:

Pythia.configure do |config|
	config.username = SOME_USERNAME
	config.password = SOME_PASSWORD
	config.base_uri = "https://gateway.watsonplatform.net/personality-insights/api"

Note: The username and password are not your Bluemix credentials. These credentials are specific to the Personality Insights API and must be obtained from said section of Watson's Docs

Generating a Personality Insight Profile

The Personality Insights API is capable of generating a personality profile for the author of the input text it is given. According to the Personality Insights documentation, the service accepts up to 20 MB of input text, but it actually requires much less. The minimum necessary input is around 600 words, but it is recommended to use an input text of 1,200 or more words for more acurate profiling.

Input Format

The documentation specifies that for JSON input, the ContentListContainer object type should be used. Said object type looks like this:

  "contentItems": [
      "content": INPUT_TEXT,
      "id": "string",
      "created": 0,
      "updated": 0,
      "contenttype": "text/plain",
      "language": "ar",
      "parentid": "null",
      "reply": false,
      "forward": false

For more information on providing input for this service, check out the Personality Insights API Reference.

Using Pythia to generate a new Personality Insight Profile

Once you've constructed the ContentListContainer object, you can use the profile method of the Pythia::Insights class to generate a full profile of the input text's author.

@author_profile = Pythia::Insights.profile(content_list_container)

This method should return a Pythia::Profile object containing the following readable properties, which make up the profile:

  • Word Count: The number of words in the input text
  • Processed Language: The language that was detected in the text or specified in the request
  • Personality: A Pythia::Personality object that lists the Big 5 personality traits and how the input text scores in each of them
  • Needs: A Pythia::Needs object that contains needs characteristics as well as their score and percentile as calculated from the input text.
  • Values: A Pythia::Values object that contains values characteristics as well as their score and percentile as calculated from the input text.
  • Behavior: A Pythia::Behavior object that lists behavioral traits as detected in the input text
  • Consumption Preferences: A Pythia::ConsumptionPreferences object that lists the author's consumption preferences as detected in the input text.
  • Warnings: A Pythia::Warnings object that lists the warning_ids and respective warning messages that were returned from the request.

For a more comprehensive understading of the nature and meaning of the contents of these attributes, please read the API documentation for the Personality Insights service.

Since profile is a class method, there's no need to instantiate Pythia::Insights first.

**Note: Remember to convert the ContentListContainer object to JSON through obj.to_json before using it in the profile method. You must require 'json' for this to work.


After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.


Bug reports and pull requests are welcome on GitHub at https://github.com/icalialabs/pythia. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.


The gem is available as open source under the terms of the MIT License.