llm-hippocampus 0.0.1__tar.gz

llm_hippocampus-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Redis, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

llm_hippocampus-0.0.1/PKG-INFO

@@ -0,0 +1,123 @@
+Metadata-Version: 2.4
+Name: llm-hippocampus
+Version: 0.0.1
+Summary: LLM Hippocampus — a Context Engineering playground
+Home-page: 
+Author: joelz
+Author-email: joelz <zhongbj_2621@163.com>
+Project-URL: Repository, https://github.com/redis-developer/redis-rag-workbench.git
+Project-URL: Bug Tracker, https://github.com/redis-developer/redis-rag-workbench/issues
+Keywords: python,redis,langchain,openai
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: openai>=1.63.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: langchain>=0.3.19
+Requires-Dist: tiktoken>=0.9.0
+Requires-Dist: redis>=5.2.1
+Requires-Dist: langchain-community>=0.3.18
+Requires-Dist: langchain-huggingface>=0.1.2
+Requires-Dist: langchain-openai>=0.3.6
+Requires-Dist: langchain-experimental>=0.3.4
+Requires-Dist: python-ulid>=2.7.0
+Requires-Dist: pandas==2.2.3
+Requires-Dist: hf-xet>=1.1.8
+Requires-Dist: redisvl>=0.8.2
+Requires-Dist: sentence-transformers>=5.1.0
+Requires-Dist: langchain-redis>=0.2.3
+Provides-Extra: dev
+Requires-Dist: mypy<2.0.0,>=1.8.0; extra == "dev"
+Requires-Dist: ruff<1.0.0,>=0.2.2; extra == "dev"
+Dynamic: author
+Dynamic: license-file
+Dynamic: requires-python
+
+<div align="center">
+<h1>🚀 LLM Hippocampus</h1>
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+![Language](https://img.shields.io/github/languages/top/redis-developer/redis-rag-workbench)
+![GitHub last commit](https://img.shields.io/github/last-commit/redis-developer/redis-rag-workbench)
+![Python](https://img.shields.io/badge/python-3.11%2B-blue)
+
+🎯 Build up and manage the LLM 's memory
+
+</div>
+
+🔥 **LLM Hippocampus** helping your project for building and experimenting with **Context Engineering** applications. harness the full power of Redis for **lightning-fast vector search**, **intelligent semantic caching**, **persistent LLM memory**, and **smart context engineering **.
+
+✨ **What makes this special?**
+- 🚀 **One-command setup** - pip install llm-hippocampus
+- ⚡  **LLM support** - OpenAI
+- 🎯 **Redis-powered** - Vector search, caching, and memory management
+- 🐳 **Docker ready** - Building... 
+- 🔧 **Developer-first** - Support to Hot load by installing llm-hippocampus
+
+---
+
+## Table of Contents
+
+- [Quick Start](#quick-start)
+- [Prerequisites](#prerequisites)
+- [Getting Started](#getting-started)
+  - [Available Commands](#available-commands)
+  - [Development Workflows](#development-workflows)
+  - [Environment Configuration](#environment-configuration)
+- [Using Google VertexAI](#using-google-vertexai)
+- [Project Structure](#project-structure)
+- [Connecting to Redis Cloud](#connecting-to-redis-cloud)
+- [Troubleshooting](#troubleshooting)
+- [Contributing](#contributing)
+- [License](#license)
+- [Learn More](#learn-more)
+
+
+## Quick Start
+
+**Get up and install in your project:**
+
+```bash
+pip install llm-hippocampus
+or
+uv add llm-hippocampus
+```
+
+Welcome to LLM Hippocampus! 🎉
+
+---
+
+## Prerequisites
+
+1. Make sure you have the following tools available:
+   - [python](https://www.docker.com/products/docker-desktop/) 3.11+
+   - [uv](https://docs.astral.sh/uv/)
+   - [Redis Stack](https://redis.io/)
+2. Setup one or more of the following:
+   - [OpenAI API](https://platform.openai.com/)
+     - You will need an API Key
+
+## Getting Started
+
+
+### Development Workflows
+- Building
+
+
+## Project Structure
+
+
+## Contributing
+
+🤝 Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for details.
+
+## Troubleshooting
+
+## Learn More

llm_hippocampus-0.0.1/README.md

@@ -0,0 +1,85 @@
+<div align="center">
+<h1>🚀 LLM Hippocampus</h1>
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+![Language](https://img.shields.io/github/languages/top/redis-developer/redis-rag-workbench)
+![GitHub last commit](https://img.shields.io/github/last-commit/redis-developer/redis-rag-workbench)
+![Python](https://img.shields.io/badge/python-3.11%2B-blue)
+
+🎯 Build up and manage the LLM 's memory
+
+</div>
+
+🔥 **LLM Hippocampus** helping your project for building and experimenting with **Context Engineering** applications. harness the full power of Redis for **lightning-fast vector search**, **intelligent semantic caching**, **persistent LLM memory**, and **smart context engineering **.
+
+✨ **What makes this special?**
+- 🚀 **One-command setup** - pip install llm-hippocampus
+- ⚡  **LLM support** - OpenAI
+- 🎯 **Redis-powered** - Vector search, caching, and memory management
+- 🐳 **Docker ready** - Building... 
+- 🔧 **Developer-first** - Support to Hot load by installing llm-hippocampus
+
+---
+
+## Table of Contents
+
+- [Quick Start](#quick-start)
+- [Prerequisites](#prerequisites)
+- [Getting Started](#getting-started)
+  - [Available Commands](#available-commands)
+  - [Development Workflows](#development-workflows)
+  - [Environment Configuration](#environment-configuration)
+- [Using Google VertexAI](#using-google-vertexai)
+- [Project Structure](#project-structure)
+- [Connecting to Redis Cloud](#connecting-to-redis-cloud)
+- [Troubleshooting](#troubleshooting)
+- [Contributing](#contributing)
+- [License](#license)
+- [Learn More](#learn-more)
+
+
+## Quick Start
+
+**Get up and install in your project:**
+
+```bash
+pip install llm-hippocampus
+or
+uv add llm-hippocampus
+```
+
+Welcome to LLM Hippocampus! 🎉
+
+---
+
+## Prerequisites
+
+1. Make sure you have the following tools available:
+   - [python](https://www.docker.com/products/docker-desktop/) 3.11+
+   - [uv](https://docs.astral.sh/uv/)
+   - [Redis Stack](https://redis.io/)
+2. Setup one or more of the following:
+   - [OpenAI API](https://platform.openai.com/)
+     - You will need an API Key
+
+## Getting Started
+
+
+### Development Workflows
+- Building
+
+
+## Project Structure
+
+
+## Contributing
+
+🤝 Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for details.
+
+## Troubleshooting
+
+## Learn More

llm_hippocampus-0.0.1/llm_hippocampus/__init__.py

@@ -0,0 +1 @@
+# -*- coding: utf-8 -*-

llm_hippocampus-0.0.1/llm_hippocampus/context/__init__.py

@@ -0,0 +1 @@
+# -*- coding: utf-8 -*-

llm_hippocampus-0.0.1/llm_hippocampus/context/context_manager.py

@@ -0,0 +1,40 @@
+# -*- coding: utf-8 -*-
+from typing import Dict, Optional
+
+class ContextManager:
+    _instance = None
+
+    def __new__(cls):
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+            cls._instance._context = {}
+        return cls._instance
+
+    def set(self, key: str, value: str) -> None:
+        """添加或更新上下文键值对"""
+        self._context[key] = value
+
+    def get(self, key: str, default: Optional[str] = None) -> Optional[str]:
+        """获取上下文值"""
+        return self._context.get(key, default)
+
+    def delete(self, key: str) -> None:
+        """删除上下文键值对"""
+        if key in self._context:
+            del self._context[key]
+
+    def clear(self) -> None:
+        """清空所有上下文数据"""
+        self._context.clear()
+
+    def get_all(self) -> Dict[str, str]:
+        """获取所有上下文数据"""
+        return self._context.copy()
+
+
+def test():
+    print()
+
+
+if __name__ == '__main__':
+    None

llm_hippocampus-0.0.1/llm_hippocampus/context/context_processing.py

@@ -0,0 +1,8 @@
+# -*- coding: utf-8 -*-
+
+def test():
+    print()
+
+
+if __name__ == '__main__':
+    None

llm_hippocampus-0.0.1/llm_hippocampus/context/context_retrieval.py

@@ -0,0 +1,132 @@
+# -*- coding: utf-8 -*-
+
+from typing import List, Callable
+from enum import Enum
+
+class ContextSource(Enum):
+    PROMPT_GENERATED = "prompt_generated"
+    EXTERNAL_KNOWLEDGE = "external_knowledge"
+    DYNAMIC_ASSEMBLED = "dynamic_assembled"
+
+class ContextRetrieval:
+    def __init__(self, context_manager):
+        self.context_manager = context_manager
+        # 注册外部知识检索器（示例接口）
+        self.external_retrievers = {
+            "default": self._default_external_retriever
+        }
+
+    def generate_prompt_based_context(self, task_type: str, reasoning_framework: str = "basic") -> str:
+        """基于提示的生成：创建任务优化的指令框架
+        Args:
+            task_type: 任务类型，如"text_classification"、"nl2sql"、"summarization"
+            reasoning_framework: 推理框架类型，如"basic"、"chain_of_thought"、"tree_of_thought"
+        Returns:
+            生成的提示上下文字符串
+        """
+        # 基础提示模板库
+        prompt_templates = {
+            "text_classification": """你是一个文本分类专家。基于以下上下文信息，将文本分类到预定义类别中：
+{context}
+文本：{input}
+要求：输出最可能的类别名称，无需解释。""",
+            "nl2sql": """你是一个SQL生成专家。基于以下数据库模式信息，将自然语言转换为SQL查询：
+{context}
+用户问题：{input}
+要求：输出标准SQL，不包含解释和多余文本。""",
+            "summarization": """你是一个文本摘要专家。基于以下上下文信息，生成简洁准确的摘要：
+{context}
+文本：{input}
+要求：摘要长度不超过{max_length}字，保留关键信息。"""
+        }
+
+        # 推理框架增强
+        reasoning_enhancements = {
+            "basic": "",
+            "chain_of_thought": "思考过程：让我逐步分析...",
+            "tree_of_thought": "可能的思考方向：\n1. ...\n2. ...\n结论：..."
+        }
+
+        # 获取基础模板
+        base_template = prompt_templates.get(task_type, prompt_templates["text_classification"])
+        # 添加推理框架
+        enhanced_template = f"{base_template}\n{reasoning_enhancements.get(reasoning_framework, '')}"
+
+        # 存储生成的提示模板到上下文
+        self.context_manager.set(f"prompt_template_{task_type}", enhanced_template)
+        return enhanced_template
+
+    def retrieve_external_knowledge(self, query: str, retriever_name: str = "default", **kwargs) -> str:
+        """外部知识检索：访问动态信息源
+        Args:
+            query: 检索查询词
+            retriever_name: 检索器名称
+            **kwargs: 检索参数（如top_k、filter条件等）
+        Returns:
+            检索到的知识文本
+        """
+        if retriever_name not in self.external_retrievers:
+            raise ValueError(f"Retriever {retriever_name} not registered")
+
+        # 调用注册的检索器
+        knowledge = self.external_retrievers[retriever_name](query, **kwargs)
+        # 存储检索结果到上下文
+        self.context_manager.set(f"external_knowledge_{query[:30]}", knowledge)
+        return knowledge
+
+    def assemble_dynamic_context(self, context_ids: List[str], assembly_strategy: str = "sequential") -> str:
+        """动态上下文组装：将多个上下文组件整合成优化的输入
+        Args:
+            context_ids: 上下文组件ID列表
+            assembly_strategy: 组装策略，如"sequential"、"priority_based"、"summary_based"
+        Returns:
+            组装后的完整上下文
+        """
+        # 获取所有上下文组件
+        context_components = []
+        for cid in context_ids:
+            component = self.context_manager.get(cid)
+            if component:
+                context_components.append((cid, component))
+
+        # 应用组装策略
+        if assembly_strategy == "sequential":
+            assembled = "\n\n".join([f"[{cid}]: {comp}" for cid, comp in context_components])
+        elif assembly_strategy == "priority_based":
+            # 按ID中包含的优先级关键词排序
+            context_components.sort(key=lambda x: "priority" in x[0], reverse=True)
+            assembled = "\n\n".join([f"[{cid}]: {comp}" for cid, comp in context_components])
+        elif assembly_strategy == "summary_based":
+            # 生成组件摘要（简化实现）
+            summaries = [f"[{cid}摘要]: {comp[:100]}..." for cid, comp in context_components]
+            assembled = "\n\n".join(summaries + ["\n完整内容:\n" + "\n\n".join([comp for _, comp in context_components])])
+        else:
+            assembled = "\n\n".join([comp for _, comp in context_components])
+
+        # 存储组装结果
+        self.context_manager.set("assembled_context", assembled)
+        return assembled
+
+    def _default_external_retriever(self, query: str, top_k: int = 3) -> str:
+        """默认外部知识检索器（示例实现）
+        实际应用中可替换为调用搜索引擎、数据库或API
+        """
+        # 模拟外部检索结果
+        mock_knowledge = [
+            f"[检索结果1] 关于'{query}'的信息：这是模拟的外部知识，实际应用中应替换为真实API调用。",
+            f"[检索结果2] 相关数据：{len(query)}个字符，{query.count(' ')+1}个词。",
+            f"[检索结果3] 时间戳：{self.context_manager.get('current_timestamp', '未知')}"
+        ]
+        return "\n\n".join(mock_knowledge[:top_k])
+
+    def register_retriever(self, name: str, retriever_func: Callable) -> None:
+        """注册自定义外部知识检索器"""
+        self.external_retrievers[name] = retriever_func
+
+
+def test():
+    print()
+
+
+if __name__ == '__main__':
+    None

llm_hippocampus-0.0.1/llm_hippocampus/env.py

@@ -0,0 +1,24 @@
+# -*- coding: utf-8 -*-
+from dotenv import load_dotenv
+from .shared.utils import str_to_bool
+import os
+load_dotenv()
+
+TOP_K = int(os.environ.get("DEFAULT_TOP_K", 3))
+DISTANCE_THRESHOLD = float(os.environ.get("DEFAULT_DISTANCE_THRESHOLD", 0.30))
+REDIS_URL = os.environ.get("REDIS_URL",  "redis://:redis@192.168.65.166:6377")
+OPENAI_API_KEY = os.environ.get("OPENAI_API_KEY")
+CHUNK_SIZE = int(os.environ.get("DEFAULT_CHUNK_SIZE", 500))
+CHUNKING_TECHNIQUE = os.environ.get(
+            "DEFAULT_CHUNKING_TECHNIQUE", "Recursive Character"
+        )
+USE_SEMANTIC_CACHE = str_to_bool(
+            os.environ.get("DEFAULT_USE_SEMANTIC_CACHE")
+        )
+USE_RERANKERS = str_to_bool(os.environ.get("DEFAULT_USE_RERANKERS"))
+RERANKER_MODEL = os.environ.get("DEFAULT_RERANKER_MODEL", "D:/model/Qwen3-Reranker-0.6B")
+RERANKER_TYPE = os.environ.get("DEFAULT_RERANKER_TYPE", "HuggingFace")
+USE_CHAT_HISTORY = str_to_bool(os.environ.get("DEFAULT_USE_CHAT_HISTORY"))
+USE_RAGAS = str_to_bool(os.environ.get("DEFAULT_USE_RAGAS"))
+EMBEDDING_MODEL_PROVIDER = "openai"
+EMBEDDING_MODEL = os.environ.get("EMBEDDING_MODEL", "D:/model/Qwen3-Embedding-0.6B")

llm_hippocampus-0.0.1/llm_hippocampus/session.py

@@ -0,0 +1,247 @@
+# -*- coding: utf-8 -*-
+import os.path
+from typing import List
+
+from langchain.chains import create_retrieval_chain
+from langchain.chains.combine_documents import create_stuff_documents_chain
+from langchain_core.prompts import ChatPromptTemplate
+from langchain_openai import (
+    OpenAIEmbeddings,
+)
+from langchain_redis import RedisChatMessageHistory, RedisVectorStore
+from langchain_core.messages.chat import ChatMessage
+from redisvl.extensions.llmcache import SemanticCache
+from redisvl.utils.rerank import HFCrossEncoderReranker
+from redisvl.utils.utils import create_ulid
+from .shared.cached_llm import CachedLLM
+from .shared.logger import logger
+from . import env
+
+os.environ["TOKENIZERS_PARALLELISM"] = "false"
+
+class Session:
+    def __init__(self, llm, session_id = None, embedding = None, rerankers = None) -> None:
+        missing_vars = []
+        self.session_id = create_ulid() if session_id is None else session_id
+        self.redis_url = env.REDIS_URL
+        self.openai_api_key = env.OPENAI_API_KEY
+
+        self.initialized = False
+        self.RERANKERS = {}
+        if rerankers and env.USE_RERANKERS:
+            self.RERANKERS = rerankers
+
+        # Initialize non-API dependent variables
+        self.chunk_size = env.CHUNK_SIZE
+        self.chunking_technique = env.CHUNKING_TECHNIQUE
+        self.chat_history = None
+        self.N = 0
+        self.count = 0
+        self.use_semantic_cache = env.USE_SEMANTIC_CACHE
+        self.use_rerankers = env.USE_RERANKERS
+        self.top_k = env.TOP_K
+        self.distance_threshold = env.DISTANCE_THRESHOLD
+        self.use_chat_history = env.USE_CHAT_HISTORY
+        self.use_ragas = env.USE_RERANKERS
+        self.reranker_type = env.RERANKER_TYPE
+        logger.info("Initializing LLM")
+        self.llm = llm.get('llm')
+        self.llm_provider = llm.get('provider')
+        if not self.llm or not self.llm_provider:
+            missing_vars.append(llm)
+        self.cached_llm = None
+        self.vector_store = None
+        self.llmcache = None
+        self.index_name = None
+        if embedding:
+            self.embedding_model_provider = embedding['provider']
+            self.embedding = embedding['embedding']
+        else:
+            self.embedding = self.get_embedding_model()
+            self.embedding_model_provider = env.EMBEDDING_MODEL_PROVIDER
+
+        if missing_vars:
+            raise ValueError(f"模型初始化记忆发生异常，未设置必要的环境变量或传入的{missing_vars}不正确")
+
+    def initialize(self):
+        # Initialize rerankers
+        if self.use_rerankers:
+            logger.info("Initializing rerankers")
+
+            self.RERANKERS = {
+                "HuggingFace": HFCrossEncoderReranker(env.RERANKER_MODEL),
+            }
+            logger.info("Rerankers initialized")
+
+        # Init chat history if use_chat_history is True
+        if self.use_chat_history:
+            self.chat_history = RedisChatMessageHistory(
+                session_id=self.session_id,
+                redis_url=self.redis_url,
+                index_name="chat_history",  # Use a common index for all chat histories
+            )
+            chats = {"session_id": self.session_id, "chat_history": self.chat_history}
+            logger.debug(f"加载对话历史，{chats}")
+        else:
+            self.chat_history = None
+
+        self.initialized = True
+
+    def get_embedding_model(self):
+        """Get the right embedding model based on settings and config"""
+        print(
+            f"Embeddings for provider: {env.EMBEDDING_MODEL_PROVIDER} and model: {env.EMBEDDING_MODEL}"
+        )
+        match env.EMBEDDING_MODEL_PROVIDER.lower():
+            case "openai":
+                return OpenAIEmbeddings(model=env.EMBEDDING_MODEL)
+
+        return None
+
+    def build_chain(self, history: List[ChatMessage]):
+        retriever = self.vector_store.as_retriever(search_kwargs={"k": self.top_k})
+
+        messages = [
+            (
+                "system",
+                """You are a helpful AI assistant. Use the following pieces of
+                    context to answer the user's question. If you don't know the
+                answer, just say that you don't know, don't try to make up an
+                    answer. Please be as detailed as possible with your
+                    answers.""",
+            ),
+            ("system", "Context: {context}"),
+        ]
+
+        if self.use_chat_history:
+            for msg in history:
+                messages.append((msg["role"], msg["content"]))
+
+        messages.append(("human", "{input}"))
+        messages.append(
+            (
+                "system",
+                "Provide a helpful and accurate answer based on the given context and question:",
+            )
+        )
+        prompt = ChatPromptTemplate.from_messages(messages)
+
+        combine_docs_chain = create_stuff_documents_chain(self.cached_llm, prompt)
+        rag_chain = create_retrieval_chain(retriever, combine_docs_chain)
+
+        return rag_chain
+
+    def update_chat_history(
+        self, history: List[ChatMessage], use_chat_history: bool
+    ):
+        self.use_chat_history = use_chat_history
+
+        if self.use_chat_history:
+            if self.chat_history is None:
+                self.chat_history = RedisChatMessageHistory(
+                    session_id=self.session_id,
+                    redis_url=self.redis_url,
+                    index_name="chat_history",
+                )
+
+        else:
+            if self.chat_history:
+                try:
+                    self.chat_history.clear()
+                except Exception as e:
+                    logger.debug(f"清理会话历史异常: {str(e)}")
+
+        history.clear()
+
+        return history
+
+    def get_chat_history(self):
+        if self.chat_history and self.use_chat_history:
+            messages = self.chat_history.messages
+            formatted_history = []
+            for msg in messages:
+                if msg.type == "human":
+                    formatted_history.append(f"👤 **Human**: {msg.content}\n")
+                elif msg.type == "ai":
+                    formatted_history.append(f"🤖 **AI**: {msg.content}\n")
+            return "\n".join(formatted_history)
+        return "No chat history available."
+
+    def update_top_k(self, new_top_k: int):
+        self.top_k = new_top_k
+
+    def make_semantic_cache(self) -> SemanticCache:
+        semantic_cache_index_name = f"llmcache:{self.index_name}"
+        return SemanticCache(
+            name=semantic_cache_index_name,
+            redis_url=self.redis_url,
+            distance_threshold=self.distance_threshold,
+        )
+
+    def clear_semantic_cache(self):
+        # Always make a new SemanticCache in case use_semantic_cache is False
+        semantic_cache = self.make_semantic_cache()
+        semantic_cache.clear()
+
+    def update_semantic_cache(self, use_semantic_cache: bool):
+        self.use_semantic_cache = use_semantic_cache
+        if self.use_semantic_cache and self.index_name:
+            self.llmcache = self.make_semantic_cache()
+        else:
+            self.llmcache = None
+
+
+    def update_distance_threshold(self, new_threshold: float):
+        self.distance_threshold = new_threshold
+        if self.index_name:
+            self.llmcache = self.make_semantic_cache()
+            self.update_llm()
+
+    def get_last_cache_status(self) -> bool:
+        if isinstance(self.cached_llm, CachedLLM):
+            return self.cached_llm.get_last_cache_status()
+        return False
+
+    def rerank_results(self, query, results):
+        if not self.use_reranker:
+            return results, None, None
+
+        reranker = self.RERANKERS[self.reranker_type]
+        original_results = [r.page_content for r in results]
+
+        reranked_results, scores = reranker.rank(query=query, docs=original_results)
+
+        # Reconstruct the results with reranked order, using fuzzy matching
+        reranked_docs = []
+        for reranked in reranked_results:
+            reranked_content = (
+                reranked["content"] if isinstance(reranked, dict) else reranked
+            )
+            best_match = max(
+                results, key=lambda r: self.similarity(r.page_content, reranked_content)
+            )
+            reranked_docs.append(best_match)
+
+        rerank_info = {
+            "original_order": original_results,
+            "reranked_order": [
+                r["content"] if isinstance(r, dict) else r for r in reranked_results
+            ],
+            "original_scores": [1.0]
+            * len(results),  # Assuming original scores are not available
+            "reranked_scores": scores,
+        }
+
+        return reranked_docs, rerank_info, original_results
+
+    def similarity(self, s1, s2):
+        # Simple similarity measure based on common words
+        words1 = set(s1.lower().split())
+        words2 = set(s2.lower().split())
+        return len(words1.intersection(words2)) / len(words1.union(words2))
+
+    def rerankers(self):
+        return self.RERANKERS
+
+    def update_embedding_model_provider(self, new_provider: str):
+        self.embedding_model_provider = new_provider

llm_hippocampus-0.0.1/llm_hippocampus/shared/__init__.py

@@ -0,0 +1 @@
+# -*- coding: utf-8 -*-

llm_hippocampus-0.0.1/llm_hippocampus/shared/cached_llm.py

@@ -0,0 +1,50 @@
+# -*- coding: utf-8 -*-
+from typing import Any, Optional
+
+from langchain_core.prompt_values import ChatPromptValue, StringPromptValue
+from langchain_core.runnables.base import Runnable
+from langchain_core.runnables.config import RunnableConfig
+
+
+class CachedLLM(Runnable):
+    def __init__(self, llm, llmcache):
+        self.llm = llm
+        self.llmcache = llmcache
+        self.last_is_cache_hit = False
+
+    def invoke(
+        self, input: Any, config: Optional[RunnableConfig] = None, **kwargs
+    ) -> str:
+        if isinstance(input, dict):
+            question = input.get("query") or input.get("input")
+        elif isinstance(input, str):
+            question = input
+        elif isinstance(input, StringPromptValue):
+            question = input.text
+        elif isinstance(input, ChatPromptValue):
+            # Extract the last human message from the chat history
+            human_message = next(
+                m for m in reversed(input.messages) if m.type == "human"
+            )
+            question = human_message.content.strip()
+        else:
+            raise ValueError(f"Unexpected input type: {type(input)}")
+
+        if not isinstance(question, str):
+            raise TypeError(f"Question must be a string, got {type(question)}")
+
+        cached_responses = self.llmcache.check(
+            prompt=question, return_fields=["prompt", "response", "metadata"]
+        )
+        if cached_responses:
+            self.last_is_cache_hit = True
+            return cached_responses[0]["response"]
+
+        self.last_is_cache_hit = False
+        response = self.llm.invoke(input, **kwargs)
+        text = response.content if hasattr(response, "content") else str(response)
+        self.llmcache.store(prompt=question, response=text)
+        return text
+
+    def get_last_cache_status(self) -> bool:
+        return self.last_is_cache_hit

llm_hippocampus-0.0.1/llm_hippocampus/shared/logger.py

@@ -0,0 +1,10 @@
+# -*- coding: utf-8 -*-
+import logging
+import os
+from dotenv import load_dotenv
+
+load_dotenv()
+log_level = os.environ.get("LOG_LEVEL", logging.DEBUG)
+
+logger = logging.getLogger("app")
+logger.setLevel(log_level)

llm_hippocampus-0.0.1/llm_hippocampus/shared/memory.py

@@ -0,0 +1,124 @@
+# -*- coding: utf-8 -*-
+from typing import List
+
+from langchain_core.prompts import ChatPromptTemplate
+from langchain_redis import RedisVectorStore
+from redisvl.index import SearchIndex
+from . import logger
+
+class Memory:
+    index: SearchIndex
+    def __init__(self, redis_url: str):
+        logger.info(f"初始化记忆模块，Redis URL: {redis_url}")
+        self.redis_url = redis_url
+
+    @property
+    def client(self):
+        """Redis client accessor."""
+        return self.index.client
+
+    def _check_vector_store_exists(self, index_name: str) -> bool:
+        """Check if a vector store exists for the given index name."""
+        try:
+            self.client.ft(index_name).info()
+            return True
+        except Exception:
+            return False
+
+    def _cleanup_vector_store(self, index_name: str) -> bool:
+        """Clean up the vector store index and its documents."""
+        if not self._check_vector_store_exists(index_name):
+            return True
+
+        try:
+            self.client.ft(index_name).dropindex(delete_documents=True)
+            logger.info(f"Successfully cleaned up vector store: {index_name}")
+            return True
+        except Exception as e:
+            logger.warning(f"Could not clean up vector store {index_name}: {e}")
+            return False
+
+    def get_chat_history(chat_history, use_chat_history: bool):
+        if chat_history and use_chat_history:
+            messages = chat_history.messages
+            formatted_history = []
+            for msg in messages:
+                if msg.type == "human":
+                    formatted_history.append(f"👤 **Human**: {msg.content}\n")
+                elif msg.type == "ai":
+                    formatted_history.append(f"🤖 **AI**: {msg.content}\n")
+            return "\n".join(formatted_history)
+        return "No chat history available."
+
+
+    def build_chain(self, history: List[any]):
+        retriever = self.vector_store.as_retriever(search_kwargs={"k": self.top_k})
+
+        messages = [
+            (
+                "system",
+                """You are a helpful AI assistant. Use the following pieces of
+                    context to answer the user's question. If you don't know the
+                answer, just say that you don't know, don't try to make up an
+                    answer. Please be as detailed as possible with your
+                    answers.""",
+            ),
+            ("system", "Context: {context}"),
+        ]
+
+        if self.use_chat_history:
+            for msg in history:
+                messages.append((msg["role"], msg["content"]))
+
+        messages.append(("human", "{input}"))
+        messages.append(
+            (
+                "system",
+                "Provide a helpful and accurate answer based on the given context and question:",
+            )
+        )
+        prompt = ChatPromptTemplate.from_messages(messages)
+
+        # combine_docs_chain = create_stuff_documents_chain(self.cached_llm, prompt)
+        # rag_chain = create_retrieval_chain(retriever, combine_docs_chain)
+
+        # return rag_chain
+
+    def load_vector_store(self, index_name: str, embeddings)  -> RedisVectorStore:
+        try:
+            # Get the metadata
+            metadata = self.get_pdf_metadata(index_name)
+            if not metadata:
+                # Try to reprocess from file
+                return self._reprocess_from_file(index_name, embeddings)
+
+            # Check if vector store exists
+            documents = None
+            if not self._check_vector_store_exists(index_name):
+                logger.info(f"Vector store missing for {index_name}, reprocessing")
+                vector_store = RedisVectorStore.from_documents(
+                    documents,
+                    embeddings,
+                    redis_url=self.redis_url,
+                    index_name=index_name,
+                    key_prefix=f"pdf:{index_name}",
+                )
+                logger.info(f"Created vector store during reprocessing for {index_name}")
+
+            # Vector store exists, load it
+            vector_store = RedisVectorStore(
+                embeddings,
+                redis_url=self.redis_url,
+                index_name=index_name,
+                key_prefix=f"pdf:{index_name}",
+            )
+
+            logger.info(f"Successfully loaded PDF: {metadata.filename}")
+            return vector_store
+
+        except Exception as e:
+            logger.error(f"Failed to load PDF {index_name}: {e}")
+            raise
+
+if __name__ == '__main__':
+    None

llm_hippocampus-0.0.1/llm_hippocampus/shared/utils.py

@@ -0,0 +1,4 @@
+# -*- coding: utf-8 -*-
+import uuid
+def str_to_bool(val):
+    return str(val).lower() in ["1", "yes", "true"]

llm_hippocampus-0.0.1/llm_hippocampus.egg-info/PKG-INFO

@@ -0,0 +1,123 @@
+Metadata-Version: 2.4
+Name: llm-hippocampus
+Version: 0.0.1
+Summary: LLM Hippocampus — a Context Engineering playground
+Home-page: 
+Author: joelz
+Author-email: joelz <zhongbj_2621@163.com>
+Project-URL: Repository, https://github.com/redis-developer/redis-rag-workbench.git
+Project-URL: Bug Tracker, https://github.com/redis-developer/redis-rag-workbench/issues
+Keywords: python,redis,langchain,openai
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: openai>=1.63.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: langchain>=0.3.19
+Requires-Dist: tiktoken>=0.9.0
+Requires-Dist: redis>=5.2.1
+Requires-Dist: langchain-community>=0.3.18
+Requires-Dist: langchain-huggingface>=0.1.2
+Requires-Dist: langchain-openai>=0.3.6
+Requires-Dist: langchain-experimental>=0.3.4
+Requires-Dist: python-ulid>=2.7.0
+Requires-Dist: pandas==2.2.3
+Requires-Dist: hf-xet>=1.1.8
+Requires-Dist: redisvl>=0.8.2
+Requires-Dist: sentence-transformers>=5.1.0
+Requires-Dist: langchain-redis>=0.2.3
+Provides-Extra: dev
+Requires-Dist: mypy<2.0.0,>=1.8.0; extra == "dev"
+Requires-Dist: ruff<1.0.0,>=0.2.2; extra == "dev"
+Dynamic: author
+Dynamic: license-file
+Dynamic: requires-python
+
+<div align="center">
+<h1>🚀 LLM Hippocampus</h1>
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+![Language](https://img.shields.io/github/languages/top/redis-developer/redis-rag-workbench)
+![GitHub last commit](https://img.shields.io/github/last-commit/redis-developer/redis-rag-workbench)
+![Python](https://img.shields.io/badge/python-3.11%2B-blue)
+
+🎯 Build up and manage the LLM 's memory
+
+</div>
+
+🔥 **LLM Hippocampus** helping your project for building and experimenting with **Context Engineering** applications. harness the full power of Redis for **lightning-fast vector search**, **intelligent semantic caching**, **persistent LLM memory**, and **smart context engineering **.
+
+✨ **What makes this special?**
+- 🚀 **One-command setup** - pip install llm-hippocampus
+- ⚡  **LLM support** - OpenAI
+- 🎯 **Redis-powered** - Vector search, caching, and memory management
+- 🐳 **Docker ready** - Building... 
+- 🔧 **Developer-first** - Support to Hot load by installing llm-hippocampus
+
+---
+
+## Table of Contents
+
+- [Quick Start](#quick-start)
+- [Prerequisites](#prerequisites)
+- [Getting Started](#getting-started)
+  - [Available Commands](#available-commands)
+  - [Development Workflows](#development-workflows)
+  - [Environment Configuration](#environment-configuration)
+- [Using Google VertexAI](#using-google-vertexai)
+- [Project Structure](#project-structure)
+- [Connecting to Redis Cloud](#connecting-to-redis-cloud)
+- [Troubleshooting](#troubleshooting)
+- [Contributing](#contributing)
+- [License](#license)
+- [Learn More](#learn-more)
+
+
+## Quick Start
+
+**Get up and install in your project:**
+
+```bash
+pip install llm-hippocampus
+or
+uv add llm-hippocampus
+```
+
+Welcome to LLM Hippocampus! 🎉
+
+---
+
+## Prerequisites
+
+1. Make sure you have the following tools available:
+   - [python](https://www.docker.com/products/docker-desktop/) 3.11+
+   - [uv](https://docs.astral.sh/uv/)
+   - [Redis Stack](https://redis.io/)
+2. Setup one or more of the following:
+   - [OpenAI API](https://platform.openai.com/)
+     - You will need an API Key
+
+## Getting Started
+
+
+### Development Workflows
+- Building
+
+
+## Project Structure
+
+
+## Contributing
+
+🤝 Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for details.
+
+## Troubleshooting
+
+## Learn More

llm_hippocampus-0.0.1/llm_hippocampus.egg-info/SOURCES.txt

@@ -0,0 +1,21 @@
+LICENSE
+README.md
+pyproject.toml
+setup.py
+llm_hippocampus/__init__.py
+llm_hippocampus/env.py
+llm_hippocampus/session.py
+llm_hippocampus.egg-info/PKG-INFO
+llm_hippocampus.egg-info/SOURCES.txt
+llm_hippocampus.egg-info/dependency_links.txt
+llm_hippocampus.egg-info/requires.txt
+llm_hippocampus.egg-info/top_level.txt
+llm_hippocampus/context/__init__.py
+llm_hippocampus/context/context_manager.py
+llm_hippocampus/context/context_processing.py
+llm_hippocampus/context/context_retrieval.py
+llm_hippocampus/shared/__init__.py
+llm_hippocampus/shared/cached_llm.py
+llm_hippocampus/shared/logger.py
+llm_hippocampus/shared/memory.py
+llm_hippocampus/shared/utils.py

llm_hippocampus-0.0.1/llm_hippocampus.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

llm_hippocampus-0.0.1/llm_hippocampus.egg-info/requires.txt

@@ -0,0 +1,19 @@
+openai>=1.63.0
+python-dotenv>=1.0.0
+langchain>=0.3.19
+tiktoken>=0.9.0
+redis>=5.2.1
+langchain-community>=0.3.18
+langchain-huggingface>=0.1.2
+langchain-openai>=0.3.6
+langchain-experimental>=0.3.4
+python-ulid>=2.7.0
+pandas==2.2.3
+hf-xet>=1.1.8
+redisvl>=0.8.2
+sentence-transformers>=5.1.0
+langchain-redis>=0.2.3
+
+[dev]
+mypy<2.0.0,>=1.8.0
+ruff<1.0.0,>=0.2.2

llm_hippocampus-0.0.1/llm_hippocampus.egg-info/top_level.txt

@@ -0,0 +1 @@
+llm_hippocampus

llm_hippocampus-0.0.1/pyproject.toml

@@ -0,0 +1,67 @@
+[project]
+name = "llm-hippocampus"
+version = "0.0.1"
+description = "LLM Hippocampus — a Context Engineering playground"
+authors = [
+  { name = "joelz", email = "zhongbj_2621@163.com" }
+]
+readme = "README.md"
+requires-python=">=3.11,<3.14"
+keywords = ["python", "redis", "langchain", "openai"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python"
+]
+dependencies = [
+    "openai>=1.63.0",
+    "python-dotenv>=1.0.0",
+    "langchain>=0.3.19",
+    "tiktoken>=0.9.0",
+    "redis>=5.2.1",
+    "langchain-community>=0.3.18",
+    "langchain-huggingface>=0.1.2",
+    "langchain-openai>=0.3.6",
+    "langchain-experimental>=0.3.4",
+    "python-ulid>=2.7.0",
+    "pandas==2.2.3",
+    "hf-xet>=1.1.8",
+    "redisvl>=0.8.2",
+    "sentence-transformers>=5.1.0",
+    "langchain-redis>=0.2.3",
+]
+
+[project.urls]
+Repository = "https://github.com/redis-developer/redis-rag-workbench.git"
+"Bug Tracker" = "https://github.com/redis-developer/redis-rag-workbench/issues"
+
+[project.optional-dependencies]
+dev = [
+    "mypy<2.0.0,>=1.8.0",
+    "ruff<1.0.0,>=0.2.2",
+]
+
+[tool.ruff]
+target-version = "py38"
+
+[tool.ruff.lint]
+select = [
+    "E",  # pycodestyle errors
+    "W",  # pycodestyle warnings
+    "F",  # pyflakes
+    "I",  # isort
+    "B",  # flake8-bugbear
+    "C4",  # flake8-comprehensions
+    "UP",  # pyupgrade
+    "ARG001", # unused arguments in functions
+]
+ignore = [
+    "E501",  # line too long, handled by black
+    "B008",  # do not perform function calls in argument defaults
+    "W191",  # indentation contains tabs
+    "B904",  # Allow raising exceptions without from e, for HTTPException
+]
+
+[tool.ruff.lint.pyupgrade]
+# Preserve types, even if a file imports `from __future__ import annotations`.
+keep-runtime-typing = true

llm_hippocampus-0.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

llm_hippocampus-0.0.1/setup.py

@@ -0,0 +1,36 @@
+# -*- coding: utf-8 -*-
+
+from setuptools import setup, find_packages
+
+setup(
+    name="llm-hippocampus",  # 包的名字（PyPI 上必须唯一，重名会传不上去）
+    version="0.0.1",  # 版本号（格式：主版本.次版本.修订号，比如 0.0.1）
+    author="joelz",
+    author_email="zhongbj_26210@163.com",
+    description="llm-hippocampus",
+    long_description=open("README.md", encoding="utf-8").read(),  # 从 README 读取详细描述
+    long_description_content_type="text/markdown",  # 说明 README 是 Markdown 格式
+    url="",
+    packages=find_packages(),  # 自动找到所有包
+    classifiers=[  # 分类标签（帮助别人在 PyPI 上搜到你的包）
+    ],
+    python_requires=">=3.11",  # 支持的 Python 版本
+    install_requires=[  # 你的包依赖的其他包（比如需要 requests 就写进去）
+        "openai>=1.63.0",
+        "python-dotenv>=1.0.0",
+        "langchain>=0.3.19",
+        "tiktoken>=0.9.0",
+        "redis>=5.2.1",
+        "langchain-community>=0.3.18",
+        "langchain-huggingface>=0.1.2",
+        "langchain-openai>=0.3.6",
+        "langchain-experimental>=0.3.4",
+        "python-ulid>=2.7.0",
+        "pandas==2.2.3",
+        "hf-xet>=1.1.8",
+        "redisvl>=0.8.2",
+        "sentence-transformers>=5.1.0",
+        "langchain-redis>=0.2.3",
+    ]
+)
+