◉ClassyGitShadowzzh

base.py

base.py
# coding: utf-8
# Copyright (c) 2025 inclusionAI.

import uuid
from abc import ABC, abstractmethod
from datetime import datetime
from typing import List, Any, Optional, Literal

from pydantic import BaseModel, Field

from aworld.core.memory import MemoryStore, LongTermConfig
from aworld.models.llm import LLMModel
from aworld.memory.models import UserProfile, AgentExperience, LongTermExtractParams


class MemoryProcessingResult(BaseModel):
    """
    Represents the result of memory processing operation.
    """
    task_id: str = Field(default=None, description="Task identifier")
    success: bool = Field(default=False, description="Success flag")
    user_profiles: Optional[List[UserProfile]] = Field(default_factory=list, description="User profiles")
    agent_experiences: Optional[List[AgentExperience]] = Field(default_factory=list, description="Agent experiences")
    finished_at: Optional[str] = Field(default=str(datetime.now().isoformat()), description="Finished timestamp")
    error_message: Optional[str] = Field(default=None, description="Error message")

class MemoryProcessingTask(BaseModel):
    """
    Represents a memory processing task containing information needed for long-term memory processing.
    
    Args:
        memory_task_id: Task identifier
        task_type: Task type
        extract_params: Long-term extract parameters
        created_at: Creation timestamp
        finished_at: Finished timestamp
    """
    memory_task_id: str = Field(default=str(uuid.uuid4()), description="Memory task identifier")
    task_type: Literal['user_profile', 'agent_experience'] = Field(..., description="Memory task type")
    extract_params: LongTermExtractParams = Field(description="Long-term extract parameters")
    metadata: dict[str, Any] = Field(default_factory=dict, description="Metadata")
    created_at: str = Field(default_factory=lambda: datetime.now().isoformat(), description="Creation timestamp")
    finished_at: str = Field(default=None, description="Finished timestamp")
    status: Literal['initial', 'processing', 'completed', 'failed'] = Field(default='initial', description="Task status")
    result: Optional[MemoryProcessingResult] = Field(default=None, description="Processing result")
    longterm_config: LongTermConfig = Field(description="Long-term memory configuration")

class MemoryOrchestrator(ABC):

    """
    Abstract base class for memory orchestrator that determines when and how to process memories.
    Responsible for evaluating trigger conditions and creating processing tasks.
    """
    
    def __init__(self, llm_instance: LLMModel,
                 longterm_config: LongTermConfig,
                 embedding_model: Optional[Any] = None,
                 long_term_memory_store: MemoryStore = None) -> None:
        """
        Initialize the memory orchestrator.
        
        Args:
            llm_instance: LLM model instance for processing
        """
        self._llm_instance = llm_instance
        self._longterm_config = longterm_config
        self._embedding_model = embedding_model
        self._long_term_memory_store: MemoryStore = long_term_memory_store


    @abstractmethod
    async def create_longterm_processing_tasks(self,
                                         extract_param_list: list[LongTermExtractParams],
                                         longterm_config: LongTermConfig
                                         ) -> None:
        """
        Create long-term memory processing tasks from the given memory items.

        Args:
            task_params: List of long-term extract parameters
            longterm_config: Long-term memory configuration settings
        """
        pass


    @abstractmethod
    async def retrieve_agent_experience(
        self, 
        query: str, 
        agent_id: Optional[str] = None,
        application_id: Optional[str] = "default",
    ) -> List[AgentExperience]:
        """
        Retrieve similar agent experiences from long-term storage for context.
        
        Args:
            query: Query string for similarity search
            agent_id: Agent identifier for filtering
            application_id: Application identifier for filtering
            
        Returns:
            List of similar memory items
        """
        pass

    @abstractmethod
    async def retrieve_user_profile(
        self, 
        query: str, 
        user_id: Optional[str] = None,
        application_id: Optional[str] = "default",
    ) -> List[UserProfile]:
        """
        Retrieve similar user profiles from long-term storage for context.

        Args:
            query: Query string for similarity search
            user_id: User identifier for filtering
            application_id: Application identifier for filtering
            
        Returns:
            List of similar memory items
        """
        pass


class MemoryGungnir(ABC):
    """
    Abstract base class for memory processing engine (Gungnir - the eternal spear of memory).
    Responsible for extracting and processing long-term memories from short-term memory items.
    """
    
    def __init__(self, llm_instance: LLMModel) -> None:
        """
        Initialize the memory processing engine.
        
        Args:
            llm_instance: LLM model instance for processing
        """
        self._llm_instance = llm_instance
    

    @abstractmethod
    async def process_memory_task(
        self, 
        task: MemoryProcessingTask
    ) -> MemoryProcessingResult:
        """
        Process a memory task and extract long-term memories.
        
        Args:
            task: Memory processing task to execute
            
        Returns:
            Processing result containing extracted memories
        """
        pass