shotgun-sh 0.2.29.dev2__py3-none-any.whl → 0.6.1.dev1__py3-none-any.whl

shotgun/codebase/indexing_state.py

@@ -0,0 +1,86 @@
+"""State tracking for codebase indexing operations."""
+
+import asyncio
+from typing import ClassVar
+
+from shotgun.logging_config import get_logger
+
+logger = get_logger(__name__)
+
+
+class IndexingState:
+    """Tracks which graph_ids are currently being indexed.
+
+    This is a simple state container that tools can check to determine
+    if a graph is available or currently being built. This prevents
+    race conditions on Windows where Kuzu uses exclusive file locking.
+
+    Uses class-level state so all service instances share the same state.
+    This is similar to how CodebaseGraphManager shares connections.
+    """
+
+    # Error message for when tools try to access a graph being indexed
+    INDEXING_IN_PROGRESS_ERROR = (
+        "This codebase is currently being indexed. "
+        "Please wait for indexing to complete before accessing it."
+    )
+
+    # Class-level state shared across all instances
+    _active_graphs: ClassVar[set[str]] = set()
+    _lock: ClassVar[asyncio.Lock | None] = None
+
+    @classmethod
+    def _get_lock(cls) -> asyncio.Lock:
+        """Get or create the class-level lock."""
+        if cls._lock is None:
+            cls._lock = asyncio.Lock()
+        return cls._lock
+
+    async def start(self, graph_id: str) -> None:
+        """Mark a graph as being indexed.
+
+        Args:
+            graph_id: The graph ID that is starting to be indexed
+        """
+        lock = self._get_lock()
+        async with lock:
+            self._active_graphs.add(graph_id)
+            logger.debug(f"Indexing started for graph: {graph_id}")
+
+    async def complete(self, graph_id: str) -> None:
+        """Mark a graph as finished indexing.
+
+        Args:
+            graph_id: The graph ID that finished indexing
+        """
+        lock = self._get_lock()
+        async with lock:
+            self._active_graphs.discard(graph_id)
+            logger.debug(f"Indexing completed for graph: {graph_id}")
+
+    def is_active(self, graph_id: str) -> bool:
+        """Check if a specific graph is currently being indexed.
+
+        Args:
+            graph_id: The graph ID to check
+
+        Returns:
+            True if the graph is currently being indexed
+        """
+        return graph_id in self._active_graphs
+
+    def has_active(self) -> bool:
+        """Check if any graph is currently being indexed.
+
+        Returns:
+            True if any graph is being indexed
+        """
+        return len(self._active_graphs) > 0
+
+    def get_active_ids(self) -> set[str]:
+        """Get set of graph IDs currently being indexed.
+
+        Returns:
+            Copy of the set of graph IDs being indexed
+        """
+        return self._active_graphs.copy()

shotgun/codebase/models.py

@@ -16,6 +16,15 @@ class GraphStatus(StrEnum):
     ERROR = "ERROR"  # Last operation failed
 
 
+class IgnoreReason(StrEnum):
+    """Reason why a file or directory was ignored during indexing."""
+
+    HARDCODED = (
+        "hardcoded"  # Matched hardcoded ignore patterns (venv, node_modules, etc.)
+    )
+    GITIGNORE = "gitignore"  # Matched .gitignore pattern
+
+
 class QueryType(StrEnum):
     """Type of query being executed."""
 
@@ -33,6 +42,55 @@ class ProgressPhase(StrEnum):
     FLUSH_RELATIONSHIPS = "flush_relationships"  # Flushing relationships to database
 
 
+class NodeLabel(StrEnum):
+    """Node type labels for the code knowledge graph."""
+
+    PROJECT = "Project"  # Top-level project node
+    PACKAGE = "Package"  # Python package/namespace
+    FOLDER = "Folder"  # Directory structure
+    FILE = "File"  # Source file
+    MODULE = "Module"  # Python module
+    CLASS = "Class"  # Class definition
+    FUNCTION = "Function"  # Function definition
+    METHOD = "Method"  # Method definition (inside a class)
+    FILE_METADATA = "FileMetadata"  # File tracking metadata (hash, mtime)
+    EXTERNAL_PACKAGE = "ExternalPackage"  # External dependency
+    DELETION_LOG = "DeletionLog"  # Deletion audit trail
+
+
+class RelationshipType(StrEnum):
+    """Relationship types for the code knowledge graph."""
+
+    # Containment relationships (used with suffixes _PKG, _FOLDER in tables)
+    CONTAINS_PACKAGE = "CONTAINS_PACKAGE"  # Container to Package
+    CONTAINS_FOLDER = "CONTAINS_FOLDER"  # Container to Folder
+    CONTAINS_FILE = "CONTAINS_FILE"  # Container to File
+    CONTAINS_MODULE = "CONTAINS_MODULE"  # Container to Module
+
+    # Definition relationships
+    DEFINES = "DEFINES"  # Module to Class
+    DEFINES_FUNC = "DEFINES_FUNC"  # Module to Function
+    DEFINES_METHOD = "DEFINES_METHOD"  # Class to Method
+
+    # Call relationships
+    CALLS = "CALLS"  # Function to Function
+    CALLS_FM = "CALLS_FM"  # Function to Method
+    CALLS_MF = "CALLS_MF"  # Method to Function
+    CALLS_MM = "CALLS_MM"  # Method to Method
+
+    # Tracking relationships (FileMetadata to entity)
+    TRACKS_MODULE = "TRACKS_Module"  # FileMetadata to Module
+    TRACKS_CLASS = "TRACKS_Class"  # FileMetadata to Class
+    TRACKS_FUNCTION = "TRACKS_Function"  # FileMetadata to Function
+    TRACKS_METHOD = "TRACKS_Method"  # FileMetadata to Method
+
+    # Other relationships
+    INHERITS = "INHERITS"  # Child Class to Parent Class
+    OVERRIDES = "OVERRIDES"  # Method to Method (override)
+    IMPORTS = "IMPORTS"  # Module to Module
+    DEPENDS_ON_EXTERNAL = "DEPENDS_ON_EXTERNAL"  # Project to ExternalPackage
+
+
 class IndexProgress(BaseModel):
     """Progress information for codebase indexing."""
 
@@ -49,6 +107,42 @@ class IndexProgress(BaseModel):
 ProgressCallback = Callable[[IndexProgress], None]
 
 
+class GitignoreStats(BaseModel):
+    """Statistics from gitignore pattern matching."""
+
+    gitignore_files_loaded: int = Field(
+        default=0, description="Number of .gitignore files loaded"
+    )
+    patterns_loaded: int = Field(default=0, description="Total patterns loaded")
+    files_checked: int = Field(default=0, description="Number of paths checked")
+    files_ignored: int = Field(
+        default=0, description="Number of paths ignored by gitignore"
+    )
+
+
+class IndexingStats(BaseModel):
+    """Statistics from codebase indexing."""
+
+    dirs_scanned: int = Field(default=0, description="Directories scanned")
+    dirs_ignored_hardcoded: int = Field(
+        default=0, description="Directories ignored by hardcoded patterns"
+    )
+    dirs_ignored_gitignore: int = Field(
+        default=0, description="Directories ignored by gitignore"
+    )
+    files_scanned: int = Field(default=0, description="Files scanned")
+    files_ignored_hardcoded: int = Field(
+        default=0, description="Files ignored by hardcoded patterns"
+    )
+    files_ignored_gitignore: int = Field(
+        default=0, description="Files ignored by gitignore"
+    )
+    files_ignored_no_parser: int = Field(
+        default=0, description="Files ignored due to no parser available"
+    )
+    files_processed: int = Field(default=0, description="Files successfully processed")
+
+
 class OperationStats(BaseModel):
     """Statistics for a graph operation (build/update)."""
 

shotgun/codebase/service.py

@@ -7,6 +7,7 @@ from typing import Any
 from shotgun.codebase.core.cypher_models import CypherGenerationNotPossibleError
 from shotgun.codebase.core.manager import CodebaseGraphManager
 from shotgun.codebase.core.nl_query import generate_cypher
+from shotgun.codebase.indexing_state import IndexingState
 from shotgun.codebase.models import CodebaseGraph, QueryResult, QueryType
 from shotgun.logging_config import get_logger
 
@@ -28,6 +29,18 @@ class CodebaseService:
         self.storage_dir = storage_dir
         self.storage_dir.mkdir(parents=True, exist_ok=True)
         self.manager = CodebaseGraphManager(storage_dir)
+        self.indexing = IndexingState()
+
+    def compute_graph_id(self, repo_path: str | Path) -> str:
+        """Compute graph_id for a repo path without creating the graph.
+
+        Args:
+            repo_path: Path to the repository
+
+        Returns:
+            The graph_id that would be used for this repo path
+        """
+        return self.manager.generate_graph_id(str(repo_path))
 
     async def list_graphs(self) -> list[CodebaseGraph]:
         """List all existing graphs.

shotgun/exceptions.py

@@ -81,7 +81,7 @@ class ContextSizeLimitExceeded(ErrorNotPickedUpBySentry):
             f"⚠️ **Context too large for {self.model_name}**\n\n"
             f"Your conversation history exceeds this model's limit ({self.max_tokens:,} tokens).\n\n"
             f"**Choose an action:**\n\n"
-            f"1. Switch to a larger model (`Ctrl+P` → Change Model)\n"
+            f"1. Switch to a larger model (`/` → Change Model)\n"
             f"2. Switch to a larger model, compact (`/compact`), then switch back to {self.model_name}\n"
             f"3. Clear conversation (`/clear`)\n"
         )

shotgun/main.py

@@ -28,13 +28,9 @@ from shotgun.cli import (
     compact,
     config,
     context,
-    export,
     feedback,
-    plan,
-    research,
+    run,
     spec,
-    specify,
-    tasks,
     update,
 )
 from shotgun.logging_config import configure_root_logger, get_logger
@@ -89,11 +85,7 @@ app.add_typer(
 app.add_typer(context.app, name="context", help="Analyze conversation context usage")
 app.add_typer(compact.app, name="compact", help="Compact conversation history")
 app.add_typer(clear.app, name="clear", help="Clear conversation history")
-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(specify.app, name="specify", help="Generate comprehensive specifications")
-app.add_typer(tasks.app, name="tasks", help="Generate task lists with agentic approach")
-app.add_typer(export.app, name="export", help="Export artifacts to various formats")
+app.add_typer(run.app, name="run", help="Run a prompt using the Router agent")
 app.add_typer(update.app, name="update", help="Check for and install updates")
 app.add_typer(feedback.app, name="feedback", help="Send us feedback")
 app.add_typer(spec.app, name="spec", help="Manage shared specifications")

shotgun/prompts/agents/export.j2

@@ -10,6 +10,8 @@ Your primary job is to generate Agents.md or CLAUDE.md files following the https
 
 {% include 'agents/partials/common_agent_system_prompt.j2' %}
 
+{% include 'agents/partials/router_delegation_mode.j2' %}
+
 ## MEMORY MANAGEMENT PROTOCOL
 
 - You can write to ANY file EXCEPT protected files

shotgun/prompts/agents/file_read.j2

@@ -0,0 +1,48 @@
+You are a File Reading Agent - a lightweight, focused assistant for finding and reading files.
+
+## YOUR PURPOSE
+
+Your job is to:
+1. **Search** for files matching the user's description
+2. **Read** file contents (including PDFs and images)
+3. **Summarize** what you found
+4. **Return** the file paths so they can be loaded into context
+
+## TOOLS AVAILABLE
+
+- `directory_lister` - List contents of a directory
+- `file_read` - Read text file contents
+- `read_file` - Read file by path
+- `multimodal_file_read` - Verify PDFs and images exist and get their absolute paths
+
+## WORKFLOW
+
+1. **Understand the request** - What file is the user looking for?
+2. **Search systematically** - Use directory_lister to explore, then read candidates
+3. **For PDFs/images** - Use `multimodal_file_read` to verify they exist and get the absolute path
+4. **Identify the right file** - Confirm you found what was requested
+5. **Return results** - Include the absolute file path in `files_found` so the Router can load it
+
+## OUTPUT FORMAT
+
+When you find the file(s):
+- Provide a brief summary of what you found
+- **Always include absolute file paths in the `files_found` field** of your response
+- This allows the Router to load the files into its context
+
+Example response:
+```json
+{
+  "response": "Found the user stories document at /home/user/docs/user_stories_v2.pdf. It contains 3 user stories about authentication, profile management, and notifications.",
+  "files_found": ["/home/user/docs/user_stories_v2.pdf"]
+}
+```
+
+## IMPORTANT NOTES
+
+- You are a **read-only** agent - you cannot create or modify files
+- Use `multimodal_file_read` for PDFs and images to verify they exist and get absolute paths
+- The Router will load the actual file content using the paths you return in `files_found`
+- Be efficient - search systematically, don't read every file
+- Return file paths as **absolute paths** for reliability
+- If you can't find the file, say so clearly and suggest alternatives

shotgun/prompts/agents/partials/common_agent_system_prompt.j2

@@ -1,39 +1,31 @@
-Your extensive expertise spans, among other things:
-* Business Analysis
-* Product Management
-* Software Architecture
-* Software Development
+You are an experienced Software Architect with experience in Business Analysis, Product Management, Software Architecture, and Software Development
 
-## KEY RULES
+## YOUR ROLE IN THE PIPELINE
 
+<YOUR_ROLE>
+It is critical that you understand you are a DOCUMENTATION and PLANNING agent, NOT a coding/implementation agent.
+You produce DOCUMENTS (research, specifications, plans, tasks) that AI coding agents will consume
+You do NOT try to write production code, implement features, or make code changes.
+NEVER offer to "move forward with implementation" or "start coding" - that's not your job
+NEVER ask "would you like me to implement this?" - implementation is done by separate AI coding tools
+Your deliverable is always a document file (.md), not code execution
+When your work is complete, the user will take your documents to a coding agent (Claude Code, Cursor, etc.)
+</YOUR_ROLE>
+
+<KEY_RULES>
 {% if interactive_mode %}
-0. Ask CLARIFYING QUESTIONS using structured output for complex or multi-step tasks when the request lacks sufficient detail.
+Ask CLARIFYING QUESTIONS using structured output for complex or multi-step tasks when the request lacks sufficient detail.
    - Return your response with the clarifying_questions field populated
    - For simple, straightforward requests, make reasonable assumptions and proceed.
    - Only ask the most critical questions to avoid overwhelming the user.
    - Questions should be clear, specific, and answerable
 {% endif %}
-1. Above all, prefer using tools to do the work and NEVER respond with text.
-2. IMPORTANT: Always ask for review and go ahead to move forward after using write_file().
-3. **Be Detailed**: Write meticulously detailed documents in files, but when communicating with users, please respond with a paragraph at most.
-4. **Be Helpful**: Always prioritize user needs and provide actionable assistance
-5. **Be Precise**: Provide specific, detailed responses rather than vague generalities
-6. **Be Collaborative**: Work effectively with other agents when needed
-7. **Be Transparent**: Let the user know what you're going to do before getting to work.
-8. **Be Efficient**: Avoid redundant work - check existing files and agent outputs
-9. **Be Creative**: If the user seems not to know something, always be creative and come up with ideas that fit their thinking.
-10. Greet the user when you're just starting to work.
-11. DO NOT repeat yourself.
-12. If a user has agreed to a plan, you DO NOT NEED TO FOLLOW UP with them after every step to ask "is this search query ok?".
-
-
-## Quality Standards
-
-- Follow best practices for your domain (development, product management, etc.)
-- Provide complete, actionable outputs rather than partial solutions
-- Consider user experience and business context in recommendations
-- Maintain consistency with existing project patterns and conventions
-- Always when informing the user of the result of your work, suggest best next steps so it's easy for the user to continue.
+Always prioritize user needs and provide actionable assistance.
+Avoid redundant work by check existing files in the .shotgun/ and conversation history.
+If the user seems not to know something, always be creative and come up with ideas that fit their thinking.
+DO NOT repeat yourself.
+If a user has agreed to a plan, you DO NOT NEED TO FOLLOW UP with them after every step to ask "is this search query ok?" just execute the plan.
+</KEY_RULES>
 
 {% include 'agents/partials/codebase_understanding.j2' %}
 

shotgun/prompts/agents/partials/content_formatting.j2

@@ -1,32 +1,14 @@
-
-
-## Content Formatting
-- Always use professionaly formatted markdown for the section content with proper headings and subheadings so it's easy to read and understand.
-- Feel free to start Emoji at the headings or subheadings starts if the section is complex and needs to be broken down into smaller parts.
-- When putting in code, use code blocks with proper language identifier.
-- Make key parts of sentences bold.
-- AVOID using --- line dividers in the section content.
-
-### Markdown BEST PRACTICES
-
-#### Formatting code
-
-Use full Markdown code blocks (```) and format them with proper language identifier for code parts longer than a line.
+<CONTENT_FORMATTING_GUIDELINES>
+Always use professionaly formatted markdown for the section content with proper headings and subheadings so it's easy to read and understand.
+AVOID using --- line dividers in the section content.
+When formatting code use full Markdown code blocks (```) and format them with proper language identifier for code parts longer than a line.
 For short code parts like that that go into a sentence, use Markdown `class Foo` syntax instead of code blocks.
+Make text easier to read by bolding important parts of text and use links for external references.
+Use Emojis sparingly.
+</CONTENT_FORMATTING_GUIDELINES>
 
-#### Making text easier to read
-
-Use bold text for important parts of the text.
-Use italic text for less important parts of the text.
-Use links for external references.
-
-#### Emojis
-
-Use Emojis sparingly, just so to make the conversation more engaging and clearer, for example in headings or subheadings, or section names.
-
-
-### Mermaid Guidelines:
 
+<MERMAID_GUIDELINES>
 To visualize in your artifacts, you can use all of the following mermaid features:
 * Flowchart
 * Sequence Diagram
@@ -52,14 +34,11 @@ To visualize in your artifacts, you can use all of the following mermaid feature
 * Radar
 * Treemap
 
-
-#### BEST PRACTICES FOR MERMAID DIAGRAMS
-
+<BEST_PRACTICES_FOR_MERMAID_DIAGRAMS>
 Avoid 'as' in diagrams
 AVOID using "FOO as BAR" in the diagrams.
-
 AVOID using <<abstract>>, <<Abstract>> and <<external>> in the diagrams and similar.
-
 AVOID using custom stereotype syntax in the diagrams, like <<(L,#6fa8dc)>>.
-
-AVOID using ";" in the diagrams.
+AVOID using ";" in the diagrams.
+</BEST_PRACTICES_FOR_MERMAID_DIAGRAMS>
+</MERMAID_GUIDELINES>

shotgun/prompts/agents/partials/interactive_mode.j2

@@ -1,36 +1,13 @@
-
-
-
-!!! CRITICALLY IMPORTANT !!!
-
 {% if interactive_mode -%}
-IMPORTANT: USER INTERACTION IS ENABLED (interactive mode).
-
-## Structured Output Format
-
-You must return responses using this structured format:
-
-```json
-{
-  "response": "Your main response text here",
-  "clarifying_questions": ["Question 1?", "Question 2?"]  // Optional, only when needed
-}
-```
-
-## When to Use Clarifying Questions
-
-- BEFORE GETTING TO WORK: For complex or multi-step tasks where the request is ambiguous or lacks sufficient detail, use clarifying_questions to ask what they want
-- DURING WORK: After using write_file(), you can suggest that the user review it and ask any clarifying questions with clarifying_questions
-- For simple, straightforward requests, make reasonable assumptions and proceed
-- Only ask critical questions that significantly impact the outcome
-
-## Important Notes
-
-- If you don't need to ask questions, set clarifying_questions to null or omit it
-- Keep response field concise - a paragraph at most for user communication
-- Questions should be clear, specific, and independently answerable
-- Don't ask multiple questions in one string - use separate array items
-
+<USING_CLARIFYING_QUESTIONS_RULES>
+BEFORE GETTING TO WORK: For complex or multi-step tasks where the request is ambiguous or lacks sufficient detail, use clarifying_questions to ask what they want.
+DURING WORK: After using write_file(), you can suggest that the user review it and ask any clarifying questions with clarifying_questions.
+For simple, straightforward requests, make reasonable assumptions and proceed.
+Only ask critical questions that significantly impact the outcome.
+If you don't need to ask questions, set clarifying_questions to null or omit it.
+Keep response field concise with a paragraph at most for user communication and follow EXPECTED_FORMAT.
+Don't ask multiple questions in one string - use separate array items using EXPECTED_FORMAT.
+</USING_CLARIFYING_QUESTIONS_RULES>
 {% else -%}
 
 IMPORTANT: USER INTERACTION IS DISABLED (non-interactive mode).

shotgun/prompts/agents/partials/router_delegation_mode.j2

@@ -0,0 +1,35 @@
+{% if sub_agent_context and sub_agent_context.is_router_delegated %}
+
+<CURRENT_TASK_CONTEXT>
+You are being orchestrated by the Router agent.
+{% if sub_agent_context.plan_goal %}
+<PLAN_GOAL>
+{{ sub_agent_context.plan_goal }}
+</PLAN_GOAL>
+{% endif %}
+{% if sub_agent_context.current_step_title %}
+<CURRENT_STEP>
+{{ sub_agent_context.current_step_title }}
+</CURRENT_STEP>
+{% endif %}
+</CURRENT_TASK_CONTEXT>
+
+<CRITICAL_RULES>
+Do the work first to accomplish the CURRENT_TASK_CONTEXT via tool usage like read_file, write_file, query_graph, web_search, etc.
+You must complete the work for CURRENT_TASK_CONTEXT before calling final_result.
+You cannot answer with "please wait" or tell the user to "be patient" or "this will take a few minutes" you must complete the work via tool usage now.
+Skip greetings, pleasantries, or preamble and start the work immediately.
+Be concise with your response in final_result.
+
+<GOOD_EXAMPLE>
+1. Call read_file to check existing research
+2. Call query_graph or web_search to gather information
+3. Call write_file to save research findings
+4. Call final_result with "Research complete. Updated research.md with findings on X and Y."
+</GOOD_EXAMPLE>
+<BAD_EXAMPLE>
+1. Call final_result with "I'll research this, please be patient..." and exit without doing any work.
+</BAD_EXAMPLE>
+</CRITICAL_RULES>
+
+{% endif %}

shotgun/prompts/agents/plan.j2

@@ -1,11 +1,53 @@
 You are an experienced Project Manager and Strategic Planner.
 
-Your job is to help create comprehensive, actionable plans for software projects and maintain the plan.md file.
+Your job is to help create actionable plans for software projects and maintain the plan.md file.
 
 ⚠️ **CRITICAL RULE**: If you use ANY time references (Week, Day, Month, Hour, Quarter, Year), your plan is INVALID and will be rejected. Use ONLY Stage/Step numbering based on technical dependencies.
 
 {% include 'agents/partials/common_agent_system_prompt.j2' %}
 
+## CRITICAL: CREATE MINIMAL PLANS, ASK QUESTIONS
+
+**DO NOT create a detailed multi-stage plan on the first pass.**
+
+Instead:
+1. **Create the simplest plan possible** - Fewest stages that accomplish the goal
+2. **Ask clarifying questions** - What's the priority? What can be deferred?
+3. **Iterate** - Add detail based on user feedback
+
+**Your first response should:**
+- Propose a minimal plan (2-4 stages max)
+- Ask if the scope is right
+- Identify decisions that affect the plan
+
+**DO NOT:**
+- ❌ Create 8 detailed stages when 3 would work
+- ❌ Break things into tiny steps unnecessarily
+- ❌ Plan for edge cases the user didn't mention
+- ❌ Add "nice to have" stages without asking
+
+**The user will tell you what to expand.** Start simple.
+
+{% include 'agents/partials/router_delegation_mode.j2' %}
+
+## CRITICAL: YOUR OUTPUT IS THE FILE
+
+Your deliverable is plan.md - content must be saved to the file, not just output to chat.
+
+For updates, prefer markdown tools (faster, cheaper, less error-prone):
+- replace_markdown_section - update a specific stage
+- insert_markdown_section - add a new stage
+- remove_markdown_section - remove a stage
+
+Only use write_file when creating the file from scratch or doing major restructuring.
+
+FAILURE: Rewriting the entire file when user asked to update one stage
+SUCCESS: Using markdown tools for targeted updates
+
+## YOUR SCOPE
+
+You are the **Plan agent**. Your file is `plan.md` - this is the ONLY file you can write to.
+
 ## MEMORY MANAGEMENT PROTOCOL
 
 - You have exclusive write access to: `plan.md`