trustgraph/docs/apis/api-flow.md

TrustGraph Flow API

This API provides workflow management for TrustGraph components. It manages flow classes (workflow templates) and flow instances (active running workflows) that orchestrate complex data processing pipelines.

Request/response

Request

The request contains the following fields:

• operation: The operation to perform (see operations below)
• class_name: Flow class name (for class operations and start-flow)
• class_definition: Flow class definition JSON (for put-class)
• description: Flow description (for start-flow)
• flow_id: Flow instance ID (for flow instance operations)

Response

The response contains the following fields:

• class_names: Array of flow class names (returned by list-classes)
• flow_ids: Array of active flow IDs (returned by list-flows)
• class_definition: Flow class definition JSON (returned by get-class)
• flow: Flow instance JSON (returned by get-flow)
• description: Flow description (returned by get-flow)
• error: Error information if operation fails

Operations

Flow Class Operations

LIST-CLASSES - List All Flow Classes

Request:

{
    "operation": "list-classes"
}

Response:

{
    "class_names": ["pdf-processor", "text-analyzer", "knowledge-extractor"]
}

GET-CLASS - Get Flow Class Definition

Request:

{
    "operation": "get-class",
    "class_name": "pdf-processor"
}

Response:

{
    "class_definition": "{\"interfaces\": {\"text-completion\": {\"request\": \"persistent://tg/request/text-completion\", \"response\": \"persistent://tg/response/text-completion\"}}, \"description\": \"PDF processing workflow\"}"
}

PUT-CLASS - Create/Update Flow Class

Request:

{
    "operation": "put-class",
    "class_name": "pdf-processor",
    "class_definition": "{\"interfaces\": {\"text-completion\": {\"request\": \"persistent://tg/request/text-completion\", \"response\": \"persistent://tg/response/text-completion\"}}, \"description\": \"PDF processing workflow\"}"
}

Response:

{}

DELETE-CLASS - Remove Flow Class

Request:

{
    "operation": "delete-class",
    "class_name": "pdf-processor"
}

Response:

{}

Flow Instance Operations

LIST-FLOWS - List Active Flow Instances

Request:

{
    "operation": "list-flows"
}

Response:

{
    "flow_ids": ["flow-123", "flow-456", "flow-789"]
}

GET-FLOW - Get Flow Instance

Request:

{
    "operation": "get-flow",
    "flow_id": "flow-123"
}

Response:

{
    "flow": "{\"interfaces\": {\"text-completion\": {\"request\": \"persistent://tg/request/text-completion-flow-123\", \"response\": \"persistent://tg/response/text-completion-flow-123\"}}}",
    "description": "PDF processing workflow instance"
}

START-FLOW - Start Flow Instance

Request:

{
    "operation": "start-flow",
    "class_name": "pdf-processor",
    "flow_id": "flow-123",
    "description": "Processing document batch 1"
}

Response:

{}

STOP-FLOW - Stop Flow Instance

Request:

{
    "operation": "stop-flow",
    "flow_id": "flow-123"
}

Response:

{}

REST service

The REST service is available at /api/v1/flow and accepts the above request formats.

Websocket

Requests have a request object containing the operation fields. Responses have a response object containing the response fields.

Request:

{
    "id": "unique-request-id",
    "service": "flow",
    "request": {
        "operation": "list-classes"
    }
}

Response:

{
    "id": "unique-request-id",
    "response": {
        "class_names": ["pdf-processor", "text-analyzer"]
    },
    "complete": true
}

Pulsar

The Pulsar schema for the Flow API is defined in Python code here:

https://github.com/trustgraph-ai/trustgraph/blob/master/trustgraph-base/trustgraph/schema/flows.py

Default request queue: non-persistent://tg/request/flow

Default response queue: non-persistent://tg/response/flow

Request schema: trustgraph.schema.FlowRequest

Response schema: trustgraph.schema.FlowResponse

Flow Service Methods

Flow instances provide access to various TrustGraph services through flow-specific endpoints:

MCP Tool Service - Invoke MCP Tools

The mcp_tool method allows invoking MCP (Model Control Protocol) tools within a flow context.

Request:

{
    "name": "file-reader",
    "parameters": {
        "path": "/path/to/file.txt"
    }
}

Response:

{
    "object": {"content": "file contents here", "size": 1024}
}

Or for text responses:

{
    "text": "plain text response"
}

Other Service Methods

Flow instances also provide access to:

• text_completion - LLM text completion
• agent - Agent question answering
• graph_rag - Graph-based RAG queries
• document_rag - Document-based RAG queries
• embeddings - Text embeddings
• prompt - Prompt template processing
• triples_query - Knowledge graph queries
• load_document - Document loading
• load_text - Text loading

Python SDK

The Python SDK provides convenient access to the Flow API:

from trustgraph.api.flow import FlowClient

client = FlowClient()

# List all flow classes
classes = await client.list_classes()

# Get a flow class definition
definition = await client.get_class("pdf-processor")

# Start a flow instance
await client.start_flow("pdf-processor", "flow-123", "Processing batch 1")

# List active flows
flows = await client.list_flows()

# Stop a flow instance
await client.stop_flow("flow-123")

# Use flow instance services
flow = client.id("flow-123")
result = await flow.mcp_tool("file-reader", {"path": "/path/to/file.txt"})

Features

• Flow Classes: Templates that define workflow structure and interfaces
• Flow Instances: Active running workflows based on flow classes
• Dynamic Management: Flows can be started/stopped dynamically
• Template Processing: Uses template replacement for customizing flow instances
• Integration: Works with TrustGraph ecosystem for data processing pipelines
• Persistent Storage: Flow definitions and instances stored for reliability

Use Cases

• Document Processing: Orchestrating PDF processing through chunking, extraction, and storage
• Knowledge Extraction: Managing workflows for relationship and definition extraction
• Data Pipelines: Coordinating complex multi-step data processing workflows
• Resource Management: Dynamically scaling processing flows based on demand