This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Functions

This section provides a comprehensive guide on how to develop, build, and manage custom functions within the platform. By leveraging the Fathom CLI, you can transform local code into scalable, platform-hosted logic that integrates seamlessly with your existing data ecosystems.

1: Function Management
2: Source Management
3: Build and Deploy
4: Interaction and debugging

1 - Function Management

This document covers the administrative lifecycle of a function. It explains how to provision new function identities, list your existing inventory, and update metadata such as environment variables or scaling parameters.

Listing Functions

To view all functions available in your current context, use the list command. This provides an overview of function names, IDs, and their current configurations.

fathom intelligence function list

Creating a Function

The create command initializes a new serverless function entry on the platform. This step sets the “blueprint” for your function, defining its runtime environment and hardware requirements before you upload any code.

fathom intelligence function create <NAME> [OPTIONS]

Key Arguments & Options

Argument/Option	Requirement	Description
<NAME>	Required	The name of the function.
–description, -d	Required	A brief description of the function’s purpose.
–kind, -k	Required	Build environment kind. Values: rust189, rust186, python310, go124.
–serving-size	Required	Computational resources: small, large, or extra-large.
–auto-create	Optional	Automatically creates a sample application structure for you.

Advanced Configuration Options

Option	Type	Description
–build-env	KEY=VALUE	Environment variables used strictly during the build process.
–serving-env	KEY=VALUE	Environment variables available to the running service.
–serving-gpu	Enum	GPU variant to attach: nvidia-l4 or nvidia-l4-2x.
–serving-timeout	Seconds	Maximum execution time before the function times out.
–schema-input	JSON	JSON schema to validate incoming request data.
–schema-output	JSON	JSON schema to validate outgoing response data.

Example: Simple Python Function

To create a simple python function with sample application code type:

fathom intelligence function create test1 --description 'Just testing' --kind python310 --serving-size small

Next Step

Now that you have created a function resource, you need to sync your local code with the platform.

Proceed to Source Management to learn how to upload your function logic.

Updating a Function

Use the update command to modify an existing function’s configuration. This is commonly used to adjust scaling, update secrets via environment variables, or rename the resource.

fathom intelligence function update <FUNCTION_ID> [OPTIONS]

Option	Requirement	Description
<FUNCTION_ID>	Required	The unique ID of the function you wish to update.
–name, -n	Optional	Update the display name of the function.
–description, -d	Optional	Update the function’s description.
–serving-size, -s	Optional	Change the hardware tier (small, large, extra-large).
–serving-env	Optional	Update or add new runtime environment variables (KEY=VALUE).
–serving-gpu	Optional	Change the GPU variant or attach one to the service.
–serving-timeout	Optional	Adjust the execution timeout in seconds.

Example: Scaling an Existing Function

If your function requires more memory or a longer execution time, you can update it as follows:

fathom intelligence function update 1fc6c0ba-2ab6-4c0d-8a32-3a6374956aa3 --serving-size extra-large --serving-timeout 600

2 - Source Management

This section focuses on the synchronization between your local development environment and the remote registry. It details the process of pushing your source code to the platform and pulling existing codebases down for collaborative development or version audits.

Initializing Local Source Code

If you created your function using the --auto-create flag, or if the function already contains source code in the registry, you should start by downloading the code to your local machine.

Downloading Code

The download command fetches the function’s source code and places it into a specified directory.

fathom intelligence function download <FUNCTION_ID> <DIRECTORY>

Example

To download a function to a folder named testing:

fathom intelligence function download --id 44b18587-5eb1-4261-a90e-fa6852bc8086 testing

After downloading, your directory (e.g., testing) will typically look like this:

testing
├── func.yaml          # Function configuration
├── function/          # Source code directory
│   ├── __init__.py
│   └── func.py        # Main logic
├── pyproject.toml     # Dependency management
├── README.md
└── tests/             # Local tests directory
    └── test_func.py

Uploading Changes

Once you have made changes to your logic or updated the dependencies locally, you must upload the source code back to the platform before it can be built or deployed.

fathom intelligence function upload <FUNCTION_ID> <DIRECTORY>

Usage Note:

The argument should point to the root folder containing your func.yaml or main source files.
This command updates the “Source” state of the function on the platform, but it does not automatically trigger a new deployment. You must run a build and deploy command separately to see the changes live.

Versioning and Revisions

Every time you successfully upload code, the CLI generates a new Revision ID. This ID is used to track different versions of your source code before they are built.

fathom intelligence function upload --id 44b18587-5eb1-4261-a90e-fa6852bc8086 testing
Function source code updated - revision: v1

Next Step

Now that your source code is synchronized with the platform, you are ready to compile your code and push it to a live environment.

Proceed to Build and Deploy to learn how to finalize your function.

3 - Build and Deploy

This section describes the critical transition from raw source code to a running service. It covers the build system where dependencies are resolved and artifacts are created and the deployment process that promotes a build into a live, accessible endpoint.

Understanding the Build Process

A Build is an immutable artifact created from a specific source code revision (e.g., v1). During this phase, the platform resolves dependencies, compiles your code and prepares the environment for execution.

Creating a Build

The build create command triggers the build process on the platform.

fathom intelligence function build create <FUNCTION_ID> [OPTIONS]

Build Options

Option	Description
–revision, -r	The source revision to build. If omitted, the CLI defaults to the most recent revision.
–auto-deploy, -a	If the build succeeds, the CLI will automatically trigger a deployment.
–watch	Starts an interactive watch mode to track build progress in real-time.
–time	Prepends timestamps to the build output logs.

Example: Build with Auto-Deploy

> fathom i function build create 44b18587-5eb1-4261-a90e-fa6852bc8086
  --revision v1
  --auto-deploy
  --watch

build created: c4c9e7c6-a93e-43a3-ac14-705691c38f72
(... logs)
build finished: c4c9e7c6-a93e-43a3-ac14-705691c38f72

Monitoring Builds

Since builds happen asynchronously on the platform, you can monitor their status and logs to troubleshoot any compilation or dependency errors.

Listing Builds

To see the history and status of all builds for your current context:

fathom intelligence function build list

Viewing Build Logs

If a build fails or you want to see the detailed compilation output, use the logs command. Note that you need both the Function ID and the Build ID (which you can get from the list command).

fathom intelligence function build logs <FUNCTION_ID> <BUILD_ID>

Deploying a Build

While --auto-deploy is the most common workflow, you can also deploy a previously “Successfully Built” artifact manually.

fathom intelligence function deploy <FUNCTION_ID> <BUILD_ID>

Manual deployment is useful when you want to roll back to an older, stable build without re-building the entire source.

Next Step

Once your function is successfully deployed, it is ready to handle requests.

Proceed to Interaction to learn how to call your function and monitor its runtime logs.

4 - Interaction and debugging

This document provides instructions for testing and maintaining your functions post-deployment. It explains how to trigger function logic directly from the CLI with custom payloads and how to stream real-time logs to troubleshoot execution errors or monitor performance.

Once your function is successfully deployed and in a “Running” state, you can interact with it and monitor its execution. This section covers triggering function logic via the CLI and accessing runtime logs.

Invoking Functions

To execute your function and see the result, use the call command group. This allows you to send data to your function and receive the processed output directly in your terminal.

Creating a Call

The call create command triggers the execution of your deployed function.

fathom intelligence function call create <FUNCTION_ID> [OPTIONS]

To read file context stdout can be used:

echo '{}' | fathom intelligence function call create --data - <FUNCTION_ID>

Listing Calls

To see the history of executions, their statuses (e.g., Succeeded, Failed), and execution times:

fathom intelligence function call list <FUNCTION_ID>

Runtime Logs

Debugging a serverless function requires visibility into what happens during execution. The logs command streams the standard output (stdout) and error (stderr) logs from your running instances.

Viewing Function Logs

Unlike build logs, which focus on compilation, these logs show your application’s logic in action (e.g., print statements, caught exceptions, or incoming request traces).

fathom intelligence function logs <FUNCTION_ID>

Real-time Debugging: Keep this command running with --watch option in a separate terminal window while you use call create to see immediate feedback.
Troubleshooting: If a call fails with a generic error, the logs will typically contain the specific stack trace or error message from your code.

Summary

You have completed the full lifecycle of a Fathom Intelligence Function:

Management: Created the resource.
Source: Uploaded your code.
Build/Deploy: Compiled and released the service.
Interaction: Verified the logic and monitored logs.

Need help? Run fathom --help at any time for a full list of global commands.