# molalchemy Project Roadmap

This document outlines the development roadmap for molalchemy, a SQLAlchemy extension for working with chemical cartridges in PostgreSQL. The roadmap is organized by development phases and includes specific opportunities for contributors.

## 🎯 Project Vision

molalchemy aims to be the **definitive Python library** for chemical database operations, providing:
- Integration between Python and chemical databases
- Support for all major chemical cartridges (Bingo, RDKit)
- Type-safe, modern SQLAlchemy 2.0+ API with full IDE support (type hints, autocompletion)
- Production-ready Docker images for easy deployment
- Comprehensive documentation and examples

## 📊 Current Status

- **Bingo PostgreSQL Integration**
  - [x] **Chemical indices** (`BingoMolIndex`, etc.)
  - [x] **Data types** (`BingoMol`, `BingoBinaryMol`, `BingoReaction`, `BingoBinaryReaction`)
  - [x] **Functions** : all function autogenerated from extracted metadata
  - [X] **Migration**: Alembic support for schema changes
  - [ ] **Full functions annotations and type hints**


- **RDKit PostgreSQL Integration**
  - [x] **Core data types** (`RdkitMol`, fingerprint types)
  - [x] **Chemical indices** (`RDKitMolIndex`, etc.)
  - [x] **Functions**: most common functions autogenerated from extracted metadata
  - [X] **Migration**: Alembic support for schema changes
  - [ ] **Full functions annotations and type hints**


- **Tutorials and Examples**
  - [x] Basic usage examples for Bingo and RDKit
  - [ ] FastAPI/SQLModel integration examples
  - [ ] Advanced tutorials covering complex queries and optimizations
  - [ ] Jupyter notebooks demonstrating real-world use cases


- **Infrastructure**
  - [x] **Modern development setup** (uv, ruff, pytest, pre-commit)
  - [x] **CI/CD pipeline setup**
  - [x] **Documentation framework** (MkDocs + mkdocstrings)
  - [ ] **Docker images** for Bingo and RDKit





### Future Plans
- [ ] ChemAxon cartridge integration (closed source, requires license)
- [ ] NextMove Author integration (closed source, requires license)
- [ ] Multi-dialect support for Bingo (e.g MySQL, Oracle)
- [ ] SQLite RDKit support (via [chemicalite](https://github.com/rvianello/chemicalite), including custom builds or custom event listeners)
- [ ] Performance benchmarking
- [ ] Advanced chemical operations

---

## To be discussed


### Multi-dialect support

Currently the library is tightly coupled to PostgreSQL, as RDkit extension is only available for PostgreSQL. But technically for Bingo and some other closed source cartridges (e.g ChemAxon) it would be possible to support other databases (e.g MySQL, Oracle).

---


#### **Documentation**
- Container usage guides
- Environment variable reference
- Volume mounting best practices
- Production deployment guides

---

## 🔧 Development Environment

### **For Contributors**

```bash
# Clone and setup
git clone https://github.com/asiomchen/molalchemy.git
cd molalchemy
uv sync

# Start development database
docker-compose up bingo  # or rdkit

# Run tests
make test

# Start documentation server
uv run mkdocs serve
```

### **Development Guidelines**

#### **Code Quality**
- Type hints for all public APIs
- 100% test coverage for new features
- Documentation for all public functions
- Follow existing code patterns

#### **Testing Requirements**
- Unit tests for all functions
- Integration tests for complex workflows
- Performance tests for critical paths
- Docker-based testing for CI/CD

#### **Documentation Standards**
- NumPy-style docstrings
- Working code examples
- API reference completeness
- User guide updates

---

## 🤝 How to Contribute

### **Getting Started**
1. Check the [issues page](https://github.com/asiomchen/molalchemy/issues) for good first issues
2. Read the [Contributing Guide](CONTRIBUTING.md)
3. Join discussions in GitHub Discussions
4. Set up your development environment

### **Contribution Process**
1. Fork the repository
2. Create a feature branch
3. Implement your changes
4. Add tests and documentation
5. Submit a pull request

### **Support**
- GitHub Discussions for questions
- GitHub Issues for bugs and features
- Direct contact: anton.siomchen+molalchemy@gmail.com

---

**molalchemy** - Making chemical databases as easy as regular databases! 🧪✨

*Last updated: September 2025*