Recipes API

Ellf’s recipes API is designed to make it easy to extend the functionality and develop custom workflows for your use cases. The recipes SDK package includes all Python utilities you need to implement a custom recipe, as well as helpers to configure the auto-generated UI forms and command-line interfaces that let you and your team start new tasks, actions, agents and services using your recipes.

Recipe decorator

The recipe decorator turns a Python function into a recipe and lets you provide basic information like titles and descriptions, as well as meta data used for the auto-generated form fields and command-line interface. Ellf provides four recipe decorators you can use to create and configure recipe functions:

1. @task_recipe for annotation tasks
2. @action_recipe for actions that perform any logic
3. @agent_recipe for autonomous agents
4. @service_recipe for long-running background services

@task_recipe decorator

Recipe decorator for annotation tasks that start the Prodigy server and annotation app.

from typing import Literal
from ellf_recipes_sdk import task_recipe, props, TextProps, Dataset, Input

@task_recipe(
    title="My Recipe",
    description="This is a task recipe",
    field_props={
        "dataset": props.dataset_choice,
        "input": TextProps(title="Input data")
    },
)
def recipe(*, dataset: Dataset[Literal["text"]], input: Input[Literal["text"]]):
    stream = input.load()
    return {
        "dataset": dataset.name,
        "stream": stream,
        "view_id": "text",
    }

@action_recipe decorator

Recipe decorator for actions that don’t start the annotation server and can execute any arbitrary Python logic like model training, data analysis, data conversion etc.

from ellf_recipes_sdk import action_recipe, TextProps, BoolProps, Input

@action_recipe(
    title="My Recipe",
    description="This is an action recipe",
    field_props={
        "input": TextProps(title="Input data"),
        "verbose": BoolProps(title="Print examples")
    },
)
def recipe(*, input: Input, verbose: bool = False):
    stream = list(input.load())
    print("Examples count:", len(stream))
    if verbose:
        print(stream)

@agent_recipe decorator

Recipe decorator for autonomous agents that run independently on the cluster and can be assigned to a task to create data and annotations. Agent recipes return an Annotator callable – a function that takes a task and config dict and returns an annotated task. The SDK handles server discovery, polling, and answer submission automatically.

from ellf_recipes_sdk import agent_recipe, Annotator, TextProps, FloatProps
from ellf_recipes_sdk import detect_task_type, format_prompt, parse_response

@agent_recipe(
    title="My Annotation Agent",
    description="Autonomous agent that annotates tasks using an LLM",
    field_props={
        "model": TextProps(title="Model name"),
        "poll_interval": FloatProps(title="Poll interval (seconds)", min=0.1),
    },
)
def my_agent(*, model: str = "my-model", poll_interval: float = 1.0) -> Annotator:
    # Set up any resources (LLM client, spaCy model, etc.)
    client = setup_llm(model)

    async def annotate(task: dict, config: dict) -> dict:
        task_type = detect_task_type(task)
        prompt = format_prompt(task, task_type, config)
        raw = await client.ask(prompt)
        return parse_response(raw, task, task_type, model_name=model)

    return annotate

Optional default recipe function parameters

These parameters can optionally be defined as recipe function parameters and are picked up automatically by the SDK when present in the recipe function signature – you don’t need to handle them yourself. poll_interval and idle_shutdown_seconds can also be fields of a dataclass argument, e.g. one that groups the agent’s advanced settings.

@agent_recipe(...)
def my_agent(*, poll_interval: float = 1.0, idle_shutdown_seconds: float = 0.0, icon: AgentIcon = "openai") -> Annotator:
    ...

Annotator type alias

The type expected as the return value of an @agent_recipe function. An Annotator is a callable that receives a task example dictionary and a config dictionary, and returns an annotated example dictionary. It can be either sync or async.

Annotator = Callable[
    [dict[str, Any], dict[str, Any]],  # example dict and config dict
    dict[str, Any] | Awaitable[dict[str, Any]],  # annotated task dict
]

def annotator(eg: dict[str, Any], config: dict[str, Any]) -> dict[str, Any]:
    annotated: dict[str, Any] = annotate(eg)
    return annotated

The annotated task dictionary must follow the same JSON format that the Prodigy annotation interface expects – the exact structure depends on the task type (e.g. spans for named entities or accept for multiple choice). It should also include an answer key with a value of "accept", "reject", or "ignore". You can optionally set _annotator_id and _session_id to identify the agent in the annotation data. If you’re using the built-in agent helpers, the response format is handled for you automatically.

Agent helpers functions

The SDK provides helper functions for building agent annotators. These handle the most common annotation patterns – detecting the task type from a Prodigy task dict, formatting an LLM prompt, and parsing the LLM’s JSON response back into the expected annotation format.

from ellf_recipes_sdk import detect_task_type, format_prompt, parse_response

task_type = detect_task_type(task)  # e.g. "spans_manual"
prompt = format_prompt(task, task_type, config)
raw_response = await llm.ask(prompt)  # your LLM call
result = parse_response(raw_response, task, task_type, model_name="my-model")

Annotation task types

Annotation agents currently support the following task types, which determine how the agent should interpret the work and update the JSON.

@service_recipe decorator

Recipe decorator for long-running background services like REST and MCP APIs and web apps. A service recipe returns a ServiceApp – an ASGI application (e.g. a FastAPI, Starlette or FastMCP instance) that the SDK serves under uvicorn – or it returns None and runs its own server, which is how non-ASGI web apps such as Streamlit or JupyterLab are served. There’s also an option to wrap a single endpoint with endpoint_app. Where a task recipe starts an annotation interface for annotators to work in, a service exposes an HTTP API or web app – consumed by machines (IDEs, MCP clients) or opened by people in a browser.

Authentication is handled by the platform, not by your recipe: the cluster rejects unauthenticated requests before they ever reach your code, so the recipe only ever sees authenticated traffic. By default a service accepts platform-issued bearer tokens (see services url) – the right mode for machine callers like MCP clients. Set auth="session" to additionally let logged-in project members open the service in a browser.

from ellf_recipes_sdk import service_recipe, ServiceApp, Secret, TextProps
from fastmcp import FastMCP

@service_recipe(
    title="Pattern Generation MCP Server",
    description="spaCy NER pattern generation, exposed as an MCP server.",
    field_props={
        "model_name": TextProps(title="Gemini model name"),
    },
)
def pattern_gen(*, api_key: Secret, model_name: str = "gemini-2.5-pro") -> ServiceApp:
    mcp = FastMCP("Pattern Generation Server")

    @mcp.tool()
    def initialize_patterns(description: str, entities: list[dict]) -> dict:
        ...  # call the LLM, return spaCy matcher patterns

    return mcp.http_app()  # an ASGI app

ServiceApp type alias

The type expected as the return value of a @service_recipe function. A ServiceApp is an ASGI application – the standard callable that web frameworks expose. FastAPI, Starlette and FastMCP instances all satisfy it, so you return one of those directly rather than implementing the signature yourself. The SDK runner binds uvicorn to the configured port and serves it until the service is stopped.

ServiceApp = Callable[
    [Scope, Receive, Send],  # ASGI connection scope and receive/send channels
    Awaitable[None],
]

from ellf_recipes_sdk import service_recipe, ServiceApp

@service_recipe(title="My API")
def my_api() -> ServiceApp:
    app = build_my_app()
    return app  # a FastAPI / Starlette / FastMCP instance

Recipes that run their own server instead of returning an app (for example Streamlit or JupyterLab) return nothing.

The /health contract required

The cluster polls an HTTP health endpoint to decide when a service is ready to receive traffic and whether to restart it. By default this is GET /health, which needs to return a 2xx status for the pod to become ready. When you return an ASGI app, the SDK mounts a /health responder for you, so the example above works as-is.

You only need to define your own /health route when:

• you want a custom health check, e.g. one that verifies a downstream dependency – add a GET /health route and the SDK leaves it untouched, or
• you’re running your own server, where the SDK doesn’t control it – point healthcheck_path at a path your server already answers (e.g. Streamlit’s /_stcore/health).

Ways to define a service

There are three ways to define a service, from the most common to the most low-level:

1. Return an ASGI app (most common) – build a FastAPI/Starlette/FastMCP app and return it, as in the example above. The SDK serves it and adds /health.
2. Wrap a single function – for one trivial endpoint, endpoint_app turns a handler function into an app, so you don’t build one by hand.
3. Run your own server – for servers that aren’t ASGI apps (Streamlit, JupyterLab), start the server inside the recipe and return nothing – the SDK then keeps the recipe alive instead of serving an app. See running your own server.

endpoint_app function

Wraps a single handler function into a FastAPI ServiceApp, so trivial endpoints don’t require building an app by hand. The handler’s signature is used by FastAPI to parse query and body parameters, exactly as for a normal route.

from ellf_recipes_sdk import service_recipe, ServiceApp, endpoint_app

@service_recipe(title="Greeter", description="A one-route greeting service.")
def greeter() -> ServiceApp:
    async def greet(name: str = "world") -> dict:
        return {"greeting": f"hello {name}"}

    return endpoint_app(greet, path="/greet", methods=["GET"])

Running your own server Advanced usage

Some workloads aren’t ASGI apps and ship their own web server – Streamlit, JupyterLab, a Node process, and so on. For these, start the server inside the recipe and return nothing. The SDK then doesn’t start uvicorn – it just keeps the recipe process alive, so the cluster keeps routing to the server you started. Set port to the port your server listens on, and healthcheck_path to a path it answers, so the cluster routes and health-checks it correctly.

import subprocess
from pathlib import Path
from ellf_recipes_sdk import service_recipe

@service_recipe(
    title="Annotation Dashboard",
    description="A Streamlit dashboard with live inter-annotator agreement.",
    port=8501,
    healthcheck_path="/_stcore/health",
    auth="session",  # people open this in a browser, not via a token
)
def dashboard() -> None:
    app = Path(__file__).parent / "streamlit_app.py"
    subprocess.Popen(
        ["streamlit", "run", str(app), "--server.port", "8501",
         "--server.address", "0.0.0.0", "--server.headless", "true"]
    )
    # Returning nothing tells the runner not to start uvicorn; it just keeps
    # this process (and the Streamlit server it spawned) alive.

Props

Props are Pydantic models that describe the properties of a recipe argument used for auto-generating the UI form fields and command line interface. They can include texts and descriptions that are displayed, optional UI widgets to use, as well as validations to check the input value against to display warnings and error messages. They can be defined as a dictionary keyed by argument name via the field_props argument of the recipe decorator.

TextProps BaseModel

Props for a text field for string inputs.

from ellf_recipes_sdk import TextProps, task_recipe

custom_name = TextProps(
    title="Custom name",
    description="A custom name used in the recipe",
    placeholder="product-launch"
)

@task_recipe(title="My Recipe", field_props={"custom_name": custom_name})
def recipe(*, custom_name: str):
    ...

BoolProps BaseModel

Props for a yes-or-no field and boolean inputs.

from ellf_recipes_sdk import BoolProps, task_recipe

update_model = BoolProps(
    title="Update the model in the loop",
    description="Check this to update the model from annotations",
)

@task_recipe(title="My Recipe", field_props={"update_model": update_model})
def recipe(*, update_model: bool):
    ...

IntProps BaseModel

Props for a number field and integer inputs.

from ellf_recipes_sdk import IntProps

batch_size = IntProps(title="Batch size", min=24, step=8)

@task_recipe(title="My Recipe", field_props={"batch_size": batch_size})
def recipe(*, batch_size: int):
    ...

FloatProps BaseModel

Props for a number field and float inputs.

from ellf_recipes_sdk import FloatProps, task_recipe

learn_rate = FloatProps(title="Learning Rate", min=0.001, step=0.001)

@task_recipe(title="My Recipe", field_props={"learn_rate": learn_rate})
def recipe(*, learn_rate: float):
    ...

ListProps BaseModel

Props for a list field and inputs of type List.

from ellf_recipes_sdk import ListProps, task_recipe

labels = ListProps(
    title="Labels",
    placeholder="PERSON, ORG, ...",
    min=1,
)

@task_recipe(title="My Recipe", field_props={"labels": labels})
def recipe(*, labels: List[str]):
    ...

ChoiceProps BaseModel

Props for a selection field with pre-defined options and inputs of type Union, Enum or a Literal of multiple options.

from ellf_recipes_sdk import ChoiceProps, Props, task_recipe

goal = ChoiceProps(
    title="Data collection goal",
    choice={
        "nooverlap": Props(title="Annotate all examples once"),
        "overlap": Props(title="Annotate with overlap"),
    },
)

@task_recipe(title="My Recipe", field_props={"goal": goal})
def recipe(*, goal: Literal["nooverlap", "overlap"]):
    ...

Props BaseModel

Base class that all specific props types inherit from and that can be used for all other arguments.

Validation BaseModel

Validations are used in the UI form when creating and configuring a task or action. They’re a powerful way to define custom constraints for the expected input and show messages to the user, including errors that prevent the form from being submitted, as well as warnings and info messages to help enforce best practices. Each prop can define one or more validations in order that are interpreted based on the field type, e.g. comparing the length of a list, a string or a number. See the recipe development guide for more details and examples.

validations = [
    Validation(
        op="re",
        value="^[\\w-]+$",
        message="It can contain only numbers, letters, dashes '-' and underscores '_'",
        level="error",
    ),
    Validation(
        op="gt",
        value=20,
        message="It's recommended to use a shorter name (20 characters or less)",
        level="warning",
    )
]

Pre-defined props

Some arguments are very common across recipes, and so are their props. Ellf’s recipe development SDK includes several pre-configured props as variables that you can import and use, so you don’t have to repeat titles, help texts and field settings.

from typing import List
from ellf_recipes_sdk import props, Dataset, InputDataset, Lang

@task_recipe(
    "my-recipe",
    field_props={
        "dataset": props.dataset_new,
        "input_dataset": props.dataset_existing,
        "other_dataset": props.dataset_choice,
        "label": props.label,
        "lang": props.lang,
    }
)
def recipe(
    *,
    dataset: Dataset,
    input_data: InputDataset,
    other_dataset: Dataset,
    label: List[str],
    lang: Lang
):
    ...

Types and dataclasses

Ellf includes a range of pre-defined argument types, usually dataclasses, for common recipe arguments. The recipe will then receive an instance of the dataclass. Dataclasses can also define their own methods, e.g. a load method to load a given asset or dataset.

Dataset dataclass

Type of a new dataset to create by the recipe. It’s a generic type that allows specifying the dataset kind as a parameter, e.g. Dataset[Literal["text"]] for datasets of kind "text". Specifying a kind will also limit the datasets that can be selected in the UI. When used in a recipe, the function will receive an instance of the dataclass.

from typing import Literal
from ellf_recipes_sdk import Dataset, task_recipe

@task_recipe(title="My Recipe")
def recipe(*, dataset: Dataset[Literal["text"]]):
    return {"dataset": dataset.name, ...}

InputDataset dataclass

Type of an existing dataset that’s required to already be in the database, e.g. for datasets used as input data. It’s a generic type that allows specifying the dataset kind as a parameter, e.g. InputDataset[Literal["text"]] for datasets of kind "text". Specifying a kind will also limit the datasets that can be selected in the UI.

from typing import Literal
from ellf_recipes_sdk import InputDataset, task_recipe

@task_recipe(title="My Recipe")
def recipe(*, input_dataset: InputDataset[Literal["text"]]):
    stream = input_dataset.load()

InputDataset.load method

Load the examples from the input dataset. It takes the same keyword arguments as Prodigy’s get_stream and returns a stream of examples.

InputDataset.export method

Export the examples from the dataset as JSONL (newline-delimited JSON).

Asset dataclass

Base class for asset. It’s a generic type that allows specifying the asset kind as a parameter, e.g. Asset[Literal["input"]] for Input. It’s typically not used directly and subclassed for specific asset types (see below). When used in a recipe, the function will receive an instance of the dataclass. See the docs on custom assets for details on how to create your own subclasses.

Input dataclass

Type of an asset used as input for a recipe, e.g. a text source. Subclass of Asset[Literal["input"]].

It’s a generic type that allows specifying the medium the recipe reads as a parameter, e.g. Input[Literal["audio"]] for audio data. The available media are "text", "image", "audio" and "video". Specifying one will limit the assets that can be selected in the UI, so an audio recipe doesn’t offer your text sources and a text recipe doesn’t offer your recordings. A plain Input accepts any input asset.

from typing import Literal
from ellf_recipes_sdk import Input, task_recipe

@task_recipe(title="My Recipe")
def recipe(*, input_data: Input[Literal["text"]]):
    stream = input_data.load()

Input.load method

Load the examples from the input asset. It takes the same keyword arguments as Prodigy’s get_stream and returns a stream of examples.

Input.create classmethod

Register a new input asset record with Ellf. Note that this only creates the record – you need to write the actual files to your cluster’s storage bucket first, e.g. using cloudpathlib.AnyPath. See creating assets in recipes for a full example.

from ellf_recipes_sdk import Input, action_recipe

@action_recipe(title="My Recipe")
def recipe():
    asset = Input.create(name="My asset", path="{__data__}/my_asset", loader="jsonl")

Input.update method

Update an existing input asset with a new version. By default, the original asset version will be incremented as a patch, e.g. 1.2.3 becomes 1.2.4.

from ellf_recipes_sdk import Input, action_recipe

@action_recipe(title="My Recipe")
def recipe(input: Input):
    input.update(path="{__data__}/my_updated_asset")

PdfDocument dataclass

Type of a PDF asset, a folder on your cluster holding the source PDFs, their rendered page images and a manifest describing them. Subclass of Asset[Literal["pdf"]]. The asset is registered by publish data with --kind pdf and made annotation-ready by a preprocessing action, either the built-in Ingest PDFs or your own. Loading it before it has been rendered raises an error telling you to run that step first.

from ellf_recipes_sdk import PdfDocument, task_recipe

@task_recipe(title="My Recipe")
def recipe(*, pdf: PdfDocument):
    handle = pdf.load()
    for doc, page in handle.pages():
        image = handle.image_url(doc["collection_id"], page["n"])

PdfDocument.load method

Read the asset’s manifest and return a PdfHandle for working with its pages. Only the manifest is read, so this stays fast however many documents the asset holds. The pages were already rendered by the preprocessing action, and the handle points at their images by URL instead of loading them.

The handle provides:

PdfLayout dataclass

Type of a layout asset, the text, tokens and layout structure extracted from a PDF asset by the built-in Extract PDF layout action. Subclass of Input with the kind "layout", so it loads the same way. It records the source PDF on every row, which is how PDF Span Annotation shows the rendered page alongside the text without asking for the PDF asset a second time. Having its own kind keeps layout assets out of the pickers meant for annotation data, and vice versa.

from ellf_recipes_sdk import PdfLayout, task_recipe

@task_recipe(title="My Recipe")
def recipe(*, layout: PdfLayout):
    stream = layout.load()

Tessdata dataclass

Type of an asset holding Tesseract .traineddata language files, for OCR in languages that aren’t bundled in the cluster image. Subclass of Asset[Literal["tessdata"]]. The asset can be a single .traineddata file or a directory holding several, and each file name has to match the language code it’s used for. See Custom OCR language data for the workflow.

from typing import Optional
from ellf_recipes_sdk import Tessdata, task_recipe

@task_recipe(title="My Recipe")
def recipe(*, lang: str = "eng", tessdata: Optional[Tessdata] = None):
    tessdata_dir = tessdata.path if tessdata is not None else None

Patterns dataclass

Type of a patterns file, a kind of asset, for recipes that use pattern matching. When loaded, it creates a PatternMatcher instance that you can use on your stream to automatically add annotations from patterns. Subclass of Asset[Literal["patterns"]].

from typing import Literal
from ellf_recipes_sdk import Model, Input, Patterns, task_recipe

@task_recipe(title="My Recipe")
def recipe(*, spacy_model: Model, input_data: Input[Literal["text"]], patterns: Patterns):
    nlp = spacy_model.load()
    stream = input_data.load()
    matcher = patterns.load(nlp=nlp, label="PERSON")
    stream = (eg for _, eg in matcher(stream))

Patterns.load method

Load the patterns and initialize a PatternMatcher that can be used by the recipe. This method takes the same arguments as Prodigy’s PatternMatcher to configure how the patterns should be applied.

Labels dataclass

Type of asset for label schemes, and subclass of Asset[Literal["labels"]]. A label scheme is a JSON file with the labels of a task in order and an optional definition for each: a description, look-alikes not to mark and examples. Loading it returns a LabelScheme.

from typing import Literal, Union
from ellf_recipes_sdk import Labels, LabelScheme, props, task_recipe

@task_recipe(
    title="My Recipe",
    field_props={"label": props.label_scheme},
    cli_names={"label-list": "label", "label-labels": "label-scheme"},
)
def recipe(*, label: Union[list[str], Labels]):
    scheme = LabelScheme.resolve(label)

In a recipe, you’ll usually accept labels as either a list of strings or an asset, using the label_scheme props and LabelScheme.resolve to handle both. The cli_names set --label for the list --label-scheme for the asset, matching the built-in task recipes.

Labels.load method

Load and validate the label scheme. Raises a ValueError for invalid schemes.

LabelScheme dataclass

The labels of a task in order, with their definitions. It’s what Labels.load returns, and it can also be created from a recipe argument that’s either a list of labels or a Labels asset, from a list of label names or from the parsed JSON of a labels file. Passing the definitions to Prodigy as "label_definitions" shows them as tooltips on the labels, and makes them available to the agents assigned to the task.

from typing import Literal, Union
from ellf_recipes_sdk import Labels, LabelScheme, props, task_recipe

@task_recipe(
    title="My Recipe",
    field_props={"label": props.label_scheme},
    cli_names={"label-list": "label", "label-labels": "label-scheme"},
)
def recipe(*, label: Union[list[str], Labels]):
    scheme = LabelScheme.resolve(label)
    # ...
    config = {
        "labels": scheme.names(),
        "label_definitions": scheme.definitions(),
    }

The dataclass also provides the following helper methods:

LabelSpec dataclass

One label of a LabelScheme and its definition. You’ll usually get it from the scheme’s labels or with LabelScheme.get, but you can also create it to build a scheme in code. Everything apart from the name is optional.

from ellf_recipes_sdk import LabelScheme, LabelSpec

person = LabelSpec("PERSON", description="A specific named individual.", do_not_mark=["job titles"])
scheme = LabelScheme([person, LabelSpec("ORG")])
assert scheme.get("ORG").is_defined is False
assert person.to_json() == {"description": "A specific named individual.", "do_not_mark": ["job titles"]}

The dataclass also provides the following helpers:

Instructions dataclass

Type of asset for annotation instructions in Markdown format, and subclass of Asset[Literal["instructions"]]. The instructions will be shown to the annotator in the Prodigy app by clicking the icon in the sidebar or pressing the H key. When an agent is assigned to a task with instructions, the agent can also use them or provide its own.

from ellf_recipes_sdk import Instructions, task_recipe

@task_recipe(title="My Recipe")
def recipe(*, instructions: Instructions):
    config = {"instructions": instructions.load()}

Instructions.load method

Load the instructions as Markdown.

Model dataclass

Type of a spaCy model, a kind of asset uploaded to the cluster. When loaded, it returns the initialized nlp object. Subclass of Asset[Literal["model"]].

from ellf_recipes_sdk import Model, task_recipe

@task_recipe(title="My Recipe")
def recipe(*, spacy_model: Model):
    nlp = spacy_model.load()

Model.load method

Load a spaCy model and initialize the nlp object. Before loading, the model will be downloaded to the worker on your cluster that’s executing the recipe.

HfModel dataclass

Type of a Hugging Face checkpoint on your cluster, i.e. a directory holding a config.json, the weights and the tokenizer files. These assets are created by downloading a model from the Hub or fine-tuning one on your annotations. Subclass of Asset[Literal["hf_model"]]. It’s kept separate from Model because it can’t be loaded as a spaCy pipeline. Loading it returns the checkpoint directory instead, which you can pass to transformers.

from transformers import pipeline
from ellf_recipes_sdk import HfModel, action_recipe

@action_recipe(title="My Recipe")
def recipe(*, model: HfModel):
    path = model.load()
    classifier = pipeline("text-classification", model=str(path))

HfModel.load method

Get the checkpoint directory on the worker executing the recipe. If the asset is stored in a cloud storage bucket, it’s downloaded first. Raises an error if the directory isn’t a Hugging Face checkpoint, i.e. has no config.json.

HfHubModel dataclass

Pre-defined custom type for a model on the Hugging Face Hub, referenced by its repo ID and downloaded when the job runs. Can be used as part of a Union type with HfModel so the user can choose between a model on the Hub and a checkpoint already on the cluster, like the built-in Hugging Face model agent does.

from typing import Union
from huggingface_hub import snapshot_download
from ellf_recipes_sdk import HfHubModel, HfModel, action_recipe

@action_recipe(title="My Recipe")
def recipe(*, model: Union[HfHubModel, HfModel]):
    if isinstance(model, HfHubModel):
        path = snapshot_download(repo_id=model.repo_id, revision=model.revision)
    else:
        path = model.load()

BlankModel dataclass

Create a blank nlp object for one of the available spaCy languages for tokenization or training a new pipeline. The language to use is a field of the type and can be set in the UI or on the CLI when a task or action is created from the recipe.

from ellf_recipes_sdk import BlankModel, task_recipe

@task_recipe(title="My Recipe")
def recipe(*, spacy_model: BlankModel):
    nlp = spacy_model.load()
    print(f"Created blank model for {spacy_model.lang}")

BlankModel.load method

Initialize a blank nlp object.

UseModel dataclass

Pre-defined custom type for recipes that use a model to pre-annotate data. Combines the model name and a boolean setting whether it should be updated in the loop (which needs to be implemented in the recipe). Can also be used as part of a Union type with BlankModel so the user can choose between a pretrained pipeline or a blank model.

from typing import Union
from ellf_recipes_sdk import UseModel, BlankModel, task_recipe

@task_recipe(title="My Recipe")
def recipe(*, spacy_model: Union[UseModel, BlankModel]):
    nlp = spacy_model.load()
    if isinstance(spacy_model, UseModel) and spacy_model.update:
        # Implement logic to update the model in the loop
        ...

Lang enum

Enum of all available spaCy languages that can be initialized with spacy.blank, e.g. for tokenization or training a new pipeline.

from ellf_recipes_sdk import Lang, task_recipe
import spacy

@task_recipe(title="My Recipe")
def recipe(*, lang: Lang = Lang.en):
    nlp = spacy.blank(lang)

Secret dataclass

Secrets are pointers to API keys or other credentials and let you securely manage access across your organization. If your recipe needs to connect to an API or authenticate with a service, you shouldn’t ever have your user provide their credentials in the web form or CLI. Instead, you can use the Secret type so you’ll be able to select an existing secret, which is then passed to your recipe function. A secret can also be optional, for recipes that work without one, e.g. when only reading public data. If the user doesn’t select a secret, the argument is None.

from ellf_recipes_sdk import agent_recipe, Secret

@agent_recipe(title="My Recipe")
def recipe(*, api_key: Secret):
    gemini_key = api_key.value()
    llm = Gemini(api_key=gemini_key, model_name="gemini-2.0-flash")

Secret.value method

Get the plain-text value of a secret. This is what should be passed to API calls and other libraries that require keys to authenticate, for example in agent recipes. The value is resolved automatically based on the recipe parameter the secret was bound to – you don’t need to know the internal storage key.

AnnotationSettings dataclass

A combined settings block to configure the annotation process, like instructions, overlap and annotation interface, including config overrides for Prodigy. By default, it will add an expandable section to the recipe form in the UI.

from ellf_recipes_sdk import task_recipe, AnnotationSettings

@task_recipe(title="My Recipe")
def recipe(*, labels: list[str], settings: AnnotationSettings = AnnotationSettings()):
    return {
        # ...
        "exclude": settings.exclude_names,
        "config": settings.prodigy_config(labels=label)
    }

The dataclass also provides the following helper properties and methods:

AgentSettings dataclass

A combined settings block to configure how an agent annotates, analogous to AnnotationSettings for tasks. It lets you give the agent its own instructions on top of the annotation instructions of the task it’s assigned to, which are included by default.

from ellf_recipes_sdk import agent_recipe, AgentSettings, Annotator, detect_task_type, format_prompt, parse_response

@agent_recipe(title="My Recipe")
def my_agent(*, model: str, settings: AgentSettings = AgentSettings()) -> Annotator:
    client = setup_llm(model)
    settings.load_instructions()

    async def annotate(task: dict, config: dict) -> dict:
        task_type = detect_task_type(task)
        prompt = format_prompt(task, task_type, settings.prompt_config(config))
        raw = await client.ask(prompt)
        return parse_response(raw, task, task_type, model_name=model)

    return annotate

The dataclass also provides the following helper methods:

AgentLabels dataclass

A settings block for the label definitions an agent uses in its prompts. Tasks that use a label scheme pass their definitions on as "label_definitions" in their config, and they’re used by default. The agent can add its own scheme on top, whose definitions replace the task’s for the labels it defines. The agent always annotates the task’s labels – all other labels in the agent’s scheme are ignored.

from ellf_recipes_sdk import agent_recipe, AgentLabels, AgentSettings, Annotator, detect_task_type, format_prompt, parse_response

@agent_recipe(title="My Recipe")
def my_agent(
    *, model: str,
    labels: AgentLabels = AgentLabels(),
    settings: AgentSettings = AgentSettings(),
) -> Annotator:
    client = setup_llm(model)

    async def annotate(task: dict, config: dict) -> dict:
        task_type = detect_task_type(task)
        prompt_config = labels.prompt_config(settings.prompt_config(config))
        prompt = format_prompt(task, task_type, prompt_config)
        raw = await client.ask(prompt)
        return parse_response(raw, task, task_type, model_name=model)

    return annotate

The dataclass also provides the following helper methods:

@ellf_type decorator

Decorator to register dataclasses as custom types. Dataclasses can define one or more custom subfields and an instance of the dataclass will be passed to the recipe function if it’s used as a type annotation. Custom types can also be used as part of a union. The metadata defined in the decorator is propagated and merged to child classes that are also annotated with @ellf_type. See the recipe development guide and custom assets for more details and examples.

from typing import Literal, Optional
from dataclasses import dataclass
from ellf_recipes_sdk import ellf_type, IntProps

@ellf_type(
    "workflow-settings",
    title="Customize annotation workflow",
    field_props={"annotations_per_task": IntProps(optional_title="Configure annotations per task")}
)
@dataclass
class WorkflowSettings:
    feed_overlap: Literal["nooverlap", "overlap"] = "nooverlap"
    annotations_per_task: Optional[int] = None
    allow_work_stealing: bool = True
    instructions: str = ""