def clarify(self, keywords):
        """
        Asks the user to specify a certain criteria if it is too broad.
        """

        # if the necessary fields do not exist, then throw an exception
        if 'clarify_cat' not in keywords or 'clarify_list' not in keywords:
            raise NLGException('Not enough information in keywords')

        # the first clause gets the user's attention
        stat1 = SPhraseSpec(
            'Hey ' + random.choice([
                random.choice([self.tone_str('adjectives') + ' ', '']) +
                self.tone_str('names'), ''
            ]), '')
        # the second clause acknowledges that a specification was given
        stat2 = SPhraseSpec(
            'I', 'know', 'you wanted a type of %s' % (keywords['clarify_cat']))
        # the third clause asks the user to provide a more narrow scope
        stat3 = SPhraseSpec()
        stat3.setCuePhrase('but please specify if')
        stat3.setVerb('meant')
        stat3.setSubject('you')
        uniques = ''
        for unique in keywords['clarify_list']:
            if unique == keywords['clarify_list'][0]:
                uniques += unique
            elif unique == keywords['clarify_list'][-1]:
                uniques += ', or ' + unique
            else:
                uniques += ', ' + unique
        stat3.setPostmodifier(uniques)

        # create the final utterance out of all the parts
        clarification = TextSpec()
        clarification.addSpec(stat1)
        clarification.addSpec(stat2)
        clarification.addSpec(stat3)
        clarification.setListConjunct(',')

        return self.clean_str(REALISER.realiseDocument(clarification).strip())
    def unknown(self):
        """
        Returns an utterance that tells the user the last input was not
        understood.
        """

        output = SPhraseSpec()
        output.setSubject('I')
        output.setComplement('you')
        output.setTense(Tense.PAST)

        choice = random.randint(1, 3)
        if choice == 1:
            output.setVerb('understand')
            output.setComplement('what you')
            output.setNegated(gateway.jvm.java.lang.Boolean.TRUE)
            output.setPostmodifier('just said')
        elif choice == 2:
            output.setInterrogative(InterrogativeType.WHAT)
            output.setVerb('do')
            output.setPostmodifier('say')
        elif choice == 3:
            output.setTense(Tense.PRESENT)
            output.setSubject('please rephrase')
            output.setComplement('what you')
            output.setPostmodifier('just said')

        return self.clean_str(REALISER.realiseDocument(output).strip())
    def unknown(self):
        """
        Returns an utterance that tells the user the last input was not
        understood.
        """

        output = SPhraseSpec()
        output.setSubject('I')
        output.setComplement('you')
        output.setTense(Tense.PAST)

        choice = random.randint(1, 3)
        if choice == 1:
            output.setVerb('understand')
            output.setComplement('what you')
            output.setNegated(gateway.jvm.java.lang.Boolean.TRUE)
            output.setPostmodifier('just said')
        elif choice == 2:
            output.setInterrogative(InterrogativeType.WHAT)
            output.setVerb('do')
            output.setPostmodifier('say')
        elif choice == 3:
            output.setTense(Tense.PRESENT)
            output.setSubject('please rephrase')
            output.setComplement('what you')
            output.setPostmodifier('just said')

        return REALISER.realiseDocument(output).strip()
    def clarify(self, keywords):
        """
        Asks the user to specify a certain criteria if it is too broad.
        """

        # if the necessary fields do not exist, then throw an exception
        if 'clarify_cat' not in keywords or 'clarify_list' not in keywords:
            raise NLGException('Not enough information in keywords')

        # the first clause gets the user's attention
        stat1 = SPhraseSpec('Hey ' + random.choice([random.choice([self.tone_str('adjectives') + ' ', '']) + self.tone_str('names'), '']), '')
        # the second clause acknowledges that a specification was given
        stat2 = SPhraseSpec('I', 'know', 'you wanted a type of %s' % (keywords['clarify_cat']))
        # the third clause asks the user to provide a more narrow scope
        stat3 = SPhraseSpec()
        stat3.setCuePhrase('but please specify if')
        stat3.setVerb('meant')
        stat3.setSubject('you')
        uniques = ''
        for unique in keywords['clarify_list']:
            if unique == keywords['clarify_list'][0]:
                uniques += unique
            elif unique == keywords['clarify_list'][-1]:
                uniques += ', or ' + unique
            else:
                uniques += ', ' + unique
        stat3.setPostmodifier(uniques)

        # create the final utterance out of all the parts
        clarification = TextSpec()
        clarification.addSpec(stat1)
        clarification.addSpec(stat2)
        clarification.addSpec(stat3)
        clarification.setListConjunct(',')

        return REALISER.realiseDocument(clarification).strip()