PraisonAI 3.0.0__py3-none-any.whl

praisonai/capabilities/passthrough.py

@@ -0,0 +1,204 @@
+"""
+Passthrough Capabilities Module
+
+Provides generic API passthrough functionality for provider-specific endpoints.
+"""
+
+from dataclasses import dataclass, field
+from typing import Optional, Any, Dict
+
+
+@dataclass
+class PassthroughResult:
+    """Result from passthrough API call."""
+    data: Any
+    status_code: int = 200
+    headers: Optional[Dict[str, str]] = None
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+
+def passthrough(
+    endpoint: str,
+    method: str = "POST",
+    model: Optional[str] = None,
+    custom_llm_provider: Optional[str] = None,
+    data: Optional[Dict[str, Any]] = None,
+    json_data: Optional[Dict[str, Any]] = None,
+    headers: Optional[Dict[str, str]] = None,
+    timeout: float = 600.0,
+    api_key: Optional[str] = None,
+    api_base: Optional[str] = None,
+    metadata: Optional[Dict[str, Any]] = None,
+    **kwargs
+) -> PassthroughResult:
+    """
+    Make a passthrough API call to a provider endpoint.
+    
+    Args:
+        endpoint: The endpoint path (e.g., "/v1/custom/endpoint")
+        method: HTTP method ("GET", "POST", "PUT", "DELETE")
+        model: Optional model name for routing
+        custom_llm_provider: Provider name
+        data: Form data
+        json_data: JSON body data
+        headers: Additional headers
+        timeout: Request timeout in seconds
+        api_key: Optional API key override
+        api_base: Optional API base URL override
+        metadata: Optional metadata for tracing
+        
+    Returns:
+        PassthroughResult with response data
+        
+    Example:
+        >>> result = passthrough(
+        ...     "/v1/custom/endpoint",
+        ...     method="POST",
+        ...     json_data={"key": "value"},
+        ...     custom_llm_provider="openai"
+        ... )
+        >>> print(result.data)
+    """
+    import litellm
+    
+    call_kwargs = {
+        'endpoint': endpoint,
+        'method': method,
+        'timeout': timeout,
+    }
+    
+    if model:
+        call_kwargs['model'] = model
+    if custom_llm_provider:
+        call_kwargs['custom_llm_provider'] = custom_llm_provider
+    if data:
+        call_kwargs['data'] = data
+    if json_data:
+        call_kwargs['json'] = json_data
+    if headers:
+        call_kwargs['request_headers'] = headers
+    if api_key:
+        call_kwargs['api_key'] = api_key
+    if api_base:
+        call_kwargs['api_base'] = api_base
+    
+    call_kwargs.update(kwargs)
+    
+    if metadata:
+        call_kwargs['metadata'] = metadata
+    
+    # Use passthrough route if available
+    try:
+        response = litellm.llm_passthrough_route(**call_kwargs)
+        
+        return PassthroughResult(
+            data=response.json() if hasattr(response, 'json') else response,
+            status_code=getattr(response, 'status_code', 200),
+            headers=dict(response.headers) if hasattr(response, 'headers') else None,
+            metadata=metadata or {},
+        )
+    except AttributeError:
+        # Fallback to httpx if passthrough not available
+        import httpx
+        
+        url = f"{api_base or 'https://api.openai.com'}{endpoint}"
+        request_headers = headers or {}
+        if api_key:
+            request_headers['Authorization'] = f"Bearer {api_key}"
+        
+        with httpx.Client(timeout=timeout) as client:
+            response = client.request(
+                method=method,
+                url=url,
+                headers=request_headers,
+                json=json_data,
+                data=data,
+            )
+        
+        return PassthroughResult(
+            data=response.json() if response.headers.get('content-type', '').startswith('application/json') else response.text,
+            status_code=response.status_code,
+            headers=dict(response.headers),
+            metadata=metadata or {},
+        )
+
+
+async def apassthrough(
+    endpoint: str,
+    method: str = "POST",
+    model: Optional[str] = None,
+    custom_llm_provider: Optional[str] = None,
+    data: Optional[Dict[str, Any]] = None,
+    json_data: Optional[Dict[str, Any]] = None,
+    headers: Optional[Dict[str, str]] = None,
+    timeout: float = 600.0,
+    api_key: Optional[str] = None,
+    api_base: Optional[str] = None,
+    metadata: Optional[Dict[str, Any]] = None,
+    **kwargs
+) -> PassthroughResult:
+    """
+    Async: Make a passthrough API call to a provider endpoint.
+    
+    See passthrough() for full documentation.
+    """
+    import litellm
+    
+    call_kwargs = {
+        'endpoint': endpoint,
+        'method': method,
+        'timeout': timeout,
+    }
+    
+    if model:
+        call_kwargs['model'] = model
+    if custom_llm_provider:
+        call_kwargs['custom_llm_provider'] = custom_llm_provider
+    if data:
+        call_kwargs['data'] = data
+    if json_data:
+        call_kwargs['json'] = json_data
+    if headers:
+        call_kwargs['request_headers'] = headers
+    if api_key:
+        call_kwargs['api_key'] = api_key
+    if api_base:
+        call_kwargs['api_base'] = api_base
+    
+    call_kwargs.update(kwargs)
+    
+    if metadata:
+        call_kwargs['metadata'] = metadata
+    
+    try:
+        response = await litellm.allm_passthrough_route(**call_kwargs)
+        
+        return PassthroughResult(
+            data=response.json() if hasattr(response, 'json') else response,
+            status_code=getattr(response, 'status_code', 200),
+            headers=dict(response.headers) if hasattr(response, 'headers') else None,
+            metadata=metadata or {},
+        )
+    except AttributeError:
+        import httpx
+        
+        url = f"{api_base or 'https://api.openai.com'}{endpoint}"
+        request_headers = headers or {}
+        if api_key:
+            request_headers['Authorization'] = f"Bearer {api_key}"
+        
+        async with httpx.AsyncClient(timeout=timeout) as client:
+            response = await client.request(
+                method=method,
+                url=url,
+                headers=request_headers,
+                json=json_data,
+                data=data,
+            )
+        
+        return PassthroughResult(
+            data=response.json() if response.headers.get('content-type', '').startswith('application/json') else response.text,
+            status_code=response.status_code,
+            headers=dict(response.headers),
+            metadata=metadata or {},
+        )

praisonai/capabilities/rag.py

@@ -0,0 +1,207 @@
+"""
+RAG (Retrieval-Augmented Generation) Capabilities Module
+
+Provides RAG functionality for document retrieval and generation.
+"""
+
+from dataclasses import dataclass, field
+from typing import Optional, Any, Dict, List
+
+
+@dataclass
+class RAGResult:
+    """Result from RAG operations."""
+    answer: str
+    sources: Optional[List[Dict[str, Any]]] = None
+    model: Optional[str] = None
+    usage: Optional[Dict[str, int]] = None
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+
+def rag_query(
+    query: str,
+    documents: Optional[List[str]] = None,
+    vector_store_id: Optional[str] = None,
+    model: str = "gpt-4o-mini",
+    max_results: int = 5,
+    timeout: float = 600.0,
+    api_key: Optional[str] = None,
+    api_base: Optional[str] = None,
+    metadata: Optional[Dict[str, Any]] = None,
+    **kwargs
+) -> RAGResult:
+    """
+    Perform a RAG query.
+    
+    Args:
+        query: Query string
+        documents: Optional list of documents to search
+        vector_store_id: Optional vector store ID to search
+        model: Model to use for generation
+        max_results: Maximum number of results to retrieve
+        timeout: Request timeout in seconds
+        api_key: Optional API key override
+        api_base: Optional API base URL override
+        metadata: Optional metadata for tracing
+        
+    Returns:
+        RAGResult with answer and sources
+        
+    Example:
+        >>> result = rag_query("What is AI?", documents=["AI is..."])
+        >>> print(result.answer)
+    """
+    import litellm
+    
+    sources = []
+    context = ""
+    
+    # If vector store provided, search it
+    if vector_store_id:
+        try:
+            from .vector_stores import vector_store_search
+            search_result = vector_store_search(
+                vector_store_id=vector_store_id,
+                query=query,
+                max_num_results=max_results,
+                api_key=api_key,
+                api_base=api_base,
+            )
+            for r in search_result.results:
+                if 'content' in r:
+                    for c in r['content']:
+                        text = c.get('text', '')
+                        context += f"\n{text}"
+                        sources.append({
+                            'score': r.get('score', 0),
+                            'text': text[:200],
+                        })
+        except Exception:
+            pass
+    
+    # If documents provided, use them as context
+    if documents:
+        for i, doc in enumerate(documents[:max_results]):
+            context += f"\n{doc}"
+            sources.append({
+                'index': i,
+                'text': doc[:200],
+            })
+    
+    # Generate answer
+    messages = [
+        {"role": "system", "content": "You are a helpful assistant. Answer the question based on the provided context. If the context doesn't contain relevant information, say so."},
+        {"role": "user", "content": f"Context:\n{context}\n\nQuestion: {query}"}
+    ]
+    
+    response = litellm.completion(
+        model=model,
+        messages=messages,
+        timeout=timeout,
+        api_key=api_key,
+        api_base=api_base,
+        **kwargs
+    )
+    
+    answer = response.choices[0].message.content if response.choices else ""
+    
+    usage = None
+    if hasattr(response, 'usage') and response.usage:
+        usage = {
+            'prompt_tokens': getattr(response.usage, 'prompt_tokens', 0),
+            'completion_tokens': getattr(response.usage, 'completion_tokens', 0),
+            'total_tokens': getattr(response.usage, 'total_tokens', 0),
+        }
+    
+    return RAGResult(
+        answer=answer,
+        sources=sources if sources else None,
+        model=model,
+        usage=usage,
+        metadata=metadata or {},
+    )
+
+
+async def arag_query(
+    query: str,
+    documents: Optional[List[str]] = None,
+    vector_store_id: Optional[str] = None,
+    model: str = "gpt-4o-mini",
+    max_results: int = 5,
+    timeout: float = 600.0,
+    api_key: Optional[str] = None,
+    api_base: Optional[str] = None,
+    metadata: Optional[Dict[str, Any]] = None,
+    **kwargs
+) -> RAGResult:
+    """
+    Async: Perform a RAG query.
+    
+    See rag_query() for full documentation.
+    """
+    import litellm
+    
+    sources = []
+    context = ""
+    
+    if vector_store_id:
+        try:
+            from .vector_stores import avector_store_search
+            search_result = await avector_store_search(
+                vector_store_id=vector_store_id,
+                query=query,
+                max_num_results=max_results,
+                api_key=api_key,
+                api_base=api_base,
+            )
+            for r in search_result.results:
+                if 'content' in r:
+                    for c in r['content']:
+                        text = c.get('text', '')
+                        context += f"\n{text}"
+                        sources.append({
+                            'score': r.get('score', 0),
+                            'text': text[:200],
+                        })
+        except Exception:
+            pass
+    
+    if documents:
+        for i, doc in enumerate(documents[:max_results]):
+            context += f"\n{doc}"
+            sources.append({
+                'index': i,
+                'text': doc[:200],
+            })
+    
+    messages = [
+        {"role": "system", "content": "You are a helpful assistant. Answer the question based on the provided context. If the context doesn't contain relevant information, say so."},
+        {"role": "user", "content": f"Context:\n{context}\n\nQuestion: {query}"}
+    ]
+    
+    response = await litellm.acompletion(
+        model=model,
+        messages=messages,
+        timeout=timeout,
+        api_key=api_key,
+        api_base=api_base,
+        **kwargs
+    )
+    
+    answer = response.choices[0].message.content if response.choices else ""
+    
+    usage = None
+    if hasattr(response, 'usage') and response.usage:
+        usage = {
+            'prompt_tokens': getattr(response.usage, 'prompt_tokens', 0),
+            'completion_tokens': getattr(response.usage, 'completion_tokens', 0),
+            'total_tokens': getattr(response.usage, 'total_tokens', 0),
+        }
+    
+    return RAGResult(
+        answer=answer,
+        sources=sources if sources else None,
+        model=model,
+        usage=usage,
+        metadata=metadata or {},
+    )

praisonai/capabilities/realtime.py

@@ -0,0 +1,160 @@
+"""
+Realtime Capabilities Module
+
+Provides realtime audio/video streaming functionality.
+"""
+
+from dataclasses import dataclass, field
+from typing import Optional, Any, Dict, List, Callable
+
+
+@dataclass
+class RealtimeSession:
+    """Realtime session information."""
+    id: str
+    status: str = "created"
+    model: Optional[str] = None
+    url: Optional[str] = None
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class RealtimeEvent:
+    """Realtime event."""
+    type: str
+    data: Optional[Any] = None
+    session_id: Optional[str] = None
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+
+def realtime_connect(
+    model: str = "gpt-4o-realtime-preview",
+    modalities: Optional[List[str]] = None,
+    instructions: Optional[str] = None,
+    voice: str = "alloy",
+    api_key: Optional[str] = None,
+    api_base: Optional[str] = None,
+    metadata: Optional[Dict[str, Any]] = None,
+    **kwargs
+) -> RealtimeSession:
+    """
+    Create a realtime session.
+    
+    Args:
+        model: Model to use
+        modalities: List of modalities (e.g., ["text", "audio"])
+        instructions: System instructions
+        voice: Voice for audio output
+        api_key: Optional API key override
+        api_base: Optional API base URL override
+        metadata: Optional metadata for tracing
+        
+    Returns:
+        RealtimeSession with connection info
+        
+    Example:
+        >>> session = realtime_connect()
+        >>> print(session.id)
+    """
+    import uuid
+    import os
+    
+    session_id = f"realtime-{uuid.uuid4().hex[:12]}"
+    
+    # Build WebSocket URL
+    base = api_base or os.environ.get("OPENAI_API_BASE", "wss://api.openai.com")
+    if base.startswith("http"):
+        base = base.replace("https://", "wss://").replace("http://", "ws://")
+    
+    url = f"{base.rstrip('/')}/v1/realtime?model={model}"
+    
+    return RealtimeSession(
+        id=session_id,
+        status="created",
+        model=model,
+        url=url,
+        metadata={
+            "modalities": modalities or ["text", "audio"],
+            "instructions": instructions,
+            "voice": voice,
+            **(metadata or {}),
+        },
+    )
+
+
+async def arealtime_connect(
+    model: str = "gpt-4o-realtime-preview",
+    modalities: Optional[List[str]] = None,
+    instructions: Optional[str] = None,
+    voice: str = "alloy",
+    api_key: Optional[str] = None,
+    api_base: Optional[str] = None,
+    metadata: Optional[Dict[str, Any]] = None,
+    **kwargs
+) -> RealtimeSession:
+    """
+    Async: Create a realtime session.
+    
+    See realtime_connect() for full documentation.
+    """
+    return realtime_connect(
+        model=model,
+        modalities=modalities,
+        instructions=instructions,
+        voice=voice,
+        api_key=api_key,
+        api_base=api_base,
+        metadata=metadata,
+        **kwargs
+    )
+
+
+def realtime_send(
+    session_id: str,
+    event_type: str,
+    data: Optional[Any] = None,
+    metadata: Optional[Dict[str, Any]] = None,
+    **kwargs
+) -> RealtimeEvent:
+    """
+    Send an event to a realtime session.
+    
+    Args:
+        session_id: Session ID
+        event_type: Event type (e.g., "input_audio_buffer.append")
+        data: Event data
+        metadata: Optional metadata for tracing
+        
+    Returns:
+        RealtimeEvent with send confirmation
+        
+    Note:
+        This is a placeholder. Actual implementation requires WebSocket connection.
+    """
+    return RealtimeEvent(
+        type=event_type,
+        data=data,
+        session_id=session_id,
+        metadata=metadata or {},
+    )
+
+
+async def arealtime_send(
+    session_id: str,
+    event_type: str,
+    data: Optional[Any] = None,
+    metadata: Optional[Dict[str, Any]] = None,
+    **kwargs
+) -> RealtimeEvent:
+    """
+    Async: Send an event to a realtime session.
+    
+    See realtime_send() for full documentation.
+    """
+    return realtime_send(
+        session_id=session_id,
+        event_type=event_type,
+        data=data,
+        metadata=metadata,
+        **kwargs
+    )