D3web: How-To Create a Session

Running a d3web Session #

Once, you have created a KnowledgeBase instance (for example, by Loading a knowledge base), you can run a problem-solving session. During a problem-solving session you enter Question-Value pairs (Fact) and the system will derive appropriate solutions for the entered facts.

Creating a new Session#

Sessions are represented by instances of Session. Use the SessionFactory to quickly create a new Session instance for the KnowledgeBase instance:

Session session = SessionFactory.createSession(knowledgeBase);

Retrieve the next reasonable question#

The Interview, which can be accessed from the session by using the interview problem solver (PSMethod), determines the next question to be presented to the user. More precisely, a FormStrategy computes the next From that is presented in the dialog. A Form consists of a title and a list of active questions:

Interview interview = session.getSessionObject(session.getPSMethodInstance(PSMethodInterview.class));
Form form = interview.nextForm();
List<Question> activeQuestions = form.getActiveQuestions();

To retrieve a single question contained in the Form you may use the NextUnansweredQuestionFormStrategy. This can be explicitly set by

interview.setFormStrategy(new NextUnansweredQuestionFormStrategy());

Entering Facts to the Session#

Next, we subsequently add facts to the session. When already having the appropriate instances of Question and Value, respectively, we are able to simply set the value by

Question question = kb.getManager().searchQuestion("QuestionName");
ChoiceValue value = new ChoiceValue("ChoiceName");

Fact fact = FactFactory.createFact(session, question, value, 
           PSMethodUserSelected.getInstance(),
           PSMethodUserSelected.getInstance());
session.getBlackboard().addValueFact(fact);

Please note, that we create a new Fact having the question and value. Additionally, the source of the fact is the User (PSMethodUserSelected) and the corresponding problem-solver is also the user. In different scenarios, the source may be the instance of a Rule used in the context of a particular PSMethod instance.

Check the Derived Solutions#

We retrieve the list of derived solutions together with their state by iterating over all solutions in the knowledge base and by asking for a diagnosis Rating that is different from UNCLEAR. This way, we return solution instances with states ESTABLISHED, SUGGESTED, and EXCLUDED.

for (Solution solution : knowledgeBase.getSolutions()) {
    Rating state = session.getBlackboard().getState(solution);
    if (!state.hasState(Rating.State.UNCLEAR))
	out.println("  " + solution + " (" + state + ")");
}

Sometimes it is easier (and a bit faster) to just get all solutions in a particular state, e.g. all established solutions:

out.println("All established solutions:");
for (Solution solution : session.getBlackboard().getSolutions(Rating.State.ESTABLISHED)) {
    out.println(solution);
}

Revisit the entered Facts#

You can simply retrieve all entered facts by the following code block:

for (ProtocolEntry entry : session.getProtocol().getProtocolHistory()) {
    out.println(entry);
}

Please note, that the session manages a Protocol, where entered findings (question/value tuples) are stored in a chronological order.

The Complete Example#

Note: The current version of the full example should be found in d3web-GlobalTests as the class de.d3web.demos.RunningACase.

public void runDemoCase() throws IOException {
	KnowledgeBase knowledgeBase = buildKnowledgeBase();

	PrintStream out = System.out;
	// Create a case (problem-solving session and set
	// all specified question/answers
	out.println("+++ Setting values +++");
	Session session = SessionFactory.createSession(knowledgeBase);

	// set: pregnant = yes
	Fact fact1 = FactFactory.createUserEnteredFact(
			pregnant, yes);
	session.getBlackboard().addValueFact(fact1);
	out.println(fact1);
	// set: weight = 80
	Fact fact2 = FactFactory.createUserEnteredFact(
			weight, new NumValue(80));
	session.getBlackboard().addValueFact(fact2);
	out.println(fact2);

	// Print all solutions with a state != UNCLEAR
	out.println("+++ Solutions +++");
	for (Solution solution : knowledgeBase.getManager().getSolutions()) {
		Rating state = session.getBlackboard().getRating(solution);
		if (!state.hasState(Rating.State.UNCLEAR)) {
			out.println("  " + solution + " (" + state + ")");
		}
	}

	// Show all entered findings
	out.println("+++ Entered Questions +++");
	for (ProtocolEntry entry : session.getProtocol().getProtocolHistory()) {
		out.println("  " + entry);
	}
}


private KnowledgeBase buildKnowledgeBase() throws IOException {
	// root {container}
	// - demoQuestion {containers}
	// - pregnant [oc]
	// - weight [num]

	// Solution: dangerousMood
	InitPluginManager.init();
	KnowledgeBase kb = KnowledgeBaseUtils.createKnowledgeBase();
	QASet root = kb.getRootQASet();

	demoQuestions = new QContainer(root, "demoQuestions");
	pregnant = new QuestionOC(demoQuestions, "pregnant", "yes", "no");
	yes = new ChoiceValue(KnowledgeBaseUtils.findChoice(pregnant, "yes"));
	weight = new QuestionNum(demoQuestions, "weight");

	dangerousMood = new Solution(kb.getRootSolution(), "dangerousMood");

	// Define the init questionnaire
	kb.setInitQuestions(Arrays.asList(demoQuestions));

	// Define the magic rule: preganant=yes AND weight > 70 => dangerousMood
	// (P7)
	List<Condition> terms = new ArrayList<Condition>();
	terms.add(new CondEqual(pregnant, yes));
	terms.add(new CondNumGreater(weight, (double) 70));
	RuleFactory.createHeuristicPSRule(dangerousMood, Score.P7, new CondAnd(terms));

	return kb;
}