durag 2.0.4__py3-none-any.whl

durag/__init__.py

@@ -0,0 +1,5 @@
+import importlib.metadata
+
+__version__ = importlib.metadata.version("durag")
+
+from durag.memory.main import AsyncMemory, Memory  # noqa

durag/configs/base.py

@@ -0,0 +1,81 @@
+import os
+from typing import Any, Dict, Optional
+
+from pydantic import BaseModel, Field
+
+from durag.configs.rerankers.config import RerankerConfig
+from durag.embeddings.configs import EmbedderConfig
+from durag.llms.configs import LlmConfig
+from durag.vector_stores.configs import VectorStoreConfig
+
+# Set up the directory path
+home_dir = os.path.expanduser("~")
+durag_dir = os.environ.get("DURAG_DIR") or os.path.join(home_dir, ".durag")
+
+
+class MemoryItem(BaseModel):
+    id: str = Field(..., description="The unique identifier for the text data")
+    memory: str = Field(
+        ..., description="The memory deduced from the text data"
+    )  # TODO After prompt changes from platform, update this
+    hash: Optional[str] = Field(None, description="The hash of the memory")
+    # The metadata value can be anything and not just string. Fix it
+    metadata: Optional[Dict[str, Any]] = Field(None, description="Additional metadata for the text data")
+    score: Optional[float] = Field(None, description="The score associated with the text data")
+    created_at: Optional[str] = Field(None, description="The timestamp when the memory was created")
+    updated_at: Optional[str] = Field(None, description="The timestamp when the memory was updated")
+
+
+class MemoryConfig(BaseModel):
+    vector_store: VectorStoreConfig = Field(
+        description="Configuration for the vector store",
+        default_factory=VectorStoreConfig,
+    )
+    llm: LlmConfig = Field(
+        description="Configuration for the language model",
+        default_factory=LlmConfig,
+    )
+    embedder: EmbedderConfig = Field(
+        description="Configuration for the embedding model",
+        default_factory=EmbedderConfig,
+    )
+    history_db_path: str = Field(
+        description="Path to the history database",
+        default=os.path.join(durag_dir, "history.db"),
+    )
+    reranker: Optional[RerankerConfig] = Field(
+        description="Configuration for the reranker",
+        default=None,
+    )
+    version: str = Field(
+        description="The version of the API",
+        default="v1.1",
+    )
+    custom_instructions: Optional[str] = Field(
+        description="Custom instructions for fact extraction",
+        default=None,
+    )
+
+
+class AzureConfig(BaseModel):
+    """
+    Configuration settings for Azure.
+
+    Args:
+        api_key (str): The API key used for authenticating with the Azure service.
+        azure_deployment (str): The name of the Azure deployment.
+        azure_endpoint (str): The endpoint URL for the Azure service.
+        api_version (str): The version of the Azure API being used.
+        default_headers (Dict[str, str]): Headers to include in requests to the Azure API.
+    """
+
+    api_key: str = Field(
+        description="The API key used for authenticating with the Azure service.",
+        default=None,
+    )
+    azure_deployment: str = Field(description="The name of the Azure deployment.", default=None)
+    azure_endpoint: str = Field(description="The endpoint URL for the Azure service.", default=None)
+    api_version: str = Field(description="The version of the Azure API being used.", default=None)
+    default_headers: Optional[Dict[str, str]] = Field(
+        description="Headers to include in requests to the Azure API.", default=None
+    )

durag/configs/embeddings/base.py

@@ -0,0 +1,110 @@
+import os
+from abc import ABC
+from typing import Dict, Optional, Union
+
+import httpx
+
+from durag.configs.base import AzureConfig
+
+
+class BaseEmbedderConfig(ABC):
+    """
+    Config for Embeddings.
+    """
+
+    def __init__(
+        self,
+        model: Optional[str] = None,
+        api_key: Optional[str] = None,
+        embedding_dims: Optional[int] = None,
+        # Ollama specific
+        ollama_base_url: Optional[str] = None,
+        # Openai specific
+        openai_base_url: Optional[str] = None,
+        # Huggingface specific
+        model_kwargs: Optional[dict] = None,
+        huggingface_base_url: Optional[str] = None,
+        # AzureOpenAI specific
+        azure_kwargs: Optional[AzureConfig] = {},
+        http_client_proxies: Optional[Union[Dict, str]] = None,
+        # VertexAI specific
+        vertex_credentials_json: Optional[str] = None,
+        memory_add_embedding_type: Optional[str] = None,
+        memory_update_embedding_type: Optional[str] = None,
+        memory_search_embedding_type: Optional[str] = None,
+        # Gemini specific
+        output_dimensionality: Optional[str] = None,
+        # LM Studio specific
+        lmstudio_base_url: Optional[str] = "http://localhost:1234/v1",
+        # AWS Bedrock specific
+        aws_access_key_id: Optional[str] = None,
+        aws_secret_access_key: Optional[str] = None,
+        aws_region: Optional[str] = None,
+    ):
+        """
+        Initializes a configuration class instance for the Embeddings.
+
+        :param model: Embedding model to use, defaults to None
+        :type model: Optional[str], optional
+        :param api_key: API key to be use, defaults to None
+        :type api_key: Optional[str], optional
+        :param embedding_dims: The number of dimensions in the embedding, defaults to None
+        :type embedding_dims: Optional[int], optional
+        :param ollama_base_url: Base URL for the Ollama API, defaults to None
+        :type ollama_base_url: Optional[str], optional
+        :param model_kwargs: key-value arguments for the huggingface embedding model, defaults a dict inside init
+        :type model_kwargs: Optional[Dict[str, Any]], defaults a dict inside init
+        :param huggingface_base_url: Huggingface base URL to be use, defaults to None
+        :type huggingface_base_url: Optional[str], optional
+        :param openai_base_url: Openai base URL to be use, defaults to "https://api.openai.com/v1"
+        :type openai_base_url: Optional[str], optional
+        :param azure_kwargs: key-value arguments for the AzureOpenAI embedding model, defaults a dict inside init
+        :type azure_kwargs: Optional[Dict[str, Any]], defaults a dict inside init
+        :param http_client_proxies: The proxy server settings used to create self.http_client, defaults to None
+        :type http_client_proxies: Optional[Dict | str], optional
+        :param vertex_credentials_json: The path to the Vertex AI credentials JSON file, defaults to None
+        :type vertex_credentials_json: Optional[str], optional
+        :param memory_add_embedding_type: The type of embedding to use for the add memory action, defaults to None
+        :type memory_add_embedding_type: Optional[str], optional
+        :param memory_update_embedding_type: The type of embedding to use for the update memory action, defaults to None
+        :type memory_update_embedding_type: Optional[str], optional
+        :param memory_search_embedding_type: The type of embedding to use for the search memory action, defaults to None
+        :type memory_search_embedding_type: Optional[str], optional
+        :param lmstudio_base_url: LM Studio base URL to be use, defaults to "http://localhost:1234/v1"
+        :type lmstudio_base_url: Optional[str], optional
+        """
+
+        self.model = model
+        self.api_key = api_key
+        self.openai_base_url = openai_base_url
+        self.embedding_dims = embedding_dims
+
+        # AzureOpenAI specific
+        self.http_client = httpx.Client(proxies=http_client_proxies) if http_client_proxies else None
+
+        # Ollama specific
+        self.ollama_base_url = ollama_base_url
+
+        # Huggingface specific
+        self.model_kwargs = model_kwargs or {}
+        self.huggingface_base_url = huggingface_base_url
+        # AzureOpenAI specific
+        self.azure_kwargs = AzureConfig(**azure_kwargs) or {}
+
+        # VertexAI specific
+        self.vertex_credentials_json = vertex_credentials_json
+        self.memory_add_embedding_type = memory_add_embedding_type
+        self.memory_update_embedding_type = memory_update_embedding_type
+        self.memory_search_embedding_type = memory_search_embedding_type
+
+        # Gemini specific
+        self.output_dimensionality = output_dimensionality
+
+        # LM Studio specific
+        self.lmstudio_base_url = lmstudio_base_url
+
+        # AWS Bedrock specific
+        self.aws_access_key_id = aws_access_key_id
+        self.aws_secret_access_key = aws_secret_access_key
+        self.aws_region = aws_region or os.environ.get("AWS_REGION") or "us-west-2"
+

durag/configs/enums.py

@@ -0,0 +1,7 @@
+from enum import Enum
+
+
+class MemoryType(Enum):
+    SEMANTIC = "semantic_memory"
+    EPISODIC = "episodic_memory"
+    PROCEDURAL = "procedural_memory"

durag/configs/llms/anthropic.py

@@ -0,0 +1,56 @@
+from typing import Optional
+
+from durag.configs.llms.base import BaseLlmConfig
+
+
+class AnthropicConfig(BaseLlmConfig):
+    """
+    Configuration class for Anthropic-specific parameters.
+    Inherits from BaseLlmConfig and adds Anthropic-specific settings.
+    """
+
+    def __init__(
+        self,
+        # Base parameters
+        model: Optional[str] = None,
+        temperature: float = 0.1,
+        api_key: Optional[str] = None,
+        max_tokens: int = 2000,
+        top_p: Optional[float] = None,
+        top_k: int = 1,
+        enable_vision: bool = False,
+        vision_details: Optional[str] = "auto",
+        http_client_proxies: Optional[dict] = None,
+        # Anthropic-specific parameters
+        anthropic_base_url: Optional[str] = None,
+    ):
+        """
+        Initialize Anthropic configuration.
+
+        Args:
+            model: Anthropic model to use, defaults to None
+            temperature: Controls randomness, defaults to 0.1
+            api_key: Anthropic API key, defaults to None
+            max_tokens: Maximum tokens to generate, defaults to 2000
+            top_p: Nucleus sampling parameter, defaults to None (omitted to avoid conflict with temperature)
+            top_k: Top-k sampling parameter, defaults to 1
+            enable_vision: Enable vision capabilities, defaults to False
+            vision_details: Vision detail level, defaults to "auto"
+            http_client_proxies: HTTP client proxy settings, defaults to None
+            anthropic_base_url: Anthropic API base URL, defaults to None
+        """
+        # Initialize base parameters
+        super().__init__(
+            model=model,
+            temperature=temperature,
+            api_key=api_key,
+            max_tokens=max_tokens,
+            top_p=top_p,
+            top_k=top_k,
+            enable_vision=enable_vision,
+            vision_details=vision_details,
+            http_client_proxies=http_client_proxies,
+        )
+
+        # Anthropic-specific parameters
+        self.anthropic_base_url = anthropic_base_url

durag/configs/llms/aws_bedrock.py

@@ -0,0 +1,196 @@
+import os
+from typing import Any, Dict, List, Optional
+
+from durag.configs.llms.base import BaseLlmConfig
+
+
+class AWSBedrockConfig(BaseLlmConfig):
+    """
+    Configuration class for AWS Bedrock LLM integration.
+
+    Supports all available Bedrock models with automatic provider detection.
+    """
+
+    def __init__(
+        self,
+        model: Optional[str] = None,
+        temperature: float = 0.1,
+        max_tokens: int = 2000,
+        top_p: Optional[float] = None,
+        top_k: int = 1,
+        aws_access_key_id: Optional[str] = None,
+        aws_secret_access_key: Optional[str] = None,
+        aws_region: str = "",
+        aws_session_token: Optional[str] = None,
+        aws_profile: Optional[str] = None,
+        model_kwargs: Optional[Dict[str, Any]] = None,
+        **kwargs,
+    ):
+        """
+        Initialize AWS Bedrock configuration.
+
+        Args:
+            model: Bedrock model identifier (e.g., "amazon.nova-3-mini-20241119-v1:0")
+            temperature: Controls randomness (0.0 to 2.0)
+            max_tokens: Maximum tokens to generate
+            top_p: Nucleus sampling (0.0–1.0). Default None omits topP on Converse
+                (required for Anthropic, which rejects temperature and topP together).
+            top_k: Top-k sampling parameter (1 to 40)
+            aws_access_key_id: AWS access key (optional, uses env vars if not provided)
+            aws_secret_access_key: AWS secret key (optional, uses env vars if not provided)
+            aws_region: AWS region for Bedrock service
+            aws_session_token: AWS session token for temporary credentials
+            aws_profile: AWS profile name for credentials
+            model_kwargs: Additional model-specific parameters
+            **kwargs: Additional arguments passed to base class
+        """
+        super().__init__(
+            model=model or "anthropic.claude-3-5-sonnet-20240620-v1:0",
+            temperature=temperature,
+            max_tokens=max_tokens,
+            top_p=top_p,
+            top_k=top_k,
+            **kwargs,
+        )
+
+        self.aws_access_key_id = aws_access_key_id
+        self.aws_secret_access_key = aws_secret_access_key
+        self.aws_region = aws_region or os.getenv("AWS_REGION", "us-west-2")
+        self.aws_session_token = aws_session_token
+        self.aws_profile = aws_profile
+        self.model_kwargs = model_kwargs or {}
+
+    @property
+    def provider(self) -> str:
+        """Get the provider from the model identifier."""
+        if not self.model or "." not in self.model:
+            return "unknown"
+        return self.model.split(".")[0]
+
+    @property
+    def model_name(self) -> str:
+        """Get the model name without provider prefix."""
+        if not self.model or "." not in self.model:
+            return self.model
+        return ".".join(self.model.split(".")[1:])
+
+    def get_model_config(self) -> Dict[str, Any]:
+        """Get model-specific configuration parameters."""
+        base_config: Dict[str, Any] = {
+            "temperature": self.temperature,
+            "max_tokens": self.max_tokens,
+            "top_k": self.top_k,
+        }
+
+        # Only include top_p when explicitly set by the user.
+        if self.top_p is not None:
+            base_config["top_p"] = self.top_p
+
+        # Add custom model kwargs
+        base_config.update(self.model_kwargs)
+
+        return base_config
+
+    def get_aws_config(self) -> Dict[str, Any]:
+        """Get AWS configuration parameters."""
+        config = {
+            "region_name": self.aws_region,
+        }
+
+        if self.aws_access_key_id:
+            config["aws_access_key_id"] = self.aws_access_key_id or os.getenv("AWS_ACCESS_KEY_ID")
+            
+        if self.aws_secret_access_key:
+            config["aws_secret_access_key"] = self.aws_secret_access_key or os.getenv("AWS_SECRET_ACCESS_KEY")
+            
+        if self.aws_session_token:
+            config["aws_session_token"] = self.aws_session_token or os.getenv("AWS_SESSION_TOKEN")
+            
+        if self.aws_profile:
+            config["profile_name"] = self.aws_profile or os.getenv("AWS_PROFILE")
+
+        return config
+
+    def validate_model_format(self) -> bool:
+        """
+        Validate that the model identifier follows Bedrock naming convention.
+        
+        Returns:
+            True if valid, False otherwise
+        """
+        if not self.model:
+            return False
+            
+        # Check if model follows provider.model-name format
+        if "." not in self.model:
+            return False
+            
+        provider, model_name = self.model.split(".", 1)
+        
+        # Validate provider
+        valid_providers = [
+            "ai21", "amazon", "anthropic", "cohere", "meta", "mistral", 
+            "stability", "writer", "deepseek", "gpt-oss", "perplexity", 
+            "snowflake", "titan", "command", "j2", "llama"
+        ]
+        
+        if provider not in valid_providers:
+            return False
+            
+        # Validate model name is not empty
+        if not model_name:
+            return False
+            
+        return True
+
+    def get_supported_regions(self) -> List[str]:
+        """Get list of AWS regions that support Bedrock."""
+        return [
+            "us-east-1",
+            "us-west-2",
+            "us-east-2",
+            "eu-west-1",
+            "ap-southeast-1",
+            "ap-northeast-1",
+        ]
+
+    def get_model_capabilities(self) -> Dict[str, Any]:
+        """Get model capabilities based on provider."""
+        capabilities = {
+            "supports_tools": False,
+            "supports_vision": False,
+            "supports_streaming": False,
+            "supports_multimodal": False,
+        }
+        
+        if self.provider == "anthropic":
+            capabilities.update({
+                "supports_tools": True,
+                "supports_vision": True,
+                "supports_streaming": True,
+                "supports_multimodal": True,
+            })
+        elif self.provider == "amazon":
+            capabilities.update({
+                "supports_tools": True,
+                "supports_vision": True,
+                "supports_streaming": True,
+                "supports_multimodal": True,
+            })
+        elif self.provider == "cohere":
+            capabilities.update({
+                "supports_tools": True,
+                "supports_streaming": True,
+            })
+        elif self.provider == "meta":
+            capabilities.update({
+                "supports_vision": True,
+                "supports_streaming": True,
+            })
+        elif self.provider == "mistral":
+            capabilities.update({
+                "supports_vision": True,
+                "supports_streaming": True,
+            })
+            
+        return capabilities

durag/configs/llms/azure.py

@@ -0,0 +1,60 @@
+from typing import Any, Dict, Optional
+
+from durag.configs.base import AzureConfig
+from durag.configs.llms.base import BaseLlmConfig
+
+
+class AzureOpenAIConfig(BaseLlmConfig):
+    """
+    Configuration class for Azure OpenAI-specific parameters.
+    Inherits from BaseLlmConfig and adds Azure OpenAI-specific settings.
+    """
+
+    def __init__(
+        self,
+        # Base parameters
+        model: Optional[str] = None,
+        temperature: float = 0.1,
+        api_key: Optional[str] = None,
+        max_tokens: int = 2000,
+        top_p: float = 0.1,
+        top_k: int = 1,
+        enable_vision: bool = False,
+        vision_details: Optional[str] = "auto",
+        reasoning_effort: Optional[str] = None,
+        http_client_proxies: Optional[dict] = None,
+        # Azure OpenAI-specific parameters
+        azure_kwargs: Optional[Dict[str, Any]] = None,
+    ):
+        """
+        Initialize Azure OpenAI configuration.
+
+        Args:
+            model: Azure OpenAI model to use, defaults to None
+            temperature: Controls randomness, defaults to 0.1
+            api_key: Azure OpenAI API key, defaults to None
+            max_tokens: Maximum tokens to generate, defaults to 2000
+            top_p: Nucleus sampling parameter, defaults to 0.1
+            top_k: Top-k sampling parameter, defaults to 1
+            enable_vision: Enable vision capabilities, defaults to False
+            vision_details: Vision detail level, defaults to "auto"
+            reasoning_effort: Effort level for reasoning models ("low", "medium", "high"), defaults to None
+            http_client_proxies: HTTP client proxy settings, defaults to None
+            azure_kwargs: Azure-specific configuration, defaults to None
+        """
+        # Initialize base parameters
+        super().__init__(
+            model=model,
+            temperature=temperature,
+            api_key=api_key,
+            max_tokens=max_tokens,
+            top_p=top_p,
+            top_k=top_k,
+            enable_vision=enable_vision,
+            vision_details=vision_details,
+            reasoning_effort=reasoning_effort,
+            http_client_proxies=http_client_proxies,
+        )
+
+        # Azure OpenAI-specific parameters
+        self.azure_kwargs = AzureConfig(**(azure_kwargs or {}))

durag/configs/llms/base.py

@@ -0,0 +1,67 @@
+from abc import ABC
+from typing import Dict, Optional, Union
+
+import httpx
+
+
+class BaseLlmConfig(ABC):
+    """
+    Base configuration for LLMs with only common parameters.
+    Provider-specific configurations should be handled by separate config classes.
+
+    This class contains only the parameters that are common across all LLM providers.
+    For provider-specific parameters, use the appropriate provider config class.
+    """
+
+    def __init__(
+        self,
+        model: Optional[Union[str, Dict]] = None,
+        temperature: float = 0.1,
+        api_key: Optional[str] = None,
+        max_tokens: int = 2000,
+        top_p: float = 0.1,
+        top_k: int = 1,
+        enable_vision: bool = False,
+        vision_details: Optional[str] = "auto",
+        reasoning_effort: Optional[str] = None,
+        http_client_proxies: Optional[Union[Dict, str]] = None,
+    ):
+        """
+        Initialize a base configuration class instance for the LLM.
+
+        Args:
+            model: The model identifier to use (e.g., "gpt-4.1-nano-2025-04-14", "claude-3-5-sonnet-20240620")
+                Defaults to None (will be set by provider-specific configs)
+            temperature: Controls the randomness of the model's output.
+                Higher values (closer to 1) make output more random, lower values make it more deterministic.
+                Range: 0.0 to 2.0. Defaults to 0.1
+            api_key: API key for the LLM provider. If None, will try to get from environment variables.
+                Defaults to None
+            max_tokens: Maximum number of tokens to generate in the response.
+                Range: 1 to 4096 (varies by model). Defaults to 2000
+            top_p: Nucleus sampling parameter. Controls diversity via nucleus sampling.
+                Higher values (closer to 1) make word selection more diverse.
+                Range: 0.0 to 1.0. Defaults to 0.1
+            top_k: Top-k sampling parameter. Limits the number of tokens considered for each step.
+                Higher values make word selection more diverse.
+                Range: 1 to 40. Defaults to 1
+            enable_vision: Whether to enable vision capabilities for the model.
+                Only applicable to vision-enabled models. Defaults to False
+            vision_details: Level of detail for vision processing.
+                Options: "low", "high", "auto". Defaults to "auto"
+            reasoning_effort: Effort level for reasoning models (e.g., o1, o3, gpt-5).
+                Options: "low", "medium", "high". Only applicable to reasoning models.
+                Defaults to None (uses the model's default reasoning effort)
+            http_client_proxies: Proxy settings for HTTP client.
+                Can be a dict or string. Defaults to None
+        """
+        self.model = model
+        self.temperature = temperature
+        self.api_key = api_key
+        self.max_tokens = max_tokens
+        self.top_p = top_p
+        self.top_k = top_k
+        self.enable_vision = enable_vision
+        self.vision_details = vision_details
+        self.reasoning_effort = reasoning_effort
+        self.http_client = httpx.Client(proxies=http_client_proxies) if http_client_proxies else None

durag/configs/llms/deepseek.py

@@ -0,0 +1,56 @@
+from typing import Optional
+
+from durag.configs.llms.base import BaseLlmConfig
+
+
+class DeepSeekConfig(BaseLlmConfig):
+    """
+    Configuration class for DeepSeek-specific parameters.
+    Inherits from BaseLlmConfig and adds DeepSeek-specific settings.
+    """
+
+    def __init__(
+        self,
+        # Base parameters
+        model: Optional[str] = None,
+        temperature: float = 0.1,
+        api_key: Optional[str] = None,
+        max_tokens: int = 2000,
+        top_p: float = 0.1,
+        top_k: int = 1,
+        enable_vision: bool = False,
+        vision_details: Optional[str] = "auto",
+        http_client_proxies: Optional[dict] = None,
+        # DeepSeek-specific parameters
+        deepseek_base_url: Optional[str] = None,
+    ):
+        """
+        Initialize DeepSeek configuration.
+
+        Args:
+            model: DeepSeek model to use, defaults to None
+            temperature: Controls randomness, defaults to 0.1
+            api_key: DeepSeek API key, defaults to None
+            max_tokens: Maximum tokens to generate, defaults to 2000
+            top_p: Nucleus sampling parameter, defaults to 0.1
+            top_k: Top-k sampling parameter, defaults to 1
+            enable_vision: Enable vision capabilities, defaults to False
+            vision_details: Vision detail level, defaults to "auto"
+            http_client_proxies: HTTP client proxy settings, defaults to None
+            deepseek_base_url: DeepSeek API base URL, defaults to None
+        """
+        # Initialize base parameters
+        super().__init__(
+            model=model,
+            temperature=temperature,
+            api_key=api_key,
+            max_tokens=max_tokens,
+            top_p=top_p,
+            top_k=top_k,
+            enable_vision=enable_vision,
+            vision_details=vision_details,
+            http_client_proxies=http_client_proxies,
+        )
+
+        # DeepSeek-specific parameters
+        self.deepseek_base_url = deepseek_base_url