@bcelep/capint 0.4.2 → 0.6.5

package/skills/redis-development/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: redis-development
+description: Redis performance optimization and best practices. Use this skill when working with Redis data structures, Redis Query Engine (RQE), vector search with RedisVL, semantic caching with LangCache, or optimizing Redis performance.
+license: MIT
+metadata:
+  author: redis
+  version: "1.0.1"
+origin: verdent
+prismx_bundle: verdent
+prismx_imported_at: 2026-05-27
+---
+
+# Redis Best Practices
+
+Comprehensive performance optimization guide for Redis, including Redis Query Engine, vector search, and semantic caching. Contains 29 rules across 11 categories, prioritized by impact to guide automated optimization and code generation.
+
+## When to Apply
+
+Reference these guidelines when:
+- Designing Redis data models and key structures
+- Implementing caching, sessions, or real-time features
+- Using Redis Query Engine (FT.CREATE, FT.SEARCH, FT.AGGREGATE)
+- Building vector search or RAG applications with RedisVL
+- Implementing semantic caching with LangCache
+- Optimizing Redis performance and memory usage
+
+## Rule Categories by Priority
+
+| Priority | Category | Impact | Prefix |
+|----------|----------|--------|--------|
+| 1 | Data Structures & Keys | HIGH | `data-` |
+| 2 | Memory & Expiration | HIGH | `ram-` |
+| 3 | Connection & Performance | HIGH | `conn-` |
+| 4 | JSON Documents | MEDIUM | `json-` |
+| 5 | Redis Query Engine | HIGH | `rqe-` |
+| 6 | Vector Search & RedisVL | HIGH | `vector-` |
+| 7 | Semantic Caching | MEDIUM | `semantic-cache-` |
+| 8 | Streams & Pub/Sub | MEDIUM | `stream-` |
+| 9 | Clustering & Replication | MEDIUM | `cluster-` |
+| 10 | Security | HIGH | `security-` |
+| 11 | Observability | MEDIUM | `observe-` |
+
+## Quick Reference
+
+### 1. Data Structures & Keys (HIGH)
+
+- `data-choose-structure` - Choose the Right Data Structure
+- `data-key-naming` - Use Consistent Key Naming Conventions
+
+### 2. Memory & Expiration (HIGH)
+
+- `ram-limits` - Configure Memory Limits and Eviction Policies
+- `ram-ttl` - Set TTL on Cache Keys
+
+### 3. Connection & Performance (HIGH)
+
+- `conn-blocking` - Avoid Slow Commands in Production
+- `conn-pipelining` - Use Pipelining for Bulk Operations
+- `conn-pooling` - Use Connection Pooling or Multiplexing
+- `conn-timeouts` - Configure Connection Timeouts
+
+### 4. JSON Documents (MEDIUM)
+
+- `json-partial-updates` - Use JSON Paths for Partial Updates
+- `json-vs-hash` - Choose JSON vs Hash Appropriately
+
+### 5. Redis Query Engine (HIGH)
+
+- `rqe-dialect` - Use DIALECT 2 for Query Syntax
+- `rqe-field-types` - Choose the Correct Field Type
+- `rqe-index-creation` - Index Only Fields You Query
+- `rqe-index-management` - Manage Indexes for Zero-Downtime Updates
+- `rqe-query-optimization` - Write Efficient Queries
+
+### 6. Vector Search & RedisVL (HIGH)
+
+- `vector-algorithm-choice` - Choose HNSW vs FLAT Based on Requirements
+- `vector-hybrid-search` - Use Hybrid Search for Better Results
+- `vector-index-creation` - Configure Vector Indexes Properly
+- `vector-rag-pattern` - Implement RAG Pattern Correctly
+
+### 7. Semantic Caching (MEDIUM)
+
+- `semantic-cache-best-practices` - Configure Semantic Cache Properly
+- `semantic-cache-langcache-usage` - Use LangCache for LLM Response Caching
+
+### 8. Streams & Pub/Sub (MEDIUM)
+
+- `stream-choosing-pattern` - Choose Streams vs Pub/Sub Appropriately
+
+### 9. Clustering & Replication (MEDIUM)
+
+- `cluster-hash-tags` - Use Hash Tags for Multi-Key Operations
+- `cluster-read-replicas` - Use Read Replicas for Read-Heavy Workloads
+
+### 10. Security (HIGH)
+
+- `security-acls` - Use ACLs for Fine-Grained Access Control
+- `security-auth` - Always Use Authentication in Production
+- `security-network` - Secure Network Access
+
+### 11. Observability (MEDIUM)
+
+- `observe-commands` - Use Observability Commands for Debugging
+- `observe-metrics` - Monitor Key Redis Metrics
+
+## How to Use
+
+Read individual rule files for detailed explanations and code examples:
+
+```
+rules/rqe-index-creation.md
+rules/vector-rag-pattern.md
+```
+
+Each rule file contains:
+- Brief explanation of why it matters
+- Correct example(s) with explanation
+- Either an "Incorrect" example (for anti-patterns that cause real harm) or "When to use / When NOT needed" guidance (for optional features)
+- Additional context and references
+
+## Full Compiled Document
+
+For the complete guide with all rules expanded: `FULL_GUIDE.md`

package/skills/redis-development/agents/verdent.yaml

@@ -0,0 +1,12 @@
+category: Backend
+interface:
+  display_name: Redis Best Practices
+  short_description: Optimize Redis data structures, queries, and caching.
+  icon_dark: './assets/icon-dark.png'
+  icon_light: './assets/icon-light.png'
+  default_prompt: Help me optimize my Redis usage.
+  label:
+    - redis
+    - database
+    - caching
+    - performance

package/skills/redis-development/rules/_contributing.md

@@ -0,0 +1,97 @@
+# Writing Guidelines for Redis Rules
+
+Guidelines for creating effective Redis best practice rules for AI agents and LLMs.
+
+## Key Principles
+
+### 1. Concrete Patterns
+
+Show exact code transformations. Avoid abstract advice.
+
+**Good:** "Use `SCAN` instead of `KEYS *` for iteration"
+**Bad:** "Design efficient queries"
+
+### 2. Problem-First Structure
+
+Show the correct pattern first, then the incorrect one. This helps agents understand what to do and what to avoid.
+
+```markdown
+**Correct:** Description of good approach.
+
+[good example]
+
+**Incorrect:** Description of problematic approach.
+
+[bad example]
+```
+
+### 3. Practical Impact
+
+Include specific benefits. Helps agents prioritize.
+
+**Good:** "10x faster", "50% less memory", "Eliminates blocking"
+**Bad:** "Faster", "Better", "More efficient"
+
+### 4. Complete Examples
+
+Examples should be runnable or close to it.
+
+```python
+import redis
+
+# Include setup when needed for clarity
+pool = redis.ConnectionPool(host='localhost', max_connections=50)
+r = redis.Redis(connection_pool=pool)
+
+# Now show the pattern
+result = r.get('user:1001')
+```
+
+### 5. Semantic Naming
+
+Use meaningful names. Names carry intent for LLMs.
+
+**Good:** `user:1001:profile`, `order:items`, `cache:api:response`
+**Bad:** `key1`, `mykey`, `data`
+
+---
+
+## Code Standards
+
+### Language Tags
+
+- `python` - Python examples (preferred for Redis)
+- `javascript` - Node.js examples
+- `bash` - Redis CLI commands
+- (none) - Redis commands without language wrapper
+
+### Comments
+
+- Explain _why_, not _what_
+- Highlight performance implications
+- Point out common mistakes
+
+---
+
+## Impact Levels
+
+| Level | Improvement | Examples |
+|-------|-------------|----------|
+| **HIGH** | 5-100x | Missing indexes, connection issues, blocking commands |
+| **MEDIUM** | 2-5x | Suboptimal data structures, missing TTL |
+| **LOW** | Incremental | Advanced patterns, edge cases |
+
+---
+
+## Review Checklist
+
+Before submitting a rule:
+
+- [ ] Title is clear and action-oriented
+- [ ] Impact level matches the benefit
+- [ ] impactDescription includes quantification
+- [ ] Has at least 1 **Correct** example
+- [ ] Has at least 1 **Incorrect** example
+- [ ] Code uses semantic naming
+- [ ] Comments explain _why_
+- [ ] Reference links included

package/skills/redis-development/rules/_sections.md

@@ -0,0 +1,50 @@
+# Section Definitions
+
+This file defines the rule categories for Redis best practices. Rules are automatically assigned to sections based on their filename prefix.
+
+---
+
+## 1. Data Structures & Keys (data)
+**Impact:** HIGH
+**Description:** Choosing the right Redis data type and key naming conventions. Foundation for efficient Redis usage.
+
+## 2. Memory & Expiration (ram)
+**Impact:** HIGH
+**Description:** Memory limits, eviction policies, TTL strategies, and memory optimization techniques.
+
+## 3. Connection & Performance (conn)
+**Impact:** HIGH
+**Description:** Connection pooling, pipelining, timeouts, and avoiding blocking commands.
+
+## 4. JSON Documents (json)
+**Impact:** MEDIUM
+**Description:** Using Redis JSON for nested structures, partial updates, and integration with RQE.
+
+## 5. Redis Query Engine (rqe)
+**Impact:** HIGH
+**Description:** FT.CREATE, FT.SEARCH, FT.AGGREGATE, index design, field types, and query optimization.
+
+## 6. Vector Search & RedisVL (vector)
+**Impact:** HIGH
+**Description:** Vector indexes, HNSW vs FLAT, hybrid search, and RAG patterns with RedisVL.
+
+## 7. Semantic Caching (semantic-cache)
+**Impact:** MEDIUM
+**Description:** LangCache for LLM response caching, distance thresholds, and cache strategies.
+
+## 8. Streams & Pub/Sub (stream)
+**Impact:** MEDIUM
+**Description:** Choosing between Streams and Pub/Sub for messaging patterns.
+
+## 9. Clustering & Replication (cluster)
+**Impact:** MEDIUM
+**Description:** Hash tags for key colocation, read replicas, and cluster-aware patterns.
+
+## 10. Security (security)
+**Impact:** HIGH
+**Description:** Authentication, ACLs, TLS, and network security.
+
+## 11. Observability (observe)
+**Impact:** MEDIUM
+**Description:** SLOWLOG, INFO, MEMORY commands, monitoring metrics, and Redis Insight.
+

package/skills/redis-development/rules/_template.md

@@ -0,0 +1,52 @@
+---
+title: Clear, Action-Oriented Title (e.g., "Use Connection Pooling")
+impact: MEDIUM
+impactDescription: Brief quantified benefit (e.g., "Reduces connection overhead by 10x")
+tags: relevant, keywords, here
+description: Clear, Action-Oriented Title (e.g., "Use Connection Pooling")
+alwaysApply: true
+---
+
+## [Rule Title]
+
+[1-2 sentence explanation of the problem and why it matters. Focus on practical impact.]
+
+**Correct:** Description of the good approach.
+
+```python
+# Comment explaining why this is better
+pool = ConnectionPool(host='localhost', max_connections=50)
+redis = Redis(connection_pool=pool)  # Reuse connections
+result = redis.get('key')
+```
+
+---
+### Choose ONE of the following patterns:
+
+#### Pattern A: "Incorrect" (when alternative causes real harm)
+Use when the alternative causes race conditions, security issues, crashes, or significant performance problems.
+
+**Incorrect:** Description of the problematic approach.
+
+```python
+# Comment explaining what makes this problematic
+redis = Redis(host='localhost')  # New connection per request - 10x overhead
+result = redis.get('key')
+```
+
+#### Pattern B: "When to use" (for feature introductions)
+Use when not using the feature is a valid choice for many use cases.
+
+**When to use:**
+- Scenario where this approach is beneficial
+- Another scenario where it helps
+
+**When NOT needed:**
+- Scenario where the simpler approach is fine
+- Another scenario where this adds unnecessary complexity
+
+---
+
+[Optional: Additional context, edge cases, or trade-offs]
+
+Reference: [Redis Docs](https://redis.io/docs/)

package/skills/redis-development/rules/cluster-hash-tags.md

@@ -0,0 +1,78 @@
+---
+title: Use Hash Tags for Multi-Key Operations
+impact: HIGH
+impactDescription: Enables multi-key operations in Redis Cluster
+tags: cluster, hash-tags, keys, sharding, multi-key
+description: Use Hash Tags for Multi-Key Operations
+alwaysApply: true
+---
+
+## Use Hash Tags for Multi-Key Operations
+
+In Redis Cluster, keys are distributed across slots based on their hash. Use hash tags to ensure keys that must be used together in [multi-key operations](https://redis.io/docs/latest/operate/rs/databases/durability-ha/clustering/#multikey-operations) are on the same slot.
+
+**Correct:** Use hash tags for keys used in multi-key operations.
+
+**Python** (redis-py):
+```python
+# These keys go to the same slot because {user:1001} is the hash tag
+redis.set("{user:1001}:profile", "...")
+redis.set("{user:1001}:settings", "...")
+redis.set("{user:1001}:cart", "...")
+
+# Now you can use transactions and pipelines
+pipe = redis.pipeline()
+pipe.get("{user:1001}:profile")
+pipe.get("{user:1001}:settings")
+pipe.execute()
+
+# Multi-key commands also work
+redis.lmove("{user:1001}:pending", "{user:1001}:processed", "LEFT", "RIGHT")
+```
+
+**Java** (Jedis):
+```java
+import redis.clients.jedis.UnifiedJedis;
+import java.util.Set;
+
+try (UnifiedJedis jedis = new UnifiedJedis("redis://localhost:6379")) {
+    // Hash tags ensure keys go to the same slot
+    jedis.sadd("{bikes:racing}:france", "bike:1", "bike:2", "bike:3");
+    jedis.sadd("{bikes:racing}:usa", "bike:1", "bike:4");
+
+    // Multi-key operation works because of matching hash tags
+    Set<String> result = jedis.sdiff("{bikes:racing}:france", "{bikes:racing}:usa");
+}
+```
+
+**Incorrect:** Keys without hash tags that need multi-key operations.
+
+**Python** (redis-py):
+```python
+# Bad: These may be on different slots
+redis.set("user:1001:profile", "...")  # No hash tag
+redis.set("user:1001:settings", "...")
+
+# This will fail in cluster mode
+pipe = redis.pipeline()
+pipe.get("user:1001:profile")
+pipe.get("user:1001:settings")
+pipe.execute()  # CROSSSLOT error
+```
+
+**Java** (Jedis):
+```java
+// Bad: No hash tags - keys may be on different slots
+jedis.sadd("bikes:racing:france", "bike:1", "bike:2", "bike:3");
+jedis.sadd("bikes:racing:usa", "bike:1", "bike:4");
+
+// This will fail in cluster mode with CROSSSLOT error
+Set<String> result = jedis.sdiff("bikes:racing:france", "bikes:racing:usa");
+```
+
+**Hash tag rules:**
+- Only the part between `{` and `}` is hashed for slot assignment
+- Use meaningful identifiers like `{user:1001}` not just `{1001}` to avoid unrelated keys (e.g., `purchase:{1001}`, `employee:{1001}`) saturating the same slot
+- Use hash tags only where multi-key operations are needed, not as a general habit
+
+Reference: [Redis Cluster Key Distribution](https://redis.io/docs/latest/operate/oss_and_stack/reference/cluster-spec/#hash-tags)

package/skills/redis-development/rules/cluster-read-replicas.md

@@ -0,0 +1,55 @@
+---
+title: Use Read Replicas for Read-Heavy Workloads
+impact: MEDIUM
+impactDescription: Scales read throughput without adding primary nodes
+tags: cluster, replicas, read-scaling, high-availability
+description: Use Read Replicas for Read-Heavy Workloads
+alwaysApply: true
+---
+
+## Use Read Replicas for Read-Heavy Workloads
+
+For read-heavy workloads, distribute reads across replicas to reduce load on primaries.
+
+**Correct:** Configure replica reads in Redis Cluster.
+
+```python
+from redis.cluster import RedisCluster
+
+rc = RedisCluster(
+    host='localhost',
+    port=6379,
+    read_from_replicas=True  # Distribute reads to replicas
+)
+
+# Writes go to primary
+rc.set("key", "value")
+
+# Reads can be served by replicas (eventually consistent)
+value = rc.get("key")
+```
+
+**Correct:** Use replica reads in standalone replication setup.
+
+```python
+from redis import Redis
+
+# Connect to primary for writes
+primary = Redis(host='primary-host', port=6379)
+
+# Connect to replica for reads
+replica = Redis(host='replica-host', port=6379)
+
+# Write to primary
+primary.set("key", "value")
+
+# Read from replica (eventually consistent)
+value = replica.get("key")
+```
+
+**Considerations:**
+- Replica reads are eventually consistent
+- Don't read from replicas for data that was just written
+- Use for read-heavy, slightly-stale-OK workloads (caches, analytics, dashboards)
+
+Reference: [Redis Replication](https://redis.io/docs/latest/operate/oss_and_stack/management/replication/)

package/skills/redis-development/rules/conn-blocking.md

@@ -0,0 +1,75 @@
+---
+title: Avoid Slow Commands in Production
+impact: HIGH
+impactDescription: Prevents Redis from becoming unresponsive
+tags: slow-commands, keys, scan, performance
+description: Avoid Slow Commands in Production
+alwaysApply: true
+---
+
+## Avoid Slow Commands in Production
+
+Some Redis commands are slow because they scan large datasets. Use incremental alternatives to avoid blocking the server.
+
+| Avoid | Use Instead |
+|-------|-------------|
+| `KEYS *` | `SCAN` with cursor |
+| `SMEMBERS` on large sets | `SSCAN` |
+| `HGETALL` on large hashes | `HSCAN` |
+| `LRANGE 0 -1` on large lists | Paginate with `LRANGE 0 100` |
+
+**Correct:** Use SCAN for iteration.
+
+**Python** (redis-py):
+```python
+# Good: Non-blocking iteration
+cursor = 0
+while True:
+    cursor, keys = redis.scan(cursor, match="user:*", count=100)
+    for key in keys:
+        process(key)
+    if cursor == 0:
+        break
+```
+
+**Java** (Jedis):
+```java
+import redis.clients.jedis.ScanIteration;
+import redis.clients.jedis.UnifiedJedis;
+import java.util.List;
+
+try (UnifiedJedis jedis = new UnifiedJedis("redis://localhost:6379")) {
+    // ScanIteration manages the cursor automatically
+    ScanIteration scan = jedis.scanIteration(10, "user:*", "hash");
+
+    while (!scan.isIterationCompleted()) {
+        List<String> result = scan.nextBatch().getResult();
+        for (String key : result) {
+            process(key);
+        }
+    }
+}
+```
+
+**Incorrect:** Using KEYS in production.
+
+**Python** (redis-py):
+```python
+# Bad: Scans all keys, slow on large datasets
+keys = redis.keys("user:*")
+```
+
+**Java** (Jedis):
+```java
+// Bad: Scans all keys, blocks the server
+Set<String> result = jedis.keys("*");
+```
+
+**Note:** Truly blocking commands (like `BLPOP`, `BRPOP`, `BLMOVE`) that wait indefinitely for data are appropriate for some use cases like job queues, but should be used with timeouts.
+
+```python
+# Blocking pop with timeout - appropriate for queue consumers
+result = redis.blpop("task_queue", timeout=5)
+```
+
+Reference: [Redis SCAN](https://redis.io/docs/latest/commands/scan/)

package/skills/redis-development/rules/conn-client-cache.md

@@ -0,0 +1,70 @@
+---
+title: Use Client-Side Caching for Frequently Read Data
+impact: HIGH
+impactDescription: Reduces network round-trips for repeated reads
+tags: caching, performance, client-side, tracking
+description: Use Client-Side Caching for Frequently Read Data
+alwaysApply: true
+---
+
+## Use Client-Side Caching for Frequently Read Data
+
+Use a connection with client-side caching enabled for any data that will be read frequently but written only occasionally. Client-side caching avoids contacting the server for repeated access to data that has recently been read, reducing network traffic and improving performance.
+
+**Correct:** Enable client-side caching with RESP3 protocol for frequently accessed data.
+
+**Python** (redis-py):
+```python
+import redis
+
+# Enable client-side caching with RESP3
+client = redis.Redis(
+    host='localhost',
+    port=6379,
+    protocol=3,  # RESP3 required for client-side caching
+    cache_config=redis.CacheConfig(max_size=1000)
+)
+
+# Cached reads avoid server round-trips
+value = client.get("frequently:read:key")
+```
+
+**Java** (Jedis):
+```java
+import redis.clients.jedis.DefaultJedisClientConfig;
+import redis.clients.jedis.UnifiedJedis;
+import redis.clients.jedis.HostAndPort;
+import redis.clients.jedis.CacheConfig;
+
+HostAndPort endpoint = new HostAndPort("localhost", 6379);
+
+DefaultJedisClientConfig config = DefaultJedisClientConfig
+    .builder()
+    .password("secretPassword")
+    .protocol(RedisProtocol.RESP3)
+    .build();
+
+CacheConfig cacheConfig = CacheConfig.builder().maxSize(1000).build();
+
+UnifiedJedis client = new UnifiedJedis(endpoint, config, cacheConfig);
+```
+
+**When to use:**
+- Configuration data read frequently, updated rarely
+- User session data accessed on every request
+- Feature flags or settings checked repeatedly
+- Any read-heavy workload with low write frequency
+
+**When NOT needed:**
+- Data that changes frequently (cache invalidation overhead outweighs benefits)
+- Write-heavy workloads
+- Simple applications where network latency is not a bottleneck
+- When you need guaranteed real-time consistency
+
+**Trade-offs:**
+- Adds memory overhead on the client
+- Requires RESP3 protocol
+- Cache invalidation adds complexity for frequently changing data
+
+Reference: [Client-side caching](https://redis.io/docs/latest/develop/clients/client-side-caching/)
+

package/skills/redis-development/rules/conn-pipelining.md

@@ -0,0 +1,58 @@
+---
+title: Use Pipelining for Bulk Operations
+impact: HIGH
+impactDescription: Reduces round trips, 5-10x faster for batch operations
+tags: pipelining, batch, performance, round-trips
+description: Use Pipelining for Bulk Operations
+alwaysApply: true
+---
+
+## Use Pipelining for Bulk Operations
+
+Batch multiple commands into a single round trip to reduce network latency.
+
+**Correct:** Use pipeline for multiple commands.
+
+**Python** (redis-py):
+```python
+# Good: Single round trip for multiple commands
+pipe = redis.pipeline()
+for user_id in user_ids:
+    pipe.get(f"user:{user_id}")
+results = pipe.execute()
+```
+
+**Java** (Jedis):
+```java
+import redis.clients.jedis.Pipeline;
+
+// Good: Buffer commands and send as single batch
+Pipeline pipe = (Pipeline) jedis.pipelined();
+
+pipe.set("person:1:name", "Alex");
+pipe.set("person:1:rank", "Captain");
+pipe.set("person:1:serial", "AB1234");
+
+pipe.sync();
+```
+
+**Incorrect:** Sequential commands in a loop.
+
+**Python** (redis-py):
+```python
+# Bad: N round trips
+results = []
+for user_id in user_ids:
+    results.append(redis.get(f"user:{user_id}"))
+```
+
+**Java** (Jedis):
+```java
+// Bad: 3 separate round trips
+jedis.set("person:1:name", "Alex");
+jedis.set("person:1:rank", "Captain");
+jedis.set("person:1:serial", "AB1234");
+```
+
+Reference: [Redis Pipelining](https://redis.io/docs/latest/develop/use/pipelining/)
+