> ## Documentation Index
> Fetch the complete documentation index at: https://prismeai-legacy.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Functions Microservice
> How to deploy, configure, and use the Prisme.ai Functions Microservice for running custom NodeJS and Python code in your applications
The Functions Microservice enables you to execute custom code (NodeJS or Python) within your Prisme.ai applications. This powerful capability allows you to extend the platform with custom logic, integrate with external systems, and implement complex business processes.
## Overview
The Functions Microservice provides a secure, isolated environment for running custom code within the Prisme.ai platform. It supports:
* **NodeJS Functions**: JavaScript code execution with access to selected built-in modules
* **Python Functions**: Python code execution with standard library access
* **Shared Execution Context**: Functions within the same workspace can call each other
* **Memory Management**: Configurable resource limits and garbage collection
* **Dependency Management**: Automatic installation of required packages
The Functions Microservice is designed with security in mind, running code in isolated environments with configurable resource limits to prevent abuse or resource exhaustion.
## Installation Prerequisites
Before deploying the Functions Microservice, ensure you have:
The service requires a volume for storing code, dependencies, and execution data. We recommend using volumes with high I/O performance as they may experience heavy usage when installing dependencies.
A set of commonly used JavaScript packages (node-fetch, js-yaml, dayjs, mongodb, redis, sharp, etc.) are **pre-installed in the Docker image** and shared across all workspaces. This means **no npm registry access is required** for most use cases.
If your custom code requires additional packages beyond the pre-installed ones, the service must have access to a npm registry. You can:
* Set `NPM_CONFIG_REGISTRY` to point to your own registry
* Or set the workspace `disableNpmRegistry` option to `true` to prevent any runtime npm install entirely (only pre-installed shared packages will be available)
By default, the service tries to install any additional and whitelisted packages from [https://www.npmjs.com/](https://www.npmjs.com/).
## Configuration
### Environment Variables
Configure the Functions Microservice with the following environment variables:
| Variable Name | Description | Default Value |
| ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
| `PYTHON_FUNCTIONS_RUN_TIMEOUT` | Python functions execution timeout in milliseconds | `20000` |
| `PYTHON_API_URL` | Python API URL | `http://localhost:8000` |
| `KERNEL_POOL_SIZE` | Number of python processes (each thread can execute only 1 function at a time) | Defaults to current cpu cores number |
| `PYTHON_BUILTIN_MODULES` | Comma-separated list of allowed Python stdlib modules for import. Dangerous modules like `subprocess`, `os`, `socket`, `ctypes` are excluded by default. See default list below. | See below |
| `PYTHON_PACKAGES_AUTO_INSTALL` | Comma-separated list of pip packages to install at startup (supports version notation like `pandas==2.0.0`) | |
| `PYTHON_PACKAGES_DIR` | Path to the custom python packages install directory | data/functions-py/packages/ |
| `PYTHON_PACKAGES_WHITELIST_IMPORT` | Comma-separated list of allowed third-party packages for import. | numpy, pandas, tabulate, dateparser, urllib3, requests, pptx, docx |
#### Default `PYTHON_BUILTIN_MODULES`
The following stdlib modules are allowed by default, organized by category:
| Category | Modules |
| ---------------------------- | ------------------------------------------------------------------------------------------------ |
| Data formats & serialization | `json`, `csv`, `xml`, `html`, `email` |
| Text & strings | `re`, `string`, `textwrap`, `unicodedata`, `difflib` |
| Math & numbers | `math`, `decimal`, `fractions`, `random`, `statistics` |
| Date & time | `datetime`, `time`, `calendar` |
| Data structures & functional | `collections`, `itertools`, `functools`, `operator`, `array`, `heapq`, `bisect`, `queue`, `copy` |
| Types & classes | `enum`, `typing`, `dataclasses`, `abc`, `types` |
| I/O & paths | `io`, `pathlib`, `tempfile`, `glob`, `fnmatch` |
| Encoding & hashing | `base64`, `hashlib`, `hmac`, `binascii`, `struct`, `secrets` |
| Compression & archives | `zlib`, `gzip`, `bz2`, `lzma`, `zipfile`, `tarfile` |
| Network (high-level only) | `urllib`, `http` |
| Logging & debugging | `logging`, `warnings`, `traceback`, `pprint` |
| Misc | `uuid`, `contextlib`, `weakref`, `timeit`, `atexit` |
The following stdlib modules are **excluded by default** for security reasons: `subprocess`, `os`, `sys`, `shutil`, `socket`, `ctypes`, `multiprocessing`, `_thread`, `signal`, `resource`, `importlib`, `runpy`, `code`, `ast`, `dis`, `pickle`, `marshal`, `pty`, `fcntl`, `mmap`, `gc`, `inspect`, `webbrowser`, `ensurepip`, `venv`.
| Variable Name | Description | Default Value |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- |
| `PORT` | HTTP port for the service | `4000` |
| `FUNCTIONS_STORAGE_FILESYSTEM_DIRPATH` | Directory path for function storage | `data/functions/` |
| `FUNCTIONS_RUN_TIMEOUT` | Functions execution timeout in milliseconds | `20000` |
| `FUNCTIONS_WORKERS_MAX_LRU` | Maximum number of function workers kept in memory | `500` |
| `NODEJS_BUILTIN_MODULES` | Comma-separated list of allowed Node.js built-in modules | `http, https, url, util, zlib, dns, stream, buffer, crypto` |
| `NODEJS_PACKAGES_WHITELIST_IMPORT` | Comma-separated list of allowed external packages for require() and install. When not set, all packages are allowed. Automatically combined with `NODEJS_SHARED_PACKAGES_WHITELIST_IMPORT` so that shared packages remain accessible. | |
| `NODEJS_SHARED_PACKAGES_WHITELIST_IMPORT` | Comma-separated list of shared packages always allowed for require(), in addition to `NODEJS_PACKAGES_WHITELIST_IMPORT`. Defaults to all packages detected in `SHARED_NODE_MODULES_DIRECTORY`. | Auto-detected from shared deps |
| `NODEJS_PACKAGES_BLACKLIST_IMPORT` | Comma-separated list of blocked npm packages for install and require(). Takes precedence over whitelists. | |
| `SHARED_NODE_MODULES_DIRECTORY` | Path to a directory containing a `package.json` and pre-installed `node_modules/` shared across all workspaces. Packages in this directory are available to all custom code functions without per-workspace npm install. | `/www/custom-js-deps` (in Docker) |
| `NPM_CONFIG_REGISTRY` | NPM registry URL | `https://registry.npmjs.org/` |
| `NODE_WORKER_MAX_OLD_GENERATION_SIZE_MB` | NodeJS function worker [maxOldGenerationSizeMb](https://nodejs.org/api/worker_threads.html#workerresourcelimits) | `100` |
| `INACTIVE_NODE_WORKER_DELETION_TIMEOUT` | Inactive period in seconds after which node workers are automatically terminated | `3600` |
| `UPDATE_SCRIPTS_ON_STARTUP` | If set to "yes" or "true", ensures function scripts are in-sync with corresponding workspace.yaml files on startup | `no` |
| `REQUEST_MAX_SIZE` | Maximum request body size (format from bodyParser.json) | `1mb` |
#### Default `NODEJS_SHARED_PACKAGES_WHITELIST_IMPORT`
The following packages are pre-installed and shared across all workspaces by default:
| Category | Packages |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| Authentication & security | `@azure/msal-node`, `google-auth-library`, `hcaptcha` |
| AI & text processing | `gpt-tokenizer` |
| Data formats & parsing | `csv-parse`, `csv-string`, `js-yaml`, `yaml`, `papaparse`, `safe-flat`, `uni-flatten` |
| Email & messaging | `@sendgrid/mail` |
| Database & caching | `mongodb`, `redis` |
| HTTP & networking | `node-fetch`, `form-data` |
| Files & archives | `adm-zip`, `archiver`, `sharp` |
| Text & encoding | `css`, `iconv-lite`, `jschardet`, `striptags`, `sift` |
| Utilities | `dayjs`, `generate-password`, `human-readable-ids`, `humanize-duration`, `md5`, `short-uuid`, `unique-names-generator` |
All transitive dependencies of these packages are also available for import. The effective shared whitelist is auto-detected from the `node_modules/` directory, not just the direct dependencies listed above.
### Resource Considerations
When deploying the Functions Microservice, consider the following resource recommendations:
Allocate sufficient memory based on your expected workload:
* Minimum: 1GB
* Recommended: 2GB or more for production environments
* Consider additional memory if functions will process large datasets
Ensure adequate CPU resources:
* Minimum: 0.5 vCPU
* Recommended: 1 vCPU or more for production environments
* Functions with complex calculations may benefit from additional CPU
Plan for storage requirements:
* Minimum: 1GB
* Recommended: 5GB or more for environments with many dependencies
* Consider storage needs for dependency caching and function code
Ensure proper network setup:
* Accessible by other microservices (especially API Gateway)
* Access to required external resources (NPM registry, etc.)
* Consider network policies for security
## Microservice Testing
After deploying the Functions Microservice, verify its operation with these simple tests:
Create a function workspace named `test` containing a `hello` function:
```bash theme={null}
curl --location 'http://localhost:4000/v2/functions/test' \
--header 'Content-Type: application/json' \
--data '{
"functions": {
"hello": {
"code": "return \"Hello \" + name;",
"parameters": {
"name": {
"type": "string"
}
}
}
}
}'
```
If successful, the same body should be returned in the response.
Run the function with a test parameter:
```bash theme={null}
curl --location 'http://localhost:4000/v2/functions/test/run/hello' \
--header 'Content-Type: application/json' \
--data '{
"parameters": {
"name": "world"
}
}'
```
If successful, you should receive a response like:
```json theme={null}
{
"result": "Hello world",
"logs": [],
"duration": 38
}
```
Test that resource limits are enforced by creating a function that attempts to use excessive resources:
```bash theme={null}
curl --location 'http://localhost:4000/v2/functions/test' \
--header 'Content-Type: application/json' \
--data '{
"functions": {
"resourceTest": {
"code": "const array = []; while(true) { array.push(new Array(1000000).fill(\"test\")); }",
"parameters": {}
}
}
}'
```
When executing this function, it should terminate due to resource limits or timeout:
```bash theme={null}
curl --location 'http://localhost:4000/v2/functions/test/run/resourceTest' \
--header 'Content-Type: application/json' \
--data '{
"parameters": {}
}'
```
If all tests pass, congratulations! Your Functions Microservice is up and running correctly.
## Advanced Features
The Functions Microservice includes several advanced capabilities that enhance its flexibility and power:
All functions are executed as asynchronous operations, even if they don't explicitly use async calls. This means:
* Every function is treated as if it had the `async` keyword
* When calling functions from the same workspace, you must use the `await` keyword
* Results are always returned as promises
**Example:**
```javascript theme={null}
// This simple function is still executed asynchronously
function simpleCalc() {
return 42;
}
// When calling from another function, use await
async function useCalc() {
const result = await simpleCalc();
return `The answer is ${result}`;
}
```
Functions within the same workspace are executed within a generated JavaScript file that combines all functions. This allows:
* Functions to call each other directly
* Shared utility functions across the workspace
* Code reuse and modularization
**Example:**
**funcA:**
```javascript theme={null}
return "world";
```
**funcB:**
```javascript theme={null}
return "hello " + (await funcA());
```
When `funcB` is called, it will internally call `funcA` and return "hello world".
Functions from the same workspace are executed within the same worker NodeJS and VM2 instance. This enables memory sharing using a special `cache` variable:
* The `cache` object persists between function executions
* Use it to store and retrieve values across multiple calls
* Useful for maintaining state or caching expensive operations
**Example:**
**funcA:**
```javascript theme={null}
let counter = cache['counter']
counter = (counter || 0) + 1
cache['counter'] = counter;
return counter;
```
**funcB:**
```javascript theme={null}
let counter = cache['counter'];
return "Counter: " + counter;
```
Each call to `funcA` will increment the counter, and `funcB` can access the current value.
Functions can use external dependencies by specifying them in the function definition:
* **NodeJS functions** can use NPM packages. Dependencies are resolved in the following order:
1. **Shared dependencies** (pre-installed at build time): A set of commonly needed packages are bundled in the Docker image under `SHARED_NODE_MODULES_DIRECTORY` and available to all workspaces instantly, without any npm install at runtime. These include packages like `lodash`, `axios`, `dayjs`, `mongodb`, `redis`, `sharp`, and more.
2. **Per-workspace dependencies**: Any additional package required by a workspace's custom code that is not in the shared dependencies will be automatically installed via npm when the function is created or updated. This can be disabled per workspace with the `disableNpmRegistry` option.
* **Python functions** can use PyPI packages that have been whitelisted and pre installed with the corresponding environment variables
When `NODEJS_PACKAGES_WHITELIST_IMPORT` is set, shared packages are automatically added to the effective whitelist so that platform-native custom code continues to work without requiring clients to explicitly list every shared package.
**Example NodeJS function with dependencies:**
```json theme={null}
{
"functions": {
"processData": {
"code": "const _ = require('lodash'); return _.groupBy(data, 'category');",
"parameters": {
"data": {
"type": "array"
}
}
}
}
}
```
## Integration with Prisme.ai
The Functions Microservice integrates with other Prisme.ai components:
Within AI Builder, you can create custom automations that execute functions, allowing you to extend workflows with custom logic.
Custom functions can be used as tools in AI Knowledge agents, enabling them to perform specialized operations like data transformation or external API calls.
Functions can power features in agents published to the AI Store, adding custom capabilities to shared agents.
The Custom Code app provides a user-friendly interface for managing, testing, and monitoring functions.
## Security Considerations
When deploying and using the Functions Microservice, keep these security considerations in mind:
Functions run in isolated environments to prevent interference between different workspaces and functions.
Configure appropriate resource limits to prevent denial-of-service attacks or resource exhaustion.
Implement proper authentication and authorization to control who can create and execute functions.
Consider scanning dependencies for vulnerabilities before allowing their installation.
Function code is executed in a restricted environment, but it still has access to specified Node.js built-in modules and network resources. Be careful when allowing users to create functions, and consider implementing additional security controls for sensitive environments.
## Troubleshooting
**Possible causes:**
* Invalid function code syntax
* Unavailable or incompatible dependencies
* Insufficient disk space for dependencies
* Network issues preventing access to the NPM registry
**Resolution steps:**
1. Check the service logs for specific error messages
2. Verify NPM registry access from within the container
3. Ensure sufficient disk space in the function storage volume
4. Validate function syntax before submission
**Possible causes:**
* Function code contains infinite loops or excessive processing
* Timeout setting is too low for the operation
* External service calls that take too long
**Resolution steps:**
1. Review function code for inefficiencies or infinite loops
2. Adjust the `FUNCTIONS_RUN_TIMEOUT` or `PYTHON_FUNCTIONS_RUN_TIMEOUT` setting
3. Implement better error handling for external service calls
4. Consider breaking complex operations into smaller, chainable functions
**Possible causes:**
* Functions attempting to use more memory than allowed
* Memory leaks in long-running functions
* Too many function workers in memory
**Resolution steps:**
1. Adjust `NODE_WORKER_MAX_OLD_GENERATION_SIZE_MB` for larger memory requirements
2. Reduce `FUNCTIONS_WORKERS_MAX_LRU` if overall memory usage is too high
3. Optimize function code to use less memory
4. Check for and fix memory leaks in function code