Pydantic & Smart Unboxing

Flatten agent parameters and auto-instantiate Pydantic models.

Type Hints and Pydantic

Elemm automatically generates JSON schemas from Python type hints. For complex inputs, you can use Pydantic models.

❗ IMPORTANT

Single Request Pattern: Elemm's automatic wrapping ("Smart Unboxing" to the agent and auto-instantiation before handler execution) is active only if the function has exactly one parameter of type BaseModel.

Recommended: Single Request Pattern

Define a single Pydantic model for all parameters. Elemm will unbox it for the agent (so the agent sees individual parameters) and automatically wrap it back into the model before calling your function:

python

from pydantic import BaseModel

class CreateInstanceRequest(BaseModel):
    name: str
    image: str = "ubuntu-24.04"
    cpu_cores: int = 2
    memory_gb: int = 4

@manager.landmark("compute:create_instance")
def create_instance(request: CreateInstanceRequest):
    # 'request' is automatically instantiated as a CreateInstanceRequest object
    return {"name": request.name, "specs": request.model_dump(exclude={"name"})}

Alternative: Multiple Parameters

If you have multiple parameters and one of them is a Pydantic model (or dict), Python receives a standard dict at runtime. You must manually instantiate the model if you want to use its methods:

python

class InstanceConfig(BaseModel):
    image: str = "ubuntu-24.04"
    cpu_cores: int = 2

@manager.landmark("compute:create_instance")
def create_instance(name: str, config: dict):
    # Manually instantiate if needed:
    config_obj = InstanceConfig(**config)
    return {"name": name, "specs": config_obj.model_dump()}

Supported type mappings:

str -> string
int -> integer
float -> number
bool -> boolean
list -> array
dict -> object
Pydantic models -> Full JSON Schema definitions