ai4chems/mof_chemunity

Purpose and entry points

MOF-ChemUnity builds and queries a Neo4j knowledge graph linking MOF computational data with LLM-extracted literature facts through CSD codes and DOI. Primary user entry point is QueryGenerationAgent.run_full_query() in src/MOF_ChemUnity/Agents/QueryAgent.py. Dataset extension is notebook-led: src/ChemUnity_Matching.ipynb then src/ChemUnity_Extraction.ipynb; graph loading is src/Knowledge Graph Creation/neo4j_import.py.

Agent layer

BaseAgent provides the shared agent foundation, specialized by extraction, entity matching, and natural-language graph querying:

• src/MOF_ChemUnity/Agents/BaseAgent.py

• src/MOF_ChemUnity/Agents/ExtractionAgent.py

• src/MOF_ChemUnity/Agents/MatchingAgent.py

• src/MOF_ChemUnity/Agents/QueryAgent.py

This separates LLM-driven interpretation from data preparation and graph persistence.

Literature ingestion and normalization

Documents are converted into usable text/Markdown before extraction. Extraction agents produce structured information such as MOF names, properties, applications, synthesis, and water stability; matching connects literature mentions to CSD identifiers. Prompt modules define task-specific LLM instructions:

• src/MOF_ChemUnity/utils/DocProcessor.py

• src/MOF_ChemUnity/utils/XML_to_MD.py

• src/MOF_ChemUnity/Prompts/Extraction_Prompts.py

• src/MOF_ChemUnity/Prompts/Matching_Prompts.py

Example PDF/XML inputs and derived Markdown demonstrate the ingestion boundary under src/Examples/PDF/ and src/Examples/XML/.

Data quality, identity, and enrichment

Utilities prepare, filter, model, and reconcile extracted records before graph import. The CSD code is the central identity boundary joining paper-derived facts to computational sources; MOF/CSD reference data supports this linkage.

• src/MOF_ChemUnity/utils/DataModels.py

• src/MOF_ChemUnity/utils/DataPrep.py

• src/MOF_ChemUnity/utils/FilterTools.py

• src/MOF_ChemUnity/utils/csd_dict.py

• data/MOF_names_and_CSD_codes.csv

Knowledge-graph persistence

Neo4j is the material runtime and system of record. Import expects relational CSV exports for matching, experimental properties, applications, synthesis, water stability, descriptors, and computational properties, then creates the graph and relationships:

• src/Knowledge Graph Creation/neo4j_import.py

• src/Examples/KG_Data/matching.csv

• src/Examples/KG_Data/computational_properties.csv

• src/Examples/KG_Data/filtered_experimental_properties.csv

Connection credentials are supplied through NEO4J_URI, NEO4J_USER, and NEO4J_PASSWORD, keeping infrastructure access outside package code.

Query and retrieval flow

A user question enters QueryGenerationAgent, which translates it into Neo4j-oriented retrieval and returns a Pandas DataFrame. Query prompts are isolated from the agent implementation:

• src/MOF_ChemUnity/Agents/QueryAgent.py

• src/MOF_ChemUnity/Prompts/Query_Generation_Prompts.py

Semantic/similarity retrieval artifacts use FAISS indexes, with neighboring-record logic in:

• src/MOF_ChemUnity/utils/NeighbourFinder.py

• src/Examples/vs/10.1016_j.molstruc.2017.11.128/index.faiss

External services and expansion

OpenAI/GPT-4o is the intended LLM service for extraction and query generation; users provide their own API key. Neo4j hosts the graph. Cross-document expansion utilities support finding related literature and appending new extractions:

• src/MOF_ChemUnity/utils/cross_doc_utils.py

• src/Cross_Document.ipynb