agent-framework-dxmt 1.6.0__py3-none-any.whl

agent_framework_dxmt/__init__.py

@@ -0,0 +1,14 @@
+"""DXMT for Microsoft Agent Framework: a vector store, and memory as a context provider."""
+
+import importlib.metadata
+
+from ._context_provider import DXMTContextProvider
+from ._settings import DXMTSettings
+from ._vector_store import DXMTCollection, DXMTStore
+
+try:
+    __version__ = importlib.metadata.version("agent-framework-dxmt")
+except importlib.metadata.PackageNotFoundError:
+    __version__ = "0.0.0"
+
+__all__ = ["DXMTCollection", "DXMTContextProvider", "DXMTSettings", "DXMTStore", "__version__"]

agent_framework_dxmt/_context_provider.py

@@ -0,0 +1,203 @@
+"""DXMT memory as an Agent Framework context provider.
+
+Before a run, the user's input is sent to DXMT's ``recall`` (hybrid: by meaning and by
+keyword) and the memories come back into the context under a short heading; after a run,
+the user and assistant messages are kept with ``remember``. Scope is tags: a memory is
+tagged with the ``user_id``, ``agent_id`` and ``application_id`` it was written under, and
+recall asks for the ``search_*`` ids -- kept separate from the storage scope, as the mem0
+provider keeps them, so a memory written under a shared agent id is not read back for an
+unrelated user unless ``search_agent_id`` says so.
+
+DXMT's memory semantics come along: a memory said twice is kept once, a new fact can
+``supersede`` an old one (kept as history, left out of recall), and ``forget`` removes on
+request. The same store is reachable from every other agent on the machine over MCP and REST.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, Any, ClassVar, Self
+
+from agent_framework import AgentSession, ContextProvider, Message, SecretString, SessionContext
+from dxmt import DXMTClient
+from dxmt.exceptions import DXMTError
+
+from ._settings import _resolve_client
+
+if TYPE_CHECKING:
+    from agent_framework._agents import SupportsAgentRun
+
+logger = logging.getLogger(__name__)
+
+
+class DXMTContextProvider(ContextProvider):
+    """Recall DXMT memories before a run and remember the exchange after it."""
+
+    DEFAULT_CONTEXT_PROMPT = "## Memories\nConsider the following memories when answering user questions:"
+    DEFAULT_SOURCE_ID: ClassVar[str] = "dxmt"
+
+    def __init__(
+        self,
+        source_id: str = DEFAULT_SOURCE_ID,
+        *,
+        client: DXMTClient | None = None,
+        url: str | None = None,
+        api_key: str | SecretString | None = None,
+        managed_client: bool | None = None,
+        env_file_path: str | None = None,
+        env_file_encoding: str | None = None,
+        application_id: str | None = None,
+        agent_id: str | None = None,
+        user_id: str | None = None,
+        search_application_id: str | None = None,
+        search_agent_id: str | None = None,
+        search_user_id: str | None = None,
+        context_prompt: str | None = None,
+        limit: int = 10,
+        kind: str | None = None,
+        store_user_messages: bool = True,
+        store_assistant_messages: bool = True,
+    ) -> None:
+        """Initialize the provider.
+
+        Args:
+            source_id: Identifier of this provider in the session context.
+            client: Existing ``DXMTClient``; otherwise one is built from ``url`` / ``api_key`` /
+                ``DXMT_URL`` / ``DXMT_API_KEY`` and closed with the provider.
+            url, api_key, managed_client, env_file_path, env_file_encoding: As on ``DXMTCollection``.
+            application_id, agent_id, user_id: The storage scope, stamped as tags on every memory written.
+            search_application_id, search_agent_id, search_user_id: The retrieval scope. Memories
+                carrying any of these tags are recalled; none set means nothing is recalled.
+            context_prompt: Heading placed above the recalled memories.
+            limit: How many memories to recall per run.
+            kind: Memory kind to write (``fact``, ``preference``, ``event``, ``instruction``, ``note``);
+                default lets the server file user turns as ``note``.
+            store_user_messages, store_assistant_messages: Which sides of the exchange to remember.
+        """
+        super().__init__(source_id)
+        resolved, owns = _resolve_client(
+            client,
+            url=url,
+            api_key=api_key,
+            managed_client=managed_client,
+            env_file_path=env_file_path,
+            env_file_encoding=env_file_encoding,
+        )
+        self.client = resolved
+        self.managed_client = owns
+        self.application_id = application_id
+        self.agent_id = agent_id
+        self.user_id = user_id
+        self.search_application_id = search_application_id
+        self.search_agent_id = search_agent_id
+        self.search_user_id = search_user_id
+        self.context_prompt = context_prompt or self.DEFAULT_CONTEXT_PROMPT
+        self.limit = limit
+        self.kind = kind
+        self.store_user_messages = store_user_messages
+        self.store_assistant_messages = store_assistant_messages
+        self._warned_no_search_scope = False
+        self._closed = False
+        if not (application_id or agent_id or user_id):
+            raise ValueError("At least one of application_id, agent_id or user_id is required to scope memories.")
+
+    # ---- scope as tags --------------------------------------------------------------
+
+    @staticmethod
+    def _tags(application_id: str | None, agent_id: str | None, user_id: str | None) -> list[str]:
+        tags = []
+        if user_id:
+            tags.append(f"user:{user_id}")
+        if agent_id:
+            tags.append(f"agent:{agent_id}")
+        if application_id:
+            tags.append(f"app:{application_id}")
+        return tags
+
+    @property
+    def storage_tags(self) -> list[str]:
+        return self._tags(self.application_id, self.agent_id, self.user_id)
+
+    @property
+    def search_tags(self) -> list[str]:
+        return self._tags(self.search_application_id, self.search_agent_id, self.search_user_id)
+
+    # ---- hooks -----------------------------------------------------------------------
+
+    async def before_run(
+        self, *, agent: SupportsAgentRun, session: AgentSession, context: SessionContext, state: dict[str, Any]
+    ) -> None:
+        tags = self.search_tags
+        if not tags:
+            if not self._warned_no_search_scope:
+                self._warned_no_search_scope = True
+                logger.warning(
+                    "DXMTContextProvider has no retrieval scope, so no memories will be recalled. "
+                    "Set search_user_id, search_agent_id and/or search_application_id."
+                )
+            return
+        query = "\n".join(m.text for m in context.input_messages if m and m.text and m.text.strip())
+        if not query.strip():
+            return
+        try:
+            memories = await self.client.arecall(query, limit=self.limit, tags=tags)
+        except DXMTError as exc:
+            logger.error("DXMT recall failed: %s", exc)
+            return
+        lines = [str(m.get("text", "")) for m in memories if m.get("text")]
+        if lines:
+            context.extend_messages(
+                self.source_id, [Message(role="user", contents=[f"{self.context_prompt}\n" + "\n".join(lines)])]
+            )
+
+    async def after_run(
+        self, *, agent: SupportsAgentRun, session: AgentSession, context: SessionContext, state: dict[str, Any]
+    ) -> None:
+        messages: list[Message] = list(context.input_messages)
+        if context.response and context.response.messages:
+            messages.extend(context.response.messages)
+        tags = self.storage_tags
+        source = f"session:{session.session_id}" if session.session_id else self.agent_id or self.source_id
+        for message in messages:
+            role = message.role.value if hasattr(message.role, "value") else str(message.role)
+            if not message.text or not message.text.strip():
+                continue
+            if role == "user" and not self.store_user_messages:
+                continue
+            if role == "assistant" and not self.store_assistant_messages:
+                continue
+            if role not in {"user", "assistant"}:
+                continue
+            try:
+                await self.client.aremember(f"{role}: {message.text.strip()}", kind=self.kind, tags=tags, source=source)
+            except DXMTError as exc:
+                logger.error("DXMT remember failed: %s", exc)
+
+    # ---- explicit memory operations ---------------------------------------------------
+
+    async def remember(
+        self, text: str, *, kind: str | None = None, supersedes: list[str] | None = None
+    ) -> dict[str, Any]:
+        """Keep a memory under the storage scope; returns the server's answer (``id``, ``superseded``)."""
+        return await self.client.aremember(text, kind=kind or self.kind, tags=self.storage_tags, supersedes=supersedes)
+
+    async def recall(self, query: str, *, limit: int | None = None) -> list[dict[str, Any]]:
+        """Memories matching ``query`` within the retrieval scope."""
+        return await self.client.arecall(query, limit=limit or self.limit, tags=self.search_tags or None)
+
+    async def forget(self, ids: list[str]) -> int:
+        """Delete memories by id; returns how many there were."""
+        forgotten = 0
+        for memory_id in ids:
+            forgotten += await self.client.aforget(memory_id)
+        return forgotten
+
+    # ---- lifecycle -------------------------------------------------------------------
+
+    async def __aenter__(self) -> Self:
+        return self
+
+    async def __aexit__(self, exc_type: object, exc_val: object, exc_tb: object) -> None:
+        if self.managed_client and not self._closed:
+            await self.client.aclose()
+            self._closed = True

agent_framework_dxmt/_filters.py

@@ -0,0 +1,117 @@
+"""Agent Framework portable filters to the server's filter, or a refusal.
+
+The server takes one shape, three flat lists of conditions -- every ``must`` holds, at least
+one ``should`` holds, no ``must_not`` holds -- so not every filter tree has a form there. This
+translation is built on the SDK's ``Field`` builder, which produces that shape exactly or raises
+``ValueError`` naming the formula it cannot flatten, and that is re-raised here as
+``NotImplementedError``, which is what the framework's own connectors raise for a portable
+filter they cannot honour. Nothing is approximated.
+
+Operators (the framework's ``FilterOperator``), with the server's semantics -- a field holding an
+array matches when any element does, which is what makes the ``contains*`` family natural:
+
+==================  ==========================================================
+``eq`` ``ne``        ``Equal`` / ``NotEqual``
+``gt`` ``gte``       numeric comparisons; ``between`` is ``gte`` and ``lte``
+``lt`` ``lte``
+``in`` ``not_in``    ``In`` / ``NotIn``
+``is_null``          ``IsNull``; ``is_not_null`` and ``exists`` are ``not IsEmpty``
+``contains``         ``Equal`` on the array field; ``contains_any`` is ``In``;
+                     ``contains_all`` is one ``Equal`` per value, all required
+``starts_with``      ``StartsWith``; ``ends_with`` is ``EndsWith``
+``contains_text``    ``Contains`` (a substring test, not tokenised search)
+==================  ==========================================================
+
+Field names are the collection definition's logical names and are mapped to storage names;
+the key field is the record id (server key ``id``).
+"""
+
+from __future__ import annotations
+
+import functools
+import operator as op
+from typing import Any
+
+from agent_framework import Filter as AFFilter
+from agent_framework import FilterGroup, VectorStoreCollectionDefinition
+from dxmt.filters import Field, Filter
+
+
+def translate(expression: Any, definition: VectorStoreCollectionDefinition) -> dict[str, Any] | None:
+    """The server filter for ``expression``, or ``None`` for no filter."""
+    if expression is None:
+        return None
+    try:
+        return _node(expression, definition).to_dict()
+    except ValueError as exc:
+        raise NotImplementedError(f"DXMT has no flat form for this filter: {exc}") from exc
+
+
+def _storage_name(name: str, definition: VectorStoreCollectionDefinition) -> str:
+    field = definition.try_get_field(name)
+    if field is None or "." in name:
+        raise NotImplementedError("DXMT filters support declared top-level logical fields only.")
+    if field.field_type == "vector":
+        raise NotImplementedError("Portable DXMT filters do not operate on vector fields.")
+    if field.field_type == "key":
+        return "id"
+    return field.storage_name or field.name
+
+
+def _leaf(f: AFFilter, definition: VectorStoreCollectionDefinition) -> Filter:
+    field = Field(_storage_name(f.field_name, definition))
+    o, v = f.operator, f.value
+    if o == "eq":
+        return field == v
+    if o == "ne":
+        return field != v
+    if o == "gt":
+        return field > v
+    if o == "gte":
+        return field >= v
+    if o == "lt":
+        return field < v
+    if o == "lte":
+        return field <= v
+    if o == "between":
+        return (field >= v[0]) & (field <= v[1])
+    if o == "in":
+        return field.is_in(list(v))
+    if o == "not_in":
+        return field.not_in(list(v))
+    if o == "is_null":
+        return field.is_null()
+    if o in ("is_not_null", "exists"):
+        return ~field.is_empty()
+    if o == "contains":
+        return field == v
+    if o == "contains_any":
+        return field.is_in(list(v))
+    if o == "contains_all":
+        values = list(v)
+        if not values:
+            raise NotImplementedError("contains_all with no values has no meaning on the server.")
+        return functools.reduce(op.and_, (field == item for item in values))
+    if o == "starts_with":
+        return field.starts_with(str(v))
+    if o == "ends_with":
+        return field.ends_with(str(v))
+    if o == "contains_text":
+        return field.contains(str(v))
+    raise NotImplementedError(f"DXMT does not support portable filter operator '{o}'.")
+
+
+def _node(expression: Any, definition: VectorStoreCollectionDefinition) -> Filter:
+    if isinstance(expression, FilterGroup):
+        parts = [_node(child, definition) for child in expression.filters]
+        if not parts:
+            raise NotImplementedError("An empty filter group has no server form.")
+        if expression.operator == "and":
+            return functools.reduce(op.and_, parts)
+        if expression.operator == "or":
+            return functools.reduce(op.or_, parts)
+        # "not" takes exactly one child.
+        return ~parts[0]
+    if isinstance(expression, AFFilter):
+        return _leaf(expression, definition)
+    raise TypeError(f"Unexpected filter node {type(expression).__name__}.")

agent_framework_dxmt/_settings.py

@@ -0,0 +1,81 @@
+"""Connection settings and client ownership, in the shape the in-tree connectors use."""
+
+from __future__ import annotations
+
+from typing import TypedDict
+from urllib.parse import urlparse
+
+from agent_framework import SecretString, load_settings
+from dxmt import DXMTClient
+
+
+class DXMTSettings(TypedDict, total=False):
+    """Connection settings loaded through Agent Framework's ``load_settings``.
+
+    Explicit constructor arguments take precedence over an explicitly selected ``.env``
+    file, then environment variables prefixed with ``DXMT_``.
+
+    Keys:
+        url: Server URL from ``DXMT_URL`` (``http://host:port``). Defaults to ``http://localhost:9999``.
+        api_key: Optional API key from ``DXMT_API_KEY``, held as an AF ``SecretString``.
+    """
+
+    url: str | None
+    api_key: SecretString | None
+
+
+DEFAULT_URL = "http://localhost:9999"
+
+
+def _client_kwargs(url: str | None, api_key: SecretString | str | None) -> dict[str, object]:
+    parsed = urlparse(url or DEFAULT_URL)
+    if parsed.scheme not in ("http", "https") or not parsed.hostname:
+        raise ValueError(f"DXMT url must look like http://host:port, got {url!r}")
+    key = api_key.get_secret_value() if isinstance(api_key, SecretString) else api_key
+    return {
+        "host": parsed.hostname,
+        "port": parsed.port or (443 if parsed.scheme == "https" else 9999),
+        "ssl": parsed.scheme == "https",
+        "api_key": key,
+    }
+
+
+def _create_client(
+    *,
+    url: str | None,
+    api_key: str | SecretString | None,
+    env_file_path: str | None,
+    env_file_encoding: str | None,
+) -> DXMTClient:
+    settings = load_settings(
+        DXMTSettings,
+        env_prefix="DXMT_",
+        url=url,
+        api_key=api_key,
+        env_file_path=env_file_path,
+        env_file_encoding=env_file_encoding,
+    )
+    return DXMTClient(**_client_kwargs(settings.get("url"), settings.get("api_key")))  # type: ignore[arg-type]
+
+
+def _resolve_client(
+    client: DXMTClient | None,
+    *,
+    url: str | None,
+    api_key: str | SecretString | None,
+    managed_client: bool | None,
+    env_file_path: str | None,
+    env_file_encoding: str | None,
+) -> tuple[DXMTClient, bool]:
+    """The client and whether this connector closes it.
+
+    An injected client is returned unchanged and stays caller-owned; url, api_key and the
+    ``.env`` options are not read. A connector-created client is owned unless
+    ``managed_client`` is false.
+    """
+    if client is not None:
+        return client, False
+    return (
+        _create_client(url=url, api_key=api_key, env_file_path=env_file_path, env_file_encoding=env_file_encoding),
+        True if managed_client is None else managed_client,
+    )

agent_framework_dxmt/_vector_store.py

@@ -0,0 +1,498 @@
+"""DXMT vector store and collection for Microsoft Agent Framework.
+
+A collection is one DXMT table. The record's key is the row id (stored as a string; ``int``
+and ``UUID`` keys are converted on the way in and back on the way out), its one vector field
+is the row's vector, and its data fields are the payload under their storage names. A data
+field marked ``is_full_text_indexed`` gets the table's BM25 index, and then
+``search(values, search_type="keyword_hybrid", additional_property_name=<that field>)`` is
+the server's hybrid search; this is the second in-tree-shaped connector to offer it. With
+``server_embedding`` the table names an embedding model and a record whose vector is ``None``
+is embedded by the server from ``server_embedding_field``; a search without a local
+embedding generator then sends ``values`` as text.
+
+Scores are the server's similarities (1.0 is identical under cosine; larger is better) and
+``score_threshold`` is in those units. Supplied clients remain caller-owned.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from typing import Any, ClassVar, Generic, cast
+from uuid import UUID
+
+from agent_framework import (
+    BaseVectorCollection,
+    BaseVectorSearch,
+    BaseVectorStore,
+    SearchResults,
+    SecretString,
+    VectorStoreCollectionDefinition,
+)
+from agent_framework.exceptions import IntegrationException, IntegrationInvalidResponseException
+from dxmt import DXMTClient
+from dxmt.exceptions import DXMTError
+from typing_extensions import TypeVar
+
+from ._filters import translate
+from ._settings import _resolve_client
+
+KeyT = TypeVar("KeyT", default=Any)
+ModelT = TypeVar("ModelT", default=Any)
+
+_DISTANCES = {
+    "DEFAULT": "cosine",
+    "cosine_similarity": "cosine",
+    "dot_prod": "dot",
+    "euclidean_distance": "euclidean",
+}
+_BATCH_SIZE = 500
+
+
+def _not_found(exc: Exception) -> bool:
+    return "TABLE_NOT_FOUND" in str(exc) or "NOT_FOUND" in str(exc)
+
+
+class DXMTCollection(BaseVectorCollection[KeyT, ModelT], BaseVectorSearch[KeyT, ModelT], Generic[KeyT, ModelT]):
+    """One DXMT table as an Agent Framework vector collection."""
+
+    supported_key_types: ClassVar[set[str] | None] = {"int", "str", "UUID"}
+    supported_vector_types: ClassVar[set[str] | None] = {"float", "float16", "float32", "float64"}
+    supported_search_types: ClassVar[set[str]] = {"vector", "keyword_hybrid"}  # type: ignore[assignment]
+
+    def __init__(
+        self,
+        record_type: type[ModelT],
+        *,
+        definition: VectorStoreCollectionDefinition | None = None,
+        collection_name: str | None = None,
+        embedding_generator: Any = None,
+        client: DXMTClient | None = None,
+        url: str | None = None,
+        api_key: str | SecretString | None = None,
+        managed_client: bool | None = None,
+        env_file_path: str | None = None,
+        env_file_encoding: str | None = None,
+        server_embedding: Mapping[str, Any] | str | None = None,
+        server_embedding_field: str | None = None,
+        text_analyzer: str = "standard",
+    ) -> None:
+        """Initialize the collection.
+
+        Args:
+            record_type: Registered application model, or dict with an explicit definition.
+            definition: Explicit dictionary schema.
+            collection_name: Table name, overriding the model's collection name.
+            embedding_generator: Default local embedding client.
+            client: Existing ``DXMTClient``. When supplied, url, api_key and the .env options are
+                ignored and the client remains caller-owned.
+            url: Server URL override (``http://host:port``); otherwise ``DXMT_URL``, then localhost:9999.
+            api_key: API key override; otherwise ``DXMT_API_KEY``.
+            managed_client: Whether to close a connector-created client. Defaults to True.
+            env_file_path: Optional .env file to load before process environment variables.
+            env_file_encoding: Encoding for the .env file.
+            server_embedding: ``{"model": ..., "base_url": ..., "api_key_env": ...}`` to have the
+                server embed with that model, or ``"server"`` for the model the server itself was
+                started with; the table is created accordingly, and a record whose vector is
+                ``None`` is embedded from ``server_embedding_field``.
+            server_embedding_field: The data field whose text the server embeds. Defaults to the
+                full-text field when there is exactly one.
+            text_analyzer: ``standard`` or ``chinese`` for the BM25 index.
+        """
+        super().__init__(
+            record_type,
+            definition=definition,
+            collection_name=collection_name,
+            embedding_generator=embedding_generator,
+        )
+        resolved, owns = _resolve_client(
+            client,
+            url=url,
+            api_key=api_key,
+            managed_client=managed_client,
+            env_file_path=env_file_path,
+            env_file_encoding=env_file_encoding,
+        )
+        self.client = resolved
+        self.managed_client = owns
+        self.server_embedding: dict[str, Any] | str | None = (
+            "server" if server_embedding == "server" else dict(server_embedding) if server_embedding else None
+        )
+        self.text_analyzer = text_analyzer
+        self._closed = False
+        self._full_text_field = self._resolve_full_text_field()
+        self.server_embedding_field = server_embedding_field or (
+            self._full_text_field.name if self._full_text_field is not None else None
+        )
+        if self.server_embedding is not None and self.server_embedding_field is None:
+            raise ValueError(
+                "server_embedding needs server_embedding_field: the data field whose text the server embeds."
+            )
+
+    # ---- model -----------------------------------------------------------------------
+
+    def _validate_data_model(self) -> None:
+        super()._validate_data_model()
+        if self.definition.key_field.is_auto_generated:
+            raise NotImplementedError("DXMT requires application-provided record ids; it does not generate keys.")
+        vectors = self.definition.vector_fields
+        if len(vectors) != 1:
+            raise NotImplementedError("A DXMT collection holds exactly one vector field.")
+        field = vectors[0]
+        if not isinstance(field.dimensions, int) or isinstance(field.dimensions, bool):
+            raise TypeError("DXMT vector dimensions must be an integer.")
+        if field.distance_function not in _DISTANCES:
+            raise NotImplementedError(f"DXMT distance function '{field.distance_function}' is not supported.")
+        if field.index_kind not in {"default", "hnsw"}:
+            raise NotImplementedError(f"DXMT index kind '{field.index_kind}' is not supported.")
+        for data in self.definition.data_fields:
+            name = data.storage_name or data.name
+            if not name or "." in name or name in {"id", "content"}:
+                raise ValueError(
+                    f"DXMT payload storage name {name!r} is reserved or contains a dot; choose another storage_name."
+                )
+        if any(f.provider_annotations for f in self.definition.fields):
+            raise NotImplementedError("DXMT has no provider annotations.")
+
+    def _resolve_full_text_field(self) -> Any:
+        indexed = [f for f in self.definition.data_fields if f.is_full_text_indexed]
+        if len(indexed) > 1:
+            raise NotImplementedError("DXMT indexes one full-text field per table.")
+        return indexed[0] if indexed else None
+
+    @property
+    def _vector_field(self) -> Any:
+        return self.definition.vector_fields[0]
+
+    def _storage(self, field: Any) -> str:
+        return field.storage_name or field.name
+
+    def _key_to_id(self, key: Any) -> str:
+        return str(key)
+
+    def _id_to_key(self, value: str) -> KeyT:
+        kind = self.definition.key_field.type_
+        if kind == "int":
+            return cast(KeyT, int(value))
+        if kind == "UUID":
+            return cast(KeyT, UUID(value))
+        return cast(KeyT, value)
+
+    # ---- lifecycle -------------------------------------------------------------------
+
+    async def collection_exists(self, *, operation_options: Mapping[str, Any] | None = None) -> bool:
+        try:
+            await self.client.aget_table(self.collection_name)
+            return True
+        except DXMTError as exc:
+            if _not_found(exc):
+                return False
+            raise IntegrationException(f"DXMT table lookup failed: {exc}") from exc
+
+    async def ensure_collection_exists(self, *, operation_options: Mapping[str, Any] | None = None) -> None:
+        if await self.collection_exists():
+            return
+        field = self._vector_field
+        text_fields = None
+        if self._full_text_field is not None:
+            # The index field is called `content` on every table: the server's full-text schema
+            # has fixed names and only `content` is the BM25-ranked body. The source is the payload key.
+            text_fields = [
+                {
+                    "name": "content",
+                    "source": {"metadata_field": self._storage(self._full_text_field)},
+                    "analyzer": self.text_analyzer,
+                    "boost": 1.0,
+                }
+            ]
+        try:
+            # With a server-side model the server decides the width; "server" means the model it
+            # was started with, which a table takes when it names neither a dimension nor a model.
+            await self.client.acreate_table(
+                name=self.collection_name,
+                dimension=None if self.server_embedding is not None else cast(int, field.dimensions),
+                distance_metric=_DISTANCES[cast(str, field.distance_function)],
+                enable_full_text_search=text_fields is not None,
+                text_fields=text_fields,
+                embedding=self.server_embedding if isinstance(self.server_embedding, dict) else None,
+            )
+        except DXMTError as exc:
+            raise IntegrationException(f"DXMT could not create table '{self.collection_name}': {exc}") from exc
+
+    async def ensure_collection_deleted(self, *, operation_options: Mapping[str, Any] | None = None) -> None:
+        try:
+            await self.client.adelete_table(self.collection_name)
+        except DXMTError as exc:
+            if not _not_found(exc):
+                raise IntegrationException(f"DXMT could not delete table '{self.collection_name}': {exc}") from exc
+
+    async def aclose(self) -> None:
+        if self.managed_client and not self._closed:
+            await self.client.aclose()
+            self._closed = True
+
+    async def __aexit__(self, exc_type: object, exc_value: object, traceback: object) -> None:
+        await self.aclose()
+
+    # ---- conversion ------------------------------------------------------------------
+
+    def _serialize_dicts_to_store_models(
+        self, records: Sequence[dict[str, Any]], *, context: Mapping[str, Any] | None = None
+    ) -> Sequence[dict[str, Any]]:
+        key_name = self.definition.key_field_storage_name
+        vector_name = self._storage(self._vector_field)
+        rows: list[dict[str, Any]] = []
+        for record in records:
+            payload = {self._storage(f): record.get(self._storage(f)) for f in self.definition.data_fields}
+            row: dict[str, Any] = {"id": self._key_to_id(record[key_name]), "payload": payload}
+            vector = record.get(vector_name)
+            if vector is not None:
+                row["vector"] = [float(x) for x in vector]
+            elif self.server_embedding is not None and self.server_embedding_field is not None:
+                source = self.definition.try_get_field(self.server_embedding_field)
+                text = payload.get(self._storage(source)) if source is not None else None
+                if not isinstance(text, str) or not text:
+                    raise ValueError(
+                        f"Record {row['id']!r} has no vector and no text in '{self.server_embedding_field}' for the server to embed."
+                    )
+                row["text"] = text
+            else:
+                raise ValueError(f"Record {row['id']!r} has no vector; set an embedding generator or server_embedding.")
+            rows.append(row)
+        return rows
+
+    def _deserialize_store_models_to_dicts(
+        self, records: Sequence[Any], *, context: Mapping[str, Any] | None = None
+    ) -> Sequence[dict[str, Any]]:
+        key_name = self.definition.key_field_storage_name
+        vector_name = self._storage(self._vector_field)
+        out: list[dict[str, Any]] = []
+        for row in records:
+            if not isinstance(row, Mapping) or "id" not in row:
+                raise IntegrationInvalidResponseException("DXMT rows must be mappings with an id.")
+            payload = row.get("payload") or row.get("metadata") or {}
+            record: dict[str, Any] = {
+                self._storage(f): payload.get(self._storage(f)) for f in self.definition.data_fields
+            }
+            record[key_name] = self._id_to_key(str(row["id"]))
+            vector = row.get("vector")
+            if vector:
+                record[vector_name] = list(vector)
+            out.append(record)
+        return out
+
+    # ---- CRUD ------------------------------------------------------------------------
+
+    async def _inner_upsert(
+        self, records: Sequence[Any], *, operation_options: Mapping[str, Any] | None = None
+    ) -> Sequence[KeyT]:
+        if not records:
+            return []
+        try:
+            for start in range(0, len(records), _BATCH_SIZE):
+                await self.client.ainsert_records(self.collection_name, list(records[start : start + _BATCH_SIZE]))
+        except DXMTError as exc:
+            raise IntegrationException(f"DXMT upsert failed: {exc}") from exc
+        return [self._id_to_key(row["id"]) for row in records]
+
+    async def _inner_get(
+        self,
+        *,
+        keys: Sequence[KeyT] | None = None,
+        filter: Any = None,
+        top: int = 10,
+        skip: int = 0,
+        order_by: Mapping[str, bool] | None = None,
+        include_vectors: bool = False,
+        operation_options: Mapping[str, Any] | None = None,
+    ) -> Sequence[Any] | None:
+        if order_by:
+            raise NotImplementedError("DXMT ordered retrieval is not supported. Omit order_by.")
+        try:
+            if keys is not None:
+                if skip:
+                    raise ValueError("DXMT key retrieval cannot be combined with skip.")
+                ids = [self._key_to_id(k) for k in keys]
+                rows: list[dict[str, Any]] = []
+                for start in range(0, len(ids), _BATCH_SIZE):
+                    rows.extend(await self.client.aget_records(self.collection_name, ids[start : start + _BATCH_SIZE]))
+                if not include_vectors:
+                    for row in rows:
+                        row.pop("vector", None)
+                return rows
+            server_filter = translate(filter, self.definition)
+            rows = []
+            seen = 0
+            async for row in self.client.ascroll(
+                self.collection_name,
+                filter=server_filter,
+                batch_size=min(_BATCH_SIZE, skip + top),
+                with_vector=include_vectors,
+            ):
+                if seen < skip:
+                    seen += 1
+                    continue
+                rows.append(row)
+                if len(rows) >= top:
+                    break
+            return rows
+        except DXMTError as exc:
+            if _not_found(exc):
+                return []
+            raise IntegrationException(f"DXMT get failed: {exc}") from exc
+
+    async def _inner_delete(self, keys: Sequence[KeyT], *, operation_options: Mapping[str, Any] | None = None) -> None:
+        ids = [self._key_to_id(k) for k in keys]
+        try:
+            for start in range(0, len(ids), _BATCH_SIZE):
+                await self.client.adelete_records(self.collection_name, ids[start : start + _BATCH_SIZE])
+        except DXMTError as exc:
+            if not _not_found(exc):
+                raise IntegrationException(f"DXMT delete failed: {exc}") from exc
+
+    # ---- search ----------------------------------------------------------------------
+
+    async def _inner_search(
+        self,
+        *,
+        search_type: str,
+        filter: Any = None,
+        values: Any | None = None,
+        vector: Any | None = None,
+        top: int = 3,
+        skip: int = 0,
+        include_vectors: bool = False,
+        vector_property_name: str | None = None,
+        additional_property_name: str | None = None,
+        score_threshold: float | None = None,
+        operation_options: Mapping[str, Any] | None = None,
+    ) -> SearchResults[Any]:
+        server_filter = translate(filter, self.definition)
+        if score_threshold is not None and (
+            isinstance(score_threshold, bool) or not isinstance(score_threshold, (int, float))
+        ):
+            raise ValueError("DXMT score_threshold must be a number.")
+        text = values if isinstance(values, str) else None
+        query_vector = [float(x) for x in vector] if vector is not None else None
+        if search_type == "keyword_hybrid":
+            if additional_property_name is not None:
+                field = self.definition.try_get_field(additional_property_name)
+                if field is None or self._full_text_field is None or field.name != self._full_text_field.name:
+                    raise NotImplementedError(
+                        "DXMT keyword-hybrid search runs over the one full-text indexed field of the collection."
+                    )
+            if self._full_text_field is None:
+                raise NotImplementedError("Keyword-hybrid search needs a data field marked is_full_text_indexed.")
+            if text is None:
+                raise ValueError("Keyword-hybrid search needs string values.")
+            try:
+                hits = await self.client.ahybrid_search(
+                    self.collection_name, vector=query_vector, text=text, k=top + skip, filter=server_filter
+                )
+            except DXMTError as exc:
+                raise IntegrationException(f"DXMT hybrid search failed: {exc}") from exc
+            hits = hits[skip:]
+        else:
+            if query_vector is None and (text is None or self.server_embedding is None):
+                raise ValueError(
+                    "DXMT vector search requires a vector, an embedding generator, or server_embedding with string values."
+                )
+            try:
+                hits = await self.client.asearch(
+                    self.collection_name,
+                    vector=query_vector,
+                    text=text if query_vector is None else None,
+                    k=top,
+                    offset=skip,
+                    filter=server_filter,
+                    score_threshold=score_threshold,
+                )
+            except DXMTError as exc:
+                raise IntegrationException(f"DXMT search failed: {exc}") from exc
+        if score_threshold is not None:
+            hits = [h for h in hits if float(h.get("score", 0.0)) >= score_threshold]
+        if include_vectors and hits and any(h.get("vector") is None for h in hits):
+            # A search hit carries `vector: null`; the rows have it.
+            rows = await self.client.aget_records(self.collection_name, [h["id"] for h in hits])
+            vectors = {r["id"]: r.get("vector") for r in rows}
+            for h in hits:
+                h["vector"] = vectors.get(h["id"])
+        return SearchResults(hits)
+
+    def _get_record_from_result(self, result: Any) -> Any:
+        if not isinstance(result, Mapping):
+            raise IntegrationInvalidResponseException("Expected a DXMT hit mapping.")
+        return result
+
+    def _get_score_from_result(self, result: Any) -> float | None:
+        score = self._get_record_from_result(result).get("score")
+        return float(score) if score is not None else None
+
+
+class DXMTStore(BaseVectorStore):
+    """A DXMT server as an Agent Framework vector store; its tables are the collections."""
+
+    def __init__(
+        self,
+        *,
+        client: DXMTClient | None = None,
+        url: str | None = None,
+        api_key: str | SecretString | None = None,
+        embedding_generator: Any = None,
+        managed_client: bool | None = None,
+        env_file_path: str | None = None,
+        env_file_encoding: str | None = None,
+    ) -> None:
+        resolved, owns = _resolve_client(
+            client,
+            url=url,
+            api_key=api_key,
+            managed_client=managed_client,
+            env_file_path=env_file_path,
+            env_file_encoding=env_file_encoding,
+        )
+        super().__init__(embedding_generator=embedding_generator, managed_client=owns)
+        self.client = resolved
+        self._closed = False
+
+    def get_collection(
+        self,
+        record_type: type[ModelT],
+        *,
+        definition: VectorStoreCollectionDefinition | None = None,
+        collection_name: str | None = None,
+        embedding_generator: Any = None,
+        **kwargs: Any,
+    ) -> DXMTCollection[Any, ModelT]:
+        return DXMTCollection(
+            record_type,
+            definition=definition,
+            collection_name=collection_name,
+            embedding_generator=embedding_generator or self.embedding_generator,
+            client=self.client,
+            managed_client=False,
+            **kwargs,
+        )
+
+    async def list_collection_names(self, *, operation_options: Mapping[str, Any] | None = None) -> Sequence[str]:
+        try:
+            tables = await self.client.alist_tables()
+        except DXMTError as exc:
+            raise IntegrationException(f"DXMT could not list tables: {exc}") from exc
+        return [t["name"] for t in tables]
+
+    async def _inner_ensure_collection_deleted(
+        self, collection_name: str, *, operation_options: Mapping[str, Any] | None = None
+    ) -> None:
+        try:
+            await self.client.adelete_table(collection_name)
+        except DXMTError as exc:
+            if not _not_found(exc):
+                raise IntegrationException(f"DXMT could not delete table '{collection_name}': {exc}") from exc
+
+    async def aclose(self) -> None:
+        if self.managed_client and not self._closed:
+            await self.client.aclose()
+            self._closed = True
+
+    async def __aexit__(self, exc_type: object, exc_value: object, traceback: object) -> None:
+        await self.aclose()

agent_framework_dxmt-1.6.0.dist-info/METADATA

@@ -0,0 +1,123 @@
+Metadata-Version: 2.5
+Name: agent-framework-dxmt
+Version: 1.6.0
+Summary: DXMT vector store and memory context provider for Microsoft Agent Framework
+Project-URL: Homepage, https://github.com/dxmt/dxmt
+Project-URL: Source, https://github.com/dxmt/dxmt/tree/main/vectordb/clients/agent-framework-dxmt
+Project-URL: Issues, https://github.com/dxmt/dxmt/issues
+Author-email: DXMT Team <contact@dxmt.online>
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: agent-framework,agent-memory,context-provider,dxmt,microsoft-agent-framework,vector-store
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: agent-framework-core<2,>=1.19.0
+Requires-Dist: dxmt-python-sdk<2.0.0,>=1.6.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-cov>=5; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# agent-framework-dxmt
+
+[DXMT](https://github.com/dxmt/dxmt), the open-source memory database for personal agents,
+for [Microsoft Agent Framework](https://github.com/microsoft/agent-framework): a vector store
+with keyword-hybrid search, and memory as a context provider.
+
+```bash
+pip install agent-framework-dxmt
+```
+
+A DXMT server has to be running (`vectordb serve`, or
+`docker run -p 127.0.0.1:9999:9999 -v dxmt:/data dxmtai/dxmt`). Connection settings are
+`DXMT_URL` (default `http://localhost:9999`) and `DXMT_API_KEY`, or the `url` / `api_key`
+arguments, resolved through Agent Framework's `load_settings` like every other connector.
+
+## Vector store
+
+`DXMTCollection` and `DXMTStore` implement `BaseVectorCollection` / `BaseVectorSearch` and
+`BaseVectorStore`. A collection is one DXMT table; the record's single vector field is the
+row's vector and its data fields are the payload.
+
+```python
+from dataclasses import dataclass
+from typing import Annotated
+
+from agent_framework import Filter, VectorStoreField, vectorstoremodel
+from agent_framework_dxmt import DXMTStore
+
+
+@vectorstoremodel
+@dataclass
+class Document:
+    id: Annotated[str, VectorStoreField("key")]
+    title: Annotated[str, VectorStoreField("data", is_full_text_indexed=True)]
+    year: Annotated[int, VectorStoreField("data", is_indexed=True)]
+    embedding: Annotated[list[float] | None, VectorStoreField("vector", dimensions=3)] = None
+
+
+async with DXMTStore() as store:
+    collection = store.get_collection(Document, collection_name="documents")
+    await collection.ensure_collection_exists()
+    await collection.upsert([Document("1", "Hello DXMT", 2026, [1.0, 0.0, 0.0])], generate_vectors=False)
+    results = await collection.search(vector=[1.0, 0.0, 0.0], filter=Filter("year", "gte", 2020), top=3)
+    async for item in results:
+        print(item["record"].title, item["score"])
+```
+
+What is specific to DXMT:
+
+- **Keyword-hybrid search.** A data field marked `is_full_text_indexed` gets the table's BM25
+  index, and `collection.search("hello", search_type="keyword_hybrid", additional_property_name="title")`
+  is the server's hybrid search (vector and keywords fused on the server). Most in-tree
+  connectors declare `{"vector"}` only.
+- **Server-side embedding.** `DXMTCollection(..., server_embedding={"model": "text-embedding-3-small"},
+  server_embedding_field="title")` has the server embed records whose vector is `None` and
+  queries given as text, so no embedding client runs in the agent's process.
+- **Filters.** Every portable operator (`eq`, `ne`, ranges, `between`, `in`, `not_in`,
+  `is_null`, `is_not_null`, `exists`, `contains`, `contains_any`, `contains_all`,
+  `starts_with`, `ends_with`, `contains_text`) and `and` / `or` / `not` groups, translated
+  exactly to the server's flat filter; a shape the server has no flat form for (`(a and b) or c`)
+  raises `NotImplementedError` rather than being approximated.
+- Scores are similarities (1.0 is identical under cosine); `score_threshold` is in those units.
+  One vector field per collection; `cosine_similarity` (default), `dot_prod`, `euclidean_distance`.
+
+## Memory as a context provider
+
+`DXMTContextProvider` recalls memories before a run (by meaning *and* keyword) and remembers
+the exchange after it, using DXMT's own memory API. Scope is tags: memories are written under
+`user_id` / `agent_id` / `application_id` and recalled by the separate `search_*` ids, the
+split the mem0 provider uses so a memory written under a shared agent is not read back for an
+unrelated user by accident.
+
+```python
+from agent_framework import Agent
+from agent_framework_dxmt import DXMTContextProvider
+
+memory = DXMTContextProvider(user_id="alice", search_user_id="alice")
+agent = Agent(chat_client, instructions="...", context_providers=[memory])
+await agent.run("I prefer answers in Chinese.")
+await agent.run("How should you answer me?")   # the preference is recalled into the context
+```
+
+`memory.remember(text, kind=..., supersedes=[...])`, `memory.recall(query)` and
+`memory.forget(ids)` expose the three operations directly. A memory said twice is kept once;
+a new fact can supersede an old one, which is kept as history and left out of recall. The
+same store is what every other agent on the machine sees over MCP and REST.
+
+## Tests
+
+```bash
+pytest                                  # unit tests, client mocked
+DXMT_TEST_URL=http://127.0.0.1:9999 pytest -m integration   # against a server
+```

agent_framework_dxmt-1.6.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+agent_framework_dxmt/__init__.py,sha256=vc_ETqQXIiTchKXVMNEbEYUautuhq2__s5O4Y8Cf91g,506
+agent_framework_dxmt/_context_provider.py,sha256=T0wM8VHzUexxRacuwq583MIQ0GwWK0HCyeFJZxCBwJI,9184
+agent_framework_dxmt/_filters.py,sha256=7WKV7WfYuyKUGx7HuCXCT9ELAn1ddByb6ywu3RNXJpw,4925
+agent_framework_dxmt/_settings.py,sha256=iPRyMe7SeHnHmb5oPOXg_X91j4u-U9NXJqupYV8ZDcY,2691
+agent_framework_dxmt/_vector_store.py,sha256=uWPe4VpP33XKH1UKJV_srY4RExCSRRbh1vDZizgu29A,22726
+agent_framework_dxmt/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+agent_framework_dxmt-1.6.0.dist-info/METADATA,sha256=ypia6p3rP9Tq192MD1PtS8GEosO9zsbPqAIOkkU3hao,5821
+agent_framework_dxmt-1.6.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+agent_framework_dxmt-1.6.0.dist-info/licenses/LICENSE,sha256=VM3yU2vC82ewJ7c3oiE0Q4GyImTppYtuM2kUGshveL8,11430
+agent_framework_dxmt-1.6.0.dist-info/RECORD,,

agent_framework_dxmt-1.6.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

agent_framework_dxmt-1.6.0.dist-info/licenses/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 上海点线面体信息科技有限公司 (Shanghai Dianxianmianti Information Technology Co., Ltd.)
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.