Implementation:Ucbepic Docetl Directive ClarifyInstructions
| Knowledge Sources | |
|---|---|
| Domains | Pipeline_Optimization, LLM_Operations |
| Last Updated | 2026-02-08 00:00 GMT |
Overview
Concrete tool for improving a single operation's prompt clarity and specificity by analyzing sample data provided by the DocETL reasoning optimizer.
Description
The ClarifyInstructionsDirective class improves a single operation's prompt clarity and specificity by analyzing sample input data to identify patterns, resolve ambiguities, and create more precise instructions that reduce LLM confusion and improve output consistency. The agent iteratively reads sample documents to understand data patterns before producing a clarified prompt that handles edge cases present in the dataset.
Usage
The MOAR agent applies this directive when a single operation has a vague or ambiguous prompt that could benefit from more specific instructions based on actual data patterns. Particularly useful when there are multiple samples of input data and the goal is to create a prompt that handles the patterns and edge cases present in the dataset.
Code Reference
Source Location
- Repository: Ucbepic_Docetl
- File: docetl/reasoning_optimizer/directives/clarify_instructions.py
- Lines: 1-282
Signature
class ClarifyInstructionsDirective(Directive):
name = "clarify_instructions"
description = "Improves a single operation's prompt clarity by analyzing sample input data to resolve ambiguities."
def check_applicability(self, ...) -> Tuple[bool, str]: ...
def apply(self, ...) -> Tuple[List[Dict], List[Dict], str, dict]: ...
Import
from docetl.reasoning_optimizer.directives.clarify_instructions import ClarifyInstructionsDirective
I/O Contract
Inputs
| Name | Type | Required | Description |
|---|---|---|---|
| op_config | Dict | Yes | Operation configuration to transform |
| pipeline_ops | List[Dict] | Yes | Full pipeline operations list |
| op_idx | int | Yes | Index of target operation |
| dataset_descriptions | Dict | Yes | Dataset schema descriptions |
Outputs
| Name | Type | Description |
|---|---|---|
| new_ops | List[Dict] | Transformed operation configs |
| new_steps | List[Dict] | Updated pipeline steps |
| explanation | str | Human-readable description of changes |
| metadata | dict | Additional metadata about the transformation |
Usage Examples
# Directives are typically invoked by the MOAR agent automatically
# Example of manual invocation:
from docetl.reasoning_optimizer.directives.clarify_instructions import ClarifyInstructionsDirective
directive = ClarifyInstructionsDirective()
applicable, reason = directive.check_applicability(op_config, pipeline_ops, op_idx, dataset_descriptions)
if applicable:
new_ops, new_steps, explanation, metadata = directive.apply(op_config, pipeline_ops, op_idx, dataset_descriptions)