Building Landmark Servers

Overview

The AIProtocolManager (aliased as ElemmGateway) is your primary interface. It allows you to register Python functions as "Actions" within specific "Landmarks".

Defining Actions with Decorators

from elemm import AIProtocolManager, MetadataRegistry

registry = MetadataRegistry("landmarks.yaml")
manager = AIProtocolManager(registry=registry)

@manager.landmark("compute:toggle_power")
async def toggle_power(instance_id: str, state: str):
    """Control the power state of a virtual machine."""
    return {"status": "success", "instance": instance_id, "new_state": state}

Advanced Decorator Options (Remedies & Instructions)

You can pass extra metadata directly into the decorator to guide the AI when errors occur or when it inspects the landmark.

@manager.landmark(
    "compute:delete_instance",
    description="Deletes a virtual machine permanently.",
    remedy="If an instance is not found, use compute:list_instances to check available IDs.",
    instructions="ALWAYS prompt the user for confirmation before calling this tool.",
    method="DELETE"
)
async def delete_instance(instance_id: str):
    # Implementation...
    pass

• remedy: A string that is dynamically attached to error responses (via the SmartRepair engine) if this tool fails. It guides the LLM on what to do next.
• instructions: Behavioral guidelines injected when the agent inspects this landmark.
• method: HTTP Method or operational mode (useful for security policies).
• returns / response_schema: Explicit overrides for the return type if Pydantic isn't enough.