### Build Basic PlanAI Workflow

Source: https://github.com/provos/planai/blob/main/docs-astro/src/content/docs/getting-started/quickstart.md

Demonstrates creating a fundamental PlanAI workflow. It defines custom Task and TaskWorker classes for data processing and printing, sets up a dependency graph, and runs the workflow with initial data. This example showcases the core components for building sequential data pipelines.

```python
from typing import List, Type

from planai import Graph, Task, TaskWorker


# Define our data models using Pydantic
class RawData(Task):
    content: str


class ProcessedData(Task):
    processed_content: str
    word_count: int


class AnalysisResult(Task):
    summary: str
    sentiment: str


# Create a simple data processor
class DataProcessor(TaskWorker):
    output_types: List[Type[Task]] = [ProcessedData]

    def consume_work(self, task: RawData):
        # Process the raw data
        cleaned = task.content.strip().lower()
        word_count = len(cleaned.split())

        # Publish the processed data
        self.publish_work(
            ProcessedData(processed_content=cleaned, word_count=word_count),
            input_task=task,
        )


class DataPrinter(TaskWorker):
    def consume_work(self, task: ProcessedData):
        print(task.processed_content)


# Create the workflow graph
graph = Graph(name="Simple Data Pipeline")
processor = DataProcessor()
printer = DataPrinter()
graph.add_workers(processor, printer)
graph.set_dependency(processor, printer)


# Run the workflow
initial_data = RawData(content="  Hello World! This is PlanAI.  ")
graph.run(initial_tasks=[(processor, initial_data)])

# Will print: Hello World! This is PlanAI. 

```

--------------------------------

### Run Workflow with Initial Data

Source: https://github.com/provos/planai/blob/main/docs-astro/src/content/docs/getting-started/quickstart.md

Demonstrates how to initialize data sources and execute a workflow using the `graph.run` method with a list of initial tasks. This sets up the starting point for the PlanAI workflow execution.

```python
initial_data = [
    DataSource(source_id="source1", data="First dataset"),
    DataSource(source_id="source2", data="Second dataset"),
    DataSource(source_id="source3", data="Third dataset"),
]
graph.run(initial_tasks=[(processor, element) for element in initial_data])
```

--------------------------------

### Install and Verify PlanAI CLI

Source: https://github.com/provos/planai/blob/main/docs-astro/src/content/docs/cli/overview.md

Installs the PlanAI CLI using pip and verifies the installation by checking the help command. This is the first step to get started with the PlanAI command-line interface.

```bash
pip install planai
```

```bash
planai --help
```

--------------------------------

### Set OpenAI API Key Environment Variable

Source: https://github.com/provos/planai/blob/main/docs-astro/src/content/docs/getting-started/quickstart.md

Provides instructions on how to set the `OPENAI_API_KEY` environment variable, which is necessary for PlanAI to authenticate with OpenAI services. Alternatively, API keys can be loaded from a `.env.local` file.

```bash
export OPENAI_API_KEY="your-api-key"
```

--------------------------------

### Develop Svelte Project

Source: https://github.com/provos/planai/blob/main/examples/deepsearch/frontend/README.md

Start the development server to see your Svelte project in action. The `-- --open` flag will automatically launch the application in your default browser.

```bash
npm run dev

# or start the server and open the app in a new browser tab
npm run dev -- --open
```

--------------------------------

### Handle Multiple Inputs with JoinedTaskWorker

Source: https://github.com/provos/planai/blob/main/docs-astro/src/content/docs/getting-started/quickstart.md

Illustrates how to manage workflows with multiple data sources using PlanAI's JoinedTaskWorker. This example defines a DataSource task, a DataProcessor that publishes multiple outputs, and a ResultAggregator (a JoinedTaskWorker) to combine results before further processing. It highlights parallel processing and aggregation patterns.

```python
from typing import List, Type

from planai import Graph, InitialTaskWorker, JoinedTaskWorker, Task, TaskWorker


# Define a data source
class DataSource(Task):
    source_id: str
    data: str


class ProcessedData(Task):
    processed_data: str


class CombinedAnalysis(Task):
    sources_analyzed: int
    combined_summary: str


# Worker to process data
class DataProcessor(TaskWorker):
    output_types: List[Type[Task]] = [ProcessedData]

    def consume_work(self, task: DataSource):
        # We'll publish multiple tasks here
        for i in range(3):
            self.publish_work(
                ProcessedData(processed_data=f"{task.data} - processed {i}"),
                input_task=task,
            )


# Worker to join results
class ResultAggregator(JoinedTaskWorker):
    join_type: Type[TaskWorker] = InitialTaskWorker
    output_types: List[Type[Task]] = [CombinedAnalysis]

    def consume_work_joined(self, tasks: List[ProcessedData]):
        combined_summary = f"Analyzed {len(tasks)} sources from {tasks[0].prefix(1)}"

        self.publish_work(
            CombinedAnalysis(
                sources_analyzed=len(tasks), combined_summary=combined_summary
            ),
            input_task=tasks[0],
        )


# Class DataPrinter
class DataPrinter(TaskWorker):
    def consume_work(self, task: CombinedAnalysis):
        self.print(task.combined_summary)


# Build the complete workflow
graph = Graph(name="Multi-Source Analysis")
processor = DataProcessor()
aggregator = ResultAggregator()
printer = DataPrinter()

graph.add_workers(processor, aggregator, printer)
graph.set_dependency(processor, aggregator).next(printer)


```

--------------------------------

### Install PlanAI with Poetry

Source: https://github.com/provos/planai/blob/main/docs/source/installation.rst

Installs the PlanAI package using Poetry, a dependency management tool for Python. This command adds PlanAI as a dependency to your project's pyproject.toml file.

```bash
poetry add planai
```

--------------------------------

### Development Installation of PlanAI

Source: https://github.com/provos/planai/blob/main/docs-astro/src/content/docs/getting-started/installation.md

Sets up PlanAI for development or contribution. This involves cloning the repository, installing dependencies using Poetry, and activating the virtual environment. This allows you to work with the latest code and make changes.

```bash
git clone https://github.com/provos/planai.git
cd planai
poetry install
poetry shell
```

--------------------------------

### Install PlanAI using Pip or Poetry

Source: https://github.com/provos/planai/blob/main/docs/source/installation.rst

This section details how to install the PlanAI project. It covers installation using the standard Python package installer (pip) and the dependency management tool (poetry).

```bash
pip install planai
```

```bash
poetry add planai
```

--------------------------------

### Implement Caching for LLM Tasks

Source: https://github.com/provos/planai/blob/main/docs-astro/src/content/docs/getting-started/quickstart.md

Shows how to create a custom task worker that leverages caching for expensive LLM operations. By inheriting from `CachedLLMTaskWorker`, responses are automatically cached, improving performance. It includes defining prompts, input/output types, and optional cache directory configuration.

```python
from planai import CachedLLMTaskWorker

class CachedAnalyzer(CachedLLMTaskWorker):
    prompt: str = "Analyze this text and provide insights"
    llm_input_type: Type[Task] = ProcessedData
    output_types: List[Type[Task]] = [AnalysisResult]

# The cached analyzer will automatically cache LLM responses
cached_analyzer = CachedAnalyzer(
    llm=llm_from_config("openai", "gpt-4"),
    cache_dir="./cache"  # Optional: specify cache location
)
```

--------------------------------

### Multi-Graph Coordination Example

Source: https://github.com/provos/planai/blob/main/docs-astro/src/content/docs/api/graph.md

Shows the setup for multi-graph coordination using a shared Dispatcher instance, specifying the web port for communication.

```Python
# Shared dispatcher for multiple graphs
dispatcher = Dispatcher(web_port=8080)

```

--------------------------------

### Install PlanAI with pip

Source: https://github.com/provos/planai/blob/main/docs-astro/src/content/docs/getting-started/installation.md

Installs the PlanAI package using pip, the standard Python package installer. This is the simplest method for most users. Ensure your pip is up-to-date for the best experience.

```bash
pip install planai
```

--------------------------------

### Few-Shot Prompting for Improved Performance

Source: https://github.com/provos/planai/blob/main/docs-astro/src/content/docs/guide/prompts.md

Implements few-shot prompting by including example input-output pairs within the prompt. This technique helps guide the LLM towards desired behavior and improves accuracy.

```python
class FewShotAnalyzer(LLMTaskWorker):
    prompt = """Classify the following text into a category.

Examples:
- \"The product arrived damaged\" -> category: complaint
- \"Thank you for the excellent service\" -> category: praise
- \"How do I reset my password?\" -> category: question

Now classify this text: {text}"""
    
    def format_prompt(self, task: Task) -> str:
        return self.prompt.format(text=task.content)
```

--------------------------------

### Verify PlanAI CLI Help

Source: https://github.com/provos/planai/blob/main/docs-astro/src/content/docs/getting-started/installation.md

Checks if the PlanAI command-line interface (CLI) is accessible and functioning. Running `planai --help` displays available commands and options, verifying that the CLI tool was installed and is in your system's PATH.

```bash
planai --help
```

--------------------------------

### Verify PlanAI Installation

Source: https://github.com/provos/planai/blob/main/docs-astro/src/content/docs/getting-started/installation.md

Verifies the PlanAI installation by importing the package and accessing a component, or by checking the command-line interface help.

```python
import planai; print(planai.Task)
```

```bash
planai --help
```

--------------------------------

### Run PlanAI Optimize-Prompt Tool (Example)

Source: https://github.com/provos/planai/blob/main/PROMPT_OPTIMIZATION.md

An example command for optimizing the `DiffAnalyzer` prompt in the `releasenotes.py` application. It specifies LLM models, the class, debug log path, search path, and a detailed goal prompt for improvement.

```bash
poetry run planai --llm-provider openai --llm-model gpt-4o --llm-reason-model o3-mini optimize-prompt --python-file releasenotes.py --class-name DiffAnalyzer --debug-log debug/DiffAnalyzer.json --search-path . --llm-opt-provider openai --llm-opt-model gpt-4o --goal-prompt "We need a change list description that accurately captures the change and can be understood in isolation. it should be clear about the component being changed and the main purpose of the code changes."
```

--------------------------------

### Add AI Capabilities to PlanAI Workflow

Source: https://github.com/provos/planai/blob/main/docs-astro/src/content/docs/getting-started/quickstart.md

Enhances a PlanAI workflow by integrating AI analysis using LLMTaskWorker. This snippet shows how to define an AIAnalyzer worker with a custom prompt, specify input and output task types, and configure an LLM client using llm_from_config. It demonstrates chaining AI processing steps in a workflow.

```python
from planai import LLMTaskWorker, llm_from_config


# Define an AI analyzer
class AIAnalyzer(LLMTaskWorker):
    prompt: str = """Analyze the following text and provide:
    1. A brief summary (one sentence)
    2. The overall sentiment (positive, negative, or neutral) 
    
    Format your response as JSON with 'summary' and 'sentiment' fields."""

    llm_input_type: Type[Task] = ProcessedData
    output_types: List[Type[Task]] = [AnalysisResult]

class ResultPrinter(TaskWorker):
    def consume_work(self, task: AnalysisResult):
        self.print(task.summary)
        self.print(task.sentiment)

# Create the enhanced workflow
graph = Graph(name="AI-Enhanced Pipeline")

# Initialize workers
processor = DataProcessor() # Assuming DataProcessor is defined as in the previous example
analyzer = AIAnalyzer(
    llm=llm_from_config(
        provider="openai",
        model_name="gpt-4o",
    )
)
result_printer = ResultPrinter()

# Build the graph
graph.add_workers(processor, analyzer, result_printer)
# analyzer depends on processor and result_printer depends on analyzer
graph.set_dependency(processor, analyzer).next(result_printer)  

# Run with monitoring dashboard
initial_data = RawData(content="PlanAI makes it easy to build AI workflows!")
graph.run(
    initial_tasks=[(processor, initial_data)],
    run_dashboard=False,  # Set to True to open monitoring at http://localhost:5000
)

# Logs should show: 
# The text promotes PlanAI's ability to simplify the creation of AI workflows.
# positive

```

--------------------------------

### LLMTaskWorker with System Prompt

Source: https://github.com/provos/planai/blob/main/docs-astro/src/content/docs/features/llm-integration.md

Shows how to enhance an `LLMTaskWorker` by providing a `system_prompt`. This allows setting the LLM's context or persona, guiding its behavior and response style. The example defines an `ExpertAnalyzer` that acts as a data analysis expert.

```python
from planai import LLMTaskWorker
from typing import Type

class ExpertAnalyzer(LLMTaskWorker):
    prompt = "Analyze this data and provide insights"
    system_prompt = """You are a data analysis expert with deep knowledge 
    of statistics and pattern recognition. Provide clear, actionable insights."""
    llm_input_type = DataSet
    output_types: List[Type[Task]] = [Analysis]
```

--------------------------------

### Install PlanAI for Development

Source: https://github.com/provos/planai/blob/main/README.md

Clones the PlanAI repository and installs development dependencies using Poetry. This is for users contributing to or modifying the PlanAI framework.

```bash
git clone https://github.com/provos/planai.git
cd planai
poetry install
```

--------------------------------

### Optimized Prompt Text Output Example

Source: https://github.com/provos/planai/blob/main/docs-astro/src/content/docs/cli/prompt-optimization.md

An example of the `optimized_prompt_*.txt` file generated by the PlanAI prompt optimization process. It shows a refined prompt designed for better LLM performance.

```text
Analyze the provided data with focus on:
1. Key metrics and their trends
2. Anomalies or outliers
3. Actionable recommendations

Structure your response according to the required format.
```

--------------------------------

### Install Pre-commit Hooks

Source: https://github.com/provos/planai/blob/main/CLAUDE.md

Installs pre-commit hooks, which are essential for maintaining code quality and consistency across all contributions to the repository.

```bash
pre-commit install
```

--------------------------------

### Implement Caching with CachedTaskWorker

Source: https://github.com/provos/planai/blob/main/docs-astro/src/content/docs/guide/usage.md

Shows how to leverage PlanAI's caching mechanism by inheriting from CachedTaskWorker. This allows for automatic memoization of task results, preventing redundant computations for identical inputs. The example illustrates the basic structure for creating a cached processor.

```python
from planai import CachedTaskWorker

class CachedProcessor(CachedTaskWorker):
    output_types: List[Type[Task]] = [ProcessedData]

    def consume_work(self, task: FetchedData):
        # Processing logic here
        pass
```

--------------------------------

### Initial PlanAI Optimization Command

Source: https://github.com/provos/planai/blob/main/docs-astro/src/content/docs/cli/prompt-optimization.md

Example of initiating a prompt optimization process using PlanAI with specific LLM providers and models.

```bash
planai --llm-provider anthropic --llm-model claude-3-opus --llm-reason-model claude-3-opus \
  optimize-prompt ...
```

--------------------------------

### Verify PlanAI Python Import

Source: https://github.com/provos/planai/blob/main/docs-astro/src/content/docs/getting-started/installation.md

Confirms that PlanAI has been installed correctly by attempting to import the package and access a specific attribute (Task) within Python. This is a quick check to ensure the Python environment recognizes the installed library.

```python
import planai
print(planai.Task)
```

--------------------------------

### Install Dependencies (Poetry)

Source: https://github.com/provos/planai/blob/main/CLAUDE.md

Installs project dependencies using Poetry, the recommended package and dependency manager for Python projects.

```bash
poetry install
```

--------------------------------

### Optimized Prompt Metadata JSON Output Example

Source: https://github.com/provos/planai/blob/main/docs-astro/src/content/docs/cli/prompt-optimization.md

An example of the `optimized_prompt_*.json` file generated by the PlanAI prompt optimization process. This file contains metadata about the optimization iteration, including score, improvements, and token reduction.

```json
{
  "class_name": "MyAnalyzer",
  "iteration": 1,
  "score": 8.5,
  "improvements": [
    "Added structured analysis points",
    "Clarified output format requirements",
    "Reduced ambiguous language"
  ],
  "token_reduction": "15%",
  "timestamp": "2024-01-15T10:30:00Z"
}
```

--------------------------------

### PlanAI Prompt Optimization Goal Examples

Source: https://github.com/provos/planai/blob/main/docs-astro/src/content/docs/cli/prompt-optimization.md

Provides examples of `goal-prompt` arguments for the PlanAI CLI's prompt optimization feature, demonstrating how to specify objectives like accuracy improvement, token reduction, format consistency, error reduction, and domain-specific tuning.

```bash
--goal-prompt "Improve accuracy in extracting key information while maintaining the current format"
```

```bash
--goal-prompt "Reduce token usage while preserving output quality and completeness"
```

```bash
--goal-prompt "Ensure consistent output format across all responses, following the Pydantic model structure"
```

```bash
--goal-prompt "Minimize parsing errors and ensure all required fields are always populated"
```

```bash
--goal-prompt "Improve medical terminology accuracy and ensure HIPAA-compliant responses"
```

--------------------------------

### Graph Entry Point Example

Source: https://github.com/provos/planai/blob/main/docs-astro/src/content/docs/api/graph.md

Demonstrates setting specific workers as entry points for the workflow graph.

```python
# Assuming Worker1 and Worker2 are TaskWorker instances
# graph.add_worker(Worker1)
# graph.add_worker(Worker2)

graph.set_entry(Worker1, Worker2)
```

--------------------------------

### Start Frontend Development Server

Source: https://github.com/provos/planai/blob/main/examples/deepsearch/README.md

Starts the Svelte development server for the DeepSearch frontend. This command should be run from the `frontend` directory.

```Shell
cd frontend
npm run dev
```

--------------------------------

### Start Backend Server

Source: https://github.com/provos/planai/blob/main/examples/deepsearch/README.md

Starts the DeepSearch backend server using Python and Flask. This command should be executed from the project's root directory.

```Shell
poetry run python deepsearch/deepsearch.py
```

--------------------------------

### PlanAI Basic Workflow Example

Source: https://github.com/provos/planai/blob/main/README.md

Demonstrates creating and running a simple PlanAI workflow. It defines custom TaskWorkers, an LLM-powered task, and sets up dependencies within a graph.

```Python
from planai import Graph, TaskWorker, Task, LLMTaskWorker, llm_from_config
from typing import List, Type

# Placeholder types for demonstration
class ProcessedData(Task):
    data: str

class AnalysisResult(Task):
    result: str

class RawData(Task):
    data: str

# Define custom TaskWorkers
class CustomDataProcessor(TaskWorker):
    output_types: List[Type[Task]] = [ProcessedData]

    def consume_work(self, task: RawData):
        processed_data = self.process(task.data)
        self.publish_work(ProcessedData(data=processed_data), input_task=task)

    def process(self, data):
        # Dummy processing logic
        return f"Processed: {data}"

# Define an LLM-powered task
class AIAnalyzer(LLMTaskWorker):
    prompt: str ="Analyze the provided data and derive insights"
    llm_input_type: Type[Task] = ProcessedData
    output_types: List[Type[Task]] = [AnalysisResult]

    def process_llm_response(self, response: str, input_task: ProcessedData) -> AnalysisResult:
        # Dummy processing of LLM response
        return AnalysisResult(result=f"AI Analysis: {response}")


# Create and run the workflow
graph = Graph(name="Data Analysis Workflow")
data_processor = CustomDataProcessor()
ai_analyzer = AIAnalyzer(
   llm=llm_from_config(provider="openai", model_name="gpt-4"))

graph.add_workers(data_processor, ai_analyzer)
graph.set_dependency(data_processor, ai_analyzer)

initial_data = RawData(data="Some raw data")
graph.run(initial_tasks=[(data_processor, initial_data)])

```

--------------------------------

### Install Pre-commit Hook

Source: https://github.com/provos/planai/blob/main/CONTRIBUTING.md

Installs the pre-commit hook to ensure code quality and consistent formatting across contributions. This is a required step before contributing to the project.

```sh
pre-commit install

```

--------------------------------

### Graph Class Initialization Example

Source: https://github.com/provos/planai/blob/main/docs-astro/src/content/docs/api/graph.md

Demonstrates how to initialize the Graph class and add a TaskWorker to it.

```python
from planai import Graph

# Assuming TaskWorker and DataProcessor are defined elsewhere
# class TaskWorker: pass
# class DataProcessor(TaskWorker): pass

graph = Graph(name="Data Pipeline")
processor = DataProcessor()
graph.add_worker(processor)
```

--------------------------------

### Display PlanAI Version

Source: https://github.com/provos/planai/blob/main/docs-astro/src/content/docs/cli/overview.md

Shows the current version of the PlanAI CLI. This command is useful for verifying installation and checking compatibility.

```bash
planai version
```

--------------------------------

### Get Help for PlanAI Commands

Source: https://github.com/provos/planai/blob/main/docs-astro/src/content/docs/cli/overview.md

Retrieves help information for PlanAI commands. Can be used for general help or specific command-level assistance.

```bash
# General help
planai --help
```

```bash
# Command-specific help
planai optimize-prompt --help
planai cache --help
```

--------------------------------

### Run Dashboard via Graph Method

Source: https://github.com/provos/planai/blob/main/docs-astro/src/content/docs/cli/overview.md

Alternatively, the web-based dashboard can be enabled by passing `run_dashboard=True` to the Graph `run` or `prepare` method. The dashboard typically starts on port 5000.

```python
# Example for Graph.run()
my_graph.run(run_dashboard=True)

# Example for Graph.prepare()
my_graph.prepare(run_dashboard=True)
```

--------------------------------

### Python Chain-of-Thought Prompting

Source: https://github.com/provos/planai/blob/main/docs-astro/src/content/docs/guide/prompts.md

Demonstrates implementing Chain-of-Thought prompting in Python. This example uses a `LLMTaskWorker` class with a system prompt designed to guide an LLM through step-by-step reasoning for problem-solving.

```python
class ReasoningAnalyzer(LLMTaskWorker):
    prompt = """Solve this problem step by step.

Problem: {problem}

Please think through this carefully:
1. First, identify what we're trying to solve
2. List the given information
3. Work through the solution step by step
4. Verify your answer

Provide your final answer in the required format."""

```

--------------------------------

### Create Starlight Project

Source: https://github.com/provos/planai/blob/main/docs-astro/README.md

Command to create a new Astro project using the Starlight template. This command initializes a new project with the necessary dependencies and configuration for Starlight.

```shell
npm create astro@latest -- --template starlight
```

--------------------------------

### Create and Run Simple PlanAI Workflow

Source: https://github.com/provos/planai/blob/main/docs/source/usage.rst

Demonstrates defining custom TaskWorker classes (DataFetcher, DataProcessor), creating a Graph, adding workers, setting dependencies, and executing the workflow with initial tasks. Requires the 'planai' library.

```python
from planai import Graph, TaskWorker, Task

# Assume FetchedData, FetchRequest, ProcessedData are defined elsewhere
# class FetchedData:
#     def __init__(self, data):
#         self.data = data
# class FetchRequest:
#     def __init__(self, url):
#         self.url = url
# class ProcessedData:
#     def __init__(self, data):
#         self.data = data

# Define custom TaskWorkers
class DataFetcher(TaskWorker):
    output_types = [FetchedData]

    def consume_work(self, task: FetchRequest):
        # Fetch data from some source
        # Placeholder for actual data fetching logic
        print(f"Fetching data from {task.url}")
        data = "sample fetched data"
        self.publish_work(FetchedData(data=data))

class DataProcessor(TaskWorker):
    output_types = [ProcessedData]

    def consume_work(self, task: FetchedData):
        # Process the fetched data
        # Placeholder for actual processing logic
        print(f"Processing data: {task.data}")
        processed_data = f"processed({task.data})"
        self.publish_work(ProcessedData(data=processed_data))

# Create a graph
graph = Graph(name="Data Processing Workflow")

# Initialize tasks
fetcher = DataFetcher()
processor = DataProcessor()

# Add tasks to the graph and set dependencies
graph.add_workers(fetcher, processor)
graph.set_dependency(fetcher, processor)

# Run the graph
# Assume FetchRequest, FetchedData, ProcessedData are defined
# initial_request = FetchRequest(url="https://example.com/data")
# graph.run(initial_tasks=[(fetcher, initial_request)])

print("Workflow setup complete. To run, uncomment graph.run() and define data classes.")
```

--------------------------------

### PlanAI: Create Reusable Subgraphs with SubGraphWorker

Source: https://github.com/provos/planai/blob/main/docs-astro/src/content/docs/guide/usage.md

Explains how to encapsulate entire workflows as reusable TaskWorkers using `SubGraphWorker`. This enables modularity and composability, requiring input/output types to be importable. The example shows defining, wrapping, and integrating a subgraph into a main workflow.

```python
from planai import Graph
from planai.graph_task import SubGraphWorker

# Assuming Task1Worker, Task2Worker, Task3Worker, Task1WorkItem are defined elsewhere
class Task1Worker:
    def __init__(self):
        pass
    def __call__(self, *args, **kwargs):
        print("Task1Worker executed")
        return Task1WorkItem(data="processed")

class Task2Worker:
    def __init__(self):
        pass
    def __call__(self, *args, **kwargs):
        print("Task2Worker executed")
        return "result_from_task2"

class Task3Worker:
    def __init__(self):
        pass
    def __call__(self, *args, **kwargs):
        print("Task3Worker executed")
        return "final_result"

class Task1WorkItem:
    def __init__(self, data):
        self.data = data

# 1. Define a subgraph
sub_graph = Graph(name="SubGraphExample")
worker1 = Task1Worker()
worker2 = Task2Worker()
sub_graph.add_workers(worker1, worker2)
sub_graph.set_dependency(worker1, worker2)
sub_graph.set_entry(worker1)
sub_graph.set_exit(worker2)

# 2. Wrap the subgraph as a TaskWorker
subgraph_worker = SubGraphWorker(name="ExampleSubGraph", graph=sub_graph)

# 3. Integrate into the main graph
main_graph = Graph(name="MainWorkflow")
final_worker = Task3Worker()
main_graph.add_workers(subgraph_worker, final_worker)
main_graph.set_dependency(subgraph_worker, final_worker)
main_graph.set_entry(subgraph_worker)
main_graph.set_exit(final_worker)

# 4. Run the main graph
initial_input = Task1WorkItem(data="start")
print("Running main graph...")
main_graph.run(initial_tasks=[(subgraph_worker, initial_input)])
print("Main graph finished.")
```

--------------------------------

### Starlight Project Structure

Source: https://github.com/provos/planai/blob/main/docs-astro/README.md

Overview of the typical directory structure for an Astro + Starlight project. Starlight content is typically placed in `src/content/docs/`.

```plaintext
.\n├── public/\n├── src/\n│   ├── assets/\n│   ├── content/\n│   │   └── docs/\n│   └── content.config.ts\n├── astro.config.mjs\n├── package.json\n└── tsconfig.json
```

--------------------------------

### Load Configuration File

Source: https://github.com/provos/planai/blob/main/docs-astro/src/content/docs/cli/overview.md

Demonstrates how to load PlanAI settings from a specified YAML configuration file using the `--config` flag.

```bash
planai --config .planai.yaml <command>
```

--------------------------------

### Run Textbook Application

Source: https://github.com/provos/planai/blob/main/examples/textbook/README.md

Command to execute the PlanAI textbook Q&A generation application from the command line.

```bash
python textbook_app.py --file path/to/your/textbook.pdf
```

--------------------------------

### Install Backend Dependencies

Source: https://github.com/provos/planai/blob/main/examples/deepsearch/README.md

Installs the necessary Python dependencies for the DeepSearch backend using Poetry and installs Playwright browsers for web scraping. Ensure Python 3.10+ is installed.

```Shell
poetry install
poetry run playwright install
```

--------------------------------

### Setup PlanAI Logging

Source: https://github.com/provos/planai/blob/main/docs-astro/src/content/docs/guide/monitoring.md

Demonstrates how to initialize PlanAI's logging system using the `setup_logging` utility function. This function generates two log files: a general log for most operations and an LLM log for communication details.

```python
from planai.utils import setup_logging

def main():
    setup_logging()
```

--------------------------------

### Build Svelte Project for Production

Source: https://github.com/provos/planai/blob/main/examples/deepsearch/frontend/README.md

Generate a production-ready build of your Svelte application. After building, you can preview the production version using the `npm run preview` command.

```bash
npm run build
```

--------------------------------

### Create Svelte Project with sv CLI

Source: https://github.com/provos/planai/blob/main/examples/deepsearch/frontend/README.md

Initialize a new Svelte project using the `sv create` command. You can create it in the current directory or specify a project name for a new subdirectory.

```bash
npx sv create

npx sv create my-app
```

--------------------------------

### Install Frontend Dependencies

Source: https://github.com/provos/planai/blob/main/examples/deepsearch/README.md

Installs the JavaScript dependencies for the DeepSearch frontend using npm. This command should be run from the `frontend` directory.

```Shell
cd frontend
npm install
```

--------------------------------

### Install PlanAI Package

Source: https://github.com/provos/planai/blob/main/README.md

Installs the PlanAI Python package using pip. This is the standard method for adding the library to your project.

```bash
pip install planai
```

--------------------------------

### Astro/Starlight Development Commands

Source: https://github.com/provos/planai/blob/main/docs-astro/README.md

Common commands for managing and developing an Astro + Starlight project. These commands are run from the project's root directory.

```shell
npm install
npm run dev
npm run build
npm run preview
npm run astro ...
npm run astro -- --help
```

--------------------------------

### Create and Run a Simple PlanAI Workflow

Source: https://github.com/provos/planai/blob/main/docs-astro/src/content/docs/guide/usage.md

Demonstrates the creation of a basic PlanAI workflow. It includes defining custom TaskWorkers for data fetching and processing, setting up a Graph, establishing dependencies between workers, defining a sink for output, and running the workflow with initial tasks. This snippet showcases the core structure for building data processing pipelines.

```python
from typing import List, Type

from planai import Graph, Task, TaskWorker


# Define custom TaskWorkers
class DataFetcher(TaskWorker):
    output_types: List[Type[Task]] = [FetchedData]

    def consume_work(self, task: FetchRequest):
        # Fetch data from some source - needs to be implemented
        data = self.fetch_data(task.url)
        self.publish_work(FetchedData(data=data), input_task=task)


class DataProcessor(TaskWorker):
    output_types: List[Type[Task]] = [ProcessedData]

    def consume_work(self, task: FetchedData):
        # Process the fetched data
        processed_data = self.process(task.data)
        self.publish_work(ProcessedData(data=processed_data), input_task=task)


# Create a graph
graph = Graph(name="Data Processing Workflow")

# Initialize tasks
fetcher = DataFetcher()
processor = DataProcessor()

# Add tasks to the graph and set dependencies
graph.add_workers(fetcher, processor)
graph.set_dependency(fetcher, processor)

# Let the graph collect all tasks published
# by the processor with the type ProcessedData
graph.set_sink(processor, ProcessedData)

# Run the graph
initial_request = FetchRequest(url="https://example.com/data")
graph.run(initial_tasks=[(fetcher, initial_request)])

# Get the outputs
outputs = graph.get_output_tasks()
```

--------------------------------

### Prompt Optimization Workflow Example

Source: https://github.com/provos/planai/blob/main/docs-astro/src/content/docs/cli/overview.md

Demonstrates the prompt optimization workflow: 1. Enable debug mode in worker. 2. Run workflow to collect data. 3. Use CLI to optimize prompts with collected data.

```bash
planai --llm-provider openai --llm-model gpt-4o-mini \
  optimize-prompt \
  --python-file my_worker.py \
  --class-name MyWorker \
  --debug-log debug/MyWorker.json \
  --goal-prompt "Improve response quality"
```

--------------------------------

### JoinedTaskWorker Example

Source: https://github.com/provos/planai/blob/main/docs-astro/src/content/docs/api/taskworker.md

Demonstrates the `JoinedTaskWorker` for aggregating multiple tasks from upstream workers. The `AnalysisJoiner` example shows how to specify the join type and process aggregated results.

```python
from planai import JoinedTaskWorker, InitialTaskWorker

class AnalysisJoiner(JoinedTaskWorker):
    join_type: Type[TaskWorker] = InitialTaskWorker
    output_types: List[Type[Task]] = [PhaseAnalyses]
    enable_trace: bool = True  # Enable dashboard tracing
    
    def consume_work_joined(self, tasks: List[PhaseAnalysis]):
        """Process aggregated tasks"""
        combined = PhaseAnalyses(analyses=tasks)
        self.publish_work(combined, input_task=tasks[0])
```

--------------------------------

### View Built Documentation

Source: https://github.com/provos/planai/blob/main/CLAUDE.md

Opens the generated HTML documentation files in the default web browser.

```bash
open dist/index.html
```

--------------------------------

### DocumentAnalyzer Example

Source: https://github.com/provos/planai/blob/main/docs-astro/src/content/docs/api/taskworker.md

A real-world example demonstrating a `DocumentAnalyzer` worker that extends `CachedTaskWorker`. It customizes the cache key, implements pre/post consume hooks, and performs analysis in `consume_work`.

```python
class DocumentAnalyzer(CachedTaskWorker):
    output_types: List[Type[Task]] = [AnalysisResult]
    cache_dir: str = "./analysis_cache"
    model_version: str = "v2.1"
    
    def extra_cache_key(self, task: DocumentTask) -> str:
        # Include model version in cache key
        return f"model_{self.model_version}"
    
    def pre_consume_work(self, task: DocumentTask):
        self.notify_status(task, "Analyzing document...")
    
    def consume_work(self, task: DocumentTask):
        # Expensive analysis operation
        analysis = self.analyze_document(task.document)
        
        result = AnalysisResult(
            document_id=task.document_id,
            analysis=analysis,
            confidence=0.95
        )
        
        self.publish_work(result, input_task=task)
    
    def post_consume_work(self, task: DocumentTask):
        self.notify_status(task, "Analysis complete")
```

--------------------------------

### Cache Key Configuration Example

Source: https://github.com/provos/planai/blob/main/docs-astro/src/content/docs/api/taskworker.md

Example of including relevant configuration parameters, such as thresholds and model versions, in the cache key via `extra_cache_key` to ensure cache accuracy.

```python
def extra_cache_key(self, task: Task) -> str:
    return f"threshold_{self.threshold}_model_{self.model_version}"
```

--------------------------------

### Install PlanAIEditor Package

Source: https://github.com/provos/planai/blob/main/README.md

Installs the PlanAIEditor GUI tool package using pip. This package provides a visual interface for building PlanAI workflows.

```bash
pip install planaieditor
```

--------------------------------

### Nested Subgraphs Example

Source: https://github.com/provos/planai/blob/main/docs-astro/src/content/docs/features/subgraphs.md

Demonstrates the concept of nested subgraphs, where one subgraph can contain other subgraphs. This example shows a meta-graph that includes multiple instances of the text analysis subgraph, potentially for different languages, routed by a language detector.

```python
# Create a higher-level subgraph
meta_graph = Graph(name="MetaAnalysis")

# Add multiple analysis subgraphs
# Assuming english_llm and spanish_llm are initialized elsewhere
# english_analyzer = SubGraphWorker(
#     name="EnglishAnalyzer",
#     graph=create_text_analysis_subgraph(english_llm)
# )

# spanish_analyzer = SubGraphWorker(
#     name="SpanishAnalyzer", 
#     graph=create_text_analysis_subgraph(spanish_llm)
# )

# Language detector to route tasks
# language_detector = LanguageDetector()
# result_merger = ResultMerger()

# meta_graph.add_workers(language_detector, english_analyzer, spanish_analyzer, result_merger)
# Set up routing based on detected language
# Example: meta_graph.set_dependency(language_detector, english_analyzer, condition=lambda lang: lang == 'en')
# Example: meta_graph.set_dependency(language_detector, spanish_analyzer, condition=lambda lang: lang == 'es')
# Example: meta_graph.set_dependency([english_analyzer, spanish_analyzer], result_merger)
```

--------------------------------

### Build Sphinx Documentation

Source: https://github.com/provos/planai/blob/main/CLAUDE.md

Builds the project's documentation using Sphinx, after navigating into the documentation directory and running an npm build script.

```bash
cd docs-astro && npm run build
```

--------------------------------

### Add PlanAI to Poetry Project

Source: https://github.com/provos/planai/blob/main/docs-astro/src/content/docs/getting-started/installation.md

Adds PlanAI as a dependency to your project managed by Poetry. This method is suitable for users who prefer Poetry for dependency management. It ensures PlanAI is correctly integrated into your project's dependency tree.

```bash
poetry add planai
```

--------------------------------

### Get Task Name Property

Source: https://github.com/provos/planai/blob/main/docs-astro/src/content/docs/api/task.md

Provides a property to retrieve the class name of a Task instance.

```python
@property
def name(self) -> str:
    """Returns the class name of the task"""

```

--------------------------------

### Configure LLM Provider

Source: https://github.com/provos/planai/blob/main/docs-astro/src/content/docs/features/llm-integration.md

Demonstrates how to initialize an LLM client using the `llm_from_config` function from the `planai` library. It shows examples for OpenAI and Ollama, highlighting the use of provider names and model names. It's recommended to set API keys via environment variables for security.

```python
from planai import llm_from_config

# Using environment variable (recommended)
# Set OPENAI_API_KEY in your environment
llm_openai = llm_from_config(
    provider="openai",
    model_name="gpt-4"
)

# Requires Ollama running locally
llm_ollama = llm_from_config(
    provider="ollama",
    model_name="llama2"
)
```

--------------------------------

### CI/CD Integration for Prompt Optimization (GitHub Actions)

Source: https://github.com/provos/planai/blob/main/docs-astro/src/content/docs/cli/prompt-optimization.md

YAML configuration for a GitHub Actions workflow that automates weekly prompt optimization using PlanAI.

```yaml
# .github/workflows/optimize-prompts.yml
name: Optimize Prompts

on:
  schedule:
    - cron: '0 0 * * 0'  # Weekly

jobs:
  optimize:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      
      - name: Setup Python
        uses: actions/setup-python@v2
        
      - name: Install dependencies
        run: pip install planai
        
      - name: Run optimization
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
        run: |
          planai --llm-provider openai --llm-model gpt-4o-mini \
            optimize-prompt \
            --python-file src/workers.py \
            --class-name AnalysisWorker \
            --debug-log data/debug_logs.json \
            --goal-prompt "Improve accuracy based on last week's data"
            
      - name: Create PR with optimized prompts
        uses: peter-evans/create-pull-request@v3
        with:
          title: "Automated prompt optimization"
          body: "Weekly prompt optimization based on production data"
```

--------------------------------

### Get Previous Input Task

Source: https://github.com/provos/planai/blob/main/docs-astro/src/content/docs/api/task.md

Retrieves the task that directly preceded the current task in the processing pipeline.

```python
def previous_input_task(self) -> Optional[Task]:
    """
    Get the task that directly led to this one
    
    Returns:
        Previous task or None
    """

```

--------------------------------

### Optimize Prompts with PlanAI CLI

Source: https://github.com/provos/planai/blob/main/docs-astro/src/content/docs/cli/overview.md

Automatically optimizes prompts using AI and production data. Requires specifying the Python file, class name, search path, a debug log file, and a goal prompt.

```bash
planai --llm-provider openai --llm-model gpt-4o-mini --llm-reason-model gpt-4 \
  optimize-prompt \
  --python-file app.py \
  --class-name MyLLMWorker \
  --search-path . \
  --debug-log debug/MyLLMWorker.json \
  --goal-prompt "Improve accuracy while reducing token usage"
```

--------------------------------

### Get Provenance Chain Prefix

Source: https://github.com/provos/planai/blob/main/docs-astro/src/content/docs/api/task.md

Extracts a specified number of preceding tasks from the task's provenance chain.

```python
def prefix(self, length: int) -> ProvenanceChain:
    """
    Get a prefix of specified length from task's provenance chain
    
    Args:
        length: The desired length of the prefix to extract
        
    Returns:
        ProvenanceChain tuple containing first 'length' elements
    """

```

--------------------------------

### Graph Worker Addition Example

Source: https://github.com/provos/planai/blob/main/docs-astro/src/content/docs/api/graph.md

Shows how to add multiple TaskWorker instances to the Graph simultaneously.

```python
# Assuming fetcher, processor, analyzer, reporter are TaskWorker instances
# graph.add_worker(fetcher)
# graph.add_worker(processor)
# graph.add_worker(analyzer)
# graph.add_worker(reporter)

graph.add_workers(fetcher, processor, analyzer, reporter)
```

--------------------------------

### Run PlanAI Optimize-Prompt Tool (General Usage)

Source: https://github.com/provos/planai/blob/main/PROMPT_OPTIMIZATION.md

Execute the `planai optimize-prompt` command to initiate the prompt optimization process. Specify LLM providers, models, the target Python file and class, search paths, debug logs, and the optimization goal.

```bash
planai --llm-provider openai --llm-model gpt-4o-mini --llm-reason-model gpt-4o optimize-prompt --python-file your_app.py --class-name YourLLMTaskWorker --search-path . --debug-log debug/YourLLMTaskWorker.json --goal-prompt "Your optimization goal here"
```

--------------------------------

### Get Provenance Prefix for Worker Type

Source: https://github.com/provos/planai/blob/main/docs-astro/src/content/docs/api/task.md

Retrieves the provenance prefix relevant for joining operations with a specific worker type.

```python
def prefix_for_input_task(self, worker_type: Type[TaskWorker]) -> Optional[ProvenanceChain]:
    """
    Get provenance prefix for a specific worker type
    
    Args:
        worker_type: Type of worker to find prefix for
        
    Returns:
        Provenance prefix string or None
    """

```