Intent

An Intent is a frozen dataclass that declares what you want to achieve. It is pure data — the runtime reads it and decides what to do.

Structure

from evoid import Intent, Level

MY_INTENT = Intent(
    name="get_user",
    level=Level.STANDARD,
    metadata={"method": "GET", "path": "/users/{id}"},
    timeout=10.0,
    priority=0,
)

Intent Levels

Creating Intents

Explicit (Native Style)

from evoid import Intent, Level, add_intent

PAYMENT = Intent(
    name="process_payment",
    level=Level.CRITICAL,
    metadata={"currency": "USD"},
)

async def handle_payment(intent: Intent) -> dict:
    return {"status": "processed"}

add_intent(PAYMENT, handle_payment)

Implicit (@route Style)

from evoid.web.route import Service, get

app = Service("my-api")

@get("/users/{user_id}", level="critical")
async def get_user(user_id: int) -> dict:
    return {"id": user_id}

The decorator creates:

• name: GET:/users/{user_id}
• level: Level.CRITICAL
• metadata: {"method": "GET", "path": "/users/{user_id}"}

Implicit (@controller Style)

from evoid.web.controller import Service, Controller, GET

app = Service("my-api")

@Controller("/users")
class UserController:
    @GET("/{user_id}", level="critical")
    async def get_user(self, user_id: int) -> dict:
        return {"id": user_id}

Intent Metadata

Metadata passes data to processors:

INTENT = Intent(
    name="send_email",
    level=Level.STANDARD,
    metadata={
        "priority": "high",
        "retry": 3,
        "timeout": 30,
        "template": "welcome",
    },
)

async def handle(intent: Intent) -> dict:
    priority = intent.metadata.get("priority", "normal")
    retries = intent.metadata.get("retry", 1)
    return {"sent": True, "priority": priority}

Lifecycle

Declaration (you create Intent)
    |
Registration (intent stored in registry)
    |
Resolution (runtime maps intent to PipelineConfig)
    |
Execution (pipeline runs processors in order)
    |
Result (success/failure with value and timing)

Inspecting Registered Intents

from evoid import all_intents

intents = all_intents()
for name, intent in intents.items():
    print(f"{name} [{intent.level.value}]")

Best Practices

• Use meaningful names — get_user over handler1
• Choose appropriate levels — Marking everything critical defeats the purpose
• Include useful metadata — Processors use it for decisions
• Keep Intents focused — One intent, one responsibility
• Set timeouts — Prevent runaway processors

Related

• Pipeline — How intents become pipelines
• Processors — Functions that handle intents