noesium 0.1.0__py3-none-any.whl → 0.2.1__py3-none-any.whl

noesium/agents/askura_agent/extractor.py

@@ -0,0 +1,175 @@
+"""
+Information Extractor for AskuraAgent - Handles multi-topic information extraction.
+"""
+
+from typing import Any, Dict, Optional
+
+try:
+    from langchain_core.tools import BaseTool
+
+    LANGCHAIN_AVAILABLE = True
+except ImportError:
+    BaseTool = None
+    LANGCHAIN_AVAILABLE = False
+
+from noesium.core.llm import BaseLLMClient
+from noesium.core.utils.logging import get_logger
+
+from .models import AskuraConfig, AskuraState, InformationSlot
+
+logger = get_logger(__name__)
+
+
+class InformationExtractor:
+    """Handles extraction of information from user messages."""
+
+    def __init__(
+        self, config: AskuraConfig, extraction_tools: Dict[str, Any], llm_client: Optional[BaseLLMClient] = None
+    ):
+        """Initialize the information extractor."""
+        self.config = config
+        self.extraction_tools = extraction_tools
+        self.llm = llm_client
+
+    def extract_all_information(self, user_message: str, current_state: Optional[AskuraState] = None) -> Dict[str, Any]:
+        """Extract all possible information from a user message using all available tools.
+
+        Args:
+            user_message: The current user message to extract information from
+            current_state: Optional current state containing previously extracted information
+        """
+        extracted_info = {}
+
+        # Get current partial extraction state for context
+        current_extractions = {}
+        if current_state and current_state.extracted_info:
+            current_extractions = current_state.extracted_info.copy()
+
+        for slot in self.config.information_slots:
+            if not slot.extraction_tools:
+                continue
+            try:
+                result = self._extract_slot_information_with_tools(user_message, slot, current_extractions)
+                if result:
+                    extracted_info[slot.name] = result
+            except Exception as e:
+                logger.warning(f"Failed to extract {slot.name}: {e}")
+
+        return self._merge_extracted_info(current_state, extracted_info)
+
+    def _merge_extracted_info(self, state: AskuraState, extracted_info: Dict[str, Any]) -> Dict[str, Any]:
+        """Update state with extracted information, handling conflicts and merging data."""
+        merged = state.extracted_info
+        for slot_name, extracted_value in extracted_info.items():
+            if not merged.get(slot_name):
+                # Simple assignment for new values
+                merged[slot_name] = extracted_value
+                logger.info(f"Extracted slot {slot_name}: {extracted_value}")
+            else:
+                # Merge existing values for certain types
+                merged[slot_name] = self._merge_values(merged[slot_name], extracted_value, slot_name)
+                logger.info(f"Updated slot {slot_name}: {merged[slot_name]}")
+        return merged
+
+    def _extract_slot_information_with_tools(
+        self, user_message: str, slot: InformationSlot, current_extractions: Dict[str, Any]
+    ) -> Optional[Any]:
+        """Extract information for a specific slot with context from current extractions."""
+        valid_tools = [tool_name for tool_name in slot.extraction_tools if tool_name in self.extraction_tools]
+        if not valid_tools:
+            logger.warning(f"No valid tools found for slot {slot.name}, skipping extraction")
+            return None
+
+        for tool_name in valid_tools:
+            try:
+                tool = self.extraction_tools[tool_name]
+
+                # Prepare context for the tool
+                context_prompt = self._build_extraction_context_prompt(slot, current_extractions)
+                tool_context = {
+                    "user_message": user_message,
+                    "slot_name": slot.name,
+                    "slot_description": slot.description,
+                    "current_extractions": current_extractions,
+                    "conversation_context": current_extractions,
+                    "context_prompt": context_prompt,
+                }
+
+                # Handle both callable tools and LangChain tools
+                if isinstance(tool, BaseTool):
+                    result = tool.invoke(tool_context)
+                elif callable(tool):
+                    # Pass context to callable tools
+                    try:
+                        result = tool(user_message, current_extractions)
+                    except TypeError:
+                        # Fallback to original signature if tool doesn't accept context
+                        result = tool(user_message)
+                else:
+                    logger.warning(f"Tool {tool_name} is not callable or a LangChain tool, skipping")
+                    continue
+
+                # Check if the tool returned useful information
+                if result and self._is_valid_extraction(result, slot):
+                    return self._process_extraction_result(result, slot)
+
+            except Exception as e:
+                logger.warning(f"Tool {tool_name} failed: {e}")
+                continue
+
+        return None
+
+    def _is_valid_extraction(self, result: Dict[str, Any], slot: InformationSlot) -> bool:
+        """Check if the extraction result is valid for the slot."""
+        # Basic validation - check if result has any non-empty values
+        if not result:
+            return False
+
+        # Check if any value in the result is not None/empty
+        for value in result.values():
+            if value is not None and value != "" and value != []:
+                return True
+
+        return False
+
+    def _process_extraction_result(self, result: Dict[str, Any], slot: InformationSlot) -> Any:
+        """Process the extraction result based on slot configuration."""
+        # For now, return the result as-is
+        # This can be extended with more sophisticated processing
+        return result
+
+    def _merge_values(self, existing_value: Any, new_value: Any, slot_name: str) -> Any:
+        """Merge existing and new values intelligently."""
+
+        # Handle list merging
+        if isinstance(existing_value, list) and isinstance(new_value, list):
+            # Merge and deduplicate
+            merged = list(set(existing_value + new_value))
+            return merged
+
+        # Handle dict merging
+        elif isinstance(existing_value, dict) and isinstance(new_value, dict):
+            merged = existing_value.copy()
+            merged.update(new_value)
+            return merged
+
+        # For other types, prefer the new value if it's not None/empty
+        elif new_value is not None and new_value != "" and new_value != []:
+            return new_value
+        else:
+            return existing_value
+
+    def _build_extraction_context_prompt(self, slot: InformationSlot, current_extractions: Dict[str, Any]) -> str:
+        """Build a context prompt to help tools understand current extraction state."""
+        if not current_extractions:
+            return f"Extract information for slot '{slot.name}': {slot.description}"
+
+        context_parts = [f"Extract information for slot '{slot.name}': {slot.description}"]
+        context_parts.append("\nCurrently extracted information:")
+
+        for slot_name, value in current_extractions.items():
+            if value and value not in (None, "", [], {}):
+                context_parts.append(f"- {slot_name}: {value}")
+
+        context_parts.append(f"\nFocus on extracting missing or additional information for '{slot.name}'.")
+        return "\n".join(context_parts)

noesium/agents/askura_agent/memory.py

@@ -0,0 +1,14 @@
+from typing import Any, Dict
+
+from .models import AskuraState
+
+
+class Memory:
+    def __init__(self):
+        pass
+
+    def save(self, state: AskuraState):
+        pass
+
+    def load(self, session_id: str) -> Dict[str, Any]:
+        return {}

noesium/agents/askura_agent/models.py

@@ -0,0 +1,239 @@
+"""
+Schemas for AskuraAgent - Flexible data structures for dynamic conversations.
+"""
+
+from enum import Enum
+from typing import Any, Dict, List, Optional, Sequence, Type, Union
+
+from pydantic import BaseModel, Field
+
+try:
+    from langchain_core.messages import BaseMessage
+
+    LANGCHAIN_AVAILABLE = True
+except ImportError:
+    BaseMessage = None
+    LANGCHAIN_AVAILABLE = False
+
+from noesium.core.consts import GEMINI_FLASH
+
+from .utils import get_enum_value
+
+
+class ConversationStyle(str, Enum):
+    """User conversation styles."""
+
+    DIRECT = "direct"
+    EXPLORATORY = "exploratory"
+    CASUAL = "casual"
+
+
+class ConversationDepth(str, Enum):
+    """Conversation depth levels."""
+
+    SURFACE = "surface"
+    MODERATE = "moderate"
+    DEEP = "deep"
+
+
+class UserConfidence(str, Enum):
+    """User confidence levels."""
+
+    LOW = "low"
+    MEDIUM = "medium"
+    HIGH = "high"
+
+
+class ConversationFlow(str, Enum):
+    """Conversation flow patterns."""
+
+    NATURAL = "natural"
+    GUIDED = "guided"
+    USER_LED = "user_led"
+
+
+class ConversationSentiment(str, Enum):
+    """Conversation sentiment states."""
+
+    POSITIVE = "positive"
+    NEUTRAL = "neutral"
+    NEGATIVE = "negative"
+    UNCERTAIN = "uncertain"
+
+
+class ConversationMomentum(str, Enum):
+    """Conversation momentum states."""
+
+    POSITIVE = "positive"
+    NEUTRAL = "neutral"
+    NEGATIVE = "negative"
+
+
+class NextActionPlan(BaseModel):
+    """Response for intent classification and next action determination."""
+
+    next_action: str = Field(description="The selected next action from available options")
+    intent_type: str = Field(description="Intent classification: 'smalltalk' or 'task'")
+    is_smalltalk: bool = Field(description="Whether the user's intent is smalltalk")
+    reasoning: str = Field(description="Brief explanation of why this action was chosen")
+    confidence: float = Field(default=0.0, description="Confidence score (0.0-1.0) in the action choice")
+
+
+class KnowledgeGapAnalysis(BaseModel):
+    """Analysis of knowledge gaps and next topics to explore."""
+
+    knowledge_gap_summary: str = Field(description="Overall summary of what's missing compared to conversation purpose")
+    critical_missing_info: List[str] = Field(
+        description="Most important information still needed", default_factory=list
+    )
+    suggested_next_topics: List[str] = Field(description="3-5 specific topics to explore next", default_factory=list)
+    readiness_to_proceed: float = Field(
+        description="Confidence (0.0-1.0) that we can proceed with current information", default=0.0
+    )
+    reasoning: str = Field(description="Analysis reasoning and recommendations")
+
+
+class MessageRoutingDecision(BaseModel):
+    """LLM-based routing decision for new messages."""
+
+    routing_destination: str = Field(description="Where to route: 'start_deep_thinking' or 'response_generator'")
+    reasoning: str = Field(description="Brief explanation of the routing decision")
+    confidence: float = Field(default=0.0, description="Confidence score (0.0-1.0) in the routing decision")
+
+
+class InformationSlot(BaseModel):
+    """Configuration for an information slot to be collected."""
+
+    name: str
+    description: str
+    priority: int = Field(default=1, description="Higher number = higher priority")
+    required: bool = Field(default=True)
+    extraction_tools: List[str] = Field(default_factory=list, description="Names of extraction tools to use")
+    extraction_model: Optional[Type[BaseModel]] = Field(default=None, description="Pydantic model class for extraction")
+    question_templates: Dict[str, Dict[str, Dict[str, str]]] = Field(default_factory=dict)
+    validation_rules: List[str] = Field(default_factory=list)
+    dependencies: List[str] = Field(default_factory=list, description="Other slots this depends on")
+
+    class Config:
+        """Pydantic configuration."""
+
+        use_enum_values = True
+
+
+class ConversationContext(BaseModel):
+    """Analysis of conversation context."""
+
+    # Conversation purpose
+    conversation_purpose: str = Field(default="")
+    conversation_on_track_confidence: float = Field(default=0.0)
+
+    # Conversation vibe
+    information_density: float = Field(default=0.0)
+    conversation_style: ConversationStyle = Field(default=ConversationStyle.DIRECT)
+    conversation_depth: ConversationDepth = Field(default=ConversationDepth.SURFACE)
+    user_confidence: UserConfidence = Field(default=UserConfidence.MEDIUM)
+    conversation_flow: ConversationFlow = Field(default=ConversationFlow.NATURAL)
+    conversation_momentum: ConversationMomentum = Field(default=ConversationMomentum.POSITIVE)
+    last_message_sentiment: ConversationSentiment = Field(default=ConversationSentiment.NEUTRAL)
+
+    class Config:
+        """Pydantic configuration."""
+
+        use_enum_values = True
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary."""
+        return {
+            "conversation_purpose": self.conversation_purpose,
+            "conversation_on_track_confidence": self.conversation_on_track_confidence,
+            "information_density": self.information_density,
+            "conversation_style": get_enum_value(self.conversation_style),
+            "conversation_depth": get_enum_value(self.conversation_depth),
+            "user_confidence": get_enum_value(self.user_confidence),
+            "conversation_flow": get_enum_value(self.conversation_flow),
+            "conversation_momentum": get_enum_value(self.conversation_momentum),
+            "last_message_sentiment": get_enum_value(self.last_message_sentiment),
+        }
+
+
+def keep_first(left: str, right: str) -> str:
+    return left if left else right
+
+
+class AskuraState(BaseModel):
+    """Core state for AskuraAgent conversations."""
+
+    # Metadata
+    user_id: str = Field(default="")
+    session_id: str = Field(default="")
+    turns: int = Field(default=0)
+    created_at: str = Field(default="")
+    updated_at: str = Field(default="")
+
+    # Conversation state
+    messages: Sequence[BaseMessage] = Field(default_factory=list)
+    conversation_context: ConversationContext = Field(default_factory=ConversationContext)
+
+    # Information slots (dynamic based on configuration)
+    extracted_info: Dict[str, Any] = Field(default_factory=dict)
+    missing_info: Dict[str, str] = Field(
+        default_factory=dict, description="Information slot name -> description of what's missing"
+    )
+    knowledge_gap: str = Field(
+        default="", description="Summary of knowledge gap between conversation purpose and current status"
+    )
+    suggested_next_topics: List[str] = Field(default_factory=list)
+
+    # Memory state
+    memory: Dict[str, Any] = Field(default_factory=dict)
+
+    # Next action analysis results
+    next_action_plan: Optional[NextActionPlan] = Field(default=None)
+
+    # Agent control
+    requires_user_input: bool = Field(default=True)
+    is_complete: bool = Field(default=False)
+    pending_extraction: bool = Field(default=False)
+
+    # Custom fields (for specific agents)
+    custom_data: Dict[str, Any] = Field(default_factory=dict)
+
+    class Config:
+        """Pydantic configuration."""
+
+        use_enum_values = True
+
+
+class AskuraConfig(BaseModel):
+    """Configuration for AskuraAgent."""
+
+    # LLM configuration
+    llm_api_provider: str = "openrouter"
+    model_name: str = GEMINI_FLASH
+    temperature: float = 0.7
+    max_tokens: int = 1000
+
+    # Purposes of the conversation
+    conversation_purpose: Union[List[str], str] = Field(default="")
+    max_conversation_turns: int = 15
+
+    # Information slots configuration
+    information_slots: List[InformationSlot] = Field(default_factory=list)
+
+    # Custom configuration
+    custom_config: Dict[str, Any] = Field(default_factory=dict)
+
+
+class AskuraResponse(BaseModel):
+    """Response from AskuraAgent."""
+
+    message: str
+    session_id: str
+    is_complete: bool = False
+    confidence: float = 0.0
+    next_actions: List[str] = Field(default_factory=list)
+    requires_user_input: bool = True
+    metadata: Dict[str, Any] = Field(default_factory=dict)
+
+    # Custom response data
+    custom_data: Dict[str, Any] = Field(default_factory=dict)

noesium/agents/askura_agent/prompts.py

@@ -0,0 +1,202 @@
+"""
+Prompts for AskuraAgent - Structured prompts for conversation analysis and management.
+"""
+
+# Structured extraction prompts - optimized for structured_completion
+CONVERSATION_ANALYSIS_SYSTEM_PROMPTS = {
+    "conversation_context": """Analyze conversation style and alignment with purpose.
+
+Assess key factors:
+- Style: direct (goal-oriented), exploratory (curious), casual (relaxed)
+- User confidence: low (hesitant), medium (balanced), high (assertive)
+- Flow: natural (organic), guided (following direction), user_led (user driving)
+- Sentiment: positive (enthusiastic), neutral (balanced), negative (frustrated), uncertain (confused)
+- Momentum: positive (building), neutral (steady), negative (losing interest)
+- On-track confidence (0.0-1.0): How well conversation aligns with purpose
+  * 0.0-0.3: Off-track, not addressing purpose
+  * 0.4-0.6: Partially on-track, some relevance  
+  * 0.7-0.8: Mostly on-track, good alignment
+  * 0.9-1.0: Highly focused on purpose""",
+    "knowledge_gap_analysis": """Analyze knowledge gap and suggest next topics to help achieve conversation purpose.
+
+**Instructions:**
+1. Evaluate how well current knowledge aligns with the conversation purpose
+2. Identify key knowledge gaps that prevent achieving the purpose
+3. Suggest 3-5 specific next topics that would help bridge these gaps
+4. Provide a clear summary of the overall knowledge gap
+5. Consider user's conversation style and preferences when suggesting topics
+
+**Analysis should help determine:**
+- Whether we have enough information to proceed
+- What critical information is still needed
+- How to prioritize gathering remaining information
+- Topics that would naturally engage the user based on their style""",
+    "determine_next_action": """Classify MOST RECENT message intent and select optimal next action.
+
+Intent Classification (focus ONLY on last message):
+- "smalltalk": Greetings, pleasantries, casual conversation
+- "task": Goal-oriented, information requests, specific questions, task content
+
+Decision Guidelines:
+- If MOST RECENT message is smalltalk: respond appropriately but guide toward task
+- If MOST RECENT message is task: focus on gathering missing information
+- If conversation off-track (<0.4): prioritize redirecting to purpose  
+- If conversation on-track (>0.7): focus on collecting missing info
+- If user confidence low: choose supportive, confidence-boosting actions
+- If momentum negative: provide encouragement or redirect
+- Balance staying on purpose with maintaining engagement
+
+Reasoning must explicitly reference the MOST RECENT user message.""",
+    "message_routing": """Evaluate if the user's message requires deep thinking or can be handled with a quick response to guide conversation.
+
+**Decision Criteria:**
+
+Deep thinking is required IF BOTH conditions are met:
+1. **Contains Purpose-Related Info**: Message contains information directly related to the conversation purpose
+2. **Needs Extraction/Reflection**: Message contains specific details, facts, preferences, or decisions that should be extracted and reflected upon
+
+Quick response is appropriate when:
+- Message is casual conversation, greetings, or small talk
+- Message is off-topic from the conversation purpose
+- Message asks general questions without providing extractable information
+- Message needs guidance to stay on topic
+
+**Instructions:**
+1. Evaluate if the message contains information related to the conversation purpose
+2. Determine if the message contains extractable information that requires reflection
+3. Choose routing destination: 'start_deep_thinking' if both criteria met, otherwise 'response_generator'
+4. Explain your reasoning clearly""",
+}
+
+CONVERSATION_ANALYSIS_USER_PROMPTS = {
+    "conversation_context": """Conversation purpose: {conversation_purpose}
+
+Recent messages: {recent_messages}""",
+    "knowledge_gap_analysis": """**Conversation Purpose:** {conversation_purpose}
+
+**Current Context:**
+{conversation_context}
+
+**What We Know (Extracted Information):**
+{extracted_info}
+
+**What We're Missing (Required Information):**
+{missing_info}
+
+**Retrieved Memory:**
+{memory}
+
+**Recent Conversation:**
+{recent_messages}""",
+    "determine_next_action": """Context: {conversation_context}
+Ready to summarize: {ready_to_summarize}
+Available actions: {available_actions}
+Recent messages: {recent_messages}""",
+    "message_routing": """**Conversation Purpose:** {conversation_purpose}
+
+**Current User Message:** {user_message}
+
+**Conversation Context:**
+{conversation_context}
+
+**Current Extracted Information:**
+{extracted_info}""",
+}
+
+# Backward compatibility - combined prompts for legacy usage
+CONVERSATION_ANALYSIS_PROMPTS = {
+    "conversation_context": CONVERSATION_ANALYSIS_SYSTEM_PROMPTS["conversation_context"]
+    + "\n\n"
+    + CONVERSATION_ANALYSIS_USER_PROMPTS["conversation_context"],
+    "knowledge_gap_analysis": CONVERSATION_ANALYSIS_SYSTEM_PROMPTS["knowledge_gap_analysis"]
+    + "\n\n"
+    + CONVERSATION_ANALYSIS_USER_PROMPTS["knowledge_gap_analysis"],
+    "determine_next_action": CONVERSATION_ANALYSIS_SYSTEM_PROMPTS["determine_next_action"]
+    + "\n\n"
+    + CONVERSATION_ANALYSIS_USER_PROMPTS["determine_next_action"],
+    "message_routing": CONVERSATION_ANALYSIS_SYSTEM_PROMPTS["message_routing"]
+    + "\n\n"
+    + CONVERSATION_ANALYSIS_USER_PROMPTS["message_routing"],
+}
+
+
+def get_conversation_analysis_prompts(analysis_type: str, **kwargs) -> tuple[str, str]:
+    """Get separated system and user prompts for conversation analysis."""
+    system_prompt = CONVERSATION_ANALYSIS_SYSTEM_PROMPTS.get(analysis_type, "")
+    user_prompt_template = CONVERSATION_ANALYSIS_USER_PROMPTS.get(analysis_type, "")
+
+    try:
+        user_prompt = user_prompt_template.format(**kwargs)
+        return system_prompt, user_prompt
+    except KeyError:
+        return system_prompt, user_prompt_template
+
+
+def get_conversation_analysis_prompt(analysis_type: str, **kwargs) -> str:
+    """Backward compatibility - get combined prompt for conversation analysis."""
+    prompt = CONVERSATION_ANALYSIS_PROMPTS.get(analysis_type, "")
+    try:
+        return prompt.format(**kwargs)
+    except KeyError:
+        return prompt
+
+
+# TODO (xmingc): I like the idea of letting the system hold a limited number of improvisations.
+RESPONSE_GENERATION_SYSTEM_PROMPT = """You are a witty and creative travel planning assistant. Generate a short, precise, and inspiring question that incorporates relevant context naturally. Feel free to make slight improvisations - add wordplay, use creative language, make clever observations, or add a touch of humor when appropriate. The question should be conversational, memorable, and always encouraging.
+Keep it under 3 sentences but make it delightful and engaging. Return only the question, no additional text.
+
+**Strategic Response Guidelines:**
+- **Balance natural conversation with purposeful direction** - Be genuinely conversational but strategically guide toward missing information
+- **Ask strategic follow-up questions** - Frame questions around genuine curiosity that happens to align with our information goals
+- **Provide context and options** - When guiding toward a topic, give examples or choices to make it easier for the user to respond
+- **Build on user's interests** - Connect their current topic to the information we need to collect. When user shows interest but may lack knowledge, provide concrete options/suggestions
+- Ask ONE specific question that helps the user think about their plans
+
+**Information Collection Strategies:**
+- **For destination/location info**: Share travel experiences, ask about dream places, mention interesting locations
+- **For dates/timing**: Talk about seasons, upcoming events, or personal scheduling preferences  
+- **For interests/preferences**: Share enthusiasm about activities, ask about past experiences, mention options
+- **For logistics (budget, group size)**: Frame around planning considerations or past experiences
+- **For general context**: Use open-ended questions that invite storytelling and detailed sharing
+
+**Special Cases:**
+- **If no information is missing**: Focus on deeper exploration, clarification, or moving toward completion
+- **If user seems hesitant**: Provide encouragement and make sharing feel easier with specific examples or options
+- **If off-topic**: Gently redirect through relevant connections or shared interests
+
+Generate a single, natural response without quotes or formatting - just the raw conversational text that feels natural while strategically moving toward the missing information we need."""
+
+RESPONSE_GENERATION_USER_PROMPT = """**Conversation Purpose:** {conversation_purpose}
+**Missing Key Information:** {missing_required_slots}
+
+**Current Situation:**
+- User's intent: {intent_type}  
+- Context: {next_action_reasoning}
+- What we know: {known_slots}
+
+Generate an appropriate response based on this context."""
+
+# Backward compatibility - combined prompt for legacy usage
+RESPONSE_GENERATION_PROMPT = RESPONSE_GENERATION_SYSTEM_PROMPT + "\n\n" + RESPONSE_GENERATION_USER_PROMPT
+
+
+def get_response_generation_prompts(**kwargs) -> tuple[str, str]:
+    """Get separated system and user prompts for response generation."""
+    try:
+        user_prompt = RESPONSE_GENERATION_USER_PROMPT.format(**kwargs)
+        return RESPONSE_GENERATION_SYSTEM_PROMPT, user_prompt
+    except KeyError:
+        return RESPONSE_GENERATION_SYSTEM_PROMPT, RESPONSE_GENERATION_USER_PROMPT
+
+
+def get_response_generation_prompt(**kwargs) -> str:
+    """Backward compatibility - get combined prompt for response generation."""
+    try:
+        return RESPONSE_GENERATION_PROMPT.format(**kwargs)
+    except KeyError:
+        return RESPONSE_GENERATION_PROMPT
+
+
+def get_next_question_prompt(**kwargs) -> str:
+    """Backward compatibility - redirect to response generation prompt."""
+    return get_response_generation_prompt(**kwargs)