devplacepy/devplacepy/services/devii/agentic/actions.py

# retoor <retoor@molodetz.nl>

from __future__ import annotations

from ..actions.spec import Action, Param


def arg(
    name: str, description: str, required: bool = False, kind: str = "string"
) -> Param:
    return Param(
        name=name,
        location="body",
        description=description,
        required=required,
        type=kind,
    )


AGENTIC_ACTIONS: tuple[Action, ...] = (
    Action(
        name="plan",
        method="LOCAL",
        path="",
        summary="Record the structured execution plan for the current request",
        description="Must be the very first tool call when a request requires any tool use.",
        handler="agentic",
        requires_auth=False,
        params=(
            arg("goal", "One-line restatement of the user's goal.", required=True),
            arg(
                "steps",
                "Ordered list of step objects, each with id, action, depends_on.",
                required=True,
                kind="array",
            ),
            arg(
                "success_criteria",
                "Concrete criteria for declaring the task complete.",
                required=True,
            ),
            arg(
                "confidence",
                "Self-estimate of plan correctness from 0.0 to 1.0.",
                kind="number",
            ),
        ),
    ),
    Action(
        name="reflect",
        method="LOCAL",
        path="",
        summary="Record a reflection and persist it as a reusable lesson for future requests",
        description="Call after any tool error and at the end of a non-trivial task to learn from it.",
        handler="agentic",
        requires_auth=False,
        params=(
            arg(
                "observation",
                "What was observed: the failure mode or notable outcome.",
                required=True,
            ),
            arg(
                "conclusion",
                "Diagnosis or interpretation of the observation.",
                required=True,
            ),
            arg(
                "next_action",
                "The chosen next step or the rule to apply in future.",
                required=True,
            ),
            arg("tags", "Optional comma-separated keywords to aid later recall."),
        ),
    ),
    Action(
        name="recall",
        method="LOCAL",
        path="",
        summary="Retrieve relevant lessons learned from past requests",
        description="Search the persistent lesson memory for guidance before acting on unfamiliar work.",
        handler="agentic",
        requires_auth=False,
        params=(
            arg(
                "query",
                "Natural-language or keyword query describing the current situation.",
                required=True,
            ),
            arg("k", "Number of lessons to return.", kind="integer"),
        ),
    ),
    Action(
        name="forget_lessons",
        method="LOCAL",
        path="",
        summary="Permanently delete learned lessons from your private memory",
        description=(
            "Removes lessons you previously stored with reflect(). With a query, only matching "
            "lessons are deleted; with no query, all of them are. Use this when the user asks you "
            "to forget something. Your lesson memory is private to this account or guest session."
        ),
        handler="agentic",
        requires_auth=False,
        params=(
            arg(
                "query",
                "Optional topic/keywords; only matching lessons are forgotten. Omit to forget everything.",
            ),
        ),
    ),
    Action(
        name="verify",
        method="LOCAL",
        path="",
        summary="Confirm that a change took effect, satisfying the verification gate",
        description=(
            "After mutating actions (create, edit, delete, vote, follow, admin changes), confirm "
            "the result, then call this with a summary of what you confirmed."
        ),
        handler="agentic",
        requires_auth=False,
        params=(
            arg("summary", "What was confirmed and how.", required=True),
            arg(
                "confirmed",
                "Whether the change was confirmed successful.",
                kind="boolean",
            ),
        ),
    ),
    Action(
        name="delegate",
        method="LOCAL",
        path="",
        summary="Spawn a focused sub-agent to complete a self-contained sub-task in isolation",
        description="The sub-agent runs its own plan/act/verify loop and returns a concise result.",
        handler="agentic",
        requires_auth=False,
        params=(
            arg(
                "task",
                "Clear, scoped task description for the sub-agent.",
                required=True,
            ),
            arg(
                "allowed_tools",
                "Optional list of tool names the sub-agent may use.",
                kind="array",
            ),
        ),
    ),
    Action(
        name="lesson_rate",
        method="LOCAL",
        path="",
        summary="Vote on a lesson's quality to help the system keep the best ones and drop bad ones",
        description=(
            "Rate a lesson recorded by reflect(). A positive vote (1) marks it as useful; "
            "a negative vote (-1) marks it as unhelpful. Lessons with a cumulative rating of "
            "-3 or lower are excluded from recall() results. Use this when you notice a lesson "
            "was particularly helpful or misleading."
        ),
        handler="agentic",
        requires_auth=False,
        params=(
            arg("uid", "The uid of the lesson to rate, from a recall() result.", required=True),
            arg("value", "1 for useful, -1 for unhelpful.", required=True, kind="integer"),
        ),
    ),
    Action(
        name="lesson_count",
        method="LOCAL",
        path="",
        summary="Report how many learned lessons are stored for this session or account",
        description="Returns the number of active lessons with an optional per-tag breakdown.",
        handler="agentic",
        requires_auth=False,
        params=(),
    ),
    Action(
        name="eval",
        method="LOCAL",
        path="",
        summary="Run a prompt through a fresh Devii sub-agent and return its result (self-evaluation)",
        description=(
            "Executes the given prompt as if it were a new request to yourself, with full tool "
            "access, and returns the result. This is the engine behind user-defined tools. Nesting is "
            "limited, so do not build deep self-calling chains."
        ),
        handler="agentic",
        requires_auth=False,
        params=(
            arg(
                "prompt",
                "The instruction to run as a fresh sub-agent request.",
                required=True,
            ),
        ),
    ),
)