pascal-agent 0.3.0__py3-none-any.whl

pascal/schemas.py

@@ -0,0 +1,183 @@
+"""Tool schemas for Pascal Function Calling.
+
+Used by loop.py to pass actual tool definitions to the LLM instead of tools=[].
+Each schema maps to one action in actions.py.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+
+ToolPreset = Literal["minimal", "standard", "full"]
+
+_MINIMAL_TOOL_NAMES = (
+    "think",
+    "pick_task",
+    "handle_notification",
+    "dismiss_notification",
+    "create_task",
+    "execute",
+    "wait",
+    "escalate",
+)
+
+_STANDARD_TOOL_NAMES = _MINIMAL_TOOL_NAMES + (
+    "plan",
+    "delegate",
+    "complete_task",
+    "fail_task",
+    "pause_task",
+    "block_task",
+    "create_subtask",
+    "add_todo",
+    "complete_todo",
+    "memorize",
+    "add_rule",
+    "remove_rule",
+    "set_context",
+)
+
+_TOOL_PRESETS: dict[ToolPreset, frozenset[str]] = {
+    "minimal": frozenset(_MINIMAL_TOOL_NAMES),
+    "standard": frozenset(_STANDARD_TOOL_NAMES),
+    # FULL uses the same Pascal action schemas as STANDARD. loop.py adds
+    # the desktop/UIA guidance to the system prompt when FULL is selected.
+    "full": frozenset(_STANDARD_TOOL_NAMES),
+}
+
+
+def build_tool_schemas(*, preset: ToolPreset = "standard") -> list[dict[str, Any]]:
+    """Build the Pascal tool list for the selected LLM preset.
+
+    Returns OpenAI-compatible tool definitions. Each tool corresponds to
+    one Pascal action (think, execute, plan, etc.).
+    """
+    try:
+        allowed_names = _TOOL_PRESETS[preset]
+    except KeyError as exc:
+        raise ValueError(f"Unknown tool preset: {preset}") from exc
+    return [tool for tool in _PASCAL_TOOLS if tool["function"]["name"] in allowed_names]
+
+
+def _tool(name: str, description: str, properties: dict, required: list[str] | None = None) -> dict:
+    """Helper to build one OpenAI-compatible tool definition."""
+    return {
+        "type": "function",
+        "function": {
+            "name": name,
+            "description": description,
+            "parameters": {
+                "type": "object",
+                "properties": properties,
+                "required": required or [],
+            },
+        },
+    }
+
+
+_PASCAL_TOOLS: list[dict[str, Any]] = [
+    _tool("think", "Reason about the current situation before acting.", {
+        "thought": {"type": "string", "description": "Your reasoning"},
+    }, ["thought"]),
+
+    _tool("execute", "Execute a shell command, built-in/MCP tool, or Python code snippet.", {
+        "command": {"type": "string", "description": "Shell command to run"},
+        "tool": {"type": "string", "description": "Tool name (mutually exclusive with command)"},
+        "tool_params": {"type": "object", "description": "Parameters for the tool"},
+        "code": {"type": "string", "description": "Python code to run in sandbox (for data processing, file ops — more efficient than multiple tool calls)"},
+        "reason": {"type": "string"},
+    }),
+
+    _tool("plan", "Create or patch a multi-step execution plan.", {
+        "reason": {"type": "string"},
+        "plan_tree": {"type": "object", "description": "Plan tree: {id, kind, title, children, done_when, action}"},
+        "steps": {"type": "array", "description": "Legacy flat steps array (auto-wrapped into tree)", "items": {"type": "object"}},
+        "patch_node_id": {"type": "string", "description": "Failed node ID to repair in existing plan"},
+    }, ["reason"]),
+
+    _tool("delegate", "Delegate a task to Claude Code or Codex CLI.", {
+        "tool": {"type": "string", "enum": ["claude-code", "codex"], "description": "Which agent to delegate to"},
+        "task": {"type": "string", "description": "Task description for the delegate"},
+        "context": {"type": "string", "description": "Additional context"},
+        "success_criteria": {"type": "string"},
+        "timeout": {"type": "integer", "description": "Timeout in seconds (max 600)"},
+    }, ["tool", "task"]),
+
+    _tool("pick_task", "Activate a pending task to work on.", {
+        "task_id": {"type": "string", "description": "ID of the task to activate"},
+        "reason": {"type": "string"},
+    }, ["task_id"]),
+
+    _tool("create_task", "Create a new task.", {
+        "goal": {"type": "string", "description": "What the task should accomplish"},
+        "priority": {"type": "string", "enum": ["urgent", "normal", "low"]},
+        "estimated_effect": {"type": "string", "description": "E0-E5 effect level"},
+    }, ["goal"]),
+
+    _tool("create_subtask", "Create a subtask under the active task.", {
+        "subtask_goal": {"type": "string"},
+        "subtask_priority": {"type": "string", "enum": ["urgent", "normal", "low"]},
+    }, ["subtask_goal"]),
+
+    _tool("handle_notification", "Handle a pending notification.", {
+        "notification_id": {"type": "string"},
+        "response": {"type": "string", "description": "Internal note about how you handled it"},
+        "reply_text": {"type": "string", "description": "Text to send back to the human (or NO_REPLY)"},
+    }, ["notification_id"]),
+
+    _tool("dismiss_notification", "Dismiss a notification without handling.", {
+        "notification_id": {"type": "string"},
+    }, ["notification_id"]),
+
+    _tool("pause_task", "Pause the current active task.", {
+        "pause_reason": {"type": "string"},
+    }),
+
+    _tool("block_task", "Block the current active task (waiting for external input).", {
+        "reason": {"type": "string"},
+    }),
+
+    _tool("fail_task", "Mark the current active task as failed.", {
+        "reason": {"type": "string"},
+    }, ["reason"]),
+
+    _tool("complete_task", "Mark the current active task as done.", {
+        "summary": {"type": "string", "description": "What was accomplished"},
+    }, ["summary"]),
+
+    _tool("add_todo", "Add a TODO item to the active task.", {
+        "todo_title": {"type": "string"},
+    }, ["todo_title"]),
+
+    _tool("complete_todo", "Mark a TODO item as done.", {
+        "todo_id": {"type": "string"},
+    }, ["todo_id"]),
+
+    _tool("memorize", "Save a memory for future reference.", {
+        "memory_kind": {"type": "string", "enum": ["fact", "lesson", "preference", "procedure"]},
+        "memory_content": {"type": "string"},
+    }, ["memory_kind", "memory_content"]),
+
+    _tool("add_rule", "Add a behavior rule.", {
+        "rule": {"type": "string"},
+    }, ["rule"]),
+
+    _tool("remove_rule", "Remove a mutable rule.", {
+        "rule_id": {"type": "string"},
+    }, ["rule_id"]),
+
+    _tool("set_context", "Set a working memory key-value pair.", {
+        "key": {"type": "string"},
+        "value": {},  # any type
+        "ttl_hours": {"type": "number", "description": "Optional TTL in hours"},
+    }, ["key", "value"]),
+
+    _tool("wait", "Do nothing and wait for new events.", {
+        "wait_reason": {"type": "string"},
+    }),
+
+    _tool("escalate", "Ask a human for help.", {
+        "question": {"type": "string", "description": "What you need help with"},
+    }, ["question"]),
+]