ragtime-cli 0.2.14__tar.gz → 0.2.16__tar.gz

{ragtime_cli-0.2.14/ragtime_cli.egg-info → ragtime_cli-0.2.16}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ragtime-cli
-Version: 0.2.14
+Version: 0.2.16
 Summary: Local-first memory and RAG system for Claude Code - semantic search over code, docs, and team knowledge
 Author-email: Bret Martineau <bretwardjames@gmail.com>
 License-Expression: MIT
@@ -263,9 +263,38 @@ This is intentional - embeddings work better on focused summaries than large cod
 
 For Claude/MCP usage: The search tool description instructs Claude to read returned file paths for full implementations before making code changes.
 
+### Smart Query Understanding
+
+Search automatically detects qualifiers in natural language:
+
+```bash
+# These are equivalent - qualifiers are auto-detected
+ragtime search "error handling in mobile app"
+ragtime search "error handling" -r mobile
+
+# Use --raw for literal/exact search
+ragtime search "mobile error handling" --raw
+```
+
+Auto-detected qualifiers include: mobile, web, desktop, ios, android, flutter, react, vue, dart, python, typescript, auth, api, database, frontend, backend, and more.
+
+### Tiered Search
+
+Use tiered search to prioritize curated knowledge over raw code:
+
+```bash
+# Via MCP
+search(query="authentication", tiered=True)
+```
+
+Tiered search returns results in priority order:
+1. **Memories** - Curated, high-signal knowledge
+2. **Documentation** - Indexed markdown files
+3. **Code** - Function signatures and symbols
+
 ### Hybrid Search
 
-Semantic search can lose qualifiers - "error handling in mobile app" might return web app results because "error handling" dominates the embedding. Use `require_terms` to ensure specific words appear:
+For explicit keyword filtering, use `require_terms`:
 
 ```bash
 # CLI
@@ -277,6 +306,29 @@ search(query="error handling", require_terms=["mobile", "dart"])
 
 This combines semantic similarity (finds conceptually related content) with keyword filtering (ensures qualifiers aren't ignored).
 
+### Hierarchical Doc Chunking
+
+Long markdown files are automatically chunked by headers for better search accuracy:
+
+- Each section becomes a separate searchable chunk
+- Parent headers are preserved as context in the embedding
+- Short docs (<500 chars) remain as single chunks
+- Section path is stored (e.g., "Installation > Configuration > Environment Variables")
+
+### Feedback Loop
+
+Search quality improves over time based on usage patterns:
+
+```bash
+# Record when a result is useful (via MCP)
+record_feedback(query="auth flow", result_file="src/auth.py", action="used")
+
+# View usage statistics
+feedback_stats()
+```
+
+Frequently-used files receive a boost in future search rankings.
+
 ## Code Indexing
 
 The code indexer extracts meaningful symbols from your codebase:
@@ -379,13 +431,15 @@ Add to your Claude config (`.mcp.json`):
 
 Available tools:
 - `remember` - Store a memory
-- `search` - Semantic search
+- `search` - Semantic search (supports tiered mode and auto-extraction)
 - `list_memories` - List with filters
 - `get_memory` - Get by ID
 - `store_doc` - Store document verbatim
 - `forget` - Delete memory
 - `graduate` - Promote branch → app
 - `update_status` - Change memory status
+- `record_feedback` - Record when search results are used (improves future rankings)
+- `feedback_stats` - View search result usage patterns
 
 ## ghp-cli Integration
 

{ragtime_cli-0.2.14 → ragtime_cli-0.2.16}/README.md

@@ -233,9 +233,38 @@ This is intentional - embeddings work better on focused summaries than large cod
 
 For Claude/MCP usage: The search tool description instructs Claude to read returned file paths for full implementations before making code changes.
 
+### Smart Query Understanding
+
+Search automatically detects qualifiers in natural language:
+
+```bash
+# These are equivalent - qualifiers are auto-detected
+ragtime search "error handling in mobile app"
+ragtime search "error handling" -r mobile
+
+# Use --raw for literal/exact search
+ragtime search "mobile error handling" --raw
+```
+
+Auto-detected qualifiers include: mobile, web, desktop, ios, android, flutter, react, vue, dart, python, typescript, auth, api, database, frontend, backend, and more.
+
+### Tiered Search
+
+Use tiered search to prioritize curated knowledge over raw code:
+
+```bash
+# Via MCP
+search(query="authentication", tiered=True)
+```
+
+Tiered search returns results in priority order:
+1. **Memories** - Curated, high-signal knowledge
+2. **Documentation** - Indexed markdown files
+3. **Code** - Function signatures and symbols
+
 ### Hybrid Search
 
-Semantic search can lose qualifiers - "error handling in mobile app" might return web app results because "error handling" dominates the embedding. Use `require_terms` to ensure specific words appear:
+For explicit keyword filtering, use `require_terms`:
 
 ```bash
 # CLI
@@ -247,6 +276,29 @@ search(query="error handling", require_terms=["mobile", "dart"])
 
 This combines semantic similarity (finds conceptually related content) with keyword filtering (ensures qualifiers aren't ignored).
 
+### Hierarchical Doc Chunking
+
+Long markdown files are automatically chunked by headers for better search accuracy:
+
+- Each section becomes a separate searchable chunk
+- Parent headers are preserved as context in the embedding
+- Short docs (<500 chars) remain as single chunks
+- Section path is stored (e.g., "Installation > Configuration > Environment Variables")
+
+### Feedback Loop
+
+Search quality improves over time based on usage patterns:
+
+```bash
+# Record when a result is useful (via MCP)
+record_feedback(query="auth flow", result_file="src/auth.py", action="used")
+
+# View usage statistics
+feedback_stats()
+```
+
+Frequently-used files receive a boost in future search rankings.
+
 ## Code Indexing
 
 The code indexer extracts meaningful symbols from your codebase:
@@ -349,13 +401,15 @@ Add to your Claude config (`.mcp.json`):
 
 Available tools:
 - `remember` - Store a memory
-- `search` - Semantic search
+- `search` - Semantic search (supports tiered mode and auto-extraction)
 - `list_memories` - List with filters
 - `get_memory` - Get by ID
 - `store_doc` - Store document verbatim
 - `forget` - Delete memory
 - `graduate` - Promote branch → app
 - `update_status` - Change memory status
+- `record_feedback` - Record when search results are used (improves future rankings)
+- `feedback_stats` - View search result usage patterns
 
 ## ghp-cli Integration
 

{ragtime_cli-0.2.14 → ragtime_cli-0.2.16}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ragtime-cli"
-version = "0.2.14"
+version = "0.2.16"
 description = "Local-first memory and RAG system for Claude Code - semantic search over code, docs, and team knowledge"
 readme = "README.md"
 license = "MIT"

{ragtime_cli-0.2.14 → ragtime_cli-0.2.16/ragtime_cli.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ragtime-cli
-Version: 0.2.14
+Version: 0.2.16
 Summary: Local-first memory and RAG system for Claude Code - semantic search over code, docs, and team knowledge
 Author-email: Bret Martineau <bretwardjames@gmail.com>
 License-Expression: MIT
@@ -263,9 +263,38 @@ This is intentional - embeddings work better on focused summaries than large cod
 
 For Claude/MCP usage: The search tool description instructs Claude to read returned file paths for full implementations before making code changes.
 
+### Smart Query Understanding
+
+Search automatically detects qualifiers in natural language:
+
+```bash
+# These are equivalent - qualifiers are auto-detected
+ragtime search "error handling in mobile app"
+ragtime search "error handling" -r mobile
+
+# Use --raw for literal/exact search
+ragtime search "mobile error handling" --raw
+```
+
+Auto-detected qualifiers include: mobile, web, desktop, ios, android, flutter, react, vue, dart, python, typescript, auth, api, database, frontend, backend, and more.
+
+### Tiered Search
+
+Use tiered search to prioritize curated knowledge over raw code:
+
+```bash
+# Via MCP
+search(query="authentication", tiered=True)
+```
+
+Tiered search returns results in priority order:
+1. **Memories** - Curated, high-signal knowledge
+2. **Documentation** - Indexed markdown files
+3. **Code** - Function signatures and symbols
+
 ### Hybrid Search
 
-Semantic search can lose qualifiers - "error handling in mobile app" might return web app results because "error handling" dominates the embedding. Use `require_terms` to ensure specific words appear:
+For explicit keyword filtering, use `require_terms`:
 
 ```bash
 # CLI
@@ -277,6 +306,29 @@ search(query="error handling", require_terms=["mobile", "dart"])
 
 This combines semantic similarity (finds conceptually related content) with keyword filtering (ensures qualifiers aren't ignored).
 
+### Hierarchical Doc Chunking
+
+Long markdown files are automatically chunked by headers for better search accuracy:
+
+- Each section becomes a separate searchable chunk
+- Parent headers are preserved as context in the embedding
+- Short docs (<500 chars) remain as single chunks
+- Section path is stored (e.g., "Installation > Configuration > Environment Variables")
+
+### Feedback Loop
+
+Search quality improves over time based on usage patterns:
+
+```bash
+# Record when a result is useful (via MCP)
+record_feedback(query="auth flow", result_file="src/auth.py", action="used")
+
+# View usage statistics
+feedback_stats()
+```
+
+Frequently-used files receive a boost in future search rankings.
+
 ## Code Indexing
 
 The code indexer extracts meaningful symbols from your codebase:
@@ -379,13 +431,15 @@ Add to your Claude config (`.mcp.json`):
 
 Available tools:
 - `remember` - Store a memory
-- `search` - Semantic search
+- `search` - Semantic search (supports tiered mode and auto-extraction)
 - `list_memories` - List with filters
 - `get_memory` - Get by ID
 - `store_doc` - Store document verbatim
 - `forget` - Delete memory
 - `graduate` - Promote branch → app
 - `update_status` - Change memory status
+- `record_feedback` - Record when search results are used (improves future rankings)
+- `feedback_stats` - View search result usage patterns
 
 ## ghp-cli Integration
 

{ragtime_cli-0.2.14 → ragtime_cli-0.2.16}/ragtime_cli.egg-info/SOURCES.txt

@@ -11,6 +11,7 @@ src/__init__.py
 src/cli.py
 src/config.py
 src/db.py
+src/feedback.py
 src/mcp_server.py
 src/memory.py
 src/commands/audit.md

{ragtime_cli-0.2.14 → ragtime_cli-0.2.16}/src/cli.py

@@ -381,13 +381,13 @@ def index(path: Path, index_type: str, clear: bool):
                     item_show_func=lambda f: f.name[:30] if f else "",
                 ) as files:
                     for file_path in files:
-                        entry = index_doc_file(file_path)
-                        if entry:
-                            entries.append(entry)
+                        # index_doc_file returns list (hierarchical chunks)
+                        file_entries = index_doc_file(file_path)
+                        entries.extend(file_entries)
 
                 if entries:
                     _upsert_entries(db, entries, "docs")
-                    click.echo(f"  Indexed {len(entries)} documents")
+                    click.echo(f"  Indexed {len(entries)} document chunks")
             elif not to_delete:
                 click.echo("  All docs up to date")
         else:
@@ -2215,8 +2215,12 @@ def update(check: bool):
     import json
     from urllib.request import urlopen
     from urllib.error import URLError
+    from importlib.metadata import version as get_version
 
-    current = "0.2.9"
+    try:
+        current = get_version("ragtime-cli")
+    except Exception:
+        current = "0.0.0"  # Fallback if not installed as package
 
     click.echo(f"Current version: {current}")
     click.echo("Checking PyPI for updates...")

{ragtime_cli-0.2.14 → ragtime_cli-0.2.16}/src/db.py

@@ -238,6 +238,118 @@ class RagtimeDB:
 
         return output
 
+    def search_tiered(
+        self,
+        query: str,
+        limit: int = 10,
+        namespace: str | None = None,
+        require_terms: list[str] | None = None,
+        auto_extract: bool = True,
+        **filters,
+    ) -> list[dict]:
+        """
+        Tiered search: prioritizes memories > docs > code.
+
+        Searches in priority order, filling up to limit:
+        1. Memories (curated, high-signal knowledge)
+        2. Documentation (indexed markdown)
+        3. Code (broadest, implementation details)
+
+        Args:
+            query: Natural language search query
+            limit: Max total results to return
+            namespace: Filter by namespace
+            require_terms: Terms that MUST appear in results
+            auto_extract: Auto-detect qualifiers from query
+            **filters: Additional metadata filters
+
+        Returns:
+            List of dicts with 'content', 'metadata', 'distance', 'tier'
+        """
+        results = []
+
+        # Tier 1: Memories (not docs or code)
+        memory_results = self._search_tier(
+            query=query,
+            tier_name="memory",
+            exclude_types=["docs", "code"],
+            limit=limit,
+            namespace=namespace,
+            require_terms=require_terms,
+            auto_extract=auto_extract,
+            **filters,
+        )
+        results.extend(memory_results)
+
+        # Tier 2: Documentation
+        if len(results) < limit:
+            doc_results = self._search_tier(
+                query=query,
+                tier_name="docs",
+                type_filter="docs",
+                limit=limit - len(results),
+                namespace=namespace,
+                require_terms=require_terms,
+                auto_extract=auto_extract,
+                **filters,
+            )
+            results.extend(doc_results)
+
+        # Tier 3: Code
+        if len(results) < limit:
+            code_results = self._search_tier(
+                query=query,
+                tier_name="code",
+                type_filter="code",
+                limit=limit - len(results),
+                namespace=namespace,
+                require_terms=require_terms,
+                auto_extract=auto_extract,
+                **filters,
+            )
+            results.extend(code_results)
+
+        return results
+
+    def _search_tier(
+        self,
+        query: str,
+        tier_name: str,
+        limit: int,
+        type_filter: str | None = None,
+        exclude_types: list[str] | None = None,
+        **kwargs,
+    ) -> list[dict]:
+        """Search a single tier and tag results."""
+        # Build where clause for exclusion if needed
+        if exclude_types:
+            # Search without type filter, then exclude in post-processing
+            results = self.search(
+                query=query,
+                limit=limit * 2,  # fetch more since we'll filter
+                type_filter=None,
+                **kwargs,
+            )
+            # Filter out excluded types
+            filtered = []
+            for r in results:
+                if r["metadata"].get("type") not in exclude_types:
+                    r["tier"] = tier_name
+                    filtered.append(r)
+                    if len(filtered) >= limit:
+                        break
+            return filtered
+        else:
+            results = self.search(
+                query=query,
+                limit=limit,
+                type_filter=type_filter,
+                **kwargs,
+            )
+            for r in results:
+                r["tier"] = tier_name
+            return results
+
     def delete(self, ids: list[str]) -> None:
         """Delete documents by ID."""
         self.collection.delete(ids=ids)

ragtime_cli-0.2.16/src/feedback.py

@@ -0,0 +1,202 @@
+"""
+Feedback loop for RAG result quality improvement.
+
+Tracks which search results are actually used/referenced by Claude,
+enabling re-ranking and quality improvements over time.
+"""
+
+import json
+from pathlib import Path
+from dataclasses import dataclass, field, asdict
+from datetime import datetime
+from typing import Optional
+
+
+@dataclass
+class SearchFeedback:
+    """Feedback for a single search result."""
+    query: str
+    result_id: str  # ChromaDB document ID
+    result_file: str  # File path for easier debugging
+    action: str  # "used", "referenced", "ignored", "helpful", "not_helpful"
+    timestamp: str = field(default_factory=lambda: datetime.now().isoformat())
+    session_id: Optional[str] = None  # Group related searches
+    position: int = 0  # Position in results (1-indexed)
+    distance: float = 0.0  # Original semantic distance
+
+
+class FeedbackStore:
+    """
+    Simple file-based feedback storage.
+
+    Stores feedback as JSON lines for easy analysis.
+    Can be upgraded to SQLite or ChromaDB later.
+    """
+
+    def __init__(self, path: Path):
+        """
+        Initialize feedback store.
+
+        Args:
+            path: Directory to store feedback data
+        """
+        self.path = path
+        self.feedback_file = path / "feedback.jsonl"
+        self.stats_file = path / "feedback_stats.json"
+        path.mkdir(parents=True, exist_ok=True)
+
+    def record(self, feedback: SearchFeedback) -> None:
+        """Record a single feedback entry."""
+        with open(self.feedback_file, "a") as f:
+            f.write(json.dumps(asdict(feedback)) + "\n")
+
+    def record_usage(
+        self,
+        query: str,
+        result_id: str,
+        result_file: str,
+        position: int = 0,
+        distance: float = 0.0,
+        session_id: Optional[str] = None,
+    ) -> None:
+        """Convenience method to record when a result is used."""
+        self.record(SearchFeedback(
+            query=query,
+            result_id=result_id,
+            result_file=result_file,
+            action="used",
+            position=position,
+            distance=distance,
+            session_id=session_id,
+        ))
+
+    def record_batch(
+        self,
+        query: str,
+        used_ids: list[str],
+        all_results: list[dict],
+        session_id: Optional[str] = None,
+    ) -> None:
+        """
+        Record feedback for a batch of results.
+
+        Marks used_ids as "used" and others as "ignored".
+        """
+        used_set = set(used_ids)
+
+        for i, result in enumerate(all_results):
+            result_id = result.get("id", "")
+            result_file = result.get("metadata", {}).get("file", "")
+            distance = result.get("distance", 0.0)
+
+            action = "used" if result_id in used_set else "ignored"
+
+            self.record(SearchFeedback(
+                query=query,
+                result_id=result_id,
+                result_file=result_file,
+                action=action,
+                position=i + 1,
+                distance=distance,
+                session_id=session_id,
+            ))
+
+    def get_usage_stats(self) -> dict:
+        """
+        Get aggregated usage statistics.
+
+        Returns:
+            Dict with usage counts, popular files, etc.
+        """
+        if not self.feedback_file.exists():
+            return {"total": 0, "used": 0, "ignored": 0}
+
+        stats = {
+            "total": 0,
+            "used": 0,
+            "ignored": 0,
+            "helpful": 0,
+            "not_helpful": 0,
+            "files_used": {},  # file -> count
+            "avg_position_used": 0.0,
+        }
+
+        positions = []
+
+        with open(self.feedback_file) as f:
+            for line in f:
+                if not line.strip():
+                    continue
+                try:
+                    entry = json.loads(line)
+                    stats["total"] += 1
+                    action = entry.get("action", "")
+
+                    if action == "used":
+                        stats["used"] += 1
+                        positions.append(entry.get("position", 0))
+                        file_path = entry.get("result_file", "")
+                        stats["files_used"][file_path] = stats["files_used"].get(file_path, 0) + 1
+                    elif action == "ignored":
+                        stats["ignored"] += 1
+                    elif action == "helpful":
+                        stats["helpful"] += 1
+                    elif action == "not_helpful":
+                        stats["not_helpful"] += 1
+                except json.JSONDecodeError:
+                    continue
+
+        if positions:
+            stats["avg_position_used"] = sum(positions) / len(positions)
+
+        return stats
+
+    def get_boost_scores(self) -> dict[str, float]:
+        """
+        Calculate boost scores for files based on historical usage.
+
+        Returns:
+            Dict mapping file paths to boost multipliers (1.0 = no boost).
+        """
+        stats = self.get_usage_stats()
+        files_used = stats.get("files_used", {})
+
+        if not files_used:
+            return {}
+
+        # Normalize to 0-1 range, then convert to boost multiplier
+        max_count = max(files_used.values())
+        boosts = {}
+
+        for file_path, count in files_used.items():
+            # Boost range: 1.0 (no boost) to 1.5 (50% boost for most-used)
+            normalized = count / max_count
+            boosts[file_path] = 1.0 + (normalized * 0.5)
+
+        return boosts
+
+    def apply_boosts(self, results: list[dict], boosts: dict[str, float]) -> list[dict]:
+        """
+        Apply historical boost scores to search results.
+
+        Adjusts distances based on historical usage patterns.
+        Lower distance = more relevant, so we divide by boost.
+        """
+        if not boosts:
+            return results
+
+        for result in results:
+            file_path = result.get("metadata", {}).get("file", "")
+            boost = boosts.get(file_path, 1.0)
+            if "distance" in result and result["distance"]:
+                # Reduce distance for frequently-used files
+                result["distance"] = result["distance"] / boost
+                result["boosted"] = boost > 1.0
+
+        # Re-sort by adjusted distance
+        return sorted(results, key=lambda r: r.get("distance", float("inf")))
+
+    def clear(self) -> None:
+        """Clear all feedback data."""
+        if self.feedback_file.exists():
+            self.feedback_file.unlink()