Pipeline Generators

Optional module

Install the pipeline_generators extra before generating pipelines via LLMs:

• pip install urban-mapper-community[pipeline_generators]
• uv add urban-mapper-community --group pipeline_generators

What is the Pipeline Generator module?

The Pipeline Generator module is solving the following scenario, imagine telling UrbanMapper exactly what urban analysis you want, and watching it craft a pipeline for you—no coding required. Powered by Large Language Models (LLMs), this module transforms your natural language descriptions into executable Python code for UrbanMapper pipelines.

Meanwhile, we recommend to look through the Example's Pipeline Generator for a more hands-on introduction about the Pipeline Generator module and its usage.

Documentation Under Alpha Construction

This documentation is in its early stages and still being developed. The API may therefore change, and some parts might be incomplete or inaccurate.

Use at your own risk, and please report anything that seems incorrect / outdated you find.

Open An Issue!

PipelineGeneratorBase

Bases: ABC

Abstract base class for pipeline generators.

This class defines the interface for pipeline generators.

What is a pipeline geneartor's primitive

Pipeline generators use large language models (LLMs) to automatically create UrbanMapper pipelines from natural language descriptions.

Implementations of this class must provide a generate_urban_pipeline method that takes a user description and returns Python code for an UrbanMapper pipeline.

Use of Short Name

The short name of the generator is used to identify the generator in the PipelineGeneratorFactory. It should be unique among all generators.

For instance, much easier to call GPT4 than GPT4Generator. See further in the factory.

Attributes:

Name	Type	Description
instructions		The instructions to guide the LLM in generating pipelines.

Examples:

>>> class GPT4Generator(PipelineGeneratorBase):
...     short_name = "GPT4"
...
...     def __init__(self, instructions: str):
...         self.instructions = instructions
...
...     def generate_urban_pipeline(self, user_description: str) -> str:
...         # Implementation that uses GPT-4 to generate a pipeline
...         ...

Source code in src/urban_mapper/modules/pipeline_generator/abc_pipeline_generator.py

class PipelineGeneratorBase(ABC):
    """Abstract base class for pipeline generators.

    This class defines the interface for pipeline generators.

    !!! question "What is a pipeline geneartor's primitive"
        Pipeline generators use large language models (LLMs) to automatically
        create `UrbanMapper pipelines` from `natural language descriptions`.

    Implementations of this class must provide a `generate_urban_pipeline` method
    that takes a user description and returns Python code for an `UrbanMapper pipeline`.

    !!! note "Use of Short Name"
        The short name of the generator is used to identify the generator in the
        `PipelineGeneratorFactory`. It should be unique among all generators.

        For instance, much easier to call GPT4 than `GPT4Generator`. See further in the factory.

    Attributes:
        instructions: The instructions to guide the LLM in generating pipelines.

    Examples:
        >>> class GPT4Generator(PipelineGeneratorBase):
        ...     short_name = "GPT4"
        ...
        ...     def __init__(self, instructions: str):
        ...         self.instructions = instructions
        ...
        ...     def generate_urban_pipeline(self, user_description: str) -> str:
        ...         # Implementation that uses GPT-4 to generate a pipeline
        ...         ...
    """

    @abstractmethod
    def generate_urban_pipeline(self, user_description: str) -> str:
        """Generate an `UrbanMapper pipeline` from a `natural language description`.

        This method uses a `large language model` to generate `Python code` for an
        `UrbanMapper pipeline` based on the user's `natural language description`.
        The generated code can then be executed to create and run the pipeline.

        Args:
            user_description: A natural language description of the desired pipeline,
                such as "Load traffic data for New York and visualise accident hotspots."

        Returns:
            A string containing Python code that implements the described pipeline.
            This code can be executed with exec() to run the pipeline.

        Examples:
            >>> generator = SomeGenerator(instructions)
            >>> pipeline_code = generator.generate_urban_pipeline(
            ...     "Load taxi trip data for Manhattan and create a heatmap of pickups"
            ... )
            >>> print(pipeline_code) # You may use Ipyleaflet Code(.) for highlighting, or even `exec(pipeline_code)` for running, yet this is not recommended.
        """
        pass

Functions

generate_urban_pipeline(user_description) abstractmethod

Generate an UrbanMapper pipeline from a natural language description.

This method uses a large language model to generate Python code for an UrbanMapper pipeline based on the user's natural language description. The generated code can then be executed to create and run the pipeline.

Parameters:

Name	Type	Description	Default
user_description	str	A natural language description of the desired pipeline, such as "Load traffic data for New York and visualise accident hotspots."	required

Returns:

Type	Description
str	A string containing Python code that implements the described pipeline.
str	This code can be executed with exec() to run the pipeline.

Examples:

>>> generator = SomeGenerator(instructions)
>>> pipeline_code = generator.generate_urban_pipeline(
...     "Load taxi trip data for Manhattan and create a heatmap of pickups"
... )
>>> print(pipeline_code) # You may use Ipyleaflet Code(.) for highlighting, or even `exec(pipeline_code)` for running, yet this is not recommended.

Source code in src/urban_mapper/modules/pipeline_generator/abc_pipeline_generator.py

@abstractmethod
def generate_urban_pipeline(self, user_description: str) -> str:
    """Generate an `UrbanMapper pipeline` from a `natural language description`.

    This method uses a `large language model` to generate `Python code` for an
    `UrbanMapper pipeline` based on the user's `natural language description`.
    The generated code can then be executed to create and run the pipeline.

    Args:
        user_description: A natural language description of the desired pipeline,
            such as "Load traffic data for New York and visualise accident hotspots."

    Returns:
        A string containing Python code that implements the described pipeline.
        This code can be executed with exec() to run the pipeline.

    Examples:
        >>> generator = SomeGenerator(instructions)
        >>> pipeline_code = generator.generate_urban_pipeline(
        ...     "Load taxi trip data for Manhattan and create a heatmap of pickups"
        ... )
        >>> print(pipeline_code) # You may use Ipyleaflet Code(.) for highlighting, or even `exec(pipeline_code)` for running, yet this is not recommended.
    """
    pass

GPT4PipelineGenerator = _GPT4PipelineGenerator module-attribute

GPT4OPipelineGenerator = _GPT4OPipelineGenerator module-attribute

GPT35TurboPipelineGenerator = _GPT35TurboPipelineGenerator module-attribute

PipelineGeneratorFactory = _PipelineGeneratorFactory module-attribute

Placeholder factory shown when pipeline generator dependencies are missing.

2025-04-282026-01-23Provost Simon, Provost Simon