Implementation:Ucbepic Docetl Directive Base
| Knowledge Sources | |
|---|---|
| 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): ...