Metadata-Version: 2.4
Name: crystalyse-ai
Version: 1.0.0
Summary: CrystaLyse.AI - Autonomous AI agents for accelerated inorganic materials design through natural language interfaces
Author: CrystaLyse.AI Development Team
Maintainer: CrystaLyse.AI Development Team
License: MIT License
        
        Copyright (c) 2025 Ry Nduma
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/ryannduma/CrystaLyse.AI
Project-URL: Documentation, https://crystalyse-ai.readthedocs.io/
Project-URL: Repository, https://github.com/ryannduma/CrystaLyse.AI.git
Project-URL: Issues, https://github.com/ryannduma/CrystaLyse.AI/issues
Project-URL: Changelog, https://github.com/ryannduma/CrystaLyse.AI/blob/main/CHANGELOG.md
Keywords: materials-design,crystal-structure-prediction,formation-energy,computational-materials-science,ai,chemistry,inorganic-materials,autonomous-agents
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Education
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: openai>=1.0.0
Requires-Dist: openai-agents>=0.0.16
Requires-Dist: rdkit>=2023.9.1
Requires-Dist: pymatgen>=2024.1.0
Requires-Dist: ase>=3.22.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: pandas>=2.0.0
Requires-Dist: scipy>=1.11.0
Requires-Dist: typing-extensions>=4.5.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: click>=8.1.0
Requires-Dist: rich>=13.0.0
Requires-Dist: prompt-toolkit>=3.0.0
Requires-Dist: asyncio>=3.4.3
Requires-Dist: httpx>=0.24.0
Requires-Dist: websockets>=11.0.0
Requires-Dist: PyYAML>=6.0.0
Requires-Dist: toml>=0.10.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: uvicorn>=0.23.0
Requires-Dist: fastapi>=0.104.0
Requires-Dist: starlette>=0.27.0
Provides-Extra: visualization
Requires-Dist: matplotlib>=3.7.0; extra == "visualization"
Requires-Dist: plotly>=5.18.0; extra == "visualization"
Requires-Dist: py3Dmol>=2.0.4; extra == "visualization"
Requires-Dist: kaleido>=0.2.1; extra == "visualization"
Requires-Dist: pymatviz>=0.8.5; extra == "visualization"
Requires-Dist: seaborn>=0.12.0; extra == "visualization"
Provides-Extra: quantum
Requires-Dist: pyscf>=2.3.0; extra == "quantum"
Requires-Dist: qiskit-nature>=0.7.0; extra == "quantum"
Requires-Dist: pennylane>=0.32.0; extra == "quantum"
Provides-Extra: materials
Requires-Dist: pymatgen>=2024.1.0; extra == "materials"
Requires-Dist: matminer>=0.9.0; extra == "materials"
Requires-Dist: mp-api>=0.41.0; extra == "materials"
Provides-Extra: ml
Requires-Dist: scikit-learn>=1.3.0; extra == "ml"
Requires-Dist: torch>=2.0.0; extra == "ml"
Requires-Dist: transformers>=4.30.0; extra == "ml"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: pytest-mock>=3.11.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: isort>=5.12.0; extra == "dev"
Requires-Dist: pre-commit>=3.0.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: mkdocs>=1.5.0; extra == "docs"
Requires-Dist: mkdocs-material>=9.0.0; extra == "docs"
Requires-Dist: mkdocstrings[python]>=0.24.0; extra == "docs"
Requires-Dist: mkdocs-jupyter>=0.24.0; extra == "docs"
Provides-Extra: all
Requires-Dist: crystalyse-ai[materials,ml,quantum,visualization]; extra == "all"
Dynamic: license-file

# CrystaLyse.AI

![CrystaLyse.AI Interface](docs/assets/images/CLI_Startup_Image.png)

**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.

> **💡 For AI Assistants & Copilots**: If you're using GitHub Copilot, Claude, ChatGPT, or other AI coding assistants, check out [`READMEFORLLMS.md`](READMEFORLLMS.md) - a comprehensive guide designed specifically for AI agents to quickly understand this project's capabilities, installation, and usage patterns. Simply copy-paste its contents into your AI assistant for instant project context!

## 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**: Interactive molecular viewers 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

## Architecture Overview

### High-Level System Architecture

```mermaid
graph TB
    subgraph "User Interface Layer"
        CLI[Enhanced CLI<br/>Rich Console + Themes]
        UNIFIED[Unified Interface<br/>Single Entry Point]
        LEGACY[Legacy CLI Commands<br/>Backward Compatibility]
    end
    
    subgraph "Agent Layer"
        SESSION_AGENT[Session-Based Agent<br/>OpenAI Agents SDK]
        LEGACY_AGENT[Legacy Agent<br/>Direct MCP Integration]
        VALIDATOR[Response Validator<br/>Anti-Hallucination]
    end
    
    subgraph "Memory System"
        SESSION_MEM[Session Memory<br/>SQLite Conversations]
        USER_MEM[User Memory<br/>Preferences & Research]
        DISCOVERY[Discovery Cache<br/>Computational Results]
        CROSS_SESSION[Cross-Session Context<br/>Research Continuity]
    end
    
    subgraph "MCP Server Architecture"
        CREATIVE[Chemistry Creative Server<br/>Chemeleon + MACE + Viz]
        UNIFIED_SERVER[Chemistry Unified Server<br/>SMACT + Chemeleon + MACE + Analysis]
        VIZ[Visualisation Server<br/>3Dmol.js + Pymatviz]
    end
    
    subgraph "Tool Dependencies (oldmcpservers)"
        SMACT[SMACT MCP<br/>Composition Validation]
        CHEMELEON[Chemeleon MCP<br/>Structure Prediction]
        MACE[MACE MCP<br/>Energy Calculation]
    end
    
    subgraph "Infrastructure"
        POOL[MCP Connection Pool<br/>Persistent Connections]
        SESSION_MGR[Session Manager<br/>Lifecycle Management]
        RESILIENT[Resilient Tool Caller<br/>Fault Tolerance]
    end
    
    CLI --> SESSION_AGENT
    UNIFIED --> SESSION_AGENT
    LEGACY --> LEGACY_AGENT
    
    SESSION_AGENT --> VALIDATOR
    SESSION_AGENT <--> SESSION_MEM
    SESSION_AGENT <--> USER_MEM
    SESSION_AGENT <--> DISCOVERY
    SESSION_AGENT <--> CROSS_SESSION
    
    SESSION_AGENT --> SESSION_MGR
    LEGACY_AGENT --> POOL
    SESSION_MGR --> POOL
    POOL --> RESILIENT
    
    RESILIENT --> CREATIVE
    RESILIENT --> UNIFIED_SERVER
    RESILIENT --> VIZ
    
    UNIFIED_SERVER --> SMACT
    UNIFIED_SERVER --> CHEMELEON
    UNIFIED_SERVER --> MACE
    CREATIVE --> CHEMELEON
    CREATIVE --> MACE
```

### Dual-Mode Operation Flow

```mermaid
graph LR
    subgraph "Entry Points"
        USER_QUERY[User Query]
        MODE_SELECT{Mode Selection<br/>/mode creative or rigorous}
    end
    
    subgraph "Creative Mode (~50s)"
        CREATIVE_SERVER[Chemistry Creative Server]
        FAST_STRUCT[Chemeleon Structure<br/>Generation]
        FAST_ENERGY[MACE Energy<br/>Calculation]
        BASIC_VIZ[Basic 3D<br/>Visualisation]
        CREATIVE_RESULT[Fast Results<br/>Structure + Energy]
    end
    
    subgraph "Rigorous Mode (2-5min)"
        UNIFIED_SERVER[Chemistry Unified Server]
        SMACT_VAL[SMACT Composition<br/>Validation]
        FULL_STRUCT[Chemeleon Complete<br/>Structure Generation]
        FULL_ENERGY[MACE Full Energy<br/>Analysis]
        COMPREHENSIVE[XRD + RDF +<br/>Coordination Analysis]
        RIGOROUS_RESULT[Complete Results<br/>Publication Ready]
    end
    
    subgraph "Memory Integration"
        CACHE[Discovery Cache<br/>Avoid Redundancy]
        SESSION[Session History<br/>Research Context]
        INSIGHTS[Cross-Session<br/>Learning]
    end
    
    USER_QUERY --> MODE_SELECT
    MODE_SELECT -->|Creative| CREATIVE_SERVER
    MODE_SELECT -->|Rigorous| UNIFIED_SERVER
    
    CREATIVE_SERVER --> FAST_STRUCT
    FAST_STRUCT --> FAST_ENERGY
    FAST_ENERGY --> BASIC_VIZ
    BASIC_VIZ --> CREATIVE_RESULT
    
    UNIFIED_SERVER --> SMACT_VAL
    SMACT_VAL --> FULL_STRUCT
    FULL_STRUCT --> FULL_ENERGY
    FULL_ENERGY --> COMPREHENSIVE
    COMPREHENSIVE --> RIGOROUS_RESULT
    
    CREATIVE_RESULT --> CACHE
    RIGOROUS_RESULT --> CACHE
    CACHE --> SESSION
    SESSION --> INSIGHTS
```

### Session-Based Research Flow

```mermaid
graph TB
    subgraph "Session Lifecycle"
        START[Session Start<br/>crystalyse chat -s project]
        RESUME[Session Resume<br/>crystalyse resume project]
        CONTEXT[Context Loading<br/>Previous Conversations]
    end
    
    subgraph "Interactive Commands"
        MODE_SWITCH["/mode creative|rigorous"]
        AGENT_SWITCH["/agent chat|analyse"]
        HISTORY["/history - Show Past"]
        STATUS["/status - Current State"]
        THEME["/theme - Change UI"]
    end
    
    subgraph "Research Memory"
        CONV_HIST[Conversation History<br/>SQLite Storage]
        DISCOVERIES[Discovery Database<br/>Computational Results]
        USER_PROF[User Profiles<br/>Research Interests]
        WEEKLY[Weekly Summaries<br/>Research Progress]
    end
    
    subgraph "Multi-Day Continuity"
        PROJECT[Long-term Projects]
        COLLAB[Collaborative Sessions]
        INSIGHTS[Pattern Recognition]
        EXPORT[Research Export]
    end
    
    START --> CONTEXT
    RESUME --> CONTEXT
    CONTEXT --> MODE_SWITCH
    CONTEXT --> AGENT_SWITCH
    
    MODE_SWITCH --> CONV_HIST
    AGENT_SWITCH --> CONV_HIST
    HISTORY --> CONV_HIST
    STATUS --> USER_PROF
    
    CONV_HIST --> DISCOVERIES
    DISCOVERIES --> WEEKLY
    WEEKLY --> PROJECT
    PROJECT --> COLLAB
    COLLAB --> INSIGHTS
    INSIGHTS --> EXPORT
```

## Repository Structure

```
CrystaLyse.AI/
├── crystalyse/                    # Core package
│   ├── agents/                    # AI agent implementations
│   ├── infrastructure/            # Connection pooling, session management
│   ├── memory/                    # Memory system and caching
│   ├── output/                    # Dual formatter and visualisation
│   ├── validation/                # Anti-hallucination system
│   └── cli.py                     # Unified command-line interface
├── chemistry-unified-server/      # Rigorous mode (SMACT + Chemeleon + MACE)
├── chemistry-creative-server/     # Creative mode (Chemeleon + MACE)
├── visualization-mcp-server/      # 3D structures and analysis plots
├── oldmcpservers/                 # Individual tool servers (required dependencies)
│   ├── smact-mcp-server/          # SMACT composition validation
│   ├── chemeleon-mcp-server/      # Chemeleon structure prediction
│   └── mace-mcp-server/           # MACE energy calculations
├── docs/                          # Comprehensive documentation
│   ├── guides/                    # Installation and usage guides
│   ├── concepts/                  # Analysis modes and architecture
│   ├── tools/                     # Individual tool documentation
│   └── reference/                 # Complete API reference
```

## Quick Start

### Installation

```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 core package
pip install -e .

# Install individual tool servers (required dependencies)
pip install -e ./oldmcpservers/smact-mcp-server
pip install -e ./oldmcpservers/chemeleon-mcp-server
pip install -e ./oldmcpservers/mace-mcp-server

# Install unified MCP servers
pip install -e ./chemistry-unified-server
pip install -e ./chemistry-creative-server
pip install -e ./visualization-mcp-server
```

### Configuration

```bash
# Set OpenAI API key
export OPENAI_API_KEY="sk-your-key-here"

# Verify installation
crystalyse --help
crystalyse config show
```

## Usage Examples

### Quick Analysis

```bash
# Creative mode (fast exploration)
crystalyse analyse "Find stable perovskite materials for solar cells" --mode creative

# Rigorous mode (complete validation)
crystalyse analyse "Analyse CsSnI3 for photovoltaic applications" --mode rigorous
```

### 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
```

### Unified Interface

```bash
# Launch interactive interface with mode switching
crystalyse

# In-session commands:
# /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                         │
│                                                                        │
│ 3D visualisations created: CsGeI3_3dmol.html, CsPbI3_3dmol.html      │
╰────────────────────────────────────────────────────────────────────────╯
```

**Rigorous Mode Output**:
- Complete SMACT composition validation
- Multiple structure candidates per composition
- Professional analysis plots (XRD, RDF, coordination analysis)
- 3D interactive visualisations
- Publication-ready results

## 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

### Research Workflows
- High-throughput materials screening
- Structure-property relationship studies
- Materials optimisation and design
- Experimental validation planning

## 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 |

**System Requirements**:
- Python 3.11+
- 8GB RAM minimum (16GB recommended)
- OpenAI API key
- Optional: NVIDIA GPU for MACE acceleration

## Documentation

Comprehensive documentation is available in the [`docs/`](docs/) directory:

- **[Quickstart Guide](docs/quickstart.md)** - Get started in minutes
- **[Installation Guide](docs/guides/installation.md)** - Detailed setup instructions
- **[CLI Usage Guide](docs/guides/cli_usage.md)** - Complete command reference
- **[Analysis Modes](docs/concepts/analysis_modes.md)** - Creative vs Rigorous workflows
- **[Tool Documentation](docs/tools/)** - SMACT, Chemeleon, MACE, Visualisation
- **[API Reference](docs/reference/)** - Complete API documentation

## 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

## Acknowledgments

CrystaLyse.AI builds upon exceptional open-source tools:

- **[SMACT](https://github.com/WMD-group/SMACT)**: Semiconducting Materials by Analogy and Chemical Theory
- **[Chemeleon](https://github.com/hspark1212/chemeleon)**: Crystal structure prediction with AI
- **[MACE](https://github.com/ACEsuit/mace)**: Machine learning ACE force fields
- **[Pymatviz](https://github.com/janosh/pymatviz)**: Materials visualisation toolkit
- **[OpenAI Agents SDK](https://github.com/openai/openai-agents-python)**: 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.
