minder-cli 0.2.0__py3-none-any.whl

minder/cache/__init__.py

@@ -0,0 +1,10 @@
+"""
+Cache package — providers for runtime caching layer.
+"""
+
+from minder.cache.providers import LRUCacheProvider, RedisCacheProvider
+
+__all__ = [
+    "LRUCacheProvider",
+    "RedisCacheProvider",
+]

minder/cache/providers.py

@@ -0,0 +1,140 @@
+"""
+Redis Cache Provider — implements ICacheProvider for runtime cache/session layer.
+
+Provides async cache operations backed by Redis. Supports key-value storage,
+TTL, namespaced operations, and health checks.
+"""
+
+from __future__ import annotations
+
+import redis.asyncio as aioredis
+
+
+class RedisCacheProvider:
+    """Async Redis cache provider implementing ICacheProvider."""
+
+    def __init__(
+        self,
+        uri: str = "redis://localhost:6379/0",
+        *,
+        prefix: str = "minder:",
+        default_ttl: int = 3600,
+    ) -> None:
+        self._prefix = prefix
+        self._default_ttl = default_ttl
+        self._client: aioredis.Redis = aioredis.from_url(  # type: ignore[type-arg]
+            uri,
+            decode_responses=True,
+        )
+
+    def _key(self, key: str) -> str:
+        """Apply namespace prefix to key."""
+        return f"{self._prefix}{key}"
+
+    async def get(self, key: str) -> str | None:
+        """Get a value by key."""
+        result = await self._client.get(self._key(key))
+        if isinstance(result, bytes):
+            return result.decode("utf-8")
+        return result  # type: ignore[return-value]
+
+    async def set(self, key: str, value: str, *, ttl: int | None = None) -> None:
+        """Set a key-value pair with optional TTL."""
+        effective_ttl = ttl if ttl is not None else self._default_ttl
+        await self._client.set(self._key(key), value, ex=effective_ttl)
+
+    async def delete(self, key: str) -> None:
+        """Delete a key."""
+        await self._client.delete(self._key(key))
+
+    async def exists(self, key: str) -> bool:
+        """Check if a key exists."""
+        return bool(await self._client.exists(self._key(key)))
+
+    async def expire(self, key: str, ttl: int) -> None:
+        """Set expiration on an existing key."""
+        await self._client.expire(self._key(key), ttl)
+
+    async def incr(self, key: str) -> int:
+        """Increment an integer value."""
+        result = await self._client.incr(self._key(key))
+        return int(result)
+
+    async def keys(self, pattern: str) -> list[str]:
+        """Get keys matching a pattern (within namespace)."""
+        full_pattern = self._key(pattern)
+        raw_keys: list[str] = await self._client.keys(full_pattern)  # type: ignore[assignment]
+        prefix_len = len(self._prefix)
+        return [k[prefix_len:] if k.startswith(self._prefix) else k for k in raw_keys]
+
+    async def flush_namespace(self, namespace: str) -> None:
+        """Delete all keys under a specific namespace prefix."""
+        pattern = self._key(f"{namespace}:*")
+        raw_keys = await self._client.keys(pattern)
+        if raw_keys:
+            await self._client.delete(*raw_keys)
+
+    async def health_check(self) -> bool:
+        """Ping Redis to check connectivity."""
+        try:
+            return bool(await self._client.ping())  # type: ignore[misc]
+        except Exception:
+            return False
+
+    async def close(self) -> None:
+        """Close the Redis connection."""
+        await self._client.aclose()
+
+
+class LRUCacheProvider:
+    """
+    In-memory LRU cache provider implementing ICacheProvider.
+
+    Used as zero-dependency fallback when Redis is not available.
+    """
+
+    def __init__(self, *, max_size: int = 1000, default_ttl: int = 3600) -> None:
+        self._max_size = max_size
+        self._default_ttl = default_ttl
+        self._store: dict[str, str] = {}
+
+    async def get(self, key: str) -> str | None:
+        return self._store.get(key)
+
+    async def set(self, key: str, value: str, *, ttl: int | None = None) -> None:
+        if len(self._store) >= self._max_size:
+            # Evict oldest entry (FIFO as simple approximation)
+            oldest_key = next(iter(self._store))
+            del self._store[oldest_key]
+        self._store[key] = value
+
+    async def delete(self, key: str) -> None:
+        self._store.pop(key, None)
+
+    async def exists(self, key: str) -> bool:
+        return key in self._store
+
+    async def expire(self, key: str, ttl: int) -> None:
+        pass  # No-op for in-memory store
+
+    async def incr(self, key: str) -> int:
+        current = int(self._store.get(key, "0"))
+        current += 1
+        self._store[key] = str(current)
+        return current
+
+    async def keys(self, pattern: str) -> list[str]:
+        import fnmatch
+        return [k for k in self._store if fnmatch.fnmatch(k, pattern)]
+
+    async def flush_namespace(self, namespace: str) -> None:
+        prefix = f"{namespace}:"
+        to_delete = [k for k in self._store if k.startswith(prefix)]
+        for k in to_delete:
+            del self._store[k]
+
+    async def health_check(self) -> bool:
+        return True
+
+    async def close(self) -> None:
+        self._store.clear()

minder/chunking/__init__.py

@@ -0,0 +1,4 @@
+from minder.chunking.code_splitter import CodeChunk, CodeSplitter
+from minder.chunking.splitter import TextChunk, TextSplitter
+
+__all__ = ["CodeChunk", "CodeSplitter", "TextChunk", "TextSplitter"]

minder/chunking/code_splitter.py

@@ -0,0 +1,184 @@
+"""
+AST-aware code chunking.
+
+Python: uses the standard-library ``ast`` module to split at top-level
+  ``def`` / ``async def`` / ``class`` boundaries.  Module-level import
+  statements are prepended to every chunk for self-containedness.
+
+TypeScript / JavaScript / Java: falls back to a brace-depth (``{`` / ``}``)
+  line-based splitter that cuts at depth-0 boundaries.
+
+Any other language: attempts Python AST first, then brace-depth.
+"""
+
+from __future__ import annotations
+
+import ast
+from dataclasses import dataclass, field
+
+PythonSymbol = ast.FunctionDef | ast.AsyncFunctionDef | ast.ClassDef
+
+
+@dataclass
+class CodeChunk:
+    content: str          # Complete, self-contained chunk text
+    start_line: int       # 1-indexed start line in the original source
+    end_line: int         # 1-indexed end line in the original source
+    symbol_name: str | None   # Function/class name, or None for file-level chunks
+    language: str
+    imports: str = field(default="")   # Module-level imports prepended to content
+
+
+# ---------------------------------------------------------------------------
+# CodeSplitter
+# ---------------------------------------------------------------------------
+
+
+class CodeSplitter:
+    """
+    Split source code into logical chunks.
+
+    Usage::
+
+        splitter = CodeSplitter()
+        chunks = splitter.split(source_code, language="python")
+    """
+
+    def split(self, code: str, language: str = "python") -> list[CodeChunk]:
+        """
+        Split *code* into :class:`CodeChunk` objects.
+
+        Args:
+            code: source code text.
+            language: one of ``"python"``, ``"typescript"``, ``"javascript"``,
+                ``"ts"``, ``"js"``, ``"java"``.  Anything else is attempted as
+                Python first, then falls back to brace-depth splitting.
+        """
+        if not code.strip():
+            return []
+
+        lang = language.lower()
+        if lang == "python":
+            return self._split_python(code)
+        if lang in {"typescript", "ts", "javascript", "js", "java"}:
+            return self._split_by_brace_depth(code, language=language)
+        # Unknown language: try Python AST, fall back to brace split
+        try:
+            return self._split_python(code)
+        except SyntaxError:
+            return self._split_by_brace_depth(code, language=language)
+
+    # ------------------------------------------------------------------
+    # Python (AST-aware)
+    # ------------------------------------------------------------------
+
+    def _split_python(self, code: str) -> list[CodeChunk]:
+        lines = code.splitlines(keepends=True)
+        tree = ast.parse(code)
+
+        import_lines: list[str] = []
+        top_symbols: list[PythonSymbol] = []
+
+        for node in ast.iter_child_nodes(tree):
+            if isinstance(node, (ast.Import, ast.ImportFrom)):
+                s = node.lineno - 1
+                e = getattr(node, "end_lineno", node.lineno) - 1
+                import_lines.extend(lines[s : e + 1])
+            elif isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
+                top_symbols.append(node)
+
+        imports_str = "".join(import_lines).rstrip()
+
+        # No top-level symbols → whole file is one chunk
+        if not top_symbols:
+            return [
+                CodeChunk(
+                    content=code,
+                    start_line=1,
+                    end_line=len(lines),
+                    symbol_name=None,
+                    language="python",
+                    imports=imports_str,
+                )
+            ]
+
+        chunks: list[CodeChunk] = []
+        for node in top_symbols:
+            start = node.lineno - 1
+            end = getattr(node, "end_lineno", node.lineno) - 1
+            body = "".join(lines[start : end + 1])
+            if imports_str:
+                content = imports_str + "\n\n" + body.rstrip()
+            else:
+                content = body.rstrip()
+            chunks.append(
+                CodeChunk(
+                    content=content,
+                    start_line=node.lineno,
+                    end_line=getattr(node, "end_lineno", node.lineno),
+                    symbol_name=node.name,
+                    language="python",
+                    imports=imports_str,
+                )
+            )
+
+        return chunks
+
+    # ------------------------------------------------------------------
+    # Brace-depth (TypeScript / JavaScript / Java)
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _split_by_brace_depth(code: str, *, language: str) -> list[CodeChunk]:
+        """Split at top-level brace-balanced block boundaries (depth 0 → 1 → 0)."""
+        lines = code.splitlines(keepends=True)
+        chunks: list[CodeChunk] = []
+        depth = 0
+        chunk_start = 0
+
+        for i, line in enumerate(lines):
+            depth += line.count("{") - line.count("}")
+            if depth == 0 and i >= chunk_start:
+                body = "".join(lines[chunk_start : i + 1]).strip()
+                if body:
+                    chunks.append(
+                        CodeChunk(
+                            content=body,
+                            start_line=chunk_start + 1,
+                            end_line=i + 1,
+                            symbol_name=None,
+                            language=language,
+                        )
+                    )
+                chunk_start = i + 1
+            # Guard against unbalanced braces
+            if depth < 0:
+                depth = 0
+
+        # Trailing content after the last depth-0 point
+        if chunk_start < len(lines):
+            body = "".join(lines[chunk_start:]).strip()
+            if body:
+                chunks.append(
+                    CodeChunk(
+                        content=body,
+                        start_line=chunk_start + 1,
+                        end_line=len(lines),
+                        symbol_name=None,
+                        language=language,
+                    )
+                )
+
+        # Fallback: return whole file as one chunk
+        if not chunks:
+            return [
+                CodeChunk(
+                    content=code,
+                    start_line=1,
+                    end_line=len(lines),
+                    symbol_name=None,
+                    language=language,
+                )
+            ]
+
+        return chunks

minder/chunking/splitter.py

@@ -0,0 +1,136 @@
+"""
+Text chunking with markdown-heading awareness.
+
+Splits documents by heading boundaries first, then applies a sliding-window
+fallback for sections that exceed chunk_size.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+
+_HEADING_RE = re.compile(r"^#{1,6}\s+.+$", re.MULTILINE)
+
+
+@dataclass
+class TextChunk:
+    content: str
+    start_char: int
+    end_char: int
+
+
+class TextSplitter:
+    """
+    Markdown-aware sliding-window text chunker.
+
+    Args:
+        chunk_size: target chunk length in characters (default 512 ≈ ~128 tokens).
+        overlap: character overlap between adjacent window chunks (default 64).
+    """
+
+    def __init__(self, chunk_size: int = 512, overlap: int = 64) -> None:
+        if chunk_size <= 0:
+            raise ValueError(f"chunk_size must be positive, got {chunk_size}")
+        if overlap < 0 or overlap >= chunk_size:
+            raise ValueError(
+                f"overlap must be in [0, chunk_size), got overlap={overlap} chunk_size={chunk_size}"
+            )
+        self._chunk_size = chunk_size
+        self._overlap = overlap
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def split(self, text: str) -> list[TextChunk]:
+        """
+        Split *text* into chunks.
+
+        Strategy:
+        1. Attempt a split at markdown heading boundaries.
+        2. Any resulting section that still exceeds chunk_size is
+           sub-split using a sliding window.
+        3. If no headings are found the whole text goes through the
+           sliding window directly.
+
+        Returns:
+            Ordered list of :class:`TextChunk` objects.
+        """
+        if not text:
+            return []
+
+        heading_sections = self._split_at_headings(text)
+        if len(heading_sections) > 1:
+            result: list[TextChunk] = []
+            for section in heading_sections:
+                if len(section.content) <= self._chunk_size:
+                    result.append(section)
+                else:
+                    result.extend(
+                        self._sliding_window(section.content, char_offset=section.start_char)
+                    )
+            return result
+
+        return self._sliding_window(text)
+
+    # ------------------------------------------------------------------
+    # Internals
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _split_at_headings(text: str) -> list[TextChunk]:
+        matches = list(_HEADING_RE.finditer(text))
+        if not matches:
+            return [TextChunk(content=text, start_char=0, end_char=len(text))]
+
+        chunks: list[TextChunk] = []
+
+        # Content before the first heading
+        first_heading_start = matches[0].start()
+        if first_heading_start > 0:
+            pre = text[:first_heading_start].strip()
+            if pre:
+                chunks.append(
+                    TextChunk(content=pre, start_char=0, end_char=first_heading_start)
+                )
+
+        # Each heading section: from heading start to next heading start (or EOF)
+        boundaries = [m.start() for m in matches] + [len(text)]
+        for i in range(len(boundaries) - 1):
+            start, end = boundaries[i], boundaries[i + 1]
+            content = text[start:end].strip()
+            if content:
+                chunks.append(TextChunk(content=content, start_char=start, end_char=end))
+
+        return chunks or [TextChunk(content=text, start_char=0, end_char=len(text))]
+
+    def _sliding_window(self, text: str, *, char_offset: int = 0) -> list[TextChunk]:
+        chunks: list[TextChunk] = []
+        step = self._chunk_size - self._overlap
+        pos = 0
+        while pos < len(text):
+            end = min(pos + self._chunk_size, len(text))
+            content = text[pos:end]
+            if content.strip():
+                chunks.append(
+                    TextChunk(
+                        content=content,
+                        start_char=char_offset + pos,
+                        end_char=char_offset + end,
+                    )
+                )
+            if end == len(text):
+                break
+            pos += step
+
+        if not chunks and text.strip():
+            chunks.append(
+                TextChunk(
+                    content=text,
+                    start_char=char_offset,
+                    end_char=char_offset + len(text),
+                )
+            )
+        return chunks