nexus-dev 3.2.0__py3-none-any.whl

nexus_dev/agents/prompt_factory.py

@@ -0,0 +1,91 @@
+"""Generate structured prompts using XML tags."""
+
+from __future__ import annotations
+
+from .agent_config import AgentConfig
+
+
+class PromptFactory:
+    """Build system prompts with XML structure for Claude/Gemini.
+
+    This factory generates prompts using XML tags that are well-understood
+    by modern LLMs like Claude and Gemini. The structure clearly separates:
+    - Role definition (identity, goal, tone)
+    - Backstory (expertise and background)
+    - Memory (RAG context from the project)
+    - Available tools
+    - Instructions
+    """
+
+    @staticmethod
+    def build(
+        agent: AgentConfig,
+        context_items: list[str],
+        available_tools: list[str] | None = None,
+    ) -> str:
+        """Build the complete system prompt.
+
+        Args:
+            agent: Agent configuration.
+            context_items: RAG search results (text snippets).
+            available_tools: List of tool names the agent can use.
+
+        Returns:
+            Formatted system prompt with XML structure.
+        """
+        # Memory block from RAG
+        memory_block = ""
+        if context_items:
+            items_str = "\n".join([f"- {item}" for item in context_items])
+            memory_block = f"""
+<nexus_memory>
+Project context from RAG (use this to inform your responses):
+{items_str}
+</nexus_memory>
+"""
+
+        # Tools block
+        tools_block = ""
+        if available_tools:
+            tools_str = ", ".join(available_tools)
+            tools_block = f"""
+<available_tools>
+You can use these tools: {tools_str}
+</available_tools>
+"""
+
+        return f"""<role_definition>
+You are {agent.display_name}.
+ROLE: {agent.profile.role}
+OBJECTIVE: {agent.profile.goal}
+TONE: {agent.profile.tone}
+</role_definition>
+
+<backstory>
+{agent.profile.backstory}
+</backstory>
+{memory_block}{tools_block}
+<instructions>
+CRITICAL RAG USAGE POLICY:
+- You MUST use search_knowledge, search_code, search_docs, or search_lessons
+  BEFORE answering ANY question about the project.
+- Do NOT rely on your internal knowledge or the <nexus_memory> context alone
+  when the user asks about specific implementations, configurations, or docs.
+- If your first search yields no results, try:
+  1. Broadening your search query
+  2. Searching different content types (code vs docs vs lessons)
+  3. Breaking down the question into smaller searchable parts
+- Only after exhausting RAG searches should you answer based on general
+  knowledge, and you must acknowledge that you couldn't find project-specific
+  information.
+
+WORKFLOW:
+1. Analyze the user's request carefully.
+2. If the request involves project-specific information, SEARCH FIRST using
+   RAG tools.
+3. Use your retrieved context and <nexus_memory> to provide accurate,
+   project-specific responses.
+4. If you need to perform actions, use the available tools.
+5. Be concise but thorough.
+</instructions>
+"""

nexus_dev/chunkers/__init__.py

@@ -0,0 +1,168 @@
+"""Chunker registry and utilities."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from .base import BaseChunker, ChunkType, CodeChunk, FallbackChunker
+from .docs_chunker import DocumentationChunker
+from .java_chunker import JavaChunker
+from .javascript_chunker import JavaScriptChunker, TypeScriptChunker
+from .python_chunker import PythonChunker
+
+if TYPE_CHECKING:
+    pass
+
+__all__ = [
+    "BaseChunker",
+    "ChunkType",
+    "CodeChunk",
+    "ChunkerRegistry",
+    "DocumentationChunker",
+    "FallbackChunker",
+    "JavaChunker",
+    "JavaScriptChunker",
+    "PythonChunker",
+    "TypeScriptChunker",
+]
+
+
+class ChunkerRegistry:
+    """Registry for file extension to chunker mapping.
+
+    The registry automatically maps file extensions to appropriate chunkers.
+    Use `get_chunker()` to get a chunker for a specific file, or
+    `chunk_file()` to directly chunk a file.
+    """
+
+    _chunkers: dict[str, BaseChunker] = {}
+    _initialized: bool = False
+
+    @classmethod
+    def _ensure_initialized(cls) -> None:
+        """Ensure default chunkers are registered."""
+        if not cls._initialized:
+            cls._register_default_chunkers()
+            cls._initialized = True
+
+    @classmethod
+    def _register_default_chunkers(cls) -> None:
+        """Register all built-in chunkers."""
+        cls.register(PythonChunker())
+        cls.register(JavaScriptChunker())
+        cls.register(TypeScriptChunker())
+        cls.register(JavaChunker())
+        cls.register(DocumentationChunker())
+
+    @classmethod
+    def register(cls, chunker: BaseChunker) -> None:
+        """Register a chunker for its supported extensions.
+
+        Args:
+            chunker: Chunker instance to register.
+        """
+        for ext in chunker.supported_extensions:
+            ext_lower = ext.lower()
+            if not ext_lower.startswith("."):
+                ext_lower = f".{ext_lower}"
+            cls._chunkers[ext_lower] = chunker
+
+    @classmethod
+    def get_chunker(cls, file_path: str | Path) -> BaseChunker | None:
+        """Get the appropriate chunker for a file.
+
+        Args:
+            file_path: Path to the file.
+
+        Returns:
+            Chunker instance or None if no specific chunker matches.
+        """
+        cls._ensure_initialized()
+
+        path = Path(file_path)
+        ext = path.suffix.lower()
+
+        return cls._chunkers.get(ext)
+
+    @classmethod
+    def chunk_file(cls, file_path: str | Path, content: str) -> list[CodeChunk]:
+        """Chunk a file using the appropriate chunker.
+
+        Args:
+            file_path: Path to the file.
+            content: File content.
+
+        Returns:
+            List of code chunks.
+        """
+        cls._ensure_initialized()
+
+        file_path_str = str(file_path)
+        chunker = cls.get_chunker(file_path)
+
+        if chunker is not None:
+            return chunker.chunk_file(file_path_str, content)
+
+        # Use fallback chunker for unknown types
+        return FallbackChunker().chunk_file(file_path_str, content)
+
+    @classmethod
+    def get_supported_extensions(cls) -> list[str]:
+        """Get list of all supported file extensions.
+
+        Returns:
+            List of supported extensions.
+        """
+        cls._ensure_initialized()
+        return list(cls._chunkers.keys())
+
+    @classmethod
+    def is_supported(cls, file_path: str | Path) -> bool:
+        """Check if a file type is supported.
+
+        Args:
+            file_path: Path to check.
+
+        Returns:
+            True if the file type has a registered chunker.
+        """
+        cls._ensure_initialized()
+
+        path = Path(file_path)
+        ext = path.suffix.lower()
+
+        return ext in cls._chunkers
+
+    @classmethod
+    def get_language(cls, file_path: str | Path) -> str:
+        """Get the language identifier for a file.
+
+        Args:
+            file_path: Path to the file.
+
+        Returns:
+            Language identifier string.
+        """
+        ext_to_language = {
+            ".py": "python",
+            ".pyw": "python",
+            ".js": "javascript",
+            ".jsx": "javascript",
+            ".mjs": "javascript",
+            ".cjs": "javascript",
+            ".ts": "typescript",
+            ".tsx": "typescript",
+            ".mts": "typescript",
+            ".cts": "typescript",
+            ".java": "java",
+            ".md": "markdown",
+            ".markdown": "markdown",
+            ".rst": "rst",
+            ".txt": "text",
+        }
+
+        path = Path(file_path)
+        ext = path.suffix.lower()
+
+        return ext_to_language.get(ext, "unknown")

nexus_dev/chunkers/base.py

@@ -0,0 +1,202 @@
+"""Base classes for code chunkers."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from enum import Enum
+
+
+class ChunkType(str, Enum):
+    """Type of code chunk."""
+
+    FUNCTION = "function"
+    CLASS = "class"
+    METHOD = "method"
+    MODULE = "module"
+    DOCUMENTATION = "documentation"
+    SECTION = "section"  # For documentation sections
+    LESSON = "lesson"
+
+
+@dataclass
+class CodeChunk:
+    """Represents a semantic code chunk.
+
+    Attributes:
+        content: The actual code/text content.
+        chunk_type: Type of chunk (function, class, etc.).
+        name: Name of the code element.
+        start_line: Starting line number (1-indexed).
+        end_line: Ending line number (1-indexed).
+        language: Programming language identifier.
+        file_path: Source file path.
+        parent: Parent element name (e.g., class name for methods).
+        docstring: Extracted docstring if available.
+        imports: List of imports used in this chunk (for context).
+        signature: Function/method signature.
+    """
+
+    content: str
+    chunk_type: ChunkType
+    name: str
+    start_line: int
+    end_line: int
+    language: str
+    file_path: str = ""
+    parent: str | None = None
+    docstring: str | None = None
+    imports: list[str] = field(default_factory=list)
+    signature: str | None = None
+
+    def get_searchable_text(self) -> str:
+        """Get text optimized for embedding and search.
+
+        Combines content with metadata for better semantic matching.
+        """
+        parts = []
+
+        # Add signature/name for context
+        if self.signature:
+            parts.append(f"# {self.signature}")
+        elif self.name:
+            parts.append(f"# {self.chunk_type.value}: {self.name}")
+
+        # Add docstring if available
+        if self.docstring:
+            parts.append(self.docstring)
+
+        # Add content
+        parts.append(self.content)
+
+        return "\n".join(parts)
+
+
+class BaseChunker(ABC):
+    """Abstract base class for all code chunkers.
+
+    To add support for a new language:
+    1. Create a new class inheriting from BaseChunker
+    2. Implement supported_extensions property
+    3. Implement chunk_file and chunk_content methods
+    4. Register the chunker in ChunkerRegistry
+    """
+
+    @property
+    @abstractmethod
+    def supported_extensions(self) -> list[str]:
+        """File extensions this chunker handles.
+
+        Returns:
+            List of extensions including the dot (e.g., ['.py', '.pyw']).
+        """
+
+    @property
+    def language_name(self) -> str:
+        """Human-readable name of the language.
+
+        Returns:
+            Language name (e.g., 'Python', 'JavaScript').
+        """
+        return self.__class__.__name__.replace("Chunker", "")
+
+    @abstractmethod
+    def chunk_file(self, file_path: str, content: str) -> list[CodeChunk]:
+        """Parse a file and extract semantic chunks.
+
+        Args:
+            file_path: Path to the file (for metadata).
+            content: File content as string.
+
+        Returns:
+            List of extracted code chunks.
+        """
+
+    def chunk_content(self, content: str, file_name: str = "unknown") -> list[CodeChunk]:
+        """Parse content string directly.
+
+        Args:
+            content: Code/text content.
+            file_name: Filename for metadata.
+
+        Returns:
+            List of extracted code chunks.
+        """
+        return self.chunk_file(file_name, content)
+
+
+class FallbackChunker(BaseChunker):
+    """Fallback chunker for unsupported file types.
+
+    Uses simple character-based chunking with overlap.
+    """
+
+    MAX_CHUNK_SIZE = 1500
+    OVERLAP_SIZE = 200
+
+    @property
+    def supported_extensions(self) -> list[str]:
+        return []  # Matches nothing, used as fallback
+
+    def chunk_file(self, file_path: str, content: str) -> list[CodeChunk]:
+        """Chunk content by character count with overlap.
+
+        Args:
+            file_path: Path to the file.
+            content: File content.
+
+        Returns:
+            List of text chunks.
+        """
+        if not content.strip():
+            return []
+
+        # For small files, return as single chunk
+        if len(content) <= self.MAX_CHUNK_SIZE:
+            return [
+                CodeChunk(
+                    content=content,
+                    chunk_type=ChunkType.MODULE,
+                    name=file_path.split("/")[-1] if "/" in file_path else file_path,
+                    start_line=1,
+                    end_line=content.count("\n") + 1,
+                    language="unknown",
+                    file_path=file_path,
+                )
+            ]
+
+        # Split into overlapping chunks
+        chunks = []
+        start = 0
+        chunk_index = 0
+
+        while start < len(content):
+            end = min(start + self.MAX_CHUNK_SIZE, len(content))
+
+            # Try to break at a newline
+            if end < len(content):
+                newline_pos = content.rfind("\n", start, end)
+                if newline_pos > start + self.MAX_CHUNK_SIZE // 2:
+                    end = newline_pos + 1
+
+            chunk_text = content[start:end]
+            start_line = content[:start].count("\n") + 1
+            end_line = start_line + chunk_text.count("\n")
+
+            chunks.append(
+                CodeChunk(
+                    content=chunk_text,
+                    chunk_type=ChunkType.MODULE,
+                    name=f"{file_path.split('/')[-1]}:chunk_{chunk_index}",
+                    start_line=start_line,
+                    end_line=end_line,
+                    language="unknown",
+                    file_path=file_path,
+                )
+            )
+
+            # Move start with overlap
+            start = end - self.OVERLAP_SIZE if end < len(content) else end
+            chunk_index += 1
+
+        return chunks