Metadata-Version: 2.1
Name: alphagrammar
Version: 0.1.2
Summary: AlphaGrammar: Grammar-based molecular representation learning
Author-email: Michael Sun <msun415@mit.edu>
License: MIT License
        
        Copyright (c) 2022 Minghao Guo
        
        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.
        
Keywords: molecule,grammar,SMILES,representation-learning,chemistry
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: torch
Requires-Dist: rdkit
Requires-Dist: networkx
Requires-Dist: matplotlib
Requires-Dist: tqdm
Requires-Dist: torch-geometric
Requires-Dist: graphviz

# AlphaGrammar

**AlphaGrammar** is a grammar-based molecular representation learning framework.
It learns a hyperedge-replacement grammar (HRG) over molecular graphs via
Monte Carlo Tree Search (MCMC) with a learned agent.

## Installation

```bash
pip install -e /path/to/AlphaGrammar_pkg
```

Or from PyPI (once published):

```bash
pip install alphagrammar
```

### Pretrained models

After installation, copy the pretrained model files to the package data directory:

```bash
DATA_DIR=$(python -c "import alphagrammar, os; print(os.path.join(os.path.dirname(alphagrammar.__file__), 'data'))")
cp /path/to/AlphaGrammar/ckpts/vocab_epoch5.pkl $DATA_DIR/
cp /path/to/AlphaGrammar/ckpts/best_agent_epoch0_R0.0000.pkl $DATA_DIR/
cp /path/to/AlphaGrammar/GCN/supervised_contextpred.pth $DATA_DIR/
```

## Usage

### Command-line interface

```bash
# Parse a single SMILES string (rollout mode)
alphagrammar parse "CCO"

# Parse from a file (one SMILES per line)
alphagrammar parse molecules.smi

# Parse with Bolinas parser (10-second timeout per molecule)
alphagrammar parse "CCO" --timeout 10

# Use only top-100 rules from vocab
alphagrammar parse "CCO" --vocab_size 100
```

### Python API

```python
from alphagrammar import MoleculeDataset, _collate_mol_batch, RuleStats
from alphagrammar.grammar_generation import MCMC_sampling
from alphagrammar.agent import Agent
import torch, pickle

# Load pretrained models
with open("data/vocab_epoch5.pkl", "rb") as f:
    rule_stats = pickle.load(f)

agent = Agent(feat_dim=300, hidden_size=256)
agent.load_state_dict(torch.load("data/best_agent_epoch0_R0.0000.pkl"))
agent.eval()

# Build input dataset
dataset = MoleculeDataset(["CCO", "c1ccccc1"], GNN_model_path="data/supervised_contextpred.pth")
batch = [dataset[i] for i in range(len(dataset))]
input_graphs_dict = _collate_mol_batch(batch)

# Run MCMC sampling
results, rules_per_mol, sequential_steps = MCMC_sampling(
    "output_dir", agent, input_graphs_dict, MCMC_size=1, debug=True
)
```

## Package structure

```
src/alphagrammar/
├── __init__.py          # Public API
├── cli.py               # argparse CLI entry point
├── core.py              # Core functions (bolinas_evaluate, MoleculeDataset, RuleStats, ...)
├── grammar_generation.py# MCMC sampling and grammar generation
├── agent.py             # Neural agent (policy network)
├── hrg_td_parser_undirected.py  # Bolinas HRG parser
├── private/             # Internal hypergraph / grammar data structures
├── fuseprop/            # Molecular fragmentation utilities
├── GCN/                 # Graph neural network feature extraction
├── data/                # Pretrained model files (copy here after install)
└── commands/
    └── parse.py         # 'alphagrammar parse' subcommand
```
