molbuilder-client 0.1.0__tar.gz

molbuilder_client-0.1.0/.gitignore

@@ -0,0 +1,46 @@
+# Build artifacts
+dist/
+build/
+*.egg-info/
+
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+.Python
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+Desktop.ini
+
+# SQLite databases
+*.db
+*.db-wal
+*.db-shm
+
+# Environment
+.env
+
+# Distribution
+*.tar.gz
+*.whl

molbuilder_client-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Wedge Dev Co
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

molbuilder_client-0.1.0/PKG-INFO

@@ -0,0 +1,160 @@
+Metadata-Version: 2.4
+Name: molbuilder-client
+Version: 0.1.0
+Summary: Python SDK for the MolBuilder REST API
+Project-URL: Homepage, https://www.molbuilder.io
+Project-URL: Documentation, https://www.molbuilder.io/docs
+Project-URL: Repository, https://github.com/Taylor-C-Powell/Molecule_Builder
+Author-email: Wedge Dev Co <taylorp661@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api-client,chemistry,molecule,retrosynthesis,smiles
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Chemistry
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# molbuilder-client
+
+Python SDK for the [MolBuilder](https://www.molbuilder.io) REST API.
+
+## Install
+
+```bash
+pip install molbuilder-client
+```
+
+Requires Python 3.11+. The only runtime dependency is [httpx](https://www.python-httpx.org/).
+
+## Quickstart
+
+```python
+from molbuilder_client import MolBuilder
+
+client = MolBuilder(api_key="mb_...")
+
+# Parse a SMILES string
+mol = client.from_smiles("CCO", name="ethanol")
+print(mol.id, mol.num_atoms)  # mol_xxxx 9
+
+# Get molecular properties
+props = client.get_properties(mol.id)
+print(props.formula, props.molecular_weight)  # C2H6O 46.07
+
+# Get 3D coordinates
+structure = client.get_3d(mol.id)
+for atom in structure.atoms:
+    print(atom.symbol, atom.position)
+
+# Look up an element
+fe = client.get_element("Fe")
+print(fe.name, fe.atomic_weight)  # Iron 55.845
+
+# Retrosynthesis
+plan = client.retrosynthesis("c1ccccc1O")  # phenol
+print(plan.routes_found, plan.best_route.total_steps)
+
+# Process evaluation
+proc = client.process_evaluate("CCO", scale_kg=100.0)
+print(proc.cost.total_usd, proc.cost.per_kg_usd)
+```
+
+## Async usage
+
+```python
+import asyncio
+from molbuilder_client import AsyncMolBuilder
+
+async def main():
+    async with AsyncMolBuilder(api_key="mb_...") as client:
+        mol = await client.from_smiles("CCO")
+        props = await client.get_properties(mol.id)
+        print(props.formula)
+
+asyncio.run(main())
+```
+
+## Error handling
+
+All API errors raise typed exceptions that inherit from `MolBuilderError`:
+
+```python
+from molbuilder_client import MolBuilder, ValidationError, RateLimitError
+
+client = MolBuilder(api_key="mb_...")
+
+try:
+    client.from_smiles("not_valid")
+except ValidationError as e:
+    print(f"Bad SMILES: {e.message}")
+except RateLimitError as e:
+    print(f"Slow down! Retry after {e.retry_after}s")
+```
+
+| HTTP Status | Exception                  |
+|-------------|----------------------------|
+| 401         | `AuthenticationError`      |
+| 403         | `ForbiddenError`           |
+| 404         | `NotFoundError`            |
+| 422         | `ValidationError`          |
+| 429         | `RateLimitError`           |
+| 500         | `ServerError`              |
+| 501/503     | `ServiceUnavailableError`  |
+
+## API reference
+
+### Auth
+
+| Method                    | Returns        | Description                         |
+|---------------------------|----------------|-------------------------------------|
+| `register(email)`         | `APIKeyInfo`   | Register a new free-tier API key    |
+| `get_token()`             | `Token`        | Exchange API key for a JWT          |
+
+### Molecule
+
+| Method                        | Returns              | Description                  |
+|-------------------------------|----------------------|------------------------------|
+| `from_smiles(smiles, name="")` | `MoleculeInfo`     | Parse SMILES into a molecule |
+| `get_properties(mol_id)`      | `MoleculeProperties` | Computed molecular properties |
+| `get_3d(mol_id)`              | `Molecule3D`        | 3D coordinates and bonds     |
+
+### Elements
+
+| Method                | Returns   | Description                  |
+|-----------------------|-----------|------------------------------|
+| `get_element(symbol)` | `Element` | Look up element by symbol    |
+
+### Retrosynthesis
+
+| Method                                              | Returns              | Description              |
+|-----------------------------------------------------|----------------------|--------------------------|
+| `retrosynthesis(smiles, max_depth=5, beam_width=5)` | `RetrosynthesisPlan` | Plan retrosynthetic routes |
+
+### Process
+
+| Method                                                            | Returns             | Description                    |
+|-------------------------------------------------------------------|---------------------|--------------------------------|
+| `process_evaluate(smiles, scale_kg=1.0, max_depth=5, beam_width=5)` | `ProcessEvaluation` | Full process engineering report |
+
+### Billing
+
+| Method                  | Returns           | Description                        |
+|-------------------------|-------------------|------------------------------------|
+| `create_checkout(plan)` | `CheckoutSession` | Create Stripe checkout session     |
+| `billing_status()`      | `BillingStatus`   | Current subscription status        |
+
+## License
+
+MIT

molbuilder_client-0.1.0/README.md

@@ -0,0 +1,132 @@
+# molbuilder-client
+
+Python SDK for the [MolBuilder](https://www.molbuilder.io) REST API.
+
+## Install
+
+```bash
+pip install molbuilder-client
+```
+
+Requires Python 3.11+. The only runtime dependency is [httpx](https://www.python-httpx.org/).
+
+## Quickstart
+
+```python
+from molbuilder_client import MolBuilder
+
+client = MolBuilder(api_key="mb_...")
+
+# Parse a SMILES string
+mol = client.from_smiles("CCO", name="ethanol")
+print(mol.id, mol.num_atoms)  # mol_xxxx 9
+
+# Get molecular properties
+props = client.get_properties(mol.id)
+print(props.formula, props.molecular_weight)  # C2H6O 46.07
+
+# Get 3D coordinates
+structure = client.get_3d(mol.id)
+for atom in structure.atoms:
+    print(atom.symbol, atom.position)
+
+# Look up an element
+fe = client.get_element("Fe")
+print(fe.name, fe.atomic_weight)  # Iron 55.845
+
+# Retrosynthesis
+plan = client.retrosynthesis("c1ccccc1O")  # phenol
+print(plan.routes_found, plan.best_route.total_steps)
+
+# Process evaluation
+proc = client.process_evaluate("CCO", scale_kg=100.0)
+print(proc.cost.total_usd, proc.cost.per_kg_usd)
+```
+
+## Async usage
+
+```python
+import asyncio
+from molbuilder_client import AsyncMolBuilder
+
+async def main():
+    async with AsyncMolBuilder(api_key="mb_...") as client:
+        mol = await client.from_smiles("CCO")
+        props = await client.get_properties(mol.id)
+        print(props.formula)
+
+asyncio.run(main())
+```
+
+## Error handling
+
+All API errors raise typed exceptions that inherit from `MolBuilderError`:
+
+```python
+from molbuilder_client import MolBuilder, ValidationError, RateLimitError
+
+client = MolBuilder(api_key="mb_...")
+
+try:
+    client.from_smiles("not_valid")
+except ValidationError as e:
+    print(f"Bad SMILES: {e.message}")
+except RateLimitError as e:
+    print(f"Slow down! Retry after {e.retry_after}s")
+```
+
+| HTTP Status | Exception                  |
+|-------------|----------------------------|
+| 401         | `AuthenticationError`      |
+| 403         | `ForbiddenError`           |
+| 404         | `NotFoundError`            |
+| 422         | `ValidationError`          |
+| 429         | `RateLimitError`           |
+| 500         | `ServerError`              |
+| 501/503     | `ServiceUnavailableError`  |
+
+## API reference
+
+### Auth
+
+| Method                    | Returns        | Description                         |
+|---------------------------|----------------|-------------------------------------|
+| `register(email)`         | `APIKeyInfo`   | Register a new free-tier API key    |
+| `get_token()`             | `Token`        | Exchange API key for a JWT          |
+
+### Molecule
+
+| Method                        | Returns              | Description                  |
+|-------------------------------|----------------------|------------------------------|
+| `from_smiles(smiles, name="")` | `MoleculeInfo`     | Parse SMILES into a molecule |
+| `get_properties(mol_id)`      | `MoleculeProperties` | Computed molecular properties |
+| `get_3d(mol_id)`              | `Molecule3D`        | 3D coordinates and bonds     |
+
+### Elements
+
+| Method                | Returns   | Description                  |
+|-----------------------|-----------|------------------------------|
+| `get_element(symbol)` | `Element` | Look up element by symbol    |
+
+### Retrosynthesis
+
+| Method                                              | Returns              | Description              |
+|-----------------------------------------------------|----------------------|--------------------------|
+| `retrosynthesis(smiles, max_depth=5, beam_width=5)` | `RetrosynthesisPlan` | Plan retrosynthetic routes |
+
+### Process
+
+| Method                                                            | Returns             | Description                    |
+|-------------------------------------------------------------------|---------------------|--------------------------------|
+| `process_evaluate(smiles, scale_kg=1.0, max_depth=5, beam_width=5)` | `ProcessEvaluation` | Full process engineering report |
+
+### Billing
+
+| Method                  | Returns           | Description                        |
+|-------------------------|-------------------|------------------------------------|
+| `create_checkout(plan)` | `CheckoutSession` | Create Stripe checkout session     |
+| `billing_status()`      | `BillingStatus`   | Current subscription status        |
+
+## License
+
+MIT

molbuilder_client-0.1.0/molbuilder_client/__init__.py

@@ -0,0 +1,95 @@
+"""MolBuilder Python SDK -- typed client for the MolBuilder REST API.
+
+Usage::
+
+    from molbuilder_client import MolBuilder
+
+    client = MolBuilder(api_key="mb_...")
+    mol = client.from_smiles("CCO")
+    print(mol.id, mol.num_atoms)
+"""
+
+from molbuilder_client._async_client import AsyncMolBuilder
+from molbuilder_client._client import MolBuilder
+from molbuilder_client._exceptions import (
+    AuthenticationError,
+    ForbiddenError,
+    MolBuilderError,
+    NotFoundError,
+    RateLimitError,
+    ServerError,
+    ServiceUnavailableError,
+    ValidationError,
+)
+from molbuilder_client._models import (
+    APIKeyInfo,
+    Atom3D,
+    BestRoute,
+    BillingStatus,
+    Bond3D,
+    CheckoutSession,
+    Conditions,
+    CostBreakdown,
+    CostEstimate,
+    Disconnection,
+    Element,
+    Hazard,
+    Molecule3D,
+    MoleculeInfo,
+    MoleculeProperties,
+    Precursor,
+    ProcessEvaluation,
+    PurificationMethod,
+    Reactor,
+    RetroNode,
+    RetrosynthesisPlan,
+    RouteStep,
+    SafetyAssessment,
+    ScaleUp,
+    StepDetail,
+    Token,
+)
+
+__all__ = [
+    # Clients
+    "MolBuilder",
+    "AsyncMolBuilder",
+    # Exceptions
+    "MolBuilderError",
+    "AuthenticationError",
+    "ForbiddenError",
+    "NotFoundError",
+    "ValidationError",
+    "RateLimitError",
+    "ServerError",
+    "ServiceUnavailableError",
+    # Models
+    "APIKeyInfo",
+    "Token",
+    "MoleculeInfo",
+    "MoleculeProperties",
+    "Atom3D",
+    "Bond3D",
+    "Molecule3D",
+    "Element",
+    "Precursor",
+    "Disconnection",
+    "RetroNode",
+    "RouteStep",
+    "BestRoute",
+    "RetrosynthesisPlan",
+    "Reactor",
+    "Conditions",
+    "PurificationMethod",
+    "StepDetail",
+    "Hazard",
+    "SafetyAssessment",
+    "CostBreakdown",
+    "CostEstimate",
+    "ScaleUp",
+    "ProcessEvaluation",
+    "CheckoutSession",
+    "BillingStatus",
+]
+
+__version__ = "0.1.0"

molbuilder_client-0.1.0/molbuilder_client/_async_client.py

@@ -0,0 +1,175 @@
+"""Asynchronous MolBuilder API client backed by ``httpx.AsyncClient``."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from molbuilder_client._base import (
+    DEFAULT_BASE_URL,
+    build_headers,
+    build_url,
+    from_dict,
+    raise_for_status,
+)
+from molbuilder_client._models import (
+    APIKeyInfo,
+    BillingStatus,
+    CheckoutSession,
+    Element,
+    Molecule3D,
+    MoleculeInfo,
+    MoleculeProperties,
+    ProcessEvaluation,
+    RetrosynthesisPlan,
+    Token,
+)
+
+
+class AsyncMolBuilder:
+    """Asynchronous client for the MolBuilder REST API.
+
+    Parameters
+    ----------
+    api_key:
+        Your MolBuilder API key (starts with ``mb_``).
+    base_url:
+        Override the default production URL (useful for local dev).
+    timeout:
+        Request timeout in seconds.  Defaults to 30.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 30.0,
+    ) -> None:
+        self._api_key = api_key
+        self._base_url = base_url
+        self._client = httpx.AsyncClient(
+            headers=build_headers(api_key),
+            timeout=timeout,
+        )
+
+    # -- Async context manager ------------------------------------------------
+
+    async def __aenter__(self) -> AsyncMolBuilder:
+        return self
+
+    async def __aexit__(self, *exc: Any) -> None:
+        await self.close()
+
+    async def close(self) -> None:
+        """Release the underlying connection pool."""
+        await self._client.aclose()
+
+    # -- Private helpers ------------------------------------------------------
+
+    def _url(self, path: str) -> str:
+        return build_url(self._base_url, path)
+
+    async def _get(self, path: str, *, params: dict[str, Any] | None = None) -> dict[str, Any]:
+        resp = await self._client.get(self._url(path), params=params)
+        raise_for_status(resp)
+        return resp.json()
+
+    async def _post(self, path: str, *, json: dict[str, Any] | None = None) -> dict[str, Any]:
+        resp = await self._client.post(self._url(path), json=json)
+        raise_for_status(resp)
+        return resp.json()
+
+    # -- Auth -----------------------------------------------------------------
+
+    async def register(self, email: str) -> APIKeyInfo:
+        """Register a new free-tier API key for *email*."""
+        data = await self._post("auth/register", json={"email": email})
+        return from_dict(APIKeyInfo, data)
+
+    async def get_token(self) -> Token:
+        """Exchange the current API key for a short-lived JWT."""
+        data = await self._post("auth/token", json={"api_key": self._api_key})
+        return from_dict(Token, data)
+
+    # -- Molecule -------------------------------------------------------------
+
+    async def from_smiles(self, smiles: str, *, name: str = "") -> MoleculeInfo:
+        """Parse a SMILES string and return basic molecule info."""
+        payload: dict[str, Any] = {"smiles": smiles}
+        if name:
+            payload["name"] = name
+        data = await self._post("molecule/from-smiles", json=payload)
+        return from_dict(MoleculeInfo, data)
+
+    async def get_properties(self, mol_id: str) -> MoleculeProperties:
+        """Retrieve computed molecular properties for *mol_id*."""
+        data = await self._get(f"molecule/{mol_id}/properties")
+        return from_dict(MoleculeProperties, data)
+
+    async def get_3d(self, mol_id: str) -> Molecule3D:
+        """Retrieve 3D atomic coordinates and bonds for *mol_id*."""
+        data = await self._get(f"molecule/{mol_id}/3d")
+        return from_dict(Molecule3D, data)
+
+    # -- Elements -------------------------------------------------------------
+
+    async def get_element(self, symbol: str) -> Element:
+        """Look up an element by its chemical symbol (e.g. ``"Fe"``)."""
+        data = await self._get(f"elements/{symbol}")
+        return from_dict(Element, data)
+
+    # -- Retrosynthesis -------------------------------------------------------
+
+    async def retrosynthesis(
+        self,
+        smiles: str,
+        *,
+        max_depth: int = 5,
+        beam_width: int = 5,
+    ) -> RetrosynthesisPlan:
+        """Plan retrosynthetic routes for a target SMILES."""
+        data = await self._post(
+            "retrosynthesis/plan",
+            json={
+                "smiles": smiles,
+                "max_depth": max_depth,
+                "beam_width": beam_width,
+            },
+        )
+        return from_dict(RetrosynthesisPlan, data)
+
+    # -- Process Evaluation ---------------------------------------------------
+
+    async def process_evaluate(
+        self,
+        smiles: str,
+        *,
+        scale_kg: float = 1.0,
+        max_depth: int = 5,
+        beam_width: int = 5,
+    ) -> ProcessEvaluation:
+        """Evaluate process engineering for a synthesis route."""
+        data = await self._post(
+            "process/evaluate",
+            json={
+                "smiles": smiles,
+                "scale_kg": scale_kg,
+                "max_depth": max_depth,
+                "beam_width": beam_width,
+            },
+        )
+        return from_dict(ProcessEvaluation, data)
+
+    # -- Billing --------------------------------------------------------------
+
+    async def create_checkout(self, plan: str) -> CheckoutSession:
+        """Create a Stripe Checkout session for *plan* (e.g. ``"pro_monthly"``)."""
+        data = await self._post("billing/checkout", json={"plan": plan})
+        return from_dict(CheckoutSession, data)
+
+    async def billing_status(self) -> BillingStatus:
+        """Return the current billing / subscription status."""
+        data = await self._get("billing/status")
+        return from_dict(BillingStatus, data)