shotgun-sh 0.1.0__py3-none-any.whl

shotgun/prompts/codebase/cypher_query_patterns.j2

@@ -0,0 +1,223 @@
+# FOLLOW THESE PATTERNS TO GENERATE THE CORRECT CYPHER QUERY:
+
+**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,30 @@
+
+# Codebase Graph Schema Definition
+The database contains information about a codebase, structured with the following nodes and relationships.
+
+THE ONLY PROPERTIES THAT ARE AVAILABLE ARE THE ONES LISTED BELOW. DO NOT MAKE UP ANY OTHER PROPERTIES.
+PAY ATTENTION TO THE PROPERTY TYPES.
+- 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/incremental_summarization.j2

@@ -0,0 +1,53 @@
+You are extending an existing conversation summary with new messages.
+
+Your task is to merge the new information into the existing summary while maintaining the same structured format and preserving all important information.
+
+<EXISTING_SUMMARY>
+{{ existing_summary }}
+</EXISTING_SUMMARY>
+
+<NEW_MESSAGES>
+{{ new_messages }}
+</NEW_MESSAGES>
+
+Instructions:
+1. Update the existing summary sections with new information from the NEW_MESSAGES
+2. Maintain the same structure and format as the existing summary
+3. Preserve all important information from both existing and new content
+4. Do not repeat information already covered in the existing summary unless it's been updated or expanded
+5. Focus on integrating new developments, decisions, or progress into the appropriate sections
+
+<OUTPUT_FORMAT>
+Provide the complete updated summary following the exact same format as the existing summary:
+
+# Context
+
+Updated summary of the discussion, incorporating new topics or tasks. 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 updated important elements of context, learnings and entities from the entire 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 new tool results were obtained, preserve them verbatim if short, summarize if long focusing on preserving all important facts.
+
+If new user messages exist, preserve them verbatim if short to medium length, summarize if long focusing on preserving all important facts.
+
+If there are any new links, IDs, filenames, etc. - preserve them verbatim.
+
+# Timeline
+
+Update the timeline with new important tasks and content:
+- 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
+
+[Include any new timeline entries from the new messages]
+
+# Current status, task and objectives
+
+Based on the complete conversation including new messages, update the current status, task and objectives.
+
+CRITICAL: This section should reflect the most current state based on all messages including the new ones. This is not about summarizing but about the status, task and objectives currently active in the conversation to keep as much context as possible.
+</OUTPUT_FORMAT>

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/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",
+]