05_with_goals/

05_with_goals.rs

//! Goal-Based Agent Example
//!
//! This example demonstrates how to use goals with the Ceylon Agent to:
//! - Break down complex tasks into structured goals
//! - Define success criteria
//! - Track progress through sub-goals
//! - Monitor goal completion and status
//!
//! Goals help agents understand what success looks like and work systematically
//! toward achieving objectives with clear milestones and criteria.
//!
//! Run with: cargo run --example 05_with_goals --manifest-path ceylon/Cargo.toml

use ceylon_next::agent::Agent;
use ceylon_next::goal::{Goal, GoalAnalysis, GoalStatus};
use ceylon_next::tasks::TaskRequest;

// ============================================
// Example 1: Manual Goal Creation
// ============================================

async fn example_1_manual_goal() {
    println!("=== Example 1: Manual Goal Creation ===\n");

    // Create an agent
    let mut agent = Agent::new("MealPlanner", "ollama::gemma3:latest");

    // Create a goal manually for a complex task
    let mut goal = Goal::new(
        "Plan a healthy meal prep for the week".to_string()
    );

    // Define what success looks like
    println!("📋 Setting success criteria...");
    goal.add_criterion("7 breakfast recipes selected".to_string());
    goal.add_criterion("7 lunch recipes selected".to_string());
    goal.add_criterion("7 dinner recipes selected".to_string());
    goal.add_criterion("Shopping list created".to_string());
    goal.add_criterion("Prep schedule created".to_string());

    // Break down into steps (sub-goals)
    println!("🎯 Breaking down into sub-goals...\n");
    goal.add_sub_goal("Ask user about dietary preferences".to_string(), 0);
    goal.add_sub_goal("Ask about time available for prep".to_string(), 1);
    goal.add_sub_goal("Suggest breakfast options".to_string(), 2);
    goal.add_sub_goal("Suggest lunch options".to_string(), 3);
    goal.add_sub_goal("Suggest dinner options".to_string(), 4);
    goal.add_sub_goal("Create shopping list".to_string(), 5);
    goal.add_sub_goal("Create prep schedule".to_string(), 6);

    // Start working on the goal
    goal.status = GoalStatus::InProgress;

    // Set the goal on the agent
    agent.set_goal(goal.clone());

    // Create a task aligned with the goal
    let task = TaskRequest::new("I need help with meal planning");

    // Run the agent
    println!("⏳ Agent is working on the meal planning task...\n");
    let _response = agent.run(task).await;

    // Show the goal summary
    println!("\n📊 Goal Summary:");
    println!("{}", goal.get_summary());

    println!("\n✅ Example 1 completed!\n");
}

// ============================================
// Example 2: Goal Progress Tracking
// ============================================

async fn example_2_goal_progress_tracking() {
    println!("\n=== Example 2: Goal Progress Tracking ===\n");

    // Create a goal for a project
    let mut goal = Goal::new(
        "Create a project plan for building a mobile app".to_string()
    );

    // Add success criteria
    goal.add_criterion("Project requirements documented".to_string());
    goal.add_criterion("Timeline created with milestones".to_string());
    goal.add_criterion("Resource allocation plan completed".to_string());
    goal.add_criterion("Risk assessment performed".to_string());

    // Add sub-goals
    goal.add_sub_goal("Gather stakeholder requirements".to_string(), 0);
    goal.add_sub_goal("Define project scope".to_string(), 1);
    goal.add_sub_goal("Create development timeline".to_string(), 2);
    goal.add_sub_goal("Allocate resources".to_string(), 3);
    goal.add_sub_goal("Identify risks and mitigation strategies".to_string(), 4);

    goal.status = GoalStatus::InProgress;

    // Simulate progress through the goal
    println!("📈 Tracking goal progress...\n");

    // Complete first sub-goal
    println!("Step 1: Gathering requirements");
    goal.complete_sub_goal(0, Some("Interviewed 5 stakeholders".to_string()));
    goal.mark_criterion_met(0, "Requirements documented".to_string());
    println!("  Progress: {}%\n", goal.get_progress());

    // Complete second sub-goal
    println!("Step 2: Defining scope");
    goal.complete_sub_goal(1, Some("Scope document created".to_string()));
    println!("  Progress: {}%\n", goal.get_progress());

    // Complete third sub-goal
    println!("Step 3: Creating timeline");
    goal.complete_sub_goal(2, Some("12-month timeline with milestones".to_string()));
    goal.mark_criterion_met(1, "Timeline created".to_string());
    println!("  Progress: {}%\n", goal.get_progress());

    // Complete fourth sub-goal
    println!("Step 4: Allocating resources");
    goal.complete_sub_goal(3, Some("Resource allocation table created".to_string()));
    goal.mark_criterion_met(2, "Resources allocated".to_string());
    println!("  Progress: {}%\n", goal.get_progress());

    // Complete fifth sub-goal
    println!("Step 5: Assessing risks");
    goal.complete_sub_goal(4, Some("Risk register created with 8 identified risks".to_string()));
    goal.mark_criterion_met(3, "Risks identified".to_string());
    println!("  Progress: {}%\n", goal.get_progress());

    // Show final status
    println!("\n📊 Final Goal Status:");
    println!("{}", goal.get_summary());

    println!("\n✅ Example 2 completed!\n");
}

// ============================================
// Example 3: Job Interview Preparation Goal
// ============================================

async fn example_3_interview_preparation() {
    println!("\n=== Example 3: Job Interview Preparation Goal ===\n");

    let mut agent = Agent::new("InterviewCoach", "ollama::gemma3:latest");

    // Create a structured goal for interview prep
    let mut goal = Goal::new(
        "Prepare for a senior software engineer interview at a tech company".to_string()
    );

    // Define success criteria
    println!("🎯 Success criteria:");
    goal.add_criterion("Technical topics reviewed (algorithms, data structures, system design)".to_string());
    goal.add_criterion("Behavioral questions prepared with STAR method examples".to_string());
    goal.add_criterion("Company research completed".to_string());
    goal.add_criterion("Practice mock interview conducted".to_string());
    goal.add_criterion("Questions to ask the interviewer prepared".to_string());

    for criterion in &goal.success_criteria {
        println!("  • {}", criterion.description);
    }

    // Define steps
    println!("\n📋 Steps to take:");
    goal.add_sub_goal("Review core algorithms and data structures".to_string(), 0);
    goal.add_sub_goal("Study system design patterns".to_string(), 1);
    goal.add_sub_goal("Prepare STAR method stories from past projects".to_string(), 2);
    goal.add_sub_goal("Research company background and culture".to_string(), 3);
    goal.add_sub_goal("Practice mock interview with a friend".to_string(), 4);
    goal.add_sub_goal("Prepare thoughtful questions about the role".to_string(), 5);

    for sub_goal in &goal.sub_goals {
        println!("  {}. {}", sub_goal.priority + 1, sub_goal.description);
    }

    goal.status = GoalStatus::InProgress;

    // Set goal on agent
    agent.set_goal(goal.clone());

    // Create related task
    let task = TaskRequest::new("Help me prepare for my senior engineer interview");

    println!("\n⏳ Agent is creating interview preparation plan...\n");
    let _response = agent.run(task).await;

    println!("\n📊 Goal Summary:");
    println!("{}", goal.get_summary());

    println!("\n✅ Example 3 completed!\n");
}

// ============================================
// Example 4: Goal Analysis from Task Description
// ============================================

fn example_4_goal_analysis() {
    println!("\n=== Example 4: Goal Analysis from Task Description ===\n");

    // Simulate LLM analyzing a task and breaking it down into a goal
    let task_description = "Help me learn Python programming";

    println!("📝 Original task: \"{}\"", task_description);
    println!("\n🔍 LLM analyzing task...\n");

    // This is what the LLM would return
    let analysis = GoalAnalysis {
        main_goal: "Help user learn Python programming from basics to practical skills".to_string(),
        success_criteria: vec![
            "User's current skill level identified".to_string(),
            "Learning path created based on skill level".to_string(),
            "Resources (tutorials, books) provided".to_string(),
            "Practice exercises suggested".to_string(),
            "Study schedule created".to_string(),
        ],
        sub_goals: vec![
            "Ask about current programming experience".to_string(),
            "Identify learning goals (web dev, data science, etc)".to_string(),
            "Create structured learning path".to_string(),
            "Recommend learning resources".to_string(),
            "Suggest practice projects".to_string(),
            "Create study timeline".to_string(),
        ],
    };

    // Convert analysis to a Goal
    let goal = analysis.to_goal();

    println!("✅ Goal created from analysis:\n");
    println!("{}", goal.get_summary());

    println!("\n✅ Example 4 completed!\n");
}

// ============================================
// Example 5: Goal Completion Verification
// ============================================

async fn example_5_goal_completion() {
    println!("\n=== Example 5: Goal Completion Verification ===\n");

    let mut goal = Goal::new("Plan a birthday party".to_string());

    // Set up success criteria
    goal.add_criterion("Guest list created".to_string());
    goal.add_criterion("Venue booked".to_string());
    goal.add_criterion("Food ordered".to_string());
    goal.add_criterion("Decorations purchased".to_string());

    // Set up sub-goals
    goal.add_sub_goal("Ask about guests".to_string(), 0);
    goal.add_sub_goal("Choose and book venue".to_string(), 1);
    goal.add_sub_goal("Order food".to_string(), 2);
    goal.add_sub_goal("Purchase decorations".to_string(), 3);

    goal.status = GoalStatus::InProgress;

    println!("🎉 Birthday party planning task started\n");
    println!("Initial progress: {}%\n", goal.get_progress());

    // Simulate completing tasks
    println!("Working through sub-goals:\n");

    // Task 1
    println!("✓ Contacted 15 friends and family members");
    goal.complete_sub_goal(0, Some("Got 15 confirmations".to_string()));
    goal.mark_criterion_met(0, "List of 15 guests confirmed".to_string());
    println!("  Progress: {}%", goal.get_progress());

    // Task 2
    println!("✓ Booked the community center for Saturday");
    goal.complete_sub_goal(1, Some("Community center reserved for 6pm".to_string()));
    goal.mark_criterion_met(1, "Community center booking confirmed".to_string());
    println!("  Progress: {}%", goal.get_progress());

    // Task 3
    println!("✓ Ordered pizza and drinks for 15 people");
    goal.complete_sub_goal(2, Some("Pizza and drinks ordered".to_string()));
    goal.mark_criterion_met(2, "Food catering arranged".to_string());
    println!("  Progress: {}%", goal.get_progress());

    // Task 4
    println!("✓ Bought balloons, streamers, and table decorations");
    goal.complete_sub_goal(3, Some("All decorations purchased".to_string()));
    goal.mark_criterion_met(3, "Decorations ready".to_string());
    println!("  Progress: {}%\n", goal.get_progress());

    // Check completion
    if goal.is_successful() {
        println!("🎊 All success criteria met!");
        goal.status = GoalStatus::Completed;
    }

    if goal.all_sub_goals_complete() {
        println!("✅ All sub-goals completed!");
    }

    println!("\nFinal Status:");
    println!("  Status: {:?}", goal.status);
    println!("  All criteria met: {}", goal.is_successful());
    println!("  Progress: {}%\n", goal.get_progress());

    println!("📊 Final Summary:");
    println!("{}", goal.get_summary());

    println!("\n✅ Example 5 completed!\n");
}

// ============================================
// Example 6: Complex Multi-Step Project
// ============================================

async fn example_6_complex_project() {
    println!("\n=== Example 6: Complex Multi-Step Project Goal ===\n");

    let mut goal = Goal::new(
        "Launch a new web application product".to_string()
    );

    // Success criteria
    goal.add_criterion("Technical architecture designed and documented".to_string());
    goal.add_criterion("Frontend and backend development completed".to_string());
    goal.add_criterion("Testing completed (unit, integration, E2E)".to_string());
    goal.add_criterion("Deployment pipeline set up".to_string());
    goal.add_criterion("Marketing materials prepared".to_string());
    goal.add_criterion("Team trained on deployment and support".to_string());

    // Sub-goals in order
    goal.add_sub_goal("Define technical requirements and architecture".to_string(), 0);
    goal.add_sub_goal("Set up development environment and CI/CD".to_string(), 1);
    goal.add_sub_goal("Develop backend API endpoints".to_string(), 2);
    goal.add_sub_goal("Build frontend user interface".to_string(), 3);
    goal.add_sub_goal("Write comprehensive test suite".to_string(), 4);
    goal.add_sub_goal("Conduct security audit".to_string(), 5);
    goal.add_sub_goal("Set up monitoring and logging".to_string(), 6);
    goal.add_sub_goal("Deploy to staging environment".to_string(), 7);
    goal.add_sub_goal("Perform final testing and QA".to_string(), 8);
    goal.add_sub_goal("Create deployment documentation".to_string(), 9);
    goal.add_sub_goal("Train support team".to_string(), 10);
    goal.add_sub_goal("Deploy to production".to_string(), 11);

    goal.status = GoalStatus::InProgress;

    println!("🚀 Web Application Product Launch Plan\n");
    println!("Total steps: {}\n", goal.sub_goals.len());

    // Simulate progress
    let completed_steps = vec![
        (0, "Architecture documented with diagrams"),
        (1, "GitHub Actions CI/CD configured"),
        (2, "All 15 API endpoints implemented and tested"),
        (3, "React frontend with all pages completed"),
        (4, "Jest test suite with 85% coverage"),
        (5, "No critical vulnerabilities found"),
        (6, "Prometheus and ELK stack configured"),
        (7, "Successfully deployed to staging"),
        (8, "UAT passed with stakeholders"),
        (9, "Deployment runbook created"),
        (10, "Support team completed training"),
    ];

    for (index, notes) in completed_steps {
        goal.complete_sub_goal(index, Some(notes.to_string()));
    }

    // Mark success criteria as met
    goal.mark_criterion_met(0, "System design document completed".to_string());
    goal.mark_criterion_met(1, "All features implemented and tested".to_string());
    goal.mark_criterion_met(2, "85% test coverage achieved".to_string());
    goal.mark_criterion_met(3, "GitHub Actions and monitoring configured".to_string());
    goal.mark_criterion_met(4, "Marketing deck prepared".to_string());
    goal.mark_criterion_met(5, "Team completed deployment training".to_string());

    println!("📈 Project Progress:\n");
    println!("Overall Progress: {}%\n", goal.get_progress());

    println!("Remaining tasks:");
    if let Some(next) = goal.get_next_sub_goal() {
        println!("  • {}", next.description);
    }

    println!("\n📊 Status Summary:");
    println!("{}", goal.get_summary());

    if goal.get_progress() == 100 {
        println!("\n✅ All sub-goals completed!");
        if goal.is_successful() {
            println!("🎉 All success criteria met!");
            println!("Ready to mark goal as Completed!");
        }
    }

    println!("\n✅ Example 6 completed!\n");
}

// ============================================
// Main function to run examples
// ============================================

#[tokio::main]
async fn main() {
    println!("🎯 Ceylon Agent - Goal-Based Examples\n");
    println!("This example demonstrates how to structure tasks as goals,");
    println!("break them into sub-goals, and track progress.\n");
    println!("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n");

    // Run examples
    example_1_manual_goal().await;
    example_2_goal_progress_tracking().await;
    example_3_interview_preparation().await;
    example_4_goal_analysis();
    example_5_goal_completion().await;
    example_6_complex_project().await;

    println!("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
    println!("\n✅ All goal-based examples completed successfully!\n");

    println!("📚 Key Takeaways:");
    println!("  1. Goals provide structure to complex tasks");
    println!("  2. Success criteria define what \"done\" looks like");
    println!("  3. Sub-goals break work into manageable steps");
    println!("  4. Progress tracking helps monitor completion");
    println!("  5. Goal status helps coordinate multi-step workflows\n");

    println!("🔗 Next steps:");
    println!("  • Combine goals with tools for autonomous task execution");
    println!("  • Use goal analysis to break down user requests automatically");
    println!("  • Integrate goal progress into agent memory for context\n");
}

/*

KEY CONCEPTS:

1. GOAL STRUCTURE
   ├─ Main Goal: What you're trying to achieve
   ├─ Success Criteria: How to know when you're done (2-5 items)
   └─ Sub-Goals: Steps to achieve the goal (prioritized, ordered)

2. GOAL STATUS
   • NotStarted: Just created
   • InProgress: Currently working on it
   • Completed: Successfully finished
   • Failed: Could not complete
   • Cancelled: User stopped it

3. PROGRESS TRACKING
   • get_progress(): Returns 0-100% based on sub-goals completed
   • get_next_sub_goal(): Shows what to work on next
   • is_successful(): All criteria met?
   • all_sub_goals_complete(): All steps done?

4. WHEN TO USE GOALS
   ✓ Complex tasks with multiple steps
   ✓ Multi-part projects
   ✓ Tasks requiring user interaction
   ✓ When you need clear milestones
   ✓ When you want to track progress

5. BENEFITS
   • Clear understanding of task scope
   • Systematic progress through complex work
   • Easy to track what's done vs pending
   • Better user communication
   • Deterministic completion criteria

*/