1use super::function_card::{ArgumentInfo, FunctionCard};
8
9pub const TASK_CARDS: &[FunctionCard] = &[
11 FunctionCard {
13 identifier: "task",
14 signature: "task(name, description)",
15 brief: "Create a new task with optional description.",
16 description: "Creates a new task primitive representing a unit of work in an agentic \
17 workflow. Tasks have a name and optional description, and can be marked \
18 as pending, completed, or failed. Tasks support special numeric semantics: \
19 completed tasks evaluate to 1.0, failed tasks to -1.0, and pending tasks \
20 to 0.0. This makes them useful for mathematical operations and progress \
21 tracking in workflows.",
22 arguments: &[
23 &ArgumentInfo {
24 label: "name",
25 description: "Task identifier/name",
26 type_hint: "Arc<str>",
27 optional: false,
28 },
29 &ArgumentInfo {
30 label: "description",
31 description: "Optional task description",
32 type_hint: "Arc<str>",
33 optional: true,
34 },
35 ],
36 returns: "New task value with pending status",
37 errors: "None - always succeeds",
38 categories: &["task", "agentic"],
39 examples: &[
40 r#"task("data_import", "Import customer data")"#,
41 r#"task("validate", "Validate data integrity")"#,
42 r#"task("process", "Process imported data")"#,
43 ],
44 },
45
46 FunctionCard {
48 identifier: "done",
49 signature: "task.done()",
50 brief: "Mark a task as completed.",
51 description: "Updates the status of a task to completed (Some(true)). Completed \
52 tasks have a numeric value of 1.0, making them useful for counting \
53 completed work items or calculating completion percentages. This \
54 function is typically used after successfully executing a task or \
55 when marking a task as finished in a workflow.",
56 arguments: &[
57 &ArgumentInfo {
58 label: "task",
59 description: "Task to mark as completed",
60 type_hint: "Task",
61 optional: false,
62 },
63 ],
64 returns: "Task with completed status",
65 errors: "Returns error if input is not a valid task",
66 categories: &["task", "status"],
67 examples: &[
68 r#"done(task("test", "Test task"))"#,
69 r#"task("validate").done() => {"name": "validate", "status": "completed"}"#,
70 r#"tasks.perform(3, task => done(task))"#,
71 ],
72 },
73
74 FunctionCard {
76 identifier: "pending",
77 signature: "task.pending()",
78 brief: "Mark a task as pending.",
79 description: "Updates the status of a task to pending (None). Pending tasks \
80 have a numeric value of 0.0, representing work that has not yet \
81 been started or is waiting to be completed. This function is \
82 useful for resetting task status or initializing tasks in a \
83 workflow before execution.",
84 arguments: &[
85 &ArgumentInfo {
86 label: "task",
87 description: "Task to mark as pending",
88 type_hint: "Task",
89 optional: false,
90 },
91 ],
92 returns: "Task with pending status",
93 errors: "Returns error if input is not a valid task",
94 categories: &["task", "status"],
95 examples: &[
96 r#"pending(task("test", "Test task"))"#,
97 r#"task("validate").pending() => {"name": "validate", "status": "pending"}"#,
98 r#"tasks.map(task => pending(task))"#,
99 ],
100 },
101
102 FunctionCard {
104 identifier: "failed",
105 signature: "task.failed()",
106 brief: "Mark a task as failed.",
107 description: "Updates the status of a task to failed (Some(false)). Failed \
108 tasks have a numeric value of -1.0, making them useful for \
109 tracking errors or counting failed attempts. This function \
110 is typically used when a task cannot be completed successfully \
111 or when marking a task as failed after an error occurs.",
112 arguments: &[
113 &ArgumentInfo {
114 label: "task",
115 description: "Task to mark as failed",
116 type_hint: "Task",
117 optional: false,
118 },
119 ],
120 returns: "Task with failed status",
121 errors: "Returns error if input is not a valid task",
122 categories: &["task", "status"],
123 examples: &[
124 r#"failed(task("test", "Test task"))"#,
125 r#"task("validate").failed() => {"name": "validate", "status": "failed"}"#,
126 r#"tasks.filter(task => failed(task))"#,
127 ],
128 },
129
130 FunctionCard {
132 identifier: "perform",
133 signature: "tasks.perform(attempts, closure)",
134 brief: "Execute pending tasks with retry logic.",
135 description: "Processes an array of tasks, attempting to complete each pending \
136 task using the provided closure. Tasks that are already completed \
137 or failed are passed through unchanged. For pending tasks, the \
138 closure is invoked up to the specified number of attempts. If a \
139 task remains pending after all attempts, it is marked as failed. \
140 This function is essential for robust workflow execution with \
141 error handling and recovery.",
142 arguments: &[
143 &ArgumentInfo {
144 label: "tasks",
145 description: "Array of tasks to execute",
146 type_hint: "Array<Task>",
147 optional: false,
148 },
149 &ArgumentInfo {
150 label: "attempts",
151 description: "Maximum number of retry attempts per task",
152 type_hint: "f64",
153 optional: false,
154 },
155 &ArgumentInfo {
156 label: "closure",
157 description: "Closure to execute for each pending task",
158 type_hint: "Closure",
159 optional: false,
160 },
161 ],
162 returns: "Array of tasks with updated statuses",
163 errors: "Returns error if inputs are invalid types",
164 categories: &["task", "workflow", "agentic"],
165 examples: &[
166 r#"perform((task("validate"), task("process")), 3, task => attempt_completion(task))"#,
167 r#"tasks.perform(3, task => done(task))"#,
168 r#"pending_tasks.perform(5, task => { if can_complete(task) { done(task) } else { failed(task) } })"#,
169 ],
170 },
171
172 FunctionCard {
174 identifier: "follow",
175 signature: "plans.follow(closure)",
176 brief: "Execute task plans sequentially with iterative processing.",
177 description: "Processes a task array by repeatedly applying a closure to the \
178 entire array until all tasks are completed/failed or the retry \
179 limit is reached. Unlike perform which processes tasks individually, \
180 follow works with the entire plan as a unit, allowing the closure \
181 to process tasks in context of each other. This is particularly \
182 useful for workflow orchestration where tasks depend on each other, \
183 batch processing of related tasks, or plan execution with mutual \
184 dependencies. The retry limit is automatically set to the number \
185 of originally pending tasks to prevent infinite loops.",
186 arguments: &[
187 &ArgumentInfo {
188 label: "plans",
189 description: "Array of task plans to execute",
190 type_hint: "Array<Task>",
191 optional: false,
192 },
193 &ArgumentInfo {
194 label: "closure",
195 description: "Closure to process the entire task array",
196 type_hint: "Closure",
197 optional: false,
198 },
199 ],
200 returns: "Array of tasks with updated statuses",
201 errors: "Returns error if inputs are invalid types",
202 categories: &["task", "workflow", "agentic"],
203 examples: &[
204 r#"follow(((task("step1"), task("step2"))), plan => execute_plan(plan))"#,
205 r#"plan.follow(plan => { plan.map(task => if pending(task) { done(task) } else { task }) })"#,
206 r#"workflow.follow(plan => process_dependencies(plan))"#,
207 ],
208 },
209];