No abstractions. No black boxes. Just Your Logic

Orkes is a Python library for building, coordinating, and observing any complex workflow that can be represented as a graph. While it is well-suited for building LLM-powered agentic systems, its core focus is on providing a flexible and intuitive graph-based framework with an emphasis on explicit control flow, transparent logic, and comprehensive traceability.

Getting Started

You can install the latest stable version of the Orkes using pip:

pip install orkes

Here's a simple example of how to build and run a graph with Orkes:

from orkes.graph.core import OrkesGraph
from typing import TypedDict, List

# 1. Define a simpler state
class SearchState(TypedDict):
    user_query: str
    search_queries: List[str]
    current_index: int
    raw_results: List[str]
    is_finished: bool
    final_answer: str

# --- Node 1: Planner (Mocked) ---
def planner_node(state: SearchState):
    """Instead of an LLM, we split the query into mock keywords."""
    print(f"📖 Planning for: {state['user_query']}")
    
    # Simple logic: split words as fake 'queries'
    state['search_queries'] = [f"Search for {word}" for word in state['user_query'].split()[:3]]
    state['current_index'] = 0
    state['raw_results'] = []
    return state

# --- Node 2: Execution (Mocked) ---
def execute_search_node(state: SearchState):
    idx = state['current_index']
    query = state['search_queries'][idx]
    
    print(f"📡 Executing Step {idx + 1}: {query}")
    state['raw_results'].append(f"Result for '{query}'")
    
    state['current_index'] += 1
    state['is_finished'] = state['current_index'] >= len(state['search_queries'])
    return state

# --- Node 3: Synthesis (Mocked) ---
def synthesis_node(state: SearchState):
    """Combines results into a simple string."""
    state['final_answer'] = "Combined Results: " + " | ".join(state['raw_results'])
    print(f"✨ Process Complete: {state['final_answer']}")
    return state

# --- Router Logic ---
def check_loop_condition(state: SearchState):
    return 'complete' if state.get('is_finished') else 'loop'

# --- Build the Graph ---
graph = OrkesGraph(SearchState)

graph.add_node('planner', planner_node)
graph.add_node('search_step', execute_search_node)
graph.add_node('synthesizer', synthesis_node)

graph.add_edge(graph.START, 'planner')
graph.add_edge('planner', 'search_step')

# Conditional Loop
graph.add_conditional_edge(
    'search_step',
    check_loop_condition,
    {
        'loop': 'search_step',   # Go back to search if not finished
        'complete': 'synthesizer' # Go to finish if done
    }
)

graph.add_edge('synthesizer', graph.END)

# --- Execute ---
runner = graph.compile()
initial_state: SearchState = {
    "user_query": "Orkes Conductor vs Temporal",
    "search_queries": [],
    "current_index": 0,
    "raw_results": [],
    "is_finished": False,
    "final_answer": ""
}

runner.run(initial_state)
runner.visualize_trace()

Here is an example how the orkes graph visualization will look like:

Core Concepts

At the heart of Orkes is a powerful graph-based architecture inspired by NetworkX. This design allows you to define your workflows as a graph of nodes and edges, where each node is a simple Python function.

• OrkesGraph: The main canvas for your workflow. It holds the nodes and edges that define your application's logic.
• Stateful Execution: A shared state object is passed between nodes, allowing for seamless data flow and management throughout the graph's execution.
• Graph Traceability: Orkes provides a built-in traceability and visualization system. When you run a graph, Orkes can generate a detailed execution trace that can be visualized as an interactive HTML file, making it easy to debug and understand your workflows.

Features

• Graph-based Architecture: Define complex workflows as a graph of nodes and edges, with support for conditional branching and loops.
• Traceability and Visualization: Generate interactive traces of your graph executions to visualize the flow of data and control.
• Pluggable LLM Integrations: A flexible and extensible system for integrating with LLMs, with out-of-the-box support for OpenAI, Anthropic's Claude, and Google's Gemini.
• Agent and Tool Support: Define custom tools and use them within your graph's nodes to interact with external APIs and services.
• Familiar Interface: The graph-based interface is inspired by NetworkX, providing a familiar and powerful paradigm for those with experience in graph-based programming.

Roadmap

Feature	Description	Status
Boilerplate Agent	Provide a well-structured boilerplate for creating new agents to accelerate the development of agentic systems.	Planned
Parallel Graph Execution	Enhance the graph runner to support parallel execution of independent branches for improved performance.	Planned
Tracer Web Platform	Develop a standalone web-based platform for visualizing and inspecting graph traces in real-time.	Planned

Documentation

For more details, visit our Documentation Page.

Contributing

Contributions are welcome! Please see the Contributing Guide for more information.

License

Orkes is licensed under the MIT License.