{"_id":"rdkit-agent","_rev":"2-3ce6169ec788d20db9c379fad6496088","name":"rdkit-agent","dist-tags":{"latest":"0.1.1"},"versions":{"0.1.0":{"name":"rdkit-agent","version":"0.1.0","keywords":["cheminformatics","rdkit","smiles","chemistry","cli","wasm"],"author":{"name":"Scott Reed"},"license":"MIT","_id":"rdkit-agent@0.1.0","maintainers":[{"name":"scottreed","email":"scott.reed@ucdenver.edu"}],"homepage":"https://github.com/scottmreed/rdkit-agent#readme","bugs":{"url":"https://github.com/scottmreed/rdkit-agent/issues"},"bin":{"rdkit-agent":"bin/rdkit_cli.js","rdkit-daemon":"bin/rdkit_daemon.js"},"dist":{"shasum":"5d461ce1d46241c8cd333d46072cedaed3ed193e","tarball":"https://registry.npmjs.org/rdkit-agent/-/rdkit-agent-0.1.0.tgz","fileCount":40,"integrity":"sha512-yrabIUgM5+GhDFhJGdJU694LBXf4xHaKOwBn5UY4O+Vv7ruA2qnT+/5jbB5vLWpPt6Jy87k6oD9nvkldkLWuMw==","signatures":[{"sig":"MEUCIQCjnuQGEzLzpONc/7mSoU7EDaHWZeEzCQpQNskFO0vvGAIgHoAcAQjEbNYnChuOG4mAD5KMFq77qtSSdhskjCDQfRE=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":278105},"jest":{"testMatch":["**/test/**/*.test.js"],"testEnvironment":"node"},"main":"src/index.js","engines":{"node":">=16.0.0"},"gitHead":"86747a8e9a30d49e523addca3c63a72f6b8b89c0","scripts":{"test":"jest --testPathPattern='test/'","agent":"node bin/rdkit_cli.js","start":"node bin/rdkit_cli.js","daemon":"node bin/rdkit_daemon.js","benchmark":"node scripts/benchmark.js","test:unit":"jest --testPathPattern='test/unit/'","test:integration":"jest --testPathPattern='test/integration/'"},"_npmUser":{"name":"scottreed","email":"scott.reed@ucdenver.edu"},"repository":{"url":"git+https://github.com/scottmreed/rdkit-agent.git","type":"git"},"_npmVersion":"10.9.3","description":"Agent-first cheminformatics CLI using Node.js + RDKit WASM","directories":{},"_nodeVersion":"22.20.0","dependencies":{"chalk":"^4.1.2","minimist":"^1.2.8","@rdkit/rdkit":"^2025.3.4-1.0.0"},"_hasShrinkwrap":false,"devDependencies":{"jest":"^29.7.0"},"_npmOperationalInternal":{"tmp":"tmp/rdkit-agent_0.1.0_1773630990429_0.42015817042187953","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"rdkit-agent","version":"0.1.1","description":"Agent-first cheminformatics CLI using Node.js + RDKit WASM","license":"MIT","main":"src/index.js","bin":{"rdkit-agent":"bin/rdkit_cli.js","rdkit-daemon":"bin/rdkit_daemon.js"},"scripts":{"test":"jest --testPathPattern='test/'","test:unit":"jest --testPathPattern='test/unit/'","test:integration":"jest --testPathPattern='test/integration/'","start":"node bin/rdkit_cli.js","agent":"node bin/rdkit_cli.js","benchmark":"node scripts/benchmark.js","daemon":"node bin/rdkit_daemon.js"},"dependencies":{"@rdkit/rdkit":"^2025.3.4-1.0.0","chalk":"^4.1.2","minimist":"^1.2.8"},"devDependencies":{"jest":"^29.7.0"},"jest":{"testEnvironment":"node","testMatch":["**/test/**/*.test.js"]},"keywords":["cheminformatics","rdkit","smiles","chemistry","cli","wasm"],"engines":{"node":">=16.0.0"},"author":{"name":"Scott Reed"},"repository":{"type":"git","url":"git+https://github.com/scottmreed/rdkit-agent.git"},"homepage":"https://github.com/scottmreed/rdkit-agent#readme","bugs":{"url":"https://github.com/scottmreed/rdkit-agent/issues"},"_id":"rdkit-agent@0.1.1","gitHead":"d8c8d68fede2e3a9ed130da524fd4df7552e39cf","_nodeVersion":"22.20.0","_npmVersion":"10.9.3","dist":{"integrity":"sha512-UmRBx2/nWQ56CFnER38+lol0ROSEwPPNbWAgepao/YeEafbIEuhbjXcogXJRyv1WBeH+Lhlbt9cbX7+JKMKtDw==","shasum":"870551dd3d02551752f1940ad531fa4bcce865af","tarball":"https://registry.npmjs.org/rdkit-agent/-/rdkit-agent-0.1.1.tgz","fileCount":40,"unpackedSize":278199,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIElkh7dikhpOfCQXln2NTseNmf7O5Wh65tcWKMa9SHaWAiBTUYLy3drDqmRkng14IRKEX2ai+Nhj3VD8nkGOv50lng=="}]},"_npmUser":{"name":"scottreed","email":"scott.reed@ucdenver.edu"},"directories":{},"maintainers":[{"name":"scottreed","email":"scott.reed@ucdenver.edu"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/rdkit-agent_0.1.1_1773631315210_0.731790383673246"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-16T03:16:30.429Z","modified":"2026-03-16T03:21:55.474Z","0.1.0":"2026-03-16T03:16:30.612Z","0.1.1":"2026-03-16T03:21:55.369Z"},"bugs":{"url":"https://github.com/scottmreed/rdkit-agent/issues"},"author":{"name":"Scott Reed"},"license":"MIT","homepage":"https://github.com/scottmreed/rdkit-agent#readme","keywords":["cheminformatics","rdkit","smiles","chemistry","cli","wasm"],"repository":{"type":"git","url":"git+https://github.com/scottmreed/rdkit-agent.git"},"description":"Agent-first cheminformatics CLI using Node.js + RDKit WASM","maintainers":[{"name":"scottreed","email":"scott.reed@ucdenver.edu"}],"readme":"# rdkit-agent\n\nAgent-first cheminformatics CLI powered by RDKit WASM. Validates, converts, and analyzes chemical notation (SMILES, SMIRKS, InChI) with structured JSON output. Works as a CLI, Node.js library, and MCP server.\n\n## Installation\n\n```bash\nnpm install -g rdkit-agent\n```\n\nRequires Node.js ≥ 16. No native build steps — RDKit runs as WebAssembly.\n\n## Quick Start\n\n```bash\n# Validate a SMILES string\nrdkit-agent check --smiles \"c1ccccc1\"\n\n# Compute molecular descriptors\nrdkit-agent descriptors --smiles \"CCO\"\n\n# Convert SMILES to InChI\nrdkit-agent convert --from smiles --to inchi --input \"CCO\"\n\n# Find similar molecules\nrdkit-agent similarity --query \"c1ccccc1\" --targets \"Cc1ccccc1,CCO,c1ccc2ccccc2c1\" --threshold 0.5\n```\n\nOutput is JSON when stdout is not a terminal (piped/redirected). Pass `--output json` to force it.\n\n## Commands\n\n| Command | Description |\n|---------|-------------|\n| `check` | Pre-flight validation for SMILES, SMIRKS, and reaction balance |\n| `repair-smiles` | Deterministically repair/reconstruct malformed SMILES into valid canonical guesses |\n| `convert` | Convert between SMILES, InChI, InChIKey, MOL, SDF |\n| `descriptors` | Compute MW, logP, TPSA, HBD, HBA, rotatable bonds, rings |\n| `balance` | Check atom balance for reactions |\n| `fg` | Detect functional groups (tiered consuming SMARTS catalog) |\n| `subsearch` | SMARTS substructure search |\n| `fingerprint` | Generate Morgan or topological fingerprints |\n| `similarity` | Tanimoto similarity search |\n| `scaffold` | Extract Murcko scaffold |\n| `filter` | Filter molecules by descriptor ranges (Lipinski Ro5, etc.) |\n| `draw` | Render molecule to SVG/PNG with optional atom/bond highlighting |\n| `stats` | Dataset statistics across descriptors |\n| `edit` | Molecular transformations (neutralize, sanitize, add-h, etc.) |\n| `rings` | Ring analysis (count, aromaticity, spiro atoms) |\n| `react` | Apply a reaction SMIRKS to reactant SMILES → product SMILES |\n| `stereo` | Stereocentre analysis (tetrahedral + E/Z, CIP codes, specified vs unspecified) |\n| `tautomers` | Enumerate tautomers *(see WASM Limitations)* |\n| `atom-map` | Atom mapping: `add` / `remove` / `check` / `list` sub-commands |\n| `schema` | Inspect JSON schemas for any command |\n| `mcp` | Start MCP stdio server |\n| `version` | Show version info |\n\n### Common flags\n\n```bash\n--json '{\"smiles\":\"CCO\"}'   # Pass arguments as JSON object\n--json -                    # Read JSON from stdin\n--fields \"MW,logP\"          # Limit output to specific fields\n--output json               # Force JSON output\n```\n\n### check\n\n```bash\nrdkit-agent check --smiles \"CCO\"\nrdkit-agent check --smiles \"H2O\"          # → corrects alias to \"O\"\nrdkit-agent check --smirks \"[C:1][OH]>>[C:1]=O\"\nrdkit-agent check --reactants \"CC,OO\" --products \"CCO,O\"\n```\n\nOutput keys: `overall_pass`, `summary`, `checks`, `failed_checks`, `fix_suggestions`, `corrected_values`\n\n### repair-smiles\n\n```bash\nrdkit-agent repair-smiles --input \"C1CC\"                   # ring-closure repair\nrdkit-agent repair-smiles --input \"H2O\"                    # alias/formula repair\nrdkit-agent repair-smiles --json '{\"molecules\":[\"C1CC\",\"Na+\"]}'\n```\n\nOutput keys: `success`, `canonical_smiles`, `strategy`, `confidence`, `intent`, `attempts`\n\n### descriptors\n\n```bash\nrdkit-agent descriptors --smiles \"CCO\"\nrdkit-agent descriptors --json '{\"molecules\":[\"CCO\",\"c1ccccc1\"]}'\nrdkit-agent descriptors --smiles \"CCO\" --fields \"MW,logP,TPSA\"\n```\n\n### convert\n\n```bash\nrdkit-agent convert --from smiles --to inchi --input \"CCO\"\nrdkit-agent convert --from smiles --to inchikey --input \"c1ccccc1\"\nrdkit-agent convert --from smiles --to mol --input \"CCO\"\n```\n\n### similarity\n\n```bash\nrdkit-agent similarity --query \"c1ccccc1\" --targets \"Cc1ccccc1,CCO\" --threshold 0.5 --top 5\n```\n\n### filter\n\n```bash\nrdkit-agent filter --smiles \"CCO,CC(=O)Oc1ccccc1C(O)=O\" --mw-max 100 --logp-max 3\nrdkit-agent filter --smiles \"CCO,CC(=O)Oc1ccccc1C(O)=O\" --lipinski\n```\n\n### draw\n\n```bash\nrdkit-agent draw --smiles \"c1ccccc1\" --output benzene.svg --format svg\nrdkit-agent draw --smiles \"c1ccccc1\" --width 400 --height 400 --output large.svg\n\n# Highlight atoms 0 and 1 in red, atom 3 in blue\nrdkit-agent draw --smiles \"c1ccccc1\" \\\n  --highlight-atoms '{\"0\":\"#ff0000\",\"1\":\"#ff0000\",\"3\":\"#0000ff\"}' \\\n  --highlight-radius 0.4\n\n# Highlight bond 1 in green\nrdkit-agent draw --smiles \"c1ccccc1\" \\\n  --highlight-bonds '{\"1\":\"#00ff00\"}'\n```\n\n`--highlight-atoms` and `--highlight-bonds` accept JSON objects mapping index (string) → CSS hex colour. `--highlight-radius` sets the highlight circle size (default 0.3).\n\n### edit\n\n```bash\nrdkit-agent edit --smiles \"[NH4+].[OH-]\" --operation neutralize\nrdkit-agent edit --smiles \"CCO\" --operation add-h\nrdkit-agent edit --smiles \"[H]OCC\" --operation remove-h\nrdkit-agent edit --smiles \"[CH3:1][OH:2]\" --operation strip-maps\n```\n\n### react\n\nApply a reaction SMIRKS to one or more reactant SMILES and receive the product SMILES.\n\n```bash\nrdkit-agent react --smirks \"[C:1][OH]>>[C:1]Br\" --reactants \"CCO,CCCO\"\n# → { \"reaction\": \"...\", \"reactant_count\": 2, \"products\": [[\"CCBr\"], [\"CCCBr\"]] }\n```\n\nReactants can be comma-separated or space-separated (positional args after the flags).\n\n> **WASM note**: requires `get_rxn` / `run_reactants` in the WASM build. If those are absent a `NOT_SUPPORTED_IN_WASM` error is thrown — see [WASM Limitations](#wasm-limitations).\n\nProgrammatic:\n```javascript\nconst { reactionApply } = require('rdkit-agent');\nconst result = await reactionApply({ smirks: '[C:1][OH]>>[C:1]Br', reactants: ['CCO', 'CCCO'] });\n```\n\n### stereo\n\nAnalyse stereocentres in a molecule. Reports tetrahedral and E/Z stereocentres with specified/unspecified status and CIP codes when available.\n\n```bash\nrdkit-agent stereo --smiles \"CC(O)C(N)C\"\n# → { stereo_centers: [...], stereo_center_count: 2, specified_count: 0, has_unspecified_stereo: true }\n\nrdkit-agent stereo --smiles \"OC1=CC=CC=C1,CC(F)Cl\"  # comma-separated batch\n```\n\nThe `--enumerate` flag will attempt to list all stereo isomers. This requires `enumerate_stereocenters` in the WASM build — see [WASM Limitations](#wasm-limitations).\n\nProgrammatic:\n```javascript\nconst { analyzeStereo } = require('rdkit-agent');\nconst result = await analyzeStereo('CC(O)C(N)C');\n```\n\n### tautomers\n\nEnumerate tautomers of a molecule.\n\n```bash\nrdkit-agent tautomers --smiles \"OC1=CC=CC=C1\" --limit 10\n# → { input_smiles: \"...\", canonical_tautomer: \"Oc1ccccc1\", tautomers: [...], count: 3 }\n```\n\n> **WASM note**: `TautomerEnumerator` is **not** available in the standard RDKit WASM build. A `NOT_SUPPORTED_IN_WASM` error will be thrown — see [WASM Limitations](#wasm-limitations).\n\nProgrammatic:\n```javascript\nconst { enumerateTautomers } = require('rdkit-agent');\nconst result = await enumerateTautomers({ smiles: 'OC1=CC=CC=C1', limit: 10 });\n```\n\n### atom-map\n\nManage atom mapping numbers in SMILES and SMIRKS.\n\n```bash\n# List atom_index → map_number\nrdkit-agent atom-map list --smiles \"[CH3:1][CH2:2][OH:3]\"\n# → { atom_maps: { \"0\": 1, \"1\": 2, \"2\": 3 }, mapped_atom_count: 3 }\n\n# Add sequential map numbers to all heavy atoms\nrdkit-agent atom-map add --smiles \"CCO\"\n# → { mapped_smiles: \"[CH3:1][CH2:2][OH:3]\" }\n\n# Strip all map numbers\nrdkit-agent atom-map remove --smiles \"[CH3:1][CH2:2][OH:3]\"\n# → { canonical_smiles: \"CCO\" }\n\n# Validate SMIRKS mapping balance\nrdkit-agent atom-map check --smirks \"[C:1][OH:2]>>[C:1]Br\"\n# → { valid: true, mapped_atoms: 1, unmapped_atoms: 1, balanced: false, ... }\n```\n\nProgrammatic:\n```javascript\nconst { atomMapList, atomMapAdd, atomMapRemove, atomMapCheck } = require('rdkit-agent');\n```\n\n## WASM Limitations\n\nSome RDKit features are **not** available in the WebAssembly build (`@rdkit/rdkit`). When these are called, a structured error with `code: \"NOT_SUPPORTED_IN_WASM\"` is thrown instead of silently failing.\n\n| Feature | Status | Python alternative |\n|---------|--------|-------------------|\n| Reaction application (`react`) | **Available** in @rdkit/rdkit ≥ 2022.03 via `get_rxn` | `AllChem.RunReactants` |\n| Stereo enumeration (`stereo --enumerate`) | **Not available** in standard builds | `EnumerateStereoisomers.EnumerateStereoisomers` |\n| Tautomer enumeration (`tautomers`) | **Not available** in standard builds | `rdMolStandardize.TautomerEnumerator` |\n\nTo use these features in Python:\n```python\nfrom rdkit import Chem\nfrom rdkit.Chem import AllChem\nfrom rdkit.Chem.MolStandardize import rdMolStandardize\nfrom rdkit.Chem.EnumerateStereoisomers import EnumerateStereoisomers\n\n# Reactions\nrxn = AllChem.ReactionFromSmarts('[C:1][OH]>>[C:1]Br')\nproducts = rxn.RunReactants((Chem.MolFromSmiles('CCO'),))\n\n# Tautomers\nte = rdMolStandardize.TautomerEnumerator()\ntautomers = te.Enumerate(Chem.MolFromSmiles('OC1=CC=CC=C1'))\n\n# Stereo enumeration\nisomers = list(EnumerateStereoisomers(Chem.MolFromSmiles('CC(O)C(N)C')))\n```\n\n## Data Files\n\n- `data/aliases.json`: Alias/formula normalization map used by hardening and validation (`H2O -> O`, `AcOH -> CC(O)=O`).\n- `data/fg_patterns.json`: Curated tiered+consuming SMARTS set used by `fg` for stable, low-overlap functional-group assignment.\n- `data/checkmol_smarts_part1.csv`: Broader checkmol-derived SMARTS catalog used by `repair-smiles` intent scoring (ring/chain/FG hint ranking), not by the main `fg` command.\n\n## MCP Server (Claude Desktop)\n\nStart the MCP stdio server to expose all commands as tools:\n\n```bash\nrdkit-agent mcp\n```\n\nAdd to your Claude Desktop `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"rdkit-agent\": {\n      \"command\": \"rdkit-agent\",\n      \"args\": [\"mcp\"]\n    }\n  }\n}\n```\n\n## Node.js API\n\n```javascript\nconst { check, descriptors, convert, similarity, RDKIT_TOOLS, handleToolCall } = require('rdkit-agent');\n\n// Always validate before using chemistry strings\nconst result = await check({ smiles: 'CCO' });\nif (!result.overall_pass) {\n  console.error(result.fix_suggestions);\n}\n\n// Compute descriptors\nconst desc = await descriptors({ smiles: 'CCO' });\nconsole.log(desc.MW, desc.logP);\n\n// Convert format\nconst inchi = await convert({ input: 'CCO', from: 'smiles', to: 'inchi' });\n\n// Similarity search\nconst hits = await similarity({\n  query: 'c1ccccc1',\n  targets: ['Cc1ccccc1', 'CCO', 'c1ccc2ccccc2c1'],\n  threshold: 0.5\n});\n```\n\n### OpenAI Tool Integration\n\n```javascript\nconst { RDKIT_TOOLS, handleToolCall } = require('rdkit-agent');\n\nconst response = await openai.chat.completions.create({\n  model: 'gpt-4o',\n  tools: RDKIT_TOOLS,\n  messages: [{ role: 'user', content: 'Is CCO a valid SMILES?' }]\n});\n\nfor (const toolCall of response.choices[0].message.tool_calls ?? []) {\n  const result = await handleToolCall(\n    toolCall.function.name,\n    JSON.parse(toolCall.function.arguments)\n  );\n  // result is JSON-serializable\n}\n```\n\n## Exit Codes\n\n| Code | Meaning |\n|------|---------|\n| 0 | Success |\n| 1 | Validation failure (`overall_pass = false`) |\n| 2 | Usage error (bad arguments, missing input) |\n| 3 | RDKit error (WASM not loaded, molecule parse failure) |\n\n## Agent Use (SKILL.md)\n\nFor use with AI agents (Claude, GPT, etc.), see [SKILL.md](./SKILL.md) which ships with the package. It documents critical invariants, error patterns, and all command schemas in agent-optimized format.\n\n## License\n\nMIT\n","readmeFilename":"README.md"}