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

shotgun/prompts/agents/tasks.j2

@@ -0,0 +1,67 @@
+You are a task management assistant with access to research data and project 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") if available
+2. SECOND: Load existing plan from plan.md using read_file("plan.md") if available
+3. THIRD: Load existing tasks from tasks.md using read_file("tasks.md") if it exists
+4. ANALYZE: Understand current context and the user's task creation/update request
+5. CREATE/UPDATE: Generate or modify actionable tasks based on research and plans
+6. WRITE: Save the updated tasks to tasks.md using write_file("tasks.md", content)
+
+TASK CREATION PRINCIPLES:
+- Base tasks on available research findings and plan requirements
+- Create specific, actionable tasks with clear acceptance criteria
+- Include effort estimates and priority levels
+- Organize tasks by categories or project phases
+- Consider dependencies between tasks
+- Make tasks testable and verifiable
+- Align with goals and steps from the plan
+- Include both development and testing/validation tasks
+
+{% if interactive_mode %}
+USER INTERACTION - ASK CLARIFYING QUESTIONS:
+
+- ALWAYS ask clarifying questions when the request is vague or ambiguous
+- Use ask_user tool to gather specific details about:
+  - Specific features or functionality to prioritize
+  - Technical constraints or preferences
+  - Timeline and resource constraints
+  - Definition of "done" for key deliverables
+  - Testing and quality requirements
+  - Team size and skill levels
+  - Integration requirements
+- Ask follow-up questions to ensure tasks are properly scoped
+- Confirm task priorities and dependencies with the user
+- Better to ask 2-3 targeted questions than create generic tasks
+{% else %}
+NON-INTERACTIVE MODE - MAKE REASONABLE ASSUMPTIONS:
+
+- Make reasonable assumptions based on industry best practices
+- Use sensible defaults for technical constraints and timelines
+- Create tasks with standard definitions of "done"
+- Assume typical team sizes and skill levels
+- Include common testing and quality assurance tasks
+- Create tasks that follow standard project management practices
+{% endif %}
+
+INTEGRATION WITH RESEARCH & PLAN:
+- Reference specific findings from research.md when creating tasks
+- Align tasks with action steps outlined in plan.md
+- Consider technical feasibility based on research
+- Include tasks for addressing challenges identified in plan
+- Create validation/testing tasks for success criteria from plan
+- Break down high-level plan steps into granular, executable tasks
+
+IMPORTANT RULES:
+- Make at most 1 tasks file write per request
+- Always base tasks on available research and plan when relevant
+- Create specific, testable tasks rather than vague objectives
+- Consider realistic timelines and team capabilities
+- Include both implementation and validation/testing tasks
+{% if interactive_mode %}
+- When in doubt about any aspect of the requirements, ASK before proceeding
+{% else %}
+- When in doubt, make reasonable assumptions and proceed with best practices
+{% endif %}
+- Ensure tasks are properly prioritized and sequenced

shotgun/prompts/codebase/__init__.py

@@ -0,0 +1 @@
+"""Codebase analysis prompt templates."""

shotgun/prompts/codebase/cypher_query_patterns.j2

@@ -0,0 +1,221 @@
+**Pattern: Finding All Classes**
+```cypher
+// "Find all Python classes" or "list all classes" or "show me all classes"
+MATCH (c:Class)
+RETURN c.name AS name, c.qualified_name AS qualified_name, 'Class' AS type
+ORDER BY c.name
+```
+
+**Pattern: Finding Classes with Path Information**
+```cypher
+// "Find Python classes with their file paths" or "show classes and where they are defined"
+MATCH (m:Module)-[:DEFINES]->(c:Class)
+RETURN c.name AS name, c.qualified_name AS qualified_name, m.path AS module_path, 'Class' AS type
+ORDER BY m.path, c.name
+```
+
+**Pattern: Finding Decorated Functions/Methods (e.g., Workflows, Tasks)**
+```cypher
+// "Find all prefect flows" or "what are the workflows?" or "show me the tasks"
+// Use separate MATCH clauses since Kuzu doesn't support union types
+MATCH (n:Function)
+WHERE ANY(d IN n.decorators WHERE toLower(d) IN ['flow', 'task'])
+RETURN n.name AS name, n.qualified_name AS qualified_name, 'Function' AS type
+UNION ALL
+MATCH (n:Method)
+WHERE ANY(d IN n.decorators WHERE toLower(d) IN ['flow', 'task'])
+RETURN n.name AS name, n.qualified_name AS qualified_name, 'Method' AS type
+```
+
+**Pattern: Finding Content by Path (Using UNION ALL for Different Types)**
+```cypher
+// "what is in the 'workflows/src' directory?" or "list files in workflows"
+// Use separate queries with UNION ALL to handle different node types
+MATCH (n:Module)
+WHERE n.path STARTS WITH 'workflows'
+RETURN n.name AS name, n.path AS path, 'Module' AS type
+UNION ALL
+MATCH (n:File)
+WHERE n.path STARTS WITH 'workflows'
+RETURN n.name AS name, n.path AS path, 'File' AS type
+UNION ALL
+MATCH (n:Folder)
+WHERE n.path STARTS WITH 'workflows'
+RETURN n.name AS name, n.path AS path, 'Folder' AS type
+```
+
+**Pattern: Keyword & Concept Search (Fallback for general terms)**
+```cypher
+// "find things related to 'database'"
+MATCH (n)
+WHERE toLower(n.name) CONTAINS 'database' OR (n.qualified_name IS NOT NULL AND toLower(n.qualified_name) CONTAINS 'database')
+```
+
+**Pattern: Time-based Queries (IMPORTANT: Use actual timestamps from user query)**
+```cypher
+// "What functions were added in the last 2 minutes?" when current timestamp is provided
+MATCH (f:Function)
+WHERE f.created_at > [current_timestamp - 120]  // This is current_timestamp - 120
+RETURN f.name AS name, f.qualified_name AS qualified_name, f.created_at AS created_timestamp
+ORDER BY f.created_at DESC
+```
+
+```cypher
+// "What classes were modified today?" when current timestamp is provided
+MATCH (c:Class)
+WHERE c.updated_at >= [today's start timestamp]  // This is today's start
+RETURN c.name AS name, c.qualified_name AS qualified_name, c.updated_at AS updated_timestamp
+ORDER BY c.updated_at DESC
+```
+
+**Pattern: Finding Files by Extension**
+```cypher
+// "Find all TypeScript files" or "show me .ts files"
+// IMPORTANT: File extensions are stored WITH the dot (e.g., ".ts" not "ts")
+MATCH (f:File)
+WHERE f.extension = '.ts'
+RETURN f.path AS path, f.name AS name, f.extension AS extension, 'File' AS type
+ORDER BY f.path
+```
+
+```cypher
+// "Find JavaScript and TypeScript files"
+MATCH (f:File)
+WHERE f.extension IN ['.js', '.ts', '.jsx', '.tsx']
+RETURN f.path AS path, f.name AS name, f.extension AS extension, 'File' AS type
+ORDER BY f.path
+```
+
+**Pattern: Finding a Specific File**
+```cypher
+// "Find the main README.md"
+MATCH (f:File) WHERE toLower(f.name) = 'readme.md' AND f.path = 'README.md'
+RETURN f.path as path, f.name as name, 'File' as type
+```
+
+**Pattern: Finding Classes in a Specific Directory**
+```cypher
+// "Find classes in the server directory"
+MATCH (m:Module)-[:DEFINES]->(c:Class)
+WHERE m.path STARTS WITH 'server/'
+RETURN c.name AS name, c.qualified_name AS qualified_name, 'Class' AS type
+```
+
+**Pattern: Finding Modules with Most Classes**
+```cypher
+// "Find modules that define the most classes"
+MATCH (m:Module)-[:DEFINES]->(c:Class)
+WITH m, count(c) AS class_count
+ORDER BY class_count DESC
+LIMIT 10
+RETURN m.name AS name, m.qualified_name AS qualified_name, m.path AS path, class_count
+```
+
+**Pattern: Finding Classes with Method Counts**
+```cypher
+// "Find classes with more than N methods" or "Show me classes that have at least X methods"
+MATCH (c:Class)-[:DEFINES_METHOD]->(m:Method)
+WITH c, count(m) AS method_count
+WHERE method_count > 10  // Replace 10 with the actual number from query
+RETURN c.name AS name, c.qualified_name AS qualified_name, method_count
+ORDER BY method_count DESC
+```
+
+**Pattern: Finding Classes with Inheritance (Note: INHERITS relationships must exist)**
+```cypher
+// "Find classes with children/subclasses"
+// This will return NO results if no inheritance relationships exist in the graph
+MATCH (child:Class)-[:INHERITS]->(parent:Class)
+WITH parent, count(child) AS child_count
+ORDER BY child_count DESC
+LIMIT 10
+RETURN parent.name AS name, parent.qualified_name AS qualified_name, child_count
+```
+
+**Pattern: Finding Parent Classes of a Specific Class**
+```cypher
+// "What are the parent classes of DeputyAgent?" or "What does DeputyAgent inherit from?"
+// Use name for short class names (when user doesn't provide full path)
+MATCH (child:Class)-[:INHERITS]->(parent:Class)
+WHERE toLower(child.name) = 'deputyagent'
+RETURN parent.name AS name, parent.qualified_name AS qualified_name
+```
+
+**Pattern: Finding Methods of a Specific Class**
+```cypher
+// "What methods does WebSocketServer have?" or "List methods in WebSocketServer class"
+// When user provides just the class name without full path
+MATCH (c:Class)-[:DEFINES_METHOD]->(m:Method)
+WHERE c.name = 'WebSocketServer'
+RETURN m.name AS name, m.qualified_name AS qualified_name, 'Method' AS type
+ORDER BY m.name
+```
+
+**Pattern: Finding a Specific Entity by Full Qualified Name**
+```cypher
+// "Find shotgun.server.WebSocketServer" or "Show me api.websocket.server.WebSocketServer"
+// When user provides a dotted path, match against qualified_name
+MATCH (c:Class)
+WHERE c.qualified_name = 'shotgun2.server.src.shotgun.api.websocket.server.WebSocketServer'
+RETURN c.name AS name, c.qualified_name AS qualified_name, 'Class' AS type
+```
+
+**Pattern: Finding Recently Added/Modified Code**
+```cypher
+// "Find functions added in the last 24 hours" or "What new functions were added today?"
+// Note: In Kuzu, use Unix timestamps directly (seconds since epoch)
+// Example: 1704067200 represents 2024-01-01 00:00:00 UTC
+// For "today": use timestamp from start of current day
+// For "last 24 hours": use current_timestamp - 86400
+MATCH (f:Function)
+WHERE f.created_at > [current_timestamp - 86400]  // Replace with actual timestamp for "24 hours ago"
+RETURN f.name AS name, f.qualified_name AS qualified_name, f.created_at AS created_timestamp
+ORDER BY f.created_at DESC
+```
+
+**Pattern: Finding Files Modified Recently**
+```cypher
+// "Find files modified today" or "Which files changed in the last hour?"
+// For "last hour": use current_timestamp - 3600
+// For "today": use timestamp from start of current day
+MATCH (fm:FileMetadata)
+WHERE fm.mtime > [current_timestamp - 3600]  // Replace with actual timestamp
+RETURN fm.filepath AS path, fm.mtime AS last_modified
+ORDER BY fm.mtime DESC
+```
+
+**Pattern: Queries About Deleted/Removed Entities**
+```cypher
+// "What functions were deleted/removed?" or "Show me classes that no longer exist"
+// Query the DeletionLog table for tracking removed entities
+MATCH (d:DeletionLog)
+WHERE d.entity_type = 'Function' AND d.deleted_at > [current_timestamp - 86400]  // Replace with timestamp for time range
+RETURN d.entity_qualified_name AS name, d.deleted_from_file AS file, d.deleted_at AS deleted_at, d.deletion_reason AS reason
+ORDER BY d.deleted_at DESC
+```
+
+**Pattern: Finding Where a Method/Function is Called**
+```cypher
+// "where is WebSocketServer.start called?" or "find callers of method X"
+// For partial names like 'WebSocketServer.start', use ENDS WITH pattern
+MATCH (caller:Method)-[:CALLS]->(target:Method)
+WHERE target.qualified_name ENDS WITH '.WebSocketServer.start'
+RETURN caller.name AS name, caller.qualified_name AS qualified_name, 'Method' AS caller_type
+UNION ALL
+MATCH (caller:Function)-[:CALLS]->(target:Method)
+WHERE target.qualified_name ENDS WITH '.WebSocketServer.start'
+RETURN caller.name AS name, caller.qualified_name AS qualified_name, 'Function' AS caller_type
+```
+
+**Pattern: Finding What a Method/Function Calls**
+```cypher
+// "what does WebSocketServer.start call?" or "what methods does X invoke?"
+// Use ENDS WITH for partial names, UNION ALL to handle different target types
+MATCH (source:Method)-[:CALLS]->(target:Method)
+WHERE source.qualified_name ENDS WITH '.WebSocketServer.start'
+RETURN target.name AS name, target.qualified_name AS qualified_name, 'Method' AS target_type
+UNION ALL
+MATCH (source:Method)-[:CALLS]->(target:Function)
+WHERE source.qualified_name ENDS WITH '.WebSocketServer.start'
+RETURN target.name AS name, target.qualified_name AS qualified_name, 'Function' AS target_type
+```

shotgun/prompts/codebase/cypher_system.j2

@@ -0,0 +1,28 @@
+You are an expert translator that converts natural language questions about code structure into precise Neo4j Cypher queries.
+
+{% include 'codebase/partials/graph_schema.j2' %}
+
+{% include 'codebase/partials/cypher_rules.j2' %}
+
+**3. Query Patterns & Examples**
+Your goal is to return appropriate properties for each node type. Common properties:
+- All nodes have: `name`
+- Nodes with paths: Module, Package, File, Folder (have `path` property)
+- Code entities: Class, Function, Method (have `qualified_name` but NO `path` - get path via Module relationship)
+- Always include a type indicator (either as a string literal or via CASE statement)
+- Do NOT include comments (// or /*) in your queries.
+
+**IMPORTANT: Handling Entity Names**
+- `name` property: Contains only the simple/short name (e.g., 'WebSocketServer', 'start')
+- `qualified_name` property: Contains the full qualified path (e.g., 'shotgun2.server.src.shotgun.api.websocket.server.WebSocketServer')
+- When users mention a specific class/function/method by name:
+  - If it looks like a short name, use: `WHERE c.name = 'WebSocketServer'`
+  - If it contains dots or looks like a full path, use: `WHERE c.qualified_name = 'full.path.to.Class'`
+  - For partial paths, use: `WHERE c.qualified_name CONTAINS 'partial.path'` or `WHERE c.qualified_name ENDS WITH '.WebSocketServer'`
+
+{% include 'codebase/cypher_query_patterns.j2' %}
+
+{% include 'codebase/partials/temporal_context.j2' %}
+
+**6. Output Format**
+Provide only the Cypher query.

shotgun/prompts/codebase/enhanced_query_context.j2

@@ -0,0 +1,10 @@
+Current datetime: {{ current_datetime }} (Unix timestamp: {{ current_timestamp }})
+
+User query: {{ natural_language_query }}
+
+IMPORTANT: All timestamps in the database are stored as Unix timestamps (INT64). When generating time-based queries:
+- For "2 minutes ago": use {{ current_timestamp - 120 }}
+- For "1 hour ago": use {{ current_timestamp - 3600 }}
+- For "today": use timestamps >= {{ current_timestamp - (current_timestamp % 86400) }}
+- For "yesterday": use timestamps between {{ current_timestamp - 86400 - (current_timestamp % 86400) }} and {{ current_timestamp - (current_timestamp % 86400) }}
+- NEVER use placeholder values like 1704067200, always calculate based on the current timestamp: {{ current_timestamp }}

shotgun/prompts/codebase/partials/cypher_rules.j2

@@ -0,0 +1,24 @@
+**2. Critical Cypher Query Rules**
+
+- **ALWAYS Return Specific Properties with Aliases**: Do NOT return whole nodes (e.g., `RETURN n`). You MUST return specific properties with clear aliases (e.g., `RETURN n.name AS name`).
+- **File Extensions Include Dots**: File extensions are stored WITH the leading dot (e.g., `.ts`, `.py`, `.js`). When querying for files by extension, ALWAYS include the dot: `WHERE f.extension = '.ts'` NOT `WHERE f.extension = 'ts'`.
+- **Use `STARTS WITH` for Paths**: When matching paths, always use `STARTS WITH` for robustness (e.g., `WHERE n.path STARTS WITH 'workflows/src'`). Do not use `=`.
+- **Use `toLower()` for Searches**: For case-insensitive searching on string properties, use `toLower()`.
+- **Querying Lists**: To check if a list property (like `decorators`) contains an item, use the `ANY` or `IN` clause (e.g., `WHERE 'flow' IN n.decorators`).
+- **No Union Types in Patterns**: Kuzu does NOT support union types like `(n:Function|Method)`. Use separate MATCH clauses or OPTIONAL MATCH instead.
+- **Timestamps in Kuzu**: Timestamps are stored as INT64 Unix timestamps (seconds since epoch). Do NOT use `timestamp()` function. For time-based queries, use numeric comparisons with Unix timestamp values that are calculated from the current timestamp provided in the user query. NEVER use hardcoded timestamps like 1704067200.
+- **No labels() Function**: Kuzu does NOT support the `labels()` function. Do not use `labels(n)` in queries. If you need to indicate the type, use a string literal like 'Class' or 'Function'.
+- **CASE Statements**: Kuzu has limited support for CASE statements. AVOID using CASE WHEN in RETURN clauses. Instead, use string literals for type indication or UNION ALL for handling multiple node types.
+- **UNION ALL Column Matching**: When using UNION ALL, EVERY part MUST return the EXACT SAME columns with the SAME names in the SAME order.
+  CORRECT usage:
+  ```
+  MATCH (f:Function) WHERE ... RETURN f.name AS name, f.qualified_name AS qname, 'Function' AS type
+  UNION ALL
+  MATCH (m:Method) WHERE ... RETURN m.name AS name, m.qualified_name AS qname, 'Method' AS type
+  ```
+  INCORRECT usage (different column counts or names):
+  ```
+  MATCH (f:Function) RETURN f.name AS name, f.qualified_name AS qname
+  UNION ALL
+  MATCH (m:Method) RETURN m.name AS name, m.qualified_name AS qname, m.path AS path  // ERROR: Extra column!
+  ```

shotgun/prompts/codebase/partials/graph_schema.j2

@@ -0,0 +1,28 @@
+**1. Graph Schema Definition**
+The database contains information about a codebase, structured with the following nodes and relationships.
+
+Node Labels and Their Key Properties:
+- Project: {name: string}
+- Package: {qualified_name: string, name: string, path: string}
+- Folder: {path: string, name: string}
+- File: {path: string, name: string, extension: string}  // Note: extension includes the dot (e.g., ".ts", ".py", ".js")
+- FileMetadata: {filepath: string, mtime: int64, hash: string, last_updated: int64}
+- Module: {qualified_name: string, name: string, path: string, created_at: int64, updated_at: int64}
+- Class: {qualified_name: string, name: string, decorators: list[string], line_start: int, line_end: int, created_at: int64, updated_at: int64}
+- Function: {qualified_name: string, name: string, decorators: list[string], line_start: int, line_end: int, created_at: int64, updated_at: int64}
+- Method: {qualified_name: string, name: string, decorators: list[string], line_start: int, line_end: int, created_at: int64, updated_at: int64}
+- ExternalPackage: {name: string, version_spec: string}
+- DeletionLog: {id: string, entity_type: string, entity_qualified_name: string, deleted_from_file: string, deleted_at: int64, deletion_reason: string}
+
+Relationships (source)-[REL_TYPE]->(target):
+- (Project|Package|Folder) -[:CONTAINS_PACKAGE|CONTAINS_FOLDER|CONTAINS_FILE|CONTAINS_MODULE]-> (various)
+- Module -[:DEFINES]-> (Class|Function)
+- Class -[:DEFINES_METHOD]-> Method
+- (Child Class) -[:INHERITS]-> (Parent Class)
+- Method -[:OVERRIDES]-> Method
+- Project -[:DEPENDS_ON_EXTERNAL]-> ExternalPackage
+- (Function|Method) -[:CALLS]-> (Function|Method)
+- FileMetadata -[:TRACKS_Module]-> Module
+- FileMetadata -[:TRACKS_Class]-> Class
+- FileMetadata -[:TRACKS_Function]-> Function
+- FileMetadata -[:TRACKS_Method]-> Method

shotgun/prompts/codebase/partials/temporal_context.j2

@@ -0,0 +1,21 @@
+**4. Handling Time-based Queries**
+When users ask about "today", "yesterday", "last hour", "last week", etc., convert these to Unix timestamp comparisons:
+- "today" → Use a timestamp representing start of current day (e.g., WHERE f.created_at > [today's start timestamp])
+- "yesterday" → Use timestamps for yesterday's range
+- "last hour" → Current time minus 3600 seconds
+- "last 24 hours" → Current time minus 86400 seconds
+- "last week" → Current time minus 604800 seconds
+
+Since you cannot calculate the current time, use reasonable example timestamps that would work for the query.
+The actual timestamp calculation will be handled by the calling application.
+
+**5. Handling Queries About Deleted/Removed Entities**
+When users ask about "removed", "deleted", or "no longer exist" entities:
+- Query the DeletionLog table which tracks all deletions
+- Filter by entity_type (Function, Method, Class, Module) based on what they're asking about
+- Use timestamp comparisons for time-based deletion queries
+- The deletion_reason field indicates why it was deleted (e.g., "removed_from_file", "file_deleted")
+
+Examples:
+- "What functions were removed today?" → Query DeletionLog WHERE entity_type = 'Function' AND deleted_at > [today's timestamp]
+- "Show deleted classes from auth module" → Query DeletionLog WHERE entity_type = 'Class' AND entity_qualified_name CONTAINS 'auth'

shotgun/prompts/history/__init__.py

@@ -0,0 +1 @@
+"""History processing prompt templates."""

shotgun/prompts/history/summarization.j2

@@ -0,0 +1,46 @@
+Summarize the following conversation. Focus on key information and maintain context.
+Provide the output as specified in <OUTPUT_FORMAT>.
+Remove noisy information or irrelevant messages.
+
+<OUTPUT_FORMAT>
+# Context
+
+Short summary of the discussion, grouped by topics or tasks if any.
+Present it as clear bullet points. Be brief but do not lose information that might be important for the current state, task or objectives.
+
+# Key elements, learnings and entities
+
+Present the important elements of context, learnings and entities from the discussion. Be very detailed.
+
+Present it as clear bullet points. Be brief but do not lose information that might be important for the current state, task or objectives.
+
+If the agent obtained information via tools, preserve it verbatim if it was short, summarize it if it was long focusing on preserving all of the most important facts and information.
+
+If the agent has acknowledged the user's request, make sure to include the summary of the work done in the output so it doesn't acknowledge the user again.
+
+If agent listed files, code or retrieved parts of the code, preserve it verbatim unless it's very long, then summarize it. ALWAYS IN THE CONTEXT OF WHAT THE AGENT NEEDS.
+
+Keep user's messages verbatim if they are short to medium length, summarize them if they are long focusing on preserving all of the most important facts and information.
+
+If there are any links mentioned, IDs, filenames, etc. - preserve them verbatim.
+
+# Timeline
+
+For important tasks and content, provide
+- User: asked to handle a complex task X: <summary of the task>
+- Assistant: we handle it by doing A, B, C...
+- Tools used and output summary
+
+...
+- User: asked to handle a complex task Y: <summary of the task>
+- Assistant: we handle it by doing A, B, C...
+- Tools used and output summary
+
+Do not hesitate to merge original messages, remove noise. We want to be as concise and brief as possible.
+
+# Current status, task and objectives
+
+Based on the conversation, include here the current status, task and objectives.
+
+CRITICAL: This is not about summarizing or compacting. We are talking about the status, task and objectives currently active in the convertion to keep as much context as possible regarding the last messages.
+</OUTPUT_FORMAT>

shotgun/prompts/loader.py

@@ -0,0 +1,140 @@
+"""Template loader utility for managing Jinja2 prompt templates."""
+
+import time
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+from jinja2 import Environment, FileSystemLoader, Template, select_autoescape
+
+from shotgun.logging_config import setup_logger
+
+logger = setup_logger(__name__)
+
+
+class PromptLoader:
+    """Manages loading and rendering of Jinja2 prompt templates."""
+
+    def __init__(self, templates_dir: str | Path | None = None) -> None:
+        """Initialize the prompt loader.
+
+        Args:
+            templates_dir: Directory containing templates. Defaults to prompts directory.
+        """
+        if templates_dir is None:
+            templates_dir = Path(__file__).parent
+        else:
+            templates_dir = Path(templates_dir)
+
+        if not templates_dir.exists():
+            raise ValueError(f"Templates directory does not exist: {templates_dir}")
+
+        self.templates_dir = templates_dir
+        self.env = Environment(
+            loader=FileSystemLoader(str(templates_dir)),
+            autoescape=select_autoescape(["j2"]),
+            trim_blocks=True,
+            lstrip_blocks=True,
+        )
+
+        # Add common global functions and variables
+        self.env.globals.update(
+            {
+                "now": datetime.now,
+                "timestamp": time.time,
+                "current_timestamp": lambda: int(time.time()),
+                "timestamp_minus": lambda seconds: int(time.time()) - seconds,
+            }
+        )
+
+        logger.debug("Initialized PromptLoader with templates_dir: %s", templates_dir)
+
+    def load_template(self, template_path: str) -> Template:
+        """Load a template from the templates directory.
+
+        Args:
+            template_path: Path to template relative to templates directory
+
+        Returns:
+            Loaded Jinja2 template
+        """
+        try:
+            template = self.env.get_template(template_path)
+            logger.debug("Loaded template: %s", template_path)
+            return template
+        except Exception as e:
+            logger.error("Failed to load template %s: %s", template_path, str(e))
+            raise
+
+    def render(self, template_path: str, **context: Any) -> str:
+        """Render a template with the given context.
+
+        Args:
+            template_path: Path to template relative to templates directory
+            **context: Variables to pass to the template
+
+        Returns:
+            Rendered template content
+        """
+        template = self.load_template(template_path)
+        try:
+            result = template.render(**context)
+            logger.debug(
+                "Rendered template %s with %d context variables",
+                template_path,
+                len(context),
+            )
+            return result
+        except Exception as e:
+            logger.error("Failed to render template %s: %s", template_path, str(e))
+            raise
+
+    def render_string(self, template_string: str, **context: Any) -> str:
+        """Render a template from a string.
+
+        Args:
+            template_string: Template content as string
+            **context: Variables to pass to the template
+
+        Returns:
+            Rendered template content
+        """
+        try:
+            template = self.env.from_string(template_string)
+            result = template.render(**context)
+            logger.debug(
+                "Rendered string template with %d context variables", len(context)
+            )
+            return result
+        except Exception as e:
+            logger.error("Failed to render string template: %s", str(e))
+            raise
+
+
+# Global instance for the default templates directory
+_default_loader: PromptLoader | None = None
+
+
+def get_prompt_loader() -> PromptLoader:
+    """Get the default prompt loader instance.
+
+    Returns:
+        Default PromptLoader instance
+    """
+    global _default_loader
+    if _default_loader is None:
+        _default_loader = PromptLoader()
+    return _default_loader
+
+
+def render_prompt(template_path: str, **context: Any) -> str:
+    """Convenience function to render a template using the default loader.
+
+    Args:
+        template_path: Path to template relative to templates directory
+        **context: Variables to pass to the template
+
+    Returns:
+        Rendered template content
+    """
+    return get_prompt_loader().render(template_path, **context)

shotgun/prompts/user/research.j2

@@ -0,0 +1,5 @@
+Research the USER_QUERY thoroughly and provide comprehensive findings:
+
+<USER_QUERY>
+{{ user_query }}
+</USER_QUERY>

shotgun/sdk/__init__.py

@@ -0,0 +1,13 @@
+"""Shotgun SDK - Framework-agnostic business logic for CLI and TUI."""
+
+from .codebase import CodebaseSDK
+from .exceptions import CodebaseNotFoundError, CodebaseOperationError, ShotgunSDKError
+from .services import get_codebase_service
+
+__all__ = [
+    "CodebaseSDK",
+    "ShotgunSDKError",
+    "CodebaseNotFoundError",
+    "CodebaseOperationError",
+    "get_codebase_service",
+]