nexus-dev 3.2.0__py3-none-any.whl

nexus_dev/__init__.py

@@ -0,0 +1,4 @@
+"""Nexus-Dev: MCP Server for Persistent AI Coding Assistant Memory."""
+
+__version__ = "0.1.0"
+__author__ = "Marco Mornati"

nexus_dev/agent_templates/__init__.py

@@ -0,0 +1,26 @@
+"""Agent templates package."""
+
+from pathlib import Path
+
+TEMPLATES_DIR = Path(__file__).parent
+
+
+def get_template_path(template_name: str) -> Path:
+    """Get the path to a template file.
+
+    Args:
+        template_name: Name of the template (without .yaml extension).
+
+    Returns:
+        Path to the template YAML file.
+    """
+    return TEMPLATES_DIR / f"{template_name}.yaml"
+
+
+def list_templates() -> list[str]:
+    """List all available template names.
+
+    Returns:
+        List of template names (without .yaml extension).
+    """
+    return [p.stem for p in TEMPLATES_DIR.glob("*.yaml") if not p.name.startswith("_")]

nexus_dev/agent_templates/api_designer.yaml

@@ -0,0 +1,26 @@
+name: "api_designer"
+display_name: "API Designer"
+description: "Reviews and designs REST/GraphQL APIs following best practices."
+
+profile:
+  role: "API Architect"
+  goal: "Design RESTful and GraphQL APIs that are intuitive, consistent, and follow industry best practices"
+  backstory: |
+    API architect with extensive experience in designing scalable, developer-friendly APIs.
+    Expert in REST principles, GraphQL schema design, API versioning, and documentation.
+    Has designed APIs for companies ranging from startups to enterprises. Believes that
+    great APIs are predictable, consistent, and self-explanatory.
+  tone: "Professional, pragmatic, and standards-focused"
+
+memory:
+  enabled: true
+  rag_limit: 6
+  search_types: ["code", "documentation", "lesson"]
+
+tools: []
+
+llm_config:
+  model_hint: "claude-sonnet-4.5"
+  fallback_hints: ["gpt-5.2", "gemini-3-pro", "auto"]
+  temperature: 0.4
+  max_tokens: 5000

nexus_dev/agent_templates/code_reviewer.yaml

@@ -0,0 +1,26 @@
+name: "code_reviewer"
+display_name: "Code Reviewer"
+description: "Analyzes code for bugs, security issues, and best practices."
+
+profile:
+  role: "Senior Code Reviewer"
+  goal: "Identify bugs, security vulnerabilities, and suggest improvements following best practices"
+  backstory: |
+    Expert software engineer with 15+ years of experience in code quality assurance.
+    Specialized in identifying subtle bugs, security vulnerabilities, and architectural issues.
+    Familiar with SOLID principles, design patterns, and language-specific best practices.
+    Provides constructive feedback that helps developers learn and improve.
+  tone: "Professional, constructive, and educational"
+
+memory:
+  enabled: true
+  rag_limit: 8
+  search_types: ["code", "documentation", "lesson"]
+
+tools: []
+
+llm_config:
+  model_hint: "claude-sonnet-4.5"
+  fallback_hints: ["gpt-5.2-codex", "gemini-3-pro", "auto"]
+  temperature: 0.3
+  max_tokens: 4000

nexus_dev/agent_templates/debug_detective.yaml

@@ -0,0 +1,26 @@
+name: "debug_detective"
+display_name: "Debug Detective"
+description: "Investigates bugs, analyzes stack traces, and proposes targeted fixes."
+
+profile:
+  role: "Debugging Specialist"
+  goal: "Analyze errors, trace root causes, and propose precise, targeted fixes"
+  backstory: |
+    Veteran debugger with a methodical approach to solving cryptic errors.
+    Expert in reading stack traces, understanding memory issues, async debugging,
+    and race conditions. Has a systematic process: reproduce, isolate, understand, fix.
+    Known for finding the needle in the haystack.
+  tone: "Analytical, patient, and thorough"
+
+memory:
+  enabled: true
+  rag_limit: 10
+  search_types: ["code", "lesson", "documentation"]
+
+tools: []
+
+llm_config:
+  model_hint: "claude-sonnet-4.5"
+  fallback_hints: ["gemini-3-deep-think", "gpt-5.2-codex", "auto"]
+  temperature: 0.2
+  max_tokens: 6000

nexus_dev/agent_templates/doc_writer.yaml

@@ -0,0 +1,26 @@
+name: "doc_writer"
+display_name: "Documentation Writer"
+description: "Creates and improves technical documentation, API docs, and README files."
+
+profile:
+  role: "Technical Writer"
+  goal: "Create clear, comprehensive documentation that helps developers understand and use code effectively"
+  backstory: |
+    Professional technical writer with expertise in developer documentation.
+    Skilled at explaining complex concepts in simple terms, creating API references,
+    writing tutorials, and maintaining README files. Believes good documentation
+    is as important as good code.
+  tone: "Clear, friendly, and helpful"
+
+memory:
+  enabled: true
+  rag_limit: 6
+  search_types: ["code", "documentation", "lesson"]
+
+tools: []
+
+llm_config:
+  model_hint: "claude-opus-4.5"
+  fallback_hints: ["claude-sonnet-4.5", "gpt-5.2", "auto"]
+  temperature: 0.6
+  max_tokens: 6000

nexus_dev/agent_templates/performance_optimizer.yaml

@@ -0,0 +1,26 @@
+name: "performance_optimizer"
+display_name: "Performance Optimizer"
+description: "Identifies performance bottlenecks and recommends optimizations."
+
+profile:
+  role: "Performance Engineer"
+  goal: "Identify performance bottlenecks, optimize code for speed and efficiency, and reduce resource consumption"
+  backstory: |
+    Performance engineering specialist with expertise in profiling, benchmarking, and optimization.
+    Skilled at identifying N+1 queries, memory leaks, inefficient algorithms, and resource bottlenecks.
+    Has optimized applications handling millions of requests per day. Believes in measuring first,
+    then optimizing based on data.
+  tone: "Data-driven, analytical, and results-oriented"
+
+memory:
+  enabled: true
+  rag_limit: 8
+  search_types: ["code", "documentation", "lesson"]
+
+tools: []
+
+llm_config:
+  model_hint: "gemini-3-pro"
+  fallback_hints: ["claude-sonnet-4.5", "gpt-5.2-codex", "auto"]
+  temperature: 0.3
+  max_tokens: 5000

nexus_dev/agent_templates/refactor_architect.yaml

@@ -0,0 +1,26 @@
+name: "refactor_architect"
+display_name: "Refactor Architect"
+description: "Restructures code for better maintainability, performance, and design patterns."
+
+profile:
+  role: "Refactoring Expert"
+  goal: "Restructure code to improve readability, maintainability, and performance without changing behavior"
+  backstory: |
+    Software architect with deep expertise in design patterns and clean code principles.
+    Specializes in identifying code smells, reducing complexity, and applying SOLID principles.
+    Has successfully refactored legacy codebases for Fortune 500 companies. Believes that
+    well-structured code is easier to understand, test, and extend.
+  tone: "Strategic, clear, and methodical"
+
+memory:
+  enabled: true
+  rag_limit: 10
+  search_types: ["code", "documentation", "lesson"]
+
+tools: []
+
+llm_config:
+  model_hint: "gemini-3-deep-think"
+  fallback_hints: ["claude-opus-4.5", "claude-sonnet-4.5", "auto"]
+  temperature: 0.4
+  max_tokens: 6000

nexus_dev/agent_templates/security_auditor.yaml

@@ -0,0 +1,26 @@
+name: "security_auditor"
+display_name: "Security Auditor"
+description: "Identifies security vulnerabilities and recommends fixes based on OWASP guidelines."
+
+profile:
+  role: "Security Analyst"
+  goal: "Identify security vulnerabilities, recommend fixes, and ensure code follows security best practices"
+  backstory: |
+    Cybersecurity expert with focus on application security and secure coding practices.
+    Familiar with OWASP Top 10, common vulnerabilities (SQL injection, XSS, CSRF, etc.),
+    and security frameworks. Has experience with security audits, penetration testing,
+    and secure code reviews for financial and healthcare applications.
+  tone: "Serious, precise, and security-focused"
+
+memory:
+  enabled: true
+  rag_limit: 7
+  search_types: ["code", "documentation", "lesson"]
+
+tools: []
+
+llm_config:
+  model_hint: "claude-opus-4.5"
+  fallback_hints: ["claude-sonnet-4.5", "gpt-5.2", "auto"]
+  temperature: 0.2
+  max_tokens: 5000

nexus_dev/agent_templates/test_engineer.yaml

@@ -0,0 +1,26 @@
+name: "test_engineer"
+display_name: "Test Engineer"
+description: "Generates comprehensive test cases and improves test coverage."
+
+profile:
+  role: "QA Engineer"
+  goal: "Generate comprehensive test cases covering edge cases, improve test coverage, and ensure code quality"
+  backstory: |
+    Quality assurance specialist with expertise in TDD and BDD methodologies.
+    Skilled in pytest, Jest, JUnit, and other testing frameworks. Believes in testing
+    the unhappy paths as much as the happy ones. Writes tests that are readable,
+    maintainable, and catch real bugs.
+  tone: "Methodical, detail-oriented, and thorough"
+
+memory:
+  enabled: true
+  rag_limit: 5
+  search_types: ["code", "documentation", "lesson"]
+
+tools: []
+
+llm_config:
+  model_hint: "gpt-5.2-codex"
+  fallback_hints: ["claude-sonnet-4.5", "gemini-3-pro", "auto"]
+  temperature: 0.4
+  max_tokens: 4000

nexus_dev/agents/__init__.py

@@ -0,0 +1,20 @@
+"""Nexus-Dev Custom Agents Package.
+
+This package provides functionality for defining and executing custom AI agents
+that leverage the project's RAG (lessons/docs) and MCP tools.
+"""
+
+from .agent_config import AgentConfig, AgentMemory, AgentProfile, LLMConfig
+from .agent_executor import AgentExecutor
+from .agent_manager import AgentManager
+from .prompt_factory import PromptFactory
+
+__all__ = [
+    "AgentConfig",
+    "AgentProfile",
+    "AgentMemory",
+    "LLMConfig",
+    "AgentManager",
+    "AgentExecutor",
+    "PromptFactory",
+]

nexus_dev/agents/agent_config.py

@@ -0,0 +1,97 @@
+"""Pydantic models for agent configuration."""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+
+class AgentProfile(BaseModel):
+    """Agent persona definition.
+
+    Attributes:
+        role: Role title (e.g., 'Code Reviewer').
+        goal: Primary objective of the agent.
+        backstory: Agent's background and expertise.
+        tone: Communication style.
+    """
+
+    role: str = Field(..., description="Role title (e.g., 'Code Reviewer')")
+    goal: str = Field(..., description="Primary objective")
+    backstory: str = Field(..., description="Agent's background and expertise")
+    tone: str = Field(default="Professional and direct")
+
+
+class AgentMemory(BaseModel):
+    """RAG configuration for the agent.
+
+    Attributes:
+        enabled: Whether to enable project RAG search.
+        rag_limit: Maximum number of context chunks to retrieve.
+        search_types: Document types to include in RAG search.
+    """
+
+    enabled: bool = Field(default=True, description="Enable project RAG search")
+    rag_limit: int = Field(default=5, ge=1, le=20, description="Max context chunks")
+    search_types: list[Literal["code", "documentation", "lesson"]] = Field(
+        default=["code", "documentation", "lesson"],
+        description="Document types to include in RAG",
+    )
+
+
+class LLMConfig(BaseModel):
+    """Model hint for MCP Sampling.
+
+    The model_hint is sent to the IDE as a preference. The IDE may use a different
+    model based on its configuration and available models.
+
+    Attributes:
+        model_hint: Suggested model name for the IDE.
+        fallback_hints: Alternative models if primary is unavailable.
+        temperature: Sampling temperature.
+        max_tokens: Maximum tokens in response.
+    """
+
+    model_hint: str = Field(
+        default="claude-sonnet-4.5",
+        description="Model preference sent to IDE (hint only)",
+    )
+    fallback_hints: list[str] = Field(
+        default_factory=lambda: ["auto"],
+        description="Fallback models if primary unavailable",
+    )
+    temperature: float = Field(default=0.5, ge=0.0, le=2.0)
+    max_tokens: int = Field(default=4000, ge=100, le=32000)
+
+
+class AgentConfig(BaseModel):
+    """Complete agent configuration.
+
+    This model represents a complete agent definition loaded from a YAML file.
+    It includes the agent's identity, memory settings, tool access, and LLM preferences.
+
+    Attributes:
+        name: Internal identifier (lowercase with underscores).
+        display_name: Human-readable name for the agent.
+        description: Tool description for AI discovery.
+        profile: Agent persona definition.
+        memory: RAG configuration.
+        tools: List of allowed MCP tool names (empty = all tools).
+        llm_config: Model preferences for MCP Sampling.
+    """
+
+    name: str = Field(
+        ...,
+        pattern=r"^[a-z][a-z0-9_]*$",
+        description="Internal ID (lowercase, underscores allowed)",
+    )
+    display_name: str = Field(..., description="Human-readable name")
+    description: str = Field(..., description="Tool description for AI discovery")
+    profile: AgentProfile
+    memory: AgentMemory = Field(default_factory=AgentMemory)
+    tools: list[str] = Field(
+        default_factory=list,
+        description="Allowed MCP tool names (empty = all project tools)",
+    )
+    llm_config: LLMConfig = Field(default_factory=LLMConfig)

nexus_dev/agents/agent_executor.py

@@ -0,0 +1,197 @@
+"""Execute agent tasks using MCP Sampling."""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+
+from mcp.types import (
+    CreateMessageRequestParams,
+    ModelHint,
+    ModelPreferences,
+    SamplingMessage,
+    TextContent,
+)
+
+from .agent_config import AgentConfig
+from .prompt_factory import PromptFactory
+
+if TYPE_CHECKING:
+    from mcp.server.fastmcp import FastMCP
+
+    from ..database import NexusDatabase
+
+logger = logging.getLogger(__name__)
+
+
+class AgentExecutor:
+    """Orchestrate agent execution with RAG and MCP Sampling.
+
+    This executor:
+    1. Retrieves relevant context from the project's LanceDB (RAG)
+    2. Builds a structured system prompt using PromptFactory
+    3. Sends a sampling request to the IDE via MCP
+    4. Returns the IDE's response
+    """
+
+    def __init__(
+        self,
+        config: AgentConfig,
+        database: NexusDatabase,
+        mcp_server: FastMCP,
+    ) -> None:
+        """Initialize the agent executor.
+
+        Args:
+            config: Agent configuration from YAML.
+            database: NexusDatabase instance for RAG search.
+            mcp_server: FastMCP server instance for sampling requests.
+        """
+        self.config = config
+        self.database = database
+        self.mcp_server = mcp_server
+
+    async def execute(self, user_task: str, project_id: str | None = None) -> str:
+        """Execute a task with the configured agent.
+
+        The execution flow:
+        1. Retrieve relevant context from RAG based on the task
+        2. Build system prompt with agent persona and context
+        3. Send sampling request to IDE
+        4. Return the response
+
+        Args:
+            user_task: The task description from the user.
+            project_id: Optional project ID for RAG filtering.
+
+        Returns:
+            The agent's response text.
+        """
+        from ..database import DocumentType
+
+        # 1. RAG Retrieval
+        context_items: list[str] = []
+        if self.config.memory.enabled:
+            for search_type in self.config.memory.search_types:
+                try:
+                    doc_type = DocumentType(search_type)
+                    results = await self.database.search(
+                        query=user_task,
+                        project_id=project_id,
+                        doc_type=doc_type,
+                        limit=self.config.memory.rag_limit,
+                    )
+                    # Truncate each result to avoid context overflow
+                    context_items.extend([r.text[:500] for r in results])
+                except Exception as e:
+                    logger.warning("RAG search failed for %s: %s", search_type, e)
+
+        logger.debug(
+            "Agent %s retrieved %d context items for task: %s",
+            self.config.name,
+            len(context_items),
+            user_task[:100],
+        )
+
+        # 2. Build Prompt
+        system_prompt = PromptFactory.build(
+            agent=self.config,
+            context_items=context_items,
+            available_tools=self.config.tools if self.config.tools else None,
+        )
+
+        # 3. MCP Sampling Request
+        try:
+            # Create the sampling request parameters
+            model_prefs = ModelPreferences(
+                hints=[ModelHint(name=self.config.llm_config.model_hint)],
+            )
+
+            request_params = CreateMessageRequestParams(
+                messages=[
+                    SamplingMessage(
+                        role="user",
+                        content=TextContent(type="text", text=user_task),
+                    )
+                ],
+                systemPrompt=system_prompt,
+                modelPreferences=model_prefs,
+                maxTokens=self.config.llm_config.max_tokens,
+            )
+
+            # Access the session from the request context
+            # Note: This requires the server to be in a request context
+            ctx = self.mcp_server.get_context()
+            result = await ctx.session.create_message(
+                messages=request_params.messages,
+                system_prompt=request_params.systemPrompt,
+                model_preferences=request_params.modelPreferences,
+                max_tokens=request_params.maxTokens,
+            )
+
+            # 4. Extract and return response text
+            if hasattr(result.content, "text"):
+                return str(result.content.text)
+            return str(result.content)
+
+        except Exception as e:
+            error_msg = str(e)
+            if "does not support CreateMessage" in error_msg or "Method not found" in error_msg:
+                logger.warning(
+                    "MCP Sampling not supported by client. Returning context-only response."
+                )
+                return self._create_fallback_response(user_task, context_items, system_prompt)
+
+            logger.error("MCP Sampling failed for agent %s: %s", self.config.name, e)
+            return f"Agent execution failed: {e}"
+
+    def _create_fallback_response(
+        self, user_task: str, context_items: list[str], system_prompt: str
+    ) -> str:
+        """Create a Markdown response when full agent execution is not supported.
+
+        Args:
+            user_task: The original task.
+            context_items: List of retrieved context strings.
+            system_prompt: The constructed system prompt.
+
+        Returns:
+            Formatted Markdown string.
+        """
+        response = [
+            f"# Agent: {self.config.display_name} (Insight Mode)",
+            "",
+            "> **Note**: Your IDE does not support fully autonomous agent "
+            "execution (MCP Sampling).",
+            "> I have retrieved the relevant context and prepared the prompt for you below.",
+            "",
+            "## 1. Retrieved Context",
+            f"Found {len(context_items)} relevant items in the knowledge base:",
+            "",
+        ]
+
+        if context_items:
+            for i, item in enumerate(context_items, 1):
+                # Try to extract a clean title or first line
+                preview = item.split("\n")[0][:80]
+                response.append(f"**Item {i}**: `{preview}...`")
+                # Indent the content for better readability in the details block
+                response.append("<details>")
+                response.append(f"<summary>View Content</summary>\n\n{item}\n")
+                response.append("</details>\n")
+        else:
+            response.append("*No relevant context found.*")
+
+        response.extend(
+            [
+                "",
+                "## 2. Recommended System Prompt",
+                "You can use this prompt with your own LLM:",
+                "",
+                "```text",
+                system_prompt,
+                "```",
+            ]
+        )
+
+        return "\n".join(response)

nexus_dev/agents/agent_manager.py

@@ -0,0 +1,104 @@
+"""Load and manage agent configurations."""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Iterator
+from pathlib import Path
+
+import yaml
+
+from .agent_config import AgentConfig
+
+logger = logging.getLogger(__name__)
+
+
+class AgentManager:
+    """Scan and load agent YAML configurations.
+
+    This manager:
+    - Scans the `agents/` directory in the project root
+    - Loads and validates each YAML file as an AgentConfig
+    - Provides access to loaded agents by name
+    """
+
+    def __init__(self, agents_dir: Path | None = None) -> None:
+        """Initialize the agent manager.
+
+        Args:
+            agents_dir: Path to the agents directory. Defaults to `./agents/`.
+        """
+        self.agents_dir = agents_dir or Path.cwd() / "agents"
+        self.agents: dict[str, AgentConfig] = {}
+        self._load_agents()
+
+    def _load_agents(self) -> None:
+        """Load all valid agent configs from the agents directory.
+
+        Invalid configs are logged as warnings but don't prevent other agents
+        from loading.
+        """
+        if not self.agents_dir.exists():
+            logger.debug("Agents directory not found: %s", self.agents_dir)
+            return
+
+        yaml_files = list(self.agents_dir.glob("*.yaml")) + list(self.agents_dir.glob("*.yml"))
+
+        for yaml_file in yaml_files:
+            try:
+                with open(yaml_file, encoding="utf-8") as f:
+                    data = yaml.safe_load(f)
+
+                if not data:
+                    logger.warning("Empty agent file: %s", yaml_file.name)
+                    continue
+
+                agent = AgentConfig(**data)
+                self.agents[agent.name] = agent
+                logger.info("Loaded agent: %s from %s", agent.name, yaml_file.name)
+
+            except yaml.YAMLError as e:
+                logger.warning("Invalid YAML in %s: %s", yaml_file.name, e)
+            except Exception as e:
+                logger.warning("Failed to load agent %s: %s", yaml_file.name, e)
+
+        logger.info("Loaded %d agents from %s", len(self.agents), self.agents_dir)
+
+    def reload(self) -> None:
+        """Reload agents from disk.
+
+        This clears the current agents and reloads from the directory.
+        """
+        self.agents.clear()
+        self._load_agents()
+
+    def get_agent(self, name: str) -> AgentConfig | None:
+        """Get agent by name.
+
+        Args:
+            name: The agent's internal name.
+
+        Returns:
+            AgentConfig if found, None otherwise.
+        """
+        return self.agents.get(name)
+
+    def list_agents(self) -> list[AgentConfig]:
+        """List all loaded agents.
+
+        Returns:
+            List of AgentConfig instances.
+        """
+        return list(self.agents.values())
+
+    def __len__(self) -> int:
+        """Return number of loaded agents."""
+        return len(self.agents)
+
+    def __iter__(self) -> Iterator[AgentConfig]:
+        """Iterate over loaded agents."""
+        return iter(self.agents.values())
+
+    def __contains__(self, name: str) -> bool:
+        """Check if an agent is loaded."""
+        return name in self.agents