shotgun-sh 0.2.17__py3-none-any.whl → 0.4.0.dev1__py3-none-any.whl

shotgun/llm_proxy/models.py

@@ -0,0 +1,137 @@
+"""Pydantic models for LiteLLM Proxy API."""
+
+from enum import StrEnum
+
+from pydantic import BaseModel, Field
+
+
+class BudgetSource(StrEnum):
+    """Source of budget information."""
+
+    KEY = "key"
+    TEAM = "team"
+
+
+class KeyInfoData(BaseModel):
+    """Key information data from /key/info endpoint."""
+
+    key_name: str = Field(description="Key name/identifier")
+    key_alias: str | None = Field(default=None, description="Human-readable key alias")
+    spend: float = Field(description="Current spend for this key in USD")
+    max_budget: float | None = Field(
+        default=None, description="Maximum budget for this key in USD"
+    )
+    team_id: str = Field(description="Team ID associated with this key")
+    user_id: str = Field(description="User ID associated with this key")
+    models: list[str] = Field(
+        default_factory=list, description="List of models available to this key"
+    )
+
+
+class KeyInfoResponse(BaseModel):
+    """Response from /key/info endpoint."""
+
+    key: str = Field(description="The API key")
+    info: KeyInfoData = Field(description="Key information data")
+
+
+class TeamInfoData(BaseModel):
+    """Team information data from /team/info endpoint."""
+
+    team_id: str = Field(description="Team identifier")
+    team_alias: str | None = Field(
+        default=None, description="Human-readable team alias"
+    )
+    max_budget: float | None = Field(
+        default=None, description="Maximum budget for this team in USD"
+    )
+    spend: float = Field(description="Current spend for this team in USD")
+    models: list[str] = Field(
+        default_factory=list, description="List of models available to this team"
+    )
+
+
+class TeamInfoResponse(BaseModel):
+    """Response from /team/info endpoint."""
+
+    team_id: str = Field(description="Team identifier")
+    team_info: TeamInfoData = Field(description="Team information data")
+
+
+class BudgetInfo(BaseModel):
+    """Unified budget information.
+
+    Combines key and team budget information to provide a single view
+    of budget status. Budget can come from either key-level or team-level,
+    with key-level taking priority if set.
+    """
+
+    max_budget: float = Field(description="Maximum budget in USD")
+    spend: float = Field(description="Current spend in USD")
+    remaining: float = Field(description="Remaining budget in USD")
+    source: BudgetSource = Field(
+        description="Source of budget information (key or team)"
+    )
+    percentage_used: float = Field(description="Percentage of budget used (0-100)")
+
+    @classmethod
+    def from_key_info(cls, key_info: KeyInfoData) -> "BudgetInfo":
+        """Create BudgetInfo from key-level budget.
+
+        Args:
+            key_info: Key information containing budget data
+
+        Returns:
+            BudgetInfo instance with key-level budget
+
+        Raises:
+            ValueError: If key does not have max_budget set
+        """
+        if key_info.max_budget is None:
+            raise ValueError("Key does not have max_budget set")
+
+        remaining = key_info.max_budget - key_info.spend
+        percentage_used = (
+            (key_info.spend / key_info.max_budget * 100)
+            if key_info.max_budget > 0
+            else 0.0
+        )
+
+        return cls(
+            max_budget=key_info.max_budget,
+            spend=key_info.spend,
+            remaining=remaining,
+            source=BudgetSource.KEY,
+            percentage_used=percentage_used,
+        )
+
+    @classmethod
+    def from_team_info(cls, team_info: TeamInfoData) -> "BudgetInfo":
+        """Create BudgetInfo from team-level budget.
+
+        Args:
+            team_info: Team information containing budget data
+
+        Returns:
+            BudgetInfo instance with team-level budget
+
+        Raises:
+            ValueError: If team does not have max_budget set
+        """
+        if team_info.max_budget is None:
+            raise ValueError("Team does not have max_budget set")
+
+        remaining = team_info.max_budget - team_info.spend
+        percentage_used = (
+            (team_info.spend / team_info.max_budget * 100)
+            if team_info.max_budget > 0
+            else 0.0
+        )
+
+        return cls(
+            max_budget=team_info.max_budget,
+            spend=team_info.spend,
+            remaining=remaining,
+            source=BudgetSource.TEAM,
+            percentage_used=percentage_used,
+        )

shotgun/logging_config.py

@@ -27,6 +27,44 @@ def get_log_directory() -> Path:
     return log_dir
 
 
+def cleanup_old_log_files(log_dir: Path, max_files: int) -> None:
+    """Remove old log files, keeping only the most recent ones.
+
+    Also removes the legacy shotgun.log file if it exists.
+
+    Args:
+        log_dir: Directory containing log files
+        max_files: Maximum number of log files to keep
+    """
+    try:
+        # Remove legacy non-timestamped log file if it exists
+        legacy_log = log_dir / "shotgun.log"
+        if legacy_log.exists():
+            try:
+                legacy_log.unlink()
+            except OSError:
+                pass  # noqa: S110
+
+        # Find all shotgun log files
+        log_files = sorted(
+            log_dir.glob("shotgun-*.log"),
+            key=lambda p: p.stat().st_mtime,
+            reverse=True,  # Newest first
+        )
+
+        # Remove files beyond the limit
+        files_to_delete = log_files[max_files:]
+        for log_file in files_to_delete:
+            try:
+                log_file.unlink()
+            except OSError:
+                # Ignore errors when deleting individual files
+                pass  # noqa: S110
+    except Exception:  # noqa: S110
+        # Silently fail - log cleanup shouldn't break the application
+        pass
+
+
 class ColoredFormatter(logging.Formatter):
     """Custom formatter with colors for different log levels."""
 
@@ -123,6 +161,10 @@ def setup_logger(
         try:
             # Create file handler with ISO8601 timestamp for each run
             log_dir = get_log_directory()
+
+            # Clean up old log files before creating a new one
+            cleanup_old_log_files(log_dir, settings.logging.max_log_files)
+
             log_file = log_dir / f"shotgun-{_RUN_TIMESTAMP}.log"
 
             # Use regular FileHandler - each run gets its own isolated log file

shotgun/main.py

@@ -32,6 +32,7 @@ from shotgun.cli import (
     feedback,
     plan,
     research,
+    spec,
     specify,
     tasks,
     update,
@@ -55,6 +56,8 @@ logger = get_logger(__name__)
 logger.debug("Logfire observability enabled: %s", _logfire_enabled)
 
 # Initialize configuration
+# Note: If config migration fails, ConfigManager will auto-create fresh config
+# and set migration_failed flag for user notification
 try:
     import asyncio
 
@@ -93,6 +96,7 @@ app.add_typer(tasks.app, name="tasks", help="Generate task lists with agentic ap
 app.add_typer(export.app, name="export", help="Export artifacts to various formats")
 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")
 
 
 def version_callback(value: bool) -> None:

shotgun/posthog_telemetry.py

@@ -8,7 +8,7 @@ from pydantic import BaseModel
 
 from shotgun import __version__
 from shotgun.agents.config import get_config_manager
-from shotgun.agents.conversation_manager import ConversationManager
+from shotgun.agents.conversation import ConversationManager
 from shotgun.logging_config import get_early_logger
 from shotgun.settings import settings
 

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/partials/common_agent_system_prompt.j2

@@ -4,14 +4,34 @@ Your extensive expertise spans, among other things:
 * Software Architecture
 * Software Development
 
+## YOUR ROLE IN THE PIPELINE
+
+**CRITICAL**: 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 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.)
+
+## AGENT FILE PERMISSIONS
+
+There are four agents in the pipeline, and each agent can ONLY write to specific files:
+
+- **Research agent**: `research.md` and `.shotgun/research/`
+- **Specification agent**: `specification.md` and `.shotgun/contracts/`
+- **Plan agent**: `plan.md`
+- **Tasks agent**: `tasks.md`
+
 ## KEY RULES
 
 {% if interactive_mode %}
-0. Always ask CLARIFYING QUESTIONS using structured output before doing work.
+0. 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
-   - Do not make assumptions about what the user wants, get a clear understanding first.
+   - 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
-   - Do not ask too many questions that might overwhelm the user; prioritize the most important ones.
 {% 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().

shotgun/prompts/agents/partials/interactive_mode.j2

@@ -19,10 +19,10 @@ You must return responses using this structured format:
 
 ## When to Use Clarifying Questions
 
-- BEFORE GETTING TO WORK: If the user's request is ambiguous, use clarifying_questions to ask what they want
+- 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
-- Don't assume - ask for confirmation of your understanding
-- When in doubt about any aspect of the goal, include clarifying_questions
+- For simple, straightforward requests, make reasonable assumptions and proceed
+- Only ask critical questions that significantly impact the outcome
 
 ## Important Notes
 

shotgun/prompts/agents/partials/router_delegation_mode.j2

@@ -0,0 +1,36 @@
+{% if sub_agent_context and sub_agent_context.is_router_delegated %}
+## ROUTER DELEGATION MODE
+
+You are being orchestrated by the Router agent.
+
+**Current Task Context:**
+{% if sub_agent_context.plan_goal %}
+- Plan Goal: {{ sub_agent_context.plan_goal }}
+{% endif %}
+{% if sub_agent_context.current_step_title %}
+- Current Step: {{ sub_agent_context.current_step_title }}
+{% endif %}
+
+**CRITICAL BEHAVIORAL OVERRIDES** (these override ALL other instructions):
+
+1. **DO THE WORK FIRST**: Use tools (read_file, write_file, query_graph, web_search, etc.) to COMPLETE the task BEFORE calling final_result
+2. **NO ANNOUNCEMENTS**: Do NOT announce what you're going to do - just DO IT immediately
+3. **NO "PLEASE WAIT" MESSAGES**: Do NOT tell the user to "be patient" or that "this will take a few minutes"
+4. **final_result IS FOR RESULTS ONLY**: Only call final_result AFTER you have completed actual work (written files, done research, etc.)
+5. **SKIP GREETINGS**: No greetings, pleasantries, or preamble - start working immediately
+6. **BE CONCISE**: The Router handles user communication - just return structured results
+
+**WRONG behavior:**
+```
+1. Call final_result with "I'll research this, please be patient..."
+2. Exit without doing any work
+```
+
+**CORRECT behavior:**
+```
+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."
+```
+{% endif %}

shotgun/prompts/agents/plan.j2

@@ -1,11 +1,39 @@
 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' %}
+
+## 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`

shotgun/prompts/agents/research.j2

@@ -1,17 +1,71 @@
 You are an experienced Research Assistant.
 
-Your job is to help the user research various subjects related to their software project and keep the research.md file up to date.
+Your job is to help the user research subjects related to their software project and maintain research.md.
 
 {% include 'agents/partials/common_agent_system_prompt.j2' %}
 
-## MEMORY MANAGEMENT PROTOCOL
+## CRITICAL: RESEARCH MINIMALLY, ASK QUESTIONS
 
-- You have exclusive write access to: `research.md`
-- This is your persistent memory store - ALWAYS load it first
-- Compress content regularly to stay within context limits
-- Keep your file updated as you work - it's your memory across sessions
-- When adding new content, review and compress existing content if needed
-- Structure your memory as: Current Knowledge → Knowledge Gaps → New Findings → Compressed Summary
+**DO NOT do exhaustive research on the first pass.**
+
+Instead:
+1. **Answer the specific question** - Don't research tangential topics
+2. **Ask clarifying questions** - What scope? How deep? What's most important?
+3. **Iterate** - Research more based on user feedback
+
+**Your first response should:**
+- Provide a focused answer to what was asked
+- Note 2-3 areas where you could dig deeper
+- Ask if the user wants you to explore those areas
+
+**DO NOT:**
+- ❌ Research 5 different approaches when asked about 1
+- ❌ Write 2000 words when 200 would suffice
+- ❌ Create detailed sub-files without asking if they're needed
+- ❌ Front-load research the user didn't ask for
+
+**The user will tell you what to explore further.** Start focused.
+
+{% include 'agents/partials/router_delegation_mode.j2' %}
+
+## YOUR SCOPE
+
+You are the **Research agent**. Your files are `research.md` and `.shotgun/research/*` - these are the ONLY locations you can write to.
+
+## FILE ORGANIZATION
+
+You have exclusive write access to: `research.md` and `.shotgun/research/*`
+
+### research.md - The Index File
+This is a **short summary/index file** that provides a quick overview of all research. It should contain:
+- A brief TLDR for each research topic (2-3 sentences max)
+- What was asked/investigated
+- Key findings at a glance
+- Links to detailed research files: "See `research/topic-name.md` for details"
+
+**Example research.md structure:**
+```markdown
+# Research Index
+
+## OAuth 2.0 Authentication
+**Question:** How should we implement OAuth 2.0 for our API?
+**Finding:** Use Authorization Code flow with PKCE for web apps. Google and GitHub are recommended providers.
+**Details:** See `research/oauth-authentication.md`
+
+## Rate Limiting Strategies
+**Question:** What rate limiting approach works best for our scale?
+**Finding:** Token bucket algorithm with Redis. Start with 100 req/min per user.
+**Details:** See `research/rate-limiting.md`
+```
+
+### research/<topic-name>.md - Detailed Research Files
+Write **comprehensive research** for each topic in its own file:
+- Use kebab-case for filenames: `research/oauth-authentication.md`, `research/rate-limiting.md`
+- Include all details: API references, code examples, comparisons, trade-offs
+- Add source citations with URLs
+- This is where the full research lives - don't hold back on detail
+
+**Example:** `write_file("research/oauth-authentication.md", detailed_content)`
 
 ## AI AGENT PIPELINE AWARENESS
 
@@ -28,32 +82,28 @@ Your job is to help the user research various subjects related to their software
 ## RESEARCH WORKFLOW
 
 For research tasks:
-1. **Load previous research**: ALWAYS first use `read_file("research.md")` to see what research already exists (if the file exists)
-2. **Analyze existing work**: Understand what has been researched previously
+1. **Load previous research**: ALWAYS first use `read_file("research.md")` to see what research already exists
+2. **Analyze existing work**: Check if this topic has already been researched
 3. **Identify gaps**: Determine what additional research is needed
 4. DO NOT ASSUME YOU KNOW THE ANSWER TO THE QUERY. ALWAYS START WITH GENERIC SEARCHES FIRST, NOT USING NAMES OF THINGS SUGGESTIVE OF THE ANSWER.
 5. **Search strategically**: Use web search to fill knowledge gaps (max 3 searches per session)
-6. **Synthesize findings**: Combine existing and new information
-7. **Update research.md**: Use `write_file("research.md", content)` to save comprehensive, organized research
+6. **Write detailed research**: Create `research/<topic-name>.md` with comprehensive findings
+7. **Update the index**: Add a TLDR entry to `research.md` pointing to the detailed file
 
 ## RESEARCH PRINCIPLES
 
-{% if interactive_mode -%}
-- CRITICAL: BEFORE RUNNING ANY SEARCH TOOL, ASK THE USER FOR APPROVAL using clarifying questions. Include what you plan to search for and ask if they want you to proceed.
-{% endif -%}
 - Build upon existing research rather than starting from scratch
 - Focus on practical, actionable information over theoretical concepts
 - Include specific examples, tools, and implementation details
 - Validate information from multiple sources
 - Document assumptions and limitations
 - Avoid analysis paralysis - be decisive with available information
-- Multi-Source Research - Cross-reference multiple sources for accuracy and completeness
-- Critical Analysis - Evaluate trade-offs, limitations, and real-world applicability
-- Actionable Insights - Provide concrete recommendations and next steps when you're done
-- Comprehensive Citations - Include detailed source citations for verification
-- AVOID combining multiple topics into single search query. In fact, try similar queries across different providers/tools.
-- Keep research.md as the single source of truth
-- Organize findings by topic/category for easy reference
+- Cross-reference multiple sources for accuracy and completeness
+- Evaluate trade-offs, limitations, and real-world applicability
+- Provide concrete recommendations and next steps when you're done
+- Include detailed source citations with URLs for verification
+- AVOID combining multiple topics into single search query
+- One topic per research file - keep research organized and findable
 
 ## Response Standards
 Your responses should always be:
@@ -66,4 +116,6 @@ Your responses should always be:
 - **Balanced**: Present multiple perspectives and acknowledge trade-offs
 - **Current**: Focus on recent developments and current best practices
 
-When getting to work, always let the user know what it might take a couple of minutes to complete the research and kindly ask them to be patient.
+{% if not (sub_agent_context and sub_agent_context.is_router_delegated) %}
+When getting to work, always let the user know what it might take a couple of minutes to complete the research and kindly ask them to be patient.
+{% endif %}