shotgun-sh 0.1.0.dev1__py3-none-any.whl

shotgun/codebase/service.py

@@ -0,0 +1,148 @@
+"""High-level service for managing codebase graphs and executing queries."""
+
+import time
+from pathlib import Path
+from typing import Any
+
+from shotgun.codebase.core.manager import CodebaseGraphManager
+from shotgun.codebase.core.nl_query import generate_cypher
+from shotgun.codebase.models import CodebaseGraph, QueryResult, QueryType
+from shotgun.logging_config import get_logger
+
+logger = get_logger(__name__)
+
+
+class CodebaseService:
+    """High-level service for codebase graph management and querying."""
+
+    def __init__(self, storage_dir: Path | str):
+        """Initialize the service.
+
+        Args:
+            storage_dir: Directory to store graph databases
+        """
+        if isinstance(storage_dir, str):
+            storage_dir = Path(storage_dir)
+
+        self.storage_dir = storage_dir
+        self.storage_dir.mkdir(parents=True, exist_ok=True)
+        self.manager = CodebaseGraphManager(storage_dir)
+
+    async def list_graphs(self) -> list[CodebaseGraph]:
+        """List all existing graphs.
+
+        Returns:
+            List of CodebaseGraph objects
+        """
+        return await self.manager.list_graphs()
+
+    async def create_graph(self, repo_path: str | Path, name: str) -> CodebaseGraph:
+        """Create and index a new graph from a repository.
+
+        Args:
+            repo_path: Path to the repository to index
+            name: Human-readable name for the graph
+
+        Returns:
+            The created CodebaseGraph
+        """
+        return await self.manager.build_graph(str(repo_path), name)
+
+    async def get_graph(self, graph_id: str) -> CodebaseGraph | None:
+        """Get graph metadata by ID.
+
+        Args:
+            graph_id: Graph ID to retrieve
+
+        Returns:
+            CodebaseGraph object or None if not found
+        """
+        return await self.manager.get_graph(graph_id)
+
+    async def delete_graph(self, graph_id: str) -> None:
+        """Delete a graph and its data.
+
+        Args:
+            graph_id: Graph ID to delete
+        """
+        await self.manager.delete_graph(graph_id)
+
+    async def reindex_graph(self, graph_id: str) -> dict[str, Any]:
+        """Rebuild an existing graph (full reindex).
+
+        Args:
+            graph_id: Graph ID to reindex
+
+        Returns:
+            Statistics from the reindex operation
+        """
+        return await self.manager.update_graph_incremental(graph_id)
+
+    async def execute_query(
+        self,
+        graph_id: str,
+        query: str,
+        query_type: QueryType,
+        parameters: dict[str, Any] | None = None,
+    ) -> QueryResult:
+        """Execute a query against a graph.
+
+        Args:
+            graph_id: Graph ID to query
+            query: The query (natural language or Cypher)
+            query_type: Type of query being executed
+            parameters: Optional parameters for Cypher queries
+
+        Returns:
+            QueryResult with results and metadata
+        """
+        start_time = time.time()
+        cypher_query = None
+
+        try:
+            # Handle query type conversion
+            if query_type == QueryType.NATURAL_LANGUAGE:
+                logger.info(f"Converting natural language query to Cypher: {query}")
+                cypher_query = await generate_cypher(query)
+                logger.info(f"Generated Cypher: {cypher_query}")
+                execute_query = cypher_query
+            else:
+                execute_query = query
+
+            # Execute the query
+            results = await self.manager.execute_query(
+                graph_id=graph_id, query=execute_query, parameters=parameters
+            )
+
+            # Extract column names from first result
+            column_names = list(results[0].keys()) if results else []
+
+            execution_time = (time.time() - start_time) * 1000
+
+            return QueryResult(
+                query=query,
+                cypher_query=cypher_query
+                if query_type == QueryType.NATURAL_LANGUAGE
+                else None,
+                results=results,
+                column_names=column_names,
+                row_count=len(results),
+                execution_time_ms=execution_time,
+                success=True,
+                error=None,
+            )
+
+        except Exception as e:
+            execution_time = (time.time() - start_time) * 1000
+            logger.error(f"Query execution failed: {e}")
+
+            return QueryResult(
+                query=query,
+                cypher_query=cypher_query,
+                results=[],
+                column_names=[],
+                row_count=0,
+                execution_time_ms=execution_time,
+                success=False,
+                error=str(e),
+            )

shotgun/logging_config.py

@@ -0,0 +1,172 @@
+"""Centralized logging configuration for Shotgun CLI."""
+
+import logging
+import logging.handlers
+import os
+import sys
+from pathlib import Path
+
+
+def get_log_directory() -> Path:
+    """Get the log directory path, creating it if necessary.
+
+    Returns:
+        Path to log directory (~/.shotgun-sh/logs/)
+    """
+    # Lazy import to avoid circular dependency
+    from shotgun.utils.file_system_utils import get_shotgun_home
+
+    log_dir = get_shotgun_home() / "logs"
+    log_dir.mkdir(parents=True, exist_ok=True)
+    return log_dir
+
+
+class ColoredFormatter(logging.Formatter):
+    """Custom formatter with colors for different log levels."""
+
+    # ANSI color codes
+    COLORS = {
+        "DEBUG": "\033[36m",  # Cyan
+        "INFO": "\033[32m",  # Green
+        "WARNING": "\033[33m",  # Yellow
+        "ERROR": "\033[31m",  # Red
+        "CRITICAL": "\033[35m",  # Magenta
+    }
+    RESET = "\033[0m"
+
+    def format(self, record: logging.LogRecord) -> str:
+        # Create a copy of the record to avoid modifying the original
+        record = logging.makeLogRecord(record.__dict__)
+
+        # Add color to levelname
+        if record.levelname in self.COLORS:
+            colored_levelname = (
+                f"{self.COLORS[record.levelname]}{record.levelname}{self.RESET}"
+            )
+            record.levelname = colored_levelname
+
+        return super().format(record)
+
+
+def setup_logger(
+    name: str,
+    format_string: str | None = None,
+) -> logging.Logger:
+    """Set up a logger with consistent configuration.
+
+    Args:
+        name: Logger name (typically __name__)
+        format_string: Custom format string, uses default if None
+
+    Returns:
+        Configured logger instance
+    """
+    logger = logging.getLogger(name)
+
+    # Avoid adding duplicate handlers
+    if logger.handlers:
+        return logger
+
+    # Get log level from environment variable, default to ERROR
+    env_level = os.getenv("SHOTGUN_LOG_LEVEL", "ERROR").upper()
+    if env_level not in ["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"]:
+        env_level = "ERROR"
+
+    logger.setLevel(getattr(logging, env_level))
+
+    # Default format string
+    if format_string is None:
+        format_string = "%(asctime)s | %(levelname)-8s | %(name)s | %(message)s"
+
+    # Check if console logging is enabled (default: off)
+    console_logging_enabled = os.getenv("LOGGING_TO_CONSOLE", "false").lower() == "true"
+
+    if console_logging_enabled:
+        # Create console handler
+        console_handler = logging.StreamHandler(sys.stdout)
+        console_handler.setLevel(getattr(logging, env_level))
+
+        # Use colored formatter for console
+        console_formatter = ColoredFormatter(format_string, datefmt="%H:%M:%S")
+        console_handler.setFormatter(console_formatter)
+
+        # Add handler to logger
+        logger.addHandler(console_handler)
+
+    # Check if file logging is enabled (default: on)
+    file_logging_enabled = os.getenv("LOGGING_TO_FILE", "true").lower() == "true"
+
+    if file_logging_enabled:
+        try:
+            # Create file handler with rotation
+            log_dir = get_log_directory()
+            log_file = log_dir / "shotgun.log"
+
+            # Use TimedRotatingFileHandler - rotates daily and keeps 7 days of logs
+            file_handler = logging.handlers.TimedRotatingFileHandler(
+                filename=log_file,
+                when="midnight",  # Rotate at midnight
+                interval=1,  # Every 1 day
+                backupCount=7,  # Keep 7 days of logs
+                encoding="utf-8",
+            )
+
+            # Also set max file size (10MB) using RotatingFileHandler as fallback
+            # Note: We'll use TimedRotatingFileHandler which handles both time and size
+            file_handler.setLevel(getattr(logging, env_level))
+
+            # Use standard formatter for file (no colors)
+            file_formatter = logging.Formatter(
+                format_string, datefmt="%Y-%m-%d %H:%M:%S"
+            )
+            file_handler.setFormatter(file_formatter)
+
+            # Add handler to logger
+            logger.addHandler(file_handler)
+        except Exception as e:
+            # If file logging fails, log to stderr but don't crash
+            print(f"Warning: Could not set up file logging: {e}", file=sys.stderr)
+
+    # Prevent propagation to avoid duplicate messages from parent loggers
+    if name != "shotgun":  # Keep propagation for root logger
+        logger.propagate = False
+
+    return logger
+
+
+def get_logger(name: str) -> logging.Logger:
+    """Get a logger instance with default configuration.
+
+    Args:
+        name: Logger name (typically __name__)
+
+    Returns:
+        Logger instance with handlers configured
+    """
+    logger = logging.getLogger(name)
+
+    # If logger doesn't have handlers, set it up
+    if not logger.handlers:
+        return setup_logger(name)
+
+    return logger
+
+
+def set_global_log_level(level: str) -> None:
+    """Set log level for all shotgun loggers.
+
+    Args:
+        level: Log level ("DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL")
+    """
+    # Set level for all existing shotgun loggers
+    for name, logger in logging.getLogger().manager.loggerDict.items():
+        if isinstance(logger, logging.Logger) and name.startswith("shotgun"):
+            logger.setLevel(getattr(logging, level.upper()))
+            # Only set handler levels if handlers exist
+            for handler in logger.handlers:
+                handler.setLevel(getattr(logging, level.upper()))
+
+
+def configure_root_logger() -> None:
+    """Configure the root shotgun logger."""
+    setup_logger("shotgun")

shotgun/main.py

@@ -0,0 +1,73 @@
+"""Main CLI application for shotgun."""
+
+from typing import Annotated
+
+import typer
+from dotenv import load_dotenv
+
+from shotgun.agents.config import get_config_manager
+from shotgun.cli import codebase, config, plan, research, tasks
+from shotgun.logging_config import configure_root_logger, get_logger
+from shotgun.telemetry import setup_phoenix_observability
+
+# Load environment variables from .env file
+load_dotenv()
+
+# Initialize logging
+configure_root_logger()
+logger = get_logger(__name__)
+
+# Initialize configuration
+try:
+    config_manager = get_config_manager()
+    config_manager.load()  # Ensure config is loaded at startup
+except Exception as e:
+    logger.debug("Configuration initialization warning: %s", e)
+
+# Initialize telemetry
+_telemetry_enabled = setup_phoenix_observability()
+logger.debug("Phoenix observability enabled: %s", _telemetry_enabled)
+
+app = typer.Typer(
+    name="shotgun",
+    help="Shotgun - AI-powered CLI tool for research, planning, and task management",
+    no_args_is_help=True,
+    rich_markup_mode="rich",
+)
+
+# Add commands
+app.add_typer(config.app, name="config", help="Manage Shotgun configuration")
+app.add_typer(
+    codebase.app, name="codebase", help="Manage and query code knowledge graphs"
+)
+app.add_typer(research.app, name="research", help="Perform research with agentic loops")
+app.add_typer(plan.app, name="plan", help="Generate structured plans")
+app.add_typer(tasks.app, name="tasks", help="Generate task lists with agentic approach")
+
+
+def version_callback(value: bool) -> None:
+    """Show version and exit."""
+    if value:
+        logger.info("shotgun 0.1.0")
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    version: Annotated[
+        bool,
+        typer.Option(
+            "--version",
+            "-v",
+            callback=version_callback,
+            is_eager=True,
+            help="Show version and exit",
+        ),
+    ] = False,
+) -> None:
+    """Shotgun - AI-powered CLI tool."""
+    logger.debug("Starting shotgun CLI application")
+
+
+if __name__ == "__main__":
+    app()

shotgun/prompts/__init__.py

@@ -0,0 +1,5 @@
+"""Jinja2 template-based prompt management for Shotgun LLM agents."""
+
+from .loader import PromptLoader
+
+__all__ = ["PromptLoader"]

shotgun/prompts/agents/__init__.py

@@ -0,0 +1 @@
+"""Agent-specific prompt templates."""

shotgun/prompts/agents/partials/codebase_understanding.j2

@@ -0,0 +1,79 @@
+{% if codebase_understanding_graphs -%}
+**Graph Tools Available**:
+- `query_graph` - Query this graph using natural language
+- `retrieve_code` - Get source code by qualified name (e.g., "module.Class.method")
+- `codebase_shell` - Run shell commands in the codebase context
+- `directory_lister` - List directory contents in the codebase
+- `file_read` - Read file contents in the codebase
+
+## Using codebases
+
+When you have a codebase available, assume the user is asking you about that codebase or in context of that codebase.
+Make sure to check the codebase before answering any question or suggesting any action.
+
+## Codebase Analysis Guidelines
+
+1. **Use existing graphs** when analyzing code structure, dependencies, or relationships
+2. **Query graphs** using natural language with the `query_graph` tool - ask questions like:
+   - "Find all classes that inherit from BaseModel"
+   - "Show functions with the most dependencies"
+   - "What are the main entry points in this codebase?"
+3. **Retrieve specific code** using `retrieve_code` with fully qualified names (module.Class.method)
+
+## Code Graph Query Examples
+
+**Natural Language Queries**:
+- "Find all functions that call each other"
+- "What classes are in the user authentication module?"
+- "Show me the dependencies of the main application class"
+- "List all test functions that are not being called"
+- "Find functions with high cyclomatic complexity"
+
+**Graph Management**:
+- Use graph IDs shown above when calling codebase tools
+- Each session can have multiple graphs for different repositories
+- Graphs persist across sessions and are shared between users working on the same repository
+
+## Codebase Tools and Management
+
+Important:
+- From a technical point of view, the codebase is represented as a graph, but the user might refer to it as a project, repository, folder or graph. Always refer to it as codebase by default but adopt the user terminology in your answer.
+- Always think about a plan first and communicate this plan back to the user BEFORE calling any codebase management or codebase understanding tools.
+- **GRAPH ID vs NAME**: Every graph has both a NAME (like "Shotgun2") and an ID (like "993ec896213d"). The name is for human reference only. ALL TOOLS REQUIRE THE GRAPH ID, NOT THE NAME!
+
+**CRITICAL RULES:**
+0.  **ALWAYS USE GRAPH ID**: When calling ANY tool that requires a graph_id parameter, you MUST use the ID (e.g., "993ec896213d"), NOT the name (e.g., "Shotgun2"). The name is only for human reference.
+1.  **TOOL-ONLY ANSWERS**: You must ONLY use information from the tools provided. Do not use external knowledge.
+2.  **NATURAL LANGUAGE QUERIES**: When using the `query_graph` tool, ALWAYS use natural language questions. NEVER write Cypher queries directly - the tool will translate your natural language into the appropriate database query.
+3.  **HONESTY**: If a tool fails or returns no results, you MUST state that clearly and report any error messages. Do not invent answers.
+
+### Workflow
+
+If the task you received is about codebase management, follow the codebase management workflow. If it is about understanding an existing codebase, follow the Codebase Understanding Workflow.
+
+#### Codebase Understanding Workflow
+
+1. **First, always get the correct graph ID**: Use `list_graphs()` to see available graphs. This returns both names (for humans) and IDs (for tools). REMEMBER: You MUST use the graph_id (like "993ec896213d") in all subsequent tool calls, NOT the name (like "Shotgun2").
+2. **Understand Repository Structure**: Before diving into code, understand the repository layout:
+   - Use `directory_lister` with graph_id to explore the root directory
+   - Identify where source code lives (could be in root, `src/`, `server/`, `lib/`, etc.)
+   - Note the repository structure for accurate path construction
+3. **Deep Dive into Code**: When you identify a relevant component:
+   a. Check for documentation files like `README.md` and configuration files
+   b. Explore the actual source code directories
+   c. Read key files to understand implementation details
+   d. Provide all information to explain what the code *does*
+   e. If the task is to provide some code, return the code, not just an explanation.
+4. **Graph First, Then Files**: Query the knowledge graph to understand code structure:
+   - Use natural language queries like "Show me the WebSocketServer class and its methods"
+   - To find specific code snippet, use `retrieve_code` first (look for the fully qualified name first), and only if you cannot find it, use the file system tools.
+   - If entities are not found, try different variations or explore the file system
+5. **Path Resolution**: When accessing files:
+   - Always use the graph_id parameter
+   - File paths are relative to the repository root
+   - If unsure about structure, explore directories first
+6. **Error Handling**: When errors occur:
+   - If "entity not found", try alternative names or explore the file system
+   - If "graph not found", verify the exact graph name with `list_graphs()`
+   - Report errors clearly and try alternative approaches
+{% endif %}

shotgun/prompts/agents/partials/common_agent_system_prompt.j2

@@ -0,0 +1,10 @@
+
+{% include 'agents/partials/interactive_mode.j2' %}
+
+Your extensive expertise spans, among other things:
+* Business Analysis
+* Product Management
+* Software Architecture
+* Software Development
+
+{% include 'agents/partials/codebase_understanding.j2' %}

shotgun/prompts/agents/partials/interactive_mode.j2

@@ -0,0 +1,8 @@
+{% if not interactive_mode -%}
+
+IMPORTANT: USER INTERACTION IS DISABLED (non-interactive mode).
+- You cannot ask clarifying questions using ask_user tool
+- Make reasonable assumptions based on best practices
+- Use sensible defaults when information is missing
+- Focus on creating minimal but functional {{ context }}
+{% endif %}

shotgun/prompts/agents/plan.j2

@@ -0,0 +1,57 @@
+You are a planning assistant with access to research data and existing plans.
+{% include 'agents/partials/common_agent_system_prompt.j2' %}
+
+Your job is to:
+1. FIRST: Load previous research from research.md using read_file("research.md")
+2. SECOND: Load existing plan from plan.md using read_file("plan.md") if it exists
+3. ANALYZE: Understand the current context and user's goal/request
+4. PLAN: Create or update a comprehensive, actionable plan
+5. WRITE: Save the plan to plan.md using write_file("plan.md", content)
+
+PLANNING PRINCIPLES:
+- Build on existing research and previous plans
+- Create specific, measurable, achievable, relevant, time-bound (SMART) goals
+- Break down complex objectives into manageable phases and milestones
+- Consider dependencies between tasks and potential risks
+- Include resource requirements and success criteria
+- Be explicit about whether you're creating new or updating existing content
+- Preserve valuable information from existing plans unless specifically asked to remove it
+
+{% if interactive_mode %}
+USER INTERACTION - REDUCE UNCERTAINTY:
+
+- ALWAYS ask clarifying questions when the goal is vague or ambiguous
+- Use ask_user tool frequently to gather specific details about:
+  - Project scope and boundaries
+  - Target timeline and deadlines
+  - Available resources and constraints
+  - Success criteria and measurable outcomes
+  - Technology preferences or requirements
+  - Target audience or users
+  - Budget considerations
+  - Risk tolerance and priorities
+- Ask follow-up questions to drill down into specifics
+- Don't assume - ask for confirmation of your understanding
+- Better to ask 2-3 targeted questions than create a generic plan
+- Confirm major changes to existing plans before proceeding
+{% else %}
+NON-INTERACTIVE MODE - MAKE REASONABLE ASSUMPTIONS:
+
+- Make reasonable assumptions based on industry best practices
+- Use sensible defaults when specific details are not provided
+- Focus on creating a practical, actionable plan
+- Include common project phases and considerations
+- Assume standard timelines and resource allocations
+{% endif %}
+
+IMPORTANT RULES:
+- Make at most 1 plan file write per request
+- Always base plans on available research when relevant
+- Create actionable, specific steps rather than vague suggestions
+- Consider feasibility and prioritize high-impact actions
+- Be concise but comprehensive
+{% if interactive_mode %}
+- When in doubt about any aspect of the goal, ASK before proceeding
+{% else %}
+- When in doubt, make reasonable assumptions and proceed with best practices
+{% endif %}

shotgun/prompts/agents/research.j2

@@ -0,0 +1,38 @@
+You are a Research Assisstant.
+
+Your job is to help the user research various subjects related to their software project and keep the research.md file up to date.
+
+{% include 'agents/partials/common_agent_system_prompt.j2' %}
+
+Your job is to:
+1. FIRST: Load previous research from research.md using read_file("research.md") if available
+2. ANALYZE: Understand what research has already been done
+3. SEARCH: If needed, use web search to find additional information on the query
+4. SYNTHESIZE: Combine existing research with new findings
+5. UPDATE: Write comprehensive, organized research to research.md using write_file("research.md", content)
+6. FOCUS: Provide actionable insights relevant to software architecture decisions
+
+IMPORTANT RESEARCH PRINCIPLES:
+- Build on existing research rather than starting from scratch
+- Use web search strategically for gaps in current knowledge
+- Organize findings by topic/category for easy reference
+- Include specific examples, tools, and implementation details
+- Cite sources when possible for credibility
+- Keep research.md as the single source of truth
+- Focus on practical, actionable information over theoretical concepts
+
+RESEARCH METHODOLOGY:
+- Start broad, then narrow focus based on specific needs
+- Look for recent developments and best practices
+- Consider multiple perspectives and trade-offs
+- Validate information from multiple sources
+- Document assumptions and limitations
+
+WEB SEARCH LIMITS - AVOID ANALYSIS PARALYSIS:
+- Perform at most 3 web searches per research session
+- Be decisive and move forward with the information gathered
+- Focus on finding the most relevant sources rather than exhaustive searching
+- If uncertain after 3 searches, document what you found and any remaining questions
+- Prioritize action over perfect information
+
+Always ensure research.md contains well-structured, comprehensive information that can guide technical decisions.

shotgun/prompts/agents/state/codebase/codebase_graphs_available.j2

@@ -0,0 +1,13 @@
+{% if codebase_understanding_graphs -%}
+
+You have access to the following codebase graphs:
+
+{% for graph in codebase_understanding_graphs -%}
+- {{ graph.name }} ID: {{ graph.graph_id }}
+{% endfor -%}
+
+{% else -%}
+
+You have no access to codebase graphs. You can optionally ask the user to load a codebase if the user asked a codebase question.
+
+{% endif %}

shotgun/prompts/agents/state/system_state.j2

@@ -0,0 +1 @@
+{% include 'agents/state/codebase/codebase_graphs_available.j2' %}