# CrystaLyse.AI
**CrystaLyse.AI - Autonomous AI agents for accelerated inorganic materials design through natural language interfaces**
[](https://badge.fury.io/py/crystalyse-ai)
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
> **Status: Research Preview - Fully Functional Materials Design Platform**
CrystaLyse.AI is a computational materials design platform that accelerates materials exploration through AI-powered analysis and validation. Built on the OpenAI Agents framework with Model Context Protocol (MCP) integration, it provides a dual-mode system for rapid materials design workflows.
## 🚀 Quick Start
### Installation
```bash
# Install from PyPI
pip install crystalyse-ai
# Set your OpenAI API key
export OPENAI_API_KEY="sk-your-key-here"
# Verify installation
crystalyse --help
```
### Basic Usage
```bash
# Creative mode (fast exploration ~50 seconds)
crystalyse analyse "Find stable perovskite materials for solar cells" --mode creative
# Rigorous mode (complete validation 2-5 minutes)
crystalyse analyse "Analyse CsSnI3 for photovoltaic applications" --mode rigorous
# Interactive session
crystalyse chat
```
## ✨ Key Features
### 🔄 Dual-Mode Analysis System
- **Creative Mode**: Fast exploration (~50 seconds) using Chemeleon + MACE
- **Rigorous Mode**: Complete validation (2-5 minutes) with SMACT + Chemeleon + MACE + Analysis Suite
- Real-time mode switching with unified interface
### 🧪 Complete Materials Pipeline
- **Composition Validation**: SMACT screening for chemically reasonable materials
- **Structure Prediction**: Chemeleon crystal structure generation with multiple candidates
- **Energy Calculations**: MACE formation energy evaluation with uncertainty quantification
- **Comprehensive Analysis**: XRD patterns, RDF analysis, coordination studies
- **3D Visualisation**: CIF file generation and professional analysis plots
### 💻 Advanced Interface Options
- **Unified CLI**: Single command interface with `/mode` and `/agent` switching
- **Session Management**: Persistent conversation history across multi-day projects
- **Interactive Chat**: Research-grade session-based workflows
- **Batch Processing**: High-throughput materials screening capabilities
## 🔬 Scientific Applications
### Energy Materials
- Battery cathodes and anodes (Li-ion, Na-ion, solid-state)
- Solid electrolytes and ion conductors
- Photovoltaic semiconductors and perovskites
- Thermoelectric materials
### Electronic Materials
- Ferroelectric and multiferroic materials
- Magnetic materials and spintronics
- Semiconductor devices and memory materials
- Superconductors and quantum materials
## 📊 Performance Characteristics
| Operation | Creative Mode | Rigorous Mode |
|-----------|---------------|---------------|
| Simple query | ~50 seconds | 2-3 minutes |
| Complex analysis | 1-2 minutes | 3-5 minutes |
| Batch processing | 5-10 minutes | 15-30 minutes |
## 🛠️ Advanced Usage
### Interactive Research Sessions
```bash
# Start a research session
crystalyse chat -u researcher -s solar_project -m creative
# Resume previous work
crystalyse resume solar_project -u researcher
# List all sessions
crystalyse sessions -u researcher
```
### In-Session Commands
```bash
/mode creative # Switch to creative mode
/mode rigorous # Switch to rigorous mode
/agent chat # Switch to chat agent
/agent analyse # Switch to analysis agent
/help # Show available commands
/exit # Exit interface
```
## 📈 Example Output
### Creative Mode Results
```
╭─────────────────────── Discovery Results ────────────────────────────╮
│ Generated 5 perovskite candidates with formation energies: │
│ │
│ 1. CsGeI₃ - Formation energy: -2.558 eV/atom (most stable) │
│ 2. CsPbI₃ - Formation energy: -2.542 eV/atom │
│ 3. CsSnI₃ - Formation energy: -2.529 eV/atom │
│ 4. RbPbI₃ - Formation energy: -2.503 eV/atom │
│ 5. RbSnI₃ - Formation energy: -2.488 eV/atom │
│ │
│ CIF files created: CsGeI3.cif, CsPbI3.cif, CsSnI3.cif │
╰────────────────────────────────────────────────────────────────────────╯
```
### Rigorous Mode Output
- Complete SMACT composition validation
- Multiple structure candidates per composition
- Professional analysis plots (XRD, RDF, coordination analysis)
- CIF file generation for all structures
- Publication-ready results
## 🔬 Scientific Integrity
CrystaLyse.AI maintains computational honesty:
- **100% Traceability**: Every result traces to actual tool calculations
- **Zero Fabrication**: No estimated or hallucinated numerical values
- **Complete Transparency**: Clear distinction between AI reasoning and computational validation
- **Anti-Hallucination System**: Response validation prevents fabricated results
## 🖥️ System Requirements
- Python 3.11+
- 8GB RAM minimum (16GB recommended)
- OpenAI API key
- Optional: NVIDIA GPU for MACE acceleration
## 🔧 Development Installation
For development or advanced usage:
```bash
# Clone repository
git clone https://github.com/ryannduma/CrystaLyse.AI.git
cd CrystaLyse.AI
# Create conda environment
conda create -n crystalyse python=3.11
conda activate crystalyse
# Install in development mode
pip install -e .
```
## 🤝 Acknowledgments
CrystaLyse.AI builds upon exceptional open-source tools:
- **SMACT**: Semiconducting Materials by Analogy and Chemical Theory
- **Chemeleon**: Crystal structure prediction with AI
- **MACE**: Machine learning ACE force fields
- **Pymatviz**: Materials visualisation toolkit
- **OpenAI Agents SDK**: Production-ready agent framework
## 📚 Citation
If you use CrystaLyse.AI in your research, please cite the underlying tools:
- **SMACT**: Davies et al., "SMACT: Semiconducting Materials by Analogy and Chemical Theory" JOSS 4, 1361 (2019)
- **Chemeleon**: Park et al., "Exploration of crystal chemical space using text-guided generative artificial intelligence" Nature Communications (2025)
- **MACE**: Batatia et al., "MACE: Higher Order Equivariant Message Passing Neural Networks for Fast and Accurate Force Fields" NeurIPS (2022)
- **Pymatviz**: Riebesell et al., "Pymatviz: visualization toolkit for materials informatics" (2022)
## 📄 License
MIT License - see LICENSE for details.
## 🐛 Issues & Support
Report issues on [GitHub Issues](https://github.com/ryannduma/CrystaLyse.AI/issues)
## 🔗 Links
- [Homepage](https://github.com/ryannduma/CrystaLyse.AI)
- [Documentation](https://crystalyse-ai.readthedocs.io/)
- [Changelog](https://github.com/ryannduma/CrystaLyse.AI/blob/main/CHANGELOG.md)
Raw data
{
"_id": null,
"home_page": null,
"name": "crystalyse-ai",
"maintainer": "CrystaLyse.AI Development Team",
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "materials-design, crystal-structure-prediction, formation-energy, computational-materials-science, ai, chemistry, inorganic-materials, autonomous-agents",
"author": "CrystaLyse.AI Development Team",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/f7/87/360c90fb958da08ac964c47f925f24ab6af7b8ba83a9ed4032f2976fb246/crystalyse_ai-1.0.14.tar.gz",
"platform": null,
"description": "# CrystaLyse.AI\n\n**CrystaLyse.AI - Autonomous AI agents for accelerated inorganic materials design through natural language interfaces**\n\n[](https://badge.fury.io/py/crystalyse-ai)\n[](https://www.python.org/downloads/)\n[](https://opensource.org/licenses/MIT)\n\n> **Status: Research Preview - Fully Functional Materials Design Platform**\n\nCrystaLyse.AI is a computational materials design platform that accelerates materials exploration through AI-powered analysis and validation. Built on the OpenAI Agents framework with Model Context Protocol (MCP) integration, it provides a dual-mode system for rapid materials design workflows.\n\n## \ud83d\ude80 Quick Start\n\n### Installation\n\n```bash\n# Install from PyPI\npip install crystalyse-ai\n\n# Set your OpenAI API key\nexport OPENAI_API_KEY=\"sk-your-key-here\"\n\n# Verify installation\ncrystalyse --help\n```\n\n### Basic Usage\n\n```bash\n# Creative mode (fast exploration ~50 seconds)\ncrystalyse analyse \"Find stable perovskite materials for solar cells\" --mode creative\n\n# Rigorous mode (complete validation 2-5 minutes)\ncrystalyse analyse \"Analyse CsSnI3 for photovoltaic applications\" --mode rigorous\n\n# Interactive session\ncrystalyse chat\n```\n\n## \u2728 Key Features\n\n### \ud83d\udd04 Dual-Mode Analysis System\n- **Creative Mode**: Fast exploration (~50 seconds) using Chemeleon + MACE\n- **Rigorous Mode**: Complete validation (2-5 minutes) with SMACT + Chemeleon + MACE + Analysis Suite\n- Real-time mode switching with unified interface\n\n### \ud83e\uddea Complete Materials Pipeline\n- **Composition Validation**: SMACT screening for chemically reasonable materials\n- **Structure Prediction**: Chemeleon crystal structure generation with multiple candidates\n- **Energy Calculations**: MACE formation energy evaluation with uncertainty quantification\n- **Comprehensive Analysis**: XRD patterns, RDF analysis, coordination studies\n- **3D Visualisation**: CIF file generation and professional analysis plots\n\n### \ud83d\udcbb Advanced Interface Options\n- **Unified CLI**: Single command interface with `/mode` and `/agent` switching\n- **Session Management**: Persistent conversation history across multi-day projects\n- **Interactive Chat**: Research-grade session-based workflows\n- **Batch Processing**: High-throughput materials screening capabilities\n\n## \ud83d\udd2c Scientific Applications\n\n### Energy Materials\n- Battery cathodes and anodes (Li-ion, Na-ion, solid-state)\n- Solid electrolytes and ion conductors\n- Photovoltaic semiconductors and perovskites\n- Thermoelectric materials\n\n### Electronic Materials\n- Ferroelectric and multiferroic materials\n- Magnetic materials and spintronics\n- Semiconductor devices and memory materials\n- Superconductors and quantum materials\n\n## \ud83d\udcca Performance Characteristics\n\n| Operation | Creative Mode | Rigorous Mode |\n|-----------|---------------|---------------|\n| Simple query | ~50 seconds | 2-3 minutes |\n| Complex analysis | 1-2 minutes | 3-5 minutes |\n| Batch processing | 5-10 minutes | 15-30 minutes |\n\n## \ud83d\udee0\ufe0f Advanced Usage\n\n### Interactive Research Sessions\n\n```bash\n# Start a research session\ncrystalyse chat -u researcher -s solar_project -m creative\n\n# Resume previous work\ncrystalyse resume solar_project -u researcher\n\n# List all sessions\ncrystalyse sessions -u researcher\n```\n\n### In-Session Commands\n\n```bash\n/mode creative # Switch to creative mode\n/mode rigorous # Switch to rigorous mode\n/agent chat # Switch to chat agent\n/agent analyse # Switch to analysis agent\n/help # Show available commands\n/exit # Exit interface\n```\n\n## \ud83d\udcc8 Example Output\n\n### Creative Mode Results\n```\n\u256d\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 Discovery Results \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256e\n\u2502 Generated 5 perovskite candidates with formation energies: \u2502\n\u2502 \u2502\n\u2502 1. CsGeI\u2083 - Formation energy: -2.558 eV/atom (most stable) \u2502\n\u2502 2. CsPbI\u2083 - Formation energy: -2.542 eV/atom \u2502\n\u2502 3. CsSnI\u2083 - Formation energy: -2.529 eV/atom \u2502\n\u2502 4. RbPbI\u2083 - Formation energy: -2.503 eV/atom \u2502\n\u2502 5. RbSnI\u2083 - Formation energy: -2.488 eV/atom \u2502\n\u2502 \u2502\n\u2502 CIF files created: CsGeI3.cif, CsPbI3.cif, CsSnI3.cif \u2502\n\u2570\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256f\n```\n\n### Rigorous Mode Output\n- Complete SMACT composition validation\n- Multiple structure candidates per composition\n- Professional analysis plots (XRD, RDF, coordination analysis)\n- CIF file generation for all structures\n- Publication-ready results\n\n## \ud83d\udd2c Scientific Integrity\n\nCrystaLyse.AI maintains computational honesty:\n\n- **100% Traceability**: Every result traces to actual tool calculations\n- **Zero Fabrication**: No estimated or hallucinated numerical values\n- **Complete Transparency**: Clear distinction between AI reasoning and computational validation\n- **Anti-Hallucination System**: Response validation prevents fabricated results\n\n## \ud83d\udda5\ufe0f System Requirements\n\n- Python 3.11+\n- 8GB RAM minimum (16GB recommended)\n- OpenAI API key\n- Optional: NVIDIA GPU for MACE acceleration\n\n## \ud83d\udd27 Development Installation\n\nFor development or advanced usage:\n\n```bash\n# Clone repository\ngit clone https://github.com/ryannduma/CrystaLyse.AI.git\ncd CrystaLyse.AI\n\n# Create conda environment\nconda create -n crystalyse python=3.11\nconda activate crystalyse\n\n# Install in development mode\npip install -e .\n```\n\n## \ud83e\udd1d Acknowledgments\n\nCrystaLyse.AI builds upon exceptional open-source tools:\n\n- **SMACT**: Semiconducting Materials by Analogy and Chemical Theory\n- **Chemeleon**: Crystal structure prediction with AI\n- **MACE**: Machine learning ACE force fields\n- **Pymatviz**: Materials visualisation toolkit\n- **OpenAI Agents SDK**: Production-ready agent framework\n\n## \ud83d\udcda Citation\n\nIf you use CrystaLyse.AI in your research, please cite the underlying tools:\n\n- **SMACT**: Davies et al., \"SMACT: Semiconducting Materials by Analogy and Chemical Theory\" JOSS 4, 1361 (2019)\n- **Chemeleon**: Park et al., \"Exploration of crystal chemical space using text-guided generative artificial intelligence\" Nature Communications (2025)\n- **MACE**: Batatia et al., \"MACE: Higher Order Equivariant Message Passing Neural Networks for Fast and Accurate Force Fields\" NeurIPS (2022)\n- **Pymatviz**: Riebesell et al., \"Pymatviz: visualization toolkit for materials informatics\" (2022)\n\n## \ud83d\udcc4 License\n\nMIT License - see LICENSE for details.\n\n## \ud83d\udc1b Issues & Support\n\nReport issues on [GitHub Issues](https://github.com/ryannduma/CrystaLyse.AI/issues)\n\n## \ud83d\udd17 Links\n\n- [Homepage](https://github.com/ryannduma/CrystaLyse.AI)\n- [Documentation](https://crystalyse-ai.readthedocs.io/)\n- [Changelog](https://github.com/ryannduma/CrystaLyse.AI/blob/main/CHANGELOG.md)\n",
"bugtrack_url": null,
"license": null,
"summary": "CrystaLyse.AI - Autonomous AI agents for accelerated inorganic materials design through natural language interfaces",
"version": "1.0.14",
"project_urls": {
"Changelog": "https://github.com/ryannduma/CrystaLyse.AI/blob/main/CHANGELOG.md",
"Documentation": "https://crystalyse-ai.readthedocs.io/",
"Homepage": "https://github.com/ryannduma/CrystaLyse.AI",
"Issues": "https://github.com/ryannduma/CrystaLyse.AI/issues",
"Repository": "https://github.com/ryannduma/CrystaLyse.AI.git"
},
"split_keywords": [
"materials-design",
" crystal-structure-prediction",
" formation-energy",
" computational-materials-science",
" ai",
" chemistry",
" inorganic-materials",
" autonomous-agents"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "42def25e5b4f532bc463a4ff54c69345faf275c1399d94b46ed220ceba9807e2",
"md5": "12081a53bf9fbf73106b94bd4f8c08e7",
"sha256": "5d00a19411fec91366a4b6c45d1b829c22d367a0f121dba706366c1579afd5b3"
},
"downloads": -1,
"filename": "crystalyse_ai-1.0.14-py3-none-any.whl",
"has_sig": false,
"md5_digest": "12081a53bf9fbf73106b94bd4f8c08e7",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 181088,
"upload_time": "2025-07-24T15:37:52",
"upload_time_iso_8601": "2025-07-24T15:37:52.963462Z",
"url": "https://files.pythonhosted.org/packages/42/de/f25e5b4f532bc463a4ff54c69345faf275c1399d94b46ed220ceba9807e2/crystalyse_ai-1.0.14-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "f787360c90fb958da08ac964c47f925f24ab6af7b8ba83a9ed4032f2976fb246",
"md5": "bf93ed8b1220aa0a2377bb864e4d861d",
"sha256": "372140097ec7194ace92dc511ffc0c7d26d4d98e12febd3019173bbcf0a0be5a"
},
"downloads": -1,
"filename": "crystalyse_ai-1.0.14.tar.gz",
"has_sig": false,
"md5_digest": "bf93ed8b1220aa0a2377bb864e4d861d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 160937,
"upload_time": "2025-07-24T15:37:54",
"upload_time_iso_8601": "2025-07-24T15:37:54.457743Z",
"url": "https://files.pythonhosted.org/packages/f7/87/360c90fb958da08ac964c47f925f24ab6af7b8ba83a9ed4032f2976fb246/crystalyse_ai-1.0.14.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-24 15:37:54",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ryannduma",
"github_project": "CrystaLyse.AI",
"github_not_found": true,
"lcname": "crystalyse-ai"
}
JSON
