A Proposal For Openai Core Services

We need to store and retrieve arbitrary kind of data. But we can try to classify diffent types of content:

Although we have different datatypes to store and retrieve, i highly suggest to use one on-disk format to handle them all.

As the time changes, dataformats come and go. At the present,XML is the thing everyone wants to have. I recommend to use XML as our only and native dataformat. The main advance is to have a whole bunch of well tested tools to create, parse, validate and use XML datafiles.

For now we've used castor and i think its a easy to configure and very usefull API to achieve transparent persistence of Java objects. Castor can do a straight forward mapping between java and XML. To use Castor, one needs to define a mapping file that tells Castor how to store the Object.

This brings up one big disadvantage: One has to take care of the mappingfiles when a classfile changes. Because the compiler isnt aware of this external resource, no error is thrown at compiletime. Therefore its rather unsafe to do changes without crosscheck them with either manual- or (better) JUnit-tests.

Changing a mappingfile pushes us ahead to another problem: When the mapping changes, the on-disk XML-schema changes also! Objects that have been stored to disk cant be retrieved anymore with the 'new' version. How to solve this? I dont know... maybe you do? Though this isnt a big deal for now, we will stumble over this when the time comes for the second release.

Anyway, we need a persistence layer. To make things more flexible, we should aim to build a format independent interface. Even if we stuck to XML for now, we dont know what the future brings. A good design can save us lots of headache.

By the first thought about modules, one might think of extensions for the GUI. I would go one step beneath the GUI. What we really need is a modulesystem on the API/framework level. The GUI should be nothing more then a `builder` or (better term) `development environment` for a AI. So the API must be able to chain together different modules without the GUI! Tho the GUI can and will have its own modules.

Each part of the system will neede some settings at runtime.

We can classify those:

Both classes can be devided further into scopes:

Properties are in a close relation to the settings issue. But there is a difference: I considersettings to be values in a higher level in the API. Settings are used as (at least) module wide properties.

The 'properties' i'm talking about here are the values that are directly in the datamodel of a OpenAI module. They are the neurons, connections, NetworkIterators, weights that make together that what we can call a 'document'. So we got finally to the bottom layer of the system.

At API-level we dont need any special interface to change the values. They are stored as normal classmembers and accessed by (mostly) bean accessors (setXxxx/getXxxx).

However the GUI does need a component to both show and modify document properties. This is the (already implemented) PropertyEditor. Later in this paper you will read some details about both capabilitys and usability of this piece of software.

This stands in a close relation to persistence. The user and also the developer wants to be able to store related documents together in one file.

This is not as easy as it might seem at a first thought, because each module will bring in its own, personal format. Also modules can depend on other modules Therefore we can get a whole tree of documents for each module. The GUI complicates this topic even more because it needs to store settings of a module, also.

My suggestion to this topic is to have a modular projectfile. Its main feature would be the ability to store a tree of subprojects of arbitrary complexity. The API has to be smart enough to allow a single module (in stand alone mode or in a user application) to grab its parts out. This creates the possibility to build/train/maintain a project in the GUI and use it in a target application and avoids the reason separate GUI and API projectfiles.

As extension to the current implementation, i suggest a interface to mark classes that are persistence-able.

For a first implementation, the following approach could be sufficient:

interface PersistAble {


	/**
	 * Register a persistencehandler for this class.
	 */
	public  void registerPersistenceHandler(Persistence handler) throws PersistenceException;

	/** 
	 * Gets a new instance of this class from a persistent source 
	 * using the given url and the registered persistencehandler.
	 */
	public  PersistAble retrieve(URL url) throws PersistenceException;

	/**
	 * Gets a new instance of this class from a DOM Element using the registered
	 * persistencehandler.
	 */
	public  PersistAble instanceFromElement(Element xml) throws PersistenceException;

	/** 
	 * Serializes and stores this object to the given url
	 * using the registered persistencehandler.
	 */
	public void store(URL url) throws PersistenceException;


	/**
	 * Serializes this object to a DOM Element using the registered 
	 * persistencehandler.
	 */
	public Element toElement() throws PersistenceException;

}
			

This gives us some advantages compared to the current implementation. At the moment, a class called persistence is the center of the xml subsystem. It is able to store and retrieve objectinstances based on a castor mappingfile. A module can bring its own mappingfile with it and it needs to register it in the persistencehandler. This in turn loads and caches the mappingfile to gain speed and to save some typing whe none wants to store a object (the path to the mappingfile can be skipt). With the new implementation, a user/developer must not know about mappingfiles or even the persistencehandler. He simply calls (for example)

network.store("file://mynetwork.xml");
			

It is neccessary to call registerPersistenceHandler(...) to initialize the PersistenceAble->Persistence binding properly. A good place for doing this in a transparent way would be the module classloader (see later). The implementation of the register method has to take care of different serializer backends and the needed settings itself !

There are 2 methods i have not explained yet:

public  PersistenceAble instanceFromElement(Element xml) throws PersistenceException;
			

public Element toElement() throws PersistenceException;
			

A universal modulesubsystem will need a central repository to get new instances of each module. The framework must be able to load and recognize modules at runtime.

Well. First question of all: do we need a setting management that implements all of the different scopes and classes i defined in the overview section?

To be honest: I don't know it! Tell me about your opinion!

I'm proud to say: this is implemented and ready to use. Even though you should know of some in-depth details about the current propertysubsystem. I'm pretty sure you have some comments and suggestions regarding it. Review the following classdiagram to make you familiar with this subsystem:

						
						
<!-- Defines a selectionlist named 'Transferfunctions' with 3 elements -->

<selectionlist name="Transferfunctions">
	<entry name="" value="{NULL}"/>
	<entry name="Sigmoid" value="net.openai.ai.nn.transfer.SigmoidTransferFunction"/>
	<entry name="TanH" value="net.openai.ai.nn.transfer.TanhTransferFunction"/>
</selectionlist>
		
<!-- Propertydefinition for the class 'Layer' (refers to Transferfunctions) -->

<class name="net.openai.ai.nn.network.Layer">

	<property name="ID" get="getID"/>
	
	<property name="Name" get="getName" set="setName"> 
		<info>Name of this Layer</info>
	</property>
	
	<property name="Ready To Learn" get="readyToLearn"> 
		<info>Tells if the layer is ready to learn</info>
	</property>
	
	<property name="Learning rule" get="getLearningRule" set="setLearningRule" select="Learningrules" type="class"> 
		<info>Rule to use while learning</info>
	</property>
	
	<property name="Transferfunction" get="getTransferFunction" set="setTransferFunction" select="Transferfunctions" type="class"> 
		<info>Function to transfer the values to the next layer</info>
	</property>
	
	<property name="Inputfunction" get="getInputFunction" set="setInputFunction" select="Inputfunctions" type="class"> 
		<info>Function to summarize the weighted inputvalues</info>
	</property>
	
	<property name="Neurons" get="getSize">
		<info>Amount of neurons in this layer</info>
	</property>
	
</class>
						
						

interface PropertyProvider {

	/**
	 * Returns the properties for this class
	 */
	public PropertyList getProperties();

}
					

AIDesktop.displayProperties(Object yourobject);

We need some sort of directory to model a project and let the needed modules connect to it. Its almost certain that a project will hold more then one instance of a documenttype. This brings the need for a naming system within the tree/directory. Having the GUI in mind, i would suggest to use simple strings to put a name to each document (=node). That gives us a nice treestructure to display in (example) the left borderpane of the mainwindow ("explorer-like").

The biggest difficulty regarding projectfiles is the following question: "How to make a mappingfile with unknown complexity and unknown modules". Answer: I think there is no need for it! As you can read in the persistence section, each persisteable document has to know of its own mappingfile. To put things together to a bigger structure, we can use a ordinary DOM tree. When the system has to store a projectfile, it traverses each hooked ("mounted") module and asks for a DOM-Element holding the already serialized data and saves the resulting structure to disk. Lets twist: we want to retrieve a project. What we get is a DOM-Tree. The project system needs the ability to decompose the tree and to reconstruct the moduleinstances(!) with the unmarshalled documents. This will be a really tough part and involves a whole bunch of coreservices. However: things are cut into small, well defined peaces. Each module will be responsible for its own data. Failing of one module (i.E. versionconflict, missing module, missing mapping) cant destroy the whole project !

Lets review another demand of the definition: “ the API has to be smart enough to allow a single module (...) to grab its parts out. ”. No Problem! We have a project directory (aka DOM-Tree). The project-API will have a method to get a named document (=DOM element). The moduleclass can use the persistencehandler to turn this element to a new instance of the module (holding the unmarshalled document)! For convenience it might be handy to have a additional method to get the first (n'th) document of a certain type back from the projecttree.