chemstore 0.1.0__tar.gz

chemstore-0.1.0/PKG-INFO

@@ -0,0 +1,434 @@
+Metadata-Version: 2.4
+Name: chemstore
+Version: 0.1.0
+Summary: High-performance cheminformatics calculation and reaction prediction engine with embedded Bitcask key-value storage
+Keywords: chemistry,cheminformatics,rdkit,smiles,smarts,reaction-prediction,equation-balancer,bitcask
+Author: mark
+Author-email: mark <pythondev677@gmail.com>
+License-Expression: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Chemistry
+Classifier: Programming Language :: Python :: 3.12
+Requires-Dist: fastapi>=0.141.1
+Requires-Dist: pydantic>=2.13.5
+Requires-Dist: rdkit>=2026.3.6
+Requires-Dist: requests>=2.34.2
+Requires-Dist: typer[all]>=0.27.2
+Requires-Dist: uvicorn>=0.53.0
+Requires-Python: >=3.12
+Project-URL: Homepage, https://github.com/munenevictor577-blip/chemstore
+Project-URL: Repository, https://github.com/munenevictor577-blip/chemstore
+Project-URL: Issues, https://github.com/munenevictor577-blip/chemstore/issues
+Description-Content-Type: text/markdown
+
+# ChemStore
+
+ChemStore is a fast, domain-driven chemical informatics toolkit and command-line application equipped with an embedded log-structured (Bitcask-style) storage engine. It provides exact molar mass calculations, stoichiometric chemical equation balancing via linear algebra, and automated organic reaction product prediction.
+
+---
+
+## Features
+
+- **Molar Mass & Formula Calculation**:
+  - Validates and parses SMILES strings into molecular structures using RDKit.
+  - Computes exact molecular weight and Hill-system molecular formulas.
+- **Stoichiometric Chemical Equation Balancing**:
+  - Supports reaction equations with `=` or `>>` operators.
+  - Automatically parses and expands nested polyatomic ion brackets (e.g., `Mg(OH)2` $\rightarrow$ `MgOHOH`).
+  - Solves the null space using exact rational arithmetic (`fractions.Fraction`) via Gaussian elimination, eliminating floating-point rounding errors.
+  - Derives the lowest positive whole-integer stoichiometric coefficients using Least Common Multiple (LCM) scaling.
+- **Intelligent Organic Reaction Product Prediction**:
+  - Curated library of standard organic reaction templates (Amide coupling, Fischer esterification, Suzuki coupling, Diels-Alder, Williamson-style ether synthesis, Imine formation, Saponification, and Alkene hydrogenation).
+  - **Zero-Configuration Automatic Reaction Detection**: Intelligently identifies compatible reactions from input reactant SMILES without requiring the user to specify the reaction type.
+  - **Order-Independent Matching**: Permutes reactants to match template reaction centers regardless of the order provided (e.g., alcohol + acid vs. acid + alcohol).
+  - Custom Reaction SMARTS support for advanced user-defined reactions.
+- **Embedded Bitcask Key-Value Cache Engine**:
+  - High-performance append-only binary log storage format with low overhead.
+  - In-memory hash indexing mapping compound keys to disk byte offsets for $O(1)$ random lookups.
+  - Automatic index reconstruction on startup from binary headers.
+  - Online compaction to prune obsolete records and reclaim disk space.
+- **Clean Architecture / Domain-Driven Design (DDD)**:
+  - Clean separation into `domain`, `infrastructure`, `usecases`, and `cli` layers for high maintainability, modularity, and testability.
+
+---
+
+## Architecture
+
+The project adheres to Clean Architecture principles:
+
+```
+src/chemstore/
+├── domain/                      # Enterprise business rules & entities (pure domain)
+│   ├── compound.py              # Compound entity (SMILES parsing, molecular mass & formula)
+│   ├── Equation.py              # Equation model, matrix composition, & rational Gaussian null-space solver
+│   ├── reaction.py              # ReactionPredictor (isolated domain logic)
+│   └── repository.py            # Abstract ChemicalRepository interface
+├── data/
+│   └── reaction_templates.json  # Externalized JSON reaction SMARTS definitions
+├── api/                         # FastAPI HTTP REST API service
+│   ├── main.py                  # Endpoint declarations & error handling
+│   ├── models.py                # Pydantic request & response schemas
+│   └── dependencies.py          # Use case dependency injection
+├── infrastructure/              # External systems & persistence mechanisms
+│   ├── smarts_loader.py         # On-demand reaction SMARTS template loader
+│   ├── storage/
+│   │   ├── append_log.py        # Low-level binary append-only disk logger
+│   │   └── engine.py            # ChemStoreEngine (Bitcask key-value store with compaction)
+│   └── repository_impl.py       # KVChemicalRepository implementation
+├── usecases/                    # Application use cases orchestrating domain models & cache
+│   ├── calculate_mass.py        # CalculateMassUseCase (cache-aside mass lookup)
+│   ├── balance_equation.py      # BalanceEquationUseCase (cache-aside equation balancing)
+│   └── predict_reaction.py      # PredictReactionUseCase (auto-detection & cached product prediction)
+└── cli/
+    └── main.py                  # CLI entry point (argparse)
+```
+
+### Storage Engine Architecture (Bitcask Log)
+
+Every record is stored sequentially in an append-only binary file using an 8-byte little-endian header:
+
+```
++-------------------+---------------------+------------------+--------------------+
+| Key Size (4 bytes)| Value Size (4 bytes)| Key UTF-8 Bytes  | Value UTF-8 Bytes  |
++-------------------+---------------------+------------------+--------------------+
+```
+
+1. **Write Path (`put`)**: Appends record to the end of the log file, returns the file offset, and updates the in-memory hash table: `index[key] = offset`.
+2. **Read Path (`get`)**: Performs an $O(1)$ in-memory index lookup to get the byte offset, jumps (`seek`) directly to that offset in the log, unpacks the header, and reads the value.
+3. **Recovery (`_build_index`)**: On startup, sequentially scans the log headers to reconstruct the in-memory hash index without loading payloads.
+4. **Compaction (`compact`)**: Rewrites only the latest values of active keys to a fresh file, discarding dead and overwritten records.
+
+---
+
+## Installation
+
+### Requirements
+- Python `>= 3.12`
+- `uv` (recommended) or `pip`
+
+### Setup with `uv`
+
+```bash
+git clone https://github.com/your-org/chemstore.git
+cd chemstore
+
+# Install dependencies and package in editable mode
+uv pip install -e .
+```
+
+### Setup with `venv` & `pip`
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e .
+```
+
+---
+
+## CLI Usage
+
+The package installs the `chemstore` command-line utility.
+
+```
+usage: chemstore [-h] {mass,balance,predict,admin} ...
+```
+
+### 1. Calculate Molar Mass (`mass`)
+
+Calculates the molecular weight from a SMILES string:
+
+```bash
+# Ethanol
+chemstore mass "CCO"
+# Output:
+# 46.041864812
+
+# Caffeine
+chemstore mass "CN1C=NC2=C1C(=O)N(C(=O)N2C)C"
+# Output:
+# 194.08037556
+```
+
+If cached, subsequent lookups retrieve the mass directly from the local Bitcask engine with near-zero latency.
+
+---
+
+### 2. Balance Chemical Equations (`balance`)
+
+Balances equations containing `=` or `>>`, automatically handling polyatomic groups and complex stoichiometries:
+
+```bash
+# Simple combustion
+chemstore balance "H2 + O2 = H2O"
+# Output:
+# 2H2 + O2 = 2H2O
+
+# Alkane combustion
+chemstore balance "C2H6 + O2 = CO2 + H2O"
+# Output:
+# 2C2H6 + 7O2 = 4CO2 + 6H2O
+
+# Yield operator (>>)
+chemstore balance "C2H6 + O2 >> CO2 + H2O"
+# Output:
+# 2C2H6 + 7O2 >> 4CO2 + 6H2O
+
+# Polyatomic brackets
+chemstore balance "Mg(OH)2 + HCl = MgCl2 + H2O"
+# Output:
+# Mg(OH)2 + 2HCl = MgCl2 + 2H2O
+```
+
+---
+
+### 3. Predict Reaction Products (`predict`)
+
+#### Automatic Reaction Detection (No Reaction Name Needed)
+Simply provide the reactant SMILES. ChemStore automatically identifies the matching reaction template and evaluates the products:
+
+```bash
+# Esterification (acetic acid + ethanol)
+chemstore predict "CC(=O)O" "CCO"
+# Output:
+# Reactants: CC(=O)O + CCO
+# Reaction: esterification (auto-detected)
+# Products: CCOC(C)=O
+
+# Order-independent (ethanol first, acetic acid second)
+chemstore predict "CCO" "CC(=O)O"
+# Output:
+# Reactants: CCO + CC(=O)O
+# Reaction: esterification (auto-detected)
+# Products: CCOC(C)=O
+
+# Diels-Alder (butadiene + ethylene)
+chemstore predict "C=CC=C" "C=C"
+# Output:
+# Reactants: C=CC=C + C=C
+# Reaction: diels_alder (auto-detected)
+# Products: C1=CCCCC1
+
+# Alkene hydrogenation
+chemstore predict "CC=CC"
+# Output:
+# Reactants: CC=CC
+# Reaction: alkene_hydrogenation (auto-detected)
+# Products: CCCC
+```
+
+#### List Available Reaction Templates (`--list` / `-l`)
+
+```bash
+chemstore predict --list
+```
+Output:
+```
+Available reactions:
+  amide_coupling        : Amide coupling: carboxylic acid + amine -> amide
+  esterification        : Fischer esterification: carboxylic acid + alcohol -> ester
+  suzuki_coupling       : Suzuki coupling: aryl halide + boronic acid -> biaryl
+  diels_alder           : Diels-Alder: diene + dienophile -> cyclohexene
+  ether_synthesis       : Ether synthesis: alkyl halide + alcohol -> ether
+  imine_formation       : Imine formation: carbonyl (aldehyde/ketone) + primary amine -> imine
+  saponification        : Saponification / ester hydrolysis: ester -> acid + alcohol
+  alkene_hydrogenation  : Alkene hydrogenation: alkene -> alkane
+```
+
+#### Explicit Reaction Selection (`--reaction` / `-r`)
+
+```bash
+chemstore predict "CC(=O)O" "CCO" --reaction esterification
+# Output:
+# Reactants: CC(=O)O + CCO
+# Reaction: esterification
+# Products: CCOC(C)=O
+```
+
+#### Custom SMARTS Rule (`--smarts` / `-s`)
+
+You can provide custom RDKit reaction SMARTS to predict arbitrary transformations:
+
+```bash
+chemstore predict "CC(=O)O" "CN" --smarts "[O:2]=[C:1][OH:3].[N:4]>>[O:2]=[C:1][N:4]"
+```
+
+---
+
+### 4. Database Operations (`admin`)
+
+Reclaim disk space by running log compaction on the cache database:
+
+```bash
+chemstore admin --compact
+# Output:
+# Connecting to the embedded database...
+# Compaction complete.
+```
+
+---
+
+## Python API Usage
+
+ChemStore can be integrated directly into Python scripts:
+
+### Molecular Mass & Formulas
+
+```python
+from chemstore.domain.compound import Compound
+
+compound = Compound("CN1C=NC2=C1C(=O)N(C(=O)N2C)C")
+print("Formula:", compound.formula)                   # C8H10N4O2
+print("Molecular Weight:", compound.molecular_weight) # 194.0803...
+```
+
+### Chemical Equation Balancing
+
+```python
+from chemstore.domain.Equation import Equation
+
+eq = Equation("C2H6 + O2 = CO2 + H2O")
+print(eq.balanced)  # 2C2H6 + 7O2 = 4CO2 + 6H2O
+```
+
+### Reaction Prediction
+
+```python
+from chemstore.domain.reaction import ReactionPredictor
+
+# 1. Automatic reaction detection
+matches = ReactionPredictor.auto_predict(["CC(=O)O", "CCO"])
+for name, products in matches:
+    print(f"Reaction: {name}, Products: {products}")
+# Reaction: esterification, Products: ['CCOC(C)=O']
+
+# 2. Named reaction by factory
+predictor = ReactionPredictor.from_name("diels_alder")
+products = predictor.run(["C=CC=C", "C=C"])
+print("Products:", products)  # ['C1=CCCCC1']
+
+# 3. Custom SMARTS rule
+custom_predictor = ReactionPredictor("[C:1](=[O:2])[OH].[N:3]>>[C:1](=[O:2])[N:3]")
+products = custom_predictor.run(["CC(=O)O", "CN"])
+print("Products:", products)  # ['CNC(C)=O']
+```
+
+### Using Cached Use Cases
+
+```python
+from chemstore.infrastructure.repository_impl import KVChemicalRepository
+from chemstore.usecases.calculate_mass import CalculateMassUseCase
+from chemstore.usecases.predict_reaction import PredictReactionUseCase
+
+repo = KVChemicalRepository("chemistry_cache.db")
+
+# Calculate mass with cache persistence
+mass_calc = CalculateMassUseCase(repo)
+mass = mass_calc.execute("CCO")
+
+# Predict reaction with cache persistence (auto-detection)
+rxn_calc = PredictReactionUseCase(repo)
+products = rxn_calc.execute(None, ["CC(=O)O", "CCO"])
+```
+
+---
+
+## REST API Service (FastAPI)
+
+ChemStore includes a FastAPI HTTP service exposing calculation and prediction endpoints. To support reverse-proxy routing (e.g. routing all `chemstore` traffic to `/chem`), endpoints are routed under `/chem/api/v1/...` while preserving `/api/v1/...` for direct calls and backward compatibility:
+
+```bash
+# Start the API server
+uvicorn chemstore.api.main:app --host 0.0.0.0 --port 8000 --reload
+```
+
+### Available Endpoints:
+- `POST /chem/api/v1/mass` (or `/api/v1/mass`)
+- `POST /chem/api/v1/balance` (or `/api/v1/balance`)
+- `POST /chem/api/v1/predict` (or `/api/v1/predict`)
+
+### Reaction Prediction Endpoint (`POST /chem/api/v1/predict`)
+
+Supports explicit reaction names, custom SMARTS strings, or zero-configuration auto-detection:
+
+#### With Reaction Name:
+```bash
+curl -X POST http://localhost:8000/chem/api/v1/predict \
+  -H "Content-Type: application/json" \
+  -d '{"reactants": ["CC(=O)O", "CCN"], "reaction_name": "amide_coupling"}'
+```
+Response:
+```json
+{
+  "reactants": ["CC(=O)O", "CCN"],
+  "reaction_name": "amide_coupling",
+  "reaction": "amide_coupling",
+  "products": ["CCNC(C)=O"]
+}
+```
+
+#### With Automatic Detection:
+```bash
+curl -X POST http://localhost:8000/chem/api/v1/predict \
+  -H "Content-Type: application/json" \
+  -d '{"reactants": ["CC(=O)O", "CCO"]}'
+```
+Response:
+```json
+{
+  "reactants": ["CC(=O)O", "CCO"],
+  "reaction_name": "esterification",
+  "reaction": "esterification",
+  "products": ["CCOC(C)=O"]
+}
+```
+
+---
+
+## Predefined Reaction Catalog
+
+| Identifier | Name | Reaction Transformation | SMARTS Rule |
+| :--- | :--- | :--- | :--- |
+| `amide_coupling` | Amide Coupling | Carboxylic Acid + Amine $\rightarrow$ Amide | `[O:2]=[C:1][OH:3].[N:4]>>[O:2]=[C:1][N:4]` |
+| `esterification` | Fischer Esterification | Carboxylic Acid + Alcohol $\rightarrow$ Ester | `[C:1](=[O:2])[OH].[O:3][C:4]>>[C:1](=[O:2])[O:3][C:4]` |
+| `suzuki_coupling` | Suzuki Coupling | Aryl Halide + Boronic Acid $\rightarrow$ Biaryl | `[c:1][Br,I,Cl].[c:2]B(O)O>>[c:1][c:2]` |
+| `diels_alder` | Diels-Alder Cycloaddition | Conjugated Diene + Dienophile $\rightarrow$ Cyclohexene | `[C:1]=[C:2][C:3]=[C:4].[C:5]=[C:6]>>[C:1]1[C:2]=[C:3][C:4][C:5][C:6]1` |
+| `ether_synthesis` | Ether Synthesis | Alkyl Halide + Alcohol $\rightarrow$ Ether | `[C:1][Br,I,Cl].[O:2][C:3]>>[C:1][O:2][C:3]` |
+| `imine_formation` | Imine Formation | Carbonyl (Aldehyde/Ketone) + Primary Amine $\rightarrow$ Imine | `[C;!$(C[O,N,S,Cl,Br,I,F]):1]=[O:2].[N;H2:3]>>[C:1]=[N:3]` |
+| `saponification` | Saponification | Ester $\rightarrow$ Carboxylic Acid + Alcohol | `[C:1](=[O:2])[O:3][C:4]>>[C:1](=[O:2])[OH].[O:3][C:4]` |
+| `alkene_hydrogenation` | Alkene Hydrogenation | Alkene $\rightarrow$ Alkane | `[C:1]=[C:2]>>[C:1][C:2]` |
+| `alkane_chlorination` | Radical Chlorination | Alkane + $\text{Cl}_2$ $\rightarrow$ Alkyl Chloride | `[CX4;!H0:1]>>[C:1]Cl` |
+| `alkane_bromination_tertiary` | Tertiary Radical Bromination | 3° Alkane + $\text{Br}_2$ $\rightarrow$ Tertiary Alkyl Bromide | `[CX4;H1:1]>>[C:1]Br` |
+| `alkane_dehydrogenation` | Alkane Dehydrogenation | Alkane $\rightarrow$ Alkene + $\text{H}_2$ | `[CX4;!H0:1]-[CX4;!H0:2]>>[C:1]=[C:2]` |
+| `alkane_nitration` | Gas-Phase Nitration | Alkane + $\text{HNO}_3$ $\rightarrow$ Nitroalkane + $\text{H}_2\text{O}$ | `[CX4;!H0:1]>>[C:1][N+](=[O])[O-]` |
+| `alkane_sulfoxidation` | Alkane Sulfoxidation | Alkane + $\text{SO}_2$ + $\text{O}_2$ $\rightarrow$ Alkanesulfonic Acid | `[CX4;!H0:1]>>[C:1]S(=O)(=O)O` |
+
+---
+
+## Testing
+
+ChemStore includes an extensive suite of automated tests covering domain logic, storage persistence, repository caching, and CLI workflows.
+
+Run the test suite using `pytest`:
+
+```bash
+# Run all tests
+.venv/bin/pytest
+
+# Run with verbose output
+.venv/bin/pytest -v
+```
+
+### Test Coverage Highlights
+- **Domain Tests** (`tests/domain/`): Valid/invalid SMILES parsing, polyatomic equation parsing, yield operator balancing, reaction templates, auto-prediction, order-independence.
+- **Infrastructure Tests** (`tests/infrastructure/`): Low-level append log writes, byte offset seeks, index recovery on startup, compaction, tombstone eviction, and on-demand JSON SMARTS template loading.
+- **API Tests** (`tests/test_api.py`): Mass calculation, chemical equation balancing, and reaction prediction with named reactions, custom SMARTS, auto-detection, and error responses.
+- **Use Case Integration Tests** (`tests/test_repository.py`): Cache hits, cache writes, fallback lookups, and multi-round verification.
+- **CLI Subprocess Tests** (`tests/test_cli.py`): Execution and error exits across `mass`, `balance`, `predict`, and `admin`.
+
+---
+
+## License
+
+This project is licensed under the MIT License.