jl-ecms-client 0.2.0__py3-none-any.whl

mirix/schemas/file.py

@@ -0,0 +1,57 @@
+from datetime import datetime
+from typing import Optional
+
+from pydantic import Field
+
+from mirix.helpers.datetime_helpers import get_utc_time
+from mirix.schemas.mirix_base import MirixBase
+
+
+class FileMetadataBase(MirixBase):
+    """Base class for FileMetadata schemas"""
+
+    __id_prefix__ = "file"
+
+
+class FileMetadata(FileMetadataBase):
+    """Representation of a single FileMetadata"""
+
+    id: str = FileMetadataBase.generate_id_field()
+    organization_id: Optional[str] = Field(
+        None,
+        description="The unique identifier of the organization associated with the document.",
+    )
+    source_id: Optional[str] = Field(
+        None,
+        description="The unique identifier of the source associated with the file.",
+    )
+    file_name: Optional[str] = Field(None, description="The name of the file.")
+    file_path: Optional[str] = Field(
+        None, description="The path to the file on the local filesystem."
+    )
+    source_url: Optional[str] = Field(
+        None, description="The URL of the remote file (for files not stored locally)."
+    )
+    google_cloud_url: Optional[str] = Field(
+        None,
+        description="The Google Cloud URI for files stored in Google Cloud (e.g., Google Gemini files).",
+    )
+    file_type: Optional[str] = Field(
+        None, description="The type of the file (MIME type)."
+    )
+    file_size: Optional[int] = Field(None, description="The size of the file in bytes.")
+    file_creation_date: Optional[str] = Field(
+        None, description="The creation date of the file."
+    )
+    file_last_modified_date: Optional[str] = Field(
+        None, description="The last modified date of the file."
+    )
+
+    # orm metadata, optional fields
+    created_at: Optional[datetime] = Field(
+        default_factory=get_utc_time, description="The creation date of the file."
+    )
+    updated_at: Optional[datetime] = Field(
+        default_factory=get_utc_time, description="The update date of the file."
+    )
+    is_deleted: bool = Field(False, description="Whether this file is deleted or not.")

mirix/schemas/health.py

@@ -0,0 +1,10 @@
+from pydantic import BaseModel
+
+
+class Health(BaseModel):
+    """
+    Health check response body
+    """
+
+    version: str
+    status: str

mirix/schemas/knowledge_vault.py

@@ -0,0 +1,181 @@
+from datetime import datetime
+from typing import Any, Dict, List, Optional
+
+from pydantic import Field, field_validator
+
+from mirix.constants import MAX_EMBEDDING_DIM
+from mirix.schemas.embedding_config import EmbeddingConfig
+from mirix.schemas.mirix_base import MirixBase
+from mirix.utils import get_utc_time
+
+
+class KnowledgeVaultItemBase(MirixBase):
+    """
+    Base schema for knowledge vault items containing common fields.
+    """
+
+    __id_prefix__ = "kv_item"
+    entry_type: str = Field(
+        ..., description="Category (e.g., 'credential', 'bookmark', 'api_key')"
+    )
+    source: str = Field(..., description="Information on who/where it was provided")
+    sensitivity: str = Field(
+        ..., description="Data sensitivity level ('low', 'medium', 'high')"
+    )
+    secret_value: str = Field(..., description="The actual credential or data value")
+    caption: str = Field(
+        ...,
+        description="Description of the knowledge vault item (e.g. 'API key for OpenAI Service')",
+    )
+
+
+class KnowledgeVaultItem(KnowledgeVaultItemBase):
+    """
+    Representation of a knowledge vault item for storing credentials, bookmarks, etc.
+
+    Additional Parameters:
+        id (str): Unique ID for this knowledge vault entry.
+        created_at (datetime): Creation timestamp.
+        updated_at (Optional[datetime]): Last update timestamp.
+    """
+
+    id: Optional[str] = Field(
+        None, description="Unique identifier for the knowledge vault item"
+    )
+    agent_id: Optional[str] = Field(
+        None, description="The id of the agent this knowledge vault item belongs to"
+    )
+    user_id: str = Field(
+        ..., description="The id of the user who generated the knowledge vault item"
+    )
+    created_at: datetime = Field(
+        default_factory=get_utc_time,
+        description="The creation date of the knowledge vault item",
+    )
+    updated_at: Optional[datetime] = Field(
+        None, description="The last update date of the knowledge vault item"
+    )
+    last_modify: Dict[str, Any] = Field(
+        default_factory=lambda: {
+            "timestamp": get_utc_time().isoformat(),
+            "operation": "created",
+        },
+        description="Last modification info including timestamp and operation type",
+    )
+    organization_id: str = Field(
+        ..., description="The unique identifier of the organization"
+    )
+    caption_embedding: Optional[List[float]] = Field(
+        None, description="The embedding of the summary"
+    )
+    embedding_config: Optional[EmbeddingConfig] = Field(
+        None, description="The embedding configuration used by the event"
+    )
+    
+    # NEW: Filter tags for flexible filtering and categorization
+    filter_tags: Optional[Dict[str, Any]] = Field(
+        default=None,
+        description="Custom filter tags for filtering and categorization",
+        examples=[
+            {
+                "project_id": "proj-abc",
+                "session_id": "sess-xyz",
+                "tags": ["important", "work"],
+                "priority": "high"
+            }
+        ]
+    )
+
+    # need to validate both details_embedding and summary_embedding to ensure they are the same size    
+    # NEW: Filter tags for flexible filtering and categorization
+    filter_tags: Optional[Dict[str, Any]] = Field(
+        default=None,
+        description="Custom filter tags for filtering and categorization",
+        examples=[
+            {
+                "project_id": "proj-abc",
+                "session_id": "sess-xyz",
+                "tags": ["important", "work"],
+                "priority": "high"
+            }
+        ]
+    )
+
+    @field_validator("caption_embedding")
+    @classmethod
+    def pad_embeddings(cls, embedding: List[float]) -> List[float]:
+        """Pad embeddings to `MAX_EMBEDDING_SIZE`. This is necessary to ensure all stored embeddings are the same size."""
+        import numpy as np
+
+        if embedding and len(embedding) != MAX_EMBEDDING_DIM:
+            np_embedding = np.array(embedding)
+            padded_embedding = np.pad(
+                np_embedding,
+                (0, MAX_EMBEDDING_DIM - np_embedding.shape[0]),
+                mode="constant",
+            )
+            return padded_embedding.tolist()
+        return embedding
+
+
+class KnowledgeVaultItemCreate(KnowledgeVaultItemBase):
+    """
+    Schema for creating a new knowledge vault item.
+
+    Inherits all required fields from KnowledgeVaultItemBase.
+    """
+
+    pass
+
+
+class KnowledgeVaultItemUpdate(MirixBase):
+    """
+    Schema for updating an existing knowledge vault item.
+
+    All fields (except id) are optional so that only provided fields are updated.
+    """
+
+    id: str = Field(..., description="Unique ID for this knowledge vault entry")
+    agent_id: Optional[str] = Field(
+        None, description="The id of the agent this knowledge vault item belongs to"
+    )
+    entry_type: Optional[str] = Field(
+        None, description="Category (e.g., 'credential', 'bookmark', 'api_key')"
+    )
+    source: Optional[str] = Field(
+        None, description="Information on who/where it was provided"
+    )
+    sensitivity: Optional[str] = Field(
+        None, description="Data sensitivity level ('low', 'medium', 'high')"
+    )
+    secret_value: Optional[str] = Field(
+        None, description="The actual credential or data value"
+    )
+    organization_id: Optional[str] = Field(
+        None, description="The unique identifier of the organization"
+    )
+    updated_at: datetime = Field(
+        default_factory=get_utc_time, description="The update date"
+    )
+    last_modify: Optional[Dict[str, Any]] = Field(
+        None,
+        description="Last modification info including timestamp and operation type",
+    )
+    caption_embedding: Optional[List[float]] = Field(
+        None, description="The embedding of the summary"
+    )
+    embedding_config: Optional[EmbeddingConfig] = Field(
+        None, description="The embedding configuration used by the event"
+    )
+
+
+    filter_tags: Optional[Dict[str, Any]] = Field(
+        None, description="Custom filter tags for filtering and categorization"
+    )
+
+class KnowledgeVaultItemResponse(KnowledgeVaultItem):
+    """
+    Response schema for knowledge vault items with additional fields that might be needed by the API.
+    """
+
+    pass

mirix/schemas/llm_config.py

@@ -0,0 +1,187 @@
+from typing import Literal, Optional
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+from mirix.log import get_logger
+
+logger = get_logger(__name__)
+
+class LLMConfig(BaseModel):
+    """
+    Configuration for a Language Model (LLM) model. This object specifies all the information necessary to access an LLM model to usage with Letta, except for secret keys.
+
+    Attributes:
+        model (str): The name of the LLM model.
+        model_endpoint_type (str): The endpoint type for the model.
+        model_endpoint (str): The endpoint for the model.
+        model_wrapper (str): The wrapper for the model. This is used to wrap additional text around the input/output of the model. This is useful for text-to-text completions, such as the Completions API in OpenAI.
+        context_window (int): The context window size for the model.
+        temperature (float): The temperature to use when generating text with the model. A higher temperature will result in more random text.
+        max_tokens (int): The maximum number of tokens to generate.
+        api_key (str, optional): Custom API key for this specific model configuration.
+        api_version (str, optional): The API version for Azure OpenAI (e.g., '2024-10-01-preview').
+        azure_endpoint (str, optional): The Azure endpoint for the model (e.g., 'https://your-resource.openai.azure.com/').
+        azure_deployment (str, optional): The Azure deployment name for the model.
+    """
+
+    # TODO: 🤮 don't default to a vendor! bug city!
+    model: str = Field(..., description="LLM model name. ")
+    model_endpoint_type: Literal[
+        "openai",
+        "anthropic",
+        "cohere",
+        "google_ai",
+        "google_vertex",
+        "azure_openai",
+        "groq",
+        "ollama",
+        "webui",
+        "webui-legacy",
+        "lmstudio",
+        "lmstudio-legacy",
+        "lmstudio-chatcompletions",
+        "llamacpp",
+        "koboldcpp",
+        "vllm",
+        "hugging-face",
+        "mistral",
+        "together",  # completions endpoint
+        "bedrock",
+        "deepseek",
+        "xai",
+    ] = Field(..., description="The endpoint type for the model.")
+    model_endpoint: Optional[str] = Field(
+        None, description="The endpoint for the model."
+    )
+    model_wrapper: Optional[str] = Field(None, description="The wrapper for the model.")
+    context_window: int = Field(
+        ..., description="The context window size for the model."
+    )
+    handle: Optional[str] = Field(
+        None,
+        description="The handle for this config, in the format provider/model-name.",
+    )
+    temperature: float = Field(
+        0.7,
+        description="The temperature to use when generating text with the model. A higher temperature will result in more random text.",
+    )
+    max_tokens: Optional[int] = Field(
+        4096,
+        description="The maximum number of tokens to generate. If not set, the model will use its default value.",
+    )
+    enable_reasoner: bool = Field(
+        False,
+        description="Whether or not the model should use extended thinking if it is a 'reasoning' style model",
+    )
+    reasoning_effort: Optional[Literal["low", "medium", "high"]] = Field(
+        None,
+        description="The reasoning effort to use when generating text reasoning models",
+    )
+    max_reasoning_tokens: int = Field(
+        0,
+        description="Configurable thinking budget for extended thinking, only used if enable_reasoner is True. Minimum value is 1024.",
+    )
+    api_key: Optional[str] = Field(
+        None,
+        description="Custom API key for this specific model configuration (used for custom models)",
+    )
+
+    # Azure-specific fields (Azure OpenAI only)
+    api_version: Optional[str] = Field(
+        None,
+        description="The API version for Azure OpenAI (e.g., '2024-10-01-preview')",
+    )
+    azure_endpoint: Optional[str] = Field(
+        None,
+        description="The Azure endpoint for the model (e.g., 'https://your-resource.openai.azure.com/')",
+    )
+    azure_deployment: Optional[str] = Field(
+        None, description="The Azure deployment name for the model"
+    )
+
+    # FIXME hack to silence pydantic protected namespace warning
+    model_config = ConfigDict(protected_namespaces=())
+
+    @model_validator(mode="before")
+    @classmethod
+    def set_default_enable_reasoner(cls, values):
+        if any(
+            openai_reasoner_model in values.get("model", "")
+            for openai_reasoner_model in ["o3-mini", "o1"]
+        ):
+            values["enable_reasoner"] = True
+        return values
+
+    @model_validator(mode="after")
+    def issue_warning_for_reasoning_constraints(self) -> "LLMConfig":
+        if self.enable_reasoner:
+            if self.max_reasoning_tokens is None:
+                logger.warning(
+                    "max_reasoning_tokens must be set when enable_reasoner is True"
+                )
+            if (
+                self.max_tokens is not None
+                and self.max_reasoning_tokens >= self.max_tokens
+            ):
+                logger.warning(
+                    "max_tokens must be greater than max_reasoning_tokens (thinking budget)"
+                )
+        elif self.max_reasoning_tokens and not self.enable_reasoner:
+            logger.warning(
+                "model will not use reasoning unless enable_reasoner is set to True"
+            )
+
+        return self
+
+    @classmethod
+    def default_config(cls, model_name: str):
+        """
+        Convenience function to generate a default `LLMConfig` from a model name. Only some models are supported in this function.
+
+        Args:
+            model_name (str): The name of the model (gpt-4, gpt-4o-mini, letta).
+        """
+        if model_name == "gpt-4":
+            return cls(
+                model="gpt-4",
+                model_endpoint_type="openai",
+                model_endpoint="https://api.openai.com/v1",
+                model_wrapper=None,
+                context_window=8192,
+            )
+        elif model_name == "gpt-4o-mini":
+            return cls(
+                model="gpt-4o-mini",
+                model_endpoint_type="openai",
+                model_endpoint="https://api.openai.com/v1",
+                model_wrapper=None,
+                context_window=128000,
+            )
+        elif model_name == "gpt-4o":
+            return cls(
+                model="gpt-4o",
+                model_endpoint_type="openai",
+                model_endpoint="https://api.openai.com/v1",
+                model_wrapper=None,
+                context_window=128000,
+            )
+        elif model_name == "letta":
+            return cls(
+                model="memgpt-openai",
+                model_endpoint_type="openai",
+                model_endpoint="https://inference.memgpt.ai",
+                context_window=8192,
+            )
+        else:
+            raise ValueError(f"Model {model_name} not supported.")
+
+    def pretty_print(self) -> str:
+        return (
+            f"{self.model}"
+            + (
+                f" [type={self.model_endpoint_type}]"
+                if self.model_endpoint_type
+                else ""
+            )
+            + (f" [ip={self.model_endpoint}]" if self.model_endpoint else "")
+        )