Python: add RedisContextProvider (#716)

* Setting up * Readme * Add redis tests path to all-tests * First pass integration * Keep provider convention * First pass integration * add redis integration tests * update README.md * Add basic sample for redis integration * Add partitioning, add partition-aware tests, improve sample script * Fix code quality check * Try to resolve pytest check * Try to identify if pytest is the cause of failed checks * Re-enable tests * Rename redis test file * Removing some tests to narrow down issue * Revert, no difference * Delete temp files * Starting refactor of RedisProvider * Build dynamic schema builder, still need to do dynamic embedding model config * Add scope control * Complete first pass functionality with OpenAI + HF vectors -> Tests, Samples, Demo to follow * Fix code quality * attempt to identify rootcause of failed test * attempt to identify rootcause of failed test * Attempt to resolve code quality fail * Update pyproject.toml for foundry to pin azure-ai-projects == 1.1.0b3,azure-ai-agents == 1.2.0b3 * Add tests for redisprovider * Remove invalid tests * Add API key handling for openai vectorizer * Update uv.locl * Use master uv.lock * Begin sample file, add lazy index creation, fix faulty override * Index drop and reinit depends on drop_redis_index not overwrite * Add samples, threading included, escaped queries, verify threading works, sample README.md * Refactor filters * Opinionated vars * Allow filter expression combination * Try inline stubs for mypy * Address mypy errors * Better docstrings, tweaks for feedback * Tweak example 3 in redis_threads.py sample * adjust confusing name * Enrich docstrings * Add descriptions and comments to samples, externalize vectorizer choice, remove nltk and sentencetransformers dependnecy * Add descriptions and comments to samples, externalize vectorizer choice, remove nltk and sentencetransformers dependnecy * Incorporate initial feedback from dmytrostruk * Fix uv.lock * Attempt to resolve conflict * Use remote .tomls * Sanity check * fix tests * Remove hardcoded API key from samples * Fix incorrect env var * Make add and redis_search private * Fix tests relying on private funcs * Expand tests * Explainer comments to each test * Add a 'get_conversation_history' function to RedisProvider - This just returns messages in sequential order. Added 'created_at_*' timestamps to facilitate sequential recovery. function has to be manually invoked by user * Add agent-framework-redis to python/pyproject.toml * Remove get_conversation_history * improve redis context provider with pydantic techniques and safe index handling patterns * add RedisChatMessageStore * remove integration test :( * fix mypy error * Remove unused params * Redo schema validation to be order-invariant, handle attrs (previously throwing errors due to strict ==) * Expand explanation * Add ChatMessageStore example * Fix comments in redis_conversation.py * Resolving uv.lock conflict, update to match main * Fix test in redis provider * Apply suggestion from @ekzhu * Update python/packages/main/pyproject.toml --------- Co-authored-by: Tyler Hutcherson <tyler.hutcherson@redis.com> Co-authored-by: Eric Zhu <ekzhu@users.noreply.github.com>
2026-06-16 21:04:09 +08:00 · 2025-09-23 00:36:27 +00:00
parent 1ef24d3e91
commit ca810076e8
23 changed files with 3406 additions and 10 deletions
@@ -0,0 +1,112 @@
+# Redis Context Provider Examples
+
+The Redis context provider enables persistent, searchable memory for your agents using Redis (RediSearch). It supports full‑text search and optional hybrid search with vector embeddings, letting agents remember and retrieve user context across sessions and threads.
+
+This folder contains an example demonstrating how to use the Redis context provider with the Agent Framework.
+
+## Examples
+
+| File | Description |
+|------|-------------|
+| [`redis_basics.py`](redis_basics.py) | Shows standalone provider usage and agent integration. Demonstrates writing messages to Redis, retrieving context via full‑text or hybrid vector search, and persisting preferences across threads. Also includes a simple tool example whose outputs are remembered. |
+| [`redis_threads.py`](redis_threads.py) | Demonstrates thread scoping. Includes: (1) global thread scope with a fixed `thread_id` shared across operations; (2) per‑operation thread scope where `scope_to_per_operation_thread_id=True` binds memory to a single thread for the provider’s lifetime; and (3) multiple agents with isolated memory via different `agent_id` values. |
+
+## Prerequisites
+
+### Required resources
+
+1. A running Redis with RediSearch (Redis Stack or a managed service)
+2. Python environment with Agent Framework Redis extra installed
+3. Optional: OpenAI API key if using vector embeddings
+
+### Install the package
+
+```bash
+pip install "agent-framework[redis]"
+```
+
+## Running Redis
+
+Pick one option:
+
+### Option A: Docker (local Redis Stack)
+
+```bash
+docker run --name redis -p 6379:6379 -d redis:8.0.3
+```
+
+### Option B: Redis Cloud
+
+Create a free database and get the connection URL at `https://redis.io/cloud/`.
+
+### Option C: Azure Managed Redis
+
+See quickstart: `https://learn.microsoft.com/azure/redis/quickstart-create-managed-redis`
+
+## Configuration
+
+### Environment variables
+
+- `OPENAI_API_KEY` (optional): Required only if you set `vectorizer_choice="openai"` to enable hybrid search.
+
+### Provider configuration highlights
+
+The provider supports both full‑text only and hybrid vector search:
+
+- Set `vectorizer_choice` to `"openai"` or `"hf"` to enable embeddings and hybrid search.
+- When using a vectorizer, also set `vector_field_name` (e.g., `"vector"`).
+- Partition fields for scoping memory: `application_id`, `agent_id`, `user_id`, `thread_id`.
+- Thread scoping: `scope_to_per_operation_thread_id=True` isolates memory per operation thread.
+- Index management: `index_name`, `overwrite_redis_index`, `drop_redis_index`.
+
+## What the example does
+
+`redis_basics.py` walks through three scenarios:
+
+1. Standalone provider usage: adds messages and retrieves context via `model_invoking`.
+2. Agent integration: teaches the agent a preference and verifies it is remembered across turns.
+3. Agent + tool: calls a sample tool (flight search) and then asks the agent to recall details remembered from the tool output.
+
+It uses OpenAI for both chat (via `OpenAIChatClient`) and, in some steps, optional embeddings for hybrid search.
+
+## How to run
+
+1) Start Redis (see options above). For local default, ensure it's reachable at `redis://localhost:6379`.
+
+2) Set your OpenAI key if using embeddings and for the chat client used in the sample:
+
+```bash
+export OPENAI_API_KEY="<your key>"
+```
+
+3) Run the example:
+
+```bash
+python redis_basics.py
+```
+
+You should see the agent responses and, when using embeddings, context retrieved from Redis. The example includes commented debug helpers you can print, such as index info or all stored docs.
+
+## Key concepts
+
+### Memory scoping
+
+- Global scope: set `application_id`, `agent_id`, `user_id`, or `thread_id` on the provider to filter memory.
+- Per‑operation thread scope: set `scope_to_per_operation_thread_id=True` to isolate memory to the current thread created by the framework.
+
+### Hybrid vector search (optional)
+
+- Enable by setting `vectorizer_choice` to `"openai"` (requires `OPENAI_API_KEY`) or `"hf"` (offline model).
+- Provide `vector_field_name` (e.g., `"vector"`); other vector settings have sensible defaults.
+
+### Index lifecycle controls
+
+- `overwrite_redis_index` and `drop_redis_index` help recreate indexes during iteration.
+
+## Troubleshooting
+
+- Ensure at least one of `application_id`, `agent_id`, `user_id`, or `thread_id` is set; the provider requires a scope.
+- If using embeddings, verify `OPENAI_API_KEY` is set and reachable.
+- Make sure Redis exposes RediSearch (Redis Stack image or managed service with search enabled).
+
+