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

mcp_agent/workflows/intent_classifier/intent_classifier_base.py

@@ -0,0 +1,120 @@
+from abc import ABC, abstractmethod
+from typing import Dict, List, Optional, TYPE_CHECKING
+from pydantic import BaseModel, Field
+
+if TYPE_CHECKING:
+    from mcp_agent.context import Context
+
+
+class Intent(BaseModel):
+    """A class that represents a single intent category"""
+
+    name: str
+    """The name of the intent"""
+
+    description: str | None = None
+    """A description of what this intent represents"""
+
+    examples: List[str] = Field(default_factory=list)
+    """Example phrases or requests that match this intent"""
+
+    metadata: Dict[str, str] = Field(default_factory=dict)
+    """Additional metadata about the intent that might be useful for classification"""
+
+
+class IntentClassificationResult(BaseModel):
+    """A class that represents the result of intent classification"""
+
+    intent: str
+    """The classified intent name"""
+
+    p_score: float | None = None
+    """
+    The probability score (i.e. 0->1) of the classification. 
+    This is optional and may only be provided if the classifier is probabilistic (e.g. a probabilistic binary classifier).
+    """
+
+    extracted_entities: Dict[str, str] = Field(default_factory=dict)
+    """Any entities or parameters extracted from the input request that are relevant to the intent"""
+
+
+class IntentClassifier(ABC):
+    """
+    Base class for intent classification. This can be implemented using different approaches
+    like LLMs, embedding models, traditional ML classification models, or rule-based systems.
+
+    When to use this:
+        - When you need to understand the user's intention before routing or processing
+        - When you want to extract structured information from natural language inputs
+        - When you need to handle multiple related but distinct types of requests
+
+    Examples:
+        - Classifying customer service requests (complaint, question, feedback)
+        - Understanding user commands in a chat interface
+        - Determining the type of analysis requested for a dataset
+    """
+
+    def __init__(
+        self, intents: List[Intent], context: Optional["Context"] = None, **kwargs
+    ):
+        super().__init__(context=context, **kwargs)
+        self.intents = {intent.name: intent for intent in intents}
+        self.initialized: bool = False
+
+        if not self.intents:
+            raise ValueError("At least one intent must be provided")
+
+    @abstractmethod
+    async def classify(
+        self, request: str, top_k: int = 1
+    ) -> List[IntentClassificationResult]:
+        """
+        Classify the input request into one or more intents.
+
+        Args:
+            request: The input text to classify
+            top_k: Maximum number of top intent matches to return. May return fewer.
+
+        Returns:
+            List of classification results, ordered by confidence
+        """
+
+    async def initialize(self):
+        """Initialize the classifier. Override this method if needed."""
+        self.initialized = True
+
+
+# Example
+# Define some intents
+# intents = [
+#     Intent(
+#         name="schedule_meeting",
+#         description="Schedule or set up a meeting or appointment",
+#         examples=[
+#             "Can you schedule a meeting with John?",
+#             "Set up a call for next week",
+#             "I need to arrange a meeting"
+#         ]
+#     ),
+#     Intent(
+#         name="check_calendar",
+#         description="Check calendar availability or existing appointments",
+#         examples=[
+#             "What meetings do I have today?",
+#             "Show me my calendar",
+#             "Am I free tomorrow afternoon?"
+#         ]
+#     )
+# ]
+
+# # Initialize with OpenAI embeddings
+# classifier = OpenAIEmbeddingIntentClassifier(intents=intents, model="text-embedding-3-small")
+
+# # Or use Cohere embeddings
+# classifier = OpenAIEmbeddingIntentClassifier(intents=intents, model="embed-multilingual-v3.0")
+
+# # Classify some text
+# results = await classifier.classify(
+#     request="Can you set up a meeting with Sarah for tomorrow?"
+#     top_k=3
+# )

mcp_agent/workflows/intent_classifier/intent_classifier_embedding.py

@@ -0,0 +1,134 @@
+from typing import List, Optional, TYPE_CHECKING
+
+from numpy import mean
+
+from mcp_agent.workflows.embedding.embedding_base import (
+    FloatArray,
+    EmbeddingModel,
+    compute_confidence,
+    compute_similarity_scores,
+)
+from mcp_agent.workflows.intent_classifier.intent_classifier_base import (
+    Intent,
+    IntentClassifier,
+    IntentClassificationResult,
+)
+
+if TYPE_CHECKING:
+    from mcp_agent.context import Context
+
+
+class EmbeddingIntent(Intent):
+    """An intent with embedding information"""
+
+    embedding: FloatArray | None = None
+    """Pre-computed embedding for this intent"""
+
+
+class EmbeddingIntentClassifier(IntentClassifier):
+    """
+    An intent classifier that uses embedding similarity for classification.
+    Supports different embedding models through the EmbeddingModel interface.
+
+    Features:
+    - Semantic similarity based classification
+    - Support for example-based learning
+    - Flexible embedding model support
+    - Multiple similarity computation strategies
+    """
+
+    def __init__(
+        self,
+        intents: List[Intent],
+        embedding_model: EmbeddingModel,
+        context: Optional["Context"] = None,
+        **kwargs,
+    ):
+        super().__init__(intents=intents, context=context, **kwargs)
+        self.embedding_model = embedding_model
+        self.initialized = False
+
+    @classmethod
+    async def create(
+        cls,
+        intents: List[Intent],
+        embedding_model: EmbeddingModel,
+    ) -> "EmbeddingIntentClassifier":
+        """
+        Factory method to create and initialize a classifier.
+        Use this instead of constructor since we need async initialization.
+        """
+        instance = cls(
+            intents=intents,
+            embedding_model=embedding_model,
+        )
+        await instance.initialize()
+        return instance
+
+    async def initialize(self):
+        """
+        Precompute embeddings for all intents by combining their
+        descriptions and examples
+        """
+        if self.initialized:
+            return
+
+        for intent in self.intents.values():
+            # Combine all text for a rich intent representation
+            intent_texts = [intent.name, intent.description] + intent.examples
+
+            # Get embeddings for all texts
+            embeddings = await self.embedding_model.embed(intent_texts)
+
+            # Use mean pooling to combine embeddings
+            embedding = mean(embeddings, axis=0)
+
+            # Create intents with embeddings
+            self.intents[intent.name] = EmbeddingIntent(
+                **intent,
+                embedding=embedding,
+            )
+
+        self.initialized = True
+
+    async def classify(
+        self, request: str, top_k: int = 1
+    ) -> List[IntentClassificationResult]:
+        """
+        Classify the input text into one or more intents
+
+        Args:
+            text: Input text to classify
+            top_k: Maximum number of top matches to return
+
+        Returns:
+            List of classification results, ordered by confidence
+        """
+        if not self.initialized:
+            await self.initialize()
+
+        # Get embedding for input
+        embeddings = await self.embedding_model.embed([request])
+        request_embedding = embeddings[0]  # Take first since we only embedded one text
+
+        results: List[IntentClassificationResult] = []
+        for intent_name, intent in self.intents.items():
+            if intent.embedding is None:
+                continue
+
+            similarity_scores = compute_similarity_scores(
+                request_embedding, intent.embedding
+            )
+
+            # Compute overall confidence score
+            confidence = compute_confidence(similarity_scores)
+
+            results.append(
+                IntentClassificationResult(
+                    intent=intent_name,
+                    p_score=confidence,
+                )
+            )
+
+        results.sort(key=lambda x: x.p_score, reverse=True)
+        return results[:top_k]

mcp_agent/workflows/intent_classifier/intent_classifier_embedding_cohere.py

@@ -0,0 +1,45 @@
+from typing import List, Optional, TYPE_CHECKING
+
+from mcp_agent.workflows.embedding.embedding_cohere import CohereEmbeddingModel
+from mcp_agent.workflows.intent_classifier.intent_classifier_base import Intent
+from mcp_agent.workflows.intent_classifier.intent_classifier_embedding import (
+    EmbeddingIntentClassifier,
+)
+
+if TYPE_CHECKING:
+    from mcp_agent.context import Context
+
+
+class CohereEmbeddingIntentClassifier(EmbeddingIntentClassifier):
+    """
+    An intent classifier that uses Cohere's embedding models for computing semantic simiarity based classifications.
+    """
+
+    def __init__(
+        self,
+        intents: List[Intent],
+        embedding_model: CohereEmbeddingModel | None = None,
+        context: Optional["Context"] = None,
+        **kwargs,
+    ):
+        embedding_model = embedding_model or CohereEmbeddingModel()
+        super().__init__(
+            embedding_model=embedding_model, intents=intents, context=context, **kwargs
+        )
+
+    @classmethod
+    async def create(
+        cls,
+        intents: List[Intent],
+        embedding_model: CohereEmbeddingModel | None = None,
+        context: Optional["Context"] = None,
+    ) -> "CohereEmbeddingIntentClassifier":
+        """
+        Factory method to create and initialize a classifier.
+        Use this instead of constructor since we need async initialization.
+        """
+        instance = cls(
+            intents=intents, embedding_model=embedding_model, context=context
+        )
+        await instance.initialize()
+        return instance

mcp_agent/workflows/intent_classifier/intent_classifier_embedding_openai.py

@@ -0,0 +1,45 @@
+from typing import List, Optional, TYPE_CHECKING
+
+from mcp_agent.workflows.embedding.embedding_openai import OpenAIEmbeddingModel
+from mcp_agent.workflows.intent_classifier.intent_classifier_base import Intent
+from mcp_agent.workflows.intent_classifier.intent_classifier_embedding import (
+    EmbeddingIntentClassifier,
+)
+
+if TYPE_CHECKING:
+    from mcp_agent.context import Context
+
+
+class OpenAIEmbeddingIntentClassifier(EmbeddingIntentClassifier):
+    """
+    An intent classifier that uses OpenAI's embedding models for computing semantic simiarity based classifications.
+    """
+
+    def __init__(
+        self,
+        intents: List[Intent],
+        embedding_model: OpenAIEmbeddingModel | None = None,
+        context: Optional["Context"] = None,
+        **kwargs,
+    ):
+        embedding_model = embedding_model or OpenAIEmbeddingModel()
+        super().__init__(
+            embedding_model=embedding_model, intents=intents, context=context, **kwargs
+        )
+
+    @classmethod
+    async def create(
+        cls,
+        intents: List[Intent],
+        embedding_model: OpenAIEmbeddingModel | None = None,
+        context: Optional["Context"] = None,
+    ) -> "OpenAIEmbeddingIntentClassifier":
+        """
+        Factory method to create and initialize a classifier.
+        Use this instead of constructor since we need async initialization.
+        """
+        instance = cls(
+            intents=intents, embedding_model=embedding_model, context=context
+        )
+        await instance.initialize()
+        return instance

mcp_agent/workflows/intent_classifier/intent_classifier_llm.py

@@ -0,0 +1,161 @@
+from typing import List, Literal, Optional, TYPE_CHECKING
+from pydantic import BaseModel
+
+from mcp_agent.workflows.llm.augmented_llm import AugmentedLLM
+from mcp_agent.workflows.intent_classifier.intent_classifier_base import (
+    Intent,
+    IntentClassifier,
+    IntentClassificationResult,
+)
+
+if TYPE_CHECKING:
+    from mcp_agent.context import Context
+
+DEFAULT_INTENT_CLASSIFICATION_INSTRUCTION = """
+You are a precise intent classifier that analyzes user requests to determine their intended action or purpose.
+Below are the available intents with their descriptions and examples:
+
+{context}
+
+Your task is to analyze the following request and determine the most likely intent(s). Consider:
+- How well the request matches the intent descriptions and examples
+- Any specific entities or parameters that should be extracted
+- The confidence level in the classification
+
+Request: {request}
+
+Respond in JSON format:
+{{
+    "classifications": [
+        {{
+            "intent": <intent name>,
+            "confidence": <float between 0 and 1>,
+            "extracted_entities": {{
+                "entity_name": "entity_value"
+            }},
+            "reasoning": <brief explanation>
+        }}
+    ]
+}}
+
+Return up to {top_k} most likely intents. Only include intents with reasonable confidence (>0.5).
+If no intents match well, return an empty list.
+"""
+
+
+class LLMIntentClassificationResult(IntentClassificationResult):
+    """The result of intent classification using an LLM."""
+
+    confidence: Literal["low", "medium", "high"]
+    """Confidence level of the classification"""
+
+    reasoning: str | None = None
+    """Optional explanation of why this intent was chosen"""
+
+
+class StructuredIntentResponse(BaseModel):
+    """The complete structured response from the LLM"""
+
+    classifications: List[LLMIntentClassificationResult]
+
+
+class LLMIntentClassifier(IntentClassifier):
+    """
+    An intent classifier that uses an LLM to determine the user's intent.
+    Particularly useful when you need:
+    - Flexible understanding of natural language
+    - Detailed reasoning about classifications
+    - Entity extraction alongside classification
+    """
+
+    def __init__(
+        self,
+        llm: AugmentedLLM,
+        intents: List[Intent],
+        classification_instruction: str | None = None,
+        context: Optional["Context"] = None,
+        **kwargs,
+    ):
+        super().__init__(intents=intents, context=context, **kwargs)
+        self.llm = llm
+        self.classification_instruction = classification_instruction
+
+    @classmethod
+    async def create(
+        cls,
+        llm: AugmentedLLM,
+        intents: List[Intent],
+        classification_instruction: str | None = None,
+    ) -> "LLMIntentClassifier":
+        """
+        Factory method to create and initialize a classifier.
+        Use this instead of constructor since we need async initialization.
+        """
+        instance = cls(
+            llm=llm,
+            intents=intents,
+            classification_instruction=classification_instruction,
+        )
+        await instance.initialize()
+        return instance
+
+    async def classify(
+        self, request: str, top_k: int = 1
+    ) -> List[LLMIntentClassificationResult]:
+        if not self.initialized:
+            self.initialize()
+
+        classification_instruction = (
+            self.classification_instruction or DEFAULT_INTENT_CLASSIFICATION_INSTRUCTION
+        )
+
+        # Generate the context with intent descriptions and examples
+        context = self._generate_context()
+
+        # Format the prompt with all the necessary information
+        prompt = classification_instruction.format(
+            context=context, request=request, top_k=top_k
+        )
+
+        # Get classification from LLM
+        response = await self.llm.generate_structured(
+            message=prompt, response_model=StructuredIntentResponse
+        )
+
+        if not response or not response.classifications:
+            return []
+
+        results = []
+        for classification in response.classifications:
+            intent = self.intents.get(classification.intent)
+            if not intent:
+                # Skip invalid categories
+                # TODO: saqadri - log or raise an error
+                continue
+
+            results.append(classification)
+
+        return results[:top_k]
+
+    def _generate_context(self) -> str:
+        """Generate a formatted context string describing all intents"""
+        context_parts = []
+
+        for idx, intent in enumerate(self.intents.values(), 1):
+            description = (
+                f"{idx}. Intent: {intent.name}\nDescription: {intent.description}"
+            )
+
+            if intent.examples:
+                examples = "\n".join(f"- {example}" for example in intent.examples)
+                description += f"\nExamples:\n{examples}"
+
+            if intent.metadata:
+                metadata = "\n".join(
+                    f"- {key}: {value}" for key, value in intent.metadata.items()
+                )
+                description += f"\nAdditional Information:\n{metadata}"
+
+            context_parts.append(description)
+
+        return "\n\n".join(context_parts)

mcp_agent/workflows/intent_classifier/intent_classifier_llm_anthropic.py

@@ -0,0 +1,60 @@
+from typing import List, Optional, TYPE_CHECKING
+
+from mcp_agent.workflows.llm.augmented_llm_anthropic import AnthropicAugmentedLLM
+from mcp_agent.workflows.intent_classifier.intent_classifier_base import Intent
+from mcp_agent.workflows.intent_classifier.intent_classifier_llm import (
+    LLMIntentClassifier,
+)
+
+if TYPE_CHECKING:
+    from mcp_agent.context import Context
+
+CLASSIFIER_SYSTEM_INSTRUCTION = """
+You are a precise intent classifier that analyzes input requests to determine their intended action or purpose.
+You are provided with a request and a list of intents to choose from.
+You can choose one or more intents, or choose none if no intent is appropriate.
+"""
+
+
+class AnthropicLLMIntentClassifier(LLMIntentClassifier):
+    """
+    An LLM router that uses an Anthropic model to make routing decisions.
+    """
+
+    def __init__(
+        self,
+        intents: List[Intent],
+        classification_instruction: str | None = None,
+        context: Optional["Context"] = None,
+        **kwargs,
+    ):
+        anthropic_llm = AnthropicAugmentedLLM(
+            instruction=CLASSIFIER_SYSTEM_INSTRUCTION, context=context
+        )
+
+        super().__init__(
+            llm=anthropic_llm,
+            intents=intents,
+            classification_instruction=classification_instruction,
+            context=context,
+            **kwargs,
+        )
+
+    @classmethod
+    async def create(
+        cls,
+        intents: List[Intent],
+        classification_instruction: str | None = None,
+        context: Optional["Context"] = None,
+    ) -> "AnthropicLLMIntentClassifier":
+        """
+        Factory method to create and initialize a classifier.
+        Use this instead of constructor since we need async initialization.
+        """
+        instance = cls(
+            intents=intents,
+            classification_instruction=classification_instruction,
+            context=context,
+        )
+        await instance.initialize()
+        return instance

mcp_agent/workflows/intent_classifier/intent_classifier_llm_openai.py

@@ -0,0 +1,60 @@
+from typing import List, Optional, TYPE_CHECKING
+
+from mcp_agent.workflows.llm.augmented_llm_openai import OpenAIAugmentedLLM
+from mcp_agent.workflows.intent_classifier.intent_classifier_base import Intent
+from mcp_agent.workflows.intent_classifier.intent_classifier_llm import (
+    LLMIntentClassifier,
+)
+
+if TYPE_CHECKING:
+    from mcp_agent.context import Context
+
+CLASSIFIER_SYSTEM_INSTRUCTION = """
+You are a precise intent classifier that analyzes input requests to determine their intended action or purpose.
+You are provided with a request and a list of intents to choose from.
+You can choose one or more intents, or choose none if no intent is appropriate.
+"""
+
+
+class OpenAILLMIntentClassifier(LLMIntentClassifier):
+    """
+    An LLM router that uses an OpenAI model to make routing decisions.
+    """
+
+    def __init__(
+        self,
+        intents: List[Intent],
+        classification_instruction: str | None = None,
+        context: Optional["Context"] = None,
+        **kwargs,
+    ):
+        openai_llm = OpenAIAugmentedLLM(
+            instruction=CLASSIFIER_SYSTEM_INSTRUCTION, context=context
+        )
+
+        super().__init__(
+            llm=openai_llm,
+            intents=intents,
+            classification_instruction=classification_instruction,
+            context=context,
+            **kwargs,
+        )
+
+    @classmethod
+    async def create(
+        cls,
+        intents: List[Intent],
+        classification_instruction: str | None = None,
+        context: Optional["Context"] = None,
+    ) -> "OpenAILLMIntentClassifier":
+        """
+        Factory method to create and initialize a classifier.
+        Use this instead of constructor since we need async initialization.
+        """
+        instance = cls(
+            intents=intents,
+            classification_instruction=classification_instruction,
+            context=context,
+        )
+        await instance.initialize()
+        return instance