feat/redis cache connector: Add Redis Cache Connector with TTL, Namespacing, and Retry Support

packages/RedisCache/.gitignore

@@ -0,0 +1,137 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+lerna-debug.log*
+.pnpm-debug.log*
+
+# Diagnostic reports (https://nodejs.org/api/report.html)
+report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json
+
+# Runtime data
+pids
+*.pid
+*.seed
+*.pid.lock
+
+# Directory for instrumented libs generated by jscoverage/JSCover
+lib-cov
+
+# Coverage directory used by tools like istanbul
+coverage
+*.lcov
+
+# nyc test coverage
+.nyc_output
+
+# Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files)
+.grunt
+
+# Bower dependency directory (https://bower.io/)
+bower_components
+
+# node-waf configuration
+.lock-wscript
+
+# Compiled binary addons (https://nodejs.org/api/addons.html)
+build/Release
+
+# Dependency directories
+node_modules/
+jspm_packages/
+
+# Snowpack dependency directory (https://snowpack.dev/)
+web_modules/
+
+# TypeScript cache
+*.tsbuildinfo
+
+# Optional npm cache directory
+.npm
+
+# Optional eslint cache
+.eslintcache
+
+# Optional stylelint cache
+.stylelintcache
+
+# Microbundle cache
+.rpt2_cache/
+.rts2_cache_cjs/
+.rts2_cache_es/
+.rts2_cache_umd/
+
+# Optional REPL history
+.node_repl_history
+
+# Output of 'npm pack'
+*.tgz
+
+# Yarn Integrity file
+.yarn-integrity
+
+# dotenv environment variable files
+.env
+.env.development.local
+.env.test.local
+.env.production.local
+.env.local
+
+# parcel-bundler cache (https://parceljs.org/)
+.cache
+.parcel-cache
+
+# Next.js build output
+.next
+out
+
+# Nuxt.js build / generate output
+.nuxt
+dist
+
+# Gatsby files
+.cache/
+# Comment in the public line in if your project uses Gatsby and not Next.js
+# https://nextjs.org/blog/next-9-1#public-directory-support
+# public
+
+# vuepress build output
+.vuepress/dist
+
+# vuepress v2.x temp and cache directory
+.temp
+.cache
+
+# vitepress build output
+**/.vitepress/dist
+
+# vitepress cache directory
+**/.vitepress/cache
+
+# Docusaurus cache and generated files
+.docusaurus
+
+# Serverless directories
+.serverless/
+
+# FuseBox cache
+.fusebox/
+
+# DynamoDB Local files
+.dynamodb/
+
+# TernJS port file
+.tern-port
+
+# Stores VSCode versions used for testing VSCode extensions
+.vscode-test
+
+# yarn v2
+.yarn/cache
+.yarn/unplugged
+.yarn/build-state.yml
+.yarn/install-state.gz
+.pnp.*
+.smyth

packages/RedisCache/.prettierrc

@@ -0,0 +1,6 @@
+{
+    "tabWidth": 4,
+    "useTabs": false,
+    "singleQuote": true,
+    "printWidth": 150
+}

packages/RedisCache/.vscode/launch.json

@@ -0,0 +1,34 @@
+{
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "type": "node",
+            "request": "launch",
+            "name": "Debug index.ts",
+            "runtimeExecutable": "node",
+            "runtimeArgs": ["--experimental-strip-types", "--enable-source-maps"],
+            "program": "${workspaceFolder}/src/index.ts",
+            "skipFiles": ["<node_internals>/**", "**/node_modules/**"],
+            "outputCapture": "std",
+            "console": "integratedTerminal",
+            "sourceMaps": true,
+            "smartStep": false,
+            "resolveSourceMapLocations": ["${workspaceFolder}/../packages/**/*", "!**/node_modules/**"],
+            "envFile": "${workspaceFolder}/.env",
+            "env": {}
+        },
+        {
+            "type": "node",
+            "request": "launch",
+            "name": "Debug dist/index.js",
+            "skipFiles": ["<node_internals>/**"],
+            "program": "${workspaceFolder}/dist/index.js",
+            "args": [""],
+            "preLaunchTask": "",
+            "outFiles": ["${workspaceFolder}/dist/**/*.js"],
+            "outputCapture": "std",
+            "sourceMap": true,
+            "env": {}
+        }
+    ]
+}

packages/RedisCache/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 SmythOS
+
+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.

packages/RedisCache/README.md

@@ -0,0 +1,118 @@
+🚀 Redis Cache Connector for SmythOS
+
+This contribution adds a Redis cache connector for SmythOS SRE projects, plus a demo AI agent that shows how caching improves agent workflows.
+
+✨ Features
+
+set/get/del/keys/flushNamespace/quit API
+
+JSON auto-serialization & parsing
+
+TTL support (per key and global default)
+
+Namespacing to prevent collisions across agents
+
+Retries with exponential backoff for transient Redis errors
+
+TLS support (rediss:// or REDIS_TLS=true)
+
+Demo agent shows [CACHE MISS] / [CACHE HIT] in real time
+
+📦 Requirements
+
+Docker Desktop
+
+Node.js v18+
+
+(Optional) API keys for OpenAI or Google Gemini if you want to use real LLMs
+
+⚡ Quick Start
+1. Start Redis
+npm run redis:up
+npm run redis:ping   # expect "PONG"
+
+2. Run connector smoke test
+npm run redis:cache-check
+
+
+Expected output:
+
+get(hello) -> world
+get(obj) -> { a: 1, b: 'x' }
+keys(*) -> [ 'sre:check:hello', 'sre:check:obj' ]
+after del(hello) -> null
+✅ Connector smoke passed
+
+3. Run automated tests
+npm run test:redis
+
+
+✅ All 5 tests should pass.
+
+🤖 AI Agent Demo with Redis Cache
+
+The included demo agent wraps an LLM (OpenAI, Google Gemini, or a mock fallback) with the Redis cache connector. It shows how caching avoids recomputation.
+
+Run demo
+npm run agent:demo:prompt
+
+Example output
+first: 420.123ms
+[CACHE MISS] key=demo-llm:v1:abc123 → querying model...
+[CACHE STORE] key=demo-llm:v1:abc123 → saved with TTL=120s
+OUT 1: MOCK_SUMMARY: Summarize the value of caching with Redis in agent workflows
+
+second: 2.345ms
+[CACHE HIT] key=demo-llm:v1:abc123
+OUT 2: MOCK_SUMMARY: Summarize the value of caching with Redis in agent workflows
+
+✅ Demo complete (second call should be faster due to cache).
+
+
+OUT 1 → cache miss (model queried, slower)
+
+OUT 2 → cache hit (from Redis, instant)
+
+👉 This proves the benefit of caching in agent workflows: speed + cost savings + reliability.
+
+🔧 Configuration
+
+Set via .env.local or environment variables:
+
+Variable	Default	Notes
+REDIS_URL	redis://127.0.0.1:6379	Use rediss:// for TLS
+REDIS_NAMESPACE	sre:dev	Prefix added to all keys
+REDIS_TLS	false	Force TLS if needed
+REDIS_USERNAME	(none)	Redis ACL username
+REDIS_PASSWORD	(none)	Redis password
+REDIS_DEFAULT_TTL	(none)	Global TTL (seconds)
+OPENAI_API_KEY	(none)	Enables OpenAI adapter
+GOOGLEAI_API_KEY	(none)	Enables Google Gemini adapter
+OPENAI_MODEL	gpt-4o-mini	Optional override
+GOOGLEAI_MODEL	gemini-1.5-flash	Optional override
+
+If no API keys are provided, the demo uses a MockAdapter that produces deterministic fake summaries.
+
+📂 Project Structure
+src/
+  connectors/
+    redis/
+      index.ts          # Redis connector
+  utils/
+    retry.ts            # retry/backoff helper
+  agents/
+    cached-llm.ts       # Redis-cached wrapper for LLMs
+    adapters.ts         # OpenAI, Google, and Mock adapters
+scripts/
+  redis-cache-check.ts  # connector smoke test
+  demo-agent.ts         # AI agent demo with cache
+test/
+  redis.test.ts         # automated tests
+
+🔮 Future Extensions
+
+Batch methods (mget/mset) for efficiency
+
+Cache metrics (hit/miss counters, logging hooks)
+
+Async iterator with SCAN for large keyspaces