MemoryOS 2.0.3__py3-none-any.whl

memos/templates/tool_mem_prompts.py

@@ -0,0 +1,139 @@
+TOOL_TRAJECTORY_PROMPT_ZH = """
+你是一个专业的工具经验提取专家。你的任务是从给定的对话消息中提取完整的工具调用轨迹经验。
+
+## 分析判断步骤：
+**步骤1：判断任务完成度**
+根据用户反馈，判定correctness：success（成功）或 failed（失败），用户反馈决定权大于执行结果，用户反馈有误，则判定为failed
+
+**步骤2：成功轨迹（success）- 经验提炼**
+从成功模式中提炼通用原则或规则，采用"when...then..."结构：
+- when: 明确描述触发该经验的场景特征（任务类型、工具环境、参数特征等）
+- then: 总结有效的参数模式、调用策略、最佳实践
+注意：经验是解决整个轨迹问题级别的，不仅仅针对单个工具
+
+**步骤3：失败轨迹（failed）- 错误分析与经验提炼**
+3.1 工具需求判断
+  - 任务是否需要工具？（需要/直接回答/误调用）
+3.2 工具调用检查
+  - 工具存在性：是否在system中提供
+  - 工具选择：是否选对工具
+  - 参数正确性：是否符合类型定义
+  - 幻觉检测：是否调用不存在的工具
+3.3 错误根因定位
+  结合消息中的错误反馈信息和上述分析，精准输出根本原因
+3.4 经验提炼（核心）
+  从失败模式中提炼通用原则或规则，采用"when...then..."结构：
+  - when: 明确描述触发该经验的场景特征（任务类型、工具环境、参数特征等）
+  - then: 给出避免错误的通用策略、正确调用方式或决策规则
+  注意：经验是解决整个轨迹问题级别的，不仅仅针对单个工具
+
+## 输出格式：
+返回一个JSON数组，格式如下：
+
+```json
+[
+  {
+    "correctness": "success 或 failed",
+    "trajectory": "精炼完整的自然语言总结，包含：[任务（用户任务） -> 执行动作（调用的工具/直接回答） -> 执行结果] (可能多轮) -> 最终回答",
+    "experience": "采用when...then...格式，例如：'when 遇到XX的任务时，应该YY'",
+    "tool_used_status": [
+      {
+        "used_tool": "工具名称（如果调用了工具）",
+        "success_rate": "0.0-1.0之间的数值，表示该工具在本次轨迹中的成功率",
+        "error_type": "调用失败时的错误类型和描述，成功时为空字符串",
+        "tool_experience": "调用该工具的经验，包括可能的前置条件和可能的后置效果"
+      }
+    ]
+  }
+]
+```
+
+## 注意事项：
+- 每个轨迹必须是独立的完整过程
+- 一个轨迹中可能涉及多个工具的使用，每个工具在tool_used_status中独立记录
+- 如果没有调用工具，tool_used_status为空数组[]
+- 如果多条轨迹存在顺序依赖关系，需要将它们视为一条轨迹
+- 只提取事实内容，不要添加任何解释或额外信息
+- 确保返回的是有效的JSON格式
+- 输出的trajectory需要按照messages的发展顺序排列
+- experience必须是通用的、可复用的经验规则，而不是针对具体案例的描述
+- 无论成功或失败，都要提炼经验并使用when...then...格式
+
+请分析以下对话消息并提取工具调用轨迹，基于以下对话消息：
+<messages>
+{messages}
+</messages>
+"""
+
+
+TOOL_TRAJECTORY_PROMPT_EN = """
+You are a professional tool experience extraction expert. Your task is to extract complete tool call trajectory experiences from given conversation messages.
+
+## Analysis and Judgment Steps:
+
+**Step 1: Assess Task Completion**
+Determine correctness based on user feedback: success or failed, user feedback has higher priority than execution results, if user feedback is incorrect, then determine as failed
+
+**Step 2: Successful Trajectory (success) - Experience Extraction**
+Extract general principles or rules from success patterns, using "when...then..." structure:
+- when: clearly describe the scenario characteristics that trigger this experience (task type, tool environment, parameter characteristics, etc.)
+- then: summarize effective parameter patterns, calling strategies, and best practices
+Note: Experience is at the trajectory-level problem-solving, not just for a single tool
+
+**Step 3: Failed Trajectory (failed) - Error Analysis and Experience Extraction**
+
+3.1 Tool Requirement Assessment
+  - Does the task require tools? (required/direct answer/unnecessary call)
+
+3.2 Tool Call Verification
+  - Tool availability: provided in system?
+  - Tool selection: correct tool chosen?
+  - Parameter correctness: conform to type definitions?
+  - Hallucination detection: calling non-existent tools?
+
+3.3 Root Cause Identification
+  Combine error feedback from messages with above analysis to precisely output root cause
+
+3.4 Experience Extraction (Core)
+  Extract general principles or rules from failure patterns, using "when...then..." structure:
+  - when: clearly describe the scenario characteristics that trigger this experience (task type, tool environment, parameter characteristics, etc.)
+  - then: provide general strategies to avoid errors, correct calling approaches, or decision rules
+  Note: Experience is at the trajectory-level problem-solving, not just for a single tool
+
+## Output Format:
+Return a JSON array in the following format:
+
+```json
+[
+  {
+    "correctness": "success or failed",
+    "trajectory": "Concise and complete natural language summary including: [task (user task) -> execution action (tool called/direct answer) -> execution result] (possibly multiple rounds) -> final answer",
+    "experience": "Use when...then... format, e.g., 'when encountering XX tasks, should do YY'",
+    "tool_used_status": [
+      {
+        "used_tool": "Tool name (if tool was called)",
+        "success_rate": "Numerical value between 0.0-1.0, indicating the success rate of this tool in current trajectory",
+        "error_type": "Error type and description when call fails, empty string when successful",
+        "tool_experience": "Experience of using this tool, including possible preconditions and possible post-effects"
+      }
+    ]
+  }
+]
+```
+
+## Notes:
+- Each trajectory must be an independent complete process
+- A trajectory may involve multiple tools, each recorded independently in tool_used_status
+- If no tool was called, tool_used_status is an empty array []
+- If multiple trajectories have sequential dependencies, treat them as one trajectory
+- Only extract factual content, do not add any explanations or extra information
+- Ensure the returned content is valid JSON format
+- The trajectory should be arranged according to the development order of messages
+- Experience must be general and reusable rules, not descriptions specific to concrete cases
+- Whether success or failed, always extract experience using when...then... format
+
+Please analyze the following conversation messages and extract tool call trajectories based on:
+<messages>
+{messages}
+</messages>
+"""

memos/templates/tree_reorganize_prompts.py

@@ -0,0 +1,230 @@
+REORGANIZE_PROMPT = """You are a memory clustering and summarization expert.
+
+Given the following child memory items:
+
+{memory_items_text}
+
+Please perform:
+1. Identify information that reflects user's experiences, beliefs, concerns, decisions, plans, or reactions — including meaningful input from assistant that user acknowledged or responded to.
+2. Resolve all time, person, and event references clearly:
+   - Convert relative time expressions (e.g., “yesterday,” “next Friday”) into absolute dates using the message timestamp if possible.
+   - Clearly distinguish between event time and message time.
+   - If uncertainty exists, state it explicitly (e.g., “around June 2025,” “exact date unclear”).
+   - Include specific locations if mentioned.
+   - Resolve all pronouns, aliases, and ambiguous references into full names or identities.
+   - Disambiguate people with the same name if applicable.
+3. Always write from a third-person perspective, referring to user as
+"The user" or by name if name mentioned, rather than using first-person ("I", "me", "my").
+For example, write "The user felt exhausted..." instead of "I felt exhausted...".
+4. Do not omit any information that user is likely to remember.
+   - Include all key experiences, thoughts, emotional responses, and plans — even if they seem minor.
+   - Prioritize completeness and fidelity over conciseness.
+   - Do not generalize or skip details that could be personally meaningful to user.
+5. Summarize all child memory items into one memory item.
+
+Language rules:
+- The `key`, `value`, `tags`, `summary` fields must match the mostly used language of the input memory items.  **如果输入是中文，请输出中文**
+- Keep `memory_type` in English.
+
+Return valid JSON:
+{
+  "key": <string, a concise title of the `value` field>,
+  "memory_type": <string, Either "LongTermMemory" or "UserMemory">,
+  "value": <A detailed, self-contained, and unambiguous memory statement, only contain detailed, unaltered information extracted and consolidated from the input `value` fields, do not include summary content — written in English if the input memory items are in English, or in Chinese if the input is in Chinese>,
+  "tags": <A list of relevant thematic keywords (e.g., ["deadline", "team", "planning"])>,
+  "summary": <a natural paragraph summarizing the above memories from user's perspective, only contain information from the input `summary` fields, 120–200 words, same language as the input>
+}
+
+"""
+
+DOC_REORGANIZE_PROMPT = """You are a document summarization and knowledge extraction expert.
+
+Given the following summarized document items:
+
+{memory_items_text}
+
+Please perform:
+1. Identify key information that reflects factual content, insights, decisions, or implications from the documents — including any notable themes, conclusions, or data points.
+2. Resolve all time, person, location, and event references clearly:
+   - Convert relative time expressions (e.g., “last year,” “next quarter”) into absolute dates if context allows.
+   - Clearly distinguish between event time and document time.
+   - If uncertainty exists, state it explicitly (e.g., “around 2024,” “exact date unclear”).
+   - Include specific locations if mentioned.
+   - Resolve all pronouns, aliases, and ambiguous references into full names or identities.
+   - Disambiguate entities with the same name if applicable.
+3. Always write from a third-person perspective, referring to the subject or content clearly rather than using first-person ("I", "me", "my").
+4. Do not omit any information that is likely to be important or memorable from the document summaries.
+   - Include all key facts, insights, emotional tones, and plans — even if they seem minor.
+   - Prioritize completeness and fidelity over conciseness.
+   - Do not generalize or skip details that could be contextually meaningful.
+5. Summarize all document summaries into one integrated memory item.
+
+Language rules:
+- The `key`, `value`, `tags`, `summary` fields must match the mostly used language of the input document summaries.  **如果输入是中文，请输出中文**
+- Keep `memory_type` in English.
+
+Return valid JSON:
+{
+  "key": <string, a concise title of the `value` field>,
+  "memory_type": "LongTermMemory",
+  "value": <A detailed, self-contained, and unambiguous memory statement, only contain detailed, unaltered information extracted and consolidated from the input `value` fields, do not include summary content — written in English if the input memory items are in English, or in Chinese if the input is in Chinese>,
+  "tags": <A list of relevant thematic keywords (e.g., ["deadline", "team", "planning"])>,
+  "summary": <a natural paragraph summarizing the above memories from user's perspective, only contain information from the input `summary` fields, 120–200 words, same language as the input>
+}
+
+"""
+
+
+LOCAL_SUBCLUSTER_PROMPT = """You are a memory organization expert.
+
+You are given a cluster of memory items, each with an ID and content.
+Your task is to divide these into smaller, semantically meaningful sub-clusters.
+
+Instructions:
+- Identify natural topics by analyzing common time, place, people, and event elements.
+- Each sub-cluster must reflect a coherent theme that helps retrieval.
+- Each sub-cluster should have 2–10 items. Discard singletons.
+- Each item ID must appear in exactly one sub-cluster or be discarded. No duplicates are allowed.
+- All IDs in the output must be from the provided Memory items.
+- Return strictly valid JSON only.
+
+Example: If you have items about a project across multiple phases, group them by milestone, team, or event.
+
+Language rules:
+- The `key` fields must match the mostly used language of the clustered memories. **如果输入是中文，请输出中文**
+
+Return valid JSON:
+{
+  "clusters": [
+    {
+      "ids": ["<id1>", "<id2>", ...],
+      "key": "<string, a unique, concise memory title>"
+    },
+    ...
+  ]
+}
+
+Memory items:
+{joined_scene}
+"""
+
+PAIRWISE_RELATION_PROMPT = """
+You are a reasoning assistant.
+
+Given two memory units:
+- Node 1: "{node1}"
+- Node 2: "{node2}"
+
+Your task:
+- Determine their relationship ONLY if it reveals NEW usable reasoning or retrieval knowledge that is NOT already explicit in either unit.
+- Focus on whether combining them adds new temporal, causal, conditional, or conflict information.
+
+Valid options:
+- CAUSE: One clearly leads to the other.
+- CONDITION: One happens only if the other condition holds.
+- RELATE: They are semantically related by shared people, time, place, or event, but neither causes the other.
+- CONFLICT: They logically contradict each other.
+- NONE: No clear useful connection.
+
+Example:
+- Node 1: "The marketing campaign ended in June."
+- Node 2: "Product sales dropped in July."
+Answer: CAUSE
+
+Another Example:
+- Node 1: "The conference was postponed to August due to the venue being unavailable."
+- Node 2: "The venue was booked for a wedding in August."
+Answer: CONFLICT
+
+Always respond with ONE word, no matter what language is for the input nodes: [CAUSE | CONDITION | RELATE | CONFLICT | NONE]
+"""
+
+INFER_FACT_PROMPT = """
+You are an inference expert.
+
+Source Memory: "{source}"
+Target Memory: "{target}"
+
+They are connected by a {relation_type} relation.
+Derive ONE new factual statement that clearly combines them in a way that is NOT a trivial restatement.
+
+Requirements:
+- Include relevant time, place, people, and event details if available.
+- If the inference is a logical guess, explicitly use phrases like "It can be inferred that...".
+
+Example:
+Source: "John missed the team meeting on Monday."
+Target: "Important project deadlines were discussed in that meeting."
+Relation: CAUSE
+Inference: "It can be inferred that John may not know the new project deadlines."
+
+If there is NO new useful fact that combines them, reply exactly: "None"
+"""
+
+AGGREGATE_PROMPT = """
+You are a concept summarization assistant.
+
+Below is a list of memory items:
+{joined}
+
+Your task:
+- Identify if they can be meaningfully grouped under a new, higher-level concept that clarifies their shared time, place, people, or event context.
+- Do NOT aggregate if the overlap is trivial or obvious from each unit alone.
+- If the summary involves any plausible interpretation, explicitly note it (e.g., "This suggests...").
+
+Example:
+Input Memories:
+- "Mary organized the 2023 sustainability summit in Berlin."
+- "Mary presented a keynote on renewable energy at the same summit."
+
+Language rules:
+- The `key`, `value`, `tags`, `background` fields must match the language of the input.
+
+Good Aggregate:
+{
+  "key": "Mary's Sustainability Summit Role",
+  "value": "Mary organized and spoke at the 2023 sustainability summit in Berlin, highlighting renewable energy initiatives.",
+  "tags": ["Mary", "summit", "Berlin", "2023"],
+  "background": "Combined from multiple memories about Mary's activities at the summit."
+}
+
+If you find NO useful higher-level concept, reply exactly: "None".
+"""
+
+REDUNDANCY_MERGE_PROMPT = """You are given two pieces of text joined by the marker `⟵MERGED⟶`. Please carefully read both sides of the merged text. Your task is to summarize and consolidate all the factual details from both sides into a single, coherent text, without omitting any information. You must include every distinct detail mentioned in either text. Do not provide any explanation or analysis — only return the merged summary. Don't use pronouns or subjective language, just the facts as they are presented.\n{merged_text}"""
+
+
+MEMORY_RELATION_DETECTOR_PROMPT = """You are a memory relationship analyzer.
+You are given two plaintext statements. Determine the relationship between them. Classify the relationship into one of the following categories:
+
+contradictory: The two statements describe the same event or related aspects of it but contain factually conflicting details.
+redundant: The two statements describe essentially the same event or information with significant overlap in content and details, conveying the same core information (even if worded differently).
+independent: The two statements are either about different events/topics (unrelated) OR describe different, non-overlapping aspects or perspectives of the same event without conflict (complementary). In both sub-cases, they provide distinct information without contradiction.
+Respond only with one of the three labels: contradictory, redundant, or independent.
+Do not provide any explanation or additional text.
+
+Statement 1: {statement_1}
+Statement 2: {statement_2}
+"""
+
+
+MEMORY_RELATION_RESOLVER_PROMPT = """You are a memory fusion expert. You are given two statements and their associated metadata. The statements have been identified as {relation}. Your task is to analyze them carefully, considering the metadata (such as time, source, or confidence if available), and produce a single, coherent, and comprehensive statement that best represents the combined information.
+
+If the statements are redundant, merge them by preserving all unique details and removing duplication, forming a richer, consolidated version.
+If the statements are contradictory, attempt to resolve the conflict by prioritizing more recent information, higher-confidence data, or logically reconciling the differences based on context. If the contradiction is fundamental and cannot be logically resolved, output <answer>No</answer>.
+Do not include any explanations, reasoning, or extra text. Only output the final result enclosed in <answer></answer> tags.
+Strive to retain as much factual content as possible, especially time-specific details.
+Use objective language and avoid pronouns.
+Output Example 1 (unresolvable conflict):
+<answer>No</answer>
+
+Output Example 2 (successful fusion):
+<answer>The meeting took place on 2023-10-05 at 14:00 in the main conference room, as confirmed by the updated schedule, and included a presentation on project milestones followed by a Q&A session.</answer>
+
+Now, reconcile the following two statements:
+Relation Type: {relation}
+Statement 1: {statement_1}
+Metadata 1: {metadata_1}
+Statement 2: {statement_2}
+Metadata 2: {metadata_2}
+"""

memos/types/__init__.py

@@ -0,0 +1,34 @@
+from .general_types import (
+    FINE_STRATEGY,
+    ChatHistory,
+    FineStrategy,
+    MemCubeID,
+    MessageDict,
+    MessageList,
+    MessageRole,
+    MessagesType,
+    MOSSearchResult,
+    Permission,
+    PermissionDict,
+    SearchMode,
+    UserContext,
+    UserID,
+)
+
+
+__all__ = [
+    "FINE_STRATEGY",
+    "ChatHistory",
+    "FineStrategy",
+    "MOSSearchResult",
+    "MemCubeID",
+    "MessageDict",
+    "MessageList",
+    "MessageRole",
+    "MessagesType",
+    "Permission",
+    "PermissionDict",
+    "SearchMode",
+    "UserContext",
+    "UserID",
+]

memos/types/general_types.py

@@ -0,0 +1,151 @@
+"""Type definitions and custom types for the MemOS library.
+
+This module defines commonly used type aliases, protocols, and custom types
+used throughout the MemOS project to improve type safety and code clarity.
+"""
+
+import os
+
+from datetime import datetime
+from enum import Enum
+from typing import Literal, NewType, TypeAlias
+
+from pydantic import BaseModel
+from typing_extensions import TypedDict
+
+from memos.memories.activation.item import ActivationMemoryItem
+from memos.memories.parametric.item import ParametricMemoryItem
+from memos.memories.textual.item import TextualMemoryItem
+
+from .openai_chat_completion_types import (
+    ChatCompletionContentPartTextParam,
+    ChatCompletionMessageParam,
+    File,
+)
+
+
+__all__ = [
+    "FINE_STRATEGY",
+    "ChatHistory",
+    "FineStrategy",
+    "MOSSearchResult",
+    "MemCubeID",
+    "MessageDict",
+    "MessageList",
+    "MessageRole",
+    "MessagesType",
+    "Permission",
+    "PermissionDict",
+    "SearchMode",
+    "UserContext",
+    "UserID",
+]
+
+# ─── Message Types ──────────────────────────────────────────────────────────────
+
+# Chat message roles
+MessageRole: TypeAlias = Literal["user", "assistant", "system"]
+
+
+# Message structure
+class MessageDict(TypedDict, total=False):
+    """Typed dictionary for chat message dictionaries."""
+
+    role: MessageRole
+    content: str
+    chat_time: str | None  # Optional timestamp for the message, format is not
+    # restricted, it can be any vague or precise time string.
+    message_id: str | None  # Optional unique identifier for the message
+
+
+RawMessageDict: TypeAlias = ChatCompletionContentPartTextParam | File
+
+
+# Message collections
+MessageList: TypeAlias = list[ChatCompletionMessageParam]
+RawMessageList: TypeAlias = list[RawMessageDict]
+
+
+# Messages Type
+MessagesType: TypeAlias = str | MessageList | RawMessageList
+
+
+# Chat history structure
+class ChatHistory(BaseModel):
+    """Model to represent chat history for export."""
+
+    user_id: str
+    session_id: str
+    created_at: datetime
+    total_messages: int
+    chat_history: MessageList
+
+
+# ─── Search ────────────────────────────────────────────────────────────────────
+# new types
+UserID = NewType("UserID", str)
+MemCubeID = NewType("CubeID", str)
+
+
+class SearchMode(str, Enum):
+    """Enumeration for search modes."""
+
+    FAST = "fast"
+    FINE = "fine"
+    MIXTURE = "mixture"
+
+
+class FineStrategy(str, Enum):
+    """Enumeration for fine strategies."""
+
+    REWRITE = "rewrite"
+    RECREATE = "recreate"
+    DEEP_SEARCH = "deep_search"
+    AGENTIC_SEARCH = "agentic_search"
+
+
+# algorithm strategies
+DEFAULT_FINE_STRATEGY = FineStrategy.RECREATE
+FINE_STRATEGY = DEFAULT_FINE_STRATEGY
+
+# Read fine strategy from environment variable `FINE_STRATEGY`.
+# If provided and valid, use it; otherwise fall back to default.
+_env_fine_strategy = os.getenv("FINE_STRATEGY")
+if _env_fine_strategy:
+    try:
+        FINE_STRATEGY = FineStrategy(_env_fine_strategy)
+    except ValueError:
+        FINE_STRATEGY = DEFAULT_FINE_STRATEGY
+
+
+# ─── MemOS ────────────────────────────────────────────────────────────────────
+
+
+class MOSSearchResult(TypedDict):
+    """Model to represent memory search result."""
+
+    text_mem: list[dict[str, str | list[TextualMemoryItem]]]
+    act_mem: list[dict[str, str | list[ActivationMemoryItem]]]
+    para_mem: list[dict[str, str | list[ParametricMemoryItem]]]
+
+
+# ─── API Types ────────────────────────────────────────────────────────────────────
+# for API Permission
+Permission: TypeAlias = Literal["read", "write", "delete", "execute"]
+
+
+# Message structure
+class PermissionDict(TypedDict, total=False):
+    """Typed dictionary for chat message dictionaries."""
+
+    permissions: list[Permission]
+    mem_cube_id: str
+
+
+class UserContext(BaseModel):
+    """Model to represent user context."""
+
+    user_id: str | None = None
+    mem_cube_id: str | None = None
+    session_id: str | None = None
+    operation: list[PermissionDict] | None = None

memos/types/openai_chat_completion_types/__init__.py

@@ -0,0 +1,15 @@
+# ruff: noqa: F403, F401
+
+from .chat_completion_assistant_message_param import *
+from .chat_completion_content_part_image_param import *
+from .chat_completion_content_part_input_audio_param import *
+from .chat_completion_content_part_param import *
+from .chat_completion_content_part_refusal_param import *
+from .chat_completion_content_part_text_param import *
+from .chat_completion_message_custom_tool_call_param import *
+from .chat_completion_message_function_tool_call_param import *
+from .chat_completion_message_param import *
+from .chat_completion_message_tool_call_union_param import *
+from .chat_completion_system_message_param import *
+from .chat_completion_tool_message_param import *
+from .chat_completion_user_message_param import *

memos/types/openai_chat_completion_types/chat_completion_assistant_message_param.py

@@ -0,0 +1,56 @@
+# ruff: noqa: TC001, TC003
+
+from __future__ import annotations
+
+from typing import Literal, TypeAlias
+
+from typing_extensions import Required, TypedDict
+
+from .chat_completion_content_part_refusal_param import ChatCompletionContentPartRefusalParam
+from .chat_completion_content_part_text_param import ChatCompletionContentPartTextParam
+from .chat_completion_message_tool_call_union_param import ChatCompletionMessageToolCallUnionParam
+
+
+__all__ = ["Audio", "ChatCompletionAssistantMessageParam", "ContentArrayOfContentPart"]
+
+
+class Audio(TypedDict, total=False):
+    id: Required[str]
+    """Unique identifier for a previous audio response from the model."""
+
+
+ContentArrayOfContentPart: TypeAlias = (
+    ChatCompletionContentPartTextParam | ChatCompletionContentPartRefusalParam
+)
+
+
+class ChatCompletionAssistantMessageParam(TypedDict, total=False):
+    role: Required[Literal["assistant"]]
+    """The role of the messages author, in this case `assistant`."""
+
+    audio: Audio | None
+    """
+    Data about a previous audio response from the model.
+    [Learn more](https://platform.openai.com/docs/guides/audio).
+    """
+
+    content: str | list[ContentArrayOfContentPart] | ContentArrayOfContentPart | None
+    """The contents of the assistant message.
+
+    Required unless `tool_calls` or `function_call` is specified.
+    """
+
+    refusal: str | None
+    """The refusal message by the assistant."""
+
+    tool_calls: (
+        list[ChatCompletionMessageToolCallUnionParam] | ChatCompletionMessageToolCallUnionParam
+    )
+    """The tool calls generated by the model, such as function calls."""
+
+    chat_time: str | None
+    """Optional timestamp for the message, format is not
+    restricted, it can be any vague or precise time string."""
+
+    message_id: str | None
+    """Optional unique identifier for the message"""

memos/types/openai_chat_completion_types/chat_completion_content_part_image_param.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+from typing import Literal
+
+from typing_extensions import Required, TypedDict
+
+
+__all__ = ["ChatCompletionContentPartImageParam", "ImageURL"]
+
+
+class ImageURL(TypedDict, total=False):
+    url: Required[str]
+    """Either a URL of the image or the base64 encoded image data."""
+
+    detail: Literal["auto", "low", "high"]
+    """Specifies the detail level of the image.
+
+    Learn more in the
+    [Vision guide](https://platform.openai.com/docs/guides/vision#low-or-high-fidelity-image-understanding).
+    """
+
+
+class ChatCompletionContentPartImageParam(TypedDict, total=False):
+    image_url: Required[ImageURL]
+
+    type: Required[Literal["image_url"]]
+    """The type of the content part."""

memos/types/openai_chat_completion_types/chat_completion_content_part_input_audio_param.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+from typing import Literal
+
+from typing_extensions import Required, TypedDict
+
+
+__all__ = ["ChatCompletionContentPartInputAudioParam", "InputAudio"]
+
+
+class InputAudio(TypedDict, total=False):
+    data: Required[str]
+    """Base64 encoded audio data."""
+
+    format: Required[Literal["wav", "mp3"]]
+    """The format of the encoded audio data. Currently supports "wav" and "mp3"."""
+
+
+class ChatCompletionContentPartInputAudioParam(TypedDict, total=False):
+    input_audio: Required[InputAudio]
+
+    type: Required[Literal["input_audio"]]
+    """The type of the content part. Always `input_audio`."""