Create a workflow

Workflows automate data transformation in Rational AI. This guide covers creating, configuring, and testing workflows that convert raw data into AI-ready knowledge using AI.

📖WHAT IS A WORKFLOW?

Workflows automate the transformation of raw data into AI-ready knowledge. They extract key information, augment it, identify connections between data points, and structure everything into a queryable knowledge base that your AI applications can use.

Prerequisites

Before creating workflows, ensure you have:

• Permissions to access to the AI Control Room Settings area
• A Knowledge base created (workflows operate on Knowledge bases)
• Python and uv package manager installed (installation guide)

Access the workflow interface

Navigate to Settings → Workflows from the left sidebar. This is the central workspace for creating and managing workflows and processing rules.

Workflow list

The left panel displays all workflows that have been created in your environment. For each workflow, you can see:

• The workflow name.
• An enable/disable toggle.

This list gives you a high-level view of which processes are active and which aren’t.

Workflow editor

When you select a workflow from the list, its details are displayed on the right side. This is where you define how your workflow behaves.

The editor includes:

• The workflow name and description.
• The editable logic or configuration area (JSON or script-based input).
• An action menu that allows you to: /* * Open the workflow in the Lab. */
  • Edit its logic.
  • Delete the workflow.

Creating your first workflow

If you’re a new user, the workflow page may initially be empty. In this case, you can create your first workflow in a few simple steps.

• Click the + New button in the center of the page.
• Enter a clear and descriptive name: for example PDF processing workflow.
• Optionally, add a short description explaining the purpose of the workflow. This is strongly recommended for long-term maintainability.
• Enable your workflow from the list and you’re done.

Workflow logic

Let's create a simple, yet effective, workflow that takes as input a lorem-ipsum markdown file, creates a Rational Resource associated with it and performs chunking and embedding automatically, to allow semantic retrieval in a RAG scenario.

The workflow business logic is defined as below:

#!/usr/bin/env -S uv run --script
# /// script
# requires-python = ">=3.12"
# dependencies = [
#     "rational-client",
# ]
#
# ///

from rational_client.core import (
    Knowledge,
    SyncedResource,
)
from rational_client.utils import run


def process(document: SyncedResource, options: dict):
    # Read document content (bytes)
    content = document.get_data()

    # Convert to string (assumes content is textual)
    text = content.decode("utf-8")
    
    # Get the Knowledge instance this document belongs to
    knowledge = Knowledge(document.knowledge_id)

    # Create a new Rational Resource in the Knowledge Base
    new_resource = knowledge.create_resource(
        name=document.name,
        category="document_category",
        tags=["some", "tags"],
        synced_resource_id=document.id,
    )

    # Return the content for chunking and embedding (optional)
    return {str(new_resource.resource_id): text}


run(process)

Let's break it down:

• the workflow starts with an incipit which species the script dependencies (in the PEP 723 format): this allows to specify arbitrary script dependencies in your workflow, no whitelisted packages!
• at the bottom we can find the workflow entrypoint, the run(process) function, which is an utility function to invoke the process function defined
• the workflow business logic is specified in the process function: it takes as input the document over which the workflow is applied, and some options that might be used to store values later used in the workflow code
• the workflow typically might invoke operation on Rational AI through the rational-client package, such as retrieving a Knowledge handle, i.e. knowledge = Knowledge(document.knowledge_id)
• the workflow might return a dictionary specifying the Rational Resources created and their textual content, i.e. text/markdown, to be automatically chunked and embedded according to the Knowledge settings

Testing your workflow locally

It is convenient to perform workflow development on your local machine, before using them into Rational AI. This is not only possible, but also encouraged, as it allows to use your favorite IDE and debugging tools.

To run your workflow locally, you just need to make it executable and pass a properly formatted input as argument to it.

Let's suppose to call the above-defined workflow as lorem-ipsum-wf.py. We can make it executable by running the command:

chmod +x lorem-ipsum-wf.py

Then, we need to prepare a Json file as input, let's call it workflow_input.json. This file needs to have this structure:

{
    "knowledge_id": "<YOUR KNOWLEDGE ID>",
    "path": "<YOUR DOCUMENT FILEPATH>",
    "options": {}
}

Once configured, we can pass the workflow_input.json file as input to our workflow, as:

./lorem-ipsum-wf.py workflow_input.json

to test our workflow locally.