noesium 0.1.0__py3-none-any.whl

noesium/core/goalith/replanner/base.py

@@ -0,0 +1,31 @@
+from abc import ABC, abstractmethod
+
+from noesium.core.goalith.decomposer.base import GoalDecomposer
+from noesium.core.goalith.goalgraph.graph import GoalGraph
+from noesium.core.goalith.goalgraph.node import GoalNode
+
+
+class BaseReplanner(ABC):
+    """
+    Base class for replanners.
+    """
+
+    def __init__(self, graph: GoalGraph, decomposer: GoalDecomposer):
+        self._goal_graph = graph
+        self._decomposer = decomposer
+
+    @property
+    def goal_graph(self):
+        """Get the graph."""
+        return self._goal_graph
+
+    @property
+    def decomposer(self):
+        """Get the decomposer."""
+        return self._decomposer
+
+    @abstractmethod
+    def replan(self, node: GoalNode, **kwargs) -> bool:
+        """
+        Replan a node in the graph.
+        """

noesium/core/goalith/replanner/replanner.py

@@ -0,0 +1,36 @@
+from noesium.core.goalith.decomposer.base import GoalDecomposer
+from noesium.core.goalith.goalgraph.graph import GoalGraph
+from noesium.core.goalith.goalgraph.node import GoalNode
+
+from .base import BaseReplanner
+
+
+class Replanner(BaseReplanner):
+    """
+    Handles replanning operations when triggers fire.
+
+    Hooks into decomposition and scheduling modules to adjust plans.
+    """
+
+    def __init__(self, graph: GoalGraph, decomposer: GoalDecomposer, **kwargs):
+        """
+        Initialize replanner.
+
+        Args:
+            graph_store: The graph store
+            decomposer: The decomposer to use
+        """
+        super().__init__(graph, decomposer, **kwargs)
+
+    def replan(self, node: GoalNode, **kwargs) -> bool:
+        """
+        Replan a node in the graph store.
+
+        Args:
+            node: The node to replan
+            **kwargs: Additional arguments
+
+        Returns:
+            True if replanning was successful, False otherwise
+        """
+        raise NotImplementedError("Replanner is an abstract class and cannot be instantiated directly.")

noesium/core/goalith/service.py

@@ -0,0 +1,26 @@
+from typing import Any, Dict, List, Optional
+
+
+class GoalithService:
+    def __init__(self):
+        pass
+
+    def create_goal(
+        self,
+        description: str,
+        priority: float = 1.0,
+        context: Optional[Dict[str, Any]] = None,
+        tags: Optional[List[str]] = None,
+    ) -> str:
+        """
+        Create a new goal in the system.
+
+        Args:
+            description: Description of the goal
+            priority: Priority level
+            context: Additional context data
+            tags: Tags for categorization
+
+        Returns:
+            ID of the created goal
+        """

noesium/core/llm/__init__.py

@@ -0,0 +1,154 @@
+import os
+from typing import Optional
+
+from .base import BaseLLMClient
+
+# Deprecated imports
+from .litellm import LLMClient as LitellmClient
+from .litellm import LLMClient as LitellmLLMClient
+from .openai import LLMClient as OpenAIClient
+from .openai import LLMClient as OpenAILLMClient
+from .openrouter import LLMClient as OpenRouterClient
+from .openrouter import LLMClient as OpenRouterLLMClient
+
+# Optional import - llamacpp might not be available
+try:
+    from .llamacpp import LLMClient as LlamaCppClient
+    from .llamacpp import LLMClient as LlamaCppLLMClient
+
+    LLAMACPP_AVAILABLE = True
+except ImportError:
+    LlamaCppLLMClient = None
+    LLAMACPP_AVAILABLE = False
+
+# Optional import - ollama might not be available
+try:
+    from .ollama import LLMClient as OllamaClient
+    from .ollama import LLMClient as OllamaLLMClient
+
+    OLLAMA_AVAILABLE = True
+except ImportError:
+    OllamaLLMClient = None
+    OLLAMA_AVAILABLE = False
+
+
+__all__ = [
+    "get_llm_client",
+    "BaseLLMClient",
+    # -- Deprecated imports --
+    "LitellmLLMClient",
+    "LlamaCppLLMClient",
+    "OpenRouterLLMClient",
+    "OllamaLLMClient",
+    "OpenAILLMClient",
+    # -- New imports --
+    "LitellmClient",
+    "LlamaCppClient",
+    "OllamaClient",
+    "OpenAIClient",
+    "OpenRouterClient",
+]
+
+#############################
+# Common LLM helper functions
+#############################
+
+
+def get_llm_client(
+    provider: str = os.getenv("COGENTS_LLM_PROVIDER", "openai"),
+    base_url: Optional[str] = None,
+    api_key: Optional[str] = None,
+    structured_output: bool = True,
+    instructor: Optional[bool] = None,
+    chat_model: Optional[str] = None,
+    vision_model: Optional[str] = None,
+    embed_model: Optional[str] = None,
+    **kwargs,
+):
+    """
+    Get an LLM client instance based on the specified provider.
+
+    Args:
+        provider: LLM provider to use ("openrouter", "openai", "litellm" always available; "ollama", "llamacpp" require optional dependencies)
+        base_url: Base URL for API (used by openai and ollama providers)
+        api_key: API key for authentication (used by openai and openrouter providers)
+        structured_output: Whether to enable structured output (default: True)
+        instructor: Whether to enable instructor for structured output (deprecated, use structured_output instead)
+        chat_model: Model to use for chat completions
+        vision_model: Model to use for vision tasks
+        embed_model: Model to use for embeddings
+        **kwargs: Additional provider-specific arguments:
+            - llamacpp: model_path, n_ctx, n_gpu_layers, etc.
+            - others: depends on provider
+            Note: 'instructor' in kwargs will be removed to avoid conflicts
+
+    Returns:
+        LLMClient instance for the specified provider
+
+    Raises:
+        ValueError: If provider is not supported or dependencies are missing
+    """
+    # Handle backward compatibility: enable instructor if either parameter is True
+    # If instructor is explicitly provided (True/False), use it OR structured_output
+    # If instructor is None, use structured_output
+    enable_instructor = (instructor if instructor is not None else False) or structured_output
+
+    # Remove 'instructor' from kwargs to avoid duplicate argument errors
+    kwargs.pop("instructor", None)
+
+    if provider == "openrouter":
+        return OpenRouterLLMClient(
+            base_url=base_url,
+            api_key=api_key,
+            instructor=enable_instructor,
+            chat_model=chat_model,
+            vision_model=vision_model,
+            embed_model=embed_model,
+            **kwargs,
+        )
+    elif provider == "openai":
+        return OpenAILLMClient(
+            base_url=base_url,
+            api_key=api_key,
+            instructor=enable_instructor,
+            chat_model=chat_model,
+            vision_model=vision_model,
+            embed_model=embed_model,
+            **kwargs,
+        )
+    elif provider == "ollama":
+        if not OLLAMA_AVAILABLE:
+            raise ValueError("ollama provider is not available. Please install the required dependencies.")
+        return OllamaLLMClient(
+            base_url=base_url,
+            api_key=api_key,
+            instructor=enable_instructor,
+            chat_model=chat_model,
+            vision_model=vision_model,
+            embed_model=embed_model,
+            **kwargs,
+        )
+    elif provider == "llamacpp":
+        if not LLAMACPP_AVAILABLE:
+            raise ValueError("llamacpp provider is not available. Please install the required dependencies.")
+        return LlamaCppLLMClient(
+            instructor=enable_instructor,
+            chat_model=chat_model,
+            vision_model=vision_model,
+            embed_model=embed_model,
+            **kwargs,
+        )
+    elif provider == "litellm":
+        return LitellmLLMClient(
+            base_url=base_url,
+            api_key=api_key,
+            instructor=enable_instructor,
+            chat_model=chat_model,
+            vision_model=vision_model,
+            embed_model=embed_model,
+            **kwargs,
+        )
+    else:
+        raise ValueError(
+            f"Unsupported provider: {provider}. Supported providers: openrouter, openai, ollama, llamacpp, litellm"
+        )

noesium/core/llm/base.py

@@ -0,0 +1,152 @@
+import os
+from abc import ABC, abstractmethod
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple, Type, TypeVar, Union
+
+from noesium.core.consts import DEFAULT_EMBEDDING_DIMS
+
+T = TypeVar("T")
+
+
+class BaseLLMClient(ABC):
+    """Client for interacting with LLMs via OpenRouter using OpenAI SDK."""
+
+    def __init__(self, **kwargs):
+        """
+        Initialize the LLM client.
+
+        Args:
+            **kwargs: Additional arguments to pass to the LLM client
+        """
+        self.debug = os.getenv("COGENTS_DEBUG", "false").lower() == "true"
+
+    @abstractmethod
+    def completion(
+        self,
+        messages: List[Dict[str, str]],
+        temperature: float = 0.7,
+        max_tokens: Optional[int] = None,
+        stream: bool = False,
+        **kwargs,
+    ) -> Union[str, Dict[str, Any]]:
+        """
+        Generate chat completion using the configured model.
+
+        Args:
+            messages: List of message dictionaries with 'role' and 'content' keys
+            temperature: Sampling temperature (0.0 to 2.0)
+            max_tokens: Maximum tokens to generate
+            stream: Whether to stream the response
+            **kwargs: Additional arguments to pass to OpenAI API
+
+        Returns:
+            Generated text response or streaming response
+        """
+
+    @abstractmethod
+    def structured_completion(
+        self,
+        messages: List[Dict[str, str]],
+        response_model: Type[T],
+        temperature: float = 0.7,
+        max_tokens: Optional[int] = None,
+        attempts: int = 2,
+        backoff: float = 0.5,
+        **kwargs,
+    ) -> T:
+        """
+        Generate structured completion using instructor.
+
+        Args:
+            messages: List of message dictionaries with 'role' and 'content' keys
+            response_model: Pydantic model class for structured output
+            temperature: Sampling temperature (0.0 to 2.0)
+            max_tokens: Maximum tokens to generate
+            attempts: Number of attempts to make
+            backoff: Backoff factor for exponential backoff
+            **kwargs: Additional arguments to pass to instructor
+
+        Returns:
+            Structured response as the specified model type
+        """
+
+    @abstractmethod
+    def understand_image(
+        self,
+        image_path: Union[str, Path],
+        prompt: str,
+        temperature: float = 0.7,
+        max_tokens: Optional[int] = None,
+        **kwargs,
+    ) -> str:
+        """
+        Analyze an image using the configured vision model.
+
+        Args:
+            image_path: Path to the image file
+            prompt: Text prompt describing what to analyze in the image
+            temperature: Sampling temperature
+            max_tokens: Maximum tokens to generate
+            **kwargs: Additional arguments
+
+        Returns:
+            Analysis of the image
+        """
+
+    @abstractmethod
+    def understand_image_from_url(
+        self,
+        image_url: str,
+        prompt: str,
+        temperature: float = 0.7,
+        max_tokens: Optional[int] = None,
+        **kwargs,
+    ) -> str:
+        """
+        Analyze an image from URL using the configured vision model.
+
+        Args:
+            image_url: URL of the image
+            prompt: Text prompt describing what to analyze in the image
+            temperature: Sampling temperature
+            max_tokens: Maximum tokens to generate
+            **kwargs: Additional arguments
+
+        Returns:
+            Analysis of the image
+        """
+
+    @abstractmethod
+    def embed(self, text: str) -> List[float]:
+        """Generate embeddings for input text"""
+
+    @abstractmethod
+    def embed_batch(self, chunks: List[str]) -> List[List[float]]:
+        """Generate embeddings for input text"""
+
+    @abstractmethod
+    def rerank(
+        self,
+        query: str,
+        chunks: List[str],
+    ) -> List[Tuple[float, int, str]]:
+        """
+        Rerank chunks based on their relevance to the query.
+
+        Args:
+            query: The query to rank against
+            chunks: List of text chunks to rerank
+
+        Returns:
+            List of tuples (similarity_score, original_index, chunk_text)
+            sorted by similarity score in descending order
+        """
+
+    def get_embedding_dimensions(self) -> int:
+        """
+        Get the expected dimensions for embeddings from this provider.
+
+        Returns:
+            int: Expected embedding dimensions
+        """
+        return int(os.getenv("COGENTS_EMBEDDING_DIMS", str(DEFAULT_EMBEDDING_DIMS)))