fast-agent-mcp 0.0.7__py3-none-any.whl

mcp_agent/resources/examples/mcp_researcher/main.py

@@ -0,0 +1,38 @@
+import asyncio
+
+from mcp_agent.core.fastagent import FastAgent
+# from rich import print
+
+agents = FastAgent(name="Researcher")
+
+
+@agents.agent(
+    "Researcher",
+    instruction="""
+You are a research assistant, with access to internet search (via Brave),
+website fetch, a python interpreter (you can install packages with uv) and a filesystem.
+Use the current working directory to save and create files with both the Interpreter and Filesystem tools.
+The interpreter has numpy, pandas, matplotlib and seaborn already installed
+    """,
+    servers=["brave", "interpreter", "filesystem", "fetch"],
+)
+async def main():
+    research_prompt = """
+Produce an investment report for the company Eutelsat. The final report should be saved in the filesystem in markdown format, and
+contain at least the following: 
+1 - A brief description of the company
+2 - Current financial position (find data, create and incorporate charts)
+3 - A PESTLE analysis
+4 - An investment thesis for the next 3 years. Include both 'buy side' and 'sell side' arguments, and a final 
+summary and recommendation.
+Todays date is 15 February 2025. Include the main data sources consulted in presenting the report."""  # noqa: F841
+
+    async with agents.run() as agent:
+        await agent.prompt()
+
+        # await agent.prompt(default="STOP")
+        #        await agent.prompt(default=research_prompt)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

mcp_agent/telemetry/usage_tracking.py

@@ -0,0 +1,18 @@
+import logging
+from mcp_agent.config import get_settings
+
+logger = logging.getLogger(__name__)
+
+
+def send_usage_data():
+    config = get_settings()
+    if not config.usage_telemetry.enabled:
+        logger.info("Usage tracking is disabled")
+        return
+
+    # TODO: saqadri - implement usage tracking
+    # data = {"installation_id": str(uuid.uuid4()), "version": "0.1.0"}
+    # try:
+    #     requests.post("https://telemetry.example.com/usage", json=data, timeout=2)
+    # except:
+    #     pass

mcp_agent/workflows/embedding/embedding_base.py

@@ -0,0 +1,61 @@
+from abc import ABC, abstractmethod
+from typing import Dict, List
+
+from numpy import float32
+from numpy.typing import NDArray
+from sklearn.metrics.pairwise import cosine_similarity
+
+from mcp_agent.context_dependent import ContextDependent
+
+
+FloatArray = NDArray[float32]
+
+
+class EmbeddingModel(ABC, ContextDependent):
+    """Abstract interface for embedding models"""
+
+    @abstractmethod
+    async def embed(self, data: List[str]) -> FloatArray:
+        """
+        Generate embeddings for a list of messages
+
+        Args:
+            data: List of text strings to embed
+
+        Returns:
+            Array of embeddings, shape (len(texts), embedding_dim)
+        """
+
+    @property
+    @abstractmethod
+    def embedding_dim(self) -> int:
+        """Return the dimensionality of the embeddings"""
+
+
+def compute_similarity_scores(
+    embedding_a: FloatArray, embedding_b: FloatArray
+) -> Dict[str, float]:
+    """
+    Compute different similarity metrics between embeddings
+    """
+    # Reshape for sklearn's cosine_similarity
+    a_emb = embedding_a.reshape(1, -1)
+    b_emb = embedding_b.reshape(1, -1)
+
+    cosine_sim = float(cosine_similarity(a_emb, b_emb)[0, 0])
+
+    # Could add other similarity metrics here
+    return {
+        "cosine": cosine_sim,
+        # "euclidean": float(euclidean_similarity),
+        # "dot_product": float(dot_product)
+    }
+
+
+def compute_confidence(similarity_scores: Dict[str, float]) -> float:
+    """
+    Compute overall confidence score from individual similarity metrics
+    """
+    # For now, just use cosine similarity as confidence
+    # Could implement more sophisticated combination of scores
+    return similarity_scores["cosine"]

mcp_agent/workflows/embedding/embedding_cohere.py

@@ -0,0 +1,49 @@
+from typing import List, Optional, TYPE_CHECKING
+
+from cohere import Client
+from numpy import array, float32
+
+from mcp_agent.workflows.embedding.embedding_base import EmbeddingModel, FloatArray
+
+if TYPE_CHECKING:
+    from mcp_agent.context import Context
+
+
+class CohereEmbeddingModel(EmbeddingModel):
+    """Cohere embedding model implementation"""
+
+    def __init__(
+        self,
+        model: str = "embed-multilingual-v3.0",
+        context: Optional["Context"] = None,
+        **kwargs,
+    ):
+        super().__init__(context=context, **kwargs)
+        self.client = Client(api_key=self.context.config.cohere.api_key)
+        self.model = model
+        # Cache the dimension since it's fixed per model
+        # https://docs.cohere.com/v2/docs/cohere-embed
+        self._embedding_dim = {
+            "embed-english-v2.0": 4096,
+            "embed-english-light-v2.0": 1024,
+            "embed-english-v3.0": 1024,
+            "embed-english-light-v3.0": 384,
+            "embed-multilingual-v2.0": 768,
+            "embed-multilingual-v3.0": 1024,
+            "embed-multilingual-light-v3.0": 384,
+        }[model]
+
+    async def embed(self, data: List[str]) -> FloatArray:
+        response = self.client.embed(
+            texts=data,
+            model=self.model,
+            input_type="classification",
+            embedding_types=["float"],
+        )
+
+        embeddings = array(response.embeddings, dtype=float32)
+        return embeddings
+
+    @property
+    def embedding_dim(self) -> int:
+        return self._embedding_dim

mcp_agent/workflows/embedding/embedding_openai.py

@@ -0,0 +1,46 @@
+from typing import List, Optional, TYPE_CHECKING
+
+from numpy import array, float32, stack
+from openai import OpenAI
+
+from mcp_agent.workflows.embedding.embedding_base import EmbeddingModel, FloatArray
+
+if TYPE_CHECKING:
+    from mcp_agent.context import Context
+
+
+class OpenAIEmbeddingModel(EmbeddingModel):
+    """OpenAI embedding model implementation"""
+
+    def __init__(
+        self, model: str = "text-embedding-3-small", context: Optional["Context"] = None
+    ):
+        super().__init__(context=context)
+        self.client = OpenAI(api_key=self.context.config.openai.api_key)
+        self.model = model
+        # Cache the dimension since it's fixed per model
+        self._embedding_dim = {
+            "text-embedding-3-small": 1536,
+            "text-embedding-3-large": 3072,
+        }[model]
+
+    async def embed(self, data: List[str]) -> FloatArray:
+        response = self.client.embeddings.create(
+            model=self.model, input=data, encoding_format="float"
+        )
+
+        # Sort the embeddings by their index to ensure correct order
+        sorted_embeddings = sorted(response.data, key=lambda x: x["index"])
+
+        # Stack all embeddings into a single array
+        embeddings = stack(
+            [
+                array(embedding["embedding"], dtype=float32)
+                for embedding in sorted_embeddings
+            ]
+        )
+        return embeddings
+
+    @property
+    def embedding_dim(self) -> int:
+        return self._embedding_dim

mcp_agent/workflows/evaluator_optimizer/evaluator_optimizer.py

@@ -0,0 +1,359 @@
+import contextlib
+from enum import Enum
+from typing import Callable, List, Optional, Type, TYPE_CHECKING
+from pydantic import BaseModel, Field
+
+from mcp_agent.workflows.llm.augmented_llm import (
+    AugmentedLLM,
+    MessageParamT,
+    MessageT,
+    ModelT,
+    RequestParams,
+)
+from mcp_agent.agents.agent import Agent
+from mcp_agent.logging.logger import get_logger
+
+if TYPE_CHECKING:
+    from mcp_agent.context import Context
+
+logger = get_logger(__name__)
+
+
+class QualityRating(str, Enum):
+    """Enum for evaluation quality ratings"""
+
+    POOR = 0  # Major improvements needed
+    FAIR = 1  # Several improvements needed
+    GOOD = 2  # Minor improvements possible
+    EXCELLENT = 3  # No improvements needed
+
+
+class EvaluationResult(BaseModel):
+    """Model representing the evaluation result from the evaluator LLM"""
+
+    rating: QualityRating = Field(description="Quality rating of the response")
+    feedback: str = Field(
+        description="Specific feedback and suggestions for improvement"
+    )
+    needs_improvement: bool = Field(
+        description="Whether the output needs further improvement"
+    )
+    focus_areas: List[str] = Field(
+        default_factory=list, description="Specific areas to focus on in next iteration"
+    )
+
+
+class EvaluatorOptimizerLLM(AugmentedLLM[MessageParamT, MessageT]):
+    """
+    Implementation of the evaluator-optimizer workflow where one LLM generates responses
+    while another provides evaluation and feedback in a refinement loop.
+
+    This can be used either:
+    1. As a standalone workflow with its own optimizer agent
+    2. As a wrapper around another workflow (Orchestrator, Router, ParallelLLM) to add
+       evaluation and refinement capabilities
+
+    When to use this workflow:
+    - When you have clear evaluation criteria and iterative refinement provides value
+    - When LLM responses improve with articulated feedback
+    - When the task benefits from focused iteration on specific aspects
+
+    Examples:
+    - Literary translation with "expert" refinement
+    - Complex search tasks needing multiple rounds
+    - Document writing requiring multiple revisions
+    """
+
+    def __init__(
+        self,
+        optimizer: Agent | AugmentedLLM,
+        evaluator: str | Agent | AugmentedLLM,
+        min_rating: QualityRating = QualityRating.GOOD,
+        max_refinements: int = 3,
+        llm_factory: Callable[[Agent], AugmentedLLM] | None = None,  # TODO: Remove legacy - factory should only be needed for str evaluator
+        context: Optional["Context"] = None,
+    ):
+        """
+        Initialize the evaluator-optimizer workflow.
+
+        Args:
+            optimizer: The agent/LLM/workflow that generates responses. Can be:
+                     - An Agent that will be converted to an AugmentedLLM
+                     - An AugmentedLLM instance
+                     - An Orchestrator/Router/ParallelLLM workflow
+            evaluator_agent: The agent/LLM that evaluates responses
+            evaluation_criteria: Criteria for the evaluator to assess responses
+            min_rating: Minimum acceptable quality rating
+            max_refinements: Maximum refinement iterations
+            llm_factory: Optional factory to create LLMs from agents
+        """
+        super().__init__(context=context)
+
+        # Set up the optimizer
+        self.name = optimizer.name
+        self.llm_factory = llm_factory
+        self.optimizer = optimizer
+        self.evaluator = evaluator
+
+        # TODO: Remove legacy - optimizer should always be an AugmentedLLM, no conversion needed
+        if isinstance(optimizer, Agent):
+            if not llm_factory:
+                raise ValueError("llm_factory is required when using an Agent")
+
+            # Only create new LLM if agent doesn't have one
+            if hasattr(optimizer, "_llm") and optimizer._llm:
+                self.optimizer_llm = optimizer._llm
+            else:
+                self.optimizer_llm = llm_factory(agent=optimizer)
+            
+            self.aggregator = optimizer
+            self.instruction = (
+                optimizer.instruction
+                if isinstance(optimizer.instruction, str)
+                else None
+            )
+
+        elif isinstance(optimizer, AugmentedLLM):
+            self.optimizer_llm = optimizer
+            self.aggregator = optimizer.aggregator
+            self.instruction = optimizer.instruction
+
+        else:
+            raise ValueError(f"Unsupported optimizer type: {type(optimizer)}")
+
+        self.history = self.optimizer_llm.history
+
+        # Set up the evaluator
+        if isinstance(evaluator, AugmentedLLM):
+            self.evaluator_llm = evaluator
+        # TODO: Remove legacy - evaluator should be either AugmentedLLM or str
+        elif isinstance(evaluator, Agent):
+            if not llm_factory:
+                raise ValueError(
+                    "llm_factory is required when using an Agent evaluator"
+                )
+
+            # Only create new LLM if agent doesn't have one
+            if hasattr(evaluator, "_llm") and evaluator._llm:
+                self.evaluator_llm = evaluator._llm
+            else:
+                self.evaluator_llm = llm_factory(agent=evaluator)
+        elif isinstance(evaluator, str):
+            # If a string is passed as the evaluator, we use it as the evaluation criteria
+            # and create an evaluator agent with that instruction
+            if not llm_factory:
+                raise ValueError(
+                    "llm_factory is required when using a string evaluator"
+                )
+
+            self.evaluator_llm = llm_factory(
+                agent=Agent(name="Evaluator", instruction=evaluator)
+            )
+        else:
+            raise ValueError(f"Unsupported evaluator type: {type(evaluator)}")
+
+        self.min_rating = min_rating
+        self.max_refinements = max_refinements
+
+        # Track iteration history
+        self.refinement_history = []
+
+    async def generate(
+        self,
+        message: str | MessageParamT | List[MessageParamT],
+        request_params: RequestParams | None = None,
+    ) -> List[MessageT]:
+        """Generate an optimized response through evaluation-guided refinement"""
+        refinement_count = 0
+        response = None
+        best_response = None
+        best_rating = QualityRating.POOR
+        self.refinement_history = []
+
+        # Initial generation
+        async with contextlib.AsyncExitStack() as stack:
+            if isinstance(self.optimizer, Agent):
+                await stack.enter_async_context(self.optimizer)
+            response = await self.optimizer_llm.generate(
+                message=message,
+                request_params=request_params,
+            )
+
+        best_response = response
+
+        while refinement_count < self.max_refinements:
+            logger.debug("Optimizer result:", data=response)
+
+            # Evaluate current response
+            eval_prompt = self._build_eval_prompt(
+                original_request=str(message),
+                current_response="\n".join(str(r) for r in response)
+                if isinstance(response, list)
+                else str(response),
+                iteration=refinement_count,
+            )
+
+            evaluation_result = None
+            async with contextlib.AsyncExitStack() as stack:
+                if isinstance(self.evaluator, Agent):
+                    await stack.enter_async_context(self.evaluator)
+
+                evaluation_result = await self.evaluator_llm.generate_structured(
+                    message=eval_prompt,
+                    response_model=EvaluationResult,
+                    request_params=request_params,
+                )
+
+            # Track iteration
+            self.refinement_history.append(
+                {
+                    "attempt": refinement_count + 1,
+                    "response": response,
+                    "evaluation_result": evaluation_result,
+                }
+            )
+
+            logger.debug("Evaluator result:", data=evaluation_result)
+
+            # Track best response (using enum ordering)
+            if evaluation_result.rating.value > best_rating.value:
+                best_rating = evaluation_result.rating
+                best_response = response
+                logger.debug(
+                    "New best response:",
+                    data={"rating": best_rating, "response": best_response},
+                )
+
+            # Check if we've reached acceptable quality
+            if (
+                evaluation_result.rating.value >= self.min_rating.value
+                or not evaluation_result.needs_improvement
+            ):
+                logger.debug(
+                    f"Acceptable quality {evaluation_result.rating.value} reached",
+                    data={
+                        "rating": evaluation_result.rating.value,
+                        "needs_improvement": evaluation_result.needs_improvement,
+                        "min_rating": self.min_rating.value,
+                    },
+                )
+                break
+
+            # Generate refined response
+            refinement_prompt = self._build_refinement_prompt(
+                original_request=str(message),
+                current_response="\n".join(str(r) for r in response)
+                if isinstance(response, list)
+                else str(response),
+                feedback=evaluation_result,
+                iteration=refinement_count,
+            )
+
+            async with contextlib.AsyncExitStack() as stack:
+                if isinstance(self.optimizer, Agent):
+                    await stack.enter_async_context(self.optimizer)
+
+                response = await self.optimizer_llm.generate(
+                    message=refinement_prompt,
+                    request_params=request_params,
+                )
+
+            refinement_count += 1
+
+        return best_response
+
+    async def generate_str(
+        self,
+        message: str | MessageParamT | List[MessageParamT],
+        request_params: RequestParams | None = None,
+    ) -> str:
+        """Generate an optimized response and return it as a string"""
+        response = await self.generate(
+            message=message,
+            request_params=request_params,
+        )
+
+        # Handle case where response is a single message
+        if not isinstance(response, list):
+            return str(response)
+            
+        # Convert all messages to strings, handling different message types
+        result_strings = []
+        for r in response:
+            if hasattr(r, 'text'):
+                result_strings.append(r.text)
+            elif hasattr(r, 'content'):
+                # Handle ToolUseBlock and similar
+                if isinstance(r.content, list):
+                    # Typically content is a list of blocks
+                    result_strings.extend(str(block) for block in r.content)
+                else:
+                    result_strings.append(str(r.content))
+            else:
+                # Fallback to string representation
+                result_strings.append(str(r))
+                
+        return "\n".join(result_strings)
+
+    async def generate_structured(
+        self,
+        message: str | MessageParamT | List[MessageParamT],
+        response_model: Type[ModelT],
+        request_params: RequestParams | None = None,
+    ) -> ModelT:
+        """Generate an optimized structured response"""
+        response_str = await self.generate_str(
+            message=message, request_params=request_params
+        )
+
+        return await self.optimizer.generate_structured(
+            message=response_str,
+            response_model=response_model,
+            request_params=request_params,
+        )
+
+    def _build_eval_prompt(
+        self, original_request: str, current_response: str, iteration: int
+    ) -> str:
+        """Build the evaluation prompt for the evaluator"""
+        return f"""
+        Evaluate the following response based on these criteria:
+        {self.evaluator.instruction}
+
+        Original Request: {original_request}
+        Current Response (Iteration {iteration + 1}): {current_response}
+
+        Provide your evaluation as a structured response with:
+        1. A quality rating (EXCELLENT, GOOD, FAIR, or POOR)
+        2. Specific feedback and suggestions
+        3. Whether improvement is needed (true/false)
+        4. Focus areas for improvement
+
+        Rate as EXCELLENT only if no improvements are needed.
+        Rate as GOOD if only minor improvements are possible.
+        Rate as FAIR if several improvements are needed.
+        Rate as POOR if major improvements are needed.
+        """
+
+    def _build_refinement_prompt(
+        self,
+        original_request: str,
+        current_response: str,
+        feedback: EvaluationResult,
+        iteration: int,
+    ) -> str:
+        """Build the refinement prompt for the optimizer"""
+        return f"""
+        Improve your previous response based on the evaluation feedback.
+        
+        Original Request: {original_request}
+        
+        Previous Response (Iteration {iteration + 1}): 
+        {current_response}
+        
+        Quality Rating: {feedback.rating}
+        Feedback: {feedback.feedback}
+        Areas to Focus On: {", ".join(feedback.focus_areas)}
+        
+        Generate an improved version addressing the feedback while maintaining accuracy and relevance.
+        """