@bcelep/capint 0.4.2 → 0.7.0

package/skills/redis-development/rules/semantic-cache-best-practices.md

@@ -0,0 +1,72 @@
+---
+title: Configure Semantic Cache Properly
+impact: MEDIUM
+impactDescription: Correct threshold tuning balances hit rate vs accuracy
+tags: langcache, cache, threshold, ttl, semantic
+description: Configure Semantic Cache Properly
+alwaysApply: true
+---
+
+## Configure Semantic Cache Properly
+
+> **Note:** LangCache is currently in preview on Redis Cloud. Features and behavior may change.
+
+Tune similarity threshold and cache separation for optimal LangCache results.
+
+**Correct:** Tune similarity threshold for your use case.
+
+```python
+from langcache import LangCache
+
+lang_cache = LangCache(
+    server_url=f"https://{os.getenv('HOST')}",
+    cache_id=os.getenv("CACHE_ID"),
+    api_key=os.getenv("API_KEY")
+)
+
+# Stricter matching - fewer false positives (0.95 = very similar)
+result = lang_cache.search(
+    prompt="What is Redis?",
+    similarity_threshold=0.95
+)
+
+# Looser matching - higher hit rate (0.8 = somewhat similar)
+result = lang_cache.search(
+    prompt="What is Redis?",
+    similarity_threshold=0.8
+)
+```
+
+**Correct:** Use separate caches for different use cases.
+
+```python
+# Create different cache IDs in Redis Cloud for different LLM tasks
+support_cache = LangCache(
+    server_url=server_url,
+    cache_id="support-cache-id",
+    api_key=api_key
+)
+
+code_cache = LangCache(
+    server_url=server_url,
+    cache_id="code-cache-id",
+    api_key=api_key
+)
+```
+
+**Incorrect:** Using a single cache for all LLM tasks.
+
+```python
+# All tasks share one cache - responses may not be relevant
+result = lang_cache.search(prompt="How do I reset my password?")
+# Could return a code snippet if someone asked a similar coding question
+```
+
+**Best practices:**
+- Start with threshold 0.9, adjust based on your use case
+- Use custom attributes to filter results within a single cache
+- Monitor cache hit rates to evaluate effectiveness
+- Use separate cache IDs for fundamentally different LLM tasks
+
+Reference: [LangCache Best Practices](https://redis.io/docs/latest/develop/ai/langcache/)
+

package/skills/redis-development/rules/semantic-cache-langcache-usage.md

@@ -0,0 +1,86 @@
+---
+title: Use LangCache for LLM Response Caching
+impact: HIGH
+impactDescription: Reduces LLM API costs by 50-90% for similar queries
+tags: langcache, llm, semantic-cache, embeddings, ai
+description: Use LangCache for LLM Response Caching
+alwaysApply: true
+---
+
+## Use LangCache for LLM Response Caching
+
+> **Note:** LangCache is currently in preview on Redis Cloud. Features and behavior may change.
+
+LangCache is a fully-managed semantic caching service on Redis Cloud that reduces LLM costs and latency.
+
+**How it works:**
+1. Your app sends a prompt to LangCache via `POST /v1/caches/{cacheId}/entries/search`
+2. LangCache generates an embedding and searches for similar cached responses
+3. If found (cache hit), returns the cached response instantly
+4. If not found (cache miss), your app calls the LLM and stores the response
+
+**Correct:** Use the LangCache Python SDK.
+
+```python
+from langcache import LangCache
+import os
+
+lang_cache = LangCache(
+    server_url=f"https://{os.getenv('HOST')}",
+    cache_id=os.getenv("CACHE_ID"),
+    api_key=os.getenv("API_KEY")
+)
+
+# Search for cached response
+result = lang_cache.search(
+    prompt="What is Redis?",
+    similarity_threshold=0.9
+)
+
+if result:
+    response = result[0]["response"]
+else:
+    response = llm.generate("What is Redis?")
+    # Store for future queries
+    lang_cache.set(
+        prompt="What is Redis?",
+        response=response
+    )
+```
+
+**LangCache REST API:**
+
+```bash
+# Search cache
+curl -X POST "https://$HOST/v1/caches/$CACHE_ID/entries/search" \
+  -H "Authorization: Bearer $API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"prompt": "What is Redis?"}'
+
+# Store a response
+curl -X POST "https://$HOST/v1/caches/$CACHE_ID/entries" \
+  -H "Authorization: Bearer $API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"prompt": "What is Redis?", "response": "Redis is an in-memory database..."}'
+```
+
+**With custom attributes for filtering:**
+
+```python
+# Store with attributes
+lang_cache.set(
+    prompt="What is Redis?",
+    response="Redis is an in-memory database...",
+    attributes={"category": "database", "version": "v1"}
+)
+
+# Search with attribute filter
+result = lang_cache.search(
+    prompt="Tell me about Redis",
+    attributes={"category": "database"},
+    similarity_threshold=0.9
+)
+```
+
+Reference: [LangCache Documentation](https://redis.io/docs/latest/develop/ai/langcache/)
+

package/skills/redis-development/rules/stream-choosing-pattern.md

@@ -0,0 +1,44 @@
+---
+title: Choose Streams vs Pub/Sub Appropriately
+impact: MEDIUM
+impactDescription: Wrong choice leads to lost messages or unnecessary complexity
+tags: streams, pubsub, messaging, events, queues
+description: Choose Streams vs Pub/Sub Appropriately
+alwaysApply: true
+---
+
+## Choose Streams vs Pub/Sub Appropriately
+
+Redis supports two messaging approaches for different use cases.
+
+**Incorrect:** Using Pub/Sub when messages must not be lost.
+
+```python
+# Pub/Sub - messages lost if no subscribers connected
+r.publish("orders", json.dumps(order))  # Fire and forget!
+```
+
+**Correct:** Use Streams when message durability matters.
+
+```python
+# Streams - messages persist and can be replayed
+r.xadd("orders:stream", {"order": json.dumps(order)})
+
+# Consumer group for reliable processing
+r.xreadgroup("workers", "worker-1", {"orders:stream": ">"}, count=10)
+r.xack("orders:stream", "workers", message_id)
+```
+
+### When to Use Each
+
+| Requirement | Use |
+|-------------|-----|
+| Real-time notifications, OK to miss messages | Pub/Sub |
+| Messages must not be lost | Streams |
+| Need to replay/reprocess messages | Streams |
+| Multiple workers processing same queue | Streams (consumer groups) |
+| Simple broadcast to connected clients | Pub/Sub |
+| Event sourcing or audit trail | Streams |
+
+Reference: [Redis Streams](https://redis.io/docs/latest/develop/data-types/streams/)
+

package/skills/redis-development/rules/vector-algorithm-choice.md

@@ -0,0 +1,60 @@
+---
+title: Choose HNSW vs FLAT Based on Requirements
+impact: HIGH
+impactDescription: HNSW trades accuracy for speed, FLAT provides exact results
+tags: vector, hnsw, flat, algorithm, performance
+description: Choose HNSW vs FLAT Based on Requirements
+alwaysApply: true
+---
+
+## Choose HNSW vs FLAT Based on Requirements
+
+Select the right algorithm based on your accuracy requirements and dataset size.
+
+| Algorithm | Speed | Accuracy | Memory | Best For |
+|-----------|-------|----------|--------|----------|
+| HNSW | Fast (approximate) | ~95%+ recall tunable | Higher | Large datasets (>10k vectors) |
+| FLAT | Slower (exact) | 100% (exact) | Lower | Small datasets, accuracy-critical |
+
+**Correct:** Use HNSW for large-scale production workloads.
+
+```python
+from redisvl.schema import IndexSchema
+
+# HNSW - fast approximate search, tunable accuracy
+schema = IndexSchema.from_dict({
+    "index": {"name": "idx:docs", "prefix": "doc:"},
+    "fields": [
+        {"name": "embedding", "type": "vector", "attrs": {
+            "dims": 1536,
+            "algorithm": "HNSW",
+            "distance_metric": "COSINE",
+            "M": 16,                  # Higher = more accurate, more memory
+            "EF_CONSTRUCTION": 200    # Higher = better index quality, slower build
+        }}
+    ]
+})
+```
+
+**Correct:** Use FLAT when exact results are required.
+
+```python
+# FLAT - exact brute-force search, guaranteed accuracy
+schema = IndexSchema.from_dict({
+    "index": {"name": "idx:small", "prefix": "small:"},
+    "fields": [
+        {"name": "embedding", "type": "vector", "attrs": {
+            "dims": 1536,
+            "algorithm": "FLAT",
+            "distance_metric": "COSINE"
+        }}
+    ]
+})
+```
+
+**Tuning HNSW accuracy vs speed:**
+- `M`: Connections per node (16-64). Higher = better recall, more memory
+- `EF_CONSTRUCTION`: Build-time parameter (100-500). Higher = better graph quality
+- `EF_RUNTIME`: Query-time parameter. Higher = better recall, slower queries
+
+Reference: [Redis Vector Search](https://redis.io/docs/latest/develop/interact/search-and-query/advanced-concepts/vectors/)

package/skills/redis-development/rules/vector-hybrid-search.md

@@ -0,0 +1,49 @@
+---
+title: Use Hybrid Search for Better Results
+impact: MEDIUM
+impactDescription: Combining vector + filters improves relevance and reduces search space
+tags: vector, hybrid, filters, redisvl, search
+description: Use Hybrid Search for Better Results
+alwaysApply: true
+---
+
+## Use Hybrid Search for Better Results
+
+Combine vector similarity with attribute filtering for more relevant results.
+
+**Correct:** Apply filters to reduce search space.
+
+```python
+from redisvl.query import VectorQuery
+
+query = VectorQuery(
+    vector=query_embedding,
+    vector_field_name="embedding",
+    return_fields=["content", "category", "date"],
+    num_results=10,
+    filter_expression="@category:{technology} @date:[2024 2025]"
+)
+
+results = index.search(query)
+```
+
+**Incorrect:** Searching entire vector space when filters apply.
+
+```python
+# Bad: No filter - searches all vectors then filters client-side
+results = index.search(VectorQuery(
+    vector=query_embedding,
+    vector_field_name="embedding",
+    num_results=1000
+))
+# Client-side filtering - wasteful
+filtered = [r for r in results if r["category"] == "technology"]
+```
+
+**Tips:**
+- Use TAG fields for category filters
+- Use NUMERIC fields for date/price ranges
+- Filters are applied before vector search, reducing computation
+
+Reference: [Redis Hybrid Queries](https://redis.io/docs/latest/develop/interact/search-and-query/query/combined/)
+

package/skills/redis-development/rules/vector-index-creation.md

@@ -0,0 +1,83 @@
+---
+title: Configure Vector Indexes Properly
+impact: HIGH
+impactDescription: Correct configuration is essential for vector search accuracy
+tags: vector, index, hnsw, flat, embeddings, rqe
+description: Configure Vector Indexes Properly
+alwaysApply: true
+---
+
+## Configure Vector Indexes Properly
+
+Set the correct dimensions, algorithm, and distance metric for your embeddings. Vector indexes can be created via CLI, Redis Insight, or any client library.
+
+**Correct:** Create index via Redis CLI or Insight.
+
+```
+FT.CREATE idx:docs ON HASH PREFIX 1 doc:
+    SCHEMA
+        content TEXT
+        embedding VECTOR HNSW 6
+            TYPE FLOAT32
+            DIM 1536
+            DISTANCE_METRIC COSINE
+```
+
+**Correct:** Create index via Python (redis-py).
+
+```python
+from redis import Redis
+from redis.commands.search.field import TextField, VectorField
+
+r = Redis()
+
+# Define schema with vector field
+schema = [
+    TextField("content"),
+    VectorField(
+        "embedding",
+        algorithm="HNSW",
+        attributes={
+            "TYPE": "FLOAT32",
+            "DIM": 1536,  # Must match your embedding model
+            "DISTANCE_METRIC": "COSINE"
+        }
+    )
+]
+
+r.ft("idx:docs").create_index(schema, definition=IndexDefinition(prefix=["doc:"]))
+```
+
+**Correct:** Create index via RedisVL.
+
+```python
+from redisvl.index import SearchIndex
+from redisvl.schema import IndexSchema
+
+schema = IndexSchema.from_dict({
+    "index": {"name": "idx:docs", "prefix": "doc:"},
+    "fields": [
+        {"name": "content", "type": "text"},
+        {"name": "embedding", "type": "vector", "attrs": {
+            "dims": 1536,
+            "algorithm": "HNSW",
+            "distance_metric": "COSINE"
+        }}
+    ]
+})
+
+index = SearchIndex(schema)
+index.create(overwrite=True)
+```
+
+**Incorrect:** Mismatched dimensions or wrong distance metric.
+
+```python
+# Bad: Wrong dimensions for your model
+{"dims": 768}  # But using OpenAI which outputs 1536
+
+# Bad: Wrong metric for normalized embeddings
+{"distance_metric": "L2"}  # When embeddings are normalized for COSINE
+```
+
+Reference: [Redis Vector Search](https://redis.io/docs/latest/develop/interact/search-and-query/advanced-concepts/vectors/)

package/skills/redis-development/rules/vector-rag-pattern.md

@@ -0,0 +1,51 @@
+---
+title: Implement RAG Pattern Correctly
+impact: HIGH
+impactDescription: Proper RAG implementation improves LLM response quality
+tags: vector, rag, llm, embeddings, retrieval
+description: Implement RAG Pattern Correctly
+alwaysApply: true
+---
+
+## Implement RAG Pattern Correctly
+
+Store documents with embeddings, retrieve relevant context, and pass to LLM.
+
+**Correct:** Full RAG pipeline with RedisVL.
+
+```python
+from redisvl.index import SearchIndex
+from redisvl.query import VectorQuery
+
+# 1. Store documents with embeddings
+for doc in documents:
+    embedding = embed_model.encode(doc["content"])
+    index.load([{
+        "content": doc["content"],
+        "embedding": embedding.tolist(),
+        "source": doc["source"]
+    }])
+
+# 2. Query with vector similarity
+query_embedding = embed_model.encode(user_question)
+results = index.search(VectorQuery(
+    vector=query_embedding,
+    vector_field_name="embedding",
+    return_fields=["content", "source"],
+    num_results=5
+))
+
+# 3. Pass context to LLM
+context = "\n".join([r["content"] for r in results])
+response = llm.generate(f"Context: {context}\n\nQuestion: {user_question}")
+```
+
+**Best practices:**
+- Normalize vectors if using COSINE distance
+- Batch inserts using `index.load()` with lists
+- Set appropriate M and EF_CONSTRUCTION for HNSW based on dataset size
+- Use filters to reduce the search space before vector comparison
+- Consider chunking long documents for better retrieval
+
+Reference: [Redis RAG Quickstart](https://redis.io/docs/latest/develop/get-started/rag/)
+

package/skills/refactor/agents/verdent.yaml

@@ -0,0 +1,11 @@
+category: Development
+interface:
+  display_name: Code Refactor
+  short_description: Improve code structure without changing behavior.
+  icon_dark: './assets/icon-dark.png'
+  icon_light: './assets/icon-light.png'
+  default_prompt: Refactor this code for better maintainability.
+  label:
+    - refactor
+    - code-quality
+    - design-patterns

package/skills/runtime-inspector/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: runtime-inspector
+description: 分析运行时行为、进程边界和 IPC 机制，检测"协议漂移"风险和进程生命周期问题。
+---
+
+# 窃听者手册 (The Wiretapper's Casebook)
+
+> "代码会骗人，但进程不会。一个 `.spawn()` 暴露的比一千行注释还多。" —— 老窃听者箴言
+
+本技能的工作是**追踪进程间的通信线路**。
+
+**老师傅核心定律**: 如果两个进程说话，但没人规定它们说什么语言、什么版本、什么格式，那就是一场等待爆发的**协议漂移 (Protocol Mismatch)** 灾难。
+
+---
+
+## 深度思考要求
+
+> [!IMPORTANT]
+> **运行时分析需要深度思考，思考方式基于模型能力和任务复杂度。**
+> 
+> **核心判断规则**：
+> - **无 CoT 模型** → **必须调用** `sequential-thinking` CLI
+> - **有 CoT 模型 + 简单项目**（单进程、通信清晰）→ 用思考引导问题组织自然 CoT
+> - **有 CoT 模型 + 复杂项目**（多进程、需要修正前提）→ 调用 `sequential-thinking` CLI
+> 
+> 思考内容例如：
+> 1.  "这个项目有多少个入口点（`main` 函数）？它们是一个进程还是多个？"
+> 2.  "进程之间用什么通信？Pipe？HTTP？共享数据库？"
+> 3.  "如果我只更新了 A 进程的通信模块，B 进程会崩吗？有版本握手吗？"
+
+---
+
+## 任务目标
+识别**运行时边界 (Runtime Boundaries)** 和 **通信契约 (Communication Contracts)**。
+
+---
+
+## 探索流程 (The Investigation)
+
+### 第一步：识别入口点 (Identify Entry Points)
+每个 `main` 函数可能代表一个独立的进程。
+*   **搜索目标**:
+    *   Rust: `fn main()`, `#[tokio::main]`
+    *   Python: `if __name__ == "__main__":`
+    *   Node: `require.main === module`, package.json 的 `bin`
+    *   Go: `func main()`
+*   **老师傅直觉**: 找到多个入口点？立刻问："它们是独立运行的，还是被一个父进程管控的？"
+
+### 第二步：追踪生成链 (Trace Spawning)
+如果进程 A 拉起了进程 B，这就是一条"血缘线"。
+*   **搜索目标**:
+    *   Rust: `Command::new(...)`, `std::process::Stdio`, `tauri-plugin-shell`
+    *   Python: `subprocess.Popen`, `multiprocessing.Process`
+    *   Node: `child_process.spawn`, `child_process.fork`
+*   **老师傅警报 (Lifecycle Risks)**:
+    *    "父进程死了，子进程知道吗？有心跳吗？" -> **僵尸进程风险 (Zombie Child)**
+    *    "子进程崩溃了，父进程会重启它吗？还是静默失败？" -> **静默故障风险**
+
+### 第三步：窃听通信 (Tap the Wire)
+进程之间用什么"说话"？协议在哪里定义？
+
+*   **搜索 Channels (通道)**:
+    *   `Pipe`, `NamedPipe`, `unix_stream`, `zmq`
+    *   `TcpListener`, `UdpSocket`, `websocket`, `http::server`
+*   **搜索 Protocols (协议)**:
+    *   `Handshake`, `Version`, `MagicBytes`, `schema`
+    *   `protobuf`, `serde_json`, `JSON.parse`, `enum Message`
+
+*   **老师傅核心判断 (Contract Status)**:
+
+    | 发现 | 状态 | 老师傅建议 |
+    | :--- | :---: | :--- |
+    | 找到 Channel + 找到 `enum Message` 或 Protobuf 定义 |  **Strong** | 契约存在，相对安全。 |
+    | 找到 Channel + 找到 `Version` 或 `Handshake` 检查 |  **Strong** | 有版本协商，很好。 |
+    | 找到 Channel + 只有 raw JSON/字符串 |  **Weak** | 无显式契约。改动一端可能炸另一端。 |
+    | 找到 Channel + 无任何协议定义 |  **None** | **通信黑洞！** 这是高危风险。 |
+
+---
+
+## IPC 风险模式速查 (来自安全研究)
+
+| 风险模式 | 检测特征 | 老师傅建议 |
+| :--- | :--- | :--- |
+| **协议漂移 (Protocol Mismatch)** | Channel 存在，但无 Handshake/Version | 在新功能规划中**强制添加版本握手任务** |
+| **僵尸进程 (Zombie Child)** | `spawn` 存在，但无 `Kill on Drop` 或心跳 | 标记进程生命周期管理风险 |
+| **单点故障 (SPOF)** | 一个进程管控所有 IPC，无容错 | 建议添加重连/重启逻辑 |
+| **Named Pipe 权限漏洞 (Windows)** | 使用 Named Pipe 但未显式设置 Security Descriptor |  高危：默认可能允许 Everyone 访问！ |
+| **竞态条件 (Race Condition)** | 多进程快速交互，无明确的消息顺序控制 | 建议添加消息序列号或锁机制 |
+
+---
+
+## 输出清单
+
+1.  **Process Roots**: 发现的入口点列表（文件路径、角色）。
+2.  **Spawning Chains**: 进程生成关系 (A spawns B)。
+3.  **IPC Surfaces**: 发现的通信通道（类型、关键词、位置）。
+4.  **Contract Status**: `[Strong / Weak / None]`，并说明依据。
+5.  **Lifecycle Risks**: 僵尸进程、静默崩溃等风险。
+6.  **Security Flags (Windows)**: 如果是 Named Pipe，是否有 ACL 设置？