cleanup up version (#482)

* cleanup up version

* chore: Auto-fix pre-commit issues

* code rabbit suggestions

* update litellm version

* chore: Auto-fix pre-commit issues

---------

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
Co-authored-by: Nandan <[email protected]>

Author: 3 people

.env.template

@@ -71,6 +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
 # GitHub Authentication Configuration
 # GH_TOKEN_LIST: Personal Access Tokens for GitHub.com (comma-separated for token pool)
 # GITHUB_APP_ID + GITHUB_PRIVATE_KEY: GitHub App credentials (recommended for production)

README.md

@@ -264,6 +264,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

@@ -52,6 +52,7 @@ def __init__(self):
             )
             exit(1)
         self.setup_sentry()
+        self.setup_phoenix_tracing()
         self.app = FastAPI()
         self.setup_cors()
         self.include_routers()
@@ -64,6 +65,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/integrations/integrations_router.py

@@ -321,7 +321,7 @@ async def linear_oauth_callback(
 
                 # Save the integration (this will exchange code for tokens)
                 save_result = await integrations_service.save_linear_integration(
-                    save_request, 
+                    save_request,
                     user_id,
                 )
 

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/tracing/__init__.py

@@ -0,0 +1,233 @@
+"""
+Phoenix Tracing Integration for LLM Monitoring
+
+This module sets up Arize Phoenix tracing for monitoring:
+- Pydantic AI agent operations (agent runs, delegations, structured outputs)
+- LLM API calls (via LiteLLM - Anthropic, OpenAI, etc.)
+- Token usage and costs
+- Multi-agent delegations (supervisor → subagents)
+- Tool calls and results
+- Performance metrics and latency
+
+CRITICAL SETUP ORDER:
+1. Call initialize_phoenix_tracing() at application startup (in main.py)
+2. This registers Phoenix and instruments Pydantic AI BEFORE any agents are created
+3. Create agents with instrument=True to enable tracing
+
+Usage:
+    from app.modules.intelligence.tracing.phoenix_tracer import initialize_phoenix_tracing
+
+    # Initialize once at application startup (BEFORE creating any agents)
+    initialize_phoenix_tracing()
+
+    # Then create agents with instrument=True
+    agent = Agent(model=..., tools=..., instrument=True)
+
+What gets traced:
+    - Pydantic AI: Agent.run(), Agent.run_sync(), agent.iter(), structured outputs, retries
+    - LiteLLM: completion(), acompletion(), streaming calls
+    - Multi-agent system: All supervisor and subagent interactions
+    - Tool calls: Function calls and results
+    - Tokens: Usage and cost tracking
+"""
+
+import os
+from typing import Optional
+from app.modules.utils.logger import setup_logger
+
+logger = setup_logger(__name__)
+
+# Global flag to track if Phoenix is initialized
+_PHOENIX_INITIALIZED = False
+
+
+def initialize_phoenix_tracing(
+    project_name: Optional[str] = None,
+    endpoint: Optional[str] = None,
+    api_key: Optional[str] = None,
+    auto_instrument: bool = True,
+) -> bool:
+    """
+    Initialize Phoenix tracing for the application.
+
+    This should be called once at application startup, ideally in main.py
+    before any LLM calls are made.
+
+    Args:
+        project_name: Name of the project in Phoenix UI. If None, reads from PHOENIX_PROJECT_NAME env var
+                     (default: "potpie-ai" if env var not set). Function parameter takes precedence over env var.
+        endpoint: Phoenix collector endpoint. If None, reads from PHOENIX_COLLECTOR_ENDPOINT env var
+                 (default: http://localhost:6006 for local Phoenix)
+        api_key: Phoenix API key. If None, reads from PHOENIX_API_KEY env var
+                (required for Phoenix Cloud, optional for local)
+        auto_instrument: Whether to automatically instrument LiteLLM (default: True)
+
+    Returns:
+        bool: True if initialization successful, False otherwise
+
+    Environment Variables:
+        PHOENIX_ENABLED: Set to "false" to disable Phoenix tracing (default: "true")
+        PHOENIX_COLLECTOR_ENDPOINT: Phoenix collector URL (default: http://localhost:6006)
+        PHOENIX_API_KEY: API key for Phoenix Cloud (optional for local)
+        PHOENIX_PROJECT_NAME: Project name (used only if project_name parameter is None, default: "potpie-ai")
+        ENV: Environment identifier (e.g., "development", "production", "staging", "testing") - used as "source" attribute in traces (default: "local")
+    """
+    global _PHOENIX_INITIALIZED
+
+    # Check if Phoenix is disabled
+    if os.getenv("PHOENIX_ENABLED", "true").lower() == "false":
+        logger.info("Phoenix tracing is disabled via PHOENIX_ENABLED=false")
+        return False
+
+    # Check if already initialized
+    if _PHOENIX_INITIALIZED:
+        logger.info("Phoenix tracing already initialized")
+        return True
+
+    try:
+        # Import required modules
+        from opentelemetry import trace
+        from opentelemetry.exporter.otlp.proto.http.trace_exporter import (
+            OTLPSpanExporter,
+        )
+        from opentelemetry.sdk.trace import TracerProvider
+        from opentelemetry.sdk.trace.export import SimpleSpanProcessor
+        from opentelemetry.sdk.resources import Resource
+        from openinference.instrumentation.pydantic_ai import OpenInferenceSpanProcessor
+        from openinference.instrumentation.litellm import LiteLLMInstrumentor
+
+        # Get configuration from environment variables
+        endpoint = endpoint or os.getenv(
+            "PHOENIX_COLLECTOR_ENDPOINT", "http://localhost:6006"
+        )
+        api_key = api_key or os.getenv("PHOENIX_API_KEY")
+        # Function parameter takes precedence over environment variable
+        project_name = project_name or os.getenv("PHOENIX_PROJECT_NAME", "potpie-ai")
+        # Get the environment/source from ENV variable (defaults to "local" if not set)
+        source = os.getenv("ENV", "local")
+
+        logger.info(
+            "Initializing Phoenix tracing:\n"
+            "  Project: %s\n"
+            "  Endpoint: %s\n"
+            "  Source: %s\n"
+            "  Auto-instrument: %s",
+            project_name,
+            endpoint,
+            source,
+            auto_instrument,
+        )
+
+        # STEP 1: Create and set up the tracer provider with resource attributes
+        resource = Resource.create(
+            {
+                "service.name": project_name,
+                "source": source,
+            }
+        )
+        tracer_provider = TracerProvider(resource=resource)
+        trace.set_tracer_provider(tracer_provider)
+
+        # STEP 2: Set up OTLP exporter to send traces to Phoenix
+        otlp_endpoint = f"{endpoint}/v1/traces"
+        headers = {}
+        if api_key:
+            headers["Authorization"] = f"Bearer {api_key}"
+
+        exporter = OTLPSpanExporter(endpoint=otlp_endpoint, headers=headers)
+
+        # STEP 3: Add span processors
+        # OpenInferenceSpanProcessor for Pydantic AI (adds semantic conventions)
+        tracer_provider.add_span_processor(OpenInferenceSpanProcessor())
+        # SimpleSpanProcessor to export spans to Phoenix
+        tracer_provider.add_span_processor(SimpleSpanProcessor(exporter))
+        logger.info("✅ Added OpenInference span processor for Pydantic AI tracing")
+
+        # STEP 4: Conditionally instrument LiteLLM (for underlying LLM API calls)
+        if auto_instrument:
+            litellm_instrumentor = LiteLLMInstrumentor()
+            litellm_instrumentor.instrument(tracer_provider=tracer_provider)
+            logger.info("✅ Instrumented LiteLLM for Phoenix tracing")
+        else:
+            logger.debug("Skipped LiteLLM instrumentation: auto_instrument=False")
+
+        _PHOENIX_INITIALIZED = True
+
+        logger.info(
+            "✅ Phoenix tracing initialized successfully!\n" "   View traces at: %s",
+            endpoint,
+        )
+
+        return True
+
+    except ImportError as e:
+        logger.warning(
+            "Phoenix tracing not available (missing dependencies): %s\n"
+            "Install with: pip install arize-phoenix arize-phoenix-otel openinference-instrumentation-pydantic-ai openinference-instrumentation-litellm",
+            e,
+        )
+        return False
+
+    except Exception as e:
+        logger.error("Failed to initialize Phoenix tracing: %s", e, exc_info=True)
+        return False
+
+
+def get_tracer(name: str = __name__):
+    """
+    Get an OpenTelemetry tracer for manual span creation.
+
+    Args:
+        name: Name for the tracer (usually __name__ of the module)
+
+    Returns:
+        Tracer instance or None if Phoenix not initialized
+
+    Example:
+        tracer = get_tracer(__name__)
+
+        def my_function(input: str) -> str:
+            return process(input)
+    """
+    try:
+        from opentelemetry import trace
+
+        if not _PHOENIX_INITIALIZED:
+            logger.debug("Phoenix not initialized, returning default tracer")
+
+        return trace.get_tracer(name)
+
+    except ImportError:
+        logger.debug("OpenTelemetry not available")
+        return None
+
+
+def is_phoenix_enabled() -> bool:
+    """Check if Phoenix tracing is enabled and initialized."""
+    return _PHOENIX_INITIALIZED
+
+
+def shutdown_phoenix_tracing():
+    """
+    Shutdown Phoenix tracing and flush any pending traces.
+
+    This should be called on application shutdown to ensure all traces are sent.
+    """
+    global _PHOENIX_INITIALIZED
+
+    if not _PHOENIX_INITIALIZED:
+        return
+
+    try:
+        from opentelemetry import trace
+
+        # Get the tracer provider and shutdown
+        tracer_provider = trace.get_tracer_provider()
+        if hasattr(tracer_provider, "shutdown"):
+            tracer_provider.shutdown()
+            logger.info("Phoenix tracing shutdown successfully")
+
+        _PHOENIX_INITIALIZED = False
+
+    except Exception as e:
+        logger.error("Error shutting down Phoenix tracing: %s", e)

app/modules/intelligence/tracing/phoenix_tracer.py

@@ -73,3 +73,11 @@ pytest-asyncio
 Pillow==10.0.1
 python-multipart>=0.0.7
 asyncpg==0.30.0
+arize-phoenix==12.12.0
+arize-phoenix-client==1.22.0
+arize-phoenix-evals==2.5.0
+arize-phoenix-otel==0.13.1
+openinference-instrumentation-litellm==0.1.28
+openinference-instrumentation-openai==0.1.40
+openinference-instrumentation-pydantic-ai==0.1.9
+anthropic==0.72.0