Squashed 'packages/tools/' content from commit 78317b9c

git-subtree-dir: packages/tools
git-subtree-split: 78317b9c127f18bd040c1d77e3c0840cdc9a5b38

crewai_tools/tools/contextualai_rerank_tool/README.md

@@ -0,0 +1,72 @@
+# ContextualAIRerankTool
+
+## Description
+This tool is designed to integrate Contextual AI's enterprise-grade instruction-following reranker with CrewAI, enabling you to intelligently reorder documents based on relevance and custom criteria. Use this tool to enhance search result quality and document retrieval for RAG systems using Contextual AI's reranking models that understand context and follow specific instructions for optimal document ordering.
+
+## Installation
+To incorporate this tool into your project, follow the installation instructions below:
+
+```shell
+pip install 'crewai[tools]' contextual-client
+```
+
+**Note**: You'll need a Contextual AI API key. Sign up at [app.contextual.ai](https://app.contextual.ai) to get your free API key.
+
+## Example
+
+```python
+from crewai_tools import ContextualAIRerankTool
+
+tool = ContextualAIRerankTool(api_key="your_api_key_here")
+
+result = tool._run(
+    query="financial performance and revenue metrics",
+    documents=[
+        "Q1 report content with revenue data", 
+        "Q2 report content with growth metrics", 
+        "News article about market trends"
+    ],
+    instruction="Prioritize documents with specific financial metrics and quantitative data"
+)
+print(result)
+```
+
+The result will contain the document ranking. For example: 
+```
+Rerank Result:
+{
+  "results": [
+    {
+      "index": 1,
+      "relevance_score": 0.88227631
+    },
+    {
+      "index": 0,
+      "relevance_score": 0.61159354
+    },
+    {
+      "index": 2,
+      "relevance_score": 0.28579462
+    }
+  ]
+}
+```
+
+## Parameters
+- `api_key`: Your Contextual AI API key
+- `query`: Search query for reranking
+- `documents`: List of document texts to rerank
+- `instruction`: Optional reranking instruction for custom criteria
+- `metadata`: Optional metadata for each document
+- `model`: Reranker model (default: "ctxl-rerank-en-v1-instruct")
+
+## Key Features
+- **Instruction-Following Reranking**: Follows custom instructions for domain-specific document ordering
+- **Metadata Integration**: Incorporates document metadata for enhanced ranking decisions
+
+## Use Cases
+- Improve search result relevance in document collections
+- Reorder documents by custom business criteria (recency, authority, relevance)
+- Filter and prioritize documents for research and analysis workflows
+
+For more detailed information about Contextual AI's capabilities, visit the [official documentation](https://docs.contextual.ai).

crewai_tools/tools/contextualai_rerank_tool/contextual_rerank_tool.py

@@ -0,0 +1,68 @@
+from typing import Any, Optional, Type, List
+from crewai.tools import BaseTool
+from pydantic import BaseModel, Field
+
+
+class ContextualAIRerankSchema(BaseModel):
+    """Schema for contextual rerank tool."""
+    query: str = Field(..., description="The search query to rerank documents against")
+    documents: List[str] = Field(..., description="List of document texts to rerank")
+    instruction: Optional[str] = Field(default=None, description="Optional instruction for reranking behavior")
+    metadata: Optional[List[str]] = Field(default=None, description="Optional metadata for each document")
+    model: str = Field(default="ctxl-rerank-en-v1-instruct", description="Reranker model to use")
+
+
+class ContextualAIRerankTool(BaseTool):
+    """Tool to rerank documents using Contextual AI's instruction-following reranker."""
+    
+    name: str = "Contextual AI Document Reranker"
+    description: str = "Rerank documents using Contextual AI's instruction-following reranker"
+    args_schema: Type[BaseModel] = ContextualAIRerankSchema
+    
+    api_key: str
+    package_dependencies: List[str] = ["contextual-client"]
+
+    def _run(
+        self,
+        query: str,
+        documents: List[str],
+        instruction: Optional[str] = None,
+        metadata: Optional[List[str]] = None,
+        model: str = "ctxl-rerank-en-v1-instruct"
+    ) -> str:
+        """Rerank documents using Contextual AI's instruction-following reranker."""
+        try:
+            import requests
+            import json
+
+            base_url = "https://api.contextual.ai/v1"
+            headers = {
+                "accept": "application/json",
+                "content-type": "application/json",
+                "authorization": f"Bearer {self.api_key}"
+            }
+
+            payload = {
+                "query": query,
+                "documents": documents,
+                "model": model
+            }
+
+            if instruction:
+                payload["instruction"] = instruction
+
+            if metadata:
+                if len(metadata) != len(documents):
+                    raise ValueError("Metadata list must have the same length as documents list")
+                payload["metadata"] = metadata
+
+            rerank_url = f"{base_url}/rerank"
+            result = requests.post(rerank_url, json=payload, headers=headers)
+
+            if result.status_code != 200:
+                raise RuntimeError(f"Reranker API returned status {result.status_code}: {result.text}")
+
+            return json.dumps(result.json(), indent=2)
+
+        except Exception as e:
+            return f"Failed to rerank documents: {str(e)}"