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

noesium/agents/askura_agent/reflection.py

@@ -0,0 +1,234 @@
+import random
+from typing import Any, List, Optional
+
+from noesium.core.llm import BaseLLMClient
+from noesium.core.utils.logging import get_logger
+
+from .models import (
+    AskuraConfig,
+    AskuraState,
+    ConversationContext,
+    ConversationStyle,
+    InformationSlot,
+    KnowledgeGapAnalysis,
+    NextActionPlan,
+)
+from .prompts import get_conversation_analysis_prompts
+from .utils import get_enum_value
+
+logger = get_logger(__name__)
+
+
+class Reflection:
+    def __init__(self, config: AskuraConfig, llm_client: Optional[BaseLLMClient] = None):
+        self.config = config
+        self.llm = llm_client
+
+    def missing_slots(self, state: AskuraState) -> List[InformationSlot]:
+        info = state.extracted_info
+        missing: List[InformationSlot] = []
+        for slot in self.config.information_slots:
+            if slot.required and not self._is_slot_complete(slot, info.get(slot.name)):
+                missing.append(slot)
+        # Highest priority first (larger number means higher priority)
+        missing.sort(key=lambda s: s.priority, reverse=True)
+        return missing
+
+    def _is_slot_complete(self, slot: InformationSlot, value: Any) -> bool:
+        if value in (None, "", [], {}):
+            return False
+        if slot.extraction_model and isinstance(value, dict):
+            try:
+                # Pydantic v2: check required fields on the model
+                required_fields = [
+                    name for name, field in slot.extraction_model.model_fields.items() if field.is_required
+                ]
+                for field_name in required_fields:
+                    if value.get(field_name) in (None, "", [], {}):
+                        return False
+            except Exception:
+                # If introspection fails, fall back to non-empty check
+                return True
+        return True
+
+    def evaluate_knowledge_gap(self, state: AskuraState, recent_messages: List[str] = None) -> KnowledgeGapAnalysis:
+        """Evaluate knowledge gaps using LLM analysis combining all upstream information."""
+        if not self.llm:
+            # Fallback when no LLM available
+            missing_slots = [s.name for s in self.missing_slots(state)]
+            return KnowledgeGapAnalysis(
+                knowledge_gap_summary=(
+                    f"Missing slots: {', '.join(missing_slots)}"
+                    if missing_slots
+                    else "All required information collected"
+                ),
+                critical_missing_info=missing_slots,
+                suggested_next_topics=missing_slots[:5] if missing_slots else [],
+                readiness_to_proceed=0.0 if missing_slots else 1.0,
+                reasoning="Fallback analysis due to missing LLM client",
+            )
+
+        try:
+            # Format extracted information for prompt
+            extracted_info_text = ""
+            if state.extracted_info:
+                extracted_info_text = "\n".join([f"- {slot}: {info}" for slot, info in state.extracted_info.items()])
+            else:
+                extracted_info_text = "No information extracted yet"
+
+            # Format missing information for prompt
+            missing_info_text = ""
+            if state.missing_info:
+                missing_info_text = "\n".join([f"- {slot}: {desc}" for slot, desc in state.missing_info.items()])
+            else:
+                missing_info_text = "All required information collected"
+
+            # Format memory information
+            memory_text = ""
+            if state.memory:
+                memory_text = str(state.memory)
+            else:
+                memory_text = "No memory available"
+
+            # Format recent messages
+            recent_messages_text = ""
+            if recent_messages:
+                recent_messages_text = "\n".join([f"User: {msg}" for msg in recent_messages])
+            else:
+                recent_messages_text = "No recent messages"
+
+            # Get structured prompts for knowledge gap analysis
+            conversation_purpose = state.conversation_context.conversation_purpose
+            system_prompt, user_prompt = get_conversation_analysis_prompts(
+                "knowledge_gap_analysis",
+                conversation_purpose=conversation_purpose,
+                conversation_context=state.conversation_context.to_dict(),
+                extracted_info=extracted_info_text,
+                missing_info=missing_info_text,
+                memory=memory_text,
+                recent_messages=recent_messages_text,
+            )
+
+            # Use structured completion for reliable analysis
+            analysis: KnowledgeGapAnalysis = self.llm.structured_completion(
+                messages=[{"role": "system", "content": system_prompt}, {"role": "user", "content": user_prompt}],
+                response_model=KnowledgeGapAnalysis,
+                temperature=0.3,
+                max_tokens=800,
+            )
+
+            return analysis
+
+        except Exception as e:
+            logger.warning(f"LLM-based knowledge gap analysis failed: {e}, falling back to basic analysis")
+            # Fallback to basic analysis
+            missing_slots = [s.name for s in self.missing_slots(state)]
+            return KnowledgeGapAnalysis(
+                knowledge_gap_summary=(
+                    f"Error in analysis. Missing slots: {', '.join(missing_slots)}"
+                    if missing_slots
+                    else "Analysis error but all slots filled"
+                ),
+                critical_missing_info=missing_slots,
+                suggested_next_topics=missing_slots[:5] if missing_slots else [],
+                readiness_to_proceed=0.0 if missing_slots else 0.5,
+                reasoning=f"Fallback analysis due to error: {str(e)}",
+            )
+
+    def next_action(
+        self,
+        state: AskuraState,
+        context: ConversationContext,
+        recent_messages: List[str],
+        ready_to_summarize: bool = False,
+    ) -> NextActionPlan:
+        """
+        Unified method to determine next action with intent classification.
+
+        This method combines intent classification and next action determination
+        into a single LLM call for better consistency and efficiency.
+        """
+        try:
+            # Prepare available actions
+            allowed = list(state.missing_info.keys())
+            if ready_to_summarize:
+                allowed.append("summarize")
+            allowed.extend(["redirect_conversation", "reply_smalltalk"])
+
+            # Get structured prompt for unified next action determination - preserve readability
+            recent_messages_text = "\n".join([f"User: {msg}" for msg in recent_messages]) if recent_messages else ""
+
+            system_prompt, user_prompt = get_conversation_analysis_prompts(
+                "determine_next_action",
+                conversation_context=context.to_dict(),
+                available_actions=allowed,
+                ready_to_summarize=ready_to_summarize,
+                recent_messages=recent_messages_text,
+            )
+
+            # Use structured completion with retry for reliable unified analysis
+            result: NextActionPlan = self.llm.structured_completion(
+                messages=[{"role": "system", "content": system_prompt}, {"role": "user", "content": user_prompt}],
+                response_model=NextActionPlan,
+                temperature=0.3,
+                max_tokens=300,
+            )
+
+            # Validate the response
+            if result.next_action not in allowed:
+                raise ValueError(f"LLM returned invalid action: {result.next_action}")
+            return result
+
+        except Exception as e:
+            logger.warning(f"Unified next action determination failed: {e}, falling back to heuristics")
+            # Fallback to heuristic approach
+            next_action = self._get_heuristic_next_action(context, list(state.missing_info.keys()))
+            return NextActionPlan(
+                intent_type="task",
+                next_action=next_action or "summarize",
+                reasoning=f"Heuristic fallback - error: {str(e)}",
+                confidence=0.5,
+                is_smalltalk=False,
+            )
+
+    def _get_heuristic_next_action(self, context: ConversationContext, missing_info: List[str]) -> Optional[str]:
+        """Get next action using heuristic approach as fallback."""
+
+        if not missing_info:
+            return "summarize"
+
+        # If conversation is off-track, prioritize redirecting
+        if context.conversation_on_track_confidence < 0.4:
+            return "redirect_conversation"
+
+        # If conversation is highly on-track, focus on gathering missing info
+        if context.conversation_on_track_confidence > 0.7:
+            # Prioritize based on conversation context
+            style_value = get_enum_value(context.conversation_style)
+            if style_value == ConversationStyle.DIRECT.value:
+                # Pick randomly from missing info instead of always first
+                return random.choice(missing_info) if missing_info else None
+            elif style_value == ConversationStyle.EXPLORATORY.value:
+                # For exploratory users, suggest topics they might be interested in
+                return random.choice(missing_info) if missing_info else None
+            elif style_value == ConversationStyle.CASUAL.value:
+                # For casual users, ask easy questions first
+                easy_questions = self._get_easy_questions()
+                for question in easy_questions:
+                    if question in missing_info:
+                        return question
+                # If no easy questions found, pick randomly from missing info
+                return random.choice(missing_info) if missing_info else None
+
+        # For moderate alignment, balance between staying on track and gathering info
+        # Pick randomly from missing info
+        return random.choice(missing_info) if missing_info else None
+
+    def _get_easy_questions(self) -> List[str]:
+        """Get list of easy questions that boost confidence."""
+        easy_questions = []
+        for slot in self.config.information_slots:
+            # Consider questions about preferences and interests as "easy"
+            if any(word in slot.name.lower() for word in ["interest", "preference", "like", "favorite"]):
+                easy_questions.append(f"ask_{slot.name}")
+        return easy_questions

noesium/agents/askura_agent/summarizer.py

@@ -0,0 +1,30 @@
+from typing import List, Optional
+
+from noesium.core.llm import BaseLLMClient
+from noesium.core.utils.logging import get_logger
+
+from .models import AskuraConfig, AskuraState
+from .reflection import Reflection
+
+logger = get_logger(__name__)
+
+
+class Summarizer:
+    def __init__(
+        self, config: AskuraConfig, llm_client: Optional[BaseLLMClient] = None, reflection: Optional[Reflection] = None
+    ):
+        self.config = config
+        self.llm = llm_client
+        self.reflection = reflection
+
+    def is_ready_to_summarize(self, state: AskuraState) -> bool:
+        # Summarize only when all required slots are complete
+        return len(self.reflection.missing_slots(state)) == 0 and state.turns > 1
+
+    def summarize(self, state: AskuraState) -> str:
+        information_slots = state.extracted_info
+        summary_parts: List[str] = []
+        for slot in self.config.information_slots:
+            if information_slots.get(slot.name):
+                summary_parts.append(f"{slot.name}: {information_slots[slot.name]}")
+        return "Summary: " + " | ".join(summary_parts) if summary_parts else "Conversation completed."

noesium/agents/askura_agent/utils.py

@@ -0,0 +1,6 @@
+# Handle both enum objects and string values safely
+def get_enum_value(field_value):
+    """Safely extract value from enum or string."""
+    if hasattr(field_value, "value"):
+        return field_value.value
+    return str(field_value)

noesium/agents/deep_research/__init__.py

@@ -0,0 +1,13 @@
+"""
+DeepResearchAgent Module
+
+This module provides advanced research capabilities using LangGraph and LLM integration.
+"""
+
+from .agent import DeepResearchAgent
+from .state import ResearchState
+
+__all__ = [
+    "DeepResearchAgent",
+    "ResearchState",
+]

noesium/agents/deep_research/agent.py

@@ -0,0 +1,398 @@
+"""
+DeepResearchAgent implementation using LangGraph and LLM integration.
+Enhanced base class designed for extensibility.
+"""
+
+from datetime import datetime
+from typing import Any, Dict, List, Optional, Type
+
+try:
+    from langchain_core.messages import AIMessage, AnyMessage, HumanMessage
+    from langchain_core.runnables import RunnableConfig
+    from langgraph.graph import END, START, StateGraph
+    from langgraph.types import Send
+
+    LANGCHAIN_AVAILABLE = True
+except ImportError:
+    AIMessage = None
+    AnyMessage = None
+    HumanMessage = None
+    RunnableConfig = None
+    StateGraph = None
+    END = None
+    START = None
+    Send = None
+    LANGCHAIN_AVAILABLE = False
+
+from noesium.core.agent import BaseResearcher, ResearchOutput
+from noesium.core.llm import BaseLLMClient
+from noesium.core.utils.logging import get_logger
+from noesium.core.utils.typing import override
+
+from .prompts import answer_instructions, query_writer_instructions, reflection_instructions
+from .schemas import Reflection, SearchQueryList
+from .state import QueryState, ReflectionState, ResearchState, WebSearchState
+
+# Configure logging
+logger = get_logger(__name__)
+
+
+def get_current_date() -> str:
+    """Get current date in a readable format."""
+    return datetime.now().strftime("%B %d, %Y")
+
+
+class DeepResearchAgent(BaseResearcher):
+    """
+    Advanced research agent using LangGraph and LLM integration.
+    """
+
+    def __init__(
+        self,
+        llm_provider: str = "openai",
+        query_generation_llm: BaseLLMClient | None = None,
+        reflection_llm: BaseLLMClient | None = None,
+        number_of_initial_queries: int = 3,
+        max_research_loops: int = 3,
+        query_generation_temperature: float = 0.7,
+        query_generation_max_tokens: int = 1000,
+        web_search_temperature: float = 0.2,
+        web_search_max_tokens: int = 10000,
+        web_search_citation_enabled: bool = True,
+        reflection_temperature: float = 0.5,
+        reflection_max_tokens: int = 1000,
+        answer_temperature: float = 0.3,
+        answer_max_tokens: int = 100000,
+        search_engines: List[str] = ["tavily", "duckduckgo"],
+        max_results_per_engine: int = 5,
+        search_timeout: int = 30,
+    ):
+        """
+        Initialize the DeepResearchAgent.
+        """
+        # Initialize base class
+        super().__init__(llm_provider=llm_provider)
+
+        # Override the LLM client with instructor support if needed
+        # Base class already initializes self.llm, so we can reuse it
+        self.llm_client = self.llm
+        self.query_generation_llm = query_generation_llm if query_generation_llm else self.llm
+        self.reflection_llm = reflection_llm if reflection_llm else self.llm
+        self.number_of_initial_queries = number_of_initial_queries
+        self.max_research_loops = max_research_loops
+        self.query_generation_temperature = query_generation_temperature
+        self.query_generation_max_tokens = query_generation_max_tokens
+        self.web_search_temperature = web_search_temperature
+        self.web_search_max_tokens = web_search_max_tokens
+        self.web_search_citation_enabled = web_search_citation_enabled
+        self.reflection_temperature = reflection_temperature
+        self.reflection_max_tokens = reflection_max_tokens
+        self.answer_temperature = answer_temperature
+        self.answer_max_tokens = answer_max_tokens
+        self.search_engines = search_engines
+        self.max_results_per_engine = max_results_per_engine
+        self.search_timeout = search_timeout
+
+        # Load prompts (can be overridden by subclasses)
+        self.prompts = self.get_prompts()
+
+        # Create the research graph
+        self.graph = self._build_graph()
+
+    @override
+    def get_state_class(self) -> Type:
+        """
+        Get the state class for this researcher.
+        Override this method in subclasses for specialized state.
+
+        Returns:
+            The state class to use for the research workflow
+        """
+        return ResearchState
+
+    @override
+    def _build_graph(self) -> StateGraph:
+        """Create the LangGraph research workflow."""
+        state_class = self.get_state_class()
+        workflow = StateGraph(state_class)
+
+        # Add nodes
+        workflow.add_node("generate_query", self._generate_query_node)
+        workflow.add_node("web_research", self._research_node)
+        workflow.add_node("reflection", self._reflection_node)
+        workflow.add_node("finalize_answer", self._finalize_answer_node)
+
+        # Set entry point
+        workflow.add_edge(START, "generate_query")
+
+        # Add conditional edges
+        workflow.add_conditional_edges("generate_query", self._continue_to_web_research, ["web_research"])
+        workflow.add_edge("web_research", "reflection")
+        workflow.add_conditional_edges("reflection", self._evaluate_research, ["web_research", "finalize_answer"])
+        workflow.add_edge("finalize_answer", END)
+
+        return workflow.compile()
+
+    @override
+    async def research(
+        self,
+        user_message: str,
+        context: Dict[str, Any] = None,
+        config: Optional[RunnableConfig] = None,
+    ) -> ResearchOutput:
+        """
+        Research a topic and return structured results.
+
+        Args:
+            user_message: User's research request
+            context: Additional context for research
+            config: Optional RunnableConfig for runtime configuration
+
+        Returns:
+            ResearchOutput with content and sources
+        """
+        try:
+            # Initialize state (can be customized by subclasses)
+            initial_state = {
+                "messages": [HumanMessage(content=user_message)],
+                "context": context,
+                "search_query": [],
+                "web_research_result": [],
+                "sources_gathered": [],
+                "initial_search_query_count": self.number_of_initial_queries,
+                "max_research_loops": self.max_research_loops,
+                "research_loop_count": 0,
+            }
+            # Run the research graph with optional runtime configuration
+            if config:
+                result = await self.graph.ainvoke(initial_state, config=config)
+            else:
+                result = await self.graph.ainvoke(initial_state)
+
+            # Extract the final AI message
+            final_message = None
+            for message in reversed(result["messages"]):
+                if isinstance(message, AIMessage):
+                    final_message = message.content
+                    break
+
+            return ResearchOutput(
+                content=final_message or "Research completed",
+                sources=result.get("sources_gathered", []),
+                summary=f"Research completed for topic",
+                timestamp=datetime.now(),
+            )
+
+        except Exception as e:
+            logger.error(f"Error in research: {e}")
+            raise RuntimeError(f"Research failed: {str(e)}")
+
+    def get_prompts(self) -> Dict[str, str]:
+        """
+        Get prompts for the researcher.
+        Override this method in subclasses for specialized prompts.
+
+        Returns:
+            Dictionary containing all prompts for the research workflow
+        """
+        return {
+            "query_writer": query_writer_instructions,
+            "reflection": reflection_instructions,
+            "answer": answer_instructions,
+        }
+
+    def _preprocess_research_topic(self, messages: List[AnyMessage]) -> str:
+        """
+        Get the research topic from the messages.
+
+        Args:
+            messages: List of messages from the conversation
+
+        Returns:
+            Formatted research topic string
+        """
+        # Check if request has a history and combine the messages into a single string
+        if len(messages) == 1:
+            research_topic = messages[-1].content
+        else:
+            research_topic = ""
+            for message in messages:
+                if isinstance(message, HumanMessage):
+                    research_topic += f"User: {message.content}\n"
+                elif isinstance(message, AIMessage):
+                    research_topic += f"Assistant: {message.content}\n"
+        return research_topic
+
+    def _generate_query_node(self, state: ResearchState, config: RunnableConfig) -> QueryState:
+        """Generate search queries based on user request using instructor structured output."""
+        # Get research topic from messages (can be customized by subclasses)
+        research_topic = self._preprocess_research_topic(state["messages"])
+
+        # Format the prompt
+        current_date = get_current_date()
+        formatted_prompt = self.prompts["query_writer"].format(
+            current_date=current_date,
+            research_topic=research_topic,
+            number_queries=state.get("initial_search_query_count", self.number_of_initial_queries),
+        )
+
+        try:
+            # Generate queries using instructor with structured output
+            result: SearchQueryList = self.llm_client.structured_completion(
+                messages=[{"role": "user", "content": formatted_prompt}],
+                response_model=SearchQueryList,
+                temperature=self.query_generation_temperature,
+                max_tokens=self.query_generation_max_tokens,
+            )
+
+            logger.info(f"Generated {len(result.query)} queries: {result.query}, rationale: {result.rationale}")
+
+            # Create query list with rationale
+            query_list = [{"query": q, "rationale": result.rationale} for q in result.query]
+            return {"query_list": query_list}
+
+        except Exception as e:
+            raise RuntimeError(f"Error in structured query generation: {e}")
+
+    def _continue_to_web_research(self, state: QueryState) -> List[Send]:
+        """Send queries to web research nodes."""
+        return [
+            Send(
+                "web_research",
+                WebSearchState(search_query=item["query"], id=str(idx)),
+            )
+            for idx, item in enumerate(state["query_list"])
+        ]
+
+    async def _research_node(self, state: WebSearchState, config: RunnableConfig) -> ResearchState:
+        """Perform web research using Tavily Search API."""
+        search_query = state["search_query"]
+
+        try:
+            from wizsearch import WizSearch, WizSearchConfig
+
+            omnisearch = WizSearch(
+                config=WizSearchConfig(
+                    enabled_engines=self.search_engines,
+                    max_results_per_engine=self.max_results_per_engine,
+                    timeout=self.search_timeout,
+                )
+            )
+
+            result = await omnisearch.search(query=search_query)
+
+            # Convert SearchResult objects to dictionaries for compatibility
+            sources_gathered = []
+            for source in result.sources:
+                sources_gathered.append(source.model_dump())
+
+            # Generate research summary based on actual search results
+            if sources_gathered:
+                # Create a summary from the actual content found
+                content_summary = "\n\n".join(
+                    [f"Source: {s['title']}\n{s['content']}" for s in sources_gathered[:5]]  # Use top 5 results
+                )
+
+                summary_prompt = f"""
+                Based on the following search results for "{search_query}", provide a concise and accurate research summary:
+
+                {content_summary}
+
+                Please provide a well-structured summary that:
+                1. Addresses the search query directly
+                2. Synthesizes information from multiple sources
+                3. Highlights key findings and insights
+                4. Maintains factual accuracy based on the provided content
+                """
+
+                search_summary = self.llm_client.completion(
+                    messages=[{"role": "user", "content": summary_prompt}],
+                    temperature=self.web_search_temperature,
+                    max_tokens=self.web_search_max_tokens,
+                )
+            else:
+                search_summary = f"No relevant sources found for: {search_query}"
+
+            return ResearchState(
+                sources_gathered=sources_gathered,
+                search_query=[search_query],
+                search_summaries=[search_summary],
+            )
+
+        except Exception as e:
+            logger.error(f"Error in Tavily web search: {e}")
+            raise RuntimeError(f"Tavily web search failed: {str(e)}")
+
+    def _reflection_node(self, state: ResearchState, config: RunnableConfig) -> ReflectionState:
+        """Reflect on research results and identify gaps using instructor structured output."""
+        # Increment research loop count
+        research_loop_count = state.get("research_loop_count", 0) + 1
+
+        # Format the prompt
+        current_date = get_current_date()
+        research_topic = self._preprocess_research_topic(state["messages"])
+        summaries = "\n\n---\n\n".join(state.get("search_summaries", []))
+
+        formatted_prompt = self.prompts["reflection"].format(
+            current_date=current_date,
+            research_topic=research_topic,
+            summaries=summaries,
+        )
+
+        try:
+            # Use instructor for reflection and evaluation with structured output
+            result: Reflection = self.llm_client.structured_completion(
+                messages=[{"role": "user", "content": formatted_prompt}],
+                response_model=Reflection,
+                temperature=self.reflection_temperature,
+                max_tokens=self.reflection_max_tokens,
+            )
+
+            return ReflectionState(
+                is_sufficient=result.is_sufficient,
+                knowledge_gap=result.knowledge_gap,
+                follow_up_queries=result.follow_up_queries,
+                research_loop_count=research_loop_count,
+                number_of_ran_queries=len(state.get("search_query", [])),
+            )
+
+        except Exception as e:
+            raise RuntimeError(f"Error in structured reflection: {e}")
+
+    def _evaluate_research(self, state: ReflectionState, config: RunnableConfig):
+        """Evaluate research and decide next step."""
+
+        if state["is_sufficient"] or state["research_loop_count"] >= self.max_research_loops:
+            return "finalize_answer"
+        else:
+            return [
+                Send(
+                    "web_research",
+                    WebSearchState(search_query=follow_up_query, id=str(state["number_of_ran_queries"] + int(idx))),
+                )
+                for idx, follow_up_query in enumerate(state["follow_up_queries"])
+            ]
+
+    def _finalize_answer_node(self, state: ResearchState, config: RunnableConfig):
+        """Finalize the research answer with advanced formatting and citations."""
+        current_date = get_current_date()
+        research_topic = self._preprocess_research_topic(state["messages"])
+        summaries = "\n---\n\n".join(state.get("search_summaries", []))
+
+        formatted_prompt = self.prompts["answer"].format(
+            current_date=current_date,
+            research_topic=research_topic,
+            summaries=summaries,
+        )
+
+        # Generate final answer using LLM
+        final_answer = self.llm_client.completion(
+            messages=[{"role": "user", "content": formatted_prompt}],
+            temperature=self.answer_temperature,
+            max_tokens=self.answer_max_tokens,
+        )
+
+        return {
+            "messages": [AIMessage(content=final_answer)],
+            "sources_gathered": state.get("sources_gathered", []),
+        }