AI query plans

Experimental

Aksara does not expose a QueryEngine class that turns natural language into database queries. The real API executes a structured AiQueryPlan.

An external model or application may construct a validated plan:

from aksara.ai.query import (
    AiFilterCondition,
    AiQueryPagination,
    AiQueryPlan,
    AiSortField,
    execute_ai_query_plan,
)

plan = AiQueryPlan(
    model="Task",
    filters=[AiFilterCondition(field="done", lookup="exact", value=False)],
    sorting=[AiSortField(field="created_at", direction="desc")],
    pagination=AiQueryPagination(limit=20, offset=0),
    select_fields=["id", "title", "done"],
)
result = await execute_ai_query_plan(plan)
print(result.rows)

The executor resolves a registered model, validates field names and supported lookups, applies ORM filters and ordering, and returns serialized rows. It does not parse natural language or call an LLM. It currently fetches all matching rows before slicing the result in Python. pagination.limit bounds returned rows, not database work or memory use; do not treat it as a query resource limit.

This low-level helper does not receive a request Principal; do not expose it directly to untrusted callers. Application code must establish authorization, field visibility, and tenant context first. Generated REST and MCP routes are the stable policy-enforced public execution paths.