PraisonAI 3.0.0__py3-none-any.whl

praisonai/capabilities/rerank.py

@@ -0,0 +1,165 @@
+"""
+Rerank Capabilities Module
+
+Provides document reranking functionality via LiteLLM.
+"""
+
+from dataclasses import dataclass, field
+from typing import Optional, Union, List, Any, Dict
+
+
+@dataclass
+class RerankResult:
+    """Result from document reranking."""
+    results: List[Dict[str, Any]]
+    model: Optional[str] = None
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+
+def rerank(
+    query: str,
+    documents: List[Union[str, Dict[str, Any]]],
+    model: str = "cohere/rerank-english-v3.0",
+    top_n: Optional[int] = None,
+    rank_fields: Optional[List[str]] = None,
+    return_documents: bool = True,
+    max_chunks_per_doc: Optional[int] = None,
+    timeout: float = 600.0,
+    api_key: Optional[str] = None,
+    api_base: Optional[str] = None,
+    metadata: Optional[Dict[str, Any]] = None,
+    **kwargs
+) -> RerankResult:
+    """
+    Rerank documents based on relevance to a query.
+    
+    Args:
+        query: The query to rank documents against
+        documents: List of documents (strings or dicts with text field)
+        model: Model name (e.g., "cohere/rerank-english-v3.0")
+        top_n: Number of top results to return
+        rank_fields: Fields to use for ranking (for dict documents)
+        return_documents: Whether to return document content
+        max_chunks_per_doc: Maximum chunks per document
+        timeout: Request timeout in seconds
+        api_key: Optional API key override
+        api_base: Optional API base URL override
+        metadata: Optional metadata for tracing
+        
+    Returns:
+        RerankResult with ranked documents
+        
+    Example:
+        >>> result = rerank("What is AI?", ["AI is...", "Machine learning..."])
+        >>> for r in result.results:
+        ...     print(r['index'], r['relevance_score'])
+    """
+    import litellm
+    
+    call_kwargs = {
+        'model': model,
+        'query': query,
+        'documents': documents,
+        'return_documents': return_documents,
+        'timeout': timeout,
+    }
+    
+    if top_n:
+        call_kwargs['top_n'] = top_n
+    if rank_fields:
+        call_kwargs['rank_fields'] = rank_fields
+    if max_chunks_per_doc:
+        call_kwargs['max_chunks_per_doc'] = max_chunks_per_doc
+    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
+    
+    response = litellm.rerank(**call_kwargs)
+    
+    results = []
+    if hasattr(response, 'results'):
+        for item in response.results:
+            result_dict = {
+                'index': getattr(item, 'index', 0),
+                'relevance_score': getattr(item, 'relevance_score', 0.0),
+            }
+            if return_documents and hasattr(item, 'document'):
+                result_dict['document'] = item.document
+            results.append(result_dict)
+    
+    return RerankResult(
+        results=results,
+        model=model,
+        metadata=metadata or {},
+    )
+
+
+async def arerank(
+    query: str,
+    documents: List[Union[str, Dict[str, Any]]],
+    model: str = "cohere/rerank-english-v3.0",
+    top_n: Optional[int] = None,
+    rank_fields: Optional[List[str]] = None,
+    return_documents: bool = True,
+    max_chunks_per_doc: Optional[int] = None,
+    timeout: float = 600.0,
+    api_key: Optional[str] = None,
+    api_base: Optional[str] = None,
+    metadata: Optional[Dict[str, Any]] = None,
+    **kwargs
+) -> RerankResult:
+    """
+    Async: Rerank documents based on relevance to a query.
+    
+    See rerank() for full documentation.
+    """
+    import litellm
+    
+    call_kwargs = {
+        'model': model,
+        'query': query,
+        'documents': documents,
+        'return_documents': return_documents,
+        'timeout': timeout,
+    }
+    
+    if top_n:
+        call_kwargs['top_n'] = top_n
+    if rank_fields:
+        call_kwargs['rank_fields'] = rank_fields
+    if max_chunks_per_doc:
+        call_kwargs['max_chunks_per_doc'] = max_chunks_per_doc
+    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
+    
+    response = await litellm.arerank(**call_kwargs)
+    
+    results = []
+    if hasattr(response, 'results'):
+        for item in response.results:
+            result_dict = {
+                'index': getattr(item, 'index', 0),
+                'relevance_score': getattr(item, 'relevance_score', 0.0),
+            }
+            if return_documents and hasattr(item, 'document'):
+                result_dict['document'] = item.document
+            results.append(result_dict)
+    
+    return RerankResult(
+        results=results,
+        model=model,
+        metadata=metadata or {},
+    )

praisonai/capabilities/responses.py

@@ -0,0 +1,266 @@
+"""
+Responses Capabilities Module
+
+Provides response management functionality via LiteLLM.
+"""
+
+from dataclasses import dataclass, field
+from typing import Optional, Any, Dict, List
+
+
+@dataclass
+class ResponseResult:
+    """Result from response operations."""
+    id: str
+    object: str = "response"
+    output: Optional[List[Dict[str, Any]]] = None
+    status: Optional[str] = None
+    model: Optional[str] = None
+    usage: Optional[Dict[str, int]] = None
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+
+def responses_create(
+    model: str,
+    input: str,
+    instructions: Optional[str] = None,
+    tools: Optional[List[Dict[str, Any]]] = None,
+    temperature: float = 1.0,
+    max_output_tokens: Optional[int] = None,
+    timeout: float = 600.0,
+    api_key: Optional[str] = None,
+    api_base: Optional[str] = None,
+    metadata: Optional[Dict[str, Any]] = None,
+    **kwargs
+) -> ResponseResult:
+    """
+    Create a response using the Responses API.
+    
+    Args:
+        model: Model to use
+        input: Input text or messages
+        instructions: System instructions
+        tools: List of tools
+        temperature: Sampling temperature
+        max_output_tokens: Maximum output tokens
+        timeout: Request timeout in seconds
+        api_key: Optional API key override
+        api_base: Optional API base URL override
+        metadata: Optional metadata for tracing
+        
+    Returns:
+        ResponseResult with response data
+        
+    Example:
+        >>> result = responses_create(
+        ...     model="gpt-4o-mini",
+        ...     input="What is 2+2?"
+        ... )
+        >>> print(result.output)
+    """
+    import litellm
+    
+    call_kwargs = {
+        'model': model,
+        'input': input,
+        'temperature': temperature,
+        'timeout': timeout,
+    }
+    
+    if instructions:
+        call_kwargs['instructions'] = instructions
+    if tools:
+        call_kwargs['tools'] = tools
+    if max_output_tokens:
+        call_kwargs['max_output_tokens'] = max_output_tokens
+    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 to use responses API if available
+    try:
+        response = litellm.responses(**call_kwargs)
+        
+        output = None
+        if hasattr(response, 'output'):
+            output = []
+            for item in response.output:
+                output.append({
+                    'type': getattr(item, 'type', 'message'),
+                    'content': getattr(item, 'content', None),
+                })
+        
+        usage = None
+        if hasattr(response, 'usage'):
+            usage = {
+                'input_tokens': getattr(response.usage, 'input_tokens', 0),
+                'output_tokens': getattr(response.usage, 'output_tokens', 0),
+                'total_tokens': getattr(response.usage, 'total_tokens', 0),
+            }
+        
+        return ResponseResult(
+            id=getattr(response, 'id', ''),
+            object=getattr(response, 'object', 'response'),
+            output=output,
+            status=getattr(response, 'status', 'completed'),
+            model=getattr(response, 'model', model),
+            usage=usage,
+            metadata=metadata or {},
+        )
+    except AttributeError:
+        # Fallback to completion if responses not available
+        messages = [{"role": "user", "content": input}]
+        if instructions:
+            messages.insert(0, {"role": "system", "content": instructions})
+        
+        response = litellm.completion(
+            model=model,
+            messages=messages,
+            temperature=temperature,
+            max_tokens=max_output_tokens,
+            timeout=timeout,
+            api_key=api_key,
+            api_base=api_base,
+            **kwargs
+        )
+        
+        output = [{
+            'type': 'message',
+            'content': response.choices[0].message.content if response.choices else None,
+        }]
+        
+        usage = None
+        if hasattr(response, 'usage'):
+            usage = {
+                'input_tokens': getattr(response.usage, 'prompt_tokens', 0),
+                'output_tokens': getattr(response.usage, 'completion_tokens', 0),
+                'total_tokens': getattr(response.usage, 'total_tokens', 0),
+            }
+        
+        return ResponseResult(
+            id=getattr(response, 'id', ''),
+            object='response',
+            output=output,
+            status='completed',
+            model=model,
+            usage=usage,
+            metadata=metadata or {},
+        )
+
+
+async def aresponses_create(
+    model: str,
+    input: str,
+    instructions: Optional[str] = None,
+    tools: Optional[List[Dict[str, Any]]] = None,
+    temperature: float = 1.0,
+    max_output_tokens: Optional[int] = None,
+    timeout: float = 600.0,
+    api_key: Optional[str] = None,
+    api_base: Optional[str] = None,
+    metadata: Optional[Dict[str, Any]] = None,
+    **kwargs
+) -> ResponseResult:
+    """
+    Async: Create a response using the Responses API.
+    
+    See responses_create() for full documentation.
+    """
+    import litellm
+    
+    call_kwargs = {
+        'model': model,
+        'input': input,
+        'temperature': temperature,
+        'timeout': timeout,
+    }
+    
+    if instructions:
+        call_kwargs['instructions'] = instructions
+    if tools:
+        call_kwargs['tools'] = tools
+    if max_output_tokens:
+        call_kwargs['max_output_tokens'] = max_output_tokens
+    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.aresponses(**call_kwargs)
+        
+        output = None
+        if hasattr(response, 'output'):
+            output = []
+            for item in response.output:
+                output.append({
+                    'type': getattr(item, 'type', 'message'),
+                    'content': getattr(item, 'content', None),
+                })
+        
+        usage = None
+        if hasattr(response, 'usage'):
+            usage = {
+                'input_tokens': getattr(response.usage, 'input_tokens', 0),
+                'output_tokens': getattr(response.usage, 'output_tokens', 0),
+                'total_tokens': getattr(response.usage, 'total_tokens', 0),
+            }
+        
+        return ResponseResult(
+            id=getattr(response, 'id', ''),
+            object=getattr(response, 'object', 'response'),
+            output=output,
+            status=getattr(response, 'status', 'completed'),
+            model=getattr(response, 'model', model),
+            usage=usage,
+            metadata=metadata or {},
+        )
+    except AttributeError:
+        messages = [{"role": "user", "content": input}]
+        if instructions:
+            messages.insert(0, {"role": "system", "content": instructions})
+        
+        response = await litellm.acompletion(
+            model=model,
+            messages=messages,
+            temperature=temperature,
+            max_tokens=max_output_tokens,
+            timeout=timeout,
+            api_key=api_key,
+            api_base=api_base,
+            **kwargs
+        )
+        
+        output = [{
+            'type': 'message',
+            'content': response.choices[0].message.content if response.choices else None,
+        }]
+        
+        usage = None
+        if hasattr(response, 'usage'):
+            usage = {
+                'input_tokens': getattr(response.usage, 'prompt_tokens', 0),
+                'output_tokens': getattr(response.usage, 'completion_tokens', 0),
+                'total_tokens': getattr(response.usage, 'total_tokens', 0),
+            }
+        
+        return ResponseResult(
+            id=getattr(response, 'id', ''),
+            object='response',
+            output=output,
+            status='completed',
+            model=model,
+            usage=usage,
+            metadata=metadata or {},
+        )

praisonai/capabilities/search.py

@@ -0,0 +1,109 @@
+"""
+Search Capabilities Module
+
+Provides search functionality.
+"""
+
+from dataclasses import dataclass, field
+from typing import Optional, Any, Dict, List
+
+
+@dataclass
+class SearchResult:
+    """Result from search operations."""
+    results: List[Dict[str, Any]]
+    query: str
+    total: Optional[int] = None
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+
+def search(
+    query: str,
+    sources: Optional[List[str]] = None,
+    max_results: int = 10,
+    timeout: float = 600.0,
+    api_key: Optional[str] = None,
+    api_base: Optional[str] = None,
+    metadata: Optional[Dict[str, Any]] = None,
+    **kwargs
+) -> SearchResult:
+    """
+    Perform a search query.
+    
+    Args:
+        query: Search query
+        sources: Optional list of sources to search
+        max_results: Maximum number of results
+        timeout: Request timeout in seconds
+        api_key: Optional API key override
+        api_base: Optional API base URL override
+        metadata: Optional metadata for tracing
+        
+    Returns:
+        SearchResult with search results
+        
+    Example:
+        >>> result = search("What is AI?")
+        >>> for r in result.results:
+        ...     print(r['title'], r['url'])
+    """
+    # Search can be implemented via various providers
+    # This is a placeholder that integrates with existing search tools
+    
+    results = []
+    
+    # Try to use web search if available
+    try:
+        from praisonaiagents.tools.duckduckgo_tools import duckduckgo_search
+        search_results = duckduckgo_search(query, max_results=max_results)
+        
+        if isinstance(search_results, list):
+            for item in search_results:
+                results.append({
+                    'title': item.get('title', ''),
+                    'url': item.get('href', item.get('url', '')),
+                    'snippet': item.get('body', item.get('snippet', '')),
+                })
+        elif isinstance(search_results, str):
+            results.append({
+                'title': 'Search Result',
+                'url': '',
+                'snippet': search_results,
+            })
+    except ImportError:
+        pass
+    
+    return SearchResult(
+        results=results,
+        query=query,
+        total=len(results),
+        metadata=metadata or {},
+    )
+
+
+async def asearch(
+    query: str,
+    sources: Optional[List[str]] = None,
+    max_results: int = 10,
+    timeout: float = 600.0,
+    api_key: Optional[str] = None,
+    api_base: Optional[str] = None,
+    metadata: Optional[Dict[str, Any]] = None,
+    **kwargs
+) -> SearchResult:
+    """
+    Async: Perform a search query.
+    
+    See search() for full documentation.
+    """
+    # For now, delegate to sync version
+    return search(
+        query=query,
+        sources=sources,
+        max_results=max_results,
+        timeout=timeout,
+        api_key=api_key,
+        api_base=api_base,
+        metadata=metadata,
+        **kwargs
+    )

praisonai/capabilities/skills.py

@@ -0,0 +1,133 @@
+"""
+Skills Capabilities Module
+
+Provides agent skills functionality.
+"""
+
+from dataclasses import dataclass, field
+from typing import Optional, Any, Dict, List
+
+
+@dataclass
+class SkillResult:
+    """Result from skill operations."""
+    name: str
+    description: Optional[str] = None
+    path: Optional[str] = None
+    instructions: Optional[str] = None
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+
+def skill_list(
+    skill_dirs: Optional[List[str]] = None,
+    include_defaults: bool = True,
+    metadata: Optional[Dict[str, Any]] = None,
+    **kwargs
+) -> List[SkillResult]:
+    """
+    List available skills.
+    
+    Args:
+        skill_dirs: Optional list of directories to scan
+        include_defaults: Whether to include default skill directories
+        metadata: Optional metadata for tracing
+        
+    Returns:
+        List of SkillResult objects
+        
+    Example:
+        >>> skills = skill_list()
+        >>> for skill in skills:
+        ...     print(skill.name)
+    """
+    try:
+        from praisonaiagents.skills import discover_skills
+        
+        skills = discover_skills(skill_dirs, include_defaults)
+        
+        results = []
+        for skill in skills:
+            results.append(SkillResult(
+                name=skill.name,
+                description=skill.description,
+                path=str(skill.path) if skill.path else None,
+                metadata=metadata or {},
+            ))
+        
+        return results
+    except ImportError:
+        return []
+
+
+async def askill_list(
+    skill_dirs: Optional[List[str]] = None,
+    include_defaults: bool = True,
+    metadata: Optional[Dict[str, Any]] = None,
+    **kwargs
+) -> List[SkillResult]:
+    """
+    Async: List available skills.
+    
+    See skill_list() for full documentation.
+    """
+    return skill_list(
+        skill_dirs=skill_dirs,
+        include_defaults=include_defaults,
+        metadata=metadata,
+        **kwargs
+    )
+
+
+def skill_load(
+    skill_name: str,
+    skill_dirs: Optional[List[str]] = None,
+    metadata: Optional[Dict[str, Any]] = None,
+    **kwargs
+) -> Optional[SkillResult]:
+    """
+    Load a skill by name.
+    
+    Args:
+        skill_name: Name of the skill to load
+        skill_dirs: Optional list of directories to scan
+        metadata: Optional metadata for tracing
+        
+    Returns:
+        SkillResult with skill details or None if not found
+    """
+    try:
+        from praisonaiagents.skills import load_skill
+        
+        skill = load_skill(skill_name, skill_dirs)
+        
+        if skill:
+            return SkillResult(
+                name=skill.name,
+                description=skill.description,
+                path=str(skill.path) if skill.path else None,
+                instructions=skill.instructions if hasattr(skill, 'instructions') else None,
+                metadata=metadata or {},
+            )
+        
+        return None
+    except ImportError:
+        return None
+
+
+async def askill_load(
+    skill_name: str,
+    skill_dirs: Optional[List[str]] = None,
+    metadata: Optional[Dict[str, Any]] = None,
+    **kwargs
+) -> Optional[SkillResult]:
+    """
+    Async: Load a skill by name.
+    
+    See skill_load() for full documentation.
+    """
+    return skill_load(
+        skill_name=skill_name,
+        skill_dirs=skill_dirs,
+        metadata=metadata,
+        **kwargs
+    )