ceylon_next/goal/

mod.rs

//! Goal-oriented task planning and tracking system.
//!
//! This module provides structures for representing goals, sub-goals, and success criteria,
//! enabling agents to break down complex tasks and track progress systematically.

use serde::{Deserialize, Serialize};

// ============================================
// Goal Understanding Structures
// ============================================

/// Represents a structured goal with sub-goals and success criteria.
///
/// Goals help agents understand what they're trying to achieve and how to
/// measure success. Each goal can have multiple sub-goals and success criteria.
///
/// # Examples
///
/// ```rust
/// use ceylon_next::goal::{Goal, GoalStatus};
///
/// let mut goal = Goal::new("Build a REST API".to_string());
///
/// // Add success criteria
/// goal.add_criterion("API responds to HTTP requests".to_string());
/// goal.add_criterion("All endpoints return valid JSON".to_string());
///
/// // Add sub-goals in priority order
/// goal.add_sub_goal("Design API endpoints".to_string(), 1);
/// goal.add_sub_goal("Implement request handlers".to_string(), 2);
/// goal.add_sub_goal("Add error handling".to_string(), 3);
///
/// // Mark sub-goal as complete
/// goal.complete_sub_goal(0, Some("Endpoints designed".to_string()));
///
/// println!("{}", goal.get_summary());
/// ```
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Goal {
    /// What we're trying to accomplish
    pub description: String,

    /// How to know when we're successful
    pub success_criteria: Vec<SuccessCriterion>,

    /// Smaller steps to achieve the goal
    pub sub_goals: Vec<SubGoal>,

    /// Current status
    pub status: GoalStatus,
}

/// A criterion that must be met for the goal to be considered successful.
///
/// Success criteria are measurable conditions that define what "done" means.
///
/// # Examples
///
/// ```rust
/// use ceylon_next::goal::SuccessCriterion;
///
/// let criterion = SuccessCriterion {
///     description: "All tests pass".to_string(),
///     is_met: false,
///     reason: None,
/// };
/// ```
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct SuccessCriterion {
    /// What needs to be true
    pub description: String,

    /// Is this criterion met?
    pub is_met: bool,

    /// Why is it met or not met?
    pub reason: Option<String>,
}

/// A smaller goal that's part of achieving the main goal.
///
/// Sub-goals break down complex tasks into manageable steps.
///
/// # Examples
///
/// ```rust
/// use ceylon_next::goal::SubGoal;
///
/// let sub_goal = SubGoal {
///     description: "Set up database schema".to_string(),
///     completed: false,
///     priority: 1,
///     notes: None,
/// };
/// ```
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct SubGoal {
    /// What this sub-goal achieves
    pub description: String,

    /// Is this sub-goal complete?
    pub completed: bool,

    /// Order to work on (lower = first)
    pub priority: u32,

    /// Notes about progress
    pub notes: Option<String>,
}

/// The current status of a goal.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
pub enum GoalStatus {
    /// Just created, not started yet
    NotStarted,

    /// Currently working on it
    InProgress,

    /// Successfully completed
    Completed,

    /// Could not complete
    Failed,

    /// User stopped it
    Cancelled,
}

impl Goal {
    /// Creates a new goal with the given description.
    ///
    /// # Arguments
    ///
    /// * `description` - A description of what the goal aims to achieve
    pub fn new(description: String) -> Self {
        Self {
            description,
            success_criteria: Vec::new(),
            sub_goals: Vec::new(),
            status: GoalStatus::NotStarted,
        }
    }

    /// Adds a success criterion to the goal.
    ///
    /// # Arguments
    ///
    /// * `description` - The condition that must be true for success
    pub fn add_criterion(&mut self, description: String) {
        self.success_criteria.push(SuccessCriterion {
            description,
            is_met: false,
            reason: None,
        });
    }

    /// Adds a sub-goal to the goal.
    ///
    /// # Arguments
    ///
    /// * `description` - What this sub-goal accomplishes
    /// * `priority` - Execution order (lower numbers are executed first)
    pub fn add_sub_goal(&mut self, description: String, priority: u32) {
        self.sub_goals.push(SubGoal {
            description,
            completed: false,
            priority,
            notes: None,
        });
    }

    /// Marks a success criterion as met.
    ///
    /// # Arguments
    ///
    /// * `index` - The index of the criterion to mark
    /// * `reason` - Why the criterion is now met
    pub fn mark_criterion_met(&mut self, index: usize, reason: String) {
        if let Some(criterion) = self.success_criteria.get_mut(index) {
            criterion.is_met = true;
            criterion.reason = Some(reason);
        }
    }

    /// Marks a sub-goal as complete.
    ///
    /// # Arguments
    ///
    /// * `index` - The index of the sub-goal to complete
    /// * `notes` - Optional notes about the completion
    pub fn complete_sub_goal(&mut self, index: usize, notes: Option<String>) {
        if let Some(sub_goal) = self.sub_goals.get_mut(index) {
            sub_goal.completed = true;
            sub_goal.notes = notes;
        }
    }

    /// Checks if all success criteria are met.
    ///
    /// # Returns
    ///
    /// `true` if all criteria are met, `false` otherwise
    pub fn is_successful(&self) -> bool {
        !self.success_criteria.is_empty()
            && self.success_criteria.iter().all(|c| c.is_met)
    }

    /// Checks if all sub-goals are complete.
    ///
    /// # Returns
    ///
    /// `true` if all sub-goals are complete, `false` otherwise
    pub fn all_sub_goals_complete(&self) -> bool {
        !self.sub_goals.is_empty()
            && self.sub_goals.iter().all(|sg| sg.completed)
    }

    /// Returns the next sub-goal to work on.
    ///
    /// Returns the incomplete sub-goal with the lowest priority number.
    ///
    /// # Returns
    ///
    /// The next sub-goal to work on, or `None` if all are complete
    pub fn get_next_sub_goal(&self) -> Option<&SubGoal> {
        self.sub_goals
            .iter()
            .filter(|sg| !sg.completed)
            .min_by_key(|sg| sg.priority)
    }

    /// Calculates the progress percentage.
    ///
    /// # Returns
    ///
    /// Progress as a percentage (0-100)
    pub fn get_progress(&self) -> u32 {
        if self.sub_goals.is_empty() {
            return 0;
        }

        let completed = self.sub_goals.iter().filter(|sg| sg.completed).count();
        ((completed as f32 / self.sub_goals.len() as f32) * 100.0) as u32
    }

    /// Returns a formatted summary of the goal's current state.
    ///
    /// # Returns
    ///
    /// A multi-line string showing the goal, status, progress, criteria, and sub-goals
    pub fn get_summary(&self) -> String {
        let mut summary = format!("Goal: {}\n", self.description);
        summary.push_str(&format!("Status: {:?}\n", self.status));
        summary.push_str(&format!("Progress: {}%\n\n", self.get_progress()));

        // Success criteria
        summary.push_str("Success Criteria:\n");
        for (i, criterion) in self.success_criteria.iter().enumerate() {
            let status = if criterion.is_met { "✓" } else { "☐" };
            summary.push_str(&format!("  {} {}. {}\n", status, i + 1, criterion.description));
        }

        // Sub-goals
        summary.push_str("\nSub-goals:\n");
        for (i, sub_goal) in self.sub_goals.iter().enumerate() {
            let status = if sub_goal.completed { "✓" } else { "☐" };
            summary.push_str(&format!("  {} {}. {}\n", status, i + 1, sub_goal.description));
        }

        summary
    }
}

// ============================================
// Goal Analyzer - Helps create goals from tasks
// ============================================

/// Utility for helping LLMs analyze tasks and create structured goals.
///
/// `GoalAnalyzer` provides methods to generate prompts that guide LLMs
/// in breaking down tasks into goals with sub-goals and success criteria.
pub struct GoalAnalyzer;

impl GoalAnalyzer {
    /// Creates a prompt for LLM to analyze a task and create a goal structure.
    ///
    /// # Arguments
    ///
    /// * `task_description` - The task to analyze
    ///
    /// # Returns
    ///
    /// A formatted prompt string for the LLM
    pub fn create_analysis_prompt(task_description: &str) -> String {
        format!(
            r#"Analyze this task and break it down into a clear goal structure.

TASK: "{}"

Please provide:
1. MAIN GOAL: What is the overall objective? (one sentence)
2. SUCCESS CRITERIA: What must be true when we're done? (list 2-5 specific things)
3. SUB-GOALS: What are the steps to achieve this? (list 3-7 ordered steps)

Format your response as JSON:
{{
  "main_goal": "description of the main goal",
  "success_criteria": [
    "criterion 1",
    "criterion 2",
    "criterion 3"
  ],
  "sub_goals": [
    "step 1",
    "step 2",
    "step 3"
  ]
}}

Be specific and actionable. Think about what information you need and what the final result should look like."#,
            task_description
        )
    }
}

// ============================================
// Goal Analysis Response
// ============================================

/// Response structure from LLM when analyzing a task into a goal.
///
/// This structure is used to deserialize the JSON response from the LLM
/// when it analyzes a task using [`GoalAnalyzer::create_analysis_prompt`].
///
/// # Examples
///
/// ```rust
/// use ceylon_next::goal::{GoalAnalysis, Goal};
/// use serde_json::json;
///
/// let json = json!({
///     "main_goal": "Build a web server",
///     "success_criteria": ["Server responds to HTTP requests", "Handles errors gracefully"],
///     "sub_goals": ["Set up HTTP listener", "Implement request routing", "Add error handling"]
/// });
///
/// let analysis: GoalAnalysis = serde_json::from_value(json).unwrap();
/// let goal = analysis.to_goal();
/// ```
#[derive(Debug, Serialize, Deserialize)]
pub struct GoalAnalysis {
    /// The main goal description
    pub main_goal: String,
    /// List of success criteria
    pub success_criteria: Vec<String>,
    /// List of sub-goals in execution order
    pub sub_goals: Vec<String>,
}

impl GoalAnalysis {
    /// Converts this analysis into a [`Goal`] structure.
    ///
    /// Sub-goals are assigned priorities based on their order in the list.
    ///
    /// # Returns
    ///
    /// A new `Goal` with status set to `NotStarted`
    pub fn to_goal(&self) -> Goal {
        let mut goal = Goal::new(self.main_goal.clone());

        // Add success criteria
        for criterion in &self.success_criteria {
            goal.add_criterion(criterion.clone());
        }

        // Add sub-goals with priority based on order
        for (i, sub_goal) in self.sub_goals.iter().enumerate() {
            goal.add_sub_goal(sub_goal.clone(), i as u32);
        }

        goal.status = GoalStatus::NotStarted;
        goal
    }
}