noesium 0.1.0__py3-none-any.whl

noesium/core/__init__.py

@@ -0,0 +1,4 @@
+from noesium.core.utils.logging import setup_logging
+
+# Enable colorful logging by default for cogents
+setup_logging(level="INFO", enable_colors=True)

noesium/core/agent/__init__.py

@@ -0,0 +1,14 @@
+from dotenv import load_dotenv
+
+from .base import BaseAgent, BaseConversationAgent, BaseGraphicAgent, BaseResearcher, ResearchOutput
+
+# Load environment variables
+load_dotenv()
+
+__all__ = [
+    "BaseAgent",
+    "BaseGraphicAgent",
+    "BaseResearcher",
+    "BaseConversationAgent",
+    "ResearchOutput",
+]

noesium/core/agent/base.py

@@ -0,0 +1,227 @@
+import os
+from abc import ABC, abstractmethod
+from datetime import datetime
+from typing import Any, Dict, List, Optional, Type
+
+from langchain_core.runnables import RunnableConfig
+from langgraph.graph import StateGraph
+from pydantic import BaseModel, Field
+
+from noesium.core.llm import get_llm_client
+from noesium.core.tracing import get_token_tracker
+from noesium.core.utils.logging import get_logger
+from noesium.core.utils.typing import override
+
+
+class BaseAgent(ABC):
+    """
+    Base class for all agents with common functionality.
+
+    Provides:
+    - LLM client management with instructor support
+    - Token usage tracking
+    - Logging capabilities
+    - Configuration management
+    - Error handling patterns
+    """
+
+    def __init__(self, llm_provider: str = "openrouter", model_name: Optional[str] = None):
+        """Initialize base agent with LLM client and logging."""
+        self.logger = get_logger(self.__class__.__name__)
+        self.llm_provider = llm_provider
+        self.model_name = model_name
+
+        # Initialize LLM client with instructor support
+        self.llm = get_llm_client(provider=llm_provider, chat_model=model_name)
+
+        self.logger.info(f"Initialized {self.__class__.__name__} with {llm_provider} provider")
+
+    @abstractmethod
+    def run(self, user_message: str, context: Dict[str, Any] = None, config: Optional[RunnableConfig] = None) -> Any:
+        """Run the agent with a user message and context."""
+
+    def get_token_usage_stats(self) -> Dict[str, Any]:
+        """Get comprehensive token usage statistics."""
+        return get_token_tracker().get_stats()
+
+    def print_token_usage_summary(self):
+        """Print a brief structured token usage summary."""
+        stats = self.get_token_usage_stats()
+        if stats["total_tokens"] > 0:
+            print(
+                f"FINAL_SUMMARY: {stats['total_tokens']} total | {stats['total_calls']} calls | P:{stats['total_prompt_tokens']} C:{stats['total_completion_tokens']}"
+            )
+        else:
+            print("FINAL_SUMMARY: 0 total | 0 calls | P:0 C:0")
+
+
+class BaseGraphicAgent(BaseAgent):
+    """
+    Base class for agents using LangGraph.
+
+    Provides:
+    - LangGraph state management
+    - Graph building abstractions
+    - Graph export functionality
+    - Common graph patterns
+    """
+
+    def __init__(self, llm_provider: str = "openrouter", model_name: Optional[str] = None):
+        """Initialize graphic agent with graph support."""
+        super().__init__(llm_provider, model_name)
+        self.graph: Optional[StateGraph] = None
+
+    @abstractmethod
+    def get_state_class(self) -> Type:
+        """Get the state class for this agent's graph."""
+
+    @abstractmethod
+    def _build_graph(self) -> StateGraph:
+        """Build the agent's graph. Must be implemented by subclasses."""
+
+    def export_graph(self, output_path: Optional[str] = None, format: str = "png"):
+        """
+        Export the agent graph visualization to file.
+
+        Args:
+            output_path: Optional path for output file. If None, uses default naming.
+            format: Export format ('png' or 'mermaid')
+        """
+        if not self.graph:
+            self.logger.warning("No graph to export. Build graph first.")
+            return
+
+        if not output_path:
+            class_name = self.__class__.__name__.lower()
+            output_path = os.path.join(os.path.dirname(__file__), f"{class_name}_graph.{format}")
+
+        try:
+            graph_structure = self.graph.get_graph()
+
+            if format == "png":
+                try:
+                    graph_structure.draw_png(output_path)
+                    self.logger.info(f"Graph exported successfully to {output_path}")
+                except ImportError:
+                    self.logger.warning("pygraphviz not installed, trying mermaid fallback")
+                    graph_structure.draw_mermaid_png(output_path)
+                    self.logger.info(f"Graph exported with mermaid to {output_path}")
+            elif format == "mermaid":
+                # For mermaid, we might want to save the mermaid code itself
+                mermaid_code = graph_structure.draw_mermaid()
+                with open(output_path.replace(".png", ".md"), "w") as f:
+                    f.write(f"```mermaid\n{mermaid_code}\n```")
+                self.logger.info(f"Mermaid graph exported to {output_path.replace('.png', '.md')}")
+            else:
+                self.logger.error(f"Unsupported export format: {format}")
+
+        except Exception as e:
+            self.logger.error(f"Failed to export graph: {e}")
+
+    def _create_error_response(self, error_message: str, **kwargs) -> Dict[str, Any]:
+        """Create a standardized error response."""
+        self.logger.error(f"Agent error: {error_message}")
+        return {"error": error_message, "success": False, "timestamp": self._now_iso(), **kwargs}
+
+    def _now_iso(self) -> str:
+        """Get current time in ISO format."""
+        from datetime import datetime, timezone
+
+        return datetime.now(timezone.utc).isoformat()
+
+
+class BaseConversationAgent(BaseGraphicAgent):
+    """
+    Abstract base class for conversation-style agents like AskuraAgent.
+
+    Provides:
+    - Session management patterns
+    - Message handling abstractions
+    - Conversation state management
+    - Response generation patterns
+    """
+
+    def __init__(self, llm_provider: str = "openrouter", model_name: Optional[str] = None):
+        """Initialize conversation agent."""
+        super().__init__(llm_provider, model_name)
+        self._session_states: Dict[str, Any] = {}
+
+    @abstractmethod
+    def start_conversation(self, user_id: str, initial_message: Optional[str] = None) -> Any:
+        """Start a new conversation with a user."""
+
+    @abstractmethod
+    def process_user_message(self, user_id: str, session_id: str, message: str) -> Any:
+        """Process a user message and return the agent's response."""
+
+    def get_session_state(self, session_id: str) -> Optional[Any]:
+        """Get the state for a specific session."""
+        return self._session_states.get(session_id)
+
+    def list_sessions(self) -> list[str]:
+        """List all active session IDs."""
+        return list(self._session_states.keys())
+
+    def clear_session(self, session_id: str) -> bool:
+        """Clear a specific session."""
+        if session_id in self._session_states:
+            del self._session_states[session_id]
+            self.logger.info(f"Cleared session {session_id}")
+            return True
+        return False
+
+    def clear_all_sessions(self):
+        """Clear all sessions."""
+        session_count = len(self._session_states)
+        self._session_states.clear()
+        self.logger.info(f"Cleared {session_count} sessions")
+
+    @override
+    def run(self, user_message: str, context: Dict[str, Any] = None, config: Optional[RunnableConfig] = None) -> str:
+        """Run the agent with a user message and context. Required by BaseAgent."""
+        # Create a temporary user ID for standalone run
+        response = self.start_conversation("standalone_user", user_message)
+        return response.message
+
+
+class ResearchOutput(BaseModel):
+    """Output from research process."""
+
+    content: str = Field(default="")
+    sources: List[Dict[str, Any]] = Field(default_factory=list)
+    summary: str = Field(default="")
+    timestamp: datetime = Field(default_factory=datetime.now)
+
+
+class BaseResearcher(BaseGraphicAgent):
+    """
+    Abstract base class for research-style agents like SeekraAgent.
+
+    Provides:
+    - Research workflow patterns
+    - Source management
+    - Query generation abstractions
+    - Result compilation patterns
+    """
+
+    def __init__(self, llm_provider: str = "openrouter", model_name: Optional[str] = None):
+        """Initialize researcher agent."""
+        super().__init__(llm_provider, model_name)
+
+    @abstractmethod
+    def research(
+        self,
+        user_message: str,
+        context: Dict[str, Any] = None,
+        config: Optional[RunnableConfig] = None,
+    ) -> ResearchOutput:
+        """Research a topic and return structured results."""
+
+    @override
+    def run(self, user_message: str, context: Dict[str, Any] = None, config: Optional[RunnableConfig] = None) -> str:
+        """
+        Default implementation of run() for researchers.
+        Calls research() and returns the content.
+        """
+        result = self.research(user_message, context, config)
+        return result.content if result else "Research failed to produce results."

noesium/core/consts.py

@@ -0,0 +1,6 @@
+# Gemini models
+GEMINI_PRO = "google/gemini-2.5-pro"
+GEMINI_FLASH = "google/gemini-2.5-flash"
+
+# Default embedding dimensions
+DEFAULT_EMBEDDING_DIMS = 768

noesium/core/goalith/conflict/conflict.py

@@ -0,0 +1,104 @@
+from abc import ABC, abstractmethod
+from datetime import datetime, timezone
+from enum import Enum
+from typing import Any, Dict, List, Optional
+from uuid import uuid4
+
+from pydantic import BaseModel, Field
+
+
+class ConflictType(str, Enum):
+    """Types of conflicts that can occur."""
+
+    CYCLE_DETECTED = "cycle_detected"
+    CONCURRENT_UPDATE = "concurrent_update"
+    STATUS_INCONSISTENCY = "status_inconsistency"
+    PRIORITY_CONFLICT = "priority_conflict"
+    DEPENDENCY_VIOLATION = "dependency_violation"
+    RESOURCE_CONFLICT = "resource_conflict"
+    SEMANTIC_INCONSISTENCY = "semantic_inconsistency"
+
+
+class Conflict(BaseModel):
+    """
+    Represents a conflict in the system.
+    """
+
+    # Core identification
+    id: str = Field(default_factory=lambda: str(uuid4()))
+    conflict_type: ConflictType = Field(..., description="Type of conflict")
+
+    # Conflict details
+    affected_nodes: List[str] = Field(..., description="IDs of affected nodes")
+    description: str = Field(default="", description="Human-readable description")
+    context: Dict[str, Any] = Field(default_factory=dict, description="Additional conflict context")
+    detected_at: datetime = Field(
+        default_factory=lambda: datetime.now(timezone.utc), description="When the conflict was detected"
+    )
+
+    # Resolution status
+    resolved: bool = Field(default=False, description="Whether the conflict has been resolved")
+    resolution_strategy: Optional[str] = Field(default=None, description="Strategy used to resolve the conflict")
+    resolution_action: Optional[Dict[str, Any]] = Field(
+        default=None, description="Resolution action returned by resolver"
+    )
+    resolved_at: Optional[datetime] = Field(default=None, description="When the conflict was resolved")
+
+    class Config:
+        """Pydantic configuration."""
+
+        use_enum_values = True
+
+    def __eq__(self, other: object) -> bool:
+        """
+        Compare two Conflicts for equality based on meaningful content.
+
+        Excludes timestamp fields as they are automatically generated.
+        """
+        if not isinstance(other, Conflict):
+            return False
+
+        return (
+            self.id == other.id
+            and self.conflict_type == other.conflict_type
+            and self.affected_nodes == other.affected_nodes
+            and self.description == other.description
+            and self.context == other.context
+            and self.resolved == other.resolved
+            and self.resolution_strategy == other.resolution_strategy
+            and self.resolution_action == other.resolution_action
+        )
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary for serialization."""
+        return {
+            "id": self.id,
+            "conflict_type": str(self.conflict_type),
+            "affected_nodes": self.affected_nodes,
+            "description": self.description,
+            "context": self.context,
+            "detected_at": self.detected_at.isoformat() if self.detected_at else None,
+            "resolved": self.resolved,
+            "resolution_strategy": self.resolution_strategy,
+            "resolved_at": self.resolved_at.isoformat() if self.resolved_at else None,
+        }
+
+
+class ConflictResolver(ABC):
+    """
+    Abstract interface for conflict resolvers.
+
+    Can be implemented by LLM-based reasoning, human input, or rule-based systems.
+    """
+
+    @abstractmethod
+    def resolve(self, conflict: Conflict) -> Optional[Dict[str, Any]]:
+        """
+        Resolve a conflict.
+
+        Args:
+            conflict: The conflict to resolve
+
+        Returns:
+            Resolution action description, or None if cannot resolve
+        """

noesium/core/goalith/conflict/detector.py

@@ -0,0 +1,53 @@
+from typing import Any, Dict, List
+
+from noesium.core.goalith.goalgraph.graph import GoalGraph
+
+from .conflict import Conflict
+
+
+class ConflictDetector:
+    """
+    Detects conflicts in the graph.
+
+    Watches for illegal states, cycles, and semantic inconsistencies.
+    """
+
+    def __init__(self, goal_graph: GoalGraph):
+        """
+        Initialize conflict detector.
+
+        Args:
+            goal_graph: The graph to monitor
+        """
+        self._goal_graph = goal_graph
+        self._detection_stats = {
+            "total_checked": 0,
+            "conflicts_found": 0,
+            "by_type": {},
+        }
+
+    @property
+    def goal_graph(self):
+        """Get the graph."""
+        return self._goal_graph
+
+    def detect_conflicts(self) -> List[Conflict]:
+        """
+        Detect conflicts in the graph.
+
+        Returns:
+            List of detected conflicts
+        """
+        self._detection_stats["total_checked"] += 1
+        conflicts = []
+        # TODO: Implement conflict detection
+        return conflicts
+
+    def get_detection_stats(self) -> Dict[str, Any]:
+        """
+        Get conflict detection statistics.
+
+        Returns:
+            Detection statistics
+        """
+        return self._detection_stats.copy()

noesium/core/goalith/decomposer/__init__.py

@@ -0,0 +1,6 @@
+from .base import GoalDecomposer
+from .callable_decomposer import CallableDecomposer
+from .llm_decomposer import LLMDecomposer
+from .simple_decomposer import SimpleListDecomposer
+
+__all__ = ["GoalDecomposer", "SimpleListDecomposer", "LLMDecomposer", "CallableDecomposer"]

noesium/core/goalith/decomposer/base.py

@@ -0,0 +1,46 @@
+"""
+Base classes and exceptions for the GoalithService.
+
+This module contains the foundational classes and exceptions used across
+the goalith_service module to avoid circular imports.
+"""
+
+from abc import ABC, abstractmethod
+from typing import Any, Dict, List, Optional
+
+from noesium.core.goalith.goalgraph.node import GoalNode
+
+
+class GoalDecomposer(ABC):
+    """
+    Abstract interface for goal decomposers.
+
+    Decomposers can be humans, AI agents (LLMs), symbolic planners,
+    or any callable entity that can break down goals into subgoals/tasks.
+    """
+
+    @abstractmethod
+    def decompose(self, goal_node: GoalNode, context: Optional[Dict[str, Any]] = None) -> List[GoalNode]:
+        """
+        Decompose a goal into subgoals or tasks.
+
+        Args:
+            goal_node: The goal node to decompose
+            context: Optional context for decomposition
+
+        Returns:
+            List of subgoal/task nodes
+
+        Raises:
+            DecompositionError: If decomposition fails
+        """
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """Get the name of this decomposer."""
+
+    @property
+    def description(self) -> str:
+        """Get the description of this decomposer."""
+        return f"Decomposer: {self.name}"

noesium/core/goalith/decomposer/callable_decomposer.py

@@ -0,0 +1,65 @@
+from typing import Any, Callable, Dict, List, Optional
+
+from noesium.core.goalith.errors import DecompositionError
+from noesium.core.goalith.goalgraph.node import GoalNode
+
+from .base import GoalDecomposer
+
+
+class CallableDecomposer(GoalDecomposer):
+    """
+    Wrapper for callable decomposition functions.
+
+    Allows any function that matches the decomposition signature
+    to be used as a decomposer.
+    """
+
+    def __init__(
+        self,
+        callable_func: Callable[[GoalNode, Optional[Dict[str, Any]]], List[GoalNode]],
+        name: Optional[str] = None,
+        description: Optional[str] = None,
+    ):
+        """
+        Initialize with a callable function.
+
+        Args:
+            callable_func: Function that performs decomposition
+            name: Name of this decomposer (auto-detected from function if None)
+            description: Optional description
+        """
+        self._callable = callable_func
+        self._name = name or getattr(callable_func, "__name__", "callable_decomposer")
+        self._description = description or f"Callable decomposer: {self._name}"
+
+    @property
+    def name(self) -> str:
+        """Get the name of this decomposer."""
+        return self._name
+
+    @property
+    def description(self) -> str:
+        """Get the description of this decomposer."""
+        return self._description
+
+    def decompose(self, goal_node: GoalNode, context: Optional[Dict[str, Any]] = None) -> List[GoalNode]:
+        """
+        Decompose using the callable function.
+
+        Args:
+            goal_node: The goal node to decompose
+            context: Optional context
+
+        Returns:
+            List of subgoal/task nodes
+
+        Raises:
+            DecompositionError: If callable raises an exception
+        """
+        try:
+            return self._callable(goal_node, context)
+        except ValueError:
+            # Let ValueError propagate as-is for test compatibility
+            raise
+        except Exception as e:
+            raise DecompositionError(f"Decomposition failed: {e}") from e