langchain-trigger-server 0.1.0__py3-none-any.whl

langchain_triggers/core.py

@@ -0,0 +1,83 @@
+"""Core types and interfaces for the triggers framework."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+from pydantic import BaseModel, Field
+
+
+
+class ProviderAuthInfo(BaseModel):
+    """Authentication info for a specific OAuth provider."""
+    
+    token: Optional[str] = None
+    auth_required: bool = False
+    auth_url: Optional[str] = None
+    auth_id: Optional[str] = None
+
+
+class UserAuthInfo(BaseModel):
+    """User authentication info containing OAuth tokens or auth requirements."""
+    
+    user_id: str
+    providers: Dict[str, ProviderAuthInfo] = Field(default_factory=dict)
+    
+    class Config:
+        arbitrary_types_allowed = True
+
+
+class MetadataManager:
+    """Manages trigger registration metadata with database persistence."""
+    
+    def __init__(self, database: Any, registration_id: str, initial_metadata: Dict[str, Any]):
+        self.database = database
+        self.registration_id = registration_id
+        self.metadata = initial_metadata.copy()
+    
+    def get(self, key: str, default: Any = None) -> Any:
+        """Get a metadata value by key."""
+        return self.metadata.get(key, default)
+    
+    async def update(self, updates: Dict[str, Any]) -> None:
+        """Update metadata and persist to database."""
+        # Update local state
+        self.metadata.update(updates)
+        
+        # Persist to database
+        await self.database.update_trigger_metadata(self.registration_id, updates)
+
+
+
+class AgentInvocationRequest(BaseModel):
+    """Request to invoke an AI agent."""
+    
+    assistant_id: str
+    user_id: str
+    input_data: Any
+    thread_id: Optional[str] = None
+    metadata: Dict[str, Any] = Field(default_factory=dict)
+
+
+class TriggerHandlerResult(BaseModel):
+    """Result returned by trigger handlers."""
+    
+    invoke_agent: bool = Field(default=True, description="Whether to invoke agents for this event")
+    data: Optional[str] = Field(default=None, description="String data to send to agents")
+    
+    def model_post_init(self, __context) -> None:
+        """Validate that data is provided when invoke_agent is True."""
+        if self.invoke_agent and not self.data:
+            raise ValueError("data field is required when invoke_agent is True")
+
+
+class TriggerRegistrationResult(BaseModel):
+    """Result returned by registration handlers."""
+    
+    metadata: Dict[str, Any] = Field(default_factory=dict, description="Metadata to store with the registration")
+
+
+class TriggerRegistrationModel(BaseModel):
+    """Base class for trigger resource models that define how webhooks are matched to registrations."""
+    
+    class Config:
+        arbitrary_types_allowed = True

langchain_triggers/database/__init__.py

@@ -0,0 +1,16 @@
+"""Database module for trigger operations."""
+
+from .interface import TriggerDatabaseInterface
+from .supabase import SupabaseTriggerDatabase
+
+
+def create_database(database_type: str = "supabase", **kwargs) -> TriggerDatabaseInterface:
+    """Factory function to create database implementation."""
+    
+    if database_type == "supabase":
+        return SupabaseTriggerDatabase(**kwargs)
+    else:
+        raise ValueError(f"Unknown database type: {database_type}")
+
+
+__all__ = ["TriggerDatabaseInterface", "SupabaseTriggerDatabase", "create_database"]

langchain_triggers/database/interface.py

@@ -0,0 +1,150 @@
+"""Database interface for trigger operations."""
+
+from abc import ABC, abstractmethod
+from typing import List, Optional, Dict, Any
+
+
+class TriggerDatabaseInterface(ABC):
+    """Abstract interface for trigger database operations."""
+    
+    # ========== Trigger Templates ==========
+    
+    @abstractmethod
+    async def create_trigger_template(
+        self, 
+        id: str, 
+        name: str, 
+        description: str = None,
+        registration_schema: Dict = None
+    ) -> Optional[Dict[str, Any]]:
+        """Create a new trigger template."""
+        pass
+    
+    @abstractmethod
+    async def get_trigger_templates(self) -> List[Dict[str, Any]]:
+        """Get all available trigger templates."""
+        pass
+    
+    @abstractmethod
+    async def get_trigger_template(self, id: str) -> Optional[Dict[str, Any]]:
+        """Get a specific trigger template by ID."""
+        pass
+    
+    # ========== Trigger Registrations ==========
+    
+    @abstractmethod
+    async def create_trigger_registration(
+        self,
+        user_id: str,
+        template_id: str, 
+        resource: Dict,
+        metadata: Dict = None
+    ) -> Optional[Dict[str, Any]]:
+        """Create a new trigger registration for a user."""
+        pass
+    
+    @abstractmethod
+    async def get_user_trigger_registrations(self, user_id: str) -> List[Dict[str, Any]]:
+        """Get all trigger registrations for a user."""
+        pass
+    
+    @abstractmethod
+    async def get_trigger_registration(
+        self, 
+        registration_id: str, 
+        user_id: str = None
+    ) -> Optional[Dict[str, Any]]:
+        """Get a specific trigger registration."""
+        pass
+    
+    @abstractmethod
+    async def find_registration_by_resource(
+        self, 
+        template_id: str, 
+        resource_data: Dict[str, Any]
+    ) -> Optional[Dict[str, Any]]:
+        """Find trigger registration by matching resource data."""
+        pass
+    
+    @abstractmethod
+    async def update_trigger_metadata(
+        self, 
+        registration_id: str, 
+        metadata_updates: Dict,
+        user_id: str = None
+    ) -> bool:
+        """Update metadata for a trigger registration."""
+        pass
+    
+    @abstractmethod
+    async def delete_trigger_registration(
+        self,
+        registration_id: str,
+        user_id: str = None
+    ) -> bool:
+        """Delete a trigger registration."""
+        pass
+    
+    # ========== Agent-Trigger Links ==========
+    
+    @abstractmethod
+    async def link_agent_to_trigger(
+        self,
+        agent_id: str,
+        registration_id: str, 
+        created_by: str,
+        field_selection: Optional[Dict[str, bool]] = None
+    ) -> bool:
+        """Link an agent to a trigger registration with optional field selection."""
+        pass
+    
+    @abstractmethod
+    async def unlink_agent_from_trigger(
+        self,
+        agent_id: str,
+        registration_id: str
+    ) -> bool:
+        """Unlink an agent from a trigger registration."""
+        pass
+    
+    @abstractmethod
+    async def get_agents_for_trigger(self, registration_id: str) -> List[Dict[str, Any]]:
+        """Get all agent links for a trigger registration with field_selection."""
+        pass
+    
+    @abstractmethod
+    async def get_triggers_for_agent(self, agent_id: str) -> List[Dict[str, Any]]:
+        """Get all trigger registrations linked to an agent."""
+        pass
+    
+    @abstractmethod
+    async def set_agent_trigger_links(
+        self,
+        agent_id: str, 
+        registration_ids: List[str],
+        created_by: str
+    ) -> bool:
+        """Replace all trigger links for an agent (atomic operation)."""
+        pass
+    
+    @abstractmethod
+    async def replace_trigger_agent_links(
+        self,
+        registration_id: str,
+        agent_ids: List[str], 
+        created_by: str
+    ) -> bool:
+        """Replace all agent links for a trigger (atomic operation)."""
+        pass
+    
+    # ========== Helper Methods ==========
+    
+    @abstractmethod
+    async def get_user_from_token(self, token: str) -> Optional[str]:
+        """Extract user ID from authentication token."""
+        pass
+    
+    @abstractmethod
+    async def get_user_by_email(self, email: str) -> Optional[str]:
+        """Get user ID by email from trigger registrations."""
+        pass

langchain_triggers/database/supabase.py

@@ -0,0 +1,365 @@
+"""Supabase implementation of trigger database interface."""
+
+import os
+import logging
+from typing import List, Optional, Dict, Any
+from supabase import create_client, Client
+
+from .interface import TriggerDatabaseInterface
+
+logger = logging.getLogger(__name__)
+
+
+class SupabaseTriggerDatabase(TriggerDatabaseInterface):
+    """Supabase implementation of trigger database operations."""
+    
+    def __init__(self, supabase_url: str = None, supabase_key: str = None):
+        self.supabase_url = supabase_url or os.getenv("SUPABASE_URL")
+        self.supabase_key = supabase_key or os.getenv("SUPABASE_KEY")
+        
+        if not self.supabase_url or not self.supabase_key:
+            raise ValueError("SUPABASE_URL and SUPABASE_KEY environment variables are required")
+        
+        self.client = create_client(self.supabase_url, self.supabase_key)
+        logger.info("Initialized SupabaseTriggerDatabase")
+    
+    
+    # ========== Trigger Templates ==========
+    
+    async def create_trigger_template(
+        self, 
+        id: str, 
+        name: str, 
+        description: str = None,
+        registration_schema: Dict = None
+    ) -> Optional[Dict[str, Any]]:
+        """Create a new trigger template."""
+        try:
+            data = {
+                "id": id,
+                "name": name,
+                "description": description,
+                "registration_schema": registration_schema or {}
+            }
+            
+            response = self.client.table("trigger_templates").insert(data).execute()
+            return response.data[0] if response.data else None
+            
+        except Exception as e:
+            logger.error(f"Error creating trigger template: {e}")
+            return None
+    
+    async def get_trigger_templates(self) -> List[Dict[str, Any]]:
+        """Get all available trigger templates."""
+        try:
+            response = self.client.table("trigger_templates").select("*").execute()
+            return response.data or []
+        except Exception as e:
+            logger.error(f"Error getting trigger templates: {e}")
+            return []
+    
+    async def get_trigger_template(self, id: str) -> Optional[Dict[str, Any]]:
+        """Get a specific trigger template by ID."""
+        try:
+            response = self.client.table("trigger_templates").select("*").eq("id", id).single().execute()
+            return response.data if response.data else None
+        except Exception as e:
+            # Don't log as error if template just doesn't exist (expected on first startup)
+            if "no rows returned" in str(e).lower() or "multiple (or no) rows returned" in str(e).lower():
+                logger.debug(f"Trigger template {id} not found in database")
+            else:
+                logger.error(f"Error getting trigger template {id}: {e}")
+            return None
+    
+    # ========== Trigger Registrations ==========
+    
+    async def create_trigger_registration(
+        self,
+        user_id: str,
+        template_id: str, 
+        resource: Dict,
+        metadata: Dict = None
+    ) -> Optional[Dict[str, Any]]:
+        """Create a new trigger registration for a user."""
+        try:
+            # Verify template exists
+            template = await self.get_trigger_template(template_id)
+            if not template:
+                logger.error(f"Template not found for ID: {template_id}")
+                return None
+            
+            data = {
+                "user_id": user_id,
+                "template_id": template_id,
+                "resource": resource,
+                "metadata": metadata or {},
+                "status": "active"
+            }
+            
+            response = self.client.table("trigger_registrations").insert(data).execute()
+            return response.data[0] if response.data else None
+            
+        except Exception as e:
+            logger.error(f"Error creating trigger registration: {e}")
+            return None
+    
+    async def get_user_trigger_registrations(self, user_id: str) -> List[Dict[str, Any]]:
+        """Get all trigger registrations for a user."""
+        try:
+            response = self.client.table("trigger_registrations").select("""
+                *,
+                trigger_templates(id, name, description)
+            """).eq("user_id", user_id).order("created_at", desc=True).execute()
+            
+            return response.data or []
+        except Exception as e:
+            logger.error(f"Error getting user trigger registrations: {e}")
+            return []
+    
+    async def get_trigger_registration(self, registration_id: str, user_id: str = None) -> Optional[Dict[str, Any]]:
+        """Get a specific trigger registration."""
+        try:
+            query = self.client.table("trigger_registrations").select("*").eq("id", registration_id)
+            if user_id:
+                query = query.eq("user_id", user_id)
+            
+            response = query.single().execute()
+            return response.data if response.data else None
+        except Exception as e:
+            logger.error(f"Error getting trigger registration {registration_id}: {e}")
+            return None
+    
+    async def update_trigger_metadata(
+        self, 
+        registration_id: str, 
+        metadata_updates: Dict,
+        user_id: str = None
+    ) -> bool:
+        """Update metadata for a trigger registration."""
+        try:
+            # Get current registration to merge metadata
+            current = await self.get_trigger_registration(registration_id, user_id)
+            if not current:
+                return False
+            
+            # Merge existing metadata with updates
+            current_metadata = current.get("metadata", {})
+            updated_metadata = {**current_metadata, **metadata_updates}
+            
+            query = self.client.table("trigger_registrations").update({
+                "metadata": updated_metadata,
+                "updated_at": "NOW()"
+            }).eq("id", registration_id)
+            
+            if user_id:
+                query = query.eq("user_id", user_id)
+            
+            response = query.execute()
+            return bool(response.data)
+            
+        except Exception as e:
+            logger.error(f"Error updating trigger metadata: {e}")
+            return False
+    
+    async def delete_trigger_registration(
+        self,
+        registration_id: str,
+        user_id: str = None
+    ) -> bool:
+        """Delete a trigger registration."""
+        try:
+            query = self.client.table("trigger_registrations").delete().eq("id", registration_id)
+            if user_id:
+                query = query.eq("user_id", user_id)
+            
+            response = query.execute()
+            return True  # Delete operations don't return data
+            
+        except Exception as e:
+            logger.error(f"Error deleting trigger registration: {e}")
+            return False
+    
+    async def find_registration_by_resource(
+        self, 
+        template_id: str, 
+        resource_data: Dict[str, Any]
+    ) -> Optional[Dict[str, Any]]:
+        """Find trigger registration by matching resource data."""
+        try:
+            # Build query to match against trigger_registrations with template_id filter
+            query = self.client.table("trigger_registrations").select(
+                "*, trigger_templates(id, name, description)"
+            ).eq("trigger_templates.id", template_id)
+            
+            # Add resource field matches
+            for field, value in resource_data.items():
+                query = query.eq(f"resource->>{field}", value)
+            
+            response = query.execute()
+            
+            if response.data:
+                return response.data[0]  # Return first match
+            return None
+            
+        except Exception as e:
+            logger.error(f"Error finding registration by resource: {e}")
+            return None
+    
+    # ========== Agent-Trigger Links ==========
+    
+    async def link_agent_to_trigger(
+        self,
+        agent_id: str,
+        registration_id: str, 
+        created_by: str,
+        field_selection: Optional[Dict[str, bool]] = None
+    ) -> bool:
+        """Link an agent to a trigger registration with optional field selection."""
+        try:
+            data = {
+                "agent_id": agent_id,
+                "registration_id": registration_id,
+                "created_by": created_by,
+                "field_selection": field_selection
+            }
+            
+            response = self.client.table("agent_trigger_links").insert(data).execute()
+            return bool(response.data)
+            
+        except Exception as e:
+            logger.error(f"Error linking agent to trigger: {e}")
+            return False
+    
+    async def unlink_agent_from_trigger(
+        self,
+        agent_id: str,
+        registration_id: str
+    ) -> bool:
+        """Unlink an agent from a trigger registration."""
+        try:
+            response = self.client.table("agent_trigger_links").delete().eq(
+                "agent_id", agent_id
+            ).eq("registration_id", registration_id).execute()
+            
+            return True  # Delete operations don't return data
+            
+        except Exception as e:
+            logger.error(f"Error unlinking agent from trigger: {e}")
+            return False
+    
+    async def get_agents_for_trigger(self, registration_id: str) -> List[Dict[str, Any]]:
+        """Get all agent links for a trigger registration with field_selection."""
+        try:
+            response = self.client.table("agent_trigger_links").select("agent_id, field_selection").eq(
+                "registration_id", registration_id
+            ).execute()
+            
+            return response.data or []
+            
+        except Exception as e:
+            logger.error(f"Error getting agents for trigger: {e}")
+            return []
+    
+    async def get_triggers_for_agent(self, agent_id: str) -> List[Dict[str, Any]]:
+        """Get all trigger registrations linked to an agent."""
+        try:
+            response = self.client.table("agent_trigger_links").select("""
+                registration_id,
+                trigger_registrations(
+                    *,
+                    trigger_templates(id, name, description)
+                )
+            """).eq("agent_id", agent_id).execute()
+            
+            return [row["trigger_registrations"] for row in response.data or []]
+            
+        except Exception as e:
+            logger.error(f"Error getting triggers for agent: {e}")
+            return []
+    
+    async def set_agent_trigger_links(
+        self,
+        agent_id: str, 
+        registration_ids: List[str],
+        created_by: str
+    ) -> bool:
+        """Replace all trigger links for an agent (atomic operation)."""
+        try:
+            # Delete existing links
+            await self.client.table("agent_trigger_links").delete().eq("agent_id", agent_id).execute()
+            
+            # Create new links
+            if registration_ids:
+                links = [
+                    {
+                        "agent_id": agent_id,
+                        "registration_id": reg_id,
+                        "created_by": created_by
+                    }
+                    for reg_id in registration_ids
+                ]
+                
+                response = self.client.table("agent_trigger_links").insert(links).execute()
+                return bool(response.data)
+            
+            return True  # Successfully cleared all links
+            
+        except Exception as e:
+            logger.error(f"Error setting agent trigger links: {e}")
+            return False
+    
+    async def replace_trigger_agent_links(
+        self,
+        registration_id: str,
+        agent_ids: List[str], 
+        created_by: str
+    ) -> bool:
+        """Replace all agent links for a trigger (atomic operation)."""
+        try:
+            # Delete existing links
+            await self.client.table("agent_trigger_links").delete().eq("registration_id", registration_id).execute()
+            
+            # Create new links
+            if agent_ids:
+                links = [
+                    {
+                        "agent_id": agent_id,
+                        "registration_id": registration_id,
+                        "created_by": created_by
+                    }
+                    for agent_id in agent_ids
+                ]
+                
+                response = self.client.table("agent_trigger_links").insert(links).execute()
+                return bool(response.data)
+            
+            return True  # Successfully cleared all links
+            
+        except Exception as e:
+            logger.error(f"Error replacing trigger agent links: {e}")
+            return False
+    
+    # ========== Helper Methods ==========
+    
+    async def get_user_from_token(self, token: str) -> Optional[str]:
+        """Extract user ID from JWT token via Supabase auth."""
+        try:
+            client = self._create_user_client(token)
+            response = client.auth.get_user(token)
+            return response.user.id if response.user else None
+        except Exception as e:
+            logger.error(f"Error getting user from token: {e}")
+            return None
+    
+    async def get_user_by_email(self, email: str) -> Optional[str]:
+        """Get user ID by email from trigger registrations."""
+        try:
+            response = self.client.table("trigger_registrations").select("user_id").eq(
+                "resource->>email", email
+            ).limit(1).execute()
+            
+            return response.data[0]["user_id"] if response.data else None
+            
+        except Exception as e:
+            logger.error(f"Error getting user by email: {e}")
+            return None

langchain_triggers/decorators.py

@@ -0,0 +1,75 @@
+"""Trigger system - templates with registration and webhook handlers."""
+
+from __future__ import annotations
+
+import inspect
+from typing import Any, Awaitable, Callable, Dict, List, Optional, Type, get_type_hints
+from .core import UserAuthInfo, TriggerRegistrationModel, TriggerHandlerResult, TriggerRegistrationResult, MetadataManager
+from pydantic import BaseModel
+
+class TriggerTemplate:
+    """A trigger template with registration handler and main handler."""
+    
+    def __init__(
+        self,
+        id: str,
+        name: str,
+        description: str,
+        registration_model: Type[BaseModel],
+
+        registration_handler,
+        trigger_handler,
+        registration_resolver,
+
+        oauth_providers: Optional[Dict[str, List[str]]] = None,
+    ):
+        self.id = id
+        self.name = name
+        self.description = description
+        self.registration_model = registration_model
+        self.registration_handler = registration_handler
+        self.trigger_handler = trigger_handler
+        self.registration_resolver = registration_resolver
+        self.oauth_providers = oauth_providers or {}
+
+        self._validate_handler_signatures()
+    
+    def _validate_handler_signatures(self):
+        """Validate that all handler functions have the correct signatures."""
+        # Expected: async def handler(registration: RegistrationModel, auth_user: UserAuthInfo) -> TriggerRegistrationResult
+        self._validate_handler("registration_handler", self.registration_handler, [self.registration_model, UserAuthInfo], TriggerRegistrationResult)
+        
+        # Expected: async def handler(payload: Dict[str, Any], auth_user: UserAuthInfo, metadata: MetadataManager) -> TriggerHandlerResult
+        self._validate_handler("trigger_handler", self.trigger_handler, [Dict[str, Any], UserAuthInfo, MetadataManager], TriggerHandlerResult)
+        
+        # Expected: async def resolver(payload: Dict[str, Any]) -> RegistrationModel
+        self._validate_handler("registration_resolver", self.registration_resolver, [Dict[str, Any]], self.registration_model)
+    
+    def _validate_handler(self, handler_name: str, handler_func, expected_types: List[Type], expected_return_type: Type = None):
+        """Common validation logic for all handler functions."""
+        if not inspect.iscoroutinefunction(handler_func):
+            raise TypeError(f"{handler_name} for trigger '{self.id}' must be async")
+        
+        sig = inspect.signature(handler_func)
+        params = list(sig.parameters.values())
+        expected_param_count = len(expected_types)
+        
+        if len(params) != expected_param_count:
+            raise TypeError(f"{handler_name} for trigger '{self.id}' must have {expected_param_count} parameters, got {len(params)}")
+        
+        hints = get_type_hints(handler_func)
+        param_names = list(sig.parameters.keys())
+        
+        # Check each parameter type if type hints are available
+        for i, expected_type in enumerate(expected_types):
+            if param_names[i] in hints and hints[param_names[i]] != expected_type:
+                expected_name = getattr(expected_type, '__name__', str(expected_type))
+                raise TypeError(f"{handler_name} for trigger '{self.id}': param {i+1} should be {expected_name}")
+        
+        # Check return type if expected and available
+        if expected_return_type and 'return' in hints:
+            actual_return_type = hints['return']
+            if actual_return_type != expected_return_type:
+                expected_name = getattr(expected_return_type, '__name__', str(expected_return_type))
+                actual_name = getattr(actual_return_type, '__name__', str(actual_return_type))
+                raise TypeError(f"{handler_name} for trigger '{self.id}': return type should be {expected_name}, got {actual_name}")