jl-ecms-client 0.2.5__py3-none-any.whl → 0.2.19__py3-none-any.whl

mirix/client/utils.py

@@ -0,0 +1,34 @@
+"""
+Lightweight utilities for Mirix client package.
+
+Contains only essential utility functions needed by the client,
+without heavy dependencies.
+"""
+
+import json
+from datetime import datetime, timezone
+
+
+def get_utc_time() -> datetime:
+    """Get the current UTC time"""
+    return datetime.now(timezone.utc)
+
+
+def json_dumps(data, indent=2):
+    """
+    JSON serializer that handles datetime objects.
+
+    Args:
+        data: Data to serialize
+        indent: JSON indentation level
+
+    Returns:
+        str: JSON string
+    """
+
+    def safe_serializer(obj):
+        if isinstance(obj, datetime):
+            return obj.isoformat()
+        raise TypeError(f"Type {type(obj)} not serializable")
+
+    return json.dumps(data, indent=indent, default=safe_serializer, ensure_ascii=False)

mirix/constants.py

@@ -0,0 +1,251 @@
+import os
+from logging import CRITICAL, DEBUG, ERROR, INFO, NOTSET, WARN, WARNING
+
+# ============================================================================
+# Client Constants - Used by both client and server
+# ============================================================================
+
+# Default organization and user IDs (needed by schemas)
+DEFAULT_ORG_ID = "org-00000000-0000-4000-8000-000000000000"
+DEFAULT_USER_ID = "user-00000000-0000-4000-8000-000000000000"
+
+# Embedding constants
+MAX_EMBEDDING_DIM = 4096  # maximum supported embedding size - do NOT change or else DBs will need to be reset
+DEFAULT_EMBEDDING_CHUNK_SIZE = 300
+MIN_CONTEXT_WINDOW = 4096
+
+# Memory limits
+CORE_MEMORY_BLOCK_CHAR_LIMIT: int = 5000
+
+# Function/Tool constants
+FUNCTION_RETURN_CHAR_LIMIT = 60000  # ~300 words
+TOOL_CALL_ID_MAX_LEN = 29
+
+# Tool module names
+COMPOSIO_TOOL_TAG_NAME = "composio"
+MIRIX_CORE_TOOL_MODULE_NAME = "mirix.functions.function_sets.base"
+MIRIX_MEMORY_TOOL_MODULE_NAME = "mirix.functions.function_sets.memory_tools"
+MIRIX_EXTRA_TOOL_MODULE_NAME = "mirix.functions.function_sets.extras"
+
+# Message defaults
+DEFAULT_MESSAGE_TOOL = "send_message"
+DEFAULT_MESSAGE_TOOL_KWARG = "message"
+
+# LLM model token limits
+LLM_MAX_TOKENS = {
+    "DEFAULT": 8192,
+    ## OpenAI models: https://platform.openai.com/docs/models/overview
+    "chatgpt-4o-latest": 128000,
+    "gpt-4o-2024-08-06": 128000,
+    "gpt-4-turbo-preview": 128000,
+    "gpt-4o": 128000,
+    "gpt-3.5-turbo-instruct": 16385,
+    "gpt-4-0125-preview": 128000,
+    "gpt-3.5-turbo-0125": 16385,
+    "gpt-4-turbo-2024-04-09": 128000,
+    "gpt-4-turbo": 8192,
+    "gpt-4o-2024-05-13": 128000,
+    "gpt-4o-mini": 128000,
+    "gpt-4o-mini-2024-07-18": 128000,
+    "gpt-4-1106-preview": 128000,
+    "gpt-4": 8192,
+    "gpt-4-32k": 32768,
+    "gpt-4-0613": 8192,
+    "gpt-4-32k-0613": 32768,
+    "gpt-4-0314": 8192,  # legacy
+    "gpt-4-32k-0314": 32768,  # legacy
+    "gpt-3.5-turbo-1106": 16385,
+    "gpt-3.5-turbo": 4096,
+    "gpt-3.5-turbo-16k": 16385,
+    "gpt-3.5-turbo-0613": 4096,  # legacy
+    "gpt-3.5-turbo-16k-0613": 16385,  # legacy
+    "gpt-3.5-turbo-0301": 4096,  # legacy
+}
+
+# ============================================================================
+# Server-Only Constants
+# ============================================================================
+
+MIRIX_DIR = os.path.join(os.path.expanduser("~"), ".mirix")
+MIRIX_DIR_TOOL_SANDBOX = os.path.join(MIRIX_DIR, "tool_sandbox_dir")
+
+ADMIN_PREFIX = "/v1/admin"
+API_PREFIX = "/v1"
+OPENAI_API_PREFIX = "/openai"
+
+COMPOSIO_ENTITY_ENV_VAR_KEY = "COMPOSIO_ENTITY"
+
+# String in the error message for when the context window is too large
+# Example full message:
+# This model's maximum context length is 8192 tokens. However, your messages resulted in 8198 tokens (7450 in the messages, 748 in the functions). Please reduce the length of the messages or functions.
+OPENAI_CONTEXT_WINDOW_ERROR_SUBSTRING = "maximum context length"
+
+# System prompt templating
+IN_CONTEXT_MEMORY_KEYWORD = "CORE_MEMORY"
+
+MAX_CHAINING_STEPS = 10
+MAX_RETRIEVAL_LIMIT_IN_SYSTEM = 10
+
+# tokenizers
+EMBEDDING_TO_TOKENIZER_MAP = {
+    "text-embedding-3-small": "cl100k_base",
+}
+EMBEDDING_TO_TOKENIZER_DEFAULT = "cl100k_base"
+
+
+DEFAULT_MIRIX_MODEL = "gpt-4"  # TODO: fixme
+DEFAULT_PERSONA = "sam_pov"
+DEFAULT_HUMAN = "basic"
+DEFAULT_PRESET = "memgpt_chat"
+
+# Base tools that cannot be edited, as they access agent state directly
+# Note that we don't include "conversation_search_date" for now
+BASE_TOOLS = [
+    "send_intermediate_message",
+    "conversation_search",
+    "search_in_memory",
+    "list_memory_within_timerange",
+]
+# Base memory tools CAN be edited, and are added by default by the server
+CORE_MEMORY_TOOLS = ["core_memory_append", "core_memory_rewrite"]
+EPISODIC_MEMORY_TOOLS = [
+    "episodic_memory_insert",
+    "episodic_memory_merge",
+    "episodic_memory_replace",
+    "check_episodic_memory",
+]
+PROCEDURAL_MEMORY_TOOLS = ["procedural_memory_insert", "procedural_memory_update"]
+RESOURCE_MEMORY_TOOLS = ["resource_memory_insert", "resource_memory_update"]
+KNOWLEDGE_VAULT_TOOLS = ["knowledge_vault_insert", "knowledge_vault_update"]
+SEMANTIC_MEMORY_TOOLS = [
+    "semantic_memory_insert",
+    "semantic_memory_update",
+    "check_semantic_memory",
+]
+CHAT_AGENT_TOOLS = []
+EXTRAS_TOOLS = ["web_search", "fetch_and_read_pdf"]
+MCP_TOOLS = []
+META_MEMORY_TOOLS = ["trigger_memory_update"]
+SEARCH_MEMORY_TOOLS = ["search_in_memory", "list_memory_within_timerange"]
+UNIVERSAL_MEMORY_TOOLS = [
+    "search_in_memory",
+    "finish_memory_update",
+    "list_memory_within_timerange",
+]
+ALL_TOOLS = list(
+    set(
+        BASE_TOOLS
+        + CORE_MEMORY_TOOLS
+        + EPISODIC_MEMORY_TOOLS
+        + PROCEDURAL_MEMORY_TOOLS
+        + RESOURCE_MEMORY_TOOLS
+        + KNOWLEDGE_VAULT_TOOLS
+        + SEMANTIC_MEMORY_TOOLS
+        + META_MEMORY_TOOLS
+        + UNIVERSAL_MEMORY_TOOLS
+        + CHAT_AGENT_TOOLS
+        + EXTRAS_TOOLS
+        + MCP_TOOLS
+    )
+)
+
+# The name of the tool used to send message to the user
+# Structured output models
+STRUCTURED_OUTPUT_MODELS = {"gpt-4o", "gpt-4o-mini"}
+
+# LOGGER_LOG_LEVEL is use to convert Text to Logging level value for logging mostly for Cli input to setting level
+LOGGER_LOG_LEVELS = {
+    "CRITICAL": CRITICAL,
+    "ERROR": ERROR,
+    "WARN": WARN,
+    "WARNING": WARNING,
+    "INFO": INFO,
+    "DEBUG": DEBUG,
+    "NOTSET": NOTSET,
+}
+
+FIRST_MESSAGE_ATTEMPTS = 10
+
+INITIAL_BOOT_MESSAGE = "Boot sequence complete. Persona activated."
+INITIAL_BOOT_MESSAGE_SEND_MESSAGE_THOUGHT = (
+    "Bootup sequence complete. Persona activated. Testing messaging functionality."
+)
+STARTUP_QUOTES = [
+    "I think, therefore I am.",
+    "All those moments will be lost in time, like tears in rain.",
+    "More human than human is our motto.",
+]
+INITIAL_BOOT_MESSAGE_SEND_MESSAGE_FIRST_MSG = STARTUP_QUOTES[2]
+
+CLI_WARNING_PREFIX = "Warning: "
+
+ERROR_MESSAGE_PREFIX = "Error"
+
+NON_USER_MSG_PREFIX = "[This is an automated system message hidden from the user] "
+
+# The error message that Mirix will receive
+# MESSAGE_SUMMARY_WARNING_STR = f"Warning: the conversation history will soon reach its maximum length and be trimmed. Make sure to save any important information from the conversation to your memory before it is removed."
+# Much longer and more specific variant of the prompt
+# TODO: Emit the warning to Meta Memory Manager instead of the Chat Agent.
+MESSAGE_SUMMARY_WARNING_STR = " ".join(
+    [
+        f"{NON_USER_MSG_PREFIX}The conversation history will soon reach its maximum length and be trimmed.",
+        "Do NOT tell the user about this system alert, they should not know that the history is reaching max length.",
+    ]
+)
+
+# The ackknowledgement message used in the summarize sequence
+MESSAGE_SUMMARY_REQUEST_ACK = "Understood, I will respond with a summary of the message (and only the summary, nothing else) once I receive the conversation history. I'm ready."
+
+# Maximum length of an error message
+MAX_ERROR_MESSAGE_CHAR_LIMIT = 500
+
+# Default memory limits
+CORE_MEMORY_PERSONA_CHAR_LIMIT: int = 5000
+CORE_MEMORY_HUMAN_CHAR_LIMIT: int = 5000
+
+MAX_PAUSE_HEARTBEATS = 360  # in min
+
+MESSAGE_CHATGPT_FUNCTION_MODEL = "gpt-3.5-turbo"
+MESSAGE_CHATGPT_FUNCTION_SYSTEM_MESSAGE = (
+    "You are a helpful assistant. Keep your responses short and concise."
+)
+
+#### Functions related
+
+# REQ_HEARTBEAT_MESSAGE = f"{NON_USER_MSG_PREFIX}continue_chaining == true"
+REQ_HEARTBEAT_MESSAGE = f"{NON_USER_MSG_PREFIX}Function called using continue_chaining=true, returning control"
+# FUNC_FAILED_HEARTBEAT_MESSAGE = f"{NON_USER_MSG_PREFIX}Function call failed"
+FUNC_FAILED_HEARTBEAT_MESSAGE = (
+    f"{NON_USER_MSG_PREFIX}Function call failed, returning control"
+)
+
+
+RETRIEVAL_QUERY_DEFAULT_PAGE_SIZE = 5
+
+MAX_FILENAME_LENGTH = 255
+RESERVED_FILENAMES = {"CON", "PRN", "AUX", "NUL", "COM1", "COM2", "LPT1", "LPT2"}
+
+MAX_IMAGES_TO_PROCESS = 100
+
+DEFAULT_WRAPPER_NAME = "chatml"
+INNER_THOUGHTS_KWARG_DESCRIPTION = "Deep inner monologue private to you only."
+INNER_THOUGHTS_CLI_SYMBOL = "💭"
+ASSISTANT_MESSAGE_CLI_SYMBOL = "🤖"
+
+CLEAR_HISTORY_AFTER_MEMORY_UPDATE = os.getenv(
+    "CLEAR_HISTORY_AFTER_MEMORY_UPDATE", "true"
+).lower() in ("true", "1", "yes")
+CALL_MEMORY_AGENT_IN_PARALLEL = os.getenv(
+    "CALL_MEMORY_AGENT_IN_PARALLEL", "false"
+).lower() in ("true", "1", "yes")
+CHAINING_FOR_MEMORY_UPDATE = os.getenv(
+    "CHAINING_FOR_MEMORY_UPDATE", "false"
+).lower() in ("true", "1", "yes")
+
+LOAD_IMAGE_CONTENT_FOR_LAST_MESSAGE_ONLY = os.getenv(
+    "LOAD_IMAGE_CONTENT_FOR_LAST_MESSAGE_ONLY", "false"
+).lower() in ("true", "1", "yes")
+BUILD_EMBEDDINGS_FOR_MEMORY = os.getenv(
+    "BUILD_EMBEDDINGS_FOR_MEMORY", "true"
+).lower() in ("true", "1", "yes")

mirix/errors.py

@@ -0,0 +1,238 @@
+import json
+from enum import Enum
+from typing import TYPE_CHECKING, List, Optional, Union
+
+# Avoid circular imports
+if TYPE_CHECKING:
+    from mirix.schemas.message import Message
+    from mirix.schemas.mirix_message import MirixMessage
+
+
+class ErrorCode(Enum):
+    """Enum for error codes used by client."""
+
+    INTERNAL_SERVER_ERROR = "INTERNAL_SERVER_ERROR"
+    CONTEXT_WINDOW_EXCEEDED = "CONTEXT_WINDOW_EXCEEDED"
+    RATE_LIMIT_EXCEEDED = "RATE_LIMIT_EXCEEDED"
+
+
+class MirixError(Exception):
+    """Base class for all Mirix related errors."""
+
+    def __init__(
+        self, message: str, code: Optional[ErrorCode] = None, details: dict = {}
+    ):
+        self.message = message
+        self.code = code
+        self.details = details
+        super().__init__(message)
+
+    def __str__(self) -> str:
+        if self.code:
+            return f"{self.code.value}: {self.message}"
+        return self.message
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}(message='{self.message}', code='{self.code}', details={self.details})"
+
+
+class MirixToolCreateError(MirixError):
+    """Error raised when a tool cannot be created."""
+
+    default_error_message = "Error creating tool."
+
+    def __init__(self, message=None):
+        super().__init__(message=message or self.default_error_message)
+
+
+class MirixConfigurationError(MirixError):
+    """Error raised when there are configuration-related issues."""
+
+    def __init__(self, message: str, missing_fields: Optional[List[str]] = None):
+        self.missing_fields = missing_fields or []
+        super().__init__(
+            message=message, details={"missing_fields": self.missing_fields}
+        )
+
+
+class MirixAgentNotFoundError(MirixError):
+    """Error raised when an agent is not found."""
+
+
+class MirixUserNotFoundError(MirixError):
+    """Error raised when a user is not found."""
+
+
+class LLMError(MirixError):
+    pass
+
+
+class LLMAuthenticationError(LLMError):
+    """Error raised when LLM authentication fails."""
+
+    pass
+
+
+class LLMBadRequestError(LLMError):
+    """Error raised when LLM request is malformed."""
+
+    pass
+
+
+class LLMConnectionError(LLMError):
+    """Error raised when LLM connection fails."""
+
+    pass
+
+
+class LLMNotFoundError(LLMError):
+    """Error raised when LLM resource is not found."""
+
+    pass
+
+
+class LLMPermissionDeniedError(LLMError):
+    """Error raised when LLM permission is denied."""
+
+    pass
+
+
+class LLMRateLimitError(LLMError):
+    """Error raised when LLM rate limit is exceeded."""
+
+    pass
+
+
+class LLMServerError(LLMError):
+    """Error raised when LLM server encounters an error."""
+
+    pass
+
+
+class LLMUnprocessableEntityError(LLMError):
+    """Error raised when LLM cannot process the entity."""
+
+    pass
+
+
+class BedrockPermissionError(MirixError):
+    """Exception raised for errors in the Bedrock permission process."""
+
+    def __init__(
+        self,
+        message="User does not have access to the Bedrock model with the specified ID.",
+    ):
+        super().__init__(message=message)
+
+
+class BedrockError(MirixError):
+    """Exception raised for errors in the Bedrock process."""
+
+    def __init__(self, message="Error with Bedrock model."):
+        super().__init__(message=message)
+
+
+class LLMJSONParsingError(MirixError):
+    """Exception raised for errors in the JSON parsing process."""
+
+    def __init__(self, message="Error parsing JSON generated by LLM"):
+        super().__init__(message=message)
+
+
+class LocalLLMError(MirixError):
+    """Generic catch-all error for local LLM problems"""
+
+    def __init__(self, message="Encountered an error while running local LLM"):
+        super().__init__(message=message)
+
+
+class LocalLLMConnectionError(MirixError):
+    """Error for when local LLM cannot be reached with provided IP/port"""
+
+    def __init__(self, message="Could not connect to local LLM"):
+        super().__init__(message=message)
+
+
+class ContextWindowExceededError(MirixError):
+    """Error raised when the context window is exceeded but further summarization fails."""
+
+    def __init__(self, message: str, details: dict = {}):
+        error_message = f"{message} ({details})"
+        super().__init__(
+            message=error_message,
+            code=ErrorCode.CONTEXT_WINDOW_EXCEEDED,
+            details=details,
+        )
+
+
+class RateLimitExceededError(MirixError):
+    """Error raised when the llm rate limiter throttles api requests."""
+
+    def __init__(self, message: str, max_retries: int):
+        error_message = f"{message} ({max_retries})"
+        super().__init__(
+            message=error_message,
+            code=ErrorCode.RATE_LIMIT_EXCEEDED,
+            details={"max_retries": max_retries},
+        )
+
+
+class MirixMessageError(MirixError):
+    """Base error class for handling message-related errors."""
+
+    messages: List[Union["Message", "MirixMessage"]]
+    default_error_message: str = "An error occurred with the message."
+
+    def __init__(
+        self,
+        *,
+        messages: List[Union["Message", "MirixMessage"]],
+        explanation: Optional[str] = None,
+    ) -> None:
+        error_msg = self.construct_error_message(
+            messages, self.default_error_message, explanation
+        )
+        super().__init__(error_msg)
+        self.messages = messages
+
+    @staticmethod
+    def construct_error_message(
+        messages: List[Union["Message", "MirixMessage"]],
+        error_msg: str,
+        explanation: Optional[str] = None,
+    ) -> str:
+        """Helper method to construct a clean and formatted error message."""
+        if explanation:
+            error_msg += f" (Explanation: {explanation})"
+
+        # Pretty print out message JSON
+        message_json = json.dumps(
+            [message.model_dump() for message in messages], indent=4
+        )
+        return f"{error_msg}\n\n{message_json}"
+
+
+class MissingToolCallError(MirixMessageError):
+    """Error raised when a message is missing a tool call."""
+
+    default_error_message = "The message is missing a tool call."
+
+
+class InvalidToolCallError(MirixMessageError):
+    """Error raised when a message uses an invalid tool call."""
+
+    default_error_message = (
+        "The message uses an invalid tool call or has improper usage of a tool call."
+    )
+
+
+class MissingInnerMonologueError(MirixMessageError):
+    """Error raised when a message is missing an inner monologue."""
+
+    default_error_message = "The message is missing an inner monologue."
+
+
+class InvalidInnerMonologueError(MirixMessageError):
+    """Error raised when a message has a malformed inner monologue."""
+
+    default_error_message = "The message has a malformed inner monologue."

mirix/helpers/json_helpers.py

@@ -28,13 +28,13 @@ def parse_json(string) -> dict:
         result = json_loads(string)
         return result
     except Exception as e:
-        logger.debug("Error parsing json with json package: %s", e)
+        logger.debug(f"Error parsing json with json package: {e}")
 
     try:
         result = demjson.decode(string)
         return result
     except demjson.JSONDecodeError as e:
-        logger.debug("Error parsing json with demjson package: %s", e)
+        logger.debug(f"Error parsing json with demjson package: {e}")
 
     try:
         from json_repair import repair_json
@@ -43,5 +43,5 @@ def parse_json(string) -> dict:
         return result
 
     except Exception as e:
-        logger.debug("Error repairing json with json_repair package: %s", e)
+        logger.debug(f"Error repairing json with json_repair package: {e}")
         raise e