notebooks/agents/Orchestrator-Workers Workflow.ipynb

{
 "cells": [
  {
   "metadata": {},
   "cell_type": "markdown",
   "source": [
    "# Orchestrator-Workers Workflow\n",
    "\n",
    "In this notebook, we'll explore the orchestrator-workers pattern — a powerful workflow design for creating flexible AI systems that can tackle complex, unpredictable tasks.\n",
    "Using Kotlin and Claude via LangChain4j,\n",
    "we'll implement a practical example that demonstrates\n",
    "how a main _\"orchestrator\"_ LLM can coordinate multiple _\"worker\"_ LLMs to achieve better results.\n",
    "\n",
    "## What is the orchestrator-workers pattern?\n",
    "\n",
    "The orchestrator-workers pattern involves using a central LLM (the orchestrator) to analyze a complex task,\n",
    "break it down dynamically into subtasks, and then delegate these subtasks to specialized worker LLMs.\n",
    "Finally, the orchestrator synthesizes the results into a cohesive output.\n",
    "\n",
    "![Orchestrator-Workers Workflow Diagram](image/orchestrator_workers.svg)\n",
    "\n",
    "This workflow differs from simple parallelization because:\n",
    "- The subtasks aren't predetermined but are identified dynamically by the orchestrator\n",
    "- The orchestrator can make decisions about task allocation based on the specific input\n",
    "- There's an explicit coordination layer that manages the overall process\n",
    "\n",
    "### When to use this pattern\n",
    "\n",
    "- Software development tasks that involve changes across multiple files\n",
    "- Complex research or analysis requiring multiple perspectives\n",
    "- Content creation with varying style requirements\n",
    "- Multistep problem-solving with interdependent components\n",
    "\n",
    "## Setting up environment\n",
    "\n",
    "Let's start by configuring the Kotlin notebook with the necessary dependencies:"
   ]
  },
  {
   "metadata": {
    "ExecuteTime": {
     "end_time": "2025-04-04T15:53:26.424151Z",
     "start_time": "2025-04-04T15:53:26.010031Z"
    }
   },
   "cell_type": "code",
   "source": [
    "@file:DependsOn(\"dev.langchain4j:langchain4j:1.0.0-beta2\")\n",
    "@file:DependsOn(\"dev.langchain4j:langchain4j-anthropic:1.0.0-beta2\")"
   ],
   "outputs": [],
   "execution_count": 1
  },
  {
   "metadata": {},
   "cell_type": "markdown",
   "source": [
    "## Defining data models\n",
    "\n",
    "We'll need some data structures to represent tasks and responses:"
   ]
  },
  {
   "metadata": {
    "ExecuteTime": {
     "end_time": "2025-04-04T15:56:39.626195Z",
     "start_time": "2025-04-04T15:56:39.319125Z"
    }
   },
   "cell_type": "code",
   "source": [
    "import com.fasterxml.jackson.annotation.JsonCreator\n",
    "import com.fasterxml.jackson.annotation.JsonProperty\n",
    "\n",
    "/**\n",
    " * Represents a subtask assigned by the orchestrator that needs to be executed by the performer.\n",
    " */\n",
    "data class Task @JsonCreator constructor(\n",
    "    @JsonProperty(\"type\") val type: String,\n",
    "    @JsonProperty(\"description\") val description: String\n",
    ")\n",
    "\n",
    "/**\n",
    " * The orchestra's response, containing a task analysis and breakdown into subtasks.\n",
    " */\n",
    "data class OrchestratorResponse @JsonCreator constructor(\n",
    "    @JsonProperty(\"analysis\") val analysis: String,\n",
    "    @JsonProperty(\"tasks\") val tasks: List<Task>\n",
    ")\n",
    "\n",
    "data class WorkerResponse(val type: String, val description: String, val result: String) {\n",
    "    override fun toString(): String {\n",
    "        return \"\"\"\n",
    "            {\n",
    "              \"type\": \"$type\",\n",
    "              \"description\": \"$description\",\n",
    "              \"result\": \"$result\"\n",
    "            }\n",
    "        \"\"\".trimIndent()\n",
    "    }\n",
    "}"
   ],
   "outputs": [],
   "execution_count": 2
  },
  {
   "metadata": {},
   "cell_type": "markdown",
   "source": [
    "These classes serve as the communication structures between our orchestrator and worker LLMs.\n",
    "\n",
    "## Creating LLM Service\n",
    "\n",
    "Next, define a simple interface for our LLM interactions:"
   ]
  },
  {
   "metadata": {
    "ExecuteTime": {
     "end_time": "2025-04-04T15:57:16.164126Z",
     "start_time": "2025-04-04T15:57:16.119676Z"
    }
   },
   "cell_type": "code",
   "source": [
    "interface LlmService {\n",
    "    fun orchestrate(input: String): OrchestratorResponse\n",
    "    fun perform(input: String): String\n",
    "}"
   ],
   "outputs": [],
   "execution_count": 3
  },
  {
   "metadata": {},
   "cell_type": "markdown",
   "source": [
    "## Implementing the orchestrator\n",
    "\n",
    "Now for the heart of our implementation — the `Orchestrator` class"
   ]
  },
  {
   "metadata": {
    "ExecuteTime": {
     "end_time": "2025-04-04T15:58:01.817129Z",
     "start_time": "2025-04-04T15:58:01.414342Z"
    }
   },
   "cell_type": "code",
   "source": [
    "import kotlinx.serialization.Serializable\n",
    "\n",
    "/**\n",
    " * Break down tasks and run them in parallel using worker LLMs\n",
    " */\n",
    "class Orchestrator(val llm: LlmService) {\n",
    "\n",
    "    companion object {\n",
    "        val orchestratorPrompt: (String) -> String = {\n",
    "            \"\"\"\n",
    "            Analyze this task and break it down into 2-3 distinct approaches:\n",
    "\n",
    "            Task: $it\n",
    "\n",
    "            Return your response in this JSON format:\n",
    "            {\n",
    "              \"analysis\": \"Explain your understanding of the task and which variations would be valuable. Focus on how each approach serves different aspects of the task.\",\n",
    "              \"tasks\": [\n",
    "                {\n",
    "                  \"type\": \"formal\",\n",
    "                  \"description\": \"Write a precise, technical version that emphasizes specifications\"\n",
    "                },\n",
    "                {\n",
    "                  \"type\": \"conversational\",\n",
    "                  \"description\": \"Write an engaging, friendly version that connects with readers\"\n",
    "                }\n",
    "              ]\n",
    "            }\n",
    "            \"\"\".trimIndent()\n",
    "        }\n",
    "\n",
    "        @Serializable\n",
    "        data class Task(val type: String, val description: String)\n",
    "\n",
    "        val workerPrompt: (String, String, String) -> String =\n",
    "            { originalTask, taskType, taskDescription ->\n",
    "                \"\"\"\n",
    "                Generate content based on:\n",
    "                Task: $originalTask\n",
    "                Style: $taskType\n",
    "                Guidelines: $taskDescription\n",
    "                \"\"\".trimIndent()\n",
    "            }\n",
    "    }\n",
    "\n",
    "    /**\n",
    "     * Process task by brealing it down and running subtasks in parallel.\n",
    "     */\n",
    "    fun process(taskInput: String): Pair<String, List<WorkerResponse>> {\n",
    "        val orchestratorInput = orchestratorPrompt(taskInput)\n",
    "        val orchestratorResponse = llm.orchestrate(orchestratorInput)\n",
    "\n",
    "        val (analysis, tasks) = orchestratorResponse\n",
    "\n",
    "        println(\n",
    "            \"\"\"\n",
    "            === ORCHESTRATOR OUTPUT ===\n",
    "            ANALYSIS: ${orchestratorResponse.analysis}\n",
    "\n",
    "            TASKS: ${orchestratorResponse.tasks}\n",
    "            \"\"\".trimIndent()\n",
    "        )\n",
    "\n",
    "        val workerResults = tasks.map { task ->\n",
    "            val workerInput = workerPrompt(taskInput, task.type, task.description)\n",
    "            val workerResponse = llm.perform(workerInput)\n",
    "\n",
    "\n",
    "            println(\n",
    "                \"\"\"\n",
    "                === WORKER RESULT (${task.type}) ===\n",
    "                $workerResponse\n",
    "                \"\"\".trimIndent()\n",
    "            )\n",
    "\n",
    "            WorkerResponse(task.type, task.description, workerResponse)\n",
    "        }\n",
    "\n",
    "        return analysis to workerResults\n",
    "    }\n",
    "}"
   ],
   "outputs": [],
   "execution_count": 4
  },
  {
   "metadata": {},
   "cell_type": "markdown",
   "source": [
    "## Creating LLM Model\n",
    "\n",
    "Let's set up the Claude model:"
   ]
  },
  {
   "metadata": {
    "ExecuteTime": {
     "end_time": "2025-04-04T15:58:41.568310Z",
     "start_time": "2025-04-04T15:58:41.356590Z"
    }
   },
   "cell_type": "code",
   "source": [
    "import dev.langchain4j.model.anthropic.AnthropicChatModel\n",
    "import dev.langchain4j.model.anthropic.AnthropicChatModelName\n",
    "\n",
    "val model = AnthropicChatModel.builder()\n",
    "    .apiKey(System.getenv(\"ANTHROPIC_API_KEY\"))\n",
    "    .modelName(AnthropicChatModelName.CLAUDE_3_7_SONNET_20250219)\n",
    "    .maxTokens(4096)\n",
    "    .temperature(0.1)\n",
    "    .build()"
   ],
   "outputs": [],
   "execution_count": 5
  },
  {
   "metadata": {},
   "cell_type": "markdown",
   "source": [
    "## Running the workflow\n",
    "\n",
    "Finally,create the llm service and process a task"
   ]
  },
  {
   "metadata": {
    "ExecuteTime": {
     "end_time": "2025-04-04T16:00:02.983219Z",
     "start_time": "2025-04-04T15:59:21.693441Z"
    }
   },
   "cell_type": "code",
   "source": [
    "import dev.langchain4j.service.AiServices\n",
    "\n",
    "val service = AiServices.create(LlmService::class.java, model)\n",
    "\n",
    "val orchestrator = Orchestrator(service)\n",
    "val result = orchestrator.process(\"Write a product description for a new eco-friendly water bottle\")"
   ],
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "=== ORCHESTRATOR OUTPUT ===\n",
      "ANALYSIS: This task requires creating a product description for an eco-friendly water bottle. The key challenge is effectively communicating both the functional benefits (durability, capacity, materials) and emotional benefits (environmental impact, lifestyle alignment) of the product. Different approaches would be valuable to address various customer segments and marketing contexts. Some customers may prioritize technical specifications and environmental credentials, while others might respond better to lifestyle benefits and emotional appeals. The marketing context could range from e-commerce listings to social media content.\n",
      "\n",
      "TASKS: [Task(type=technical-environmental, description=Create a specification-focused description highlighting the bottle's eco-friendly materials, manufacturing process, and technical features with precise measurements and environmental impact statistics), Task(type=lifestyle-benefits, description=Develop a benefits-oriented description emphasizing how the bottle enhances the user's daily life while supporting their environmental values, using vivid imagery and emotional appeals), Task(type=comparative-educational, description=Craft an educational description that contrasts the eco-bottle with conventional alternatives, explaining environmental problems it solves while educating consumers about sustainable choices)]\n",
      "                === WORKER RESULT (technical-environmental) ===\n",
      "                # AQUA-SUSTAIN PRO: Advanced Eco-Conscious Hydration System\n",
      "\n",
      "## Technical Specifications\n",
      "\n",
      "The AQUA-SUSTAIN PRO represents the culmination of sustainable engineering in personal hydration technology. This 750ml capacity vessel is precision-crafted from 18/8 food-grade 304 stainless steel (ASTM A240 compliant) with walls measuring 1.2mm in thickness, ensuring optimal structural integrity while minimizing material usage by 17% compared to conventional alternatives.\n",
      "\n",
      "## Material Composition & Environmental Impact\n",
      "\n",
      "* **Primary Construction**: 100% recyclable 304-grade stainless steel (0% BPA, phthalates, or leaching compounds)\n",
      "* **Insulation Matrix**: Vacuum-sealed double-wall construction utilizing zero CFC/HCFC compounds\n",
      "* **Exterior Coating**: Water-based, low-VOC (< 5g/L) finish applied via electrostatic process, reducing overspray waste by 94%\n",
      "* **Carbon Footprint**: 78% lower lifecycle emissions (4.2kg CO₂e) versus single-use plastic bottles over 3-year usage period\n",
      "* **End-of-Life Recovery**: 97.3% of components recoverable through standard municipal recycling programs\n",
      "\n",
      "## Manufacturing Protocol\n",
      "\n",
      "The AQUA-SUSTAIN PRO is manufactured utilizing our proprietary Low-Impact Production System (LIPS), which reduces water consumption by 76% compared to industry standards. Our facility operates on 100% renewable energy, with 87% sourced from on-site solar arrays generating 1.2MW daily. The manufacturing process employs precision hydroforming techniques that eliminate 94% of material waste typically associated with traditional deep-drawing methods.\n",
      "\n",
      "## Thermal Performance Metrics\n",
      "\n",
      "* **Heat Retention**: Maintains liquid temperature within ±1.5°C of original for 12 hours (hot) and 24 hours (cold) in ambient conditions (23°C)\n",
      "* **Condensation Coefficient**: Zero external moisture accumulation in humidity conditions up to 85% RH\n",
      "* **Thermal Transfer Rating**: 0.17 W/m²K, exceeding industry standards by 42%\n",
      "\n",
      "## Environmental Certification\n",
      "\n",
      "* ISO 14001:2015 Environmental Management System Certified\n",
      "* Cradle to Cradle Certified™ (Gold Level)\n",
      "* Carbon Trust Standard\n",
      "* Global Recycled Standard (GRS) Certified\n",
      "\n",
      "By selecting the AQUA-SUSTAIN PRO, users prevent approximately 167 single-use plastic bottles from entering waste streams annually, equivalent to a 73.5kg reduction in plastic pollution per user per year.\n",
      "                === WORKER RESULT (lifestyle-benefits) ===\n",
      "                # Stay Hydrated, Stay Conscious: The EcoFlow Water Bottle\n",
      "\n",
      "Imagine starting your day knowing that every sip you take isn't just nourishing your body, but also nurturing the planet. The EcoFlow isn't just a water bottle—it's your daily companion in living a life aligned with your values.\n",
      "\n",
      "## Seamlessly Fits Into Your World\n",
      "\n",
      "Slip the sleek EcoFlow into your gym bag, briefcase, or bicycle holder and experience hydration without compromise. Its lightweight yet durable design means you'll never have to choose between convenience and consciousness again. The leak-proof seal ensures your belongings stay dry while you move through your busy day with confidence.\n",
      "\n",
      "## Elevate Your Hydration Experience\n",
      "\n",
      "Feel the difference as you drink from a bottle crafted from premium, toxin-free materials. The EcoFlow's temperature-retention technology keeps your morning tea soothingly warm during your commute and your afternoon water refreshingly cool during your workout. The ergonomic mouthpiece delivers a smooth flow with every sip, transforming hydration from a necessity into a pleasure.\n",
      "\n",
      "## A Statement of Your Values\n",
      "\n",
      "Each time you refill your EcoFlow, you're making a powerful declaration. You're saying no to the estimated 1,500 plastic bottles the average American uses annually. You're choosing to be part of the solution. Watch as colleagues and friends take notice of your thoughtful choice—perhaps inspiring their own journey toward more sustainable living.\n",
      "\n",
      "## Created With Care, Designed for Impact\n",
      "\n",
      "Made from 100% recycled materials and completely BPA-free, your EcoFlow bottle prevents hundreds of single-use plastics from entering our oceans each year. The minimal, timeless design isn't just aesthetically pleasing—it's created to last for years, not months, further reducing your environmental footprint.\n",
      "\n",
      "With every EcoFlow purchase, we donate 5% to ocean cleanup initiatives, meaning your daily hydration ritual actively contributes to healing our planet's most precious resource.\n",
      "\n",
      "Transform something as simple as staying hydrated into an act of purpose. Choose EcoFlow—where personal wellness meets global wellbeing.\n",
      "                === WORKER RESULT (comparative-educational) ===\n",
      "                # HydroEarth: The Water Bottle That Protects What Matters Most\n",
      "\n",
      "In a world where over 1 million plastic bottles are purchased every minute—with 91% never making it to recycling facilities—choosing the right water bottle becomes more than a convenience decision; it's an environmental statement. The HydroEarth bottle stands apart from conventional alternatives through thoughtful design and genuine sustainability credentials.\n",
      "\n",
      "## How HydroEarth Compares to Conventional Bottles\n",
      "\n",
      "### Materials That Make a Difference\n",
      "While standard plastic water bottles are petroleum-based products requiring 700 years to decompose, the HydroEarth is crafted from plant-derived bioplastics and recycled stainless steel. This combination creates a product with 87% less carbon footprint than traditional bottles during manufacturing.\n",
      "\n",
      "### Lifecycle Comparison\n",
      "Consider this: a person using disposable bottles consumes approximately 167 bottles annually. Over five years, that's 835 bottles in landfills or oceans. A single HydroEarth bottle replaces all of these, preventing approximately 30 pounds of plastic waste per person.\n",
      "\n",
      "### Toxin-Free Hydration\n",
      "Unlike many conventional plastic bottles containing BPA, phthalates, and microplastics that leach into your water, HydroEarth features a completely non-toxic interior that maintains water purity even after hundreds of uses and temperature changes.\n",
      "\n",
      "## Environmental Problems Solved\n",
      "\n",
      "The HydroEarth directly addresses three critical environmental challenges:\n",
      "\n",
      "1. **Petroleum Consumption**: Conventional plastic bottles consume 17 million barrels of oil annually just for U.S. demand. HydroEarth's bioplastic components derive from sustainable plant sources instead of fossil fuels.\n",
      "\n",
      "2. **Oceanic Plastic Pollution**: With 8 million metric tons of plastic entering our oceans yearly, HydroEarth prevents approximately 300 potential ocean-bound bottles per user over its lifetime.\n",
      "\n",
      "3. **Landfill Burden**: When your HydroEarth eventually reaches end-of-life, its components are 100% recyclable or compostable, unlike conventional bottles that remain in landfills for centuries.\n",
      "\n",
      "## Making Informed Choices\n",
      "\n",
      "Understanding the true cost of conventional bottles extends beyond the purchase price. While a disposable water bottle might cost $1-2, the environmental price includes:\n",
      "\n",
      "- Water usage: 3 liters required to produce 1 liter of bottled water\n",
      "- Carbon emissions: 82.8g of CO₂ per disposable bottle\n",
      "- Waste management costs: $70 million annually in U.S. cleanup costs\n",
      "\n",
      "The HydroEarth's slightly higher upfront investment ($35) pays for itself within 3-4 weeks of daily use while eliminating these hidden environmental costs.\n",
      "\n",
      "By choosing HydroEarth, you're not just buying a water bottle—you're participating in a necessary shift toward sustainable consumption that our planet urgently needs.\n"
     ]
    }
   ],
   "execution_count": 6
  },
  {
   "metadata": {},
   "cell_type": "markdown",
   "source": [
    "## How it works\n",
    "\n",
    "1. The orchestrator LLM receives the initial task and analyzes it to identify distinct approaches (like formal and conversational styles)\n",
    "2. Based on its analysis, the orchestrator dynamically generates subtasks with specific requirements\n",
    "3. Each subtask is delegated to a worker LLM, which executes it with the focused parameters\n",
    "4. The orchestrator collects the results from all workers\n",
    "\n",
    "## Conclusion\n",
    "\n",
    "The orchestrator-workers pattern offers a powerful approach to building AI systems that can tackle complex, unpredictable tasks.\n",
    "By dynamically breaking down problems and delegating subtasks to specialized workers,\n",
    "we can create more flexible, adaptable solutions.\n",
    "\n",
    "Kotlin's expressive syntax and strong typing make it an excellent fit for implementing this pattern,\n",
    "providing both readability and reliability.\n",
    "\n",
    "This approach is particularly valuable when dealing with tasks where the exact steps aren't known in advance,\n",
    "allowing our AI systems to adapt their strategies based on the specific needs of each input."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Kotlin",
   "language": "kotlin",
   "name": "kotlin"
  },
  "language_info": {
   "name": "kotlin",
   "version": "1.9.23",
   "mimetype": "text/x-kotlin",
   "file_extension": ".kt",
   "pygments_lexer": "kotlin",
   "codemirror_mode": "text/x-kotlin",
   "nbconvert_exporter": ""
  }
 },
 "nbformat": 4,
 "nbformat_minor": 0
}