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.getInterviewManager().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

Fact fact = FactFactory.createFact(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();
	KnowledgeBaseManagement kbm = KnowledgeBaseManagement.createInstance();
	QASet root = kbm.getKnowledgeBase().getRootQASet();

	demoQuestions = kbm.createQContainer("demoQuestions", root);
	pregnant = kbm.createQuestionOC("pregnant", demoQuestions, new String[] { "yes",
			"no" });
	yes = new ChoiceValue(kbm.findChoice(pregnant, "yes"));
	weight = kbm.createQuestionNum("weight", "weight", demoQuestions);

	dangerousMood = kbm.createSolution("dangerousMood");
	
	// Define the init questionnaire
	kbm.getKnowledgeBase().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.valueOf(70)));
	RuleFactory.createHeuristicPSRule("r1", dangerousMood, Score.P7, new CondAnd(terms));
	
	return kbm.getKnowledgeBase();
}