chore: import upstream snapshot with attribution

python/packages/redis/agent_framework_redis/__init__.py

@@ -0,0 +1,16 @@
+# Copyright (c) Microsoft. All rights reserved.
+import importlib.metadata
+
+from ._context_provider import RedisContextProvider
+from ._history_provider import RedisHistoryProvider
+
+try:
+    __version__ = importlib.metadata.version(__name__)
+except importlib.metadata.PackageNotFoundError:
+    __version__ = "0.0.0"  # Fallback for development mode
+
+__all__ = [
+    "RedisContextProvider",
+    "RedisHistoryProvider",
+    "__version__",
+]

python/packages/redis/agent_framework_redis/_context_provider.py

@@ -0,0 +1,429 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""New-pattern Redis context provider using ContextProvider.
+
+This module provides ``RedisContextProvider``, built on the new
+:class:`ContextProvider` hooks pattern.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from typing import TYPE_CHECKING, Any, ClassVar, Literal
+
+import numpy as np
+from agent_framework import Message
+from agent_framework._sessions import AgentSession, ContextProvider, SessionContext
+from agent_framework.exceptions import (
+    AgentException,
+    IntegrationInvalidRequestException,
+)
+from redisvl.index import AsyncSearchIndex
+from redisvl.query import AggregateHybridQuery, TextQuery
+from redisvl.query.filter import FilterExpression, Tag
+from redisvl.utils.token_escaper import TokenEscaper
+from redisvl.utils.vectorize import BaseVectorizer
+
+if sys.version_info >= (3, 11):
+    from typing import Self  # pragma: no cover
+else:
+    from typing_extensions import Self  # pragma: no cover
+
+if sys.version_info >= (3, 12):
+    from typing import override  # pragma: no cover
+else:
+    from typing_extensions import override  # pragma: no cover
+
+if TYPE_CHECKING:
+    from agent_framework._agents import SupportsAgentRun
+
+
+class RedisContextProvider(ContextProvider):
+    """Redis context provider using the new ContextProvider hooks pattern.
+
+    Stores context in Redis and retrieves scoped context via full-text or
+    optional hybrid vector search.
+    """
+
+    DEFAULT_CONTEXT_PROMPT = "## Memories\nConsider the following memories when answering user questions:"
+    DEFAULT_SOURCE_ID: ClassVar[str] = "redis"
+
+    def __init__(
+        self,
+        source_id: str = DEFAULT_SOURCE_ID,
+        redis_url: str = "redis://localhost:6379",
+        index_name: str = "context",
+        prefix: str = "context",
+        *,
+        redis_vectorizer: BaseVectorizer | None = None,
+        vector_field_name: str | None = None,
+        vector_algorithm: Literal["flat", "hnsw"] | None = None,
+        vector_distance_metric: Literal["cosine", "ip", "l2"] | None = None,
+        application_id: str | None = None,
+        agent_id: str | None = None,
+        user_id: str | None = None,
+        context_prompt: str | None = None,
+        redis_index: Any = None,
+        overwrite_index: bool = False,
+    ):
+        """Create a Redis Context Provider.
+
+        Args:
+            source_id: Unique identifier for this provider instance.
+            redis_url: The Redis server URL.
+            index_name: The name of the Redis index.
+            prefix: The prefix for all keys in the Redis database.
+            redis_vectorizer: The vectorizer to use for Redis.
+            vector_field_name: The name of the vector field in Redis.
+            vector_algorithm: The algorithm to use for vector search.
+            vector_distance_metric: The distance metric to use for vector search.
+            application_id: The application ID to scope the context.
+            agent_id: The agent ID to scope the context.
+            user_id: The user ID to scope the context.
+            context_prompt: The context prompt to use for the provider.
+            redis_index: The Redis index to use for the provider.
+            overwrite_index: Whether to overwrite the existing Redis index.
+        """
+        super().__init__(source_id)
+        self.redis_url = redis_url
+        self.index_name = index_name
+        self.prefix = prefix
+        if redis_vectorizer is not None and not isinstance(redis_vectorizer, BaseVectorizer):
+            raise AgentException(
+                f"The redis vectorizer is not a valid type, got: {type(redis_vectorizer)}, expected: BaseVectorizer."
+            )
+        self.redis_vectorizer = redis_vectorizer
+        self.vector_field_name = vector_field_name
+        self.vector_algorithm: Literal["flat", "hnsw"] | None = vector_algorithm
+        self.vector_distance_metric: Literal["cosine", "ip", "l2"] | None = vector_distance_metric
+        self.application_id = application_id
+        self.agent_id = agent_id
+        self.user_id = user_id
+        self.context_prompt = context_prompt or self.DEFAULT_CONTEXT_PROMPT
+        self.overwrite_index = overwrite_index
+        self._token_escaper: TokenEscaper = TokenEscaper()
+        self._index_initialized: bool = False
+        self._schema_dict: dict[str, Any] | None = None
+        index = redis_index or AsyncSearchIndex.from_dict(  # pyright: ignore[reportUnknownMemberType]
+            self.schema_dict, redis_url=self.redis_url, validate_on_load=True
+        )
+        self.redis_index: Any = index
+
+    # -- Hooks pattern ---------------------------------------------------------
+
+    @override
+    async def before_run(
+        self,
+        *,
+        agent: SupportsAgentRun,
+        session: AgentSession,
+        context: SessionContext,
+        state: dict[str, Any],
+    ) -> None:
+        """Retrieve scoped context from Redis and add to the session context."""
+        self._validate_filters()
+        input_text = "\n".join(msg.text for msg in context.input_messages if msg and msg.text and msg.text.strip())
+        if not input_text.strip():
+            return
+
+        memories = await self._redis_search(text=input_text)
+        line_separated_memories = "\n".join(
+            str(memory.get("content", "")) for memory in memories if memory.get("content")
+        )
+        if line_separated_memories:
+            context.extend_messages(
+                self.source_id,
+                [Message(role="user", contents=[f"{self.context_prompt}\n{line_separated_memories}"])],
+            )
+
+    @override
+    async def after_run(
+        self,
+        *,
+        agent: SupportsAgentRun,
+        session: AgentSession,
+        context: SessionContext,
+        state: dict[str, Any],
+    ) -> None:
+        """Store request/response messages to Redis for future retrieval."""
+        self._validate_filters()
+
+        messages_to_store: list[Message] = list(context.input_messages)
+        if context.response and context.response.messages:
+            messages_to_store.extend(context.response.messages)
+
+        messages: list[dict[str, Any]] = []
+        for message in messages_to_store:
+            if message.role in {"user", "assistant", "system"} and message.text and message.text.strip():
+                shaped: dict[str, Any] = {
+                    "role": message.role,
+                    "content": message.text,
+                    "conversation_id": context.session_id,
+                    "message_id": message.message_id,
+                    "author_name": message.author_name,
+                }
+                messages.append(shaped)
+        if messages:
+            await self._add(data=messages, session_id=context.session_id)
+
+    # -- Internal methods (ported from RedisProvider) --------------------------
+
+    @property
+    def schema_dict(self) -> dict[str, Any]:
+        """Get the Redis schema dictionary, computing and caching it on first access."""
+        if self._schema_dict is None:
+            vector_dims = self.redis_vectorizer.dims if self.redis_vectorizer is not None else None
+            vector_datatype = self.redis_vectorizer.dtype if self.redis_vectorizer is not None else None
+            self._schema_dict = self._build_schema_dict(
+                index_name=self.index_name,
+                prefix=self.prefix,
+                vector_field_name=self.vector_field_name,
+                vector_dims=vector_dims,
+                vector_datatype=vector_datatype,
+                vector_algorithm=self.vector_algorithm,
+                vector_distance_metric=self.vector_distance_metric,
+            )
+        return self._schema_dict
+
+    def _build_filter_from_dict(self, filters: dict[str, str | None]) -> Any | None:
+        """Builds a combined filter expression from simple equality tags."""
+        parts: list[FilterExpression] = [Tag(k) == v for k, v in filters.items() if v]
+        if not parts:
+            return None
+        combined = parts[0]
+        for part in parts[1:]:
+            combined = combined & part
+        return combined
+
+    def _build_schema_dict(
+        self,
+        *,
+        index_name: str,
+        prefix: str,
+        vector_field_name: str | None,
+        vector_dims: int | None,
+        vector_datatype: str | None,
+        vector_algorithm: Literal["flat", "hnsw"] | None,
+        vector_distance_metric: Literal["cosine", "ip", "l2"] | None,
+    ) -> dict[str, Any]:
+        """Builds the RediSearch schema configuration dictionary."""
+        fields: list[dict[str, Any]] = [
+            {"name": "role", "type": "tag"},
+            {"name": "mime_type", "type": "tag"},
+            {"name": "content", "type": "text"},
+            {"name": "conversation_id", "type": "tag"},
+            {"name": "message_id", "type": "tag"},
+            {"name": "author_name", "type": "tag"},
+            {"name": "application_id", "type": "tag"},
+            {"name": "agent_id", "type": "tag"},
+            {"name": "user_id", "type": "tag"},
+            {"name": "thread_id", "type": "tag"},
+        ]
+        if vector_field_name is not None and vector_dims is not None:
+            fields.append({
+                "name": vector_field_name,
+                "type": "vector",
+                "attrs": {
+                    "algorithm": (vector_algorithm or "hnsw"),
+                    "dims": int(vector_dims),
+                    "distance_metric": (vector_distance_metric or "cosine"),
+                    "datatype": (vector_datatype or "float32"),
+                },
+            })
+        return {
+            "index": {"name": index_name, "prefix": prefix, "key_separator": ":", "storage_type": "hash"},
+            "fields": fields,
+        }
+
+    async def _ensure_index(self) -> None:
+        """Initialize the search index."""
+        if self._index_initialized:
+            return
+        index_exists = await self.redis_index.exists()
+        if not self.overwrite_index and index_exists:
+            await self._validate_schema_compatibility()
+        await self.redis_index.create(overwrite=self.overwrite_index, drop=False)
+        self._index_initialized = True
+
+    async def _validate_schema_compatibility(self) -> None:
+        """Validate that existing index schema matches current configuration."""
+        TAG_DEFAULTS = {"separator": ",", "case_sensitive": False, "withsuffixtrie": False}
+        TEXT_DEFAULTS = {"weight": 1.0, "no_stem": False}
+
+        def _significant_index(i: dict[str, Any]) -> dict[str, Any]:
+            return {k: i.get(k) for k in ("name", "prefix", "key_separator", "storage_type")}
+
+        def _sig_tag(attrs: dict[str, Any] | None) -> dict[str, Any]:
+            a = {**TAG_DEFAULTS, **(attrs or {})}
+            return {k: a[k] for k in ("separator", "case_sensitive", "withsuffixtrie")}
+
+        def _sig_text(attrs: dict[str, Any] | None) -> dict[str, Any]:
+            a = {**TEXT_DEFAULTS, **(attrs or {})}
+            return {k: a[k] for k in ("weight", "no_stem")}
+
+        def _sig_vector(attrs: dict[str, Any] | None) -> dict[str, Any]:
+            a = {**(attrs or {})}
+            return {k: a.get(k) for k in ("algorithm", "dims", "distance_metric", "datatype")}
+
+        def _schema_signature(schema: dict[str, Any]) -> dict[str, Any]:
+            sig: dict[str, Any] = {"index": _significant_index(schema.get("index", {})), "fields": {}}
+            for f in schema.get("fields", []):
+                name, ftype = f.get("name"), f.get("type")
+                if not name:
+                    continue
+                if ftype == "tag":
+                    sig["fields"][name] = {"type": "tag", "attrs": _sig_tag(f.get("attrs"))}
+                elif ftype == "text":
+                    sig["fields"][name] = {"type": "text", "attrs": _sig_text(f.get("attrs"))}
+                elif ftype == "vector":
+                    sig["fields"][name] = {"type": "vector", "attrs": _sig_vector(f.get("attrs"))}
+                else:
+                    sig["fields"][name] = {"type": ftype}
+            return sig
+
+        existing_index: Any = await AsyncSearchIndex.from_existing(  # pyright: ignore[reportUnknownMemberType]
+            self.index_name, redis_url=self.redis_url
+        )
+        existing_schema = existing_index.schema.to_dict()
+        current_schema = self.schema_dict
+        existing_sig = _schema_signature(existing_schema)
+        current_sig = _schema_signature(current_schema)
+        if existing_sig != current_sig:
+            raise ValueError(
+                "Existing Redis index schema is incompatible with the current configuration.\n"
+                f"Existing (significant): {json.dumps(existing_sig, indent=2, sort_keys=True)}\n"
+                f"Current  (significant): {json.dumps(current_sig, indent=2, sort_keys=True)}\n"
+                "Set overwrite_index=True to rebuild if this change is intentional."
+            )
+
+    async def _add(
+        self,
+        *,
+        data: dict[str, Any] | list[dict[str, Any]],
+        session_id: str | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> None:
+        """Inserts one or many documents with partition fields populated."""
+        self._validate_filters()
+        await self._ensure_index()
+        docs = data if isinstance(data, list) else [data]
+
+        prepared: list[dict[str, Any]] = []
+        for doc in docs:
+            d = dict(doc)
+            d.setdefault("application_id", self.application_id)
+            d.setdefault("agent_id", self.agent_id)
+            d.setdefault("user_id", self.user_id)
+            d.setdefault("thread_id", session_id)
+            d.setdefault("conversation_id", session_id)
+            if "content" not in d:
+                raise IntegrationInvalidRequestException("add() requires a 'content' field in data")
+            if self.vector_field_name:
+                d.setdefault(self.vector_field_name, None)
+            prepared.append(d)
+
+        if self.redis_vectorizer and self.vector_field_name:
+            text_list = [d["content"] for d in prepared]
+            embeddings = await self.redis_vectorizer.aembed_many(  # pyright: ignore[reportUnknownMemberType]
+                text_list, batch_size=len(text_list)
+            )
+            for i, d in enumerate(prepared):
+                vec = np.asarray(embeddings[i], dtype=np.float32).tobytes()
+                field_name: str = self.vector_field_name
+                d[field_name] = vec
+
+        await self.redis_index.load(prepared)
+
+    async def _redis_search(
+        self,
+        text: str,
+        *,
+        session_id: str | None = None,
+        text_scorer: str = "BM25STD",
+        filter_expression: Any | None = None,
+        return_fields: list[str] | None = None,
+        num_results: int = 10,
+        alpha: float = 0.7,
+    ) -> list[dict[str, Any]]:
+        """Runs a text or hybrid vector-text search with optional filters."""
+        await self._ensure_index()
+        self._validate_filters()
+
+        q = (text or "").strip()
+        if not q:
+            raise IntegrationInvalidRequestException("text_search() requires non-empty text")
+        num_results = max(int(num_results or 10), 1)
+
+        combined_filter = self._build_filter_from_dict({
+            "application_id": self.application_id,
+            "agent_id": self.agent_id,
+            "user_id": self.user_id,
+            "thread_id": session_id,
+            "conversation_id": session_id,
+        })
+        if filter_expression is not None:
+            combined_filter = (combined_filter & filter_expression) if combined_filter else filter_expression
+
+        return_fields = (
+            return_fields
+            if return_fields is not None
+            else ["content", "role", "application_id", "agent_id", "user_id", "thread_id"]
+        )
+
+        try:
+            if self.redis_vectorizer and self.vector_field_name:
+                vector = await self.redis_vectorizer.aembed(q)  # pyright: ignore[reportUnknownMemberType]
+                query = AggregateHybridQuery(
+                    text=q,
+                    text_field_name="content",
+                    vector=vector,
+                    vector_field_name=self.vector_field_name,
+                    text_scorer=text_scorer,
+                    filter_expression=combined_filter,
+                    alpha=alpha,
+                    dtype=self.redis_vectorizer.dtype,
+                    num_results=num_results,
+                    return_fields=return_fields,
+                    stopwords=None,
+                )
+                return await self.redis_index.query(query)
+            query = TextQuery(
+                text=q,
+                text_field_name="content",
+                text_scorer=text_scorer,
+                filter_expression=combined_filter,
+                num_results=num_results,
+                return_fields=return_fields,
+                stopwords=None,
+            )
+            return await self.redis_index.query(query)
+        except Exception as exc:  # pragma: no cover
+            raise IntegrationInvalidRequestException(f"Redis text search failed: {exc}") from exc
+
+    def _validate_filters(self) -> None:
+        """Validates that at least one filter is provided."""
+        if not self.agent_id and not self.user_id and not self.application_id:
+            raise ValueError("At least one of the filters: agent_id, user_id, or application_id is required.")
+
+    async def search_all(self, page_size: int = 200) -> list[dict[str, Any]]:
+        """Returns all documents in the index."""
+        from redisvl.query import FilterQuery
+
+        out: list[dict[str, Any]] = []
+        async for batch in self.redis_index.paginate(
+            FilterQuery(FilterExpression("*"), return_fields=[], num_results=page_size),
+            page_size=page_size,
+        ):
+            out.extend(batch)
+        return out
+
+    async def __aenter__(self) -> Self:
+        """Async context manager entry."""
+        return self
+
+    async def __aexit__(self, exc_type: type[BaseException] | None, exc_val: BaseException | None, exc_tb: Any) -> None:
+        """Async context manager exit."""
+
+
+__all__ = ["RedisContextProvider"]

python/packages/redis/agent_framework_redis/_history_provider.py

@@ -0,0 +1,194 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""New-pattern Redis history provider using HistoryProvider.
+
+This module provides ``RedisHistoryProvider``, built on the new
+:class:`HistoryProvider` hooks pattern.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Any, ClassVar
+
+import redis.asyncio as redis
+from agent_framework import Message
+from agent_framework._sessions import HistoryProvider
+from redis.credentials import CredentialProvider
+
+
+class RedisHistoryProvider(HistoryProvider):
+    """Redis-backed history provider using the new HistoryProvider hooks pattern.
+
+    Stores conversation history in Redis Lists, with each session isolated by a
+    unique Redis key.
+    """
+
+    DEFAULT_SOURCE_ID: ClassVar[str] = "redis_memory"
+
+    def __init__(
+        self,
+        source_id: str = DEFAULT_SOURCE_ID,
+        redis_url: str | None = None,
+        credential_provider: CredentialProvider | None = None,
+        host: str | None = None,
+        port: int = 6380,
+        ssl: bool = True,
+        username: str | None = None,
+        *,
+        key_prefix: str = "chat_messages",
+        max_messages: int | None = None,
+        load_messages: bool = True,
+        store_outputs: bool = True,
+        store_inputs: bool = True,
+        store_context_messages: bool = False,
+        store_context_from: set[str] | None = None,
+    ) -> None:
+        """Initialize the Redis history provider.
+
+        Args:
+            source_id: Unique identifier for this provider instance.
+            redis_url: Redis connection URL (e.g., "redis://localhost:6379").
+                Mutually exclusive with credential_provider.
+            credential_provider: Redis credential provider for Azure AD authentication.
+                Requires host parameter. Mutually exclusive with redis_url.
+            host: Redis host name. Required when using credential_provider.
+            port: Redis port number. Defaults to 6380 (Azure Redis SSL port).
+            ssl: Enable SSL/TLS connection. Defaults to True.
+            username: Redis username.
+            key_prefix: Prefix for Redis keys. Defaults to 'chat_messages'.
+            max_messages: Maximum number of messages to retain per session.
+                When exceeded, oldest messages are automatically trimmed.
+                None means unlimited storage.
+            load_messages: Whether to load messages before invocation.
+            store_outputs: Whether to store response messages.
+            store_inputs: Whether to store input messages.
+            store_context_messages: Whether to store context from other providers.
+            store_context_from: If set, only store context from these source_ids.
+
+        Raises:
+            ValueError: If neither redis_url nor credential_provider is provided.
+            ValueError: If both redis_url and credential_provider are provided.
+            ValueError: If credential_provider is used without host parameter.
+        """
+        super().__init__(
+            source_id,
+            load_messages=load_messages,
+            store_outputs=store_outputs,
+            store_inputs=store_inputs,
+            store_context_messages=store_context_messages,
+            store_context_from=store_context_from,
+        )
+
+        if redis_url is None and credential_provider is None:
+            raise ValueError("Either redis_url or credential_provider must be provided")
+        if redis_url is not None and credential_provider is not None:
+            raise ValueError("redis_url and credential_provider are mutually exclusive")
+        if credential_provider is not None and host is None:
+            raise ValueError("host is required when using credential_provider")
+
+        self.key_prefix = key_prefix
+        self.max_messages = max_messages
+        self.redis_url = redis_url
+
+        if credential_provider is not None and host is not None:
+            self._redis_client = redis.Redis(
+                host=host,
+                port=port,
+                ssl=ssl,
+                username=username,
+                credential_provider=credential_provider,
+                decode_responses=True,
+            )
+        else:
+            self._redis_client = redis.from_url(redis_url, decode_responses=True)  # type: ignore[no-untyped-call]
+
+    def _redis_key(self, session_id: str | None) -> str:
+        """Get the Redis key for a given session's messages."""
+        return f"{self.key_prefix}:{session_id or 'default'}"
+
+    async def get_messages(
+        self,
+        session_id: str | None,
+        *,
+        state: dict[str, Any] | None = None,
+        **kwargs: Any,
+    ) -> list[Message]:
+        """Retrieve stored messages for this session from Redis.
+
+        Args:
+            session_id: The session ID to retrieve messages for.
+            state: Optional session state. Unused for Redis-backed history.
+            **kwargs: Additional arguments (unused).
+
+        Returns:
+            List of stored Message objects in chronological order.
+        """
+        key = self._redis_key(session_id)
+        redis_messages: list[str] = await self._redis_client.lrange(key, 0, -1)  # type: ignore[misc]
+        messages: list[Message] = []
+        if redis_messages:
+            for serialized in redis_messages:  # type: ignore[union-attr]
+                messages.append(Message.from_dict(self._deserialize_json(serialized)))  # type: ignore[union-attr]
+        return messages
+
+    async def save_messages(
+        self,
+        session_id: str | None,
+        messages: Sequence[Message],
+        *,
+        state: dict[str, Any] | None = None,
+        **kwargs: Any,
+    ) -> None:
+        """Persist messages for this session to Redis.
+
+        Args:
+            session_id: The session ID to store messages for.
+            messages: The messages to persist.
+            state: Optional session state. Unused for Redis-backed history.
+            **kwargs: Additional arguments (unused).
+        """
+        if not messages:
+            return
+
+        key = self._redis_key(session_id)
+        serialized_messages = [self._serialize_json(msg) for msg in messages]
+
+        async with self._redis_client.pipeline(transaction=True) as pipe:
+            for serialized in serialized_messages:
+                await pipe.rpush(key, serialized)  # type: ignore[misc]
+            await pipe.execute()
+
+        if self.max_messages is not None:
+            current_count = await self._redis_client.llen(key)  # type: ignore[misc]
+            if current_count > self.max_messages:
+                await self._redis_client.ltrim(key, -self.max_messages, -1)  # type: ignore[misc]
+
+    @staticmethod
+    def _serialize_json(message: Message) -> str:
+        """Serialize a Message to a JSON string for Redis storage."""
+        import json
+
+        return json.dumps(message.to_dict())
+
+    @staticmethod
+    def _deserialize_json(data: str) -> dict[str, Any]:
+        """Deserialize a JSON string from Redis to a dict."""
+        import json
+
+        return json.loads(data)
+
+    async def clear(self, session_id: str | None) -> None:
+        """Clear all messages for a session.
+
+        Args:
+            session_id: The session ID to clear messages for.
+        """
+        await self._redis_client.delete(self._redis_key(session_id))
+
+    async def aclose(self) -> None:
+        """Close the Redis connection."""
+        await self._redis_client.aclose()
+
+
+__all__ = ["RedisHistoryProvider"]