Implementation:Ucbepic Docetl Directive Base

Knowledge Sources	Ucbepic_Docetl
Domains	Pipeline_Optimization, LLM_Operations
Last Updated	2026-02-08 00:00 GMT

Overview

Abstract base class defining the interface for all reasoning optimizer directives provided by the DocETL reasoning optimizer.

Description

The base.py module defines the Directive abstract base class (extending both BaseModel and ABC) that all concrete directives must implement. It specifies required fields (name, formal_description, nl_description, when_to_use, instantiate_schema_type, example, test_cases) and abstract methods (to_string_for_instantiate, llm_instantiate, apply, instantiate). It also provides supporting classes DirectiveTestCase and TestResult, plus configuration constants like MAX_DIRECTIVE_INSTANTIATION_ATTEMPTS, DEFAULT_MODEL, DEFAULT_MAX_TPM, and DEFAULT_OUTPUT_DIR.

Usage

This module is the foundation for all directives. Every concrete directive subclass inherits from Directive and must implement the abstract methods. The run_tests method allows automated testing of directive implementations via LLM-judged test cases.

Code Reference

Source Location

Repository: Ucbepic_Docetl
File: docetl/reasoning_optimizer/directives/base.py
Lines: 1-231

Signature

class Directive(BaseModel, ABC):
    name: str = Field(..., description="The name of the directive")
    formal_description: str = Field(..., description="A description of the directive; e.g., map => map -> map")
    nl_description: str = Field(..., description="An english description of the directive")
    when_to_use: str = Field(..., description="When to use the directive")
    instantiate_schema_type: BaseModel = Field(...)
    example: str = Field(...)
    test_cases: List[DirectiveTestCase] = Field(default_factory=list)

    def to_string_for_plan(self) -> str: ...
    @abstractmethod
    def to_string_for_instantiate(self, *args, **kwargs) -> str: ...
    @abstractmethod
    def llm_instantiate(self, *args, **kwargs): ...
    @abstractmethod
    def apply(self, *args, **kwargs) -> list: ...
    @abstractmethod
    def instantiate(self, *args, **kwargs): ...
    def run_tests(self, agent_llm: str = "gpt-4o-mini") -> List[TestResult]: ...

Import

from docetl.reasoning_optimizer.directives.base import Directive, DirectiveTestCase, TestResult

I/O Contract

Inputs

Name	Type	Required	Description
name	str	Yes	The name of the directive
formal_description	str	Yes	Formal transformation notation (e.g., "Map => Map -> Map")
nl_description	str	Yes	Natural language description of the directive
when_to_use	str	Yes	Conditions under which the directive should be applied
instantiate_schema_type	BaseModel	Yes	Pydantic schema for instantiation parameters

Outputs

Name	Type	Description
plan_string	str	Formatted description for prompt inclusion via to_string_for_plan()
applied_ops	list	Transformed operations from apply()
test_results	List[TestResult]	Results of running test cases via run_tests()

Usage Examples

# Creating a custom directive by subclassing
from docetl.reasoning_optimizer.directives.base import Directive, DirectiveTestCase

class MyCustomDirective(Directive):
    name = "my_custom"
    formal_description = "Op => Op*"
    nl_description = "A custom transformation"
    when_to_use = "When custom transformation is needed"

    def to_string_for_instantiate(self, *args, **kwargs) -> str: ...
    def llm_instantiate(self, *args, **kwargs): ...
    def apply(self, *args, **kwargs) -> list: ...
    def instantiate(self, *args, **kwargs): ...

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment