Python Chemistry Service
Relevant source files
The following files were used as context for generating this wiki page:
The Python Chemistry Service (internally referred to as chem-service) is a specialized backend component of the cheMD ecosystem. Its primary purpose is to provide high-level chemical data processing capabilities, including Optical Character Recognition (OCR) for chemical structures, SMILES/Molfile normalization, and structure rendering fallbacks. It serves as a bridge between raw image input and the structured semantic AST used by the core application.
Within the broader project architecture, the service acts as a supporting utility for the web application and the resolution pipeline. While the core chemd parser and resolver are implemented in TypeScript, this Python-based service handles computationally intensive chemistry tasks that benefit from mature chemical informatics libraries and OCR models.
Sources: services/chem-service/app.py:1-4, chemd-v0.1-architecture.md:59-100, apps/web/src/app/page.tsx:210-230
Service Architecture and Configuration
The service is built using the Flask web framework and is designed to handle chemical structure records with an internal caching mechanism. It utilizes environment variables for configuration, allowing for flexible deployment across different environments.
Core Configuration
The service relies on several environment variables to define its operational limits, such as maximum content lengths for uploads and cache sizes.
| Variable | Description | Default Value |
|---|---|---|
CHEM_SERVICE_MAX_CONTENT_LENGTH | Max allowed payload size | 5,242,880 bytes (5MB) |
CHEM_SERVICE_CACHE_MAX_ENTRIES | Max entries in the structure cache | 256 |
CHEM_SERVICE_MAX_IMAGE_BASE64_LENGTH | Max length for OCR base64 strings | 4,194,304 bytes (4MB) |
CHEM_SERVICE_PORT | Port for the service to listen on | 18081 |
CHEM_SERVICE_ALLOW_ORIGINS | Permitted CORS origins | http://127.0.0.1:2436, http://localhost:2436 |
Sources: services/chem-service/app.py:15-56, services/chem-service/app.py:228-232
Cache Logic and Data Model
The service maintains an in-memory cache of StructureRecord objects. These records link specific blocks within a chemd document to their chemical representations (SMILES or Molfile).
The cache employs a Time-To-Live (TTL) of 300 seconds and automatically prunes expired records or the oldest entries when the capacity limit is reached.
Sources: services/chem-service/app.py:59-111
API Endpoints
The Chemistry Service exposes several RESTful endpoints to facilitate chemistry-related workflows in the cheMD frontend.
Optical Character Recognition (OCR)
The /ocr endpoint is designed to accept base64 encoded images of chemical structures. In the current v0.1 implementation, it serves as a placeholder for future integration with models like MolScribe.
- Method:
POST - Input:
{"imageBase64": "..."} - Behavior: Validates image size and presence; returns a failure status if the OCR backend is not yet enabled.
Sources: services/chem-service/app.py:126-146, apps/web/src/app/page.tsx:94-115
Chemical Normalization
The /normalize endpoint processes chemical strings to ensure consistency across the application.
- Method:
POST - Input:
{"smiles": "...", "molfile": "..."} - Output: Returns
canonicalSmilesandnormalizedMolfile. It currently utilizes an RDKit normalization fallback.
Sources: services/chem-service/app.py:149-166
Fallback Rendering
While the primary rendering is handled by renderer-svg using RDKit.js, this service provides a server-side fallback for rendering structures as SVG.
- Method:
POST - Input: SMILES or Molfile data.
- Output: A basic SVG string representing the structure or a placeholder with the label of the structure.
Sources: services/chem-service/app.py:169-196, chemd-v0.1-architecture.md:154-165
Structure Persistence
The /structure endpoint manages the stateful storage of chemical structures associated with specific document blocks.
Integration with cheMD Ecosystem
The service integrates into the cheMD multi-stage pipeline during the render adapter mapping and export stages.
- UI Interaction: The web playground (in
apps/web) triggers OCR viauseImageOcror manual structure edits viaKetcherDialog. - State Management: When a structure is saved, the UI sends a request to the Python service to cache the structure and then updates the local Markdown source with the new SMILES string in a
:::moleculeblock. - Rendering Fallback: If client-side rendering is unavailable, the UI can request an SVG representation from the service's
/renderendpoint.
Sources: chemd-v0.1-architecture.md:46-57, apps/web/src/app/page.tsx:220-250, chemd-v0.1-spec.md:500-520
Summary
The Python Chemistry Service provides essential chemical informatics support to the cheMD platform. By handling normalization, persistence of structure metadata, and providing an interface for OCR, it allows the TypeScript-based frontend to remain lightweight while ensuring chemical data is canonically represented. Its architecture emphasizes safety through strictly enforced content limits and ephemeral caching, ensuring stable operation during the v0.1 development phase.