Sparksatchel

SparkSatchel 灵犀妙计

A Meta-Skill that provides intelligent skill retrieval and recommendation for Claude Code.

Core Philosophy

"Think twice before acting, keep the user burden-free"

Quick Start

from src.retriever import SparkSatchel

sparksatchel = SparkSatchel()
result = sparksatchel.retrieve("process this PDF")

Decision Mechanism

The system evaluates confidence and responds accordingly:

Key Features

1. Semantic Retrieval

• Bilingual embeddings: Supports Chinese and English via paraphrase-multilingual-MiniLM-L12-v2
• Sharded storage: Skills organized by category for efficient retrieval
• Vector similarity: Matches user intent to skill descriptions

2. Intent Analysis

Extracts from user requests:

• Primary intent
• Keywords
• Entities (filenames, formats, etc.)

3. Historical Learning

• Tracks all skill calls
• Records success/failure feedback
• Calculates skill success rates
• Optimizes recommendation ranking

4. Health Checking

• Detects missing skills
• Identifies corrupted skills
• Handles version mismatches
• Provides fallback strategies

5. Cache Management

• Monitors database size
• Tracks record count
• Suggests cleanup when needed
• Supports auto/manual cleanup

Usage Examples

High Confidence (Auto-recommend)

User: "Process this PDF"
SparkSatchel: "I recommend pdf-skill because it specializes in PDF documents (92% historical success rate)"

Medium Confidence (With alternatives)

User: "Create a document"
SparkSatchel: "I suggest docx-skill. pdf-skill is also available. Want me to compare them?"

Low Confidence (Ask user)

User: "Process data"
SparkSatchel: "Found several matching skills. Which one fits best?
- xlsx-skill: Excel spreadsheet processing
- pandas-skill: Data analysis with Python
- csv-skill: CSV file handling"

Embedding Models

Pre-installed Model (Ready to Use)

SparkSatchel comes with a pre-downloaded bilingual embedding model:

• Model: paraphrase-multilingual-MiniLM-L12-v2
• Size: ~470MB
• Languages: 50+ including Chinese and English
• Dimension: 384
• Status: ✅ Pre-downloaded, ready to use out-of-the-box
• Location: ~/.cache/huggingface/hub/

The default model provides good balance between:

• ✅ Bilingual support (Chinese + English)
• ✅ Lightweight size
• ✅ Fast inference
• ✅ Offline capability

Model Selection Guide

Choose the right model based on your scenario:

Model Comparison

Scenario Recommendations

Quick Download with Script

Use the provided download script for convenience:

# List available models
python scripts/download_model.py --list

# Download default model (already downloaded ✅)
python scripts/download_model.py default

# Download Chinese-optimized model
python scripts/download_model.py chinese

# Download high-accuracy multilingual model
python scripts/download_model.py large

# Download ultra-lightweight English model
python scripts/download_model.py english

Scenario 1: Chinese-dominant environment

# Option A: Use download script
python scripts/download_model.py chinese

# Option B: Manual download
pip install sentence-transformers
python -c "from sentence_transformers import SentenceTransformer; SentenceTransformer('shibing624/text2vec-base-chinese')"

Scenario 2: English-only (fastest)

# Option A: Use download script
python scripts/download_model.py english

# Option B: Manual download
pip install sentence-transformers
python -c "from sentence_transformers import SentenceTransformer; SentenceTransformer('all-MiniLM-L6-v2')"

Scenario 3: Maximum accuracy (multilingual)

# Download high-accuracy model
pip install sentence-transformers
python -c "from sentence_transformers import SentenceTransformer; SentenceTransformer('intfloat/multilingual-e5-large')"

Scenario 4: Cloud-based (no local storage)

# Use OpenAI API (requires API key)
pip install openai

How to Switch Models

Option 1: Modify code (permanent)

Edit src/models/embedding.py:

class EmbeddingModel:
    # Change default model
    DEFAULT_MODEL = "shibing624/text2vec-base-chinese"  # Your choice

Option 2: Pass model name (temporary)

from src.models.embedding import EmbeddingModel
from src.retriever import SparkSatchel

# Use custom model
custom_model = EmbeddingModel(
    model_name="shibing624/text2vec-base-chinese",
    device="cpu"  # or "cuda" for GPU acceleration
)

# Pass to SparkSatchel
sparksatchel = SparkSatchel(embedding_model=custom_model)

Option 3: Use OpenAI API

import openai

def openai_embedding(text: str) -> list:
    response = openai.Embedding.create(
        model="text-embedding-3-small",
        input=text
    )
    return response['data'][0]['embedding']

Model Performance Tips

1. GPU Acceleration: If you have NVIDIA GPU, use device="cuda" for 5-10x speedup
2. Batch Processing: Process multiple texts at once for better throughput
3. Caching: Models are cached after first download, no re-downloading needed
4. Quantization: For memory-constrained environments, use 8-bit quantized models

Project Structure

SparkSatchel/
├── SKILL.md              # This file
├── requirements.txt      # Dependencies
├── src/
│   ├── retriever.py      # Main entry point
│   ├── models/           # Embedding models
│   ├── storage/          # Vector DB + history
│   ├── analysis/         # Intent + confidence
│   └── maintenance/      # Health + lifecycle + cache
└── data/                 # Data storage
    ├── collections/      # Vector databases
    └── history.db        # Call history

API Reference

Main Interface

class SparkSatchel:
    def retrieve(self, user_request: str) -> RetrievalResult:
        """Search and recommend skills"""

    def feedback(self, skill_name: str, success: bool, feedback: str = ""):
        """Record user feedback"""

    def check_health(self) -> Dict:
        """Check system health"""

    def cleanup(self, strategy: dict = None):
        """Execute cache cleanup"""

Retrieval Result

@dataclass
class RetrievalResult:
    confidence: float              # 0-1
    recommended_skill: str         # Skill name
    reasoning: str                 # Explanation
    alternative_skills: List[str]  # For medium confidence
    candidate_skills: List[Dict]   # For low confidence
    requires_confirmation: bool    # Needs user input?

Maintenance

Check Health

health = sparksatchel.check_health()
if health["cache"]["needs_cleanup"]:
    print(health["suggestion"])

Cleanup Cache

from src.maintenance.cache import CleanupStrategy

# By age (delete records older than 30 days)
sparksatchel.cleanup(CleanupStrategy.by_age(days=30))

# By count (keep recent 1000 records)
sparksatchel.cleanup(CleanupStrategy.by_count(keep=1000))

Tech Stack

• Python: 3.10+
• Vector DB: ChromaDB
• Embedding: sentence-transformers
• History: SQLite

Performance