cdxml-toolkit 0.5.0__py3-none-any.whl

cdxml_toolkit/office/ole_extractor.py

@@ -0,0 +1,272 @@
+#!/usr/bin/env python3
+"""
+OLE Extractor — Extract embedded ChemDraw objects from .pptx and .docx files.
+
+Office files (PPTX/DOCX) are ZIP archives containing OLE compound documents
+as binary blobs. ChemDraw objects are stored as CDX data inside the OLE
+"CONTENTS" stream. This tool extracts and optionally converts them to CDXML.
+
+Usage:
+    python ole_extractor.py input.pptx [-o output_dir/] [--format cdxml|cdx|both]
+    python ole_extractor.py input.docx [-o output_dir/] [--format cdxml|cdx|both]
+
+Requires: olefile, cdx_converter (for CDXML conversion)
+"""
+
+import argparse
+import io
+import os
+import sys
+import zipfile
+from dataclasses import dataclass, field
+from typing import List, Optional
+
+import olefile
+
+# ChemDraw OLE CLSID (CS ChemDraw Drawing / CS ChemDraw 3D)
+CHEMDRAW_CLSIDS = {
+    "41BA6D21-A02E-11CE-8FD9-0020AFD1F20C",  # ChemDraw Drawing
+}
+
+# CDX binary magic bytes
+CDX_MAGIC = b"VjCD"
+
+# Where Office stores OLE embeddings
+EMBEDDING_PATTERNS = {
+    ".pptx": "ppt/embeddings/",
+    ".docx": "word/embeddings/",
+}
+
+
+@dataclass
+class ExtractedObject:
+    """A single extracted ChemDraw object."""
+    source_path: str  # path inside ZIP (e.g. ppt/embeddings/oleObject1.bin)
+    cdx_data: bytes
+    cdx_output: Optional[str] = None  # path where CDX was saved
+    cdxml_output: Optional[str] = None  # path where CDXML was saved
+    error: Optional[str] = None
+
+
+def find_ole_entries(zip_path: str) -> List[str]:
+    """List OLE embedding paths inside a PPTX/DOCX ZIP."""
+    ext = os.path.splitext(zip_path)[1].lower()
+    prefix = EMBEDDING_PATTERNS.get(ext)
+    if prefix is None:
+        raise ValueError(
+            f"Unsupported file type: {ext}. Use .pptx or .docx."
+        )
+
+    with zipfile.ZipFile(zip_path, "r") as zf:
+        return [
+            name for name in zf.namelist()
+            if name.startswith(prefix) and name.lower().endswith(".bin")
+        ]
+
+
+def is_chemdraw_ole(ole: olefile.OleFileIO) -> bool:
+    """Check if an OLE container holds a ChemDraw object."""
+    # Check CLSID
+    clsid = ole.root.clsid.upper() if ole.root.clsid else ""
+    if clsid in CHEMDRAW_CLSIDS:
+        return True
+
+    # Check for CONTENTS stream with CDX magic
+    if ole.exists("CONTENTS"):
+        header = ole.openstream("CONTENTS").read(4)
+        if header == CDX_MAGIC:
+            return True
+
+    return False
+
+
+def extract_cdx_from_ole(ole_data: bytes) -> Optional[bytes]:
+    """Extract raw CDX bytes from an OLE compound document."""
+    if not olefile.isOleFile(io.BytesIO(ole_data)):
+        return None
+
+    ole = olefile.OleFileIO(io.BytesIO(ole_data))
+    try:
+        if not is_chemdraw_ole(ole):
+            return None
+
+        if ole.exists("CONTENTS"):
+            cdx = ole.openstream("CONTENTS").read()
+            if cdx[:4] == CDX_MAGIC:
+                return cdx
+
+        # Fallback: check \x01Ole10Native stream
+        if ole.exists("\x01Ole10Native"):
+            data = ole.openstream("\x01Ole10Native").read()
+            # Skip 4-byte length prefix
+            if len(data) > 4 and data[4:8] == CDX_MAGIC:
+                return data[4:]
+
+        return None
+    finally:
+        ole.close()
+
+
+def extract_from_office(
+    input_path: str,
+    output_dir: Optional[str] = None,
+    output_format: str = "cdxml",
+    convert_method: str = "auto",
+) -> List[ExtractedObject]:
+    """Extract all ChemDraw objects from a PPTX/DOCX file.
+
+    Args:
+        input_path: Path to .pptx or .docx file.
+        output_dir: Directory for extracted files. Default: <basename>_chemdraw/
+        output_format: "cdx", "cdxml", or "both".
+        convert_method: Backend for CDX→CDXML conversion (passed to cdx_converter).
+
+    Returns:
+        List of ExtractedObject with extraction results.
+    """
+    if output_dir is None:
+        basename = os.path.splitext(os.path.basename(input_path))[0]
+        output_dir = os.path.join(os.path.dirname(input_path) or ".", f"{basename}_chemdraw")
+
+    os.makedirs(output_dir, exist_ok=True)
+
+    # Lazy import — only needed if converting to CDXML
+    _converter = None
+    if output_format in ("cdxml", "both"):
+        try:
+            from ..chemdraw import cdx_converter
+            _converter = cdx_converter
+        except ImportError:
+            print(
+                "Warning: cdx_converter not found. CDX files will be saved "
+                "but CDXML conversion is unavailable.",
+                file=sys.stderr,
+            )
+
+    ole_entries = find_ole_entries(input_path)
+    results = []
+
+    with zipfile.ZipFile(input_path, "r") as zf:
+        for entry in ole_entries:
+            ole_data = zf.read(entry)
+            cdx_data = extract_cdx_from_ole(ole_data)
+
+            if cdx_data is None:
+                # Not a ChemDraw object — skip silently
+                continue
+
+            # Derive output filename from ZIP entry
+            entry_name = os.path.splitext(os.path.basename(entry))[0]
+            obj = ExtractedObject(source_path=entry, cdx_data=cdx_data)
+
+            # Save CDX
+            if output_format in ("cdx", "both"):
+                cdx_path = os.path.join(output_dir, f"{entry_name}.cdx")
+                with open(cdx_path, "wb") as f:
+                    f.write(cdx_data)
+                obj.cdx_output = cdx_path
+
+            # Convert to CDXML
+            if output_format in ("cdxml", "both"):
+                cdxml_path = os.path.join(output_dir, f"{entry_name}.cdxml")
+                if _converter is not None:
+                    try:
+                        cdxml_str = _converter.convert_cdx_to_cdxml(
+                            cdx_data, method=convert_method
+                        )
+                        with open(cdxml_path, "w", encoding="utf-8") as f:
+                            f.write(cdxml_str)
+                        obj.cdxml_output = cdxml_path
+                    except Exception as e:
+                        obj.error = f"CDXML conversion failed: {e}"
+                        # Still save CDX as fallback
+                        if obj.cdx_output is None:
+                            fallback = os.path.join(output_dir, f"{entry_name}.cdx")
+                            with open(fallback, "wb") as f:
+                                f.write(cdx_data)
+                            obj.cdx_output = fallback
+                else:
+                    # No converter — save CDX instead
+                    if obj.cdx_output is None:
+                        fallback = os.path.join(output_dir, f"{entry_name}.cdx")
+                        with open(fallback, "wb") as f:
+                            f.write(cdx_data)
+                        obj.cdx_output = fallback
+                    obj.error = "cdx_converter unavailable; saved CDX only"
+
+            results.append(obj)
+
+    return results
+
+
+def print_summary(results: List[ExtractedObject], input_path: str) -> None:
+    """Print extraction summary to stdout."""
+    print(f"{'=' * 60}")
+    print(f"OLE Extractor - {os.path.basename(input_path)}")
+    print(f"{'=' * 60}")
+
+    if not results:
+        print("No ChemDraw objects found.")
+        return
+
+    print(f"Found {len(results)} ChemDraw object(s):\n")
+    for i, obj in enumerate(results, 1):
+        print(f"  [{i}] {obj.source_path}")
+        print(f"      CDX size: {len(obj.cdx_data):,} bytes")
+        if obj.cdx_output:
+            print(f"      CDX:   {obj.cdx_output}")
+        if obj.cdxml_output:
+            size = os.path.getsize(obj.cdxml_output)
+            print(f"      CDXML: {obj.cdxml_output} ({size:,} bytes)")
+        if obj.error:
+            print(f"      Note:  {obj.error}")
+        print()
+
+
+# ---------------------------------------------------------------------------
+# CLI
+# ---------------------------------------------------------------------------
+
+def main(argv=None) -> int:
+    parser = argparse.ArgumentParser(
+        description="Extract embedded ChemDraw objects from .pptx/.docx files."
+    )
+    parser.add_argument("input", help="Input file (.pptx or .docx)")
+    parser.add_argument(
+        "-o", "--output-dir",
+        help="Output directory (default: <input_basename>_chemdraw/)"
+    )
+    parser.add_argument(
+        "--format",
+        choices=["cdxml", "cdx", "both"],
+        default="cdxml",
+        help="Output format (default: cdxml)"
+    )
+    parser.add_argument(
+        "--method",
+        choices=["auto", "com", "pycdxml", "obabel"],
+        default="auto",
+        help="CDX→CDXML conversion backend (default: auto)"
+    )
+    args = parser.parse_args(argv)
+
+    if not os.path.isfile(args.input):
+        print(f"Error: file not found: {args.input}", file=sys.stderr)
+        return 1
+
+    try:
+        results = extract_from_office(
+            args.input,
+            output_dir=args.output_dir,
+            output_format=args.format,
+            convert_method=args.method,
+        )
+        print_summary(results, args.input)
+        return 0
+    except Exception as e:
+        print(f"Error: {e}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

cdxml_toolkit/perception/__init__.py

@@ -0,0 +1,10 @@
+"""Perception — reading and understanding reaction schemes.
+
+Everything about extracting semantic meaning from CDXML: which fragments are
+reactants vs products vs reagents, what the arrows connect, what the text
+labels mean.
+"""
+
+from .scheme_reader import read_scheme, SchemeDescription
+from .reaction_parser import parse_reaction, ReactionDescriptor, reaction_summary
+from .scheme_segmenter import segment_scheme, classify_scheme_complexity

cdxml_toolkit/perception/compound_search.py

@@ -0,0 +1,229 @@
+#!/usr/bin/env python3
+"""
+compound_search.py — Search for a molecule across a directory of experiments.
+
+Given a query SMILES and a directory of experiment subdirectories (each
+containing ELN exports: .cdxml, .csv, .rxn), parses every experiment and
+compares the query against all species using RDKit exact-match and Tanimoto
+fingerprint similarity.
+
+Python API:
+    from cdxml_toolkit.perception.compound_search import search_compound
+    results = search_compound(
+        smiles="NCCCCCOc1cccc2c1C(=O)N(C1CCC(=O)NC1=O)C2=O",
+        experiment_dir="/path/to/KL-7001",
+    )
+"""
+
+from __future__ import annotations
+
+import traceback
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _canonical(smiles: str) -> Optional[str]:
+    """Return canonical SMILES, or None if invalid."""
+    try:
+        from rdkit import Chem
+        mol = Chem.MolFromSmiles(smiles)
+        if mol is None:
+            return None
+        return Chem.MolToSmiles(mol)
+    except Exception:
+        return None
+
+
+def _morgan_fp(smiles: str):
+    """Return Morgan fingerprint (radius=2, 2048 bits), or None."""
+    try:
+        from rdkit import Chem
+        from rdkit.Chem import AllChem
+        mol = Chem.MolFromSmiles(smiles)
+        if mol is None:
+            return None
+        return AllChem.GetMorganFingerprintAsBitVect(mol, radius=2, nBits=2048)
+    except Exception:
+        return None
+
+
+def _tanimoto(fp1, fp2) -> float:
+    """Tanimoto similarity between two RDKit fingerprints."""
+    from rdkit import DataStructs
+    return DataStructs.TanimotoSimilarity(fp1, fp2)
+
+
+def _discover_files(exp_dir: Path):
+    """Return (cdxml_path, csv_path) for a single experiment subdirectory."""
+    cdxml_files = list(exp_dir.glob("*.cdxml"))
+    csv_files = list(exp_dir.glob("*.csv"))
+    cdxml = str(cdxml_files[0]) if cdxml_files else None
+    csv = str(csv_files[0]) if csv_files else None
+    return cdxml, csv
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+def search_compound(
+    smiles: str,
+    experiment_dir: str,
+    similarity_threshold: float = 0.85,
+) -> Dict[str, Any]:
+    """Search for a molecule (by SMILES) across all experiments in a directory.
+
+    Args:
+        smiles: Query molecule as a SMILES string.
+        experiment_dir: Path to a directory whose immediate subdirectories are
+            individual experiments (each containing .cdxml / .csv files).
+        similarity_threshold: Minimum Tanimoto similarity (0–1) for a species
+            to appear in ``similar_matches``.  Exact matches (same canonical
+            SMILES) are always reported regardless of this threshold.
+
+    Returns:
+        A dict with keys:
+            ok (bool), query_smiles (str), query_canonical (str),
+            exact_matches (list), similar_matches (list),
+            experiments_searched (int), experiments_parsed_ok (int),
+            parse_errors (list of {"experiment": str, "error": str}).
+    """
+    from cdxml_toolkit.perception.reaction_parser import parse_reaction
+
+    # Validate query
+    query_canonical = _canonical(smiles)
+    if query_canonical is None:
+        return {
+            "ok": False,
+            "error": f"Invalid query SMILES: {smiles!r}",
+            "query_smiles": smiles,
+        }
+
+    query_fp = _morgan_fp(query_canonical)
+
+    root = Path(experiment_dir)
+    if not root.is_dir():
+        return {
+            "ok": False,
+            "error": f"experiment_dir does not exist or is not a directory: {experiment_dir!r}",
+            "query_smiles": smiles,
+        }
+
+    # Collect experiment subdirectories (immediate children only)
+    exp_dirs = sorted(p for p in root.iterdir() if p.is_dir())
+
+    exact_matches: List[Dict[str, Any]] = []
+    similar_matches: List[Dict[str, Any]] = []
+    parse_errors: List[Dict[str, str]] = []
+    experiments_parsed_ok = 0
+
+    for exp_dir in exp_dirs:
+        exp_name = exp_dir.name
+        cdxml, csv = _discover_files(exp_dir)
+
+        if cdxml is None:
+            # No CDXML → skip silently (no reaction to parse)
+            continue
+
+        try:
+            desc = parse_reaction(
+                cdxml=cdxml,
+                csv=csv,
+                use_network=False,  # keep offline for batch search
+                verbose=False,
+            )
+        except Exception as exc:
+            parse_errors.append({
+                "experiment": exp_name,
+                "error": f"{type(exc).__name__}: {exc}",
+                "traceback": traceback.format_exc(),
+            })
+            continue
+
+        experiments_parsed_ok += 1
+
+        # Pull eln_data fields once per experiment
+        eln = desc.eln_data or {}
+        product_yield = eln.get("product_yield")
+        product_obtained = eln.get("product_obtained")
+        sm_mass = eln.get("sm_mass")
+
+        for sp in desc.species:
+            # Prefer the full SMILES; also check neutral form for exact matching
+            sp_smiles = sp.smiles or sp.smiles_neutral
+            if not sp_smiles:
+                continue
+
+            sp_canonical = _canonical(sp_smiles)
+            if sp_canonical is None:
+                continue
+
+            # Neutral canonical (largest fragment, salt-stripped) for comparison
+            sp_neutral_canonical = (
+                _canonical(sp.smiles_neutral) if sp.smiles_neutral else None
+            )
+
+            # --- Exact match ---
+            # Check both the full canonical and the neutral (salt-free) form.
+            # This lets "NCCCCCOc1..." match "Cl.NCCCCCOc1..." (HCl salt).
+            matched_as_exact = (
+                sp_canonical == query_canonical
+                or (sp_neutral_canonical and sp_neutral_canonical == query_canonical)
+            )
+            if matched_as_exact:
+                reported_smiles = (
+                    sp_neutral_canonical
+                    if sp_neutral_canonical == query_canonical
+                    else sp_canonical
+                )
+                record: Dict[str, Any] = {
+                    "experiment": exp_name,
+                    "species_name": sp.name or sp.id,
+                    "role": sp.role,
+                    "smiles": reported_smiles,
+                }
+                if sp_canonical != reported_smiles:
+                    record["smiles_full"] = sp_canonical  # show the salt form too
+                if product_yield:
+                    record["yield"] = product_yield
+                if product_obtained:
+                    record["amount_obtained"] = product_obtained
+                if sm_mass:
+                    record["sm_mass"] = sm_mass
+                exact_matches.append(record)
+                continue  # don't also report as similar
+
+            # --- Similarity match ---
+            # Use the neutral form for fingerprint comparison when available
+            # (avoids artificially low similarity for salt vs free base).
+            fp_smiles = sp_neutral_canonical or sp_canonical
+            if query_fp is not None:
+                sp_fp = _morgan_fp(fp_smiles)
+                if sp_fp is not None:
+                    sim = _tanimoto(query_fp, sp_fp)
+                    if sim >= similarity_threshold:
+                        similar_matches.append({
+                            "experiment": exp_name,
+                            "species_name": sp.name or sp.id,
+                            "role": sp.role,
+                            "similarity": round(sim, 4),
+                            "smiles": sp_canonical,
+                        })
+
+    # Sort similar matches by descending similarity
+    similar_matches.sort(key=lambda x: x["similarity"], reverse=True)
+
+    return {
+        "ok": True,
+        "query_smiles": smiles,
+        "query_canonical": query_canonical,
+        "exact_matches": exact_matches,
+        "similar_matches": similar_matches,
+        "experiments_searched": len(exp_dirs),
+        "experiments_parsed_ok": experiments_parsed_ok,
+        "parse_errors": parse_errors,
+    }