Merge dev update to main: RAG agent/graph for XANES, memory/database, evaluation

.github/workflows/dependency_tests.yml

@@ -0,0 +1,92 @@
+name: Dependency Tests
+
+on:
+  push:
+    branches: [ toml_dev ]
+  pull_request:
+    branches: [ toml_dev ]
+
+jobs:
+  test_install:
+    name: Verify Install (${{ matrix.install_extras }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+        install_extras: [core, calculators, uma, ui, parsl, viz]
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+
+    - name: Install Dependencies
+      run: |
+        python -m pip install --upgrade pip
+        if [ "${{ matrix.install_extras }}" == "uma" ]; then
+          # 1. Install the main package (installs mace-torch + old e3nn)
+          pip install .
+
+          # 2. FORCE UNINSTALL the conflicting packages
+          echo "💥 Forcefully removing mace-torch and e3nn for UMA compatibility..."
+          pip uninstall -y mace-torch e3nn
+
+          # 3. MANUALLY install the UMA dependencies 
+          # (We cannot use pip install .[uma] because it would trigger the resolution error)
+          pip install "fairchem-core==2.13.0" "e3nn>=0.5"
+
+        elif [ "${{ matrix.install_extras }}" == "core" ]; then
+          pip install .
+        else
+          pip install ".[${{ matrix.install_extras }}]"
+        fi
+    - name: Verify Imports
+      run: |
+        python -c "
+        import importlib
+        import sys
+
+        def check_import(package_name):
+            try:
+                importlib.import_module(package_name)
+                print(f'✅ {package_name} imported successfully')
+                return True
+            except ImportError as e:
+                print(f'❌ {package_name} failed to import: {e}')
+                return False
+
+        extras = '${{ matrix.install_extras }}'
+        failures = []
+
+        # Core imports that should always work
+        core_packages = ['chemgraph']
+        for pkg in core_packages:
+            if not check_import(pkg):
+                failures.append(pkg)
+
+        # Mapping of extras to key packages they provide
+        extra_packages = {
+            'calculators': ['tblite'],
+            'uma': ['fairchem.core', 'e3nn'],
+            'ui': ['streamlit', 'stmol'],
+            'parsl': ['parsl'],
+            'viz': ['pyppeteer', 'grandalf', 'nest_asyncio']
+        }
+
+        if extras != 'core':
+             # Check packages for specific extra
+             if extras in extra_packages:
+                 for pkg in extra_packages[extras]:
+                     if not check_import(pkg):
+                         failures.append(pkg)
+
+        if failures:
+            print(f'Failed to import: {failures}')
+            sys.exit(1)
+        else:
+            print('All expected packages active!')
+        "

.github/workflows/test-pypi-package.yml

@@ -1,12 +1,12 @@
 name: Test PyPI Package
 
 on:
-  push:
-    branches: [ main ]
-  pull_request:
-    branches: [ main ]
-    types: [opened, synchronize, reopened, ready_for_review]
-  workflow_dispatch:  # Allow manual triggering
+  workflow_dispatch:
+    inputs:
+      version:
+        description: 'PyPI version to test'
+        required: true
+        default: '0.3.4'
 
 jobs:
   test-pypi-install:
@@ -28,12 +28,12 @@ jobs:
 
     - name: Install chemgraphagent from PyPI
       run: |
-        pip install --no-cache-dir --upgrade "chemgraphagent==0.3.0"
+        pip install --no-cache-dir --upgrade "chemgraphagent==${{ inputs.version }}"
 
     - name: Verify package installation
       run: |
         python -c "import chemgraph; print('ChemGraph imported successfully')"
-        python -c "import ui; print('UI module imported successfully')"
+        python -c "from chemgraph.cli import main; print('CLI module imported successfully')"
         # Test that CLI command is available
         chemgraph --help || echo "CLI help command executed"
 
@@ -49,4 +49,4 @@ jobs:
     - name: Check package version
       run: |
         pip show chemgraphagent
-        python -c "from importlib.metadata import version; v=version('chemgraphagent'); print('Installed:', v); assert v=='0.3.0', f'Expected 0.3.0, got {v}'"
+        python -c "from importlib.metadata import version; v=version('chemgraphagent'); print('Installed:', v); assert v=='${{ inputs.version }}', f'Expected ${{ inputs.version }}, got {v}'"

.gitignore

@@ -45,6 +45,10 @@ test_outputs/
 
 .venv
 combine*
+
+# OpenCode (user-local config; copy from opencode.example.jsonc)
+opencode.json
+chemgraph_mcp_logs/
 vllm/
 logs/
 error_log.txt

.opencode/opencode.example.jsonc

@@ -0,0 +1,84 @@
+{
+  // ChemGraph OpenCode MCP Configuration
+  //
+  // Copy this file to opencode.json and customize for your environment:
+  //
+  //   cp .opencode/opencode.example.jsonc opencode.json
+  //
+  // Then set CHEMGRAPH_PYTHON to your ChemGraph Python interpreter:
+  //
+  //   export CHEMGRAPH_PYTHON=/path/to/your/venv/bin/python
+  //
+  // For example:
+  //   export CHEMGRAPH_PYTHON=env/chemgraph_env/bin/python   # local venv
+  //   export CHEMGRAPH_PYTHON=.venv/bin/python                # standard venv
+  //   export CHEMGRAPH_PYTHON=$(which python)                 # active environment
+  //
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    // ── General chemistry tools ─────────────────────────────────────────
+    // Provides: molecule_name_to_smiles, smiles_to_coordinate_file,
+    //           run_ase (energy/opt/vib/thermo/ir), extract_output_json
+    "chemgraph": {
+      "type": "local",
+      "command": [
+        "{env:CHEMGRAPH_PYTHON}",
+        "-m",
+        "chemgraph.mcp.mcp_tools"
+      ],
+      "enabled": true,
+      "environment": {
+        "CHEMGRAPH_LOG_DIR": "./chemgraph_mcp_logs"
+      }
+    }
+
+    // ── Additional MCP servers (uncomment to enable) ────────────────────
+    //
+    // MACE + Parsl (HPC ensemble calculations)
+    // Requires: parsl, mace-torch, HPC environment
+    //
+    // "chemgraph-mace-parsl": {
+    //   "type": "local",
+    //   "command": [
+    //     "{env:CHEMGRAPH_PYTHON}",
+    //     "-m",
+    //     "chemgraph.mcp.mace_mcp_parsl"
+    //   ],
+    //   "enabled": true,
+    //   "environment": {
+    //     "CHEMGRAPH_LOG_DIR": "./chemgraph_mcp_logs"
+    //   }
+    // },
+    //
+    // gRASPA + Parsl (gas adsorption simulations)
+    // Requires: parsl, gRASPA binary, HPC environment
+    //
+    // "chemgraph-graspa-parsl": {
+    //   "type": "local",
+    //   "command": [
+    //     "{env:CHEMGRAPH_PYTHON}",
+    //     "-m",
+    //     "chemgraph.mcp.graspa_mcp_parsl"
+    //   ],
+    //   "enabled": true,
+    //   "environment": {
+    //     "CHEMGRAPH_LOG_DIR": "./chemgraph_mcp_logs"
+    //   }
+    // },
+    //
+    // Data analysis (CIF splitting, JSONL aggregation, isotherm plotting)
+    //
+    // "chemgraph-data-analysis": {
+    //   "type": "local",
+    //   "command": [
+    //     "{env:CHEMGRAPH_PYTHON}",
+    //     "-m",
+    //     "chemgraph.mcp.data_analysis_mcp"
+    //   ],
+    //   "enabled": true,
+    //   "environment": {
+    //     "CHEMGRAPH_LOG_DIR": "./chemgraph_mcp_logs"
+    //   }
+    // }
+  }
+}

DEPLOYMENT.md

@@ -0,0 +1,75 @@
+# ChemGraph Deployment Guide
+
+This guide describes how to deploy ChemGraph using Docker. The deployment supports both an interactive Command Line Interface (CLI) and a JupyterLab environment.
+
+## Prerequisites
+
+- Docker
+- Docker Compose (v2 or later recommended) (Optional, but easier)
+- API Keys for Large Language Models (LLMs) (e.g., OpenAI, Anthropic, Gemini, Groq)
+
+## Building the Docker Image
+
+To build the Docker image locally:
+
+```bash
+docker build -t chemgraph:latest .
+```
+
+## Running the Application
+
+### Option 1: Using Docker Compose (Recommended)
+
+This method simplifies managing environment variables and volumes.
+
+1.  **Configure API Keys**: Create a `.env` file in the root directory (or ensure your environment variables are set in your shell).
+    ```env
+    OPENAI_API_KEY=your_key_here
+    ANTHROPIC_API_KEY=your_key_here
+    GEMINI_API_KEY=your_key_here
+    GROQ_API_KEY=your_key_here
+    ```
+
+2.  **Run CLI Interactively**:
+    ```bash
+    docker-compose run --rm chemgraph-cli
+    ```
+    This drops you into the ChemGraph interactive shell.
+
+3.  **Run JupyterLab**:
+    ```bash
+    docker-compose up chemgraph-jupyter
+    ```
+    Access JupyterLab at `http://localhost:8888`.
+
+### Option 2: Using Docker CLI Directly
+
+1.  **Run CLI Interactively**:
+    ```bash
+    docker run -it --rm \
+      -v "$(pwd):/app" \
+      -e OPENAI_API_KEY=$OPENAI_API_KEY \
+      chemgraph:latest
+    ```
+    *Note: Add other API keys as `-e VAR_NAME=value` flags as needed.*
+
+2.  **Run JupyterLab**:
+    ```bash
+    docker run -it --rm \
+      -p 8888:8888 \
+      -v "$(pwd):/app" \
+      chemgraph:latest \
+      jupyter lab --ip=0.0.0.0 --port=8888 --no-browser --allow-root --LabApp.token=''
+    ```
+
+## Development
+
+The `Dockerfile` and `docker-compose.yml` map the local directory to `/app` in the container. This means changes you make to the code locally are immediately visible in the container (for Python code, thanks to `-e .` editable install behavior, though `Dockerfile` uses standard install, mapping the volume overlays the source code).
+
+### Rebuilding Dependencies
+
+If you change `pyproject.toml` or `environment.yml`, you need to rebuild the image:
+
+```bash
+docker-compose build
+```