jade.semantics.kbase

Interface KBase

All Known Subinterfaces:

FilterKBase

All Known Implementing Classes:

ArrayListKBaseImpl, CasaKB, FilterKBaseImpl, KBaseDecorator

public interface KBase

This interface defines belief base API. The belief base is a central component of the JSA framework, which mainly maintains the internal state of semantic agents, in terms of their explicit symbolic representation of their environment. This symbolic representation is expressed by FIPA-SL formulas.

This interface provides three main kinds of operations:

• update the semantic agent's internal state, by asserting or retracting formulas,
• retrieve beliefs from the semantic agent's internal state, by querying formulas or IREs (Identifying Referential Expressions),
• notify changes of the semantic agent's internal state, by installing or uninstalling observers.

The KBase interface was primarily intended to be implemented by third parties. However, as it is quite a difficult and very technical task, the JSA frameworks provides a default filter-based implementation, which offers a good trade-off between efficiency and expressiveness.

Since:

JSA 1.0

Version:

0.9, 0.9

Author:

Vincent Pautret - France Telecom

Method Summary

Modifier and Type	Method and Description
void	addClosedPredicate(Formula pattern) Define a new pattern of closed formula.
void	addObserver(Observer o) Add an observer to this KBase instance (at the end of the list of observers).
void	assertFormula(Formula formula) Assert a fact (given as a FIPA-SL formula) believed by the owning agent into this belief base.
Term	eval(Term expression)
Term	getAgentName() Get the name of the agent (given as a FIPA-SL term representing his AID) owning this KBase instance.
KBase	getWrappingKBase() The KBase mechanism follows the decoration design pattern.
boolean	isClosed(Formula pattern, QueryResult values) Return true if a given pattern of formula is closed on a given domain of values, and false otherwise.
QueryResult	query(Formula formula) Check wether a given fact is believed by the agent owning this KBase instance.
QueryResult	query(Formula formula, ArrayList reasons)
ListOfTerm	queryRef(IdentifyingExpression expression) Return a list of objects satisfying a given logical description (expressed as an Identifying Referential Expression), which is believed by the agent owning this KBase instance.
Term	queryRef(IdentifyingExpression expression, ArrayList falsityReasons)
Term	queryRefSingleTerm(IdentifyingExpression expression) Return a term satisfying a given logical description (expressed as an Identifying Referential Expression), which is believed by the agent owning this KBase instance.
void	removeClosedPredicate(Finder finder) Remove the definition of a pattern of closed formula.
void	removeFormula(Finder finder) Deprecated. use retractFormula(Formula) instead.
void	removeObserver(Finder finder) Remove from this KBase instance all the observers that are identified by a given finder.
void	removeObserver(Observer obs) Remove from this KBase instance a given observer.
void	retractFormula(Formula formula) Retract a fact from the belief base.
void	setAgentName(Term agent) Modify the agent (given as a FIPA-SL term representing his AID) the beliefs stored in this KBase instance belong to.
void	setWrappingKBase(KBase kbase) Set the most enclosing KBase.
ArrayList	toStrings() Return the list of believed facts contained in this KBase instance as an array of String.
void	updateObservers(Formula formula) Update the status of all observers concerned by a given formula.

Method Detail

getWrappingKBase

KBase getWrappingKBase()

The KBase mechanism follows the decoration design pattern. A KBase instance can be enclosed within another KBase instance, wich can in turn be enclosed in another KBase instance and so on.

Returns:

the most enclosing KBase instance, on which to proceed assertion and query operations. This also corresonds to the KBase instance attached to the semantic capabilities of an agent. It can be this KBase object.

setWrappingKBase

void setWrappingKBase(KBase kbase)

Set the most enclosing KBase. This method is for internal use only, and should never be called by the JSA programmer.

Parameters:

the - most enclosing KBase instance, on which to proceed assertion and query operations. This also corresonds to the KBase instance attached to the semantic capabilities of an agent. It can be this KBase object.

getAgentName

Term getAgentName()

Get the name of the agent (given as a FIPA-SL term representing his AID) owning this KBase instance. Note that a KBase instance stores the beliefs of only one agent, even if these beliefs may concern beliefs on other agents.

Returns:

the name of the agent believing the facts stored in this KBase object.

setAgentName

void setAgentName(Term agent)

Modify the agent (given as a FIPA-SL term representing his AID) the beliefs stored in this KBase instance belong to.

Parameters:

agent - the agent the beliefs of this KBase object belong to.

assertFormula

void assertFormula(Formula formula)

Assert a fact (given as a FIPA-SL formula) believed by the owning agent into this belief base. It is very important to understand that asserted facts are necessarily facts believed by the agent, independently from their truth value in the real world.

Asserting p actually means that (B ??myself p) is true (where ??myself represents the agent owning the belief base), while asserting (not p) actually means that (B ??myself (not p)) is true.
Consequently, asserting p is equivalent to asserting (B ??myself p) (because in the underlying formal model - see the FIPA SL specifications, (B i (B i p)) is logically equivalent to (B i p)).

The KBase implementations are expected to maintain a logically consistent set of beliefs. When a fact, which is inconsistent with an already stored belief, is asserted, the implementation must explicitly choose an option that ensures the global consistency (for example, keeping the most recently asserted fact in the base).

Depending on their sophistication, the KBase implementations may not be able to actually store all asserted facts. In this case, the reasoning (or "intellectual") capabilities of the owning agent will simply be considered as limited, which is a very common case. In any case, the asserted facts that cannot be dealt with should not create any inconsistency in the belief base. For example, the implementation provided with the JSA framework does not deal with uncertainty modal operators, so that asserting (U ??myself p) has no effect.

Parameters:

formula - the formula to assert.

retractFormula

void retractFormula(Formula formula)

Retract a fact from the belief base. Actually, this method should be a shortcut for the assertion of (not (B ??myself formula)). In other words, retracting p actually means that (not (B ??myself p)) is true.

The retracted formula may include meta-references, in this case, all stored facts that match the input formula are retracted. For example, if (age john 25), (age mary 25) and (age peter 20) are believed by the agent, retracting (age ??person 25) will result in dropping the first two facts from the belief base.

Parameters:

formula - the formula to retract.

removeFormula

@Deprecated
void removeFormula(Finder finder)

Deprecated. use retractFormula(Formula) instead.

Removes from the belief base all formulas recognized by a given finder.

Parameters:

finder - a finder to identify formulas to remove from the belief base.

queryRef

ListOfTerm queryRef(IdentifyingExpression expression)

Return a list of objects satisfying a given logical description (expressed as an Identifying Referential Expression), which is believed by the agent owning this KBase instance.

Formally, given an IRE ??IRE quantified by either iota or any, the method returns a list of one single term ??o such that: (B ??myself (= ??IRE ??o)) is true.
Given an IRE ??IRE quantified by either all or some, the method returns a set ??set of zero or more terms (given as a ListOfTerm object) such that: (B ??myself (= ??IRE ??set)) is true.

If no term satisfy the previous formulas, then the method returns null (which actually means that either the agent does not know the specified objects or there is no such objects).

Parameters:

expression - an Identifying Referential Expression describing one or more objects to find within the agent's beliefs.

Returns:

a list of terms containing all the objects satisfying the input IRE according the the agent's beliefs, or null if there is no such object in the agent's beliefs.

queryRefSingleTerm

Term queryRefSingleTerm(IdentifyingExpression expression)

Return a term satisfying a given logical description (expressed as an Identifying Referential Expression), which is believed by the agent owning this KBase instance.

Formally, given an IRE ??IRE quantified by either iota or any, the method returns either a term ??o such that (B ??myself (= ??IRE ??o)) is true or null if (not (exists ?o (B ??myself (= ??IRE ?o)))).
Given an IRE ??IRE quantified by either all or some, the method returns a set ??set of zero or more terms such that: (B ??myself (= ??IRE ??set)) is true.

Parameters:

expression - an Identifying Referential Expression describing one or more objects to find within the agent's beliefs.

Returns:

a term satisfying the input IRE according the the agent's beliefs, or null if there is no such object according to the agent's beliefs.

See Also:

queryRef(IdentifyingExpression)

queryRef

Term queryRef(IdentifyingExpression expression,
              ArrayList falsityReasons)

query

QueryResult query(Formula formula)

Check wether a given fact is believed by the agent owning this KBase instance.

If the fact is not believed by the agent, the method returns null.

The queried fact may include meta-references. In this case, the method returns all bindings of these meta-references, for which the corresponding instantiated fact is believed by the agent. These bindings are returned using a QueryResult instance. If the queried fact include no meta-reference and is actually believed, the returned QueryResult object is an empty list equal to QueryResult.KNOWN.

For example, if (age john 25), (age mary 25) and (age peter 20) are believed by the agent, querying for (age ??who 25) will return a list of two MatchResult objects containing respectively the bindings (??who=john) and (??who=mary).

Parameters:

formula - a fact to retrieve in the belief base (may include meta- references)

Returns:

null (QueryResult.UNKNOWN) if the agent doesn't know about this fact,
an empty QueryResult (QueryResult.KNOWN) if the queried fact is believed by the agent and includes no meta-reference,

a not empty QueryResult, if the queried fact is believed by the agent and includes meta-reference.

query

QueryResult query(Formula formula,
                  ArrayList reasons)

eval

Term eval(Term expression)

Parameters:

expression - a term to evaluate

Returns:

a term, which is logically equal to the given expression

addObserver

void addObserver(Observer o)

Add an observer to this KBase instance (at the end of the list of observers). Observers make it possible to monitor the truth value of a given fact and trigger some action each time this fact becomes believed by the agent owning the belief base. For example, this mechanism is used by the SIPs that manage the interpretation of the SUBSCRIBE or REQUEST-WHEN* messages.

Parameters:

o - the observer to add

removeObserver

void removeObserver(Finder finder)

Remove from this KBase instance all the observers that are identified by a given finder.

Parameters:

finder - a finder that identifies the observers to remove.

removeObserver

void removeObserver(Observer obs)

Remove from this KBase instance a given observer.

Parameters:

obs - the observer to remove.

updateObservers

void updateObservers(Formula formula)

Update the status of all observers concerned by a given formula. Updating an observer means requesting it to check whether its monitored formula has become believed by the agent owning the belief base (and trigger the associated action if needed). An observer is concerned by a formula if asserting this formula may change the truth value of its monitored formula.

A null formula forces all observers to be updated.

This operation is needed to trigger the observers even when an assertion does not lead to an actual assertion in the belief base.

Parameters:

formula - a formula that has just been asserted.

See Also:

Observer

isClosed

boolean isClosed(Formula pattern,
                 QueryResult values)

Return true if a given pattern of formula is closed on a given domain of values, and false otherwise.

A pattern of formula is considered as closed on a set of values if and only if:

• its instantiation with each value is believed by the agent owning the belief base,
• the agent believes that its instantiation with any other value is necessarily false.

Closed formulas are particularly useful to deal with the iota and the all IRE quantifiers. For example, the belief (B ??myself (= (all ?x (age ?x 25)) (set john mary))) is actually stored in the belief base as the formula (age ??x 25) closed on the domain (john, mary). This makes it possible to retrieve implicit entailments such as (B ??myself (not (age peter 25))) (without the closed formula mechanism, one could only entail (not (B ??myself (age peter 25)))).

Consequent to the formal definition of the underlying logical model for agents' beliefs, all patterns of mental attitudes of the agent owning the belief base (that is all patterns logically equivalent to a formula of the form (B ??myself ??PHI)) are necessarily closed. In other words, agents know exactly what are all their mental attitudes, they cannot not be aware of them.

Closed formulas can be defined and undefined using the addClosedPredicate(Formula) and removeClosedPredicate(Finder) methods.

Parameters:

pattern - the pattern of closed formula to check.

values - the domain of values to used to check the closure. null value does not check the values, only the registration of the pattern as a closed formula.

Returns:

true if the pattern is closed on the given domain, false otherwise.

addClosedPredicate

void addClosedPredicate(Formula pattern)

Define a new pattern of closed formula.

If there is no instance of this pattern, which is already believed by the agent owning the belief base, this is equivalent to assert (= (all ??VARS ??pattern) (set)), where ??VAR is a sequence of all meta-references occurring in the pattern.

Parameters:

pattern - the pattern of formula to declare as closed.

See Also:

isClosed(Formula, QueryResult)

removeClosedPredicate

void removeClosedPredicate(Finder finder)

Remove the definition of a pattern of closed formula. This pattern is identified by a Finder object.

Parameters:

finder - a finder identifying the pattern of closed formula to remove.

See Also:

isClosed(Formula, QueryResult)

toStrings

ArrayList toStrings()

Return the list of believed facts contained in this KBase instance as an array of String. It is useful for debugging purposes.

Returns:

the list of believed facts in this belief base.