Welcome to the AdsKRK repository! This project is a prototype developed during the 2-day LLM Hackathon for Application in Chemistry and Materials Science.
The goal of AdsKRK is to showcase how Large Language Models (LLMs) can autonomously explore the binding configurations of adsorbates on hetero-catalytic surfaces. Starting from only a SMILES string and a surface structure, the agent can:
- generate binding configurations,
- run structure relaxations,
- analyze the results, and
- iterate until a stable configuration is found.
Users can also interact with the agent - asking questions about the system or guiding the search process through prompts.
At the core of AdsKRK is AutoAdsorbate - a powerful tool for generating chemically meaningful molecular and fragment configurations on surfaces, providing a search space for the agent.
- Multi-Backend LLM Support: Google AI (Gemini), OpenRouter, Ollama, HuggingFace
- Multiple Structure Formats: XYZ, CIF, PDB, SDF, MOL, POSCAR/VASP
- Interactive UI: Streamlit-based interface with real-time agent feedback
- Local & Cloud Options: Use cloud APIs or run completely offline with Ollama/HuggingFace
# Clone and install
git clone https://github.com/schwallergroup/llm_adsorbate.git
cd llm_adsorbate
uv pip install -e .
# Set API key (Google AI is default)
export GOOGLE_API_KEY="your-google-api-key"
# Run the app
streamlit run src/app/app.pyThen provide your inputs in the sidebar:
- SMILES: Molecule structure (e.g.,
O=C=Ofor CO₂,Ofor oxygen atom) - Slab File: Upload your surface structure
- Query: What you want to find
- Click
▶️ Run
📖 See Quickstart Guide for detailed instructions.
| Backend | Type | API Key | Best For |
|---|---|---|---|
| Google AI | Cloud | GOOGLE_API_KEY |
Production (default) |
| OpenRouter | Cloud | OPENROUTER_API_KEY |
Multi-model access |
| Ollama | Local | Not needed | Privacy, offline |
| HuggingFace | Local | Not needed | Customization |
Select your backend in the app sidebar or via environment variable:
export ADSKRK_LLM_BACKEND=google # or openrouter, ollama, huggingface📖 See LLM Backends for configuration details.
| Format | Extensions |
|---|---|
| XYZ | .xyz |
| CIF | .cif |
| PDB | .pdb |
| SDF/MOL | .sdf, .mol |
| POSCAR | .poscar, .vasp |
Multiple ways to provide your API key (in priority order):
-
Environment variable:
export GOOGLE_API_KEY="your-google-api-key" # or OPENROUTER_API_KEY for OpenRouter
-
Config file: Use the app's "Save for future sessions" checkbox
- Stored at:
~/.adskrk/config.json
- Stored at:
-
Manual input: Enter in the sidebar each session
The app provides advanced settings (click ⚙️ Advanced Settings):
- Temperature: 0.0 (deterministic) to 1.0 (creative)
- Max Tokens: 256 to 16384
One particularly interesting finding was the agent's ability to reason about relaxation trajectories. For CO₂ on a copper surface, Gemini 2.5 Pro can analyze:
The stability of the initial adsorption configuration was assessed by
performing a structural relaxation. Based on the output from the simulation,
the fragment did not remain bound to the surface.
...
Therefore, to answer the user's question: no, the fragment does not stay
covalently bound. The initial configuration, with the carbon atom placed
on a top site of the Cu(211) surface, is unstable and leads to desorption.
- Quickstart Guide - Get started in 5 minutes
- LLM Backends - Configure LLM providers
- Calculator Backends - MACE and other calculators
# Install with dev dependencies
uv pip install -e ".[dev]"
# Run tests
pytest tests/MIT License - see LICENSE file.
- AutoAdsorbate - Surface configuration generation
- MACE - Machine learning interatomic potentials
- LangChain - LLM framework