llm_toolkit_expertise/

types.rs

//! Core expertise types and structures.
//!
//! This module defines the main Expertise type and related structures for
//! composing agent capabilities from weighted knowledge fragments.

use crate::context::{ContextMatcher, ContextProfile, Priority};
use crate::fragment::KnowledgeFragment;
use schemars::JsonSchema;
use serde::{Deserialize, Serialize};

/// Expertise: Agent capability package (Graph node)
///
/// Represents a complete agent expertise profile composed of weighted
/// knowledge fragments. Uses composition instead of inheritance for
/// flexible capability mixing.
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
pub struct Expertise {
    /// Unique identifier
    pub id: String,

    /// Version string
    pub version: String,

    /// Optional lightweight catalog description for Orchestrator routing
    ///
    /// This is a concise (1-2 sentence) summary used by orchestrators to select
    /// the appropriate agent. The full expertise details are rendered via `to_prompt()`
    /// for LLM consumption.
    ///
    /// If not provided, it will be auto-generated from the first fragment content
    /// (typically starts with "You are XXX" or "XXX Agent...").
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub description: Option<String>,

    /// Tags for search and grouping (e.g., ["lang:rust", "role:reviewer", "style:friendly"])
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub tags: Vec<String>,

    /// Knowledge and capability components (weighted)
    pub content: Vec<WeightedFragment>,
}

impl Expertise {
    /// Create a new expertise profile
    ///
    /// # Arguments
    ///
    /// * `id` - Unique identifier for this expertise
    /// * `version` - Version string (e.g., "1.0.0")
    ///
    /// # Description Auto-generation
    ///
    /// The `description` field is optional. If not set via [`with_description()`](Self::with_description),
    /// it will be auto-generated from the first fragment's content when needed.
    /// Typical patterns include:
    /// - "You are a Rust expert..."
    /// - "Senior software engineer specialized in..."
    /// - "Code reviewer with focus on..."
    ///
    /// # Example
    ///
    /// ```
    /// use llm_toolkit_expertise::Expertise;
    ///
    /// let expertise = Expertise::new("rust-expert", "1.0.0");
    /// ```
    pub fn new(id: impl Into<String>, version: impl Into<String>) -> Self {
        Self {
            id: id.into(),
            version: version.into(),
            description: None,
            tags: Vec::new(),
            content: Vec::new(),
        }
    }

    /// Set an explicit description for catalog/routing purposes
    ///
    /// This overrides the auto-generated description. Use this when you want
    /// a specific concise summary for orchestrator routing that differs from
    /// the first fragment's content.
    ///
    /// # Example
    ///
    /// ```
    /// use llm_toolkit_expertise::Expertise;
    ///
    /// let expertise = Expertise::new("rust-expert", "1.0.0")
    ///     .with_description("Expert Rust developer and code reviewer");
    /// ```
    pub fn with_description(mut self, description: impl Into<String>) -> Self {
        self.description = Some(description.into());
        self
    }

    /// Add a tag
    pub fn with_tag(mut self, tag: impl Into<String>) -> Self {
        self.tags.push(tag.into());
        self
    }

    /// Add tags
    pub fn with_tags(mut self, tags: Vec<String>) -> Self {
        self.tags.extend(tags);
        self
    }

    /// Add a weighted fragment
    pub fn with_fragment(mut self, fragment: WeightedFragment) -> Self {
        self.content.push(fragment);
        self
    }

    /// Get the description, auto-generating if not explicitly set
    ///
    /// If no explicit description was set via [`with_description()`](Self::with_description),
    /// this method generates one from the first fragment's content. It extracts the first
    /// ~100 characters, which typically captures patterns like:
    /// - "You are a Rust expert..."
    /// - "Senior software engineer specialized in..."
    ///
    /// Returns an empty string if there are no fragments.
    pub fn get_description(&self) -> String {
        if let Some(desc) = &self.description {
            return desc.clone();
        }

        // Auto-generate from first fragment
        if let Some(first_fragment) = self.content.first() {
            let content = match &first_fragment.fragment {
                KnowledgeFragment::Text(text) => text.clone(),
                KnowledgeFragment::Logic { instruction, .. } => instruction.clone(),
                KnowledgeFragment::Guideline { rule, .. } => rule.clone(),
                KnowledgeFragment::QualityStandard { criteria, .. } => criteria
                    .first()
                    .cloned()
                    .unwrap_or_else(|| format!("{} v{}", self.id, self.version)),
                _ => {
                    // For ToolDefinition and other types, look for next usable fragment
                    self.content
                        .iter()
                        .skip(1)
                        .find_map(|wf| match &wf.fragment {
                            KnowledgeFragment::Text(t) => Some(t.clone()),
                            KnowledgeFragment::Logic { instruction, .. } => {
                                Some(instruction.clone())
                            }
                            KnowledgeFragment::Guideline { rule, .. } => Some(rule.clone()),
                            _ => None,
                        })
                        .unwrap_or_else(|| format!("{} v{}", self.id, self.version))
                }
            };

            // Take first ~100 chars or first sentence
            let truncated = content.chars().take(100).collect::<String>();
            if truncated.len() < content.len() {
                format!("{}...", truncated.trim_end())
            } else {
                truncated
            }
        } else {
            // No fragments, use id/version
            format!("{} v{}", self.id, self.version)
        }
    }

    /// Extract tool definitions as capability names
    ///
    /// This method scans all fragments and extracts tool names from `ToolDefinition` fragments.
    /// Returns a vector of capability identifiers that can be used for agent registration.
    ///
    /// Note: This is a basic implementation that extracts tool names from JSON schemas.
    /// For use with llm-toolkit's `Capability` type, enable the "integration" feature.
    pub fn extract_tool_names(&self) -> Vec<String> {
        self.content
            .iter()
            .filter_map(|wf| match &wf.fragment {
                KnowledgeFragment::ToolDefinition(tool_json) => {
                    // Try to extract a name from the tool definition
                    tool_json
                        .get("name")
                        .and_then(|v| v.as_str())
                        .map(|s| s.to_string())
                        .or_else(|| {
                            // Fallback: use the type field if no name
                            tool_json
                                .get("type")
                                .and_then(|v| v.as_str())
                                .map(|s| s.to_string())
                        })
                }
                _ => None,
            })
            .collect()
    }

    /// Generate a single prompt string from all fragments
    ///
    /// Fragments are ordered by priority (Critical → High → Normal → Low)
    pub fn to_prompt(&self) -> String {
        self.to_prompt_with_context(&ContextMatcher::default())
    }

    /// Generate a prompt string with render context filtering (Phase 2)
    ///
    /// This is the new context-aware rendering API that supports multiple user states
    /// and improved context matching.
    ///
    /// # Examples
    ///
    /// ```
    /// use llm_toolkit_expertise::{Expertise, WeightedFragment, KnowledgeFragment};
    /// use llm_toolkit_expertise::render::RenderContext;
    /// use llm_toolkit_expertise::context::TaskHealth;
    ///
    /// let expertise = Expertise::new("test", "1.0")
    ///     .with_fragment(WeightedFragment::new(
    ///         KnowledgeFragment::Text("Test".to_string())
    ///     ));
    ///
    /// let context = RenderContext::new()
    ///     .with_task_type("security-review")
    ///     .with_task_health(TaskHealth::AtRisk);
    ///
    /// let prompt = expertise.to_prompt_with_render_context(&context);
    /// ```
    pub fn to_prompt_with_render_context(&self, context: &crate::render::RenderContext) -> String {
        // Convert RenderContext to ContextMatcher for now
        // In the future, we can refactor to use RenderContext directly
        self.to_prompt_with_context(&context.to_context_matcher())
    }

    /// Generate a prompt string with context filtering (legacy API)
    ///
    /// Only includes fragments that match the given context conditions.
    ///
    /// **Note**: Consider using `to_prompt_with_render_context()` for the new API
    /// with improved context matching.
    pub fn to_prompt_with_context(&self, context: &ContextMatcher) -> String {
        let mut result = format!("# Expertise: {} (v{})\n\n", self.id, self.version);

        if !self.tags.is_empty() {
            result.push_str("**Tags:** ");
            result.push_str(&self.tags.join(", "));
            result.push_str("\n\n");
        }

        result.push_str("---\n\n");

        // Sort fragments by priority (highest first)
        let mut sorted_fragments: Vec<_> = self
            .content
            .iter()
            .filter(|f| f.context.matches(context))
            .collect();
        sorted_fragments.sort_by(|a, b| b.priority.cmp(&a.priority));

        // Group by priority
        let mut current_priority: Option<Priority> = None;
        for weighted in sorted_fragments {
            // Add priority header if changed
            if current_priority != Some(weighted.priority) {
                current_priority = Some(weighted.priority);
                result.push_str(&format!("## Priority: {}\n\n", weighted.priority.label()));
            }

            // Add fragment content
            result.push_str(&weighted.fragment.to_prompt());
            result.push('\n');
        }

        result
    }

    /// Generate a Mermaid graph representation
    pub fn to_mermaid(&self) -> String {
        let mut result = String::from("graph TD\n");

        // Root node (expertise)
        result.push_str(&format!("    ROOT[\"Expertise: {}\"]\n", self.id));

        // Add tag nodes if present
        if !self.tags.is_empty() {
            result.push_str("    TAGS[\"Tags\"]\n");
            result.push_str("    ROOT --> TAGS\n");
            for (i, tag) in self.tags.iter().enumerate() {
                let tag_id = format!("TAG{}", i);
                result.push_str(&format!("    {}[\"{}\"]\n", tag_id, tag));
                result.push_str(&format!("    TAGS --> {}\n", tag_id));
            }
        }

        // Add fragment nodes
        for (i, weighted) in self.content.iter().enumerate() {
            let node_id = format!("F{}", i);
            let summary = weighted.fragment.summary();
            let type_label = weighted.fragment.type_label();

            // Node with priority styling
            let style_class = match weighted.priority {
                Priority::Critical => ":::critical",
                Priority::High => ":::high",
                Priority::Normal => ":::normal",
                Priority::Low => ":::low",
            };

            result.push_str(&format!(
                "    {}[\"{} [{}]: {}\"]{}\n",
                node_id,
                weighted.priority.label(),
                type_label,
                summary,
                style_class
            ));
            result.push_str(&format!("    ROOT --> {}\n", node_id));

            // Add context info if conditional
            if let ContextProfile::Conditional {
                task_types,
                user_states,
                task_health,
            } = &weighted.context
            {
                let context_id = format!("C{}", i);
                let mut context_parts = Vec::new();

                if !task_types.is_empty() {
                    context_parts.push(format!("Tasks: {}", task_types.join(", ")));
                }
                if !user_states.is_empty() {
                    context_parts.push(format!("States: {}", user_states.join(", ")));
                }
                if let Some(health) = task_health {
                    context_parts.push(format!("Health: {}", health.label()));
                }

                if !context_parts.is_empty() {
                    result.push_str(&format!(
                        "    {}[\"Context: {}\"]\n",
                        context_id,
                        context_parts.join("; ")
                    ));
                    result.push_str(&format!("    {} -.-> {}\n", node_id, context_id));
                }
            }
        }

        // Add styling
        result.push_str("\n    classDef critical fill:#ff6b6b,stroke:#c92a2a,stroke-width:3px\n");
        result.push_str("    classDef high fill:#ffd93d,stroke:#f08c00,stroke-width:2px\n");
        result.push_str("    classDef normal fill:#a0e7e5,stroke:#4ecdc4,stroke-width:1px\n");
        result.push_str("    classDef low fill:#e0e0e0,stroke:#999,stroke-width:1px\n");

        result
    }

    /// Generate a simple tree representation
    pub fn to_tree(&self) -> String {
        let mut result = format!("Expertise: {} (v{})\n", self.id, self.version);

        if !self.tags.is_empty() {
            result.push_str(&format!("├─ Tags: {}\n", self.tags.join(", ")));
        }

        result.push_str("└─ Content:\n");

        // Sort by priority
        let mut sorted_fragments: Vec<_> = self.content.iter().collect();
        sorted_fragments.sort_by(|a, b| b.priority.cmp(&a.priority));

        for (i, weighted) in sorted_fragments.iter().enumerate() {
            let is_last = i == sorted_fragments.len() - 1;
            let prefix = if is_last { "   └─" } else { "   ├─" };

            let summary = weighted.fragment.summary();
            let type_label = weighted.fragment.type_label();

            result.push_str(&format!(
                "{} [{}] {}: {}\n",
                prefix,
                weighted.priority.label(),
                type_label,
                summary
            ));

            // Add context info
            if let ContextProfile::Conditional {
                task_types,
                user_states,
                task_health,
            } = &weighted.context
            {
                let sub_prefix = if is_last { "      " } else { "   │  " };
                if !task_types.is_empty() {
                    result.push_str(&format!(
                        "{} └─ Tasks: {}\n",
                        sub_prefix,
                        task_types.join(", ")
                    ));
                }
                if !user_states.is_empty() {
                    result.push_str(&format!(
                        "{} └─ States: {}\n",
                        sub_prefix,
                        user_states.join(", ")
                    ));
                }
                if let Some(health) = task_health {
                    result.push_str(&format!(
                        "{} └─ Health: {} {}\n",
                        sub_prefix,
                        health.emoji(),
                        health.label()
                    ));
                }
            }
        }

        result
    }
}

/// WeightedFragment: Knowledge entity with metadata
///
/// Combines a knowledge fragment with its priority and activation context.
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
pub struct WeightedFragment {
    /// Priority: Controls enforcement strength and ordering
    #[serde(default)]
    pub priority: Priority,

    /// Context: Activation conditions
    #[serde(default)]
    pub context: ContextProfile,

    /// Fragment: The actual knowledge content
    pub fragment: KnowledgeFragment,
}

impl WeightedFragment {
    /// Create a new weighted fragment with default priority and always-active context
    pub fn new(fragment: KnowledgeFragment) -> Self {
        Self {
            priority: Priority::default(),
            context: ContextProfile::default(),
            fragment,
        }
    }

    /// Set priority
    pub fn with_priority(mut self, priority: Priority) -> Self {
        self.priority = priority;
        self
    }

    /// Set context profile
    pub fn with_context(mut self, context: ContextProfile) -> Self {
        self.context = context;
        self
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_expertise_builder() {
        let expertise = Expertise::new("test", "1.0")
            .with_description("Test description")
            .with_tag("test-tag")
            .with_fragment(WeightedFragment::new(KnowledgeFragment::Text(
                "Test content".to_string(),
            )));

        assert_eq!(expertise.id, "test");
        assert_eq!(expertise.version, "1.0");
        assert_eq!(expertise.description, Some("Test description".to_string()));
        assert_eq!(expertise.tags.len(), 1);
        assert_eq!(expertise.content.len(), 1);
    }

    #[test]
    fn test_to_prompt_ordering() {
        let expertise = Expertise::new("test", "1.0")
            .with_fragment(
                WeightedFragment::new(KnowledgeFragment::Text("Low priority".to_string()))
                    .with_priority(Priority::Low),
            )
            .with_fragment(
                WeightedFragment::new(KnowledgeFragment::Text("Critical priority".to_string()))
                    .with_priority(Priority::Critical),
            )
            .with_fragment(
                WeightedFragment::new(KnowledgeFragment::Text("Normal priority".to_string()))
                    .with_priority(Priority::Normal),
            );

        let prompt = expertise.to_prompt();

        // Critical should appear before Normal, Normal before Low
        let critical_pos = prompt.find("Critical priority").unwrap();
        let normal_pos = prompt.find("Normal priority").unwrap();
        let low_pos = prompt.find("Low priority").unwrap();

        assert!(critical_pos < normal_pos);
        assert!(normal_pos < low_pos);
    }

    #[test]
    fn test_context_filtering() {
        let expertise = Expertise::new("test", "1.0")
            .with_fragment(
                WeightedFragment::new(KnowledgeFragment::Text("Always visible".to_string()))
                    .with_context(ContextProfile::Always),
            )
            .with_fragment(
                WeightedFragment::new(KnowledgeFragment::Text("Debug only".to_string()))
                    .with_context(ContextProfile::Conditional {
                        task_types: vec!["Debug".to_string()],
                        user_states: vec![],
                        task_health: None,
                    }),
            );

        // Without debug context
        let prompt1 = expertise.to_prompt_with_context(&ContextMatcher::new());
        assert!(prompt1.contains("Always visible"));
        assert!(!prompt1.contains("Debug only"));

        // With debug context
        let prompt2 =
            expertise.to_prompt_with_context(&ContextMatcher::new().with_task_type("Debug"));
        assert!(prompt2.contains("Always visible"));
        assert!(prompt2.contains("Debug only"));
    }

    #[test]
    fn test_to_tree() {
        let expertise = Expertise::new("test", "1.0")
            .with_tag("test-tag")
            .with_fragment(WeightedFragment::new(KnowledgeFragment::Text(
                "Test content".to_string(),
            )));

        let tree = expertise.to_tree();
        assert!(tree.contains("Expertise: test"));
        assert!(tree.contains("test-tag"));
        assert!(tree.contains("Test content"));
    }

    #[test]
    fn test_to_mermaid() {
        let expertise = Expertise::new("test", "1.0").with_fragment(WeightedFragment::new(
            KnowledgeFragment::Text("Test content".to_string()),
        ));

        let mermaid = expertise.to_mermaid();
        assert!(mermaid.contains("graph TD"));
        assert!(mermaid.contains("Expertise: test"));
        assert!(mermaid.contains("Test content"));
    }
}