diff --git a/README.md b/README.md index 369d64553..355a168e0 100644 --- a/README.md +++ b/README.md @@ -1,1077 +1,377 @@ -# Conductor OSS Python SDK -[![CI Status](https://github.com/conductor-oss/python-sdk/actions/workflows/pull_request.yml/badge.svg)](https://github.com/conductor-oss/python-sdk/actions/workflows/pull_request.yml) - -Python SDK for working with https://github.com/conductor-oss/conductor. - -[Conductor](https://www.conductor-oss.org/) is the leading open-source orchestration platform allowing developers to build highly scalable distributed applications. +# Conductor Python SDK -Check out the [official documentation for Conductor](https://orkes.io/content). +[![CI Status](https://github.com/conductor-oss/python-sdk/actions/workflows/pull_request.yml/badge.svg)](https://github.com/conductor-oss/python-sdk/actions/workflows/pull_request.yml) -## ⭐ Conductor OSS +Python SDK for [Conductor](https://www.conductor-oss.org/) — the leading open-source orchestration platform for building distributed applications, AI agents, and workflow-driven microservices. Define workflows as code, run workers anywhere, and let Conductor handle retries, state management, and observability. -Show support for the Conductor OSS. Please help spread the awareness by starring Conductor repo. +If you find [Conductor](https://github.com/conductor-oss/conductor) useful, please consider giving it a star on GitHub -- it helps the project grow. [![GitHub stars](https://img.shields.io/github/stars/conductor-oss/conductor.svg?style=social&label=Star&maxAge=)](https://GitHub.com/conductor-oss/conductor/) -## Content - - - - -- [Install Conductor Python SDK](#install-conductor-python-sdk) - - [Get Conductor Python SDK](#get-conductor-python-sdk) -- [Hello World Application Using Conductor](#hello-world-application-using-conductor) - - [Step 1: Create Workflow](#step-1-create-workflow) - - [Creating Workflows by Code](#creating-workflows-by-code) - - [(Alternatively) Creating Workflows in JSON](#alternatively-creating-workflows-in-json) - - [Step 2: Write Task Worker](#step-2-write-task-worker) - - [Step 3: Write _Hello World_ Application](#step-3-write-_hello-world_-application) -- [Running Workflows on Conductor Standalone (Installed Locally)](#running-workflows-on-conductor-standalone-installed-locally) - - [Setup Environment Variable](#setup-environment-variable) - - [Start Conductor Server](#start-conductor-server) - - [Execute Hello World Application](#execute-hello-world-application) -- [Running Workflows on Orkes Conductor](#running-workflows-on-orkes-conductor) -- [Learn More about Conductor Python SDK](#learn-more-about-conductor-python-sdk) -- [Create and Run Conductor Workers](#create-and-run-conductor-workers) -- [Writing Workers](#writing-workers) - - [Implementing Workers](#implementing-workers) - - [Managing Workers in Application](#managing-workers-in-application) - - [Design Principles for Workers](#design-principles-for-workers) - - [System Task Workers](#system-task-workers) - - [Wait Task](#wait-task) - - [Using Code to Create Wait Task](#using-code-to-create-wait-task) - - [JSON Configuration](#json-configuration) - - [HTTP Task](#http-task) - - [Using Code to Create HTTP Task](#using-code-to-create-http-task) - - [JSON Configuration](#json-configuration-1) - - [Javascript Executor Task](#javascript-executor-task) - - [Using Code to Create Inline Task](#using-code-to-create-inline-task) - - [JSON Configuration](#json-configuration-2) - - [JSON Processing using JQ](#json-processing-using-jq) - - [Using Code to Create JSON JQ Transform Task](#using-code-to-create-json-jq-transform-task) - - [JSON Configuration](#json-configuration-3) - - [Worker vs. Microservice/HTTP Endpoints](#worker-vs-microservicehttp-endpoints) - - [Deploying Workers in Production](#deploying-workers-in-production) -- [Create Conductor Workflows](#create-conductor-workflows) - - [Conductor Workflows](#conductor-workflows) - - [Creating Workflows](#creating-workflows) - - [Execute Dynamic Workflows Using Code](#execute-dynamic-workflows-using-code) - - [Kitchen-Sink Workflow](#kitchen-sink-workflow) - - [Executing Workflows](#executing-workflows) - - [Execute Workflow Asynchronously](#execute-workflow-asynchronously) - - [Execute Workflow Synchronously](#execute-workflow-synchronously) - - [Managing Workflow Executions](#managing-workflow-executions) - - [Get Execution Status](#get-execution-status) - - [Update Workflow State Variables](#update-workflow-state-variables) - - [Terminate Running Workflows](#terminate-running-workflows) - - [Retry Failed Workflows](#retry-failed-workflows) - - [Restart Workflows](#restart-workflows) - - [Rerun Workflow from a Specific Task](#rerun-workflow-from-a-specific-task) - - [Pause Running Workflow](#pause-running-workflow) - - [Resume Paused Workflow](#resume-paused-workflow) - - [Searching for Workflows](#searching-for-workflows) - - [Handling Failures, Retries and Rate Limits](#handling-failures-retries-and-rate-limits) - - [Retries](#retries) - - [Rate Limits](#rate-limits) - - [Task Registration](#task-registration) - - [Update Task Definition:](#update-task-definition) -- [Using Conductor in Your Application](#using-conductor-in-your-application) - - [Adding Conductor SDK to Your Application](#adding-conductor-sdk-to-your-application) - - [Testing Workflows](#testing-workflows) - - [Example Unit Testing Application](#example-unit-testing-application) - - [Workflow Deployments Using CI/CD](#workflow-deployments-using-cicd) - - [Versioning Workflows](#versioning-workflows) - - - -## Install Conductor Python SDK - -Before installing Conductor Python SDK, it is a good practice to set up a dedicated virtual environment as follows: +## 60-Second Quickstart + +Install the SDK and create a single file `quickstart.py`: ```shell -virtualenv conductor -source conductor/bin/activate +pip install conductor-python ``` -### Get Conductor Python SDK +## Setting Up Conductor -The SDK requires Python 3.9+. To install the SDK, use the following command: +If you don't already have a Conductor server running: +**macOS / Linux:** ```shell -python3 -m pip install conductor-python +curl -sSL https://raw.githubusercontent.com/conductor-oss/conductor/main/conductor_server.sh | sh ``` -## 🚀 Quick Start - -For a complete end-to-end example, see [examples/workers_e2e.py](examples/workers_e2e.py): - -```bash -export CONDUCTOR_SERVER_URL="http://localhost:8080/api" -python3 examples/workers_e2e.py +**Docker:** +```shell +docker run -p 8080:8080 conductoross/conductor:latest ``` +The UI will be available at `http://localhost:8080`. -This example demonstrates: -- Registering a workflow definition -- Starting workflow execution -- Running workers (sync + async) -- Monitoring with Prometheus metrics -- Long-running tasks with lease extension - -**What you'll see:** -- Workflow URL to monitor execution in UI -- Workers processing tasks (AsyncTaskRunner vs TaskRunner) -- Metrics endpoint at http://localhost:8000/metrics -- Long-running task with TaskInProgress (5 polls) - -## ⚡ Performance Features (SDK 1.3.0+) - -The Python SDK provides high-performance worker execution with automatic optimization: - -**Worker Architecture:** -- **AsyncTaskRunner** for async workers (`async def`) - Pure async/await, zero thread overhead -- **TaskRunner** for sync workers (`def`) - ThreadPoolExecutor for concurrent execution -- **Automatic selection** - Based on function signature, no configuration needed -- **One process per worker** - Process isolation and fault tolerance - -**Performance Optimizations:** -- **Dynamic batch polling** - Batch size adapts to available capacity (thread_count - running tasks) -- **Adaptive backoff** - Exponential backoff when queue empty (1ms → 2ms → 4ms → poll_interval) -- **High concurrency** - Async workers support higher task throughput, sync workers use thread pools - -**AsyncTaskRunner Benefits (async def workers):** -- Fewer threads per worker (single event loop) -- Lower memory footprint per worker -- Better I/O throughput for async workloads -- Direct `await worker_fn()` execution - -See [docs/design/WORKER_DESIGN.md](docs/design/WORKER_DESIGN.md) for complete architecture details. - -## 📚 Documentation - -**Getting Started:** -- **[End-to-End Example](examples/workers_e2e.py)** - Complete workflow execution with workers -- **[Examples Guide](examples/EXAMPLES_README.md)** - All examples with quick reference - -**Worker Documentation:** -- **[Worker Design & Architecture](docs/design/WORKER_DESIGN.md)** - Complete worker architecture guide - - AsyncTaskRunner vs TaskRunner - - Automatic runner selection - - Worker discovery, configuration, best practices - - Long-running tasks and lease extension - - Performance metrics and monitoring -- **[Worker Configuration](WORKER_CONFIGURATION.md)** - Hierarchical environment-based configuration -- **[Complete Worker Guide](docs/WORKER.md)** - Comprehensive worker documentation - -**Monitoring & Advanced:** -- **[Metrics](METRICS.md)** - Prometheus metrics collection -- **[Event-Driven Architecture](docs/design/event_driven_interceptor_system.md)** - Observability design - -## Hello World Application Using Conductor - -In this section, we will create a simple "Hello World" application that executes a "greetings" workflow managed by Conductor. - -### Step 1: Create Workflow - -#### Creating Workflows by Code - -Create [greetings_workflow.py](examples/helloworld/greetings_workflow.py) with the following: - +## Run your first workflow app ```python +from conductor.client.automator.task_handler import TaskHandler +from conductor.client.configuration.configuration import Configuration from conductor.client.workflow.conductor_workflow import ConductorWorkflow from conductor.client.workflow.executor.workflow_executor import WorkflowExecutor -from greetings_worker import greet - -def greetings_workflow(workflow_executor: WorkflowExecutor) -> ConductorWorkflow: - name = 'greetings' - workflow = ConductorWorkflow(name=name, executor=workflow_executor) - workflow.version = 1 - workflow >> greet(task_ref_name='greet_ref', name=workflow.input('name')) - return workflow - - -``` - -#### (Alternatively) Creating Workflows in JSON - -Create `greetings_workflow.json` with the following: - -```json -{ - "name": "greetings", - "description": "Sample greetings workflow", - "version": 1, - "tasks": [ - { - "name": "greet", - "taskReferenceName": "greet_ref", - "type": "SIMPLE", - "inputParameters": { - "name": "${workflow.input.name}" - } - } - ], - "timeoutPolicy": "TIME_OUT_WF", - "timeoutSeconds": 60 -} -``` - -Workflows must be registered to the Conductor server. Use the API to register the greetings workflow from the JSON file above: -```shell -curl -X POST -H "Content-Type:application/json" \ -http://localhost:8080/api/metadata/workflow -d @greetings_workflow.json -``` -> [!note] -> To use the Conductor API, the Conductor server must be up and running (see [Running over Conductor standalone (installed locally)](#running-over-conductor-standalone-installed-locally)). - -### Step 2: Write Task Worker - -Using Python, a worker represents a function with the worker_task decorator. Create [greetings_worker.py](examples/helloworld/greetings_worker.py) file as illustrated below: - -> [!note] -> A single workflow can have task workers written in different languages and deployed anywhere, making your workflow polyglot and distributed! - -```python from conductor.client.worker.worker_task import worker_task +# Step 1: Define a worker — any Python function @worker_task(task_definition_name='greet') def greet(name: str) -> str: return f'Hello {name}' -``` -Now, we are ready to write our main application, which will execute our workflow. - -### Step 3: Write _Hello World_ Application - -Let's add [helloworld.py](examples/helloworld/helloworld.py) with a `main` method: - -```python -from conductor.client.automator.task_handler import TaskHandler -from conductor.client.configuration.configuration import Configuration -from conductor.client.workflow.conductor_workflow import ConductorWorkflow -from conductor.client.workflow.executor.workflow_executor import WorkflowExecutor -from greetings_workflow import greetings_workflow - - -def register_workflow(workflow_executor: WorkflowExecutor) -> ConductorWorkflow: - workflow = greetings_workflow(workflow_executor=workflow_executor) - workflow.register(True) - return workflow - def main(): - # The app is connected to http://localhost:8080/api by default - api_config = Configuration() + # Step 2: Configure the SDK (reads CONDUCTOR_SERVER_URL from env) + config = Configuration() - workflow_executor = WorkflowExecutor(configuration=api_config) - - # Registering the workflow (Required only when the app is executed the first time) - workflow = register_workflow(workflow_executor) + # Step 3: Build a workflow with the >> operator + executor = WorkflowExecutor(configuration=config) + workflow = ConductorWorkflow(name='greetings', version=1, executor=executor) + workflow >> greet(task_ref_name='greet_ref', name=workflow.input('name')) + workflow.register(True) - # Starting the worker polling mechanism - task_handler = TaskHandler(configuration=api_config) + # Step 4: Start polling for tasks + task_handler = TaskHandler(configuration=config) task_handler.start_processes() - workflow_run = workflow_executor.execute(name=workflow.name, version=workflow.version, - workflow_input={'name': 'Orkes'}) + # Step 5: Run the workflow and get the result + result = executor.execute(name='greetings', version=1, workflow_input={'name': 'Conductor'}) + print(f'result: {result.output["result"]}') + print(f'execution: {config.ui_host}/execution/{result.workflow_id}') - print(f'\nworkflow result: {workflow_run.output["result"]}\n') - print(f'see the workflow execution here: {api_config.ui_host}/execution/{workflow_run.workflow_id}\n') task_handler.stop_processes() if __name__ == '__main__': main() ``` -## Running Workflows on Conductor Standalone (Installed Locally) - -### Setup Environment Variable - -Set the following environment variable to point the SDK to the Conductor Server API endpoint: - -```shell -export CONDUCTOR_SERVER_URL=http://localhost:8080/api -``` -### Start Conductor Server -To start the Conductor server in a standalone mode from a Docker image, type the command below: +Run it: ```shell -docker run --init -p 8080:8080 -p 5000:5000 conductoross/conductor-standalone:3.15.0 -``` -To ensure the server has started successfully, open Conductor UI on http://localhost:5000. - -### Execute Hello World Application - -To run the application, type the following command: - -``` -python helloworld.py +export CONDUCTOR_SERVER_URL="http://localhost:8080/api" +python quickstart.py ``` -Now, the workflow is executed, and its execution status can be viewed from Conductor UI (http://localhost:5000). +> **Using Orkes Conductor?** Export your authentication credentials as well: +> ```shell +> export CONDUCTOR_SERVER_URL="https://your-cluster.orkesconductor.io/api" +> export CONDUCTOR_AUTH_KEY="your-key" +> export CONDUCTOR_AUTH_SECRET="your-secret" +> ``` +> See [Configuration](#configuration) for details. -Navigate to the **Executions** tab to view the workflow execution. +That's it -- you just defined a worker, built a workflow, and executed it. Open [http://localhost:8080](http://localhost:8080) to see the execution in the Conductor UI. -Screenshot 2024-03-18 at 12 30 07 +### Comprehensive example with sync + async workers, metrics, and long-running tasks -## Running Workflows on Orkes Conductor +See [examples/workers_e2e.py](examples/workers_e2e.py) -For running the workflow in Orkes Conductor, +### Configuration -- Update the Conductor server URL to your cluster name. +The SDK reads configuration from environment variables: ```shell -export CONDUCTOR_SERVER_URL=https://[cluster-name].orkesconductor.io/api -``` - -- If you want to run the workflow on the Orkes Conductor Playground, set the Conductor Server variable as follows: - -```shell -export CONDUCTOR_SERVER_URL=https://developer.orkescloud.com/api -``` - -- Orkes Conductor requires authentication. [Obtain the key and secret from the Conductor server](https://orkes.io/content/how-to-videos/access-key-and-secret) and set the following environment variables. +# Required — Conductor server endpoint +export CONDUCTOR_SERVER_URL="http://localhost:8080/api" -```shell -export CONDUCTOR_AUTH_KEY=your_key -export CONDUCTOR_AUTH_SECRET=your_key_secret +# Optional — Authentication (required for Orkes Conductor) +export CONDUCTOR_AUTH_KEY="your-key" +export CONDUCTOR_AUTH_SECRET="your-secret" ``` +--- -Run the application and view the execution status from Conductor's UI Console. - -> [!NOTE] -> That's it - you just created and executed your first distributed Python app! - -## Learn More about Conductor Python SDK - -There are three main ways you can use Conductor when building durable, resilient, distributed applications. - -1. Write service workers that implement business logic to accomplish a specific goal - such as initiating payment transfer, getting user information from the database, etc. -2. Create Conductor workflows that implement application state - A typical workflow implements the saga pattern. -3. Use Conductor SDK and APIs to manage workflows from your application. - -## Create and Run Conductor Workers - -## Writing Workers - -A Workflow task represents a unit of business logic that achieves a specific goal, such as checking inventory, initiating payment transfer, etc. A worker implements a task in the workflow. - - -### Implementing Workers +## Workers -The workers can be implemented by writing a simple Python function and annotating the function with the `@worker_task`. Conductor workers are services (similar to microservices) that follow the [Single Responsibility Principle](https://en.wikipedia.org/wiki/Single_responsibility_principle). - -Workers can be hosted along with the workflow or run in a distributed environment where a single workflow uses workers deployed and running in different machines/VMs/containers. Whether to keep all the workers in the same application or run them as a distributed application is a design and architectural choice. Conductor is well suited for both kinds of scenarios. - -You can create or convert any existing Python function to a distributed worker by adding `@worker_task` annotation to it. Here is a simple worker that takes `name` as input and returns greetings: +Workers are Python functions that execute tasks. Decorate any function with `@worker_task` to make it a distributed worker: +Note: Workers can be used by LLMs for tool calling. ```python from conductor.client.worker.worker_task import worker_task -@worker_task(task_definition_name='greetings') -def greetings(name: str) -> str: - return f'Hello, {name}' +@worker_task(task_definition_name='greet') +def greet(name: str) -> str: + return f'Hello {name}' ``` -**Async Workers:** Workers can be defined as `async def` functions for I/O-bound tasks. The SDK automatically uses **AsyncTaskRunner** for pure async/await execution with high concurrency: +**Async workers** for I/O-bound tasks — the SDK automatically uses `AsyncTaskRunner` (event loop, no thread overhead): ```python -@worker_task(task_definition_name='fetch_data', thread_count=50) +@worker_task(task_definition_name='fetch_data') async def fetch_data(url: str) -> dict: - # Automatically uses AsyncTaskRunner (not TaskRunner) - # - Pure async/await execution (no thread overhead) - # - Single event loop per process - # - Up to 50 concurrent tasks async with httpx.AsyncClient() as client: response = await client.get(url) return response.json() ``` -**Sync Workers:** Use regular `def` functions for CPU-bound or blocking I/O tasks: - -```python -@worker_task(task_definition_name='process_data', thread_count=5) -def process_data(data: dict) -> dict: - # Automatically uses TaskRunner (ThreadPoolExecutor) - # - 5 concurrent threads - # - Best for CPU-bound tasks or blocking I/O - result = expensive_computation(data) - return {'result': result} -``` - -**The SDK automatically selects the right execution model** based on your function signature (`def` vs `async def`). - -A worker can take inputs which are primitives - `str`, `int`, `float`, `bool` etc. or can be complex data classes. - -Here is an example worker that uses `dataclass` as part of the worker input. - -```python -from conductor.client.worker.worker_task import worker_task -from dataclasses import dataclass - -@dataclass -class OrderInfo: - order_id: int - sku: str - quantity: int - sku_price: float - - -@worker_task(task_definition_name='process_order') -def process_order(order_info: OrderInfo) -> str: - return f'order: {order_info.order_id}' - -``` - -### Managing Workers in Application - -Workers use a polling mechanism (with a long poll) to check for any available tasks from the server periodically. The startup and shutdown of workers are handled by the `conductor.client.automator.task_handler.TaskHandler` class. +**Start workers** with `TaskHandler`: ```python from conductor.client.automator.task_handler import TaskHandler from conductor.client.configuration.configuration import Configuration -def main(): - # points to http://localhost:8080/api by default - api_config = Configuration() - - task_handler = TaskHandler( - workers=[], - configuration=api_config, - scan_for_annotated_workers=True, - import_modules=['greetings'] # import workers from this module - leave empty if all the workers are in the same module - ) - - # start worker polling - task_handler.start_processes() - - # Call to stop the workers when the application is ready to shutdown - task_handler.stop_processes() - - -if __name__ == '__main__': - main() - -``` - -**Worker Configuration:** Workers support hierarchical configuration via environment variables, allowing you to override settings at deployment without code changes: - -```bash -# Global configuration (applies to all workers) - Unix format recommended -export CONDUCTOR_WORKER_ALL_DOMAIN=production -export CONDUCTOR_WORKER_ALL_POLL_INTERVAL_MILLIS=250 -export CONDUCTOR_WORKER_ALL_THREAD_COUNT=20 - -# Task registration configuration -export CONDUCTOR_WORKER_ALL_REGISTER_TASK_DEF=true # Auto-register task definitions -export CONDUCTOR_WORKER_ALL_OVERWRITE_TASK_DEF=true # Overwrite existing (default) -export CONDUCTOR_WORKER_ALL_STRICT_SCHEMA=false # Lenient schema validation (default) - -# Worker-specific configuration (overrides global) -export CONDUCTOR_WORKER_GREETINGS_THREAD_COUNT=50 -export CONDUCTOR_WORKER_VALIDATE_ORDER_STRICT_SCHEMA=true # Strict validation for this worker - -# Runtime control (pause/resume workers without code changes) -export CONDUCTOR_WORKER_ALL_PAUSED=true # Maintenance mode - -# Alternative: Dot notation also works -# export conductor.worker.all.strict_schema=true -# export conductor.worker.validate_order.strict_schema=false -``` - -Workers log their resolved configuration on startup: -``` -INFO - Conductor Worker[name=greetings, pid=12345, status=active, poll_interval=250ms, domain=production, thread_count=50] -``` - -**Configuration Priority:** Worker-specific > Global > Code defaults - -For detailed configuration options, see [WORKER_CONFIGURATION.md](WORKER_CONFIGURATION.md). - -**Monitoring:** Enable Prometheus metrics with built-in HTTP server: - -```python -from conductor.client.configuration.settings.metrics_settings import MetricsSettings - -metrics_settings = MetricsSettings( - directory='/tmp/conductor-metrics', # Multiprocess coordination - http_port=8000 # HTTP metrics endpoint -) - +api_config = Configuration() task_handler = TaskHandler( + workers=[], configuration=api_config, - metrics_settings=metrics_settings, - scan_for_annotated_workers=True + scan_for_annotated_workers=True, ) -# Metrics available at: http://localhost:8000/metrics -``` - -For more details, see [METRICS.md](METRICS.md) and [docs/design/WORKER_DESIGN.md](docs/design/WORKER_DESIGN.md). - -### Design Principles for Workers - -Each worker embodies the design pattern and follows certain basic principles: - -1. Workers are stateless and do not implement a workflow-specific logic. -2. Each worker executes a particular task and produces well-defined output given specific inputs. -3. Workers are meant to be idempotent (Should handle cases where the partially executed task, due to timeouts, etc, gets rescheduled). -4. Workers do not implement the logic to handle retries, etc., that is taken care of by the Conductor server. - -#### System Task Workers - -A system task worker is a pre-built, general-purpose worker in your Conductor server distribution. - -System tasks automate repeated tasks such as calling an HTTP endpoint, executing lightweight ECMA-compliant javascript code, publishing to an event broker, etc. - -#### Wait Task - -> [!tip] -> Wait is a powerful way to have your system wait for a specific trigger, such as an external event, a particular date/time, or duration, such as 2 hours, without having to manage threads, background processes, or jobs. - -##### Using Code to Create Wait Task - -```python -from conductor.client.workflow.task.wait_task import WaitTask - -# waits for 2 seconds before scheduling the next task -wait_for_two_sec = WaitTask(task_ref_name='wait_for_2_sec', wait_for_seconds=2) - -# wait until end of jan -wait_till_jan = WaitTask(task_ref_name='wait_till_jsn', wait_until='2024-01-31 00:00 UTC') - -# waits until an API call or an event is triggered -wait_for_signal = WaitTask(task_ref_name='wait_till_jan_end') - -``` -##### JSON Configuration - -```json -{ - "name": "wait", - "taskReferenceName": "wait_till_jan_end", - "type": "WAIT", - "inputParameters": { - "until": "2024-01-31 00:00 UTC" - } -} -``` -#### HTTP Task - -Make a request to an HTTP(S) endpoint. The task allows for GET, PUT, POST, DELETE, HEAD, and PATCH requests. - -##### Using Code to Create HTTP Task - -```python -from conductor.client.workflow.task.http_task import HttpTask - -HttpTask(task_ref_name='call_remote_api', http_input={ - 'uri': 'https://orkes-api-tester.orkesconductor.com/api' - }) +task_handler.start_processes() ``` -##### JSON Configuration - -```json -{ - "name": "http_task", - "taskReferenceName": "http_task_ref", - "type" : "HTTP", - "uri": "https://orkes-api-tester.orkesconductor.com/api", - "method": "GET" -} -``` - -#### Javascript Executor Task - -Execute ECMA-compliant Javascript code. It is useful when writing a script for data mapping, calculations, etc. - -##### Using Code to Create Inline Task - -```python -from conductor.client.workflow.task.javascript_task import JavascriptTask - -say_hello_js = """ -function greetings() { - return { - "text": "hello " + $.name - } -} -greetings(); -""" - -js = JavascriptTask(task_ref_name='hello_script', script=say_hello_js, bindings={'name': '${workflow.input.name}'}) -``` -##### JSON Configuration - -```json -{ - "name": "inline_task", - "taskReferenceName": "inline_task_ref", - "type": "INLINE", - "inputParameters": { - "expression": " function greetings() {\n return {\n \"text\": \"hello \" + $.name\n }\n }\n greetings();", - "evaluatorType": "graaljs", - "name": "${workflow.input.name}" - } -} -``` +Workers support complex inputs (dataclasses), long-running tasks (`TaskInProgress`), and hierarchical configuration via environment variables. -#### JSON Processing using JQ +**Learn more:** +- [Worker Design & Architecture](docs/design/WORKER_DESIGN.md) — AsyncTaskRunner vs TaskRunner, discovery, lifecycle +- [Worker Configuration](WORKER_CONFIGURATION.md) — Environment variable configuration system +- [Complete Worker Guide](docs/WORKER.md) — All worker patterns (function, class, annotation, async) -[Jq](https://jqlang.github.io/jq/) is like sed for JSON data - you can slice, filter, map, and transform structured data with the same ease that sed, awk, grep, and friends let you play with text. +## Workflows -##### Using Code to Create JSON JQ Transform Task +Define workflows in Python using the `>>` operator to chain tasks: ```python -from conductor.client.workflow.task.json_jq_task import JsonJQTask - -jq_script = """ -{ key3: (.key1.value1 + .key2.value2) } -""" - -jq = JsonJQTask(task_ref_name='jq_process', script=jq_script) -``` -##### JSON Configuration - -```json -{ - "name": "json_transform_task", - "taskReferenceName": "json_transform_task_ref", - "type": "JSON_JQ_TRANSFORM", - "inputParameters": { - "key1": "k1", - "key2": "k2", - "queryExpression": "{ key3: (.key1.value1 + .key2.value2) }", - } -} -``` - -### Worker vs. Microservice/HTTP Endpoints - -> [!tip] -> Workers are a lightweight alternative to exposing an HTTP endpoint and orchestrating using HTTP tasks. Using workers is a recommended approach if you do not need to expose the service over HTTP or gRPC endpoints. - -There are several advantages to this approach: - -1. **No need for an API management layer** : Given there are no exposed endpoints and workers are self-load-balancing. -2. **Reduced infrastructure footprint** : No need for an API gateway/load balancer. -3. All the communication is initiated by workers using polling - avoiding the need to open up any incoming TCP ports. -4. Workers **self-regulate** when busy; they only poll as much as they can handle. Backpressure handling is done out of the box. -5. Workers can be scaled up/down quickly based on the demand by increasing the number of processes. - -### Deploying Workers in Production - -Conductor workers can run in the cloud-native environment or on-prem and can easily be deployed like any other Python application. Workers can run a containerized environment, VMs, or bare metal like you would deploy your other Python applications. - -## Create Conductor Workflows - -### Conductor Workflows - -Workflow can be defined as the collection of tasks and operators that specify the order and execution of the defined tasks. This orchestration occurs in a hybrid ecosystem that encircles serverless functions, microservices, and monolithic applications. - -This section will dive deeper into creating and executing Conductor workflows using Python SDK. - - -### Creating Workflows - -Conductor lets you create the workflows using either Python or JSON as the configuration. - -Using Python as code to define and execute workflows lets you build extremely powerful, dynamic workflows and run them on Conductor. - -When the workflows are relatively static, they can be designed using the Orkes UI (available when using Orkes Conductor) and APIs or SDKs to register and run the workflows. - -Both the code and configuration approaches are equally powerful and similar in nature to how you treat Infrastructure as Code. - -#### Execute Dynamic Workflows Using Code - -For cases where the workflows cannot be created statically ahead of time, Conductor is a powerful dynamic workflow execution platform that lets you create very complex workflows in code and execute them. It is useful when the workflow is unique for each execution. - -```python -from conductor.client.automator.task_handler import TaskHandler -from conductor.client.configuration.configuration import Configuration -from conductor.client.orkes_clients import OrkesClients -from conductor.client.worker.worker_task import worker_task from conductor.client.workflow.conductor_workflow import ConductorWorkflow +from conductor.client.workflow.executor.workflow_executor import WorkflowExecutor -#@worker_task annotation denotes that this is a worker -@worker_task(task_definition_name='get_user_email') -def get_user_email(userid: str) -> str: - return f'{userid}@example.com' - -#@worker_task annotation denotes that this is a worker -@worker_task(task_definition_name='send_email') -def send_email(email: str, subject: str, body: str): - print(f'sending email to {email} with subject {subject} and body {body}') - - -def main(): - - # defaults to reading the configuration using following env variables - # CONDUCTOR_SERVER_URL : conductor server e.g. https://developer.orkescloud.com/api - # CONDUCTOR_AUTH_KEY : API Authentication Key - # CONDUCTOR_AUTH_SECRET: API Auth Secret - api_config = Configuration() - - task_handler = TaskHandler(configuration=api_config) - #Start Polling - task_handler.start_processes() - - clients = OrkesClients(configuration=api_config) - workflow_executor = clients.get_workflow_executor() - workflow = ConductorWorkflow(name='dynamic_workflow', version=1, executor=workflow_executor) - get_email = get_user_email(task_ref_name='get_user_email_ref', userid=workflow.input('userid')) - sendmail = send_email(task_ref_name='send_email_ref', email=get_email.output('result'), subject='Hello from Orkes', - body='Test Email') - #Order of task execution - workflow >> get_email >> sendmail - - # Configure the output of the workflow - workflow.output_parameters(output_parameters={ - 'email': get_email.output('result') - }) - #Run the workflow - result = workflow.execute(workflow_input={'userid': 'user_a'}) - print(f'\nworkflow output: {result.output}\n') - #Stop Polling - task_handler.stop_processes() - - -if __name__ == '__main__': - main() - -``` - -```shell ->> python3 dynamic_workflow.py - -2024-02-03 19:54:35,700 [32853] conductor.client.automator.task_handler INFO created worker with name=get_user_email and domain=None -2024-02-03 19:54:35,781 [32853] conductor.client.automator.task_handler INFO created worker with name=send_email and domain=None -2024-02-03 19:54:35,859 [32853] conductor.client.automator.task_handler INFO TaskHandler initialized -2024-02-03 19:54:35,859 [32853] conductor.client.automator.task_handler INFO Starting worker processes... -2024-02-03 19:54:35,861 [32853] conductor.client.automator.task_runner INFO Polling task get_user_email with domain None with polling interval 0.1 -2024-02-03 19:54:35,861 [32853] conductor.client.automator.task_handler INFO Started 2 TaskRunner process -2024-02-03 19:54:35,862 [32853] conductor.client.automator.task_handler INFO Started all processes -2024-02-03 19:54:35,862 [32853] conductor.client.automator.task_runner INFO Polling task send_email with domain None with polling interval 0.1 -sending email to user_a@example.com with subject Hello from Orkes and body Test Email - -workflow output: {'email': 'user_a@example.com'} - -2024-02-03 19:54:36,309 [32853] conductor.client.automator.task_handler INFO Stopped worker processes... +workflow_executor = WorkflowExecutor(configuration=api_config) +workflow = ConductorWorkflow(name='greetings', version=1, executor=workflow_executor) +workflow >> greet(task_ref_name='greet_ref', name=workflow.input('name')) +workflow.register(True) ``` -See [dynamic_workflow.py](examples/dynamic_workflow.py) for a fully functional example. - -#### Kitchen-Sink Workflow - -For a more complex workflow example with all the supported features, see [kitchensink.py](examples/kitchensink.py). -### Executing Workflows - -The [WorkflowClient](src/conductor/client/workflow_client.py) interface provides all the APIs required to work with workflow executions. +**Execute workflows:** ```python -from conductor.client.configuration.configuration import Configuration -from conductor.client.orkes_clients import OrkesClients - -api_config = Configuration() -clients = OrkesClients(configuration=api_config) -workflow_client = clients.get_workflow_client() -``` -#### Execute Workflow Asynchronously - -Useful when workflows are long-running. +# Synchronous (waits for completion) +result = workflow_executor.execute(name='greetings', version=1, workflow_input={'name': 'Orkes'}) +print(result.output) -```python +# Asynchronous (returns workflow ID immediately) from conductor.client.http.models import StartWorkflowRequest - -request = StartWorkflowRequest() -request.name = 'hello' -request.version = 1 -request.input = {'name': 'Orkes'} -# workflow id is the unique execution id associated with this execution +request = StartWorkflowRequest(name='greetings', version=1, input={'name': 'Orkes'}) workflow_id = workflow_client.start_workflow(request) ``` -#### Execute Workflow Synchronously - -Applicable when workflows complete very quickly - usually under 20-30 seconds. - -```python -from conductor.client.http.models import StartWorkflowRequest - -request = StartWorkflowRequest() -request.name = 'hello' -request.version = 1 -request.input = {'name': 'Orkes'} - -workflow_run = workflow_client.execute_workflow( - start_workflow_request=request, - wait_for_seconds=12) -``` - - -### Managing Workflow Executions -> [!note] -> See [workflow_ops.py](examples/workflow_ops.py) for a fully working application that demonstrates working with the workflow executions and sending signals to the workflow to manage its state. -Workflows represent the application state. With Conductor, you can query the workflow execution state anytime during its lifecycle. You can also send signals to the workflow that determines the outcome of the workflow state. - -[WorkflowClient](src/conductor/client/workflow_client.py) is the client interface used to manage workflow executions. +**Manage running workflows:** ```python -from conductor.client.configuration.configuration import Configuration from conductor.client.orkes_clients import OrkesClients -api_config = Configuration() clients = OrkesClients(configuration=api_config) workflow_client = clients.get_workflow_client() -``` - -### Get Execution Status -The following method lets you query the status of the workflow execution given the id. When the `include_tasks` is set, the response also includes all the completed and in-progress tasks. - -```python -get_workflow(workflow_id: str, include_tasks: Optional[bool] = True) -> Workflow +workflow_client.pause_workflow(workflow_id) +workflow_client.resume_workflow(workflow_id) +workflow_client.terminate_workflow(workflow_id, reason='no longer needed') +workflow_client.retry_workflow(workflow_id) +workflow_client.restart_workflow(workflow_id) ``` -### Update Workflow State Variables +**Learn more:** +- [Workflow Management](docs/WORKFLOW.md) — Start, pause, resume, terminate, retry, search +- [Workflow Testing](docs/WORKFLOW_TESTING.md) — Unit testing with mock task outputs +- [Metadata Management](docs/METADATA.md) — Task & workflow definitions -Variables inside a workflow are the equivalent of global variables in a program. +## Hello World -```python -update_variables(self, workflow_id: str, variables: Dict[str, object] = {}) -``` - -### Terminate Running Workflows - -Used to terminate a running workflow. Any pending tasks are canceled, and no further work is scheduled for this workflow upon termination. A failure workflow will be triggered but can be avoided if `trigger_failure_workflow` is set to False. - -```python -terminate_workflow(self, workflow_id: str, reason: Optional[str] = None, trigger_failure_workflow: bool = False) -``` - -### Retry Failed Workflows +The complete Hello World example lives in [`examples/helloworld/`](examples/helloworld/): -If the workflow has failed due to one of the task failures after exhausting the retries for the task, the workflow can still be resumed by calling the retry. - -```python -retry_workflow(self, workflow_id: str, resume_subworkflow_tasks: Optional[bool] = False) +```shell +python examples/helloworld/helloworld.py ``` -When a sub-workflow inside a workflow has failed, there are two options: +It creates a `greetings` workflow with one worker task, runs the worker, executes the workflow, and prints the result. See the [Hello World source](examples/helloworld/helloworld.py) for the full code. -1. Re-trigger the sub-workflow from the start (Default behavior). -2. Resume the sub-workflow from the failed task (set `resume_subworkflow_tasks` to True). +## AI & LLM Workflows -### Restart Workflows +Conductor supports AI-native workflows including agentic tool calling, RAG pipelines, and multi-agent orchestration. -A workflow in the terminal state (COMPLETED, TERMINATED, FAILED) can be restarted from the beginning. Useful when retrying from the last failed task is insufficient, and the whole workflow must be started again. +### Agentic Workflows -```python -restart_workflow(self, workflow_id: str, use_latest_def: Optional[bool] = False) -``` +Build AI agents where LLMs dynamically select and call Python workers as tools: -### Rerun Workflow from a Specific Task +| Example | Description | +|---------|-------------| +| [agentic_workflow.py](examples/agentic_workflow.py) | Interactive agent that calls Python workers (weather, search, calculator) based on user queries | +| [mcp_weather_agent.py](examples/mcp_weather_agent.py) | Agent using Model Context Protocol (MCP) for external tool discovery and execution | +| [multiagent_chat.py](examples/orkes/multiagent_chat.py) | Multi-agent conversation where multiple LLMs collaborate with routing and turn-taking | +| [open_ai_function_example.py](examples/orkes/open_ai_function_example.py) | OpenAI function calling with dynamic task execution in a loop | +| [open_ai_copilot.py](examples/orkes/copilot/open_ai_copilot.py) | Copilot-style assistant with human-in-the-loop, sub-workflows, and dynamic tool dispatch | -In the cases where a workflow needs to be restarted from a specific task rather than from the beginning, rerun provides that option. When issuing the rerun command to the workflow, you can specify the task ID from where the workflow should be restarted (as opposed to from the beginning), and optionally, the workflow's input can also be changed. +### LLM and RAG Workflows -```python -rerun_workflow(self, workflow_id: str, rerun_workflow_request: RerunWorkflowRequest) -``` +| Example | Description | +|---------|-------------| +| [rag_workflow.py](examples/rag_workflow.py) | End-to-end RAG: document conversion (PDF/Word/Excel), pgvector indexing, semantic search, answer generation | +| [vector_db_helloworld.py](examples/orkes/vector_db_helloworld.py) | Vector database operations: text indexing, embedding generation, and semantic search with Pinecone | +| [open_ai_chat_gpt.py](examples/orkes/open_ai_chat_gpt.py) | Multi-turn chat with OpenAI using conversation history in a loop | +| [open_ai_chat_user_input.py](examples/orkes/open_ai_chat_user_input.py) | Chat with human input -- pauses for user messages between LLM responses | +| [open_ai_helloworld.py](examples/orkes/open_ai_helloworld.py) | Minimal LLM text completion with OpenAI | -> [!tip] -> Rerun is one of the most powerful features Conductor has, giving you unparalleled control over the workflow restart. -> - -### Pause Running Workflow - -A running workflow can be put to a PAUSED status. A paused workflow lets the currently running tasks complete but does not schedule any new tasks until resumed. +```shell +# Agentic workflow +python examples/agentic_workflow.py -```python -pause_workflow(self, workflow_id: str) +# RAG pipeline +pip install "markitdown[pdf]" +python examples/rag_workflow.py document.pdf "What are the key findings?" ``` -### Resume Paused Workflow +### Worker Configuration -Resume operation resumes the currently paused workflow, immediately evaluating its state and scheduling the next set of tasks. +Workers support hierarchical environment variable configuration — global settings that can be overridden per worker: -```python -resume_workflow(self, workflow_id: str) -``` - -### Searching for Workflows - -Workflow executions are retained until removed from the Conductor. This gives complete visibility into all the executions an application has - regardless of the number of executions. Conductor has a powerful search API that allows you to search for workflow executions. +```shell +# Global (all workers) +export CONDUCTOR_WORKER_ALL_POLL_INTERVAL_MILLIS=250 +export CONDUCTOR_WORKER_ALL_THREAD_COUNT=20 +export CONDUCTOR_WORKER_ALL_DOMAIN=production -```python -search(self, start, size, free_text: str = '*', query: str = None) -> ScrollableSearchResultWorkflowSummary +# Per-worker override +export CONDUCTOR_WORKER_GREETINGS_THREAD_COUNT=50 ``` -* **free_text**: Free text search to look for specific words in the workflow and task input/output. -* **query** SQL-like query to search against specific fields in the workflow. - -Here are the supported fields for **query**: - -| Field | Description | -|-------------|-----------------| -| status |The status of the workflow. | -| correlationId |The ID to correlate the workflow execution to other executions. | -| workflowType |The name of the workflow. | - | version |The version of the workflow. | -|startTime|The start time of the workflow is in milliseconds.| - - -### Handling Failures, Retries and Rate Limits - -Conductor lets you embrace failures rather than worry about the complexities introduced in the system to handle failures. - -All the aspects of handling failures, retries, rate limits, etc., are driven by the configuration that can be updated in real time without re-deploying your application. - -#### Retries - -Each task in the Conductor workflow can be configured to handle failures with retries, along with the retry policy (linear, fixed, exponential backoff) and maximum number of retry attempts allowed. - -See [Error Handling](https://orkes.io/content/error-handling) for more details. +See [WORKER_CONFIGURATION.md](WORKER_CONFIGURATION.md) for all options. -#### Rate Limits +### Monitoring -What happens when a task is operating on a critical resource that can only handle a few requests at a time? Tasks can be configured to have a fixed concurrency (X request at a time) or a rate (Y tasks/time window). - - -#### Task Registration +Enable Prometheus metrics: ```python -from conductor.client.configuration.configuration import Configuration -from conductor.client.http.models import TaskDef -from conductor.client.orkes_clients import OrkesClients - - -def main(): - api_config = Configuration() - clients = OrkesClients(configuration=api_config) - metadata_client = clients.get_metadata_client() - - task_def = TaskDef() - task_def.name = 'task_with_retries' - task_def.retry_count = 3 - task_def.retry_logic = 'LINEAR_BACKOFF' - task_def.retry_delay_seconds = 1 - - # only allow 3 tasks at a time to be in the IN_PROGRESS status - task_def.concurrent_exec_limit = 3 +from conductor.client.configuration.settings.metrics_settings import MetricsSettings - # timeout the task if not polled within 60 seconds of scheduling - task_def.poll_timeout_seconds = 60 +metrics_settings = MetricsSettings(directory='/tmp/conductor-metrics', http_port=8000) +task_handler = TaskHandler(configuration=api_config, metrics_settings=metrics_settings, scan_for_annotated_workers=True) +# Metrics at http://localhost:8000/metrics +``` - # timeout the task if the task does not COMPLETE in 2 minutes - task_def.timeout_seconds = 120 +See [METRICS.md](METRICS.md) for details. - # for the long running tasks, timeout if the task does not get updated in COMPLETED or IN_PROGRESS status in - # 60 seconds after the last update - task_def.response_timeout_seconds = 60 +## Examples - # only allow 100 executions in a 10-second window! -- Note, this is complementary to concurrent_exec_limit - task_def.rate_limit_per_frequency = 100 - task_def.rate_limit_frequency_in_seconds = 10 +See the [Examples Guide](examples/README.md) for the full catalog. Key examples: - metadata_client.register_task_def(task_def=task_def) -``` +| Example | Description | Run | +|---------|-------------|-----| +| [workers_e2e.py](examples/workers_e2e.py) | End-to-end: sync + async workers, metrics | `python examples/workers_e2e.py` | +| [helloworld.py](examples/helloworld/helloworld.py) | Minimal hello world | `python examples/helloworld/helloworld.py` | +| [dynamic_workflow.py](examples/dynamic_workflow.py) | Build workflows programmatically | `python examples/dynamic_workflow.py` | +| [agentic_workflow.py](examples/agentic_workflow.py) | AI agent with tool calling | `python examples/agentic_workflow.py` | +| [rag_workflow.py](examples/rag_workflow.py) | RAG pipeline (PDF → pgvector → answer) | `python examples/rag_workflow.py file.pdf "question"` | +| [task_context_example.py](examples/task_context_example.py) | Long-running tasks with TaskInProgress | `python examples/task_context_example.py` | +| [workflow_ops.py](examples/workflow_ops.py) | Pause, resume, terminate workflows | `python examples/workflow_ops.py` | +| [test_workflows.py](examples/test_workflows.py) | Unit testing workflows | `python -m unittest examples.test_workflows` | +| [kitchensink.py](examples/kitchensink.py) | All task types (HTTP, JS, JQ, Switch) | `python examples/kitchensink.py` | +### API Journey Examples -```json -{ - "name": "task_with_retries", - - "retryCount": 3, - "retryLogic": "LINEAR_BACKOFF", - "retryDelaySeconds": 1, - "backoffScaleFactor": 1, - - "timeoutSeconds": 120, - "responseTimeoutSeconds": 60, - "pollTimeoutSeconds": 60, - "timeoutPolicy": "TIME_OUT_WF", - - "concurrentExecLimit": 3, - - "rateLimitPerFrequency": 0, - "rateLimitFrequencyInSeconds": 1 -} -``` +End-to-end examples covering all APIs for each domain: -#### Update Task Definition: +| Example | APIs | Run | +|---------|------|-----| +| [authorization_journey.py](examples/authorization_journey.py) | Authorization APIs | `python examples/authorization_journey.py` | +| [metadata_journey.py](examples/metadata_journey.py) | Metadata APIs | `python examples/metadata_journey.py` | +| [schedule_journey.py](examples/schedule_journey.py) | Schedule APIs | `python examples/schedule_journey.py` | +| [prompt_journey.py](examples/prompt_journey.py) | Prompt APIs | `python examples/prompt_journey.py` | -```shell -POST /api/metadata/taskdef -d @task_def.json -``` +## Documentation -See [task_configure.py](examples/task_configure.py) for a detailed working app. +| Document | Description | +|----------|-------------| +| [Worker Design](docs/design/WORKER_DESIGN.md) | Architecture: AsyncTaskRunner vs TaskRunner, discovery, lifecycle | +| [Worker Guide](docs/WORKER.md) | All worker patterns (function, class, annotation, async) | +| [Worker Configuration](WORKER_CONFIGURATION.md) | Hierarchical environment variable configuration | +| [Workflow Management](docs/WORKFLOW.md) | Start, pause, resume, terminate, retry, search | +| [Workflow Testing](docs/WORKFLOW_TESTING.md) | Unit testing with mock outputs | +| [Task Management](docs/TASK_MANAGEMENT.md) | Task operations | +| [Metadata](docs/METADATA.md) | Task & workflow definitions | +| [Authorization](docs/AUTHORIZATION.md) | Users, groups, applications, permissions | +| [Schedules](docs/SCHEDULE.md) | Workflow scheduling | +| [Secrets](docs/SECRET_MANAGEMENT.md) | Secret storage | +| [Prompts](docs/PROMPT.md) | AI/LLM prompt templates | +| [Integrations](docs/INTEGRATION.md) | AI/LLM provider integrations | +| [Metrics](METRICS.md) | Prometheus metrics collection | +| [Examples](examples/README.md) | Complete examples catalog | -## Using Conductor in Your Application +## Support -Conductor SDKs are lightweight and can easily be added to your existing or new Python app. This section will dive deeper into integrating Conductor in your application. +- [Open an issue](https://github.com/conductor-oss/conductor/issues) for bugs, questions, and feature requests +- [Join the Conductor Slack](https://join.slack.com/t/orkes-conductor/shared_invite/zt-2vdbx239s-Eacdyqya9giNLHfrCavfaA) for community discussion and help +- [Orkes Community Forum](https://community.orkes.io/) for Q&A -### Adding Conductor SDK to Your Application +## Frequently Asked Questions -Conductor Python SDKs are published on PyPi @ https://pypi.org/project/conductor-python/: +**Is this the same as Netflix Conductor?** -```shell -pip3 install conductor-python -``` +Yes. Conductor OSS is the continuation of the original [Netflix Conductor](https://github.com/Netflix/conductor) repository after Netflix contributed the project to the open-source foundation. -### Testing Workflows +**Is this project actively maintained?** -Conductor SDK for Python provides a complete feature testing framework for your workflow-based applications. The framework works well with any testing framework you prefer without imposing any specific framework. +Yes. [Orkes](https://orkes.io) is the primary maintainer and offers an enterprise SaaS platform for Conductor across all major cloud providers. -The Conductor server provides a test endpoint `POST /api/workflow/test` that allows you to post a workflow along with the test execution data to evaluate the workflow. +**Can Conductor scale to handle my workload?** -The goal of the test framework is as follows: +Conductor was built at Netflix to handle massive scale and has been battle-tested in production environments processing millions of workflows. It scales horizontally to meet virtually any demand. -1. Ability to test the various branches of the workflow. -2. Confirm the workflow execution and tasks given a fixed set of inputs and outputs. -3. Validate that the workflow completes or fails given specific inputs. +**Does Conductor support durable code execution?** -Here are example assertions from the test: +Yes. Conductor ensures workflows complete reliably even in the face of infrastructure failures, process crashes, or network issues. -```python +**Are workflows always asynchronous?** -... -test_request = WorkflowTestRequest(name=wf.name, version=wf.version, - task_ref_to_mock_output=task_ref_to_mock_output, - workflow_def=wf.to_workflow_def()) -run = workflow_client.test_workflow(test_request=test_request) +No. While Conductor excels at asynchronous orchestration, it also supports synchronous workflow execution when immediate results are required. -print(f'completed the test run') -print(f'status: {run.status}') -self.assertEqual(run.status, 'COMPLETED') +**Do I need to use a Conductor-specific framework?** -... +No. Conductor is language and framework agnostic. Use your preferred language and framework -- the [SDKs](https://github.com/conductor-oss/conductor#conductor-sdks) provide native integration for Python, Java, JavaScript, Go, C#, and more. -``` +**Can I mix workers written in different languages?** -> [!note] -> Workflow workers are your regular Python functions and can be tested with any available testing framework. +Yes. A single workflow can have workers written in Python, Java, Go, or any other supported language. Workers communicate through the Conductor server, not directly with each other. -#### Example Unit Testing Application +**What Python versions are supported?** -See [test_workflows.py](examples/test_workflows.py) for a fully functional example of how to test a moderately complex workflow with branches. +Python 3.9 and above. -### Workflow Deployments Using CI/CD +**Should I use `def` or `async def` for my workers?** -> [!tip] -> Treat your workflow definitions just like your code. Suppose you are defining the workflows using UI. In that case, we recommend checking the JSON configuration into the version control and using your development workflow for CI/CD to promote the workflow definitions across various environments such as Dev, Test, and Prod. +Use `async def` for I/O-bound tasks (API calls, database queries) -- the SDK uses `AsyncTaskRunner` with a single event loop for high concurrency with low overhead. Use regular `def` for CPU-bound or blocking work -- the SDK uses `TaskRunner` with a thread pool. The SDK selects the right runner automatically based on your function signature. -Here is a recommended approach when defining workflows using JSON: +**How do I run workers in production?** -* Treat your workflow metadata as code. -* Check in the workflow and task definitions along with the application code. -* Use `POST /api/metadata/*` endpoints or MetadataClient (`from conductor.client.metadata_client import MetadataClient`) to register/update workflows as part of the deployment process. -* Version your workflows. If there is a significant change, change the version field of the workflow. See versioning workflows below for more details. +Workers are standard Python processes. Deploy them as you would any Python application -- in containers, VMs, or bare metal. Workers poll the Conductor server for tasks, so no inbound ports need to be opened. See [Worker Design](docs/design/WORKER_DESIGN.md) for architecture details. +**How do I test workflows without running a full Conductor server?** -### Versioning Workflows +The SDK provides a test framework that uses Conductor's `POST /api/workflow/test` endpoint to evaluate workflows with mock task outputs. See [Workflow Testing](docs/WORKFLOW_TESTING.md) for details. -A powerful feature of Conductor is the ability to version workflows. You should increment the version of the workflow when there is a significant change to the definition. You can run multiple versions of the workflow at the same time. When starting a new workflow execution, use the `version` field to specify which version to use. When omitted, the latest (highest-numbered) version is used. +## License -* Versioning allows safely testing changes by doing canary testing in production or A/B testing across multiple versions before rolling out. -* A version can also be deleted, effectively allowing for "rollback" if required. +Apache 2.0 diff --git a/examples/README.md b/examples/README.md index 0b7366f7d..da80d9b8b 100644 --- a/examples/README.md +++ b/examples/README.md @@ -60,6 +60,7 @@ See: `task_context_example.py`, `worker_example.py` | File | Description | Run | |------|-------------|-----| +| **agentic_workflow.py** | 🤖 AI agent with Python workers as tools | `python examples/agentic_workflow.py` | | **dynamic_workflow.py** | Create workflows programmatically | `python examples/dynamic_workflow.py` | | **workflow_ops.py** | Start, pause, resume, terminate workflows | `python examples/workflow_ops.py` | | **workflow_status_listner.py** | Workflow event listeners | `python examples/workflow_status_listner.py` | @@ -67,6 +68,15 @@ See: `task_context_example.py`, `worker_example.py` --- +### AI/LLM Workflows + +| File | Description | Run | +|------|-------------|-----| +| **rag_workflow.py** | 📚 RAG pipeline: markitdown → pgvector → search → answer | `python examples/rag_workflow.py file.pdf "question"` | +| **mcp_weather_agent.py** | 🌤️ AI agent with MCP tool calling | `python examples/mcp_weather_agent.py "What's the weather?"` | + +--- + ### Monitoring | File | Description | Run | @@ -174,6 +184,65 @@ python examples/prompt_journey.py --- +### RAG Pipeline Setup + +Complete RAG (Retrieval Augmented Generation) pipeline example: + +```bash +# 1. Install dependencies +pip install conductor-python "markitdown[pdf]" + +# 2. Configure (requires Orkes Conductor with AI/LLM support) +# - Vector DB integration named "postgres-prod" (pgvector) +# - LLM provider named "openai" with a valid API key +export CONDUCTOR_SERVER_URL="http://localhost:7001/api" + +# 3. Run RAG workflow +python examples/rag_workflow.py examples/goog-20251231.pdf "What were Google's total revenues?" +``` + +**Pipeline:** `convert_to_markdown` → `LLM_INDEX_TEXT` → `WAIT` → `LLM_SEARCH_INDEX` → `LLM_CHAT_COMPLETE` + +**Features:** +- Document conversion (PDF, Word, Excel → Markdown via [markitdown](https://github.com/microsoft/markitdown)) +- Vector database ingestion into pgvector with OpenAI `text-embedding-3-small` embeddings +- Semantic search with configurable result count +- Context-aware answer generation with `gpt-4o-mini` + +--- + +### MCP Tool Integration Setup + +MCP (Model Context Protocol) agent example: + +```bash +# 1. Install MCP weather server +pip install mcp-weather-server + +# 2. Start MCP server +python3 -m mcp_weather_server \ + --mode streamable-http \ + --host localhost \ + --port 3001 \ + --stateless + +# 3. Run AI agent +export OPENAI_API_KEY="your-key" +export ANTHROPIC_API_KEY="your-key" +python examples/mcp_weather_agent.py "What's the weather in Tokyo?" + +# Or simple mode (direct tool call): +python examples/mcp_weather_agent.py "Temperature in New York" --simple +``` + +**Features:** +- MCP tool discovery +- LLM-based planning (agent decides which tool to use) +- Tool execution via HTTP/Streamable transport +- Natural language response generation + +--- + ## 🎓 Learning Path (60-Second Guide) ```bash @@ -189,7 +258,10 @@ python examples/worker_configuration_example.py # 4. Workflows (10 min) python examples/dynamic_workflow.py -# 5. Monitoring (5 min) +# 5. AI/RAG (15 min) +python examples/rag_workflow.py examples/goog-20251231.pdf "What were Google's total revenues?" + +# 6. Monitoring (5 min) python examples/metrics_example.py curl http://localhost:8000/metrics ``` @@ -209,11 +281,16 @@ examples/ │ └── pythonic_usage.py # Pythonic decorators │ ├── Workflows +│ ├── agentic_workflow.py # 🤖 AI agent with tools │ ├── dynamic_workflow.py # Workflow creation │ ├── workflow_ops.py # Workflow management │ ├── workflow_status_listner.py # Workflow events │ └── test_workflows.py # Unit tests │ +├── AI/LLM Workflows +│ ├── rag_workflow.py # 📚 RAG pipeline (markitdown + pgvector) +│ └── mcp_weather_agent.py # 🌤️ MCP tool calling agent +│ ├── Monitoring │ ├── metrics_example.py # Prometheus metrics │ ├── event_listener_examples.py # Custom listeners diff --git a/examples/agentic_workflow.py b/examples/agentic_workflow.py new file mode 100644 index 000000000..ec4a96b47 --- /dev/null +++ b/examples/agentic_workflow.py @@ -0,0 +1,407 @@ +""" +Agentic Workflow Example - Using Python Workers as Agent Tools + +This example demonstrates how to create an agentic workflow where an LLM can +dynamically call Python worker tasks as tools to accomplish goals. + +The workflow: +1. Takes a user query +2. LLM analyzes the query and decides which tool(s) to call +3. Python workers execute as tools +4. LLM summarizes the results + +Requirements: +- Conductor server running (see README.md for startup instructions) +- OpenAI API key configured in Conductor integrations +- Set environment variables: + export CONDUCTOR_SERVER_URL=http://localhost:8080/api + export CONDUCTOR_AUTH_KEY=your_key # if using Orkes Conductor + export CONDUCTOR_AUTH_SECRET=your_secret # if using Orkes Conductor + +Usage: + python examples/agentic_workflow.py +""" + +import os +import time +from typing import Optional + +from conductor.client.ai.orchestrator import AIOrchestrator +from conductor.client.automator.task_handler import TaskHandler +from conductor.client.configuration.configuration import Configuration +from conductor.client.http.models import TaskDef +from conductor.client.http.models.task_result_status import TaskResultStatus +from conductor.client.orkes_clients import OrkesClients +from conductor.client.worker.worker_task import worker_task +from conductor.client.workflow.conductor_workflow import ConductorWorkflow +from conductor.client.workflow.task.do_while_task import LoopTask +from conductor.client.workflow.task.dynamic_task import DynamicTask +from conductor.client.workflow.task.llm_tasks.llm_chat_complete import LlmChatComplete, ChatMessage +from conductor.client.workflow.task.set_variable_task import SetVariableTask +from conductor.client.workflow.task.switch_task import SwitchTask +from conductor.client.workflow.task.timeout_policy import TimeoutPolicy +from conductor.client.workflow.task.wait_task import WaitTask + + +# ============================================================================= +# DEFINE PYTHON WORKERS AS AGENT TOOLS +# ============================================================================= +# These workers will be available as tools for the LLM agent to call. +# Each worker is a self-contained function that performs a specific task. + +@worker_task(task_definition_name='get_weather') +def get_weather(city: str, units: str = 'fahrenheit') -> dict: + """ + Get current weather for a city. + + Args: + city: City name or zip code + units: Temperature units ('fahrenheit' or 'celsius') + + Returns: + Weather information including temperature and conditions + """ + # In a real application, this would call a weather API + weather_data = { + 'new york': {'temp': 72, 'condition': 'Partly Cloudy', 'humidity': 65}, + 'san francisco': {'temp': 58, 'condition': 'Foggy', 'humidity': 80}, + 'miami': {'temp': 85, 'condition': 'Sunny', 'humidity': 75}, + 'chicago': {'temp': 45, 'condition': 'Windy', 'humidity': 55}, + } + + city_lower = city.lower() + data = weather_data.get(city_lower, {'temp': 70, 'condition': 'Clear', 'humidity': 50}) + + if units == 'celsius': + data['temp'] = round((data['temp'] - 32) * 5/9, 1) + + return { + 'city': city, + 'temperature': data['temp'], + 'units': units, + 'condition': data['condition'], + 'humidity': data['humidity'] + } + + +@worker_task(task_definition_name='search_products') +def search_products(query: str, max_results: int = 5) -> dict: + """ + Search for products in a catalog. + + Args: + query: Search query string + max_results: Maximum number of results to return + + Returns: + List of matching products with prices + """ + # Simulated product database + products = [ + {'name': 'Wireless Headphones', 'price': 79.99, 'category': 'Electronics'}, + {'name': 'Running Shoes', 'price': 129.99, 'category': 'Sports'}, + {'name': 'Coffee Maker', 'price': 49.99, 'category': 'Kitchen'}, + {'name': 'Laptop Stand', 'price': 39.99, 'category': 'Electronics'}, + {'name': 'Yoga Mat', 'price': 24.99, 'category': 'Sports'}, + {'name': 'Bluetooth Speaker', 'price': 59.99, 'category': 'Electronics'}, + {'name': 'Water Bottle', 'price': 19.99, 'category': 'Sports'}, + ] + + query_lower = query.lower() + matches = [p for p in products if query_lower in p['name'].lower() or query_lower in p['category'].lower()] + + return { + 'query': query, + 'total_found': len(matches), + 'products': matches[:max_results] + } + + +@worker_task(task_definition_name='calculate') +def calculate(expression: str) -> dict: + """ + Perform a mathematical calculation. + + Args: + expression: Mathematical expression to evaluate (e.g., "2 + 2", "sqrt(16)") + + Returns: + Calculation result + """ + import math + + # Safe evaluation with limited functions + safe_dict = { + 'abs': abs, 'round': round, 'min': min, 'max': max, + 'sqrt': math.sqrt, 'pow': pow, 'log': math.log, + 'sin': math.sin, 'cos': math.cos, 'tan': math.tan, + 'pi': math.pi, 'e': math.e + } + + try: + result = eval(expression, {"__builtins__": {}}, safe_dict) + return {'expression': expression, 'result': result, 'success': True} + except Exception as e: + return {'expression': expression, 'error': str(e), 'success': False} + + +@worker_task(task_definition_name='send_notification') +def send_notification(recipient: str, message: str, channel: str = 'email') -> dict: + """ + Send a notification to a user. + + Args: + recipient: Email address or phone number + message: Notification message content + channel: Notification channel ('email', 'sms', 'push') + + Returns: + Confirmation of notification sent + """ + # In a real application, this would integrate with notification services + return { + 'status': 'sent', + 'recipient': recipient, + 'channel': channel, + 'message_preview': message[:50] + '...' if len(message) > 50 else message, + 'timestamp': time.strftime('%Y-%m-%d %H:%M:%S') + } + + +# ============================================================================= +# AGENT WORKFLOW SETUP +# ============================================================================= + +def start_workers(api_config: Configuration) -> TaskHandler: + """Start the task handler with worker discovery.""" + task_handler = TaskHandler( + workers=[], + configuration=api_config, + scan_for_annotated_workers=True, + ) + task_handler.start_processes() + return task_handler + + +def register_tool_tasks(metadata_client) -> None: + """Register task definitions for our worker tools.""" + tools = ['get_weather', 'search_products', 'calculate', 'send_notification'] + for tool in tools: + metadata_client.register_task_def(task_def=TaskDef(name=tool)) + + +def create_agent_prompt() -> str: + """Create the system prompt that defines available tools for the agent.""" + return """ +You are a helpful AI assistant with access to the following tools: + +1. get_weather(city: str, units: str = 'fahrenheit') -> dict + - Get current weather for a city + - units can be 'fahrenheit' or 'celsius' + +2. search_products(query: str, max_results: int = 5) -> dict + - Search for products in our catalog + - Returns product names and prices + +3. calculate(expression: str) -> dict + - Perform mathematical calculations + - Supports basic math, sqrt, pow, log, trig functions + +4. send_notification(recipient: str, message: str, channel: str = 'email') -> dict + - Send notifications via email, sms, or push + +When you need to use a tool, respond with a JSON object in this exact format: +{ + "type": "function", + "function": "FUNCTION_NAME", + "function_parameters": {"param1": "value1", "param2": "value2"} +} + +If you don't need to use a tool, just respond normally with text. +Always be helpful and explain your actions to the user. +""" + + +def create_agentic_workflow( + workflow_executor, + llm_provider: str, + model: str, + prompt_name: str +) -> ConductorWorkflow: + """ + Create an agentic workflow that uses Python workers as tools. + + The workflow: + 1. Waits for user input + 2. Sends to LLM with tool definitions + 3. If LLM wants to call a tool, dynamically execute the worker + 4. Loop back for more interactions + """ + wf = ConductorWorkflow(name='python_agent_workflow', version=1, executor=workflow_executor) + + # Wait for user input + user_input = WaitTask(task_ref_name='get_user_input') + + # Collect conversation history + collect_history = SetVariableTask(task_ref_name='collect_history_ref') + collect_history.input_parameter('messages', [ + ChatMessage(role='user', message='${get_user_input.output.question}') + ]) + collect_history.input_parameter('_merge', True) + + # LLM chat completion with tool awareness + chat_complete = LlmChatComplete( + task_ref_name='chat_complete_ref', + llm_provider=llm_provider, + model=model, + instructions_template=prompt_name, + messages='${workflow.variables.messages}', + max_tokens=1000, + temperature=0 + ) + + # Dynamic task to call the function returned by LLM + function_call = DynamicTask( + task_reference_name='fn_call_ref', + dynamic_task=chat_complete.output('function') + ) + function_call.input_parameters['inputs'] = chat_complete.output('function_parameters') + function_call.input_parameters['dynamicTaskInputParam'] = 'inputs' + + # Switch to check if LLM wants to call a function + should_call_fn = SwitchTask( + task_ref_name='check_function_call', + case_expression="$.type == 'function' ? 'call_function' : 'direct_response'", + use_javascript=True + ) + should_call_fn.input_parameter('type', chat_complete.output('type')) + should_call_fn.switch_case('call_function', [function_call]) + should_call_fn.default_case([]) # No function call needed + + # Update history with assistant response + update_history = SetVariableTask(task_ref_name='update_history_ref') + update_history.input_parameter('messages', [ + ChatMessage(role='assistant', message='${chat_complete_ref.output.result}') + ]) + update_history.input_parameter('_merge', True) + + # Create the conversation loop + loop_tasks = [user_input, collect_history, chat_complete, should_call_fn, update_history] + chat_loop = LoopTask(task_ref_name='agent_loop', iterations=10, tasks=loop_tasks) + + wf >> chat_loop + + # Set workflow timeout (5 minutes) + wf.timeout_seconds(300).timeout_policy(timeout_policy=TimeoutPolicy.TIME_OUT_WORKFLOW) + + return wf + + +def main(): + """Main entry point for the agentic workflow example.""" + + # Configuration + llm_provider = 'openai' # Change to your configured provider + model = 'gpt-4' # Or 'gpt-3.5-turbo' for faster/cheaper responses + + print(""" +╔══════════════════════════════════════════════════════════════════╗ +║ 🤖 Conductor Agentic Workflow Example ║ +╠══════════════════════════════════════════════════════════════════╣ +║ This agent can: ║ +║ • Get weather for any city ║ +║ • Search products in a catalog ║ +║ • Perform calculations ║ +║ • Send notifications ║ +║ ║ +║ Try asking: ║ +║ - "What's the weather in San Francisco?" ║ +║ - "Search for electronics under $100" ║ +║ - "Calculate the square root of 144" ║ +║ - "Send an email to user@example.com saying hello" ║ +╚══════════════════════════════════════════════════════════════════╝ +""") + + # Initialize configuration and clients + api_config = Configuration() + clients = OrkesClients(configuration=api_config) + workflow_executor = clients.get_workflow_executor() + workflow_client = clients.get_workflow_client() + task_client = clients.get_task_client() + metadata_client = clients.get_metadata_client() + + # Start workers + task_handler = start_workers(api_config) + + # Register tool tasks + register_tool_tasks(metadata_client) + + # Set up AI orchestrator and prompt + orchestrator = AIOrchestrator(api_configuration=api_config) + prompt_name = 'python_agent_instructions' + prompt_text = create_agent_prompt() + + orchestrator.add_prompt_template(prompt_name, prompt_text, 'Agent with Python tool access') + orchestrator.associate_prompt_template(prompt_name, llm_provider, [model]) + + # Create and register workflow + wf = create_agentic_workflow(workflow_executor, llm_provider, model, prompt_name) + wf.register(overwrite=True) + + print(f"✅ Workflow registered: {wf.name}") + print(f"🌐 Conductor UI: {api_config.ui_host}\n") + + # Start workflow execution + workflow_run = wf.execute( + wait_until_task_ref='get_user_input', + wait_for_seconds=1, + workflow_input={} + ) + workflow_id = workflow_run.workflow_id + + print(f"🚀 Workflow started: {api_config.ui_host}/execution/{workflow_id}\n") + + # Interactive conversation loop + try: + while workflow_run.is_running(): + current_task = workflow_run.current_task + if current_task and current_task.workflow_task.task_reference_name == 'get_user_input': + + # Check for previous function call results + fn_call_task = workflow_run.get_task(task_reference_name='fn_call_ref') + if fn_call_task and fn_call_task.output_data: + print(f"\n🔧 Tool Result: {fn_call_task.output_data.get('result', fn_call_task.output_data)}") + + # Check for LLM response + chat_task = workflow_run.get_task(task_reference_name='chat_complete_ref') + if chat_task and chat_task.output_data.get('result'): + print(f"\n🤖 Assistant: {chat_task.output_data['result']}") + + # Get user input + question = input('\n👤 You: ') + if question.lower() in ['quit', 'exit', 'q']: + print("\n👋 Goodbye!") + break + + # Submit user input to workflow + task_client.update_task_sync( + workflow_id=workflow_id, + task_ref_name='get_user_input', + status=TaskResultStatus.COMPLETED, + output={'question': question} + ) + + time.sleep(0.5) + workflow_run = workflow_client.get_workflow(workflow_id=workflow_id, include_tasks=True) + + except KeyboardInterrupt: + print("\n\n⚠️ Interrupted by user") + finally: + # Cleanup + print("\n🛑 Stopping workers...") + task_handler.stop_processes() + print("✅ Done!") + + +if __name__ == '__main__': + main() diff --git a/examples/goog-20251231.pdf b/examples/goog-20251231.pdf new file mode 100644 index 000000000..e6f1d6f2e Binary files /dev/null and b/examples/goog-20251231.pdf differ diff --git a/examples/mcp_weather_agent.py b/examples/mcp_weather_agent.py new file mode 100644 index 000000000..dcd363fd5 --- /dev/null +++ b/examples/mcp_weather_agent.py @@ -0,0 +1,370 @@ +""" +MCP (Model Context Protocol) + AI Agent Example + +This example demonstrates an autonomous AI agent that: +1. Discovers available tools from an MCP server +2. Uses an LLM to decide which tools to use +3. Executes tool calls via MCP +4. Summarizes results for the user + +Prerequisites: +1. Install MCP weather server: + pip install mcp-weather-server + +2. Start MCP weather server: + python3 -m mcp_weather_server \\ + --mode streamable-http \\ + --host localhost \\ + --port 3001 \\ + --stateless + +3. Configure Conductor server: + export OPENAI_API_KEY="your-key" + export ANTHROPIC_API_KEY="your-key" + +4. Run the example: + export CONDUCTOR_SERVER_URL="http://localhost:7001/api" + python examples/mcp_weather_agent.py "What's the weather in Tokyo?" + +Reference: +https://github.com/conductor-oss/conductor/tree/main/ai#mcp--ai-agent-workflow + +MCP Server Installation & Setup: +$ pip install mcp-weather-server +$ python3 -m mcp_weather_server --mode streamable-http --host localhost --port 3001 --stateless + +The weather server will be available at: http://localhost:3001/mcp +""" + +import os +import sys +from typing import Dict, Any + +from conductor.client.configuration.configuration import Configuration +from conductor.client.workflow.conductor_workflow import ConductorWorkflow +from conductor.client.workflow.executor.workflow_executor import WorkflowExecutor +from conductor.client.orkes_clients import OrkesClients +from conductor.client.workflow.task.llm_tasks import ( + ListMcpTools, + CallMcpTool, + LlmChatComplete, + ChatMessage +) + + +# ══════════════════════════════════════════════════════════════════════════════ +# Workflow: MCP AI Agent +# ══════════════════════════════════════════════════════════════════════════════ + +def create_mcp_agent_workflow(executor: WorkflowExecutor, mcp_server: str) -> ConductorWorkflow: + """ + Creates an AI agent workflow that uses MCP tools. + + Workflow Steps: + 1. List available tools from MCP server + 2. Ask LLM to plan which tool to use based on user request + 3. Execute the tool via MCP + 4. Summarize the result for the user + + Args: + executor: Workflow executor + mcp_server: MCP server URL (e.g., "http://localhost:3001/mcp") + + Returns: + ConductorWorkflow: Configured MCP agent workflow + """ + wf = ConductorWorkflow( + executor=executor, + name="mcp_ai_agent", + version=1, + description="AI agent with MCP tool integration" + ) + + # Step 1: Discover available MCP tools + list_tools = ListMcpTools( + task_ref_name="discover_tools", + mcp_server=mcp_server + ) + + # Step 2: Ask LLM to plan which tool to use + plan_task = LlmChatComplete( + task_ref_name="plan_action", + llm_provider="anthropic", + model="claude-sonnet-4-20250514", + messages=[ + ChatMessage( + role="system", + message="""You are an AI agent that can use tools to help users. + +Available tools: +${discover_tools.output.tools} + +User's request: +${workflow.input.request} + +Decide which tool to use and what parameters to pass. Respond with a JSON object: +{ + "method": "tool_name", + "arguments": { + "param1": "value1", + "param2": "value2" + }, + "reasoning": "why you chose this tool and parameters" +} + +If no tool is suitable, respond with {"method": "none", "reasoning": "explanation"}.""" + ), + ChatMessage( + role="user", + message="What tool should I use and with what parameters?" + ) + ], + temperature=0.1, + max_tokens=500, + json_output=True + ) + + # Step 3: Execute the selected tool via MCP + # Note: In a real workflow, you'd use a SWITCH task to handle the "none" case + execute_tool = CallMcpTool( + task_ref_name="execute_tool", + mcp_server=mcp_server, + method="${plan_action.output.result.method}", + arguments="${plan_action.output.result.arguments}" # Arguments dict from LLM planning + ) + + # Step 4: Summarize the result + summarize_task = LlmChatComplete( + task_ref_name="summarize_result", + llm_provider="openai", + model="gpt-4o-mini", + messages=[ + ChatMessage( + role="system", + message="""You are a helpful assistant. Summarize the tool execution result for the user. + +Original request: ${workflow.input.request} + +Tool used: ${plan_action.output.result.method} +Tool reasoning: ${plan_action.output.result.reasoning} + +Tool result: ${execute_tool.output.content} + +Provide a natural, conversational response to the user.""" + ), + ChatMessage( + role="user", + message="Please summarize the result" + ) + ], + temperature=0.3, + max_tokens=300 + ) + + # Build workflow + wf >> list_tools >> plan_task >> execute_tool >> summarize_task + + return wf + + +def create_simple_weather_workflow(executor: WorkflowExecutor, mcp_server: str) -> ConductorWorkflow: + """ + Creates a simple weather query workflow (no planning, direct tool call). + + Args: + executor: Workflow executor + mcp_server: MCP server URL + + Returns: + ConductorWorkflow: Simple weather workflow + """ + wf = ConductorWorkflow( + executor=executor, + name="simple_weather_query", + version=1, + description="Simple weather query via MCP" + ) + + # Direct weather query + get_weather = CallMcpTool( + task_ref_name="get_weather", + mcp_server=mcp_server, + method="get_current_weather", + arguments={ + "city": "${workflow.input.city}" + } + ) + + wf >> get_weather + + return wf + + +# ══════════════════════════════════════════════════════════════════════════════ +# Main: Run MCP Agent +# ══════════════════════════════════════════════════════════════════════════════ + +def main(): + # Parse command line arguments + if len(sys.argv) < 2: + print("Usage: python mcp_weather_agent.py [--simple]") + print("\nExamples:") + print(' python mcp_weather_agent.py "What\'s the weather in Tokyo?"') + print(' python mcp_weather_agent.py "Temperature in New York" --simple') + print("\nPrerequisites:") + print("1. Install: pip install mcp-weather-server") + print("2. Start server:") + print(" python3 -m mcp_weather_server --mode streamable-http --host localhost --port 3001 --stateless") + sys.exit(1) + + request = sys.argv[1] + simple_mode = "--simple" in sys.argv + + # Configuration + server_url = os.getenv('CONDUCTOR_SERVER_URL', 'http://localhost:7001/api') + mcp_server = os.getenv('MCP_SERVER_URL', 'http://localhost:3001/mcp') + + configuration = Configuration( + server_api_url=server_url, + debug=False + ) + + clients = OrkesClients(configuration=configuration) + executor = clients.get_workflow_executor() + + print("=" * 80) + print("MCP AI AGENT - Tool Integration Example") + print("=" * 80) + print(f"\n🤖 Mode: {'Simple Weather Query' if simple_mode else 'AI Agent with Planning'}") + print(f"📡 MCP Server: {mcp_server}") + print(f"💬 Request: {request}\n") + + try: + # Create and register workflow + if simple_mode: + # Parse city from request + # Look for city name after common prepositions + import re + match = re.search(r'\b(?:in|at|for|of)\s+([A-Z][a-z]+(?:\s+[A-Z][a-z]+)?)', request) + if match: + city = match.group(1) + else: + # Fallback: look for capitalized words + words = [w for w in request.split() if w and w[0].isupper()] + city = words[-1] if words else "San Francisco" + + city = city.strip('?".,') + + print("📋 Creating simple weather workflow...") + wf = create_simple_weather_workflow(executor, mcp_server) + wf.register(overwrite=True) + print(f"✅ Workflow registered: {wf.name}") + print(f"🌍 Extracted city: {city}") + + workflow_input = { + "city": city + } + else: + print("📋 Creating MCP AI agent workflow...") + wf = create_mcp_agent_workflow(executor, mcp_server) + wf.register(overwrite=True) + print(f"✅ Workflow registered: {wf.name}") + + workflow_input = { + "request": request + } + + # Execute workflow + print(f"\n🚀 Starting workflow execution...") + workflow_run = wf.execute( + workflow_input=workflow_input, + wait_for_seconds=30 + ) + + workflow_id = workflow_run.workflow_id + status = workflow_run.status + + print(f"📊 Workflow Status: {status}") + print(f"🔗 Workflow ID: {workflow_id}") + print(f"🌐 View: {server_url.replace('/api', '')}/execution/{workflow_id}") + + if status == "COMPLETED": + # Display results + print("\n" + "=" * 80) + print("RESULTS") + print("=" * 80) + + output = workflow_run.output + + if simple_mode: + # Simple weather output (output is directly the MCP tool result) + if "content" in output: + for item in output["content"]: + if item.get("type") == "text": + print(f"\n🌤️ {item['text']}\n") + else: + # AI agent output + + # Tools discovered + if "discover_tools" in output and "tools" in output["discover_tools"]: + tools = output["discover_tools"]["tools"] + print(f"\n🔧 Tools Available: {len(tools)}") + for tool in tools: + print(f" • {tool.get('name', 'unknown')}: {tool.get('description', 'no description')}") + + # Agent's plan + if "plan_action" in output and "result" in output["plan_action"]: + plan = output["plan_action"]["result"] + print(f"\n🧠 Agent's Plan:") + print(f" Tool: {plan.get('method', 'unknown')}") + print(f" Arguments: {plan.get('arguments', {})}") + print(f" Reasoning: {plan.get('reasoning', 'none provided')}") + + # Tool execution result + if "execute_tool" in output: + tool_result = output["execute_tool"] + print(f"\n⚙️ Tool Execution:") + if "content" in tool_result: + for item in tool_result["content"]: + if item.get("type") == "text": + print(f" {item['text']}") + print(f" Error: {tool_result.get('isError', False)}") + + # Final summary + if "summarize_result" in output: + summary = output["summarize_result"].get("result", "No summary generated") + print(f"\n💬 Agent's Response:") + print(f"\n{summary}\n") + + # Token usage + for task in ["plan_action", "summarize_result"]: + if task in output and "metadata" in output[task]: + metadata = output[task]["metadata"] + if "usage" in metadata: + usage = metadata["usage"] + print(f"📊 {task} tokens: {usage.get('totalTokens', 0)}") + + else: + print(f"\n❌ Workflow failed with status: {status}") + if hasattr(workflow_run, 'reason_for_incompletion'): + print(f"Reason: {workflow_run.reason_for_incompletion}") + + # Show task failures + if hasattr(workflow_run, 'tasks'): + failed_tasks = [t for t in workflow_run.tasks if t.status == "FAILED"] + if failed_tasks: + print("\n❌ Failed Tasks:") + for task in failed_tasks: + ref_name = getattr(task, 'reference_task_name', getattr(task, 'taskReferenceName', 'unknown')) + reason = getattr(task, 'reason_for_incompletion', getattr(task, 'reasonForIncompletion', 'No reason provided')) + print(f" • {ref_name}: {reason}") + + except Exception as e: + print(f"\n❌ Error: {e}") + import traceback + traceback.print_exc() + sys.exit(1) + + +if __name__ == "__main__": + main() diff --git a/examples/rag_workflow.py b/examples/rag_workflow.py new file mode 100644 index 000000000..9576d6c24 --- /dev/null +++ b/examples/rag_workflow.py @@ -0,0 +1,352 @@ +""" +RAG (Retrieval Augmented Generation) Workflow Example + +This example demonstrates a complete RAG pipeline using Conductor: +1. User provides a file path (PDF, Word, Excel, etc.) as workflow input +2. A custom worker converts the file to markdown using markitdown +3. Conductor indexes the markdown into pgvector using OpenAI embeddings +4. A search query retrieves relevant context from the vector store +5. An LLM generates an answer grounded in the retrieved context + +Prerequisites: +1. Install dependencies: + pip install conductor-python "markitdown[pdf]" + +2. Orkes Conductor server with AI/LLM support: + This example uses LLM system tasks (LLM_INDEX_TEXT, LLM_SEARCH_INDEX, + LLM_CHAT_COMPLETE) which require Orkes Conductor (not OSS conductor-rust). + +3. Configure integrations in Conductor: + - Vector DB integration named "postgres-prod" (pgvector) + - LLM provider named "openai" with a valid API key + (See Conductor docs for integration setup) + +4. Set environment variables: + export CONDUCTOR_SERVER_URL="http://localhost:7001/api" + # If using Orkes Cloud: + # export CONDUCTOR_AUTH_KEY="your-key" + # export CONDUCTOR_AUTH_SECRET="your-secret" + +5. Run the example: + python examples/rag_workflow.py examples/goog-20251231.pdf "What were Google's total revenues?" + +Pipeline (5 tasks): + convert_to_markdown (SIMPLE worker - markitdown) + LLM_INDEX_TEXT (index markdown into pgvector with OpenAI embeddings) + WAIT (pause for pgvector to commit - eventual consistency) + LLM_SEARCH_INDEX (semantic search over the vector store) + LLM_CHAT_COMPLETE (generate a grounded answer with gpt-4o-mini) +""" + +import logging +import os +import sys +import time +from pathlib import Path +from typing import Dict, Any + +from markitdown import MarkItDown + +from conductor.client.automator.task_handler import TaskHandler +from conductor.client.configuration.configuration import Configuration +from conductor.client.orkes_clients import OrkesClients +from conductor.client.worker.worker_task import worker_task +from conductor.client.workflow.conductor_workflow import ConductorWorkflow +from conductor.client.workflow.task.llm_tasks.llm_chat_complete import LlmChatComplete, ChatMessage +from conductor.client.workflow.task.llm_tasks.llm_index_text import LlmIndexText +from conductor.client.workflow.task.llm_tasks.llm_search_index import LlmSearchIndex +from conductor.client.workflow.task.llm_tasks.utils.embedding_model import EmbeddingModel +from conductor.client.workflow.task.simple_task import SimpleTask +from conductor.client.workflow.task.wait_task import WaitForDurationTask + + +# ============================================================================= +# Configuration constants +# Matches the reference workflow: postgres-prod, openai, text-embedding-3-small +# ============================================================================= + +VECTOR_DB = "postgres-prod" +VECTOR_INDEX = "demo_index" +EMBEDDING_PROVIDER = "openai" +EMBEDDING_MODEL = "text-embedding-3-small" +EMBEDDING_DIMENSIONS = 1536 +LLM_PROVIDER = "openai" +LLM_MODEL = "gpt-4o-mini" + + +# ============================================================================= +# Workers +# ============================================================================= + +MAX_CHUNK_CHARS = 20000 # ~5000 tokens, well within embedding model limits + + +@worker_task(task_definition_name='convert_to_markdown') +def convert_to_markdown(file_path: str) -> Dict[str, Any]: + """Convert a document to markdown using markitdown. + + Supports: PDF, Word (.docx), Excel (.xlsx), PowerPoint (.pptx), + HTML, images (with EXIF/OCR), and more. + + For large documents the text is truncated to MAX_CHUNK_CHARS so that it + fits within the embedding model's token limit. In a production system + you would split the text into multiple chunks and index each one + separately (e.g. using a dynamic fork). + + Args: + file_path: Absolute path to the document file. + + Returns: + dict with keys: + - markdown: the converted text content (may be truncated) + - title: filename used as document title + - doc_id: identifier derived from the file path + """ + md = MarkItDown() + result = md.convert(file_path) + filename = Path(file_path).stem # e.g. "report" from "report.pdf" + text = result.text_content + + # Truncate to stay within embedding model token limits + if len(text) > MAX_CHUNK_CHARS: + text = text[:MAX_CHUNK_CHARS] + + return { + "markdown": text, + "title": filename, + "doc_id": filename.lower().replace(" ", "_"), + } + + +# ============================================================================= +# Workflow definition +# ============================================================================= + +def create_rag_workflow(executor, namespace: str = "demo_namespace") -> ConductorWorkflow: + """Build the RAG pipeline workflow. + + Pipeline: + convert_to_markdown --> index_document --> wait --> search_index --> generate_answer + + The workflow input must contain: + - file_path (str): path to the document to ingest + - question (str): the user's question to answer + + Args: + executor: WorkflowExecutor from OrkesClients. + namespace: pgvector namespace for isolation. + + Returns: + A ConductorWorkflow ready to register and execute. + """ + workflow = ConductorWorkflow( + executor=executor, + name="rag_document_pipeline", + version=1, + description="RAG pipeline: convert document -> index in pgvector -> search -> answer", + ) + workflow.timeout_seconds(600) # 10 minutes for large documents + + # Step 1: Convert the input file to markdown (custom worker) + convert_task = SimpleTask( + task_def_name="convert_to_markdown", + task_reference_name="convert_doc_ref", + ) + convert_task.input_parameters = { + "file_path": "${workflow.input.file_path}", + } + + # Step 2: Index the markdown text into pgvector + # This mirrors the reference workflow's LLM_INDEX_TEXT configuration + index_task = LlmIndexText( + task_ref_name="index_doc_ref", + vector_db=VECTOR_DB, + index=VECTOR_INDEX, + namespace=namespace, + embedding_model=EmbeddingModel(provider=EMBEDDING_PROVIDER, model=EMBEDDING_MODEL), + text="${convert_doc_ref.output.markdown}", + doc_id="${convert_doc_ref.output.doc_id}", + dimensions=EMBEDDING_DIMENSIONS, + chunk_size=1024, + chunk_overlap=128, + metadata={ + "title": "${convert_doc_ref.output.title}", + "source": "${workflow.input.file_path}", + }, + ) + + # Step 3: Wait for pgvector to commit the new embeddings. + # Without this pause the search may return empty results because the + # index write has not been flushed yet (eventual consistency). + wait_task = WaitForDurationTask( + task_ref_name="wait_for_index_ref", + duration_time_seconds=5, + ) + + # Step 4: Search the index with the user's question (after the wait) + search_task = LlmSearchIndex( + task_ref_name="search_index_ref", + vector_db=VECTOR_DB, + namespace=namespace, + index=VECTOR_INDEX, + embedding_model_provider=EMBEDDING_PROVIDER, + embedding_model=EMBEDDING_MODEL, + query="${workflow.input.question}", + max_results=5, + dimensions=EMBEDDING_DIMENSIONS, + ) + + # Step 5: Generate an answer using the retrieved context + answer_task = LlmChatComplete( + task_ref_name="generate_answer_ref", + llm_provider=LLM_PROVIDER, + model=LLM_MODEL, + messages=[ + ChatMessage( + role="system", + message=( + "You are a helpful assistant. Answer the user's question " + "based ONLY on the context provided below. If the context " + "does not contain enough information, say so.\n\n" + "Context from knowledge base:\n" + "${search_index_ref.output.result}" + ), + ), + ChatMessage( + role="user", + message="${workflow.input.question}", + ), + ], + temperature=0.2, + max_tokens=1024, + ) + + # Chain the tasks sequentially + workflow >> convert_task >> index_task >> wait_task >> search_task >> answer_task + + # Define workflow outputs (mirrors the reference workflow output structure) + workflow.output_parameters({ + "indexing_status": "${index_doc_ref.output}", + "retrieved_context": "${search_index_ref.output.result}", + "final_answer": "${generate_answer_ref.output.result}", + }) + + return workflow + + +# ============================================================================= +# Main +# ============================================================================= + +def main(): + if len(sys.argv) < 3: + print("Usage: python rag_workflow.py ") + print() + print("Example:") + print(' python examples/rag_workflow.py examples/goog-20251231.pdf "What were Google\'s total revenues?"') + sys.exit(1) + + file_path = os.path.abspath(sys.argv[1]) + question = sys.argv[2] + + if not os.path.isfile(file_path): + print(f"Error: File not found: {file_path}") + sys.exit(1) + + # --- Configuration --- + api_config = Configuration() + clients = OrkesClients(configuration=api_config) + executor = clients.get_workflow_executor() + workflow_client = clients.get_workflow_client() + + print("=" * 80) + print("RAG WORKFLOW - Document Ingestion & Question Answering") + print("=" * 80) + print(f" File: {file_path}") + print(f" Question: {question}") + print(f" Server: {api_config.host}") + print() + + # --- Register and start workers --- + # scan_for_annotated_workers=True discovers @worker_task decorated functions + task_handler = TaskHandler( + workers=[], + configuration=api_config, + scan_for_annotated_workers=True, + ) + task_handler.start_processes() + + try: + # --- Create and register workflow --- + workflow = create_rag_workflow(executor) + workflow.register(overwrite=True) + print(f"Registered workflow: {workflow.name} v{workflow.version}") + + # --- Start the workflow --- + # Use start_workflow_with_input so the input is set correctly on the + # workflow execution (not nested inside the StartWorkflowRequest). + print("Starting workflow execution...") + workflow_id = workflow.start_workflow_with_input( + workflow_input={ + "file_path": file_path, + "question": question, + }, + ) + + ui_url = f"{api_config.ui_host}/execution/{workflow_id}" + print(f" Workflow ID: {workflow_id}") + print(f" View: {ui_url}") + + # --- Poll for completion --- + print(" Waiting for workflow to complete...") + max_wait = 120 + poll_interval = 2 + elapsed = 0 + status = "RUNNING" + wf_status = None + while elapsed < max_wait: + time.sleep(poll_interval) + elapsed += poll_interval + wf_status = workflow_client.get_workflow(workflow_id, include_tasks=False) + status = wf_status.status + if status in ("COMPLETED", "FAILED", "TERMINATED", "TIMED_OUT"): + break + + print(f" Status: {status}") + print() + + if status == "COMPLETED": + output = wf_status.output or {} + + # Show retrieved context + context = output.get("retrieved_context", []) + if context: + print(f"Retrieved {len(context)} chunk(s) from knowledge base") + for i, chunk in enumerate(context, 1): + score = chunk.get("score", 0) + text_preview = chunk.get("text", "")[:120] + print(f" {i}. (score={score:.3f}) {text_preview}...") + print() + + # Show the answer + answer = output.get("final_answer", "No answer generated.") + print("Answer:") + print("-" * 80) + print(answer) + print("-" * 80) + else: + print(f"Workflow did not complete successfully: {status}") + if hasattr(wf_status, "reason_for_incompletion") and wf_status.reason_for_incompletion: + print(f" Reason: {wf_status.reason_for_incompletion}") + + finally: + task_handler.stop_processes() + print("\nWorkers stopped.") + + +if __name__ == "__main__": + logging.basicConfig( + level=logging.INFO, + format="%(asctime)s [%(levelname)s] %(name)s: %(message)s", + ) + main() diff --git a/examples/test_ai_examples.py b/examples/test_ai_examples.py new file mode 100644 index 000000000..fa7aca420 --- /dev/null +++ b/examples/test_ai_examples.py @@ -0,0 +1,243 @@ +""" +Unit tests for AI workflow examples. + +Tests workflow creation, registration, and structure without requiring: +- Running Conductor server +- OpenAI/Anthropic API keys +- PostgreSQL/pgvector database +- MCP weather server +""" + +import unittest +import os +import sys +from unittest.mock import Mock, patch, MagicMock + +# Add parent directory to path +sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__)))) + +from conductor.client.configuration.configuration import Configuration +from conductor.client.workflow.executor.workflow_executor import WorkflowExecutor + + +class TestRAGWorkflow(unittest.TestCase): + """Tests for RAG workflow example.""" + + def setUp(self): + """Set up test fixtures.""" + self.config = Configuration(server_api_url="http://localhost:7001/api") + self.executor = Mock(spec=WorkflowExecutor) + + def test_imports(self): + """Test that all required imports are available.""" + try: + from conductor.client.workflow.task.llm_tasks import ( + LlmIndexText, + LlmSearchIndex, + LlmChatComplete, + ChatMessage + ) + from conductor.client.workflow.task.llm_tasks.utils.embedding_model import EmbeddingModel + from conductor.client.workflow.task.simple_task import SimpleTask + except ImportError as e: + self.fail(f"Import failed: {e}") + + def test_workflow_creation(self): + """Test RAG workflow can be created.""" + from conductor.client.workflow.conductor_workflow import ConductorWorkflow + from conductor.client.workflow.task.llm_tasks import LlmIndexText, LlmSearchIndex, LlmChatComplete + from conductor.client.workflow.task.llm_tasks.utils.embedding_model import EmbeddingModel + + # Create workflow + wf = ConductorWorkflow( + executor=self.executor, + name="test_rag", + version=1 + ) + + # Add RAG tasks + index_task = LlmIndexText( + task_ref_name="index_doc", + vector_db="pgvectordb", + index="test_index", + embedding_model=EmbeddingModel(provider="openai", model="text-embedding-3-small"), + text="test text", + doc_id="test_doc", + namespace="test_ns" + ) + + search_task = LlmSearchIndex( + task_ref_name="search_kb", + vector_db="pgvectordb", + namespace="test_ns", + index="test_index", + embedding_model_provider="openai", + embedding_model="text-embedding-3-small", + query="test query", + max_results=5 + ) + + # Verify tasks created + self.assertEqual(index_task.task_reference_name, "index_doc") + self.assertEqual(search_task.task_reference_name, "search_kb") + + # Verify input parameters + self.assertEqual(index_task.input_parameters["vectorDB"], "pgvectordb") + self.assertEqual(search_task.input_parameters["query"], "test query") + + +class TestMCPWorkflow(unittest.TestCase): + """Tests for MCP agent workflow example.""" + + def setUp(self): + """Set up test fixtures.""" + self.config = Configuration(server_api_url="http://localhost:7001/api") + self.executor = Mock(spec=WorkflowExecutor) + + def test_imports(self): + """Test that all required imports are available.""" + try: + from conductor.client.workflow.task.llm_tasks import ( + ListMcpTools, + CallMcpTool, + LlmChatComplete, + ChatMessage + ) + except ImportError as e: + self.fail(f"Import failed: {e}") + + def test_workflow_creation(self): + """Test MCP workflow can be created.""" + from conductor.client.workflow.conductor_workflow import ConductorWorkflow + from conductor.client.workflow.task.llm_tasks import ListMcpTools, CallMcpTool, LlmChatComplete, ChatMessage + + # Create workflow + wf = ConductorWorkflow( + executor=self.executor, + name="test_mcp_agent", + version=1 + ) + + mcp_server = "http://localhost:3001/mcp" + + # Add MCP tasks + list_tools = ListMcpTools( + task_ref_name="discover_tools", + mcp_server=mcp_server + ) + + call_tool = CallMcpTool( + task_ref_name="execute_tool", + mcp_server=mcp_server, + method="test_method" + ) + + plan_task = LlmChatComplete( + task_ref_name="plan_action", + llm_provider="anthropic", + model="claude-sonnet-4-20250514", + messages=[ + ChatMessage(role="system", message="You are an AI agent"), + ChatMessage(role="user", message="What should I do?") + ] + ) + + # Verify tasks created + self.assertEqual(list_tools.task_reference_name, "discover_tools") + self.assertEqual(call_tool.task_reference_name, "execute_tool") + self.assertEqual(plan_task.task_reference_name, "plan_action") + + # Verify input parameters + self.assertEqual(list_tools.input_parameters["mcpServer"], mcp_server) + self.assertEqual(call_tool.input_parameters["method"], "test_method") + self.assertEqual(plan_task.input_parameters["llmProvider"], "anthropic") + + def test_mcp_task_serialization(self): + """Test MCP tasks serialize correctly.""" + from conductor.client.workflow.task.llm_tasks import ListMcpTools, CallMcpTool + from conductor.client.workflow.task.task_type import TaskType + + list_tools = ListMcpTools( + task_ref_name="list_ref", + mcp_server="http://test.com/mcp" + ) + + # Verify task type (check task_type attribute, not type) + self.assertEqual(list_tools.task_type, TaskType.LIST_MCP_TOOLS) + + # Verify input parameters structure + self.assertIn("mcpServer", list_tools.input_parameters) + self.assertEqual(list_tools.input_parameters["mcpServer"], "http://test.com/mcp") + + call_tool = CallMcpTool( + task_ref_name="call_ref", + mcp_server="http://test.com/mcp", + method="get_weather", + arguments={"location": "Tokyo", "units": "celsius"} + ) + + # Verify task type + self.assertEqual(call_tool.task_type, TaskType.CALL_MCP_TOOL) + + # Verify all params present + self.assertIn("mcpServer", call_tool.input_parameters) + self.assertIn("method", call_tool.input_parameters) + self.assertIn("arguments", call_tool.input_parameters) + + self.assertEqual(call_tool.input_parameters["method"], "get_weather") + self.assertEqual(call_tool.input_parameters["arguments"]["location"], "Tokyo") + self.assertEqual(call_tool.input_parameters["arguments"]["units"], "celsius") + + +class TestChatMessageSerialization(unittest.TestCase): + """Tests for ChatMessage model.""" + + def test_chat_message_creation(self): + """Test ChatMessage can be created and serialized.""" + from conductor.client.workflow.task.llm_tasks import ChatMessage, Role + + # Create message + msg = ChatMessage( + role="user", + message="Hello, world!" + ) + + # Serialize + msg_dict = msg.to_dict() + + # Verify structure + self.assertEqual(msg_dict["role"], "user") + self.assertEqual(msg_dict["message"], "Hello, world!") + self.assertNotIn("media", msg_dict) # Should not include empty fields + + def test_chat_message_with_media(self): + """Test ChatMessage with media attachments.""" + from conductor.client.workflow.task.llm_tasks import ChatMessage + + msg = ChatMessage( + role="user", + message="Describe this image", + media=["https://example.com/image.jpg"], + mime_type="image/jpeg" + ) + + msg_dict = msg.to_dict() + + self.assertEqual(msg_dict["role"], "user") + self.assertIn("media", msg_dict) + self.assertEqual(msg_dict["media"], ["https://example.com/image.jpg"]) + self.assertEqual(msg_dict["mimeType"], "image/jpeg") + + def test_role_enum(self): + """Test Role enum values.""" + from conductor.client.workflow.task.llm_tasks import Role + + self.assertEqual(Role.USER.value, "user") + self.assertEqual(Role.ASSISTANT.value, "assistant") + self.assertEqual(Role.SYSTEM.value, "system") + self.assertEqual(Role.TOOL_CALL.value, "tool_call") + self.assertEqual(Role.TOOL.value, "tool") + + +if __name__ == '__main__': + unittest.main() diff --git a/src/conductor/client/ai/configuration.py b/src/conductor/client/ai/configuration.py index a40cf482f..edcfe1985 100644 --- a/src/conductor/client/ai/configuration.py +++ b/src/conductor/client/ai/configuration.py @@ -2,12 +2,21 @@ class LLMProvider(str, Enum): - AZURE_OPEN_AI = "azure_openai", + AZURE_OPEN_AI = "azure_openai" OPEN_AI = "openai" - GCP_VERTEX_AI = "vertex_ai", + GCP_VERTEX_AI = "vertex_ai" HUGGING_FACE = "huggingface" + ANTHROPIC = "anthropic" + BEDROCK = "bedrock" + COHERE = "cohere" + GROK = "Grok" + MISTRAL = "mistral" + OLLAMA = "ollama" + PERPLEXITY = "perplexity" class VectorDB(str, Enum): - PINECONE_DB = "pineconedb", + PINECONE_DB = "pineconedb" WEAVIATE_DB = "weaviatedb" + POSTGRES_DB = "pgvectordb" + MONGO_DB = "mongovectordb" diff --git a/src/conductor/client/ai/orchestrator.py b/src/conductor/client/ai/orchestrator.py index 35e3613b2..d4e084795 100644 --- a/src/conductor/client/ai/orchestrator.py +++ b/src/conductor/client/ai/orchestrator.py @@ -23,7 +23,7 @@ def __init__(self, api_configuration: Configuration, prompt_test_workflow_name: orkes_clients = OrkesClients(api_configuration) self.integration_client = orkes_clients.get_integration_client() - self.workflow_client = orkes_clients.get_integration_client() + self.workflow_client = orkes_clients.get_workflow_client() self.workflow_executor = orkes_clients.get_workflow_executor() self.prompt_client = orkes_clients.get_prompt_client() diff --git a/src/conductor/client/configuration/configuration.py b/src/conductor/client/configuration/configuration.py index 157e76073..3242ceb1d 100644 --- a/src/conductor/client/configuration/configuration.py +++ b/src/conductor/client/configuration/configuration.py @@ -45,7 +45,7 @@ def __init__( self.temp_folder_path = None self.__ui_host = os.getenv("CONDUCTOR_UI_SERVER_URL") if self.__ui_host is None: - self.__ui_host = self.host.replace("8080/api", "5001") + self.__ui_host = self.host.rstrip("/").removesuffix("/api") if authentication_settings is not None: self.authentication_settings = authentication_settings diff --git a/src/conductor/client/workflow/task/llm_tasks/__init__.py b/src/conductor/client/workflow/task/llm_tasks/__init__.py index e69de29bb..fe8c1d303 100644 --- a/src/conductor/client/workflow/task/llm_tasks/__init__.py +++ b/src/conductor/client/workflow/task/llm_tasks/__init__.py @@ -0,0 +1,36 @@ +from conductor.client.workflow.task.llm_tasks.chat_message import ChatMessage, Role +from conductor.client.workflow.task.llm_tasks.tool_spec import ToolSpec +from conductor.client.workflow.task.llm_tasks.tool_call import ToolCall +from conductor.client.workflow.task.llm_tasks.llm_chat_complete import LlmChatComplete +from conductor.client.workflow.task.llm_tasks.llm_text_complete import LlmTextComplete +from conductor.client.workflow.task.llm_tasks.llm_generate_embeddings import LlmGenerateEmbeddings +from conductor.client.workflow.task.llm_tasks.llm_query_embeddings import LlmQueryEmbeddings +from conductor.client.workflow.task.llm_tasks.llm_index_text import LlmIndexText +from conductor.client.workflow.task.llm_tasks.llm_index_documents import LlmIndexDocument +from conductor.client.workflow.task.llm_tasks.llm_search_index import LlmSearchIndex +from conductor.client.workflow.task.llm_tasks.generate_image import GenerateImage +from conductor.client.workflow.task.llm_tasks.generate_audio import GenerateAudio +from conductor.client.workflow.task.llm_tasks.llm_store_embeddings import LlmStoreEmbeddings +from conductor.client.workflow.task.llm_tasks.llm_search_embeddings import LlmSearchEmbeddings +from conductor.client.workflow.task.llm_tasks.list_mcp_tools import ListMcpTools +from conductor.client.workflow.task.llm_tasks.call_mcp_tool import CallMcpTool + +__all__ = [ + "ChatMessage", + "Role", + "ToolSpec", + "ToolCall", + "LlmChatComplete", + "LlmTextComplete", + "LlmGenerateEmbeddings", + "LlmQueryEmbeddings", + "LlmIndexText", + "LlmIndexDocument", + "LlmSearchIndex", + "GenerateImage", + "GenerateAudio", + "LlmStoreEmbeddings", + "LlmSearchEmbeddings", + "ListMcpTools", + "CallMcpTool", +] diff --git a/src/conductor/client/workflow/task/llm_tasks/call_mcp_tool.py b/src/conductor/client/workflow/task/llm_tasks/call_mcp_tool.py new file mode 100644 index 000000000..4c4b216e0 --- /dev/null +++ b/src/conductor/client/workflow/task/llm_tasks/call_mcp_tool.py @@ -0,0 +1,49 @@ +from __future__ import annotations + +from typing import Optional, Dict, Any + +from typing_extensions import Self + +from conductor.client.workflow.task.task import TaskInterface +from conductor.client.workflow.task.task_type import TaskType + + +class CallMcpTool(TaskInterface): + """Calls a specific tool on an MCP (Model Context Protocol) server. + + Args: + task_ref_name: Reference name for the task in the workflow. + mcp_server: MCP server URL. + method: Name of the tool to call. + arguments: Arguments to pass to the tool. + headers: Optional HTTP headers for the MCP server connection. + task_name: Optional custom task name. + """ + + def __init__( + self, + task_ref_name: str, + mcp_server: str, + method: str, + arguments: Optional[Dict[str, Any]] = None, + headers: Optional[Dict[str, str]] = None, + task_name: Optional[str] = None, + ) -> Self: + if task_name is None: + task_name = "call_mcp_tool" + + input_params: Dict[str, Any] = { + "mcpServer": mcp_server, + "method": method, + "arguments": arguments or {}, + } + + if headers: + input_params["headers"] = headers + + super().__init__( + task_name=task_name, + task_reference_name=task_ref_name, + task_type=TaskType.CALL_MCP_TOOL, + input_parameters=input_params, + ) diff --git a/src/conductor/client/workflow/task/llm_tasks/chat_message.py b/src/conductor/client/workflow/task/llm_tasks/chat_message.py new file mode 100644 index 000000000..ebdc2ac61 --- /dev/null +++ b/src/conductor/client/workflow/task/llm_tasks/chat_message.py @@ -0,0 +1,52 @@ +from __future__ import annotations + +from enum import Enum +from typing import Optional, List, TYPE_CHECKING + +if TYPE_CHECKING: + from conductor.client.workflow.task.llm_tasks.tool_call import ToolCall + + +class Role(str, Enum): + """Roles for participants in a chat conversation.""" + USER = "user" + ASSISTANT = "assistant" + SYSTEM = "system" + TOOL_CALL = "tool_call" + TOOL = "tool" + + +class ChatMessage: + """Represents a message in a chat conversation. + + Attributes: + role: The role of the message sender (user, assistant, system, tool_call, tool). + message: The text content of the message. + media: List of media URLs attached to the message. + mime_type: MIME type of the media content. + tool_calls: List of tool calls associated with the message. + """ + + def __init__( + self, + role: str, + message: str, + media: Optional[List[str]] = None, + mime_type: Optional[str] = None, + tool_calls: Optional[List[ToolCall]] = None, + ) -> None: + self.role = role + self.message = message + self.media = media or [] + self.mime_type = mime_type + self.tool_calls = tool_calls + + def to_dict(self) -> dict: + d = {"role": self.role, "message": self.message} + if self.media: + d["media"] = self.media + if self.mime_type is not None: + d["mimeType"] = self.mime_type + if self.tool_calls: + d["toolCalls"] = [tc.to_dict() for tc in self.tool_calls] + return d diff --git a/src/conductor/client/workflow/task/llm_tasks/generate_audio.py b/src/conductor/client/workflow/task/llm_tasks/generate_audio.py new file mode 100644 index 000000000..faf38a67e --- /dev/null +++ b/src/conductor/client/workflow/task/llm_tasks/generate_audio.py @@ -0,0 +1,69 @@ +from __future__ import annotations + +from typing import Optional, Dict, Any + +from typing_extensions import Self + +from conductor.client.workflow.task.task import TaskInterface +from conductor.client.workflow.task.task_type import TaskType + + +class GenerateAudio(TaskInterface): + """Generates audio (text-to-speech) using an LLM provider. + + Args: + task_ref_name: Reference name for the task in the workflow. + llm_provider: AI provider integration name. + model: Model name (e.g., "tts-1"). + text: Text content to convert to speech. + voice: Voice identifier. + speed: Speech speed multiplier. + response_format: Audio format (e.g., "mp3", "wav"). + n: Number of audio outputs to generate (default: 1). + prompt: Alternative prompt text. + prompt_variables: Variables for prompt template substitution. + task_name: Optional custom task name. + """ + + def __init__( + self, + task_ref_name: str, + llm_provider: str, + model: str, + text: Optional[str] = None, + voice: Optional[str] = None, + speed: Optional[float] = None, + response_format: Optional[str] = None, + n: int = 1, + prompt: Optional[str] = None, + prompt_variables: Optional[Dict[str, Any]] = None, + task_name: Optional[str] = None, + ) -> Self: + if task_name is None: + task_name = "generate_audio" + + input_params: Dict[str, Any] = { + "llmProvider": llm_provider, + "model": model, + "n": n, + } + + if text is not None: + input_params["text"] = text + if voice is not None: + input_params["voice"] = voice + if speed is not None: + input_params["speed"] = speed + if response_format is not None: + input_params["responseFormat"] = response_format + if prompt is not None: + input_params["prompt"] = prompt + if prompt_variables: + input_params["promptVariables"] = prompt_variables + + super().__init__( + task_name=task_name, + task_reference_name=task_ref_name, + task_type=TaskType.GENERATE_AUDIO, + input_parameters=input_params, + ) diff --git a/src/conductor/client/workflow/task/llm_tasks/generate_image.py b/src/conductor/client/workflow/task/llm_tasks/generate_image.py new file mode 100644 index 000000000..715cb563b --- /dev/null +++ b/src/conductor/client/workflow/task/llm_tasks/generate_image.py @@ -0,0 +1,73 @@ +from __future__ import annotations + +from typing import Optional, Dict, Any + +from typing_extensions import Self + +from conductor.client.workflow.task.task import TaskInterface +from conductor.client.workflow.task.task_type import TaskType + + +class GenerateImage(TaskInterface): + """Generates images using an LLM provider. + + Args: + task_ref_name: Reference name for the task in the workflow. + llm_provider: AI provider integration name (e.g., "openai"). + model: Model name (e.g., "dall-e-3"). + prompt: Image generation prompt. + width: Image width in pixels (default: 1024). + height: Image height in pixels (default: 1024). + size: Size specification (alternative to width/height, e.g., "1024x1024"). + style: Image style (e.g., "natural", "vivid"). + n: Number of images to generate (default: 1). + weight: Image weight parameter. + output_format: Output format - "jpg", "png", or "webp" (default: "png"). + prompt_variables: Variables for prompt template substitution. + task_name: Optional custom task name. + """ + + def __init__( + self, + task_ref_name: str, + llm_provider: str, + model: str, + prompt: str, + width: int = 1024, + height: int = 1024, + size: Optional[str] = None, + style: Optional[str] = None, + n: int = 1, + weight: Optional[float] = None, + output_format: str = "png", + prompt_variables: Optional[Dict[str, Any]] = None, + task_name: Optional[str] = None, + ) -> Self: + if task_name is None: + task_name = "generate_image" + + input_params: Dict[str, Any] = { + "llmProvider": llm_provider, + "model": model, + "prompt": prompt, + "width": width, + "height": height, + "n": n, + "outputFormat": output_format, + } + + if size is not None: + input_params["size"] = size + if style is not None: + input_params["style"] = style + if weight is not None: + input_params["weight"] = weight + if prompt_variables: + input_params["promptVariables"] = prompt_variables + + super().__init__( + task_name=task_name, + task_reference_name=task_ref_name, + task_type=TaskType.GENERATE_IMAGE, + input_parameters=input_params, + ) diff --git a/src/conductor/client/workflow/task/llm_tasks/list_mcp_tools.py b/src/conductor/client/workflow/task/llm_tasks/list_mcp_tools.py new file mode 100644 index 000000000..8b6013d4b --- /dev/null +++ b/src/conductor/client/workflow/task/llm_tasks/list_mcp_tools.py @@ -0,0 +1,43 @@ +from __future__ import annotations + +from typing import Optional, Dict + +from typing_extensions import Self + +from conductor.client.workflow.task.task import TaskInterface +from conductor.client.workflow.task.task_type import TaskType + + +class ListMcpTools(TaskInterface): + """Lists available tools from an MCP (Model Context Protocol) server. + + Args: + task_ref_name: Reference name for the task in the workflow. + mcp_server: MCP server URL (e.g., "http://localhost:3000/sse"). + headers: Optional HTTP headers for the MCP server connection. + task_name: Optional custom task name. + """ + + def __init__( + self, + task_ref_name: str, + mcp_server: str, + headers: Optional[Dict[str, str]] = None, + task_name: Optional[str] = None, + ) -> Self: + if task_name is None: + task_name = "list_mcp_tools" + + input_params = { + "mcpServer": mcp_server, + } + + if headers: + input_params["headers"] = headers + + super().__init__( + task_name=task_name, + task_reference_name=task_ref_name, + task_type=TaskType.LIST_MCP_TOOLS, + input_parameters=input_params, + ) diff --git a/src/conductor/client/workflow/task/llm_tasks/llm_chat_complete.py b/src/conductor/client/workflow/task/llm_tasks/llm_chat_complete.py index d26ede8aa..11a98b0db 100644 --- a/src/conductor/client/workflow/task/llm_tasks/llm_chat_complete.py +++ b/src/conductor/client/workflow/task/llm_tasks/llm_chat_complete.py @@ -1,58 +1,157 @@ from __future__ import annotations -from typing import Optional, List, Dict + +from typing import Optional, List, Dict, Any from typing_extensions import Self from conductor.client.workflow.task.task import TaskInterface from conductor.client.workflow.task.task_type import TaskType - -class ChatMessage: - - def __init__(self, role: str, message: str) -> None: - self.role = role - self.message = message +# Re-export ChatMessage for backward compatibility +from conductor.client.workflow.task.llm_tasks.chat_message import ChatMessage, Role # noqa: F401 +from conductor.client.workflow.task.llm_tasks.tool_spec import ToolSpec class LlmChatComplete(TaskInterface): - def __init__(self, task_ref_name: str, llm_provider: str, model: str, messages: List[ChatMessage], - stop_words: Optional[List[str]] = None, max_tokens: Optional[int] = 100, - temperature: int = 0, top_p: int = 1, instructions_template: Optional[str] = None, - template_variables: Optional[Dict[str, object]] = None) -> Self: - template_variables = template_variables or {} - stop_words = stop_words or [] + """Executes an LLM chat completion request. - optional_input_params = {} + Sends a conversation (messages) or a prompt template to an LLM provider + and returns the model's response. Supports tool calling, structured output, + multi-modal input, and advanced generation parameters. - if stop_words: - optional_input_params.update({"stopWords": stop_words}) + Args: + task_ref_name: Reference name for the task in the workflow. + llm_provider: AI model integration name (e.g., "openai", "anthropic"). + model: Model identifier (e.g., "gpt-4", "claude-sonnet-4-20250514"). + messages: List of ChatMessage objects for the conversation. + instructions_template: Prompt template name registered in Conductor. + template_variables: Variables to substitute in the prompt template. + prompt_version: Version of the prompt template to use. + tools: List of ToolSpec objects for function/tool calling. + user_input: Direct user input text (alternative to messages). + json_output: If True, request structured JSON output from the model. + google_search_retrieval: If True, enable Google search grounding (Gemini). + input_schema: JSON schema for validating input. + output_schema: JSON schema for structured output. + output_mime_type: MIME type for the output (e.g., "application/json"). + thinking_token_limit: Max tokens for extended thinking (Anthropic/Gemini). + reasoning_effort: Reasoning effort level (e.g., "low", "medium", "high"). + output_location: Storage location for output (e.g., S3 path). + voice: Voice ID for text-to-speech output. + participants: Map of participant names to their roles. + stop_words: List of stop sequences for generation. + max_tokens: Maximum tokens to generate. + temperature: Sampling temperature (0.0-2.0). + top_p: Nucleus sampling parameter. + top_k: Top-k sampling parameter. + frequency_penalty: Penalize frequent tokens (-2.0 to 2.0). + presence_penalty: Penalize present tokens (-2.0 to 2.0). + max_results: Maximum number of results to return. + task_name: Optional custom task name override. + """ - if max_tokens: - optional_input_params.update({"maxTokens": max_tokens}) + def __init__( + self, + task_ref_name: str, + llm_provider: str, + model: str, + messages: Optional[List[ChatMessage]] = None, + instructions_template: Optional[str] = None, + template_variables: Optional[Dict[str, object]] = None, + prompt_version: Optional[int] = None, + tools: Optional[List[ToolSpec]] = None, + user_input: Optional[str] = None, + json_output: bool = False, + google_search_retrieval: bool = False, + input_schema: Optional[Dict[str, Any]] = None, + output_schema: Optional[Dict[str, Any]] = None, + output_mime_type: Optional[str] = None, + thinking_token_limit: Optional[int] = None, + reasoning_effort: Optional[str] = None, + output_location: Optional[str] = None, + voice: Optional[str] = None, + participants: Optional[Dict[str, str]] = None, + stop_words: Optional[List[str]] = None, + max_tokens: Optional[int] = None, + temperature: Optional[float] = None, + top_p: Optional[float] = None, + top_k: Optional[int] = None, + frequency_penalty: Optional[float] = None, + presence_penalty: Optional[float] = None, + max_results: Optional[int] = None, + task_name: Optional[str] = None, + ) -> Self: + if task_name is None: + task_name = "llm_chat_complete" - input_params = { + input_params: Dict[str, Any] = { "llmProvider": llm_provider, "model": model, - "promptVariables": template_variables, - "temperature": temperature, - "topP": top_p, - "instructions": instructions_template, - "messages": messages } - input_params.update(optional_input_params) + if template_variables: + input_params["promptVariables"] = template_variables + if prompt_version is not None: + input_params["promptVersion"] = prompt_version + + if messages is not None: + input_params["messages"] = [ + m.to_dict() if hasattr(m, 'to_dict') else m for m in messages + ] + if instructions_template is not None: + input_params["instructions"] = instructions_template + if user_input is not None: + input_params["userInput"] = user_input + if tools: + input_params["tools"] = [t.to_dict() if hasattr(t, 'to_dict') else t for t in tools] + if json_output: + input_params["jsonOutput"] = json_output + if google_search_retrieval: + input_params["googleSearchRetrieval"] = google_search_retrieval + if input_schema is not None: + input_params["inputSchema"] = input_schema + if output_schema is not None: + input_params["outputSchema"] = output_schema + if output_mime_type is not None: + input_params["outputMimeType"] = output_mime_type + if thinking_token_limit is not None: + input_params["thinkingTokenLimit"] = thinking_token_limit + if reasoning_effort is not None: + input_params["reasoningEffort"] = reasoning_effort + if output_location is not None: + input_params["outputLocation"] = output_location + if voice is not None: + input_params["voice"] = voice + if participants: + input_params["participants"] = participants + if stop_words: + input_params["stopWords"] = stop_words + if max_tokens is not None: + input_params["maxTokens"] = max_tokens + if temperature is not None: + input_params["temperature"] = temperature + if top_p is not None: + input_params["topP"] = top_p + if top_k is not None: + input_params["topK"] = top_k + if frequency_penalty is not None: + input_params["frequencyPenalty"] = frequency_penalty + if presence_penalty is not None: + input_params["presencePenalty"] = presence_penalty + if max_results is not None: + input_params["maxResults"] = max_results super().__init__( - task_name="llm_chat_complete", + task_name=task_name, task_reference_name=task_ref_name, task_type=TaskType.LLM_CHAT_COMPLETE, - input_parameters=input_params + input_parameters=input_params, ) def prompt_variables(self, variables: Dict[str, object]) -> Self: - self.input_parameters["promptVariables"].update(variables) + self.input_parameters.setdefault("promptVariables", {}).update(variables) return self def prompt_variable(self, variable: str, value: object) -> Self: - self.input_parameters["promptVariables"][variable] = value + self.input_parameters.setdefault("promptVariables", {})[variable] = value return self diff --git a/src/conductor/client/workflow/task/llm_tasks/llm_generate_embeddings.py b/src/conductor/client/workflow/task/llm_tasks/llm_generate_embeddings.py index 9c2ef8e6b..b7f8fddfa 100644 --- a/src/conductor/client/workflow/task/llm_tasks/llm_generate_embeddings.py +++ b/src/conductor/client/workflow/task/llm_tasks/llm_generate_embeddings.py @@ -1,5 +1,7 @@ from __future__ import annotations + from typing import Optional + from typing_extensions import Self from conductor.client.workflow.task.task import TaskInterface @@ -7,16 +9,44 @@ class LlmGenerateEmbeddings(TaskInterface): - def __init__(self, task_ref_name: str, llm_provider: str, model: str, text: str, task_name: Optional[str] = None) -> Self: + """Generates embeddings from text using an LLM provider. + + Converts text into a vector representation using the specified + embedding model. + + Args: + task_ref_name: Reference name for the task in the workflow. + llm_provider: AI model integration name (e.g., "openai"). + model: Embedding model identifier (e.g., "text-embedding-ada-002"). + text: Text to generate embeddings for. + dimensions: Embedding vector dimensions. + task_name: Optional custom task name override. + """ + + def __init__( + self, + task_ref_name: str, + llm_provider: str, + model: str, + text: str, + dimensions: Optional[int] = None, + task_name: Optional[str] = None, + ) -> Self: if task_name is None: task_name = "llm_generate_embeddings" + + input_params = { + "llmProvider": llm_provider, + "model": model, + "text": text, + } + + if dimensions is not None: + input_params["dimensions"] = dimensions + super().__init__( task_name=task_name, task_reference_name=task_ref_name, task_type=TaskType.LLM_GENERATE_EMBEDDINGS, - input_parameters={ - "llmProvider": llm_provider, - "model": model, - "text": text, - } + input_parameters=input_params, ) diff --git a/src/conductor/client/workflow/task/llm_tasks/llm_index_documents.py b/src/conductor/client/workflow/task/llm_tasks/llm_index_documents.py index 5a89092d2..1b2a68dc2 100644 --- a/src/conductor/client/workflow/task/llm_tasks/llm_index_documents.py +++ b/src/conductor/client/workflow/task/llm_tasks/llm_index_documents.py @@ -10,29 +10,47 @@ class LlmIndexDocument(TaskInterface): - """ - Indexes the document specified by a URL - Inputs: - embedding_model.provider: AI provider to use for generating embeddings e.g. OpenAI - embedding_model.model: Model to be used to generate embeddings e.g. text-embedding-ada-002 - url: URL to read the document from. Can be HTTP(S), S3 or other blob store that the server can access - media_type: content type for the document. e.g. application/pdf, text/html, text/plain, application/json, text/json - namespace: (optional) namespace to separate the data inside the index - if supported by vector store (e.g. Pinecone) - index: Index or classname (in case of Weaviate) + """Indexes a document from a URL into a vector database. + + Fetches the document, splits it into chunks, generates embeddings, + and stores them in the vector database. + + Note: This class uses the LLM_INDEX_TEXT task type on the server side. + The server's IndexDocInput model handles both inline text (via LlmIndexText) + and URL-based document indexing (via this class) under the same task type. - Optional fields - chunk_size: size of the chunk so the document is split into the chunks and stored - chunk_overlap: how much the chunks should overlap - doc_id: by default the indexed document is given an id based on the URL, use doc_id to override this - metadata: a dictionary of optional metadata to be added to thd indexed doc + Args: + task_ref_name: Reference name for the task in the workflow. + vector_db: Vector database integration name. + namespace: Namespace for data isolation. + embedding_model: EmbeddingModel with provider and model name. + index: Index or collection name. + url: URL to fetch the document from (HTTP(S), S3, blob store). + media_type: Content type (e.g., application/pdf, text/html, text/plain). + chunk_size: Size of text chunks for splitting. + chunk_overlap: Overlap between chunks. + doc_id: Override the default URL-based document ID. + task_name: Optional custom task name. + metadata: Optional metadata dictionary to store with the document. + dimensions: Embedding vector dimensions. """ - def __init__(self, task_ref_name: str, vector_db: str, namespace: str, - embedding_model: EmbeddingModel, index: str, url: str, media_type: str, - chunk_size: Optional[int] = None, chunk_overlap: Optional[int] = None, doc_id: Optional[str] = None, - task_name: Optional[str] = None, - metadata: Optional[dict] = None) -> Self: - metadata = metadata or {} + def __init__( + self, + task_ref_name: str, + vector_db: str, + namespace: str, + embedding_model: EmbeddingModel, + index: str, + url: str, + media_type: str, + chunk_size: Optional[int] = None, + chunk_overlap: Optional[int] = None, + doc_id: Optional[str] = None, + task_name: Optional[str] = None, + metadata: Optional[dict] = None, + dimensions: Optional[int] = None, + ) -> Self: input_params = { "vectorDB": vector_db, "namespace": namespace, @@ -41,27 +59,25 @@ def __init__(self, task_ref_name: str, vector_db: str, namespace: str, "embeddingModel": embedding_model.model, "url": url, "mediaType": media_type, - "metadata": metadata } - optional_input_params = {} - + if metadata: + input_params["metadata"] = metadata if chunk_size is not None: - optional_input_params.update({"chunkSize": chunk_size}) - + input_params["chunkSize"] = chunk_size if chunk_overlap is not None: - optional_input_params.update({"chunkOverlap": chunk_overlap}) - + input_params["chunkOverlap"] = chunk_overlap if doc_id is not None: - optional_input_params.update({"docId": doc_id}) + input_params["docId"] = doc_id + if dimensions is not None: + input_params["dimensions"] = dimensions - input_params.update(optional_input_params) if task_name is None: - task_name = "llm_index_document" + task_name = "llm_index_text" super().__init__( task_name=task_name, task_reference_name=task_ref_name, - task_type=TaskType.LLM_INDEX_DOCUMENT, - input_parameters=input_params + task_type=TaskType.LLM_INDEX_TEXT, + input_parameters=input_params, ) diff --git a/src/conductor/client/workflow/task/llm_tasks/llm_index_text.py b/src/conductor/client/workflow/task/llm_tasks/llm_index_text.py index 234230e40..e87f1cb92 100644 --- a/src/conductor/client/workflow/task/llm_tasks/llm_index_text.py +++ b/src/conductor/client/workflow/task/llm_tasks/llm_index_text.py @@ -1,5 +1,7 @@ from __future__ import annotations + from typing import Optional + from typing_extensions import Self from conductor.client.workflow.task.llm_tasks.utils.embedding_model import EmbeddingModel @@ -8,39 +10,70 @@ class LlmIndexText(TaskInterface): + """Stores text as embeddings in a vector database. + + Generates embeddings from the provided text and indexes them. + + Args: + task_ref_name: Reference name for the task in the workflow. + vector_db: Vector database integration name (e.g., "pineconedb", "pgvectordb"). + index: Index or collection name in the vector database. + embedding_model: EmbeddingModel with provider and model name. + text: Text content to index. + doc_id: Unique identifier for the document. + namespace: Optional namespace for data isolation (e.g., Pinecone namespaces). + task_name: Optional custom task name. + metadata: Optional metadata dictionary to store with the document. + url: Optional URL of the source document. + chunk_size: Size of text chunks for splitting (default: 12000 on server). + chunk_overlap: Overlap between chunks (default: 400 on server). + dimensions: Embedding vector dimensions. """ - Stores the text as ebmeddings in the vector database - Inputs: - embedding_model.provider: AI provider to use for generating embeddings e.g. OpenAI - embedding_model.model: Model to be used to generate embeddings e.g. text-embedding-ada-002 - url: URL to read the document from. Can be HTTP(S), S3 or other blob store that the server can access - media_type: content type for the document. e.g. application/pdf, text/html, text/plain, application/json, text/json - namespace: (optional) namespace to separate the data inside the index - if supported by vector store (e.g. Pinecone) - index: Index or classname (in case of Weaviate) - doc_id: ID of the stored document in the vector db - metadata: a dictionary of optional metadata to be added to thd indexed doc - """ - - def __init__(self, task_ref_name: str, vector_db: str, index: str, - embedding_model: EmbeddingModel, text: str, doc_id: str, namespace: Optional[str] = None, task_name: Optional[str] = None, - metadata: Optional[dict] = None) -> Self: - metadata = metadata or {} + + def __init__( + self, + task_ref_name: str, + vector_db: str, + index: str, + embedding_model: EmbeddingModel, + text: str, + doc_id: str, + namespace: Optional[str] = None, + task_name: Optional[str] = None, + metadata: Optional[dict] = None, + url: Optional[str] = None, + chunk_size: Optional[int] = None, + chunk_overlap: Optional[int] = None, + dimensions: Optional[int] = None, + ) -> Self: if task_name is None: - task_name = "llm_index_doc" + task_name = "llm_index_text" + + input_params = { + "vectorDB": vector_db, + "index": index, + "embeddingModelProvider": embedding_model.provider, + "embeddingModel": embedding_model.model, + "text": text, + "docId": doc_id, + } + + if metadata: + input_params["metadata"] = metadata + if namespace is not None: + input_params["namespace"] = namespace + if url is not None: + input_params["url"] = url + if chunk_size is not None: + input_params["chunkSize"] = chunk_size + if chunk_overlap is not None: + input_params["chunkOverlap"] = chunk_overlap + if dimensions is not None: + input_params["dimensions"] = dimensions super().__init__( task_name=task_name, task_reference_name=task_ref_name, task_type=TaskType.LLM_INDEX_TEXT, - input_parameters={ - "vectorDB": vector_db, - "index": index, - "embeddingModelProvider": embedding_model.provider, - "embeddingModel": embedding_model.model, - "text": text, - "docId": doc_id, - "metadata": metadata - } + input_parameters=input_params, ) - if namespace is not None: - self.input_parameter("namespace", namespace) diff --git a/src/conductor/client/workflow/task/llm_tasks/llm_query_embeddings.py b/src/conductor/client/workflow/task/llm_tasks/llm_query_embeddings.py index 1c9e9947a..4daf7a963 100644 --- a/src/conductor/client/workflow/task/llm_tasks/llm_query_embeddings.py +++ b/src/conductor/client/workflow/task/llm_tasks/llm_query_embeddings.py @@ -1,4 +1,5 @@ from __future__ import annotations + from typing import List, Optional from typing_extensions import Self @@ -8,19 +9,44 @@ class LlmQueryEmbeddings(TaskInterface): - def __init__(self, task_ref_name: str, vector_db: str, index: str, - embeddings: List[int], task_name: Optional[str] = None, namespace: Optional[str] = None) -> Self: + """Queries a vector database using pre-computed embeddings. + + Searches the vector database for the nearest neighbors to the + provided embedding vector. + + Args: + task_ref_name: Reference name for the task in the workflow. + vector_db: Vector database integration name. + index: Index or collection name. + embeddings: Embedding vector (list of floats) to search with. + task_name: Optional custom task name override. + namespace: Optional namespace for data isolation. + """ + + def __init__( + self, + task_ref_name: str, + vector_db: str, + index: str, + embeddings: List[float], + task_name: Optional[str] = None, + namespace: Optional[str] = None, + ) -> Self: if task_name is None: task_name = "llm_get_embeddings" + input_params = { + "vectorDB": vector_db, + "index": index, + "embeddings": embeddings, + } + + if namespace is not None: + input_params["namespace"] = namespace + super().__init__( task_name=task_name, task_reference_name=task_ref_name, task_type=TaskType.LLM_GET_EMBEDDINGS, - input_parameters={ - "vectorDB": vector_db, - "namespace": namespace, - "index": index, - "embeddings": embeddings - } + input_parameters=input_params, ) diff --git a/src/conductor/client/workflow/task/llm_tasks/llm_search_embeddings.py b/src/conductor/client/workflow/task/llm_tasks/llm_search_embeddings.py new file mode 100644 index 000000000..df386d6bc --- /dev/null +++ b/src/conductor/client/workflow/task/llm_tasks/llm_search_embeddings.py @@ -0,0 +1,64 @@ +from __future__ import annotations + +from typing import Optional, List, Dict, Any + +from typing_extensions import Self + +from conductor.client.workflow.task.task import TaskInterface +from conductor.client.workflow.task.task_type import TaskType + + +class LlmSearchEmbeddings(TaskInterface): + """Searches a vector database using pre-computed embeddings. + + Args: + task_ref_name: Reference name for the task in the workflow. + vector_db: Vector database integration name. + index: Index or collection name. + embeddings: Pre-computed embedding vector to search with. + namespace: Optional namespace for data isolation. + max_results: Maximum number of results to return. + dimensions: Embedding vector dimensions. + embedding_model: Embedding model name. + embedding_model_provider: Embedding model provider name. + task_name: Optional custom task name. + """ + + def __init__( + self, + task_ref_name: str, + vector_db: str, + index: str, + embeddings: List[float], + namespace: Optional[str] = None, + max_results: int = 1, + dimensions: Optional[int] = None, + embedding_model: Optional[str] = None, + embedding_model_provider: Optional[str] = None, + task_name: Optional[str] = None, + ) -> Self: + if task_name is None: + task_name = "llm_search_embeddings" + + input_params: Dict[str, Any] = { + "vectorDB": vector_db, + "index": index, + "embeddings": embeddings, + "maxResults": max_results, + } + + if namespace is not None: + input_params["namespace"] = namespace + if dimensions is not None: + input_params["dimensions"] = dimensions + if embedding_model is not None: + input_params["embeddingModel"] = embedding_model + if embedding_model_provider is not None: + input_params["embeddingModelProvider"] = embedding_model_provider + + super().__init__( + task_name=task_name, + task_reference_name=task_ref_name, + task_type=TaskType.LLM_SEARCH_EMBEDDINGS, + input_parameters=input_params, + ) diff --git a/src/conductor/client/workflow/task/llm_tasks/llm_search_index.py b/src/conductor/client/workflow/task/llm_tasks/llm_search_index.py index d0e317b74..d8c3d4b82 100644 --- a/src/conductor/client/workflow/task/llm_tasks/llm_search_index.py +++ b/src/conductor/client/workflow/task/llm_tasks/llm_search_index.py @@ -1,5 +1,7 @@ from __future__ import annotations + from typing import Optional + from typing_extensions import Self from conductor.client.workflow.task.task import TaskInterface @@ -7,22 +9,56 @@ class LlmSearchIndex(TaskInterface): - def __init__(self, task_ref_name: str, vector_db: str, namespace: str, index: str, - embedding_model_provider: str, embedding_model: str, query: str, task_name: Optional[str] = None, max_results : int = 1) -> Self: + """Searches a vector database index using a text query. + + Generates embeddings from the query text and searches the vector + database for semantically similar documents. + + Args: + task_ref_name: Reference name for the task in the workflow. + vector_db: Vector database integration name. + namespace: Namespace for data isolation. + index: Index or collection name. + embedding_model_provider: AI model integration name for embeddings. + embedding_model: Embedding model identifier. + query: Text query to search for. + task_name: Optional custom task name override. + max_results: Maximum number of results to return (default: 1). + dimensions: Embedding vector dimensions. + """ + + def __init__( + self, + task_ref_name: str, + vector_db: str, + namespace: str, + index: str, + embedding_model_provider: str, + embedding_model: str, + query: str, + task_name: Optional[str] = None, + max_results: int = 1, + dimensions: Optional[int] = None, + ) -> Self: if task_name is None: task_name = "llm_search_index" + input_params = { + "vectorDB": vector_db, + "namespace": namespace, + "index": index, + "embeddingModelProvider": embedding_model_provider, + "embeddingModel": embedding_model, + "query": query, + "maxResults": max_results, + } + + if dimensions is not None: + input_params["dimensions"] = dimensions + super().__init__( task_name=task_name, task_reference_name=task_ref_name, task_type=TaskType.LLM_SEARCH_INDEX, - input_parameters={ - "vectorDB": vector_db, - "namespace": namespace, - "index": index, - "embeddingModelProvider": embedding_model_provider, - "embeddingModel": embedding_model, - "query": query, - "maxResults": max_results - } + input_parameters=input_params, ) diff --git a/src/conductor/client/workflow/task/llm_tasks/llm_store_embeddings.py b/src/conductor/client/workflow/task/llm_tasks/llm_store_embeddings.py new file mode 100644 index 000000000..725a4d049 --- /dev/null +++ b/src/conductor/client/workflow/task/llm_tasks/llm_store_embeddings.py @@ -0,0 +1,65 @@ +from __future__ import annotations + +from typing import Optional, List, Dict, Any + +from typing_extensions import Self + +from conductor.client.workflow.task.task import TaskInterface +from conductor.client.workflow.task.task_type import TaskType + + +class LlmStoreEmbeddings(TaskInterface): + """Stores pre-computed embeddings directly in a vector database. + + Args: + task_ref_name: Reference name for the task in the workflow. + vector_db: Vector database integration name. + index: Index or collection name. + embeddings: Pre-computed embedding vector. + namespace: Optional namespace for data isolation. + id: Document ID (auto-generated UUID if not provided). + metadata: Optional metadata dictionary. + embedding_model: Embedding model name. + embedding_model_provider: Embedding model provider name. + task_name: Optional custom task name. + """ + + def __init__( + self, + task_ref_name: str, + vector_db: str, + index: str, + embeddings: List[float], + namespace: Optional[str] = None, + id: Optional[str] = None, + metadata: Optional[Dict[str, Any]] = None, + embedding_model: Optional[str] = None, + embedding_model_provider: Optional[str] = None, + task_name: Optional[str] = None, + ) -> Self: + if task_name is None: + task_name = "llm_store_embeddings" + + input_params: Dict[str, Any] = { + "vectorDB": vector_db, + "index": index, + "embeddings": embeddings, + } + + if namespace is not None: + input_params["namespace"] = namespace + if id is not None: + input_params["id"] = id + if metadata: + input_params["metadata"] = metadata + if embedding_model is not None: + input_params["embeddingModel"] = embedding_model + if embedding_model_provider is not None: + input_params["embeddingModelProvider"] = embedding_model_provider + + super().__init__( + task_name=task_name, + task_reference_name=task_ref_name, + task_type=TaskType.LLM_STORE_EMBEDDINGS, + input_parameters=input_params, + ) diff --git a/src/conductor/client/workflow/task/llm_tasks/llm_text_complete.py b/src/conductor/client/workflow/task/llm_tasks/llm_text_complete.py index fd843d957..8bd4391a2 100644 --- a/src/conductor/client/workflow/task/llm_tasks/llm_text_complete.py +++ b/src/conductor/client/workflow/task/llm_tasks/llm_text_complete.py @@ -1,6 +1,6 @@ from __future__ import annotations -from typing import Optional, List, Dict +from typing import Optional, List, Dict, Any from typing_extensions import Self @@ -9,44 +9,88 @@ class LlmTextComplete(TaskInterface): - def __init__(self, task_ref_name: str, llm_provider: str, model: str, prompt_name: str, - stop_words: Optional[List[str]] = None, max_tokens: Optional[int] = 100, - temperature: int = 0, top_p: int = 1, task_name: Optional[str] = None) -> Self: - stop_words = stop_words or [] - optional_input_params = {} + """Executes an LLM text completion request using a prompt template. - if stop_words: - optional_input_params.update({"stopWords": stop_words}) + Sends a prompt template with variables to an LLM provider and returns + the model's text completion response. - if max_tokens: - optional_input_params.update({"maxTokens": max_tokens}) + Args: + task_ref_name: Reference name for the task in the workflow. + llm_provider: AI model integration name (e.g., "openai", "anthropic"). + model: Model identifier (e.g., "gpt-4", "claude-sonnet-4-20250514"). + prompt_name: Name of the prompt template registered in Conductor. + prompt_version: Version of the prompt template to use. + stop_words: List of stop sequences for generation. + max_tokens: Maximum tokens to generate. + temperature: Sampling temperature (0.0-2.0). + top_p: Nucleus sampling parameter. + top_k: Top-k sampling parameter. + frequency_penalty: Penalize frequent tokens (-2.0 to 2.0). + presence_penalty: Penalize present tokens (-2.0 to 2.0). + max_results: Maximum number of results to return. + json_output: If True, request structured JSON output from the model. + task_name: Optional custom task name override. + """ + def __init__( + self, + task_ref_name: str, + llm_provider: str, + model: str, + prompt_name: str, + prompt_version: Optional[int] = None, + stop_words: Optional[List[str]] = None, + max_tokens: Optional[int] = None, + temperature: Optional[float] = None, + top_p: Optional[float] = None, + top_k: Optional[int] = None, + frequency_penalty: Optional[float] = None, + presence_penalty: Optional[float] = None, + max_results: Optional[int] = None, + json_output: bool = False, + task_name: Optional[str] = None, + ) -> Self: if not task_name: task_name = "llm_text_complete" - input_params = { + input_params: Dict[str, Any] = { "llmProvider": llm_provider, "model": model, "promptName": prompt_name, - "promptVariables": {}, - "temperature": temperature, - "topP": top_p, } - input_params.update(optional_input_params) + if prompt_version is not None: + input_params["promptVersion"] = prompt_version + if stop_words: + input_params["stopWords"] = stop_words + if max_tokens is not None: + input_params["maxTokens"] = max_tokens + if temperature is not None: + input_params["temperature"] = temperature + if top_p is not None: + input_params["topP"] = top_p + if top_k is not None: + input_params["topK"] = top_k + if frequency_penalty is not None: + input_params["frequencyPenalty"] = frequency_penalty + if presence_penalty is not None: + input_params["presencePenalty"] = presence_penalty + if max_results is not None: + input_params["maxResults"] = max_results + if json_output: + input_params["jsonOutput"] = json_output super().__init__( task_name=task_name, task_reference_name=task_ref_name, task_type=TaskType.LLM_TEXT_COMPLETE, - input_parameters=input_params + input_parameters=input_params, ) - self.input_parameters["promptVariables"] = {} def prompt_variables(self, variables: Dict[str, object]) -> Self: - self.input_parameters["promptVariables"].update(variables) + self.input_parameters.setdefault("promptVariables", {}).update(variables) return self def prompt_variable(self, variable: str, value: object) -> Self: - self.input_parameters["promptVariables"][variable] = value + self.input_parameters.setdefault("promptVariables", {})[variable] = value return self diff --git a/src/conductor/client/workflow/task/llm_tasks/tool_call.py b/src/conductor/client/workflow/task/llm_tasks/tool_call.py new file mode 100644 index 000000000..ab0c89933 --- /dev/null +++ b/src/conductor/client/workflow/task/llm_tasks/tool_call.py @@ -0,0 +1,44 @@ +from __future__ import annotations + +from typing import Optional, Dict, Any + + +class ToolCall: + """Represents a tool call made by an LLM during chat completion. + + Attributes: + task_reference_name: Reference name for the task in a workflow. + name: Name of the tool being called. + integration_names: Map of integration type to integration name. + type: Task type for execution (default: "SIMPLE"). + input_parameters: Input parameters for the tool call. + output: Output from the tool execution. + """ + + def __init__( + self, + name: str, + task_reference_name: Optional[str] = None, + integration_names: Optional[Dict[str, str]] = None, + type: str = "SIMPLE", + input_parameters: Optional[Dict[str, Any]] = None, + output: Optional[Dict[str, Any]] = None, + ) -> None: + self.task_reference_name = task_reference_name + self.name = name + self.integration_names = integration_names or {} + self.type = type + self.input_parameters = input_parameters or {} + self.output = output or {} + + def to_dict(self) -> dict: + d: Dict[str, Any] = {"name": self.name, "type": self.type} + if self.task_reference_name is not None: + d["taskReferenceName"] = self.task_reference_name + if self.integration_names: + d["integrationNames"] = self.integration_names + if self.input_parameters: + d["inputParameters"] = self.input_parameters + if self.output: + d["output"] = self.output + return d diff --git a/src/conductor/client/workflow/task/llm_tasks/tool_spec.py b/src/conductor/client/workflow/task/llm_tasks/tool_spec.py new file mode 100644 index 000000000..ef25362b2 --- /dev/null +++ b/src/conductor/client/workflow/task/llm_tasks/tool_spec.py @@ -0,0 +1,49 @@ +from __future__ import annotations + +from typing import Optional, Dict, Any + + +class ToolSpec: + """Specification for a tool available to an LLM during chat completion. + + Attributes: + name: Name of the tool. + type: Type of the tool (e.g., "SIMPLE", "SUB_WORKFLOW"). + description: Human-readable description of the tool. + config_params: Configuration parameters for the tool. + integration_names: Map of integration type to integration name. + input_schema: JSON Schema for the tool's input. + output_schema: JSON Schema for the tool's output. + """ + + def __init__( + self, + name: str, + type: str = "SIMPLE", + description: Optional[str] = None, + config_params: Optional[Dict[str, Any]] = None, + integration_names: Optional[Dict[str, str]] = None, + input_schema: Optional[Dict[str, Any]] = None, + output_schema: Optional[Dict[str, Any]] = None, + ) -> None: + self.name = name + self.type = type + self.description = description + self.config_params = config_params or {} + self.integration_names = integration_names or {} + self.input_schema = input_schema or {} + self.output_schema = output_schema or {} + + def to_dict(self) -> dict: + d: Dict[str, Any] = {"name": self.name, "type": self.type} + if self.description is not None: + d["description"] = self.description + if self.config_params: + d["configParams"] = self.config_params + if self.integration_names: + d["integrationNames"] = self.integration_names + if self.input_schema: + d["inputSchema"] = self.input_schema + if self.output_schema: + d["outputSchema"] = self.output_schema + return d diff --git a/src/conductor/client/workflow/task/task_type.py b/src/conductor/client/workflow/task/task_type.py index efdd07f89..38ebb16ad 100644 --- a/src/conductor/client/workflow/task/task_type.py +++ b/src/conductor/client/workflow/task/task_type.py @@ -32,5 +32,11 @@ class TaskType(str, Enum): LLM_TEXT_COMPLETE = "LLM_TEXT_COMPLETE" LLM_CHAT_COMPLETE = "LLM_CHAT_COMPLETE" LLM_INDEX_TEXT = "LLM_INDEX_TEXT" - LLM_INDEX_DOCUMENT = "LLM_INDEX_DOCUMENT" + LLM_INDEX_DOCUMENT = "LLM_INDEX_TEXT" # Deprecated: server handles document indexing via LLM_INDEX_TEXT LLM_SEARCH_INDEX = "LLM_SEARCH_INDEX" + GENERATE_IMAGE = "GENERATE_IMAGE" + GENERATE_AUDIO = "GENERATE_AUDIO" + LLM_STORE_EMBEDDINGS = "LLM_STORE_EMBEDDINGS" + LLM_SEARCH_EMBEDDINGS = "LLM_SEARCH_EMBEDDINGS" + LIST_MCP_TOOLS = "LIST_MCP_TOOLS" + CALL_MCP_TOOL = "CALL_MCP_TOOL" diff --git a/tests/integration/test_ai_examples.py b/tests/integration/test_ai_examples.py new file mode 100644 index 000000000..8ec11fb92 --- /dev/null +++ b/tests/integration/test_ai_examples.py @@ -0,0 +1,506 @@ +""" +Integration tests: Execute AI example workflows from the Conductor AI README. + +These tests create and execute real AI workflows against the Conductor server +using OpenAI and Anthropic providers, plus MCP tool integration. + +Requires: + - Conductor server at localhost:7001 with AI enabled + - OpenAI and Anthropic API keys configured on the server + - MCP weather server at localhost:3001 +""" + +import json +import time +import unittest + +from conductor.client.configuration.configuration import Configuration +from conductor.client.orkes_clients import OrkesClients +from conductor.client.workflow.conductor_workflow import ConductorWorkflow +from conductor.client.workflow.executor.workflow_executor import WorkflowExecutor + +from conductor.client.workflow.task.llm_tasks import ( + ChatMessage, + Role, + ToolSpec, + LlmChatComplete, + LlmTextComplete, + LlmGenerateEmbeddings, + GenerateImage, + GenerateAudio, + ListMcpTools, + CallMcpTool, +) + +SERVER_URL = "http://localhost:7001/api" +MCP_SERVER = "http://localhost:3001/mcp" + +# Models +OPENAI_CHAT_MODEL = "gpt-4o-mini" +ANTHROPIC_CHAT_MODEL = "claude-sonnet-4-20250514" +OPENAI_EMBEDDING_MODEL = "text-embedding-3-small" +OPENAI_IMAGE_MODEL = "dall-e-3" +OPENAI_TTS_MODEL = "tts-1" + +WORKFLOW_PREFIX = "sdk_ai_example_" + + +class TestAIExamples(unittest.TestCase): + """Execute all AI example workflows from the Conductor AI README using the Python SDK.""" + + @classmethod + def setUpClass(cls): + cls.config = Configuration(server_api_url=SERVER_URL) + cls.clients = OrkesClients(configuration=cls.config) + cls.executor = WorkflowExecutor(configuration=cls.config) + cls.metadata_client = cls.clients.get_metadata_client() + cls.workflow_client = cls.clients.get_workflow_client() + cls.registered_workflows = [] + + @classmethod + def tearDownClass(cls): + """Clean up all test workflows.""" + for wf_name in cls.registered_workflows: + try: + cls.metadata_client.unregister_workflow_def(wf_name, 1) + except Exception: + pass + + def _execute_and_assert(self, workflow: ConductorWorkflow, workflow_input=None, + wait_for_seconds=30) -> dict: + """Execute a workflow synchronously and assert it completed.""" + wf_name = workflow.name + self.registered_workflows.append(wf_name) + + run = workflow.execute(workflow_input=workflow_input or {}, + wait_for_seconds=wait_for_seconds) + + status = run.status + self.assertEqual( + status, "COMPLETED", + f"Workflow {wf_name} did not complete. Status: {status}. " + f"Tasks: {self._task_summary(run)}" + ) + return run + + def _task_summary(self, run) -> str: + """Extract task summary for error messages.""" + summaries = [] + for t in (run.tasks or []): + s = f"{t.reference_task_name}={t.status}" + if t.reason_for_incompletion: + s += f" ({t.reason_for_incompletion[:200]})" + summaries.append(s) + return "; ".join(summaries) + + def _get_task_output(self, run, task_ref: str) -> dict: + """Get output data from a specific task in the workflow run.""" + for t in (run.tasks or []): + if t.reference_task_name == task_ref: + return t.output_data or {} + return {} + + # ─── Example 1: Chat Completion ────────────────────────────────────── + + def test_01_chat_completion_openai(self): + """README Example 1 - Chat completion with OpenAI.""" + wf = ConductorWorkflow( + executor=self.executor, + name=f"{WORKFLOW_PREFIX}chat_openai", + version=1, + ) + chat = LlmChatComplete( + task_ref_name="chat", + llm_provider="openai", + model=OPENAI_CHAT_MODEL, + messages=[ + ChatMessage(role=Role.SYSTEM, message="You are a helpful assistant."), + ChatMessage(role=Role.USER, message="What is the capital of France?"), + ], + temperature=0.7, + max_tokens=500, + ) + wf >> chat + + run = self._execute_and_assert(wf) + output = self._get_task_output(run, "chat") + + self.assertIn("result", output) + result = output["result"].lower() + self.assertIn("paris", result, f"Expected 'paris' in response, got: {output['result']}") + print(f" OpenAI Chat: {output['result'][:100]}") + + def test_02_chat_completion_anthropic(self): + """README Example 1 variant - Chat completion with Anthropic Claude.""" + wf = ConductorWorkflow( + executor=self.executor, + name=f"{WORKFLOW_PREFIX}chat_anthropic", + version=1, + ) + chat = LlmChatComplete( + task_ref_name="chat", + llm_provider="anthropic", + model=ANTHROPIC_CHAT_MODEL, + messages=[ + ChatMessage(role=Role.SYSTEM, message="You are a helpful assistant."), + ChatMessage(role=Role.USER, message="What is the capital of France?"), + ], + temperature=0.7, + max_tokens=500, + ) + wf >> chat + + run = self._execute_and_assert(wf) + output = self._get_task_output(run, "chat") + + self.assertIn("result", output) + result = output["result"].lower() + self.assertIn("paris", result, f"Expected 'paris' in response, got: {output['result']}") + print(f" Anthropic Chat: {output['result'][:100]}") + + # ─── Example 2: Generate Embeddings ────────────────────────────────── + + def test_03_generate_embeddings(self): + """README Example 2 - Generate embeddings with OpenAI.""" + wf = ConductorWorkflow( + executor=self.executor, + name=f"{WORKFLOW_PREFIX}embeddings", + version=1, + ) + embed = LlmGenerateEmbeddings( + task_ref_name="embeddings", + llm_provider="openai", + model=OPENAI_EMBEDDING_MODEL, + text="Conductor is an orchestration platform", + ) + wf >> embed + + run = self._execute_and_assert(wf) + output = self._get_task_output(run, "embeddings") + + self.assertIn("result", output) + embeddings = output["result"] + self.assertIsInstance(embeddings, list, "Embeddings should be a list") + self.assertGreater(len(embeddings), 100, f"Expected high-dimensional vector, got {len(embeddings)} dims") + self.assertIsInstance(embeddings[0], float, "Each element should be a float") + print(f" Embeddings: {len(embeddings)} dimensions, first 3: {embeddings[:3]}") + + # ─── Example 3: Image Generation ───────────────────────────────────── + + def test_04_image_generation(self): + """README Example 3 - Generate image with OpenAI DALL-E.""" + wf = ConductorWorkflow( + executor=self.executor, + name=f"{WORKFLOW_PREFIX}image_gen", + version=1, + ) + img = GenerateImage( + task_ref_name="image", + llm_provider="openai", + model=OPENAI_IMAGE_MODEL, + prompt="A futuristic cityscape at sunset", + width=1024, + height=1024, + n=1, + style="vivid", + ) + wf >> img + + run = self._execute_and_assert(wf) + output = self._get_task_output(run, "image") + + # DALL-E returns url, b64_json, media array, or result + has_result = (output.get("url") or output.get("b64_json") + or output.get("result") or output.get("media")) + self.assertTrue(has_result, f"Expected image output, got: {list(output.keys())}") + print(f" Image output keys: {list(output.keys())}") + if output.get("url"): + print(f" Image URL: {output['url'][:100]}...") + if output.get("media"): + print(f" Image media: {str(output['media'])[:200]}") + + # ─── Example 4: Audio Generation (TTS) ─────────────────────────────── + + def test_05_audio_generation(self): + """README Example 4 - Text-to-speech with OpenAI.""" + wf = ConductorWorkflow( + executor=self.executor, + name=f"{WORKFLOW_PREFIX}tts", + version=1, + ) + audio = GenerateAudio( + task_ref_name="audio", + llm_provider="openai", + model=OPENAI_TTS_MODEL, + text="Hello, this is a test of text to speech.", + voice="alloy", + speed=1.0, + response_format="mp3", + ) + wf >> audio + + run = self._execute_and_assert(wf) + output = self._get_task_output(run, "audio") + + # TTS returns a URL, audio data, media, or result + has_result = (output.get("url") or output.get("result") + or output.get("format") or output.get("media")) + self.assertTrue(has_result, f"Expected audio output, got: {list(output.keys())}") + print(f" Audio output keys: {list(output.keys())}") + + # ─── Example 7a: MCP - List Tools ──────────────────────────────────── + + def test_06_mcp_list_tools(self): + """README Example 7 - List tools from MCP server.""" + wf = ConductorWorkflow( + executor=self.executor, + name=f"{WORKFLOW_PREFIX}mcp_list", + version=1, + ) + list_tools = ListMcpTools( + task_ref_name="list_tools", + mcp_server=MCP_SERVER, + ) + wf >> list_tools + + run = self._execute_and_assert(wf) + output = self._get_task_output(run, "list_tools") + + self.assertIn("tools", output, f"Expected 'tools' in output, got: {list(output.keys())}") + tools = output["tools"] + self.assertIsInstance(tools, list) + self.assertGreater(len(tools), 0, "Expected at least one tool") + + tool_names = [t["name"] for t in tools] + self.assertIn("get_current_weather", tool_names) + print(f" MCP Tools found: {tool_names}") + + # ─── Example 7b: MCP - Call Tool ───────────────────────────────────── + + def test_07_mcp_call_tool(self): + """README Example 7 - Call MCP weather tool directly.""" + wf = ConductorWorkflow( + executor=self.executor, + name=f"{WORKFLOW_PREFIX}mcp_call", + version=1, + ) + call = CallMcpTool( + task_ref_name="weather", + mcp_server=MCP_SERVER, + method="get_current_weather", + arguments={"city": "New York"}, + ) + wf >> call + + run = self._execute_and_assert(wf) + output = self._get_task_output(run, "weather") + + # MCP returns content array + self.assertIn("content", output, f"Expected 'content' in output, got: {list(output.keys())}") + content = output["content"] + self.assertIsInstance(content, list) + self.assertGreater(len(content), 0) + + # Check for weather data in the text response + text = content[0].get("text", "") + self.assertTrue(len(text) > 0, "Expected non-empty weather response") + print(f" MCP Weather: {text[:200]}") + + # ─── Example 8: MCP + AI Agent Workflow ────────────────────────────── + + def test_08_mcp_ai_agent(self): + """README Example 8 - MCP + AI Agent: discover tools, plan, execute, summarize.""" + wf = ConductorWorkflow( + executor=self.executor, + name=f"{WORKFLOW_PREFIX}mcp_agent", + version=1, + ) + + # Step 1: Discover available tools from MCP server + discover = ListMcpTools( + task_ref_name="discover_tools", + mcp_server=MCP_SERVER, + ) + + # Step 2: LLM decides which tool to use (using Anthropic) + plan = LlmChatComplete( + task_ref_name="plan", + llm_provider="anthropic", + model=ANTHROPIC_CHAT_MODEL, + messages=[ + ChatMessage( + role=Role.SYSTEM, + message="You are an AI agent. Available tools: ${discover_tools.output.tools}. " + "The user wants to: ${workflow.input.task}. " + "Respond with ONLY a JSON object (no markdown, no explanation): " + "{\"method\": \"\", \"arguments\": {}}" + ), + ChatMessage( + role=Role.USER, + message="Which tool should I use and what parameters?" + ), + ], + temperature=0.1, + max_tokens=500, + ) + + # Step 3: Execute the chosen tool + execute = CallMcpTool( + task_ref_name="execute", + mcp_server=MCP_SERVER, + method="get_current_weather", + arguments={"city": "${workflow.input.city}"}, + ) + + # Step 4: Summarize the result + summarize = LlmChatComplete( + task_ref_name="summarize", + llm_provider="openai", + model=OPENAI_CHAT_MODEL, + messages=[ + ChatMessage( + role=Role.USER, + message="Summarize this weather result for the user in one sentence: " + "${execute.output.content}" + ), + ], + max_tokens=200, + ) + + wf >> discover >> plan >> execute >> summarize + + run = self._execute_and_assert( + wf, + workflow_input={"task": "Get the current weather in San Francisco", "city": "San Francisco"}, + ) + + # Verify each step completed + discover_out = self._get_task_output(run, "discover_tools") + self.assertIn("tools", discover_out) + print(f" Step 1 - Discovered {len(discover_out['tools'])} tools") + + plan_out = self._get_task_output(run, "plan") + self.assertIn("result", plan_out) + print(f" Step 2 - Plan: {str(plan_out['result'])[:150]}") + + execute_out = self._get_task_output(run, "execute") + self.assertIn("content", execute_out) + print(f" Step 3 - Weather: {execute_out['content'][0].get('text', '')[:150]}") + + summarize_out = self._get_task_output(run, "summarize") + self.assertIn("result", summarize_out) + print(f" Step 4 - Summary: {summarize_out['result'][:150]}") + + # ─── Example: LLM with tool calling ────────────────────────────────── + + def test_09_chat_with_tool_definitions(self): + """README Example - LLM Chat Complete with tool definitions (function calling).""" + wf = ConductorWorkflow( + executor=self.executor, + name=f"{WORKFLOW_PREFIX}chat_tools", + version=1, + ) + + weather_tool = ToolSpec( + name="get_current_weather", + type="MCP_TOOL", + description="Get current weather for a city", + config_params={"mcpServer": MCP_SERVER}, + input_schema={ + "type": "object", + "properties": { + "city": { + "type": "string", + "description": "City name in English", + } + }, + "required": ["city"], + }, + ) + + chat = LlmChatComplete( + task_ref_name="chat", + llm_provider="openai", + model=OPENAI_CHAT_MODEL, + messages=[ + ChatMessage( + role=Role.SYSTEM, + message="You are a helpful assistant with access to weather tools.", + ), + ChatMessage( + role=Role.USER, + message="What is the weather like in Tokyo right now?", + ), + ], + tools=[weather_tool], + temperature=0.1, + max_tokens=500, + ) + wf >> chat + + run = self._execute_and_assert(wf) + output = self._get_task_output(run, "chat") + + # The LLM may either call the tool (TOOL_CALLS) or respond directly + finish_reason = output.get("finishReason", "") + result = output.get("result", "") + tool_calls = output.get("toolCalls", []) + + print(f" Finish reason: {finish_reason}") + if tool_calls: + print(f" Tool calls: {json.dumps(tool_calls, indent=2)[:300]}") + if result: + print(f" Result: {str(result)[:200]}") + + # Either the LLM called the tool or gave a direct response - both are valid + self.assertTrue( + finish_reason in ("STOP", "TOOL_CALLS", "stop", "tool_calls", "end_turn") or result, + f"Expected valid finish reason or result, got finishReason={finish_reason}, result={result}" + ) + + # ─── Multi-provider comparison ─────────────────────────────────────── + + def test_10_multi_provider_comparison(self): + """Bonus: Same question to both OpenAI and Anthropic, compare responses.""" + wf = ConductorWorkflow( + executor=self.executor, + name=f"{WORKFLOW_PREFIX}multi_provider", + version=1, + ) + + openai_chat = LlmChatComplete( + task_ref_name="openai_answer", + llm_provider="openai", + model=OPENAI_CHAT_MODEL, + messages=[ + ChatMessage(role=Role.USER, message="In one sentence, what is workflow orchestration?"), + ], + max_tokens=100, + ) + + anthropic_chat = LlmChatComplete( + task_ref_name="anthropic_answer", + llm_provider="anthropic", + model=ANTHROPIC_CHAT_MODEL, + messages=[ + ChatMessage(role=Role.USER, message="In one sentence, what is workflow orchestration?"), + ], + max_tokens=100, + ) + + wf >> openai_chat >> anthropic_chat + + run = self._execute_and_assert(wf) + + openai_out = self._get_task_output(run, "openai_answer") + anthropic_out = self._get_task_output(run, "anthropic_answer") + + self.assertIn("result", openai_out) + self.assertIn("result", anthropic_out) + + print(f" OpenAI: {openai_out['result'][:150]}") + print(f" Anthropic: {anthropic_out['result'][:150]}") + + +if __name__ == "__main__": + unittest.main(verbosity=2) diff --git a/tests/integration/test_ai_task_types.py b/tests/integration/test_ai_task_types.py new file mode 100644 index 000000000..d03e13b2b --- /dev/null +++ b/tests/integration/test_ai_task_types.py @@ -0,0 +1,436 @@ +""" +Integration test: Register workflows with all 13 AI task types against the Conductor server. + +This test creates a workflow for each AI/LLM task type, registers it on the server, +then retrieves the workflow definition back to verify correct serialization. +Finally, it cleans up by deleting all test workflows. + +Requires a running Conductor server at localhost:7001. +""" + +import json +import sys +import unittest + +from conductor.client.configuration.configuration import Configuration +from conductor.client.orkes_clients import OrkesClients +from conductor.client.workflow.conductor_workflow import ConductorWorkflow +from conductor.client.workflow.executor.workflow_executor import WorkflowExecutor + +# Import all AI task types +from conductor.client.workflow.task.llm_tasks import ( + ChatMessage, + Role, + ToolSpec, + ToolCall, + LlmChatComplete, + LlmTextComplete, + LlmGenerateEmbeddings, + LlmQueryEmbeddings, + LlmIndexText, + LlmIndexDocument, + LlmSearchIndex, + GenerateImage, + GenerateAudio, + LlmStoreEmbeddings, + LlmSearchEmbeddings, + ListMcpTools, + CallMcpTool, +) +from conductor.client.workflow.task.llm_tasks.utils.embedding_model import EmbeddingModel +from conductor.client.workflow.task.task_type import TaskType + +# Also verify backward-compatible import path +from conductor.client.workflow.task.llm_tasks.llm_chat_complete import ChatMessage as ChatMessageBC + + +WORKFLOW_PREFIX = "test_ai_task_type_" + + +class TestAITaskTypeRegistration(unittest.TestCase): + """Test that all 13 AI task types can be registered as workflows on the server.""" + + @classmethod + def setUpClass(cls): + cls.config = Configuration(server_api_url="http://localhost:7001/api") + cls.clients = OrkesClients(configuration=cls.config) + cls.executor = WorkflowExecutor(configuration=cls.config) + cls.metadata_client = cls.clients.get_metadata_client() + cls.registered_workflows = [] + + @classmethod + def tearDownClass(cls): + """Clean up all test workflows.""" + for wf_name in cls.registered_workflows: + try: + cls.metadata_client.unregister_workflow_def(wf_name, 1) + except Exception: + pass + + def _register_and_verify(self, workflow: ConductorWorkflow, expected_task_type: str): + """Register a workflow and verify it was stored correctly.""" + wf_name = workflow.name + self.registered_workflows.append(wf_name) + + # Register + workflow.register(overwrite=True) + + # Retrieve and verify + wf_def = self.metadata_client.get_workflow_def(wf_name, version=1) + self.assertIsNotNone(wf_def, f"Workflow {wf_name} not found after registration") + + # Check the task type in the first task + tasks = wf_def.tasks + self.assertGreater(len(tasks), 0, f"Workflow {wf_name} has no tasks") + actual_type = tasks[0].type + self.assertEqual( + actual_type, + expected_task_type, + f"Task type mismatch for {wf_name}: expected {expected_task_type}, got {actual_type}", + ) + return wf_def + + # ─── 1. LLM_CHAT_COMPLETE ─────────────────────────────────────────── + + def test_01_llm_chat_complete_basic(self): + """Register a workflow with LlmChatComplete task.""" + wf = ConductorWorkflow(executor=self.executor, name=f"{WORKFLOW_PREFIX}chat_complete_basic", version=1) + task = LlmChatComplete( + task_ref_name="chat_ref", + llm_provider="openai", + model="gpt-4", + instructions_template="You are a helpful assistant.", + ) + wf >> task + wf_def = self._register_and_verify(wf, "LLM_CHAT_COMPLETE") + input_params = wf_def.tasks[0].input_parameters + self.assertEqual(input_params["llmProvider"], "openai") + self.assertEqual(input_params["model"], "gpt-4") + + def test_02_llm_chat_complete_with_tools(self): + """Register LlmChatComplete with tools, messages, and new params.""" + tool = ToolSpec( + name="get_weather", + type="SIMPLE", + description="Get weather for a location", + input_schema={"type": "object", "properties": {"location": {"type": "string"}}}, + ) + msg = ChatMessage(role=Role.USER, message="What's the weather in NYC?") + wf = ConductorWorkflow(executor=self.executor, name=f"{WORKFLOW_PREFIX}chat_complete_tools", version=1) + task = LlmChatComplete( + task_ref_name="chat_tools_ref", + llm_provider="openai", + model="gpt-4", + messages=[msg], + tools=[tool], + json_output=True, + thinking_token_limit=1024, + reasoning_effort="medium", + top_k=5, + frequency_penalty=0.5, + presence_penalty=0.3, + max_results=10, + ) + wf >> task + wf_def = self._register_and_verify(wf, "LLM_CHAT_COMPLETE") + input_params = wf_def.tasks[0].input_parameters + self.assertTrue(input_params.get("jsonOutput")) + self.assertEqual(input_params.get("thinkingTokenLimit"), 1024) + self.assertEqual(input_params.get("reasoningEffort"), "medium") + self.assertIsInstance(input_params.get("tools"), list) + self.assertEqual(len(input_params["tools"]), 1) + + # ─── 2. LLM_TEXT_COMPLETE ──────────────────────────────────────────── + + def test_03_llm_text_complete(self): + """Register a workflow with LlmTextComplete task.""" + wf = ConductorWorkflow(executor=self.executor, name=f"{WORKFLOW_PREFIX}text_complete", version=1) + task = LlmTextComplete( + task_ref_name="text_ref", + llm_provider="openai", + model="gpt-3.5-turbo", + prompt_name="summarize", + max_tokens=500, + temperature=0.7, + top_k=10, + frequency_penalty=0.2, + presence_penalty=0.1, + json_output=True, + ) + wf >> task + wf_def = self._register_and_verify(wf, "LLM_TEXT_COMPLETE") + input_params = wf_def.tasks[0].input_parameters + self.assertEqual(input_params["promptName"], "summarize") + self.assertEqual(input_params.get("topK"), 10) + self.assertTrue(input_params.get("jsonOutput")) + + # ─── 3. LLM_GENERATE_EMBEDDINGS ───────────────────────────────────── + + def test_04_llm_generate_embeddings(self): + """Register a workflow with LlmGenerateEmbeddings task.""" + wf = ConductorWorkflow(executor=self.executor, name=f"{WORKFLOW_PREFIX}generate_embeddings", version=1) + task = LlmGenerateEmbeddings( + task_ref_name="gen_embed_ref", + llm_provider="openai", + model="text-embedding-ada-002", + text="Hello world", + dimensions=1536, + ) + wf >> task + wf_def = self._register_and_verify(wf, "LLM_GENERATE_EMBEDDINGS") + input_params = wf_def.tasks[0].input_parameters + self.assertEqual(input_params["dimensions"], 1536) + + # ─── 4. LLM_GET_EMBEDDINGS (LlmQueryEmbeddings) ───────────────────── + + def test_05_llm_query_embeddings(self): + """Register a workflow with LlmQueryEmbeddings task.""" + wf = ConductorWorkflow(executor=self.executor, name=f"{WORKFLOW_PREFIX}query_embeddings", version=1) + task = LlmQueryEmbeddings( + task_ref_name="query_embed_ref", + vector_db="pineconedb", + index="my-index", + embeddings=[0.1, 0.2, 0.3], + namespace="test-ns", + ) + wf >> task + wf_def = self._register_and_verify(wf, "LLM_GET_EMBEDDINGS") + input_params = wf_def.tasks[0].input_parameters + self.assertEqual(input_params["vectorDB"], "pineconedb") + self.assertEqual(input_params["namespace"], "test-ns") + + # ─── 5. LLM_INDEX_TEXT ─────────────────────────────────────────────── + + def test_06_llm_index_text(self): + """Register a workflow with LlmIndexText task.""" + wf = ConductorWorkflow(executor=self.executor, name=f"{WORKFLOW_PREFIX}index_text", version=1) + task = LlmIndexText( + task_ref_name="index_text_ref", + vector_db="pineconedb", + index="my-index", + embedding_model=EmbeddingModel(provider="openai", model="text-embedding-ada-002"), + text="Sample text to index", + doc_id="doc-001", + namespace="test-ns", + chunk_size=1000, + chunk_overlap=200, + dimensions=1536, + url="https://example.com/doc.txt", + ) + wf >> task + wf_def = self._register_and_verify(wf, "LLM_INDEX_TEXT") + input_params = wf_def.tasks[0].input_parameters + self.assertEqual(input_params["chunkSize"], 1000) + self.assertEqual(input_params["dimensions"], 1536) + self.assertEqual(input_params["url"], "https://example.com/doc.txt") + + # ─── 6. LLM_INDEX_DOCUMENT (uses LLM_INDEX_TEXT on server) ────────── + + def test_07_llm_index_document(self): + """Register a workflow with LlmIndexDocument task (maps to LLM_INDEX_TEXT).""" + wf = ConductorWorkflow(executor=self.executor, name=f"{WORKFLOW_PREFIX}index_document", version=1) + task = LlmIndexDocument( + task_ref_name="index_doc_ref", + vector_db="pineconedb", + namespace="test-ns", + embedding_model=EmbeddingModel(provider="openai", model="text-embedding-ada-002"), + index="my-index", + url="https://example.com/doc.pdf", + media_type="application/pdf", + dimensions=1536, + ) + wf >> task + wf_def = self._register_and_verify(wf, "LLM_INDEX_TEXT") + input_params = wf_def.tasks[0].input_parameters + self.assertEqual(input_params["dimensions"], 1536) + self.assertEqual(input_params["url"], "https://example.com/doc.pdf") + self.assertEqual(input_params["mediaType"], "application/pdf") + + # ─── 7. LLM_SEARCH_INDEX ──────────────────────────────────────────── + + def test_08_llm_search_index(self): + """Register a workflow with LlmSearchIndex task.""" + wf = ConductorWorkflow(executor=self.executor, name=f"{WORKFLOW_PREFIX}search_index", version=1) + task = LlmSearchIndex( + task_ref_name="search_idx_ref", + vector_db="pineconedb", + namespace="test-ns", + index="my-index", + embedding_model_provider="openai", + embedding_model="text-embedding-ada-002", + query="find related documents", + max_results=5, + dimensions=1536, + ) + wf >> task + wf_def = self._register_and_verify(wf, "LLM_SEARCH_INDEX") + input_params = wf_def.tasks[0].input_parameters + self.assertEqual(input_params["dimensions"], 1536) + self.assertEqual(input_params["maxResults"], 5) + + # ─── 8. GENERATE_IMAGE ────────────────────────────────────────────── + + def test_09_generate_image(self): + """Register a workflow with GenerateImage task.""" + wf = ConductorWorkflow(executor=self.executor, name=f"{WORKFLOW_PREFIX}generate_image", version=1) + task = GenerateImage( + task_ref_name="gen_img_ref", + llm_provider="openai", + model="dall-e-3", + prompt="A sunset over mountains", + width=1024, + height=1024, + style="vivid", + n=1, + output_format="png", + ) + wf >> task + wf_def = self._register_and_verify(wf, "GENERATE_IMAGE") + input_params = wf_def.tasks[0].input_parameters + self.assertEqual(input_params["llmProvider"], "openai") + self.assertEqual(input_params["prompt"], "A sunset over mountains") + self.assertEqual(input_params["style"], "vivid") + + # ─── 9. GENERATE_AUDIO ────────────────────────────────────────────── + + def test_10_generate_audio(self): + """Register a workflow with GenerateAudio task.""" + wf = ConductorWorkflow(executor=self.executor, name=f"{WORKFLOW_PREFIX}generate_audio", version=1) + task = GenerateAudio( + task_ref_name="gen_audio_ref", + llm_provider="openai", + model="tts-1", + text="Hello, this is a test.", + voice="alloy", + speed=1.0, + response_format="mp3", + ) + wf >> task + wf_def = self._register_and_verify(wf, "GENERATE_AUDIO") + input_params = wf_def.tasks[0].input_parameters + self.assertEqual(input_params["text"], "Hello, this is a test.") + self.assertEqual(input_params["voice"], "alloy") + self.assertEqual(input_params["responseFormat"], "mp3") + + # ─── 10. LLM_STORE_EMBEDDINGS ──────────────────────────────────────── + + def test_11_llm_store_embeddings(self): + """Register a workflow with LlmStoreEmbeddings task.""" + wf = ConductorWorkflow(executor=self.executor, name=f"{WORKFLOW_PREFIX}store_embeddings", version=1) + task = LlmStoreEmbeddings( + task_ref_name="store_embed_ref", + vector_db="pineconedb", + index="my-index", + embeddings=[0.1, 0.2, 0.3, 0.4], + namespace="test-ns", + id="doc-123", + metadata={"source": "test"}, + embedding_model="text-embedding-ada-002", + embedding_model_provider="openai", + ) + wf >> task + wf_def = self._register_and_verify(wf, "LLM_STORE_EMBEDDINGS") + input_params = wf_def.tasks[0].input_parameters + self.assertEqual(input_params["vectorDB"], "pineconedb") + self.assertEqual(input_params["id"], "doc-123") + self.assertEqual(input_params["embeddingModel"], "text-embedding-ada-002") + + # ─── 11. LLM_SEARCH_EMBEDDINGS ─────────────────────────────────────── + + def test_12_llm_search_embeddings(self): + """Register a workflow with LlmSearchEmbeddings task.""" + wf = ConductorWorkflow(executor=self.executor, name=f"{WORKFLOW_PREFIX}search_embeddings", version=1) + task = LlmSearchEmbeddings( + task_ref_name="search_embed_ref", + vector_db="pineconedb", + index="my-index", + embeddings=[0.1, 0.2, 0.3], + namespace="test-ns", + max_results=10, + dimensions=1536, + embedding_model="text-embedding-ada-002", + embedding_model_provider="openai", + ) + wf >> task + wf_def = self._register_and_verify(wf, "LLM_SEARCH_EMBEDDINGS") + input_params = wf_def.tasks[0].input_parameters + self.assertEqual(input_params["maxResults"], 10) + self.assertEqual(input_params["dimensions"], 1536) + + # ─── 12. LIST_MCP_TOOLS ───────────────────────────────────────────── + + def test_13_list_mcp_tools(self): + """Register a workflow with ListMcpTools task.""" + wf = ConductorWorkflow(executor=self.executor, name=f"{WORKFLOW_PREFIX}list_mcp_tools", version=1) + task = ListMcpTools( + task_ref_name="list_mcp_ref", + mcp_server="http://localhost:3000/sse", + headers={"Authorization": "Bearer test-token"}, + ) + wf >> task + wf_def = self._register_and_verify(wf, "LIST_MCP_TOOLS") + input_params = wf_def.tasks[0].input_parameters + self.assertEqual(input_params["mcpServer"], "http://localhost:3000/sse") + + # ─── 13. CALL_MCP_TOOL ────────────────────────────────────────────── + + def test_14_call_mcp_tool(self): + """Register a workflow with CallMcpTool task.""" + wf = ConductorWorkflow(executor=self.executor, name=f"{WORKFLOW_PREFIX}call_mcp_tool", version=1) + task = CallMcpTool( + task_ref_name="call_mcp_ref", + mcp_server="http://localhost:3000/sse", + method="get_weather", + arguments={"location": "New York"}, + headers={"Authorization": "Bearer test-token"}, + ) + wf >> task + wf_def = self._register_and_verify(wf, "CALL_MCP_TOOL") + input_params = wf_def.tasks[0].input_parameters + self.assertEqual(input_params["method"], "get_weather") + self.assertEqual(input_params["arguments"]["location"], "New York") + + # ─── Backward compatibility ────────────────────────────────────────── + + def test_15_backward_compat_chat_message_import(self): + """Verify ChatMessage can be imported from the old location.""" + self.assertIs(ChatMessageBC, ChatMessage) + + # ─── Model serialization ──────────────────────────────────────────── + + def test_16_chat_message_to_dict(self): + """Verify ChatMessage serializes correctly.""" + msg = ChatMessage(role=Role.USER, message="Hello") + d = msg.to_dict() + self.assertEqual(d["role"], "user") + self.assertEqual(d["message"], "Hello") + + def test_17_tool_spec_to_dict(self): + """Verify ToolSpec serializes correctly.""" + spec = ToolSpec( + name="search", + type="SIMPLE", + description="Search the web", + input_schema={"type": "object"}, + ) + d = spec.to_dict() + self.assertEqual(d["name"], "search") + self.assertEqual(d["type"], "SIMPLE") + self.assertEqual(d["inputSchema"], {"type": "object"}) + + def test_18_tool_call_to_dict(self): + """Verify ToolCall serializes correctly.""" + tc = ToolCall( + task_reference_name="call_ref", + name="search", + type="SIMPLE", + input_parameters={"query": "test"}, + ) + d = tc.to_dict() + self.assertEqual(d["taskReferenceName"], "call_ref") + self.assertEqual(d["name"], "search") + self.assertEqual(d["inputParameters"], {"query": "test"}) + + +if __name__ == "__main__": + unittest.main(verbosity=2)