use serde_json::{Map, Value};
use crate::error::Result;
use super::def::AgentDef;
use super::tool::ToolDef;
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Ref {
pub step_id: String,
}
impl Ref {
pub fn new(step_id: impl Into<String>) -> Self {
Self {
step_id: step_id.into(),
}
}
#[must_use]
pub fn to_value(&self) -> Value {
serde_json::json!({"$ref": self.step_id})
}
}
impl From<Ref> for Value {
fn from(r: Ref) -> Value {
r.to_value()
}
}
#[derive(Debug, Clone, PartialEq)]
pub struct Context {
text: Option<String>,
url: Option<String>,
headers: std::collections::HashMap<String, String>,
required: bool,
max_bytes: u32,
}
impl Context {
pub fn text(text: impl Into<String>) -> Self {
Self {
text: Some(text.into()),
url: None,
headers: std::collections::HashMap::new(),
required: true,
max_bytes: 0x4000,
}
}
pub fn url(url: impl Into<String>) -> Self {
Self {
text: None,
url: Some(url.into()),
headers: std::collections::HashMap::new(),
required: true,
max_bytes: 0x4000,
}
}
#[must_use]
pub fn with_headers(mut self, headers: std::collections::HashMap<String, String>) -> Self {
self.headers = headers;
self
}
#[must_use]
pub fn with_required(mut self, required: bool) -> Self {
self.required = required;
self
}
#[must_use]
pub fn with_max_bytes(mut self, max_bytes: u32) -> Self {
self.max_bytes = max_bytes;
self
}
#[must_use]
pub fn to_value(&self) -> Value {
let mut map = Map::new();
if let Some(text) = &self.text {
map.insert("text".to_owned(), Value::String(text.clone()));
}
if let Some(url) = &self.url {
map.insert("url".to_owned(), Value::String(url.clone()));
if !self.headers.is_empty() {
let headers = self
.headers
.iter()
.map(|(k, v)| (k.clone(), Value::String(v.clone())))
.collect();
map.insert("headers".to_owned(), Value::Object(headers));
}
if !self.required {
map.insert("required".to_owned(), Value::Bool(false));
}
if self.max_bytes != 0x4000 {
map.insert("maxBytes".to_owned(), Value::from(self.max_bytes));
}
}
Value::Object(map)
}
}
#[derive(Debug, Clone, PartialEq)]
pub struct Generate {
pub instructions: String,
pub output_schema: String,
pub max_tokens: Option<u32>,
pub context: Option<Value>,
}
impl Generate {
pub fn new(instructions: impl Into<String>, output_schema: impl Into<String>) -> Self {
Self {
instructions: instructions.into(),
output_schema: output_schema.into(),
max_tokens: None,
context: None,
}
}
#[must_use]
pub fn with_max_tokens(mut self, max_tokens: u32) -> Self {
self.max_tokens = Some(max_tokens);
self
}
#[must_use]
pub fn with_context(mut self, context: impl Into<Value>) -> Self {
self.context = Some(context.into());
self
}
fn to_value(&self) -> Value {
let mut map = Map::new();
map.insert(
"instructions".to_owned(),
Value::String(self.instructions.clone()),
);
map.insert(
"output_schema".to_owned(),
Value::String(self.output_schema.clone()),
);
if let Some(max_tokens) = self.max_tokens {
map.insert("max_tokens".to_owned(), Value::from(max_tokens));
}
if let Some(context) = &self.context {
map.insert("context".to_owned(), context.clone());
}
Value::Object(map)
}
}
#[derive(Debug, Clone, PartialEq)]
pub enum OpBody {
Args(Value),
Generate(Generate),
}
#[derive(Debug, Clone, PartialEq)]
pub struct Op {
pub tool: String,
pub body: OpBody,
}
impl Op {
pub fn with_args(tool: impl Into<String>, args: Value) -> Self {
Self {
tool: tool.into(),
body: OpBody::Args(args),
}
}
pub fn with_generate(tool: impl Into<String>, generate: Generate) -> Self {
Self {
tool: tool.into(),
body: OpBody::Generate(generate),
}
}
fn to_value(&self) -> Value {
let mut map = Map::new();
map.insert("tool".to_owned(), Value::String(self.tool.clone()));
match &self.body {
OpBody::Args(args) => {
map.insert("args".to_owned(), args.clone());
}
OpBody::Generate(generate) => {
map.insert("generate".to_owned(), generate.to_value());
}
}
Value::Object(map)
}
}
#[derive(Debug, Clone, PartialEq)]
pub struct Step {
pub id: String,
pub operations: Vec<Op>,
pub depends_on: Vec<String>,
pub parallel: bool,
}
impl Step {
pub fn new(id: impl Into<String>, operations: Vec<Op>) -> Self {
Self {
id: id.into(),
operations,
depends_on: Vec::new(),
parallel: false,
}
}
#[must_use]
pub fn with_depends_on(
mut self,
depends_on: impl IntoIterator<Item = impl Into<String>>,
) -> Self {
self.depends_on = depends_on.into_iter().map(Into::into).collect();
self
}
#[must_use]
pub fn with_parallel(mut self, parallel: bool) -> Self {
self.parallel = parallel;
self
}
fn to_value(&self) -> Value {
let mut map = Map::new();
map.insert("id".to_owned(), Value::String(self.id.clone()));
map.insert(
"operations".to_owned(),
Value::Array(self.operations.iter().map(Op::to_value).collect()),
);
if !self.depends_on.is_empty() {
map.insert(
"depends_on".to_owned(),
Value::Array(self.depends_on.iter().cloned().map(Value::String).collect()),
);
}
if self.parallel {
map.insert("parallel".to_owned(), Value::Bool(true));
}
Value::Object(map)
}
}
#[derive(Debug, Clone, PartialEq)]
pub struct Validation {
pub tool: String,
pub args: Option<Value>,
pub success_condition: Option<String>,
}
impl Validation {
pub fn new(tool: impl Into<String>) -> Self {
Self {
tool: tool.into(),
args: None,
success_condition: None,
}
}
#[must_use]
pub fn with_args(mut self, args: Value) -> Self {
self.args = Some(args);
self
}
#[must_use]
pub fn with_success_condition(mut self, expr: impl Into<String>) -> Self {
self.success_condition = Some(expr.into());
self
}
fn to_value(&self) -> Value {
let mut map = Map::new();
map.insert("tool".to_owned(), Value::String(self.tool.clone()));
if let Some(args) = &self.args {
map.insert("args".to_owned(), args.clone());
}
if let Some(expr) = &self.success_condition {
map.insert("success_condition".to_owned(), Value::String(expr.clone()));
}
Value::Object(map)
}
}
#[derive(Debug, Clone, PartialEq)]
pub struct Action {
pub tool: String,
pub args: Option<Value>,
}
impl Action {
pub fn new(tool: impl Into<String>) -> Self {
Self {
tool: tool.into(),
args: None,
}
}
#[must_use]
pub fn with_args(mut self, args: Value) -> Self {
self.args = Some(args);
self
}
fn to_value(&self) -> Value {
let mut map = Map::new();
map.insert("tool".to_owned(), Value::String(self.tool.clone()));
if let Some(args) = &self.args {
map.insert("args".to_owned(), args.clone());
}
Value::Object(map)
}
}
#[derive(Debug, Clone, Default, PartialEq)]
pub struct Plan {
pub steps: Vec<Step>,
pub validation: Vec<Validation>,
pub on_success: Vec<Action>,
pub on_failure: Vec<Action>,
}
impl Plan {
#[must_use]
pub fn new(steps: Vec<Step>) -> Self {
Self {
steps,
validation: Vec::new(),
on_success: Vec::new(),
on_failure: Vec::new(),
}
}
#[must_use]
pub fn with_validation(mut self, validation: Vec<Validation>) -> Self {
self.validation = validation;
self
}
#[must_use]
pub fn with_on_success(mut self, on_success: Vec<Action>) -> Self {
self.on_success = on_success;
self
}
#[must_use]
pub fn with_on_failure(mut self, on_failure: Vec<Action>) -> Self {
self.on_failure = on_failure;
self
}
pub fn to_value(&self) -> Value {
let mut map = Map::new();
map.insert(
"steps".to_owned(),
Value::Array(self.steps.iter().map(Step::to_value).collect()),
);
if !self.validation.is_empty() {
map.insert(
"validation".to_owned(),
Value::Array(self.validation.iter().map(Validation::to_value).collect()),
);
}
if !self.on_success.is_empty() {
map.insert(
"on_success".to_owned(),
Value::Array(self.on_success.iter().map(Action::to_value).collect()),
);
}
if !self.on_failure.is_empty() {
map.insert(
"on_failure".to_owned(),
Value::Array(self.on_failure.iter().map(Action::to_value).collect()),
);
}
Value::Object(map)
}
}
#[derive(Debug, Clone, Default)]
pub struct PlanExecuteOptions {
pub planner_instructions: String,
pub fallback_instructions: Option<String>,
pub model: Option<String>,
pub fallback_max_turns: Option<u32>,
pub planner_context: Vec<String>,
}
pub fn plan_execute(
name: impl Into<String>,
tools: Vec<ToolDef>,
options: PlanExecuteOptions,
) -> Result<AgentDef> {
let name = name.into();
let mut planner =
AgentDef::new(format!("{name}_planner"))?.with_instructions(options.planner_instructions);
if let Some(model) = &options.model {
planner = planner.with_model(model.clone());
}
let fallback = match &options.fallback_instructions {
Some(fallback_instructions) => {
let mut fallback = AgentDef::new(format!("{name}_fallback"))?
.with_instructions(fallback_instructions.clone())
.with_tools(tools.clone());
if let Some(model) = &options.model {
fallback = fallback.with_model(model.clone());
}
Some(fallback)
}
None => None,
};
let mut harness = AgentDef::new(name)?.with_planner(planner).with_tools(tools);
if let Some(fallback) = fallback {
harness = harness.with_fallback(fallback);
}
if let Some(model) = &options.model {
harness = harness.with_model(model.clone());
}
if let Some(fallback_max_turns) = options.fallback_max_turns {
harness = harness.with_fallback_max_turns(fallback_max_turns);
}
if !options.planner_context.is_empty() {
harness = harness.with_planner_contexts(options.planner_context);
}
harness.with_strategy(super::def::Strategy::PlanExecute)
}
#[cfg(test)]
mod tests {
use super::*;
fn test_tool(name: &str) -> ToolDef {
ToolDef::function::<Value, _, _>(
name,
"a test tool",
serde_json::json!({"type": "object"}),
|_args: Value| async move { Ok(Value::Null) },
)
}
#[test]
fn test_ref_to_value() {
assert_eq!(
Ref::new("fetch").to_value(),
serde_json::json!({"$ref": "fetch"})
);
}
#[test]
fn test_ref_embeds_in_nested_args_via_into() {
let args = serde_json::json!({"document": Value::from(Ref::new("fetch"))});
assert_eq!(args, serde_json::json!({"document": {"$ref": "fetch"}}));
}
#[test]
fn test_context_text_only_emits_text() {
let value = Context::text("be concise").to_value();
assert_eq!(value, serde_json::json!({"text": "be concise"}));
}
#[test]
fn test_context_url_emits_defaults_omitted() {
let value = Context::url("https://example.com/rules").to_value();
assert_eq!(
value,
serde_json::json!({"url": "https://example.com/rules"})
);
}
#[test]
fn test_context_url_with_all_options() {
let mut headers = std::collections::HashMap::new();
headers.insert("Authorization".to_owned(), "${GH_TOKEN}".to_owned());
let value = Context::url("https://example.com/rules")
.with_headers(headers)
.with_required(false)
.with_max_bytes(1024)
.to_value();
assert_eq!(
value,
serde_json::json!({
"url": "https://example.com/rules",
"headers": {"Authorization": "${GH_TOKEN}"},
"required": false,
"maxBytes": 1024,
})
);
}
#[test]
fn test_generate_to_value_minimal() {
let value = Generate::new("write the intro", r#"{"content": "..."}"#).to_value();
assert_eq!(
value,
serde_json::json!({
"instructions": "write the intro",
"output_schema": r#"{"content": "..."}"#,
})
);
}
#[test]
fn test_generate_with_ref_context() {
let value = Generate::new("summarize", "{}")
.with_context(Ref::new("fetch"))
.to_value();
assert_eq!(value["context"], serde_json::json!({"$ref": "fetch"}));
}
#[test]
fn test_op_with_args_to_value() {
let op = Op::with_args("create_directory", serde_json::json!({"path": "out"}));
assert_eq!(
op.to_value(),
serde_json::json!({"tool": "create_directory", "args": {"path": "out"}})
);
}
#[test]
fn test_op_with_generate_to_value() {
let op = Op::with_generate(
"write_file",
Generate::new("write the intro", r#"{"path": "out/intro.md"}"#),
);
let value = op.to_value();
assert_eq!(value["tool"], "write_file");
assert!(value.get("generate").is_some());
assert!(value.get("args").is_none());
}
#[test]
fn test_step_to_value_minimal() {
let step = Step::new(
"setup",
vec![Op::with_args(
"create_directory",
serde_json::json!({"path": "out"}),
)],
);
let value = step.to_value();
assert_eq!(value["id"], "setup");
assert!(value.get("depends_on").is_none());
assert!(value.get("parallel").is_none());
}
#[test]
fn test_step_with_depends_on_and_parallel() {
let step = Step::new("write_sections", vec![])
.with_depends_on(["setup"])
.with_parallel(true);
let value = step.to_value();
assert_eq!(value["depends_on"], serde_json::json!(["setup"]));
assert_eq!(value["parallel"], Value::Bool(true));
}
#[test]
fn test_validation_to_value() {
let validation = Validation::new("check_word_count")
.with_args(serde_json::json!({"path": "out/intro.md", "min_words": 200}))
.with_success_condition("$.passed === true");
let value = validation.to_value();
assert_eq!(value["tool"], "check_word_count");
assert_eq!(value["success_condition"], "$.passed === true");
}
#[test]
fn test_action_to_value() {
let action = Action::new("notify").with_args(serde_json::json!({"channel": "#ops"}));
let value = action.to_value();
assert_eq!(value["tool"], "notify");
assert_eq!(value["args"], serde_json::json!({"channel": "#ops"}));
}
#[test]
fn test_plan_to_value_matches_wire_shape() {
let plan = Plan::new(vec![
Step::new(
"setup",
vec![Op::with_args(
"create_directory",
serde_json::json!({"path": "out"}),
)],
),
Step::new(
"write_sections",
vec![Op::with_generate(
"write_file",
Generate::new(
"Write the introduction.",
r#"{"path": "out/intro.md", "content": "..."}"#,
),
)],
)
.with_depends_on(["setup"])
.with_parallel(true),
])
.with_validation(vec![Validation::new("check_word_count")
.with_args(serde_json::json!({"path": "out/intro.md", "min_words": 200}))]);
let value = plan.to_value();
assert_eq!(value["steps"].as_array().unwrap().len(), 2);
assert_eq!(value["validation"].as_array().unwrap().len(), 1);
assert!(value.get("on_success").is_none());
assert!(value.get("on_failure").is_none());
}
#[test]
fn test_plan_omits_empty_collections() {
let plan = Plan::new(vec![Step::new("only", vec![])]);
let value = plan.to_value();
let obj = value.as_object().unwrap();
assert!(!obj.contains_key("validation"));
assert!(!obj.contains_key("on_success"));
assert!(!obj.contains_key("on_failure"));
}
#[test]
fn test_plan_execute_builds_planner_and_parent() {
let agent = plan_execute(
"research",
vec![test_tool("search")],
PlanExecuteOptions {
planner_instructions: "Plan a research report.".to_owned(),
..Default::default()
},
)
.unwrap();
assert_eq!(agent.name, "research");
assert_eq!(agent.strategy, super::super::def::Strategy::PlanExecute);
assert_eq!(agent.planner.as_ref().unwrap().name, "research_planner");
assert!(agent.fallback.is_none());
assert_eq!(agent.tools.len(), 1);
}
#[test]
fn test_plan_execute_builds_fallback_when_instructions_given() {
let agent = plan_execute(
"research",
vec![test_tool("search")],
PlanExecuteOptions {
fallback_instructions: Some("Recover and retry.".to_owned()),
fallback_max_turns: Some(5),
..Default::default()
},
)
.unwrap();
let fallback = agent.fallback.as_ref().unwrap();
assert_eq!(fallback.name, "research_fallback");
assert_eq!(fallback.tools.len(), 1);
assert_eq!(agent.fallback_max_turns, Some(5));
}
#[test]
fn test_plan_execute_propagates_model_to_planner_fallback_and_parent() {
let agent = plan_execute(
"research",
vec![test_tool("search")],
PlanExecuteOptions {
fallback_instructions: Some("Recover.".to_owned()),
model: Some("openai/gpt-4o".to_owned()),
..Default::default()
},
)
.unwrap();
assert_eq!(agent.model, Some("openai/gpt-4o".to_owned()));
assert_eq!(
agent.planner.as_ref().unwrap().model,
Some("openai/gpt-4o".to_owned())
);
assert_eq!(
agent.fallback.as_ref().unwrap().model,
Some("openai/gpt-4o".to_owned())
);
}
#[test]
fn test_plan_execute_fails_without_tools() {
let result = plan_execute("research", vec![], PlanExecuteOptions::default());
result.unwrap_err();
}
}