cleanup up version

.env.template

@@ -71,7 +71,13 @@ POSTHOG_API_KEY=
 POSTHOG_HOST=
 FIRECRAWL_API_KEY=
 
-
+# Phoenix Tracing Configuration
+# Set PHOENIX_ENABLED=false to disable tracing
+PHOENIX_ENABLED=true
+# Phoenix collector endpoint (default: local Phoenix server)
+PHOENIX_COLLECTOR_ENDPOINT=http://localhost:6006
+# Project name shown in Phoenix UI (default: "potpie-ai")
+PHOENIX_PROJECT_NAME=potpie-ai
 
 # For tests
 # create a private repo named "potpie-private-test-repo"

README.md

@@ -224,6 +224,14 @@ Potpie provides a set of tools that agents can use to interact with the knowledg
    - Start the FastAPI application
    - Start the Celery worker
 
+**Optional: Phoenix Tracing Setup (Local Only)**
+
+   To monitor LLM traces and agent operations with Phoenix in local development:
+   ```bash
+   phoenix serve
+   ```
+   Run this in a new terminal to start the Phoenix server. Traces will be available at `http://localhost:6006` (default). Phoenix tracing is automatically initialized when Potpie starts, but you need to run `phoenix serve` separately to view the traces. **Note:** This setup is for local development only.
+
 3. **Stop Potpie**
 
    To stop all Potpie services:

app/celery/celery_app.py

@@ -80,7 +80,22 @@ def configure_celery(queue_prefix: str):
 
 configure_celery(queue_name)
 
-# Import the lock decorator
+
+def setup_phoenix_tracing():
+    """Initialize Phoenix tracing for LLM monitoring in Celery workers."""
+    try:
+        from app.modules.intelligence.tracing.phoenix_tracer import (
+            initialize_phoenix_tracing,
+        )
+
+        initialize_phoenix_tracing()
+    except Exception as e:
+        logger.warning(
+            f"Phoenix tracing initialization failed in Celery worker (non-fatal): {e}"
+        )
+
+
+setup_phoenix_tracing()
 
 # Import the lock decorator
 from celery.contrib.abortable import AbortableTask  # noqa

app/main.py

@@ -51,6 +51,7 @@ def __init__(self):
             )
             exit(1)
         self.setup_sentry()
+        self.setup_phoenix_tracing()
         self.app = FastAPI()
         self.setup_cors()
         self.include_routers()
@@ -63,6 +64,16 @@ def setup_sentry(self):
                 profiles_sample_rate=1.0,
             )
 
+    def setup_phoenix_tracing(self):
+        try:
+            from app.modules.intelligence.tracing.phoenix_tracer import (
+                initialize_phoenix_tracing,
+            )
+
+            initialize_phoenix_tracing()
+        except Exception as e:
+            logging.warning(f"Phoenix tracing initialization failed (non-fatal): {e}")
+
     def setup_cors(self):
         origins = ["*"]
         self.app.add_middleware(

app/modules/intelligence/agents/chat_agents/pydantic_agent.py

@@ -139,6 +139,7 @@ def _create_agent(self, ctx: ChatContext) -> Agent:
             "defer_model_check": True,
             "end_strategy": "exhaustive",
             "model_settings": {"max_tokens": 14000},
+            "instrument": True,
         }
 
         if not allow_parallel_tools:

app/modules/intelligence/tools/jira_tools/README.md

@@ -21,7 +21,7 @@ The Jira tools enable agents to perform common Jira operations on behalf of user
   - Set at creation time
   - Defines what type of work item it is
   - Examples: Bug, Task, Story, Epic, Subtask
-  
+
 - **Status**: The current STATE in the workflow (e.g., To Do, In Progress, Done)
   - Changes throughout the issue's lifecycle
   - Represents where the issue is in its workflow

app/modules/intelligence/tools/jira_tools/add_jira_comment_tool.py

@@ -26,18 +26,18 @@ class AddJiraCommentTool:
 
     name = "Add Jira Comment"
     description = """Add a comment to an existing Jira issue.
-    
+
     Use this tool when you need to:
     - Add analysis results or findings to an issue
     - Document progress or updates on work
     - Provide additional context or information
     - Log investigation results or debugging notes
     - Reply to discussions on an issue
     - Add code review feedback
-    
+
     The comment will be posted with your user account as the author.
     Supports Jira text formatting (markdown-like syntax).
-    
+
     Returns confirmation and the posted comment details.
     """
 
@@ -99,18 +99,18 @@ def add_jira_comment_tool(db: Session, user_id: str) -> StructuredTool:
         func=tool_instance.run,
         name="Add Jira Comment",
         description="""Add a comment to an existing Jira issue.
-        
+
         Use this when you need to:
         - Document analysis results or findings
         - Provide updates or progress on work
         - Add additional context or information
         - Log investigation or debugging notes
         - Reply to discussions
-        
+
         Inputs:
         - issue_key (str): The issue key (e.g., 'PROJ-123')
         - comment (str): The comment text to add
-        
+
         Returns confirmation and posted comment details.""",
         args_schema=AddJiraCommentInput,
     )

app/modules/intelligence/tools/jira_tools/create_jira_issue_tool.py

@@ -43,12 +43,12 @@ class CreateJiraIssueTool:
 
     name = "Create Jira Issue"
     description = """Create a new issue in Jira.
-    
+
     IMPORTANT: Before using this tool, use 'Get Jira Project Details' tool to discover:
     - Valid issue types for the project (Task, Bug, Story, Epic, etc.)
     - Valid priority levels (Highest, High, Medium, Low, Lowest)
     - Existing labels you can use
-    
+
     If assigning to a user, use 'Get Jira Project Users' tool first to get their account_id.
 
     Use this tool when you need to:
@@ -57,20 +57,20 @@ class CreateJiraIssueTool:
     - Create a story for a new feature
     - Document technical debt or improvements
     - Log incidents or problems
-    
+
     Required fields:
     - project_key: The project where issue will be created
     - summary: Brief title/summary of the issue
     - description: Detailed description
-    
+
     Optional fields:
     - issue_type: Type of work item (default: 'Task') - e.g., Bug, Story, Epic. Use 'Get Jira Project Details' to see valid types.
     - priority: Priority level (e.g., 'High', 'Medium', 'Low'). Use 'Get Jira Project Details' to see valid priorities.
     - assignee_id: Account ID of user to assign to
     - labels: Tags for categorization
-    
+
     To change the status after creation, use the 'Transition Jira Issue' tool.
-    
+
     Returns the created issue with its key and details.
     """
 
@@ -174,16 +174,16 @@ def create_jira_issue_tool(db: Session, user_id: str) -> StructuredTool:
         func=tool_instance.run,
         name="Create Jira Issue",
         description="""Create a new issue in Jira with summary, description, and optional fields.
-        
+
         IMPORTANT: Use 'Get Jira Project Details' tool FIRST to discover valid issue types and priorities.
         If assigning to a user, use 'Get Jira Project Users' tool to get their account_id.
-        
+
         Use this when you need to:
         - Create bug reports from errors or issues found
         - Create tasks for work that needs to be done
         - Document feature requests or improvements
         - Log incidents or problems
-        
+
         Inputs:
         - project_key (str): Project key (e.g., 'PROJ', 'BUG')
         - summary (str): Brief title of the issue
@@ -192,7 +192,7 @@ def create_jira_issue_tool(db: Session, user_id: str) -> StructuredTool:
         - priority (str, optional): Priority level. Get valid priorities from project details.
         - assignee_id (str, optional): User's account ID. Get from project users tool.
         - labels (list, optional): List of labels/tags
-        
+
         Returns the created issue with its key and URL. Use 'Transition Jira Issue' tool to change status.""",
         args_schema=CreateJiraIssueInput,
     )

app/modules/intelligence/tools/jira_tools/get_jira_issue_tool.py

@@ -25,13 +25,13 @@ class GetJiraIssueTool:
 
     name = "Get Jira Issue"
     description = """Fetch detailed information about a Jira issue by its key.
-    
+
     Use this tool when you need to:
     - Get current status, assignee, or priority of an issue
     - Read the description and summary of an issue
     - Check when an issue was created or last updated
     - Get the reporter and project information
-    
+
     Returns comprehensive issue details including summary, description, status,
     priority, assignee, reporter, dates, and more.
     """
@@ -91,16 +91,16 @@ def get_jira_issue_tool(db: Session, user_id: str) -> StructuredTool:
         func=tool_instance.run,
         name="Get Jira Issue",
         description="""Fetch detailed information about a Jira issue by its key (e.g., 'PROJ-123').
-        
+
         Use this when you need to:
         - Get current status, assignee, or priority of an issue
         - Read the description and summary of an issue
         - Check when an issue was created or last updated
         - Get the reporter and project information
-        
+
         Input:
         - issue_key (str): The Jira issue key (e.g., 'PROJ-123', 'BUG-456')
-        
+
         Returns comprehensive issue details.""",
         args_schema=GetJiraIssueInput,
     )

app/modules/intelligence/tools/jira_tools/get_jira_project_details_tool.py

@@ -25,18 +25,18 @@ class GetJiraProjectDetailsTool:
 
     name = "Get Jira Project Details"
     description = """Get comprehensive details about a Jira project including all metadata.
-    
+
     Use this tool when you need to:
     - Find out what issue types are available in a project (Task, Bug, Story, Epic, etc.)
     - Get available priority levels (Highest, High, Medium, Low, Lowest)
     - See all possible statuses/workflows for transitions (To Do, In Progress, Done, etc.)
     - Get available issue link types (Blocks, Relates to, Duplicates, etc.)
     - View existing labels in the project
     - Get project lead and basic information
-    
+
     This tool is essential BEFORE creating or updating issues to ensure you use valid
     issue types and priorities. The statuses are for use with the Transition tool.
-    
+
     Returns comprehensive project metadata including:
     - Project basic info (name, description, lead, URL)
     - All available issue types with descriptions
@@ -103,18 +103,18 @@ def get_jira_project_details_tool(db: Session, user_id: str) -> StructuredTool:
         func=tool_instance.run,
         name="Get Jira Project Details",
         description="""Get comprehensive metadata about a Jira project.
-        
+
         IMPORTANT: Use this tool FIRST before creating or updating issues to discover:
         - Valid issue types for creation (Task, Bug, Story, Epic, etc.)
         - Valid priority levels for creation/updates (Highest, High, Medium, Low, Lowest)
         - Valid statuses for transitions (To Do, In Progress, Done, etc.) - use with Transition tool
         - Available link types for linking issues
         - Existing labels in the project
-        
+
         Input:
         - project_key (str): The project key (e.g., 'PROJ', 'BUG')
-        
-        Returns all project metadata including issue types, priorities, statuses, 
+
+        Returns all project metadata including issue types, priorities, statuses,
         link types, labels, and basic project information.""",
         args_schema=GetJiraProjectDetailsInput,
     )

app/modules/intelligence/tools/jira_tools/get_jira_project_users_tool.py

@@ -35,16 +35,16 @@ def __init__(self, db: Session, user_id: int):
         self.user_id = user_id
 
     description = """Get a list of users who can be assigned to issues in a Jira project.
-    
+
     Use this tool when you need to:
     - Find a user's account ID for assigning issues
     - Search for users by name or email
     - Discover who can be assigned to tasks in a project
     - Finding users in a particular Jira project
-    
+
     Returns a list of users with their account IDs, display names, and email addresses.
     You can optionally filter by providing a search query (e.g., a person's name).
-    
+
     IMPORTANT: Use the 'accountId' field when assigning issues, NOT the display name."""
 
     async def arun(
@@ -121,14 +121,14 @@ def get_jira_project_users_tool(db: Session, user_id: int) -> StructuredTool:
         func=tool_instance.run,
         name="Get Jira Project Users",
         description="""Get assignable users in a Jira project.
-        
+
         Use this to find user account IDs needed for assigning issues.
         You can search by name or email using the optional query parameter.
-        
+
         Inputs:
         - project_key (str): The project key (e.g., 'PROJ')
         - query (str, optional): Search term to filter users by name or email
-        
+
         Returns a list of users with their account IDs, which you can use when creating or updating issues.
         IMPORTANT: Use the 'accountId' field when assigning, not the display name.""",
         args_schema=GetJiraProjectUsersInput,

app/modules/intelligence/tools/jira_tools/get_jira_projects_tool.py

@@ -26,13 +26,13 @@ class GetJiraProjectsTool:
 
     name = "Get Jira Projects"
     description = """Fetch all Jira projects accessible to the authenticated user.
-    
+
     Use this tool when you need to:
     - List all available projects for the user
     - Find a project by name to get its key
     - Show the user what projects they can create issues in
     - Get project metadata (ID, key, name, lead, type)
-    
+
     Returns a list of all accessible projects with their details including:
     - Project key (used for creating issues)
     - Project name
@@ -104,16 +104,16 @@ def get_jira_projects_tool(db: Session, user_id: str) -> StructuredTool:
         func=tool_instance.run,
         name="Get Jira Projects",
         description="""Fetch all Jira projects accessible to the authenticated user.
-        
+
         Use this when you need to:
         - List all available projects
         - Find a project key by name
         - Show what projects the user can work with
         - Get project metadata for creating issues
-        
+
         Input:
         - max_results (int, optional): Maximum projects to return (default: 50, max: 100)
-        
+
         Returns list of projects with key, name, ID, type, lead, and URL.""",
         args_schema=GetJiraProjectsInput,
     )