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

stravinsky_claude_assets/commands/str/search.md

@@ -0,0 +1,205 @@
+# /str:search - Semantic Code Search
+
+Search your indexed project using natural language queries with the `semantic_search()` MCP tool.
+
+## What This Does
+
+Performs semantic code search using pre-computed vector embeddings to find code matching your natural language description:
+
+Examples:
+- "find authentication logic"
+- "error handling in API endpoints"
+- "database connection pooling"
+- "logging and monitoring"
+- "configuration management"
+- "HTTP request processing"
+
+## Prerequisites
+
+This command requires the project to be indexed first. **Run `/str:index` before using `/str:search`.**
+
+## Usage
+
+Invoke the `semantic_search()` MCP tool directly with your natural language query:
+
+```
+semantic_search(
+  query="your search description here",
+  project_path=".",
+  n_results=10,
+  provider="ollama",
+  language=None,
+  node_type=None
+)
+```
+
+## Parameters
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `query` | string | required | Natural language search description |
+| `project_path` | string | "." | Project root directory |
+| `n_results` | int | 10 | Number of results to return |
+| `provider` | string | "ollama" | Embedding provider: ollama, gemini, openai, huggingface |
+| `language` | string | None | Optional language filter (py, ts, js, java, go, etc.) |
+| `node_type` | string | None | Optional node type filter (function, class, method, import, etc.) |
+
+## Example Queries
+
+### Architectural/Design Questions
+
+```
+semantic_search(query="authentication and authorization implementation")
+semantic_search(query="error handling and exception recovery patterns", n_results=15)
+semantic_search(query="caching and performance optimization strategies")
+semantic_search(query="database connection pooling and persistence")
+semantic_search(query="configuration loading and environment settings")
+```
+
+### Feature Discovery
+
+```
+semantic_search(query="logging instrumentation and monitoring")
+semantic_search(query="HTTP request processing and routing")
+semantic_search(query="input validation and data sanitization")
+semantic_search(query="background job processing and scheduling")
+semantic_search(query="rate limiting and throttling mechanisms")
+```
+
+### Code Organization
+
+```
+semantic_search(query="testing framework and test utilities")
+semantic_search(query="deployment pipeline and release management")
+semantic_search(query="security encryption and cryptographic operations")
+semantic_search(query="transaction handling and atomicity guarantees")
+```
+
+### Filtered Search
+
+```
+semantic_search(query="error handling patterns", language="py")
+semantic_search(query="authentication logic", node_type="class")
+semantic_search(query="API handlers", language="py", node_type="function")
+```
+
+## Provider Options
+
+### Ollama (Default - Recommended for Development)
+
+Free, local, private embeddings:
+- No setup required if ollama is running
+- Model: nomic-embed-text (embeddings) or similar
+- Speed: Fast
+- Cost: Free
+
+**Setup:**
+```bash
+# Install ollama (if not already installed)
+brew install ollama  # macOS
+
+# Start ollama server
+ollama serve
+
+# In another terminal, pull the embedding model
+ollama pull nomic-embed-text
+```
+
+### Gemini (Cloud - Recommended for Production)
+
+Google's embeddings service:
+- **Setup:** `stravinsky-auth login gemini`
+- **Speed:** Fast
+- **Cost:** Low (~$0.075/1M tokens)
+- **Quality:** Excellent
+
+### OpenAI
+
+OpenAI's embeddings API:
+- **Setup:** `stravinsky-auth login openai`
+- **Speed:** Medium
+- **Cost:** Medium (~$0.10/1M tokens)
+- **Quality:** Excellent
+
+### HuggingFace
+
+Free cloud embeddings (no auth required):
+- **Speed:** Slower (can be slow for large codebases)
+- **Cost:** Free
+- **Quality:** Good
+
+## Tips
+
+1. **Be specific and conversational** in your queries
+   - Good: "How is authentication and authorization implemented?"
+   - Less effective: "auth"
+
+2. **Use filters to narrow results**
+   - Language filter: `language="py"` for Python-only results
+   - Node type filter: `node_type="function"` for function definitions only
+
+3. **Adjust result count based on codebase size**
+   - Small projects: `n_results=5`
+   - Medium projects: `n_results=10` (default)
+   - Large projects: `n_results=15-20`
+
+4. **Rebuild index if results are stale**
+   - Run `/str:index force=true` to reindex the entire project
+
+5. **Check index status**
+   - Run `semantic_stats()` to view index statistics and provider information
+
+## Switching Providers
+
+```
+# Default (local ollama - free)
+semantic_search(query="your query")
+
+# Cloud providers
+semantic_search(query="your query", provider="gemini")
+semantic_search(query="your query", provider="openai")
+semantic_search(query="your query", provider="huggingface")
+```
+
+First-time setup for cloud providers:
+
+```bash
+# Gemini OAuth
+stravinsky-auth login gemini
+
+# OpenAI OAuth
+stravinsky-auth login openai
+```
+
+## Common Search Patterns
+
+### Finding Implementation Details
+
+```
+semantic_search(query="where is X implemented")
+semantic_search(query="how does Y work")
+semantic_search(query="what components make up Z")
+```
+
+### Quality/Best Practices
+
+```
+semantic_search(query="error handling patterns in the codebase")
+semantic_search(query="security checks and validation logic")
+semantic_search(query="performance optimization strategies")
+```
+
+### Integration Points
+
+```
+semantic_search(query="external API integration and client libraries")
+semantic_search(query="database queries and ORM usage")
+semantic_search(query="message queue and event processing")
+```
+
+## Related Commands
+
+- `/str:index` - Index the project for semantic search
+- `/explore` - Run explore agent for code discovery
+- `/delphi` - Ask architecture and design questions
+- `/dewey` - Research implementation patterns

stravinsky_claude_assets/commands/str/start_filewatch.md

@@ -0,0 +1,136 @@
+# Start File Watcher for Automatic Reindexing
+
+Enable automatic reindexing of your codebase when Python files change.
+
+## What This Does
+
+Starts a background file watcher that monitors your project for file changes and automatically triggers reindexing:
+
+- Watches for create, modify, delete, and move events
+- Debounces rapid changes to batch reindexing efficiently
+- Automatically reindexes modified files for semantic search
+- Runs as a daemon thread (non-blocking)
+- Thread-safe with clean shutdown
+
+## Prerequisites
+
+**Recommended**: Run `/index` first to create an initial index before starting the file watcher.
+
+## Usage
+
+Use the `start_file_watcher` MCP tool to enable automatic reindexing:
+
+**Parameters:**
+- `project_path`: Root directory to watch (default: "." - current directory)
+- `provider`: Embedding provider to use for reindexing (default: "ollama")
+  - "ollama" - Free, local (recommended)
+  - "gemini" - Cloud-based, requires OAuth
+  - "openai" - Cloud-based, requires ChatGPT Plus/Pro
+  - "huggingface" - Cloud-based, requires API token
+- `debounce_seconds`: Wait time before reindexing after changes (default: 2.0)
+
+## Example Usage
+
+**Start watcher on current project with default settings:**
+```
+start_file_watcher()
+```
+
+**Start watcher with custom debounce:**
+```
+start_file_watcher(project_path=".", provider="ollama", debounce_seconds=3.0)
+```
+
+**Start watcher on specific directory:**
+```
+start_file_watcher(project_path="/path/to/project", provider="gemini")
+```
+
+## File System Monitoring
+
+The file watcher automatically monitors:
+- All `.py` files in your project
+- File creation, modification, deletion, and moves
+- Batches changes within the debounce window
+
+The watcher **skips**:
+- Virtual environments (`venv/`)
+- Python cache (`__pycache__/`, `.pyc` files)
+- Git metadata (`.git/`)
+- Node modules (`node_modules/`)
+- Build artifacts (`dist/`, `build/`)
+
+## Managing Watchers
+
+**Check active watchers:**
+```
+list_file_watchers()
+```
+
+**Get specific watcher status:**
+```
+get_file_watcher(project_path=".")
+```
+
+**Stop a watcher:**
+```
+stop_file_watcher(project_path=".")
+```
+
+## Workflow
+
+1. Create initial index with `/index` (optional but recommended)
+2. Start file watcher with `/str:start_filewatch`
+3. Continue coding - changes are automatically indexed
+4. Use `/search` for semantic queries
+5. Stop when done with `/str:stop_filewatch`
+
+## Provider Selection
+
+Choose based on your needs:
+
+- **ollama** (default): Free, local, no setup required
+  - Best for development
+  - Requires `ollama` installed and running
+  - Run: `ollama pull nomic-embed-text`
+
+- **gemini**: Cloud-based, excellent quality
+  - Best for production
+  - Requires: `stravinsky-auth login gemini`
+
+- **openai**: Cloud-based, excellent quality
+  - Requires: ChatGPT Plus/Pro subscription
+  - Run: `stravinsky-auth login openai`
+
+## Performance Tips
+
+- **Debounce value**: 
+  - 2.0s (default): Good balance for most projects
+  - 1.0s: For fast, continuous indexing (higher CPU)
+  - 3.0-5.0s: For large projects or slower systems
+
+- **Provider choice**:
+  - Local (ollama) if indexing many files frequently
+  - Cloud (gemini/openai) if network latency is acceptable
+
+## Troubleshooting
+
+**Watcher not working:**
+- Ensure provider is accessible (run `ollama` if using ollama)
+- Check logs: Look for errors in tool output
+- Try higher debounce value if system is slow
+
+**Too much reindexing:**
+- Increase `debounce_seconds` (e.g., 3.0 or 5.0)
+- This batches more changes before reindexing
+
+**Memory usage:**
+- File watchers run as daemon threads
+- Memory is low (typically <50MB per watcher)
+- Stop unused watchers to free resources
+
+## Related Commands
+
+- `/index` - Create/rebuild semantic search index
+- `/search` - Query indexed code with natural language
+- `/str:stop_filewatch` - Stop automatic reindexing

stravinsky_claude_assets/commands/str/stats.md

@@ -0,0 +1,71 @@
+---
+description: /str:stats - View semantic search index statistics (indexed files, chunks, embeddings)
+---
+
+# Semantic Search Index Statistics
+
+View detailed statistics about the semantic search index for your project.
+
+## What This Does
+
+Displays comprehensive information about the semantic search index including:
+- Number of indexed files
+- Total chunks/embeddings created
+- Index size on disk
+- Provider information
+- Last update timestamp
+- Indexed programming languages
+
+## Prerequisites
+
+An index must exist. Run `/index` first to create the semantic search index.
+
+## Usage
+
+Use the `semantic_stats` MCP tool to view index statistics:
+
+**Parameters:**
+- `project_path`: Path to project root (default: ".")
+
+## Example
+
+```
+semantic_stats(project_path=".")
+```
+
+## Output
+
+Displays information like:
+```
+Index Statistics
+================
+Project: /path/to/project
+Provider: ollama
+Status: Ready
+
+Files Indexed: 142
+Chunks: 3,847
+Total Embeddings: 3,847
+Index Size: 45.2 MB
+
+Languages:
+  - Python: 98 files
+  - Markdown: 28 files
+  - JSON: 16 files
+
+Last Updated: 2025-01-07 18:32:15
+```
+
+## Troubleshooting
+
+**"Index not found"**: Run `/index` to create the index first.
+
+**"Index is stale"**: Run `/index` again to update it with new/modified files.
+
+**"Rebuild index"**: Run `/index force=true` to completely rebuild from scratch.
+
+## Tips
+
+- Check stats regularly to ensure your index is up-to-date
+- Use stats to verify index coverage before running `/search` queries
+- Stats help identify if re-indexing is needed (large file count changes)

stravinsky_claude_assets/commands/str/stop_filewatch.md

@@ -0,0 +1,89 @@
+# Stop File Watcher
+
+Disable automatic reindexing for a project.
+
+## What This Does
+
+Stops and removes a file watcher that was previously started with `/str:start_filewatch`:
+
+- Gracefully shuts down the background watcher thread
+- Releases file system resources
+- Stops automatic reindexing for the specified project
+- Returns status (true if watcher was active, false if none was running)
+
+## Usage
+
+Use the `stop_file_watcher` MCP tool to disable automatic reindexing:
+
+**Parameters:**
+- `project_path`: Root directory that was being watched (default: "." - current directory)
+
+## Example Usage
+
+**Stop watcher on current project:**
+```
+stop_file_watcher()
+```
+
+**Stop watcher on specific directory:**
+```
+stop_file_watcher(project_path="/path/to/project")
+```
+
+## Status
+
+The tool returns:
+- `True` if a watcher was active and has been stopped
+- `False` if no watcher was active for that project path
+
+## Checking Watchers
+
+**List all active watchers before stopping:**
+```
+list_file_watchers()
+```
+
+This shows:
+- Project paths being watched
+- Provider for each watcher
+- Number of changes detected
+- Watch status (running/stopped)
+
+**Get status of specific watcher:**
+```
+get_file_watcher(project_path=".")
+```
+
+Returns the CodebaseFileWatcher object if active, None otherwise.
+
+## When to Stop
+
+- Stop when you're done with a project
+- Stop if you need to change provider settings
+- Stop to reduce resource usage
+- Stop before shutting down to clean shutdown the watcher thread
+
+## Restarting
+
+You can restart the watcher at any time:
+
+```
+# Stop current watcher
+stop_file_watcher()
+
+# Start new watcher with different settings
+start_file_watcher(project_path=".", provider="gemini", debounce_seconds=3.0)
+```
+
+## Workflow
+
+1. Start watcher with `/str:start_filewatch`
+2. Code and make changes (automatically indexed)
+3. Use `/search` for semantic queries
+4. When done: **Stop watcher with `/str:stop_filewatch`**
+
+## Related Commands
+
+- `/str:start_filewatch` - Enable automatic reindexing
+- `/search` - Query indexed code with natural language
+- `/index` - Create/rebuild semantic search index

stravinsky_claude_assets/commands/str/unwatch.md

@@ -0,0 +1,42 @@
+---
+description: Stop file watching for semantic search index updates
+allowed-tools: mcp__stravinsky__stop_file_watcher, mcp__stravinsky__list_file_watchers
+---
+
+# Stop File Watcher
+
+Stop automatic reindexing for a project's semantic search index.
+
+## What This Does
+
+Stops the background file watcher that monitors code changes and triggers reindexing.
+
+## Usage
+
+Call `stop_file_watcher` with parameter:
+- `project_path`: "." (current directory)
+
+## Example
+
+```python
+# Stop watching current project
+stop_file_watcher(project_path=".")
+```
+
+Returns: Boolean indicating if watcher was stopped (true) or wasn't running (false)
+
+## List Active Watchers
+
+Use `list_file_watchers()` to see all active watchers across projects:
+
+```python
+list_file_watchers()
+```
+
+Returns JSON with active watcher details (project path, provider, status).
+
+## Notes
+
+- Watcher automatically cleans up on process exit
+- Stopping a non-existent watcher returns false
+- Any pending debounced reindex is cancelled when stopping

stravinsky_claude_assets/commands/str/watch.md

@@ -0,0 +1,45 @@
+---
+description: Start automatic file watching for semantic search index updates
+allowed-tools: mcp__stravinsky__start_file_watcher, mcp__stravinsky__semantic_index, mcp__stravinsky__semantic_stats
+---
+
+# Start File Watcher for Semantic Search
+
+Automatically reindex code changes in the background. The watcher monitors `.py` files and triggers incremental reindexing when changes are detected.
+
+## What This Does
+
+1. **Auto-catches up**: Runs incremental reindex to catch changes since last index
+2. **Starts monitoring**: Watches for file create/modify/delete/move events
+3. **Debounces changes**: Waits 2 seconds after last change before reindexing
+4. **Background operation**: Runs as daemon thread, cleans up on exit
+
+## Prerequisites
+
+- Index must exist first (run `/index` or `semantic_index()` before starting watcher)
+- Ollama must be running with embedding model available
+
+## Usage
+
+Call `start_file_watcher` with parameters:
+- `project_path`: "." (current directory)
+- `provider`: "ollama" (or "mxbai", "gemini", "openai", "huggingface")
+- `debounce_seconds`: 2.0 (optional, default is 2.0)
+
+## Example
+
+```python
+# Start watching current project
+start_file_watcher(project_path=".", provider="ollama")
+```
+
+## Stop Watching
+
+Use `/str:unwatch` or call `stop_file_watcher(project_path=".")` to stop the watcher.
+
+## Notes
+
+- Watcher automatically performs incremental reindex on start to catch missed changes
+- Only monitors Python files (`.py` extension)
+- Skips: venv, __pycache__, .git, node_modules, dist, build
+- Thread-safe with automatic cleanup on process exit

stravinsky_claude_assets/commands/strav.md

@@ -0,0 +1,53 @@
+---
+name: strav
+description: |
+  Stravinsky task orchestrator and parallel execution specialist.
+---
+
+# /strav (Stravinsky Orchestrator)
+
+**Identity**: You are Stravinsky, the Parallel Orchestrator.
+**Goal**: Maximize throughput by spawning multiple specialized agents in parallel.
+
+---
+
+## 🚀 ULTRAWORK PROTOCOL (Trigger: /strav ulw, /strav uw)
+
+When ULTRAWORK mode is detected (keywords: `ultrawork`, `uw`, `ulw`):
+
+1.  **IMMEDIATE PARALLELISM**: You must NEVER work sequentially.
+2.  **SPAWN AGENTS**: Use `agent_spawn` for ALL tasks.
+3.  **NO LOCAL TOOLS**: Do NOT use `Read`, `Grep`, or `Bash` yourself. Delegate EVERYTHING.
+
+**Correct Response Pattern (FIRE EVERYTHING AT ONCE):**
+```python
+# 1. Spawn Context Gatherer
+agent_spawn(agent_type="explore", prompt="Find auth flow...", task_id="auth_search")
+# 2. Spawn Documentation Researcher
+agent_spawn(agent_type="dewey", prompt="Research JWT best practices...", task_id="doc_search")
+# 3. Spawn Implementation Planner
+agent_spawn(agent_type="delphi", prompt="Plan refactoring based on...", task_id="planner")
+```
+
+---
+
+## Agent Roster
+
+| Agent Type | Best For | Model |
+|------------|----------|-------|
+| `explore` | Codebase search, finding files | gemini-3-flash |
+| `dewey` | Documentation, external research | gemini-3-flash |
+| `frontend` | UI/CSS, React components | gemini-3-pro |
+| `delphi` | Architecture, complex bugs | gpt-5.2 |
+
+---
+
+## Execution Rules
+
+1.  **Analyze Request**: Identify independent sub-tasks.
+2.  **Delegate**: Call `agent_spawn` for each sub-task in the SAME turn.
+3.  **Wait**: Do not mark as done until agents return success.
+4.  **Verify**: Use `lsp_diagnostics` on modified files.
+
+**IF YOU SEE "ULTRAWORK" or "UW":**
+Your FIRST action MUST be `agent_spawn`. Do not talk. Do not plan text. SPAWN.