How acceleratedscience/openad-toolkit works
Project Type and Purpose
• OpenAD is an open-source, full-featured molecular & materials research toolkit written in Python.
• It exposes a low-code API/CLI, Jupyter Notebook integration (magic commands), and an optional web-based GUI (Flask + WASM).
• It integrates with external LLM services, RDKit via WebAssembly, and supports plugin/toolkit extensions.
High-Level Architecture Analysis
• Layered, modular design with clear separation of concerns:
• User Interfaces (CLI, Jupyter, Web UI)
• Application Orchestration (openad/app, openad/api)
• Core Domain Logic (openad/core, openad/helpers, openad/mmols, openad/smols)
• Service Integrations (openad/llm_assist, openad/openad_model_plugin)
• Static GUI Bundles (openad/gui-build, openad/gui-build-proxy)
• Plugins & Toolkits (openad/plugins, openad/user_toolkits)
• Background Workers (openad/workers/file_system.py)
• External Dependencies (LLM endpoints, RDKit WASM)
Main Components
A. User Interface Layer
1. CLI EntryPoint (openad console script, openad/openad_api.py)
2. Jupyter Notebook Magic (openad/app/magic/openad_magic.py)
3. Web UI Frontend
• Flask Server (openad/app/main.py, openad/flask_apps/routes.py)
• Static Assets & WASM (openad/gui-build, openad/gui-build-proxy, RDKit_minimal.wasm)
B. Application Layer
1. API Handlers (openad/api.py)
2. App Orchestrator (openad/app/*: login_manager, main_lib, memory, metadata.json)
C. Core Domain Layer
1. Language & Grammar Engines (openad/core/grammar.py, lang_*.py)
2. Molecule/Material Commands & Transforms (openad/mmols, openad/smols)
3. Helpers (file I/O, data formats, credentials)
D. Service Integration Layer
1. LLM Assistant (openad/llm_assist/*)
2. Model Plugin Service (openad/openad_model_plugin/*)
3. External LLM APIs (OpenAI, Hugging Face, etc.)
E. Extension Layer
1. Built-in Plugins (openad/plugins/*)
2. User Toolkits (openad/user_toolkits/*)
F. Workers / Background Tasks
• File system operations, long-running jobs (openad/workers/file_system.py)
Relationships & Data Flows
• CLI & Jupyter → Application Layer → Core Domain → Service Integration → External LLMs / RDKit WASM → return results back up
• Web UI Frontend ↔ Flask Server → Application Layer → Core Domain → Services
• Plugins & Toolkits hook into Application Layer via the openad/api or openad/app plugin registries
• Workers handle asynchronous or heavy tasks on behalf of the Application Layer
Architectural Patterns & Principles
• Layered architecture (UI → API/App → Core → Services)
• Plugin/extension architecture (discoverable plugins in openad/plugins and user_toolkits)
• MVC in the Flask component (routes serve static bundle + JSON endpoints)
• Separation of concerns: UI code (JS/WASM) vs. business logic (Python)
• Low-code integration: single python package exposes CLI, API, Jupyter magic
Technologies & Frameworks to Annotate
• Python 3.x, Flask (web server), Jupyter/IPython magic
• JavaScript/TypeScript front end, WebAssembly (RDKit)
• HTTP/REST for Web UI ↔ Backend
• LLM integration via HTTP/SDKs (OpenAI, etc.)
• Packaging & build: pyproject.toml, Makefile, setup.sh