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, instantiated with the Session, 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 an interviewObject (a Question of a QContainer):

Form form = session.getInterview().nextForm();
InterviewObject interviewObject = form.getInterviewObject();

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

session.getInterview().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.createFact(pregnant, yes, PSMethodUserSelected
				.getInstance(), PSMethodUserSelected.getInstance());
	session.getBlackboard().addValueFact(fact1);
	out.println(fact1);
	// set: weight = 80
	Fact fact2 = FactFactory.createFact(weight, new NumValue(80), 
			PSMethodUserSelected.getInstance(), 
			PSMethodUserSelected.getInstance());
	session.getBlackboard().addValueFact(fact2);
	out.println(fact2);
	
	// Print all solutions with a state != UNCLEAR
	out.println("+++ Solutions +++");
	for (Solution solution : knowledgeBase.getSolutions()) {
		Rating state = session.getBlackboard().getState(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();

	QContainer demoQuestion = new QContainer(kb.getRootQASet(), "demoQuestions");
	QuestionYN pregnant = new QuestionYN(demoQuestion, "pregnant");

	Choice yes = pregnant.getAnswerChoiceYes();

	QuestionNum weight = new QuestionNum(demoQuestion, "weight");

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

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

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

	return kb;
}