stravinsky 0.4.18__py3-none-any.whl → 0.4.66__py3-none-any.whl

stravinsky_claude_assets/commands/str/agent_retry.md

@@ -0,0 +1,94 @@
+---
+description: Retry a failed or cancelled background agent with the same prompt
+allowed-tools: mcp__stravinsky__agent_retry, mcp__stravinsky__agent_spawn
+---
+
+# Retry Background Agent
+
+Retry a failed or cancelled agent with the exact same prompt and configuration.
+
+## What This Does
+
+Creates a new agent task with the same:
+- Agent type
+- Prompt
+- Description
+- Model (if specified)
+
+Returns a new task ID for the retried agent.
+
+## Usage
+
+```python
+# Retry a failed agent
+agent_retry(task_id="task_001")
+```
+
+## Parameters
+
+- `task_id`: The task ID of the failed/cancelled agent to retry
+
+## When to Retry
+
+- **Transient failures**: Network timeout, API rate limit, temporary service outage
+- **Fixed environment**: Ollama was down, now it's running
+- **Cancelled by mistake**: Accidentally cancelled a needed agent
+- **Resource contention**: Agent failed due to too many concurrent operations
+
+## Example Workflow
+
+```python
+# 1. Spawn agent
+task_1 = agent_spawn(
+    agent_type="explore",
+    prompt="Find authentication code",
+    description="Auth search"
+)
+
+# 2. Agent fails (e.g., network error)
+agent_list()  # Shows task_001: failed
+
+# 3. Fix issue (e.g., restart network)
+
+# 4. Retry with same configuration
+retry_result = agent_retry(task_id=task_1["task_id"])
+new_task_id = retry_result["task_id"]
+
+# 5. Monitor new agent
+agent_progress(task_id=new_task_id)
+result = agent_output(task_id=new_task_id, block=True)
+```
+
+## Output
+
+```
+♻️ Retrying agent task_001 (explore - Auth search)
+New task ID: task_004
+Agent started with same configuration
+```
+
+## Error Handling
+
+```python
+# Pattern: Retry on failure
+try:
+    result = agent_output(task_id="task_001", block=True)
+except Exception as e:
+    print(f"Agent failed: {e}")
+    retry = agent_retry(task_id="task_001")
+    result = agent_output(task_id=retry["task_id"], block=True)
+```
+
+## Notes
+
+- **New task ID**: Retry creates a new agent, doesn't reuse the old task ID
+- **Same configuration**: All parameters are copied from original agent
+- **Independent execution**: Retried agent is separate from original
+- **No automatic retry**: You must explicitly call `agent_retry`
+
+## Related Commands
+
+- `/str:agent_list` - List failed agents to retry
+- `/str:agent_output` - Get results after retry
+- `/str:agent_progress` - Monitor retry progress
+- `/str:agent_cancel` - Cancel retry if it fails again

stravinsky_claude_assets/commands/str/cancel.md

@@ -0,0 +1,51 @@
+---
+description: Cancel ongoing semantic indexing operation
+allowed-tools: mcp__stravinsky__cancel_indexing
+---
+
+# Cancel Semantic Indexing
+
+Gracefully cancel an ongoing `semantic_index()` operation. Useful for large codebases where indexing takes several minutes.
+
+## What This Does
+
+Sets a cancellation flag that's checked between batches (every 50 chunks). The current batch completes before stopping, ensuring no partial writes to ChromaDB.
+
+## Usage
+
+Call `cancel_indexing` with parameters:
+- `project_path`: "." (current directory)
+- `provider`: "ollama" (must match the provider used for indexing)
+
+## Example
+
+```python
+# In one session: Start indexing
+semantic_index(project_path=".", provider="ollama")
+
+# From another call (or same session): Cancel it
+cancel_indexing(project_path=".", provider="ollama")
+```
+
+## Output Example
+
+```
+✅ Cancellation requested for /path/to/project
+Indexing will stop after current batch completes.
+```
+
+The indexing operation will return partial results:
+
+```
+⚠️ Indexing cancelled
+Indexed 150 chunks from 75 files before cancellation
+Cancelled after 150/500 chunks
+```
+
+## Notes
+
+- **Graceful**: Current batch (50 chunks) completes before stopping
+- **Progress preserved**: All completed batches remain indexed
+- **Thread-safe**: Uses locks to prevent race conditions
+- **Provider must match**: Use the same provider you started indexing with
+- Flag automatically clears at start of next indexing operation

stravinsky_claude_assets/commands/str/clean.md

@@ -0,0 +1,97 @@
+---
+description: Delete semantic search indexes to free disk space
+allowed-tools: mcp__stravinsky__delete_index, mcp__stravinsky__semantic_stats
+---
+
+# Delete Semantic Search Indexes
+
+Remove semantic search indexes to free disk space. Supports deleting specific project/provider combinations or all indexes globally.
+
+## What This Does
+
+Deletes ChromaDB vector databases stored at `~/.stravinsky/vectordb/`. Indexes can be regenerated by running `/str:index` again.
+
+## Interactive Usage
+
+**IMPORTANT**: When invoked without arguments, this command MUST present the user with these two options:
+
+**Option 1: Clear this repo's indexes only**
+```
+Would you like to:
+1. Clear indexes for THIS project only (safe)
+2. Clear indexes for ALL projects (⚠️ irreversible)
+
+Enter your choice (1 or 2):
+```
+
+### Implementation:
+```python
+# First, ask the user to choose
+# DO NOT proceed until user responds
+
+# If user chooses Option 1:
+delete_index(project_path=".")
+
+# If user chooses Option 2:
+delete_index(delete_all=True)
+```
+
+Before deleting, show what will be deleted using `semantic_stats()` to help the user make an informed decision.
+
+## Manual Usage Modes
+
+For direct invocation without prompting:
+
+### 1. Delete Specific Provider for Project
+
+```python
+delete_index(project_path=".", provider="ollama")
+```
+
+Deletes only the Ollama index for the current project.
+
+### 2. Delete All Providers for Project
+
+```python
+delete_index(project_path=".")
+```
+
+Deletes indexes for all providers (ollama, mxbai, gemini, openai, huggingface) for the current project.
+
+### 3. Delete ALL Indexes (Global Clean)
+
+```python
+delete_index(delete_all=True)
+```
+
+⚠️ **WARNING**: Deletes indexes for ALL projects and ALL providers. This is irreversible.
+
+## Output Example
+
+```
+✅ Deleted 2 index(es):
+  - /Users/you/.stravinsky/vectordb/abc123_ollama
+  - /Users/you/.stravinsky/vectordb/abc123_mxbai
+```
+
+## Use Cases
+
+- **Free disk space**: Large codebases can create 100MB+ indexes
+- **Provider switching**: Clean up old provider indexes when changing embedding models
+- **Fresh start**: Delete and reindex to fix corrupted indexes
+- **Project cleanup**: Remove indexes for archived projects
+
+## Check Index Size
+
+Use `semantic_stats()` to see index details before deleting:
+
+```python
+semantic_stats(project_path=".", provider="ollama")
+```
+
+## Notes
+
+- Deletion is permanent - no undo
+- Indexes can be regenerated with `/str:index`
+- Use `delete_all=True` carefully - affects all projects
+- Stops any running file watchers automatically

stravinsky_claude_assets/commands/str/continue.md

@@ -0,0 +1,38 @@
+---
+description: Continue working on pending todos (RALPH loop manual trigger)
+allowed-tools: TodoRead
+---
+
+# Continue Working on Pending Todos
+
+Manually trigger the RALPH loop (Relentless Autonomous Labor Protocol) to continue working on incomplete todos.
+
+## What This Does
+
+Forces Claude to continue working on incomplete todos instead of stopping. Use this when:
+- Claude completes a task but there are still pending todos
+- You want to ensure all todos are completed before stopping
+- The auto-continuation safety limit was reached
+
+## Usage
+
+Simply run: `/str:continue` or `/continue`
+
+## What Happens
+
+Claude will:
+1. Check for incomplete todos (in_progress or pending)
+2. Resume work on the next todo
+3. Continue until all todos are complete or safety limit reached
+
+## Safety Limits
+
+- Maximum 10 auto-continuations per hour
+- Resets after 1 hour of inactivity
+- Manual `/continue` bypasses the limit
+
+## Related Commands
+
+- `/str:clean` - Delete semantic search indexes
+- `/str:watch` - Start file watcher
+- `/str:unwatch` - Stop file watcher

stravinsky_claude_assets/commands/str/index.md

@@ -0,0 +1,199 @@
+---
+description: Index the codebase for semantic search with vector embeddings.
+---
+
+# Index Codebase for Semantic Search
+
+Build a semantic search index using vector embeddings to enable natural language code discovery.
+
+## What This Does
+
+Creates a vector database that indexes your codebase for semantic search, enabling queries like:
+- "find authentication logic"
+- "error handling in API endpoints"
+- "database connection pooling"
+- "logging and monitoring"
+- "caching and performance optimization"
+
+This index enables the `/search` command to find code based on meaning and intent, not just keyword matching.
+
+## Prerequisites
+
+Ensure your embedding provider is ready:
+
+### Ollama (Recommended - Free, Local)
+
+```bash
+# Install Ollama (if not already installed)
+brew install ollama
+
+# Pull the lightweight embedding model (274MB, recommended)
+ollama pull nomic-embed-text
+
+# Or for better accuracy (670MB):
+ollama pull mxbai-embed-large
+```
+
+### Other Providers
+
+- **Gemini**: Requires OAuth - run `stravinsky-auth login gemini`
+- **OpenAI**: Requires ChatGPT Plus/Pro - run `stravinsky-auth login openai`
+- **HuggingFace**: No auth needed, cloud-based
+
+## Usage
+
+Call the `semantic_index` MCP tool with your desired parameters:
+
+### Parameters
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `project_path` | string | "." | Path to project root (absolute or relative) |
+| `provider` | string | "ollama" | Embedding provider: "ollama", "gemini", "openai", "huggingface" |
+| `force` | boolean | false | Force full reindex (true) or incremental update (false) |
+
+### Examples
+
+**Basic indexing (default Ollama):**
+```
+semantic_index(project_path=".")
+```
+
+**Full reindex with force:**
+```
+semantic_index(project_path=".", force=true)
+```
+
+**Using Gemini provider:**
+```
+semantic_index(project_path=".", provider="gemini")
+```
+
+**Specific project directory:**
+```
+semantic_index(project_path="/path/to/project", provider="ollama")
+```
+
+## Index Management
+
+### Check Index Status
+
+After indexing, view the index statistics:
+```
+semantic_stats(project_path=".")
+```
+
+This shows:
+- Number of indexed files
+- Total code blocks indexed
+- Index size
+- Last update time
+- Provider information
+
+### Incremental vs Full Reindex
+
+- **Incremental (force=false)**: Only indexes new or modified files. Fast for ongoing development.
+- **Full Reindex (force=true)**: Rebuilds the entire index from scratch. Use when:
+  - Files have been deleted or moved
+  - You're getting stale results
+  - Upgrading embedding models
+  - You've made significant codebase changes
+
+### When to Reindex
+
+Run `/str:index` again when:
+- Adding new files or modules to your project
+- Significantly modifying existing files
+- Changing the codebase structure
+- Want to use a different embedding provider
+- Getting stale or outdated search results
+
+Use `force=true` if results become stale:
+```
+semantic_index(project_path=".", force=true)
+```
+
+## Provider Comparison
+
+| Provider | Speed | Accuracy | Cost | Setup |
+|----------|-------|----------|------|-------|
+| **Ollama** | Fast | Good | Free | Local |
+| **Gemini** | Fast | Excellent | Low | OAuth |
+| **OpenAI** | Medium | Excellent | Medium | OAuth |
+| **HuggingFace** | Slow | Good | Free | Cloud |
+
+## Next Steps
+
+After indexing, use semantic search:
+
+```
+/search "find authentication logic"
+/search "database connection pooling"
+/search "error handling patterns" language=py
+```
+
+See `/search` for detailed search command documentation.
+
+## Troubleshooting
+
+### "Ollama connection refused"
+
+Ensure Ollama is running:
+```bash
+# Check if Ollama is running
+lsof -i :11434
+
+# Start Ollama (usually auto-starts, but can manually start)
+ollama serve
+```
+
+### "Provider not available"
+
+Verify you have the required credentials:
+- **Gemini/OpenAI**: Run `stravinsky-auth login <provider>`
+- **HuggingFace**: Ensure HF_TOKEN environment variable is set
+
+### "Index is stale"
+
+Rebuild with full reindex:
+```
+semantic_index(project_path=".", force=true)
+```
+
+### Large index size
+
+If your index becomes very large:
+1. Exclude directories: Add to `.gitignore` patterns (same dirs are skipped from indexing)
+2. Use language filter in search instead of indexing all languages
+3. Reindex with different provider for smaller index
+
+## Performance Tips
+
+- **First index**: May take 1-2 minutes depending on codebase size
+- **Incremental updates**: Typically 30 seconds or less
+- **Ollama locally**: No internet required, very fast once loaded
+- **Batch indexing**: Index once, then search many times (cost-effective)
+
+## File Watching (Automatic Reindexing)
+
+Enable automatic reindexing when files change:
+
+```python
+from mcp_bridge.tools.semantic_search import start_file_watcher
+
+watcher = start_file_watcher(
+    project_path=".",
+    provider="ollama",
+    debounce_seconds=2.0
+)
+# Files now automatically reindex when modified
+```
+
+Stop automatic watching when done:
+```python
+from mcp_bridge.tools.semantic_search import stop_file_watcher
+
+stop_file_watcher(".")
+```
+
+See `/str:watch` for more details on automatic file watching.

stravinsky_claude_assets/commands/str/list_watchers.md

@@ -0,0 +1,96 @@
+---
+description: /str:list_watchers - List all active file watchers across projects
+allowed-tools: mcp__stravinsky__list_file_watchers
+---
+
+# List Active File Watchers
+
+View all currently running file watchers for automatic semantic search reindexing.
+
+## What This Does
+
+Displays information about active file watchers across all projects including:
+- Project path being watched
+- Embedding provider (ollama, gemini, openai, huggingface)
+- Debounce interval (wait time before reindexing)
+- Current status (running/stopped)
+
+## Prerequisites
+
+At least one file watcher must be running. Start a watcher with `/str:start_filewatch` first.
+
+## Usage
+
+Call the MCP tool directly (no parameters):
+
+```python
+mcp__stravinsky__list_file_watchers()
+```
+
+Returns a list of dicts with:
+- `project_path`: Root directory being watched
+- `provider`: Embedding provider name
+- `debounce_seconds`: Wait time before reindexing
+- `status`: "running" or "stopped"
+
+## Example Output
+
+```
+Active File Watchers
+====================
+
+Watcher 1:
+  Project: /Users/dev/project1
+  Provider: ollama
+  Debounce: 2.0s
+  Status: running
+
+Watcher 2:
+  Project: /Users/dev/project2
+  Provider: gemini
+  Debounce: 3.0s
+  Status: running
+
+Total: 2 active watchers
+```
+
+## Use Cases
+
+**Before stopping a watcher:**
+```python
+# List watchers to get project path
+mcp__stravinsky__list_file_watchers()
+
+# Stop specific watcher
+mcp__stravinsky__stop_file_watcher(project_path="/Users/dev/project1")
+```
+
+**Check status across multiple repos:**
+```python
+# See all watched projects at once
+mcp__stravinsky__list_file_watchers()
+```
+
+**Verify watcher started successfully:**
+```python
+# After starting watcher
+mcp__stravinsky__start_file_watcher(project_path=".", provider="ollama")
+
+# Confirm it's running
+mcp__stravinsky__list_file_watchers()
+```
+
+## Troubleshooting
+
+**"No active watchers"**: Start a watcher with `/str:start_filewatch` first.
+
+**"Watcher shows stopped"**: The watcher encountered an error or was manually stopped. Restart with `/str:start_filewatch`.
+
+**Multiple watchers for same project**: This indicates duplicate watcher processes. Stop and restart with `/str:stop_filewatch`.
+
+## Tips
+
+- Run this before stopping watchers to identify project paths
+- Use to verify watchers are running after system restart
+- Check status if reindexing seems not to be happening automatically
+- Each project can only have ONE active watcher per provider