Package: rxnoptgoaliteragent
Reaction Optimisation Goal Iteration (ROGI) AgentThe folder contains the source, resource, and Docker setup files for the Reaction Optimisation Goal Iteration (ROGI) Agent, following the suggestions on a template provide asTheWorldAvatar/JPS_BASE_LIB/python_derivation_agent/README.md.PurposeThe Reaction Optimisation Goal Iteration (ROGI) Agent is designed to perform iterations of reaction experiment as part of goal-driven reaction optimisation exercise. It operates based on concepts defined inOntoGoaland orchestratesDoE Agent,VapourtecSchedule Agent,Vapourtec Agent,HPLC Agent, andHPLCPostPro Agentto complete one iteration.Building the Docker imageRequirements:Example of configurations for the agent are provided inTheWorldAvatar/Agents/RxnOptGoalIterAgent/agent.goal.iter.env.examplefile. The knowledge graph endpoints used by this agent are specified usingSPARQL_QUERY_ENDPOINTandSPARQL_UPDATE_ENDPOINTfor triple store, andFILESERVER_URLfor the file server. The credentials for knowledge graph endpoints, i.e. triple store and file server, should be provided in the same file usingKG_USERNAME,KG_PASSWORD,FILE_SERVER_USERNAME,FILE_SERVER_PASSWORD. To avoid commit these information to git at deployment, developer may make a copy of this example file asagent.goal.iter.env. As*.enventry already exist in.gitignore, this new created file will be omitted. Any credentials encoded are safe. The OntoAgent:Service IRI of the agent is specified usingONTOAGENT_SERVICE_IRI. The periodically time interval to monitor asynchronous derivation is specified byDERIVATION_PERIODIC_TIMESCALE. One may also provideDERIVATION_INSTANCE_BASE_URLto be used by DerivationClient when creating derivations related instances.ONTOAGENT_OPERATION_HTTP_URLcan be used to specify the URL of the agent that listens the request for updating synchronous derivations, however, given the nature of the post processing Agent, this is NOT RECOMMENDED. Developers needs to ensure that this file is correctly updated before building the Docker Image.Once the requirements have been addressed, the Image can be build via docker container, one example of which is:(Linux)cd/your_absolute_path_to/TheWorldAvatar/Agents/RxnOptGoalIterAgent/
docker-compose-f"docker-compose.test.yml"up-d--buildOr, simply right clickdocker-compose.test.ymlfile and selectCompose Upoption in Visual Studio Code.Environment setupFor development and testing reasons, follow below instructions to get started.Virtual environment setupIt is highly recommended to installpyderivationagentpackages in avirtual environment (python>=3.8). The following steps can be taken to build a virtual environment:(Windows)$ python -m venv <venv_name>
$ <venv_name>\Scripts\activate.bat
(<venv_name>) $(Linux)$python3-mvenv<venv_name>
$source<venv_name>/bin/activate(<venv_name>)$The above commands will create and activate the virtual environment<venv_name>in the current directory.Package installationThe following command can be used to install all required packages.(Linux)(<venv_name>)$python-mpipinstall--upgradepip# Install all required packages, incl. pyderivationagent, pytest etc.# NOTE instead of the loosely constrained versions defined in the setup.py#   here packages in the requirements.txt with the pinned version are installed# This ensures the user getting a tested version of the agent# However, one can skip this line and execute the next command directly#   where pip will pick up the versions automatically(<venv_name>)$python-mpipinstall-rrequirements.txt# Install the agent package itself for development purpose# If the previous command executed, pip will skip all the "install_requires"#   as "Requirement already satisfied"(<venv_name>)$python-mpipinstall-e.[dev]Aspyderivationagentlibrary relies on thepy4jpspackage, Java 11 is required. For Windows, it is recommended to obtain OpenJDK 11 fromhereand follow theinstructions. For linux environment, one can install via:(Linux)$sudoaptupdate
$sudoaptinstallopenjdk-11-jdk-headlessHow to use itThe ROGI Agent is intended to use theasychronous modeof the Derivation Framework to detect changes in instantiated OntoGoal properties (e.g.goal,best resutl, andrestriction) to automatically request the design/schedule/execution/analyses of a reaction experiment instances in the KG. As the agent adopts thepyderivationagent, it also serves HTTP requests to handle synchronous derivations. However, it is (strongly) discouraged to invoke such HTTP request by ONESELF.After successful agent start-up, an instructional page shall become available at the root (i.e./) of the port specified in the docker compose file. The exact address depends on where the agent container is deployed (i.e. localhost, remote VM, ...), but takes a form likehttp://165.232.172.16:7060/.Asynchronous derivation operationOnce the Agent is deployed, it periodically (defined byDERIVATION_PERIODIC_TIMESCALE) checks the derivation thatisDerivedUsingitself (parameterONTOAGENT_SERVICE_IRI) and acts based on the status associated with that derivation. Over time, you may see more information about a reaction experiment is added to the knowledge graph gradually.Prior derivation markupFor the Agent to detect outdated information, a proper mark up of the relevant derivation inputs (i.e.pureinputs) is required. (Please note, that another pre-requisite for detecting derivation inputs is the registration of the agent in the KG, i.e.REGISTER_AGENT=truein the env file.) The following methods from thepyderivationagentpackage shall be used to mark up derivation inputs within the KG (for illustration purposes only):# Retrieve derivation client from derivation agentderiv_client=agent.derivation_client# Alternatively create new derivation client using:# deriv_client = pyderivationagent.PyDerivationClient(...)# Using pyderivationagent>=1.3.0, the timestamp for pure inputs will be added automatically when marking up the derivations# Hence, no need to add them separately (just for reference here)#deriv_client.addTimeInstance(inputIRI)# Update time stamp to all pure input instances (i.e. inputIRIs)deriv_client.updateTimestamp(inputIRI)# Create (flat!) list of all pure inputs (i.e. inputIRIs)deriv_inputs=[goal_set_IRI,lab_IRI,chem_rxn_IRI,rxn_exp_IRI1,rxn_exp_IRI2,...]# Create derivation markup in KGderiv_iri=deriv_client.createAsyncDerivationForNewInfo(agent.agentIRI,deriv_inputs)Agent integration testAs this derivation agent modifies the knowledge graph automatically, it is recommended to run integration tests before deploying it for production. A few integration tests are provided in thetestsrepository.The dockerised integration test can be invoked via below commands:(Linux)cd/your_absolute_path_to/TheWorldAvatar/Agents/RxnOptGoalIterAgent
pytest-s--docker-compose=./docker-compose.test.yml--reruns5--reruns-delay5If you would like to contribute to new features for the ROGI Agent, you may use the same integration test to make sure the new features added do NOT break the original function.Upload docker image to GitHubDevelopers who add new features to theRxnOptGoalIter Agenthandle the distribution of the docker image on GitHub. If you want to add new features that suit your project and release the docker image independently, i.e. become a developer/maintainer, please contact the repository's administrator to indicate your interest.The release procedure is currently semi-automated and requires a few items:Your GitHub account and password (personal access token)The version number x.x.x for the releaseClone ofTheWorldAvatarrepository on your local machineDocker-desktop is installed and running on your local machineStable version releaseThe release process can be started by using the commands below. (REMEMBER TO CHANGE THE CORRECT VALUES FOR<absolute_path_to>IN THE COMMANDS BELOW!)NOTE: the release process is only tested in WSL2 environment.(Linux)$cd/<absolute_path_to>/TheWorldAvatar/Agents/RxnOptGoalIterAgent
$./upload_docker_image_to_github.sh-vx.x.xPlease follow the instructions presented in the console once the process has begun. If everything goes well, the change performed automatically during the release process should be commited, i.e., in python scriptAgents/RxnOptGoalIterAgent/docker-compose.github.ymlimage: ghcr.io/cambridge-cares/rxn_opt_goal_iter_agent:x.x.xNOTE: the visibility of the uploaded docker image is set as private by default, developer who uploaded the image need to change the package visibility to public manually after the upload.Snapshot version releaseIf you would like to release the package in SNAPSHOT version, below commands can be used intead:(Linux)$cd/<absolute_path_to>/TheWorldAvatar/Agents/RxnOptGoalIterAgent
$./upload_docker_image_to_github.sh-vx.x.x-SNAPSHOTPlease follow the instructions presented in the console once the process has begun. If everything goes well, commit the change in version number following the same procedure as in the stable version release.AuthorsJiaru Bai (jb2197@cam.ac.uk)