zclaw_openfang/crates/zclaw-growth/src/lib.rs

//! ZCLAW Agent Growth System
//!
//! This crate provides the agent growth functionality for ZCLAW,
//! enabling agents to learn and evolve from conversations.
//!
//! # Architecture
//!
//! The growth system consists of several subsystems:
//!
//! ## Memory Pipeline (L0-L2)
//!
//! 1. **MemoryExtractor** (`extractor`) - Analyzes conversations and extracts
//!    preferences, knowledge, and experience using LLM. Supports combined extraction
//!    (single LLM call for memories + experiences + profile signals).
//!
//! 2. **MemoryRetriever** (`retriever`) - Performs semantic search over
//!    stored memories to find contextually relevant information.
//!
//! 3. **PromptInjector** (`injector`) - Injects retrieved memories into
//!    the system prompt with token budget control.
//!
//! 4. **GrowthTracker** (`tracker`) - Tracks growth metrics and evolution
//!    over time.
//!
//! ## Evolution Engine (L1-L3)
//!
//! 5. **ExperienceStore** (`experience_store`) - FTS5-backed structured experience storage.
//!
//! 6. **PatternAggregator** (`pattern_aggregator`) - Collects high-frequency patterns for L2.
//!
//! 7. **SkillGenerator** (`skill_generator`) - LLM-driven SKILL.md content generation.
//!
//! 8. **QualityGate** (`quality_gate`) - Validates candidate skills (confidence, conflicts).
//!
//! 9. **EvolutionEngine** (`evolution_engine`) - Orchestrates L1/L2/L3 evolution phases.
//!
//! 10. **WorkflowComposer** (`workflow_composer`) - Extracts tool chain patterns for Pipeline YAML.
//!
//! 11. **FeedbackCollector** (`feedback_collector`) - Trust score management with decay.
//!
//! ## Support Modules
//!
//! 12. **VikingAdapter** (`viking_adapter`) - Storage abstraction (in-memory + SQLite backends).
//! 13. **Summarizer** (`summarizer`) - L0/L1 summary generation.
//! 14. **JsonUtils** (`json_utils`) - Shared JSON parsing utilities.
//!
//! # Storage
//!
//! All memories are stored in OpenViking with a URI structure:
//!
//! ```text
//! agent://{agent_id}/
//! ├── preferences/{category}  - User preferences
//! ├── knowledge/{domain}      - Accumulated knowledge
//! ├── experience/{skill}      - Skill/tool experience
//! └── sessions/{session_id}/  - Conversation history
//!     ├── raw                 - Original conversation (L0)
//!     ├── summary             - Summary (L1)
//!     └── keywords            - Keywords (L2)
//! ```
//!
//! # Usage
//!
//! ```rust,ignore
//! use zclaw_growth::{MemoryExtractor, MemoryRetriever, PromptInjector, VikingAdapter};
//!
//! // Create components
//! let viking = VikingAdapter::in_memory();
//! let retriever = MemoryRetriever::new(Arc::new(viking.clone()));
//! let injector = PromptInjector::new();
//!
//! // Before conversation: retrieve relevant memories
//! let memories = retriever.retrieve(&agent_id, &user_input).await?;
//!
//! // Inject into system prompt
//! let enhanced_prompt = injector.inject(&base_prompt, &memories);
//!
//! // After conversation: extract and store new memories
//! let extracted = extractor.extract(&messages, session_id).await?;
//! extractor.store_memories(&agent_id, &extracted).await?;
//! ```

pub mod types;
pub mod extractor;
pub mod retriever;
pub mod injector;
pub mod tracker;
pub mod viking_adapter;
pub mod storage;
pub mod retrieval;
pub mod summarizer;
pub mod experience_store;
pub mod json_utils;
pub mod experience_extractor;
pub mod profile_updater;
pub mod pattern_aggregator;
pub mod skill_generator;
pub mod quality_gate;
pub mod evolution_engine;
pub mod workflow_composer;
pub mod feedback_collector;

// Re-export main types for convenience
pub use types::{
    DecayResult,
    ExtractedMemory,
    ExtractionConfig,
    GrowthStats,
    MemoryEntry,
    MemoryType,
    RetrievalConfig,
    RetrievalResult,
    UriBuilder,
    effective_importance,
    ArtifactType,
    CombinedExtraction,
    EvolutionEvent,
    EvolutionEventType,
    EvolutionStatus,
    ExperienceCandidate,
    Outcome,
    ProfileSignals,
};

pub use extractor::{LlmDriverForExtraction, MemoryExtractor};
pub use retriever::{MemoryRetriever, MemoryStats};
pub use injector::{InjectionFormat, PromptInjector};
pub use tracker::{AgentMetadata, GrowthTracker, LearningEvent};
pub use viking_adapter::{FindOptions, VikingAdapter, VikingLevel, VikingStorage};
pub use storage::SqliteStorage;
pub use experience_store::{Experience, ExperienceStore};
pub use retrieval::{EmbeddingClient, MemoryCache, QueryAnalyzer, SemanticScorer};
pub use summarizer::SummaryLlmDriver;
pub use experience_extractor::ExperienceExtractor;
pub use json_utils::{extract_json_block, extract_string_array};
pub use profile_updater::{ProfileFieldUpdate, ProfileUpdateKind, UserProfileUpdater};
pub use pattern_aggregator::{AggregatedPattern, PatternAggregator};
pub use skill_generator::{SkillCandidate, SkillGenerator};
pub use quality_gate::{QualityGate, QualityReport};
pub use evolution_engine::{EvolutionConfig, EvolutionEngine};
pub use workflow_composer::{PipelineCandidate, ToolChainPattern, WorkflowComposer};
pub use feedback_collector::{
    EvolutionArtifact, FeedbackCollector, FeedbackEntry, FeedbackSignal,
    RecommendedAction, Sentiment, TrustRecord, TrustUpdate,
};

/// Growth system configuration
#[derive(Debug, Clone)]
pub struct GrowthConfig {
    /// Enable/disable growth system
    pub enabled: bool,
    /// Retrieval configuration
    pub retrieval: RetrievalConfig,
    /// Extraction configuration
    pub extraction: ExtractionConfig,
    /// Auto-extract after each conversation
    pub auto_extract: bool,
}

impl Default for GrowthConfig {
    fn default() -> Self {
        Self {
            enabled: true,
            retrieval: RetrievalConfig::default(),
            extraction: ExtractionConfig::default(),
            auto_extract: true,
        }
    }
}

/// Convenience function to create a complete growth system
pub fn create_growth_system(
    viking: std::sync::Arc<VikingAdapter>,
    llm_driver: std::sync::Arc<dyn LlmDriverForExtraction>,
) -> (MemoryExtractor, MemoryRetriever, PromptInjector, GrowthTracker) {
    let extractor = MemoryExtractor::new(llm_driver).with_viking(viking.clone());
    let retriever = MemoryRetriever::new(viking.clone());
    let injector = PromptInjector::new();
    let tracker = GrowthTracker::new(viking);

    (extractor, retriever, injector, tracker)
}

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

    #[test]
    fn test_growth_config_default() {
        let config = GrowthConfig::default();
        assert!(config.enabled);
        assert!(config.auto_extract);
        assert_eq!(config.retrieval.max_tokens, 500);
    }

    #[test]
    fn test_memory_type_reexport() {
        let mt = MemoryType::Preference;
        assert_eq!(format!("{}", mt), "preferences");
    }
}