open-swarm 0.1.1743070217__py3-none-any.whl

swarm/tool_executor.py

@@ -0,0 +1,239 @@
+"""
+Tool execution utilities for the Swarm framework.
+Handles invoking agent functions/tools based on LLM requests.
+"""
+
+import json
+import logging
+import inspect # To check for awaitables
+from typing import List, Dict, Any, Optional, Union
+
+# Import necessary types from the Swarm framework
+from .types import (
+    ChatCompletionMessageToolCall,
+    Agent,
+    AgentFunction, # Type hint for functions/tools
+    Response, # Structure for returning results of multiple tool calls
+    Result # Structure for returning result of a single tool call
+)
+# Utility to convert function signatures to JSON schema (if needed, though less common now with direct calls)
+# from .util import function_to_json # Commented out if not used directly here
+
+# Configure module-level logging
+logger = logging.getLogger(__name__)
+# logger.setLevel(logging.DEBUG) # Uncomment for verbose logging
+if not logger.handlers:
+    stream_handler = logging.StreamHandler()
+    formatter = logging.Formatter("[%(levelname)s] %(asctime)s - %(name)s:%(lineno)d - %(message)s")
+    stream_handler.setFormatter(formatter)
+    logger.addHandler(stream_handler)
+
+# Standard name used for injecting context variables into tool calls
+__CTX_VARS_NAME__ = "context_variables"
+
+
+def handle_function_result(result: Any, debug: bool) -> Result:
+    """
+    Process the raw result returned by an agent function/tool into a standardized Result object.
+    Handles agent handoffs if the result is an Agent instance.
+
+    Args:
+        result: The raw return value from the executed function/tool.
+        debug: If True, log detailed information about the result processing.
+
+    Returns:
+        Result: A standardized Result object containing the processed value,
+                potential agent handoff, and context variable updates.
+
+    Raises:
+        TypeError: If the raw result cannot be cast to a string for the Result value.
+    """
+    if debug:
+        # Log raw result type and a preview (truncated for brevity)
+        try:
+            result_preview = str(result)[:100] + ('...' if len(str(result)) > 100 else '')
+        except Exception:
+            result_preview = "[Could not convert result to string for preview]"
+        logger.debug(f"Processing function result. Type: {type(result)}, Preview: {result_preview}")
+
+    # Check if the result is already a Result object
+    if isinstance(result, Result):
+        if debug: logger.debug("Result is already a Result object. Returning as is.")
+        return result
+    # Check if the result indicates an agent handoff
+    elif isinstance(result, Agent):
+        agent_name = getattr(result, 'name', 'UnnamedAgent')
+        if debug: logger.debug(f"Result is an Agent handoff to: '{agent_name}'")
+        # Create a Result object indicating the handoff
+        # The 'value' might represent the confirmation or status of the handoff itself
+        return Result(value=json.dumps({"status": f"Handoff to agent {agent_name} initiated."}), agent=result)
+    # Handle other types (attempt to serialize to string)
+    else:
+        try:
+            # Convert the result to a JSON string if possible, otherwise just stringify
+            # JSON is generally preferred for structured tool responses
+            if isinstance(result, (dict, list, tuple)):
+                 result_str = json.dumps(result)
+            else:
+                 result_str = str(result)
+
+            if debug: logger.debug(f"Converted result to string/JSON: {result_str[:100]}{'...' if len(result_str) > 100 else ''}")
+            # Return a Result object with the stringified value
+            return Result(value=result_str)
+        except (TypeError, ValueError) as e:
+            logger.error(f"Failed to serialize or cast function result to string/JSON: {e}", exc_info=debug)
+            # Raise a TypeError if conversion fails, indicating an issue with the tool's return type
+            raise TypeError(f"Tool function returned a result of type {type(result)} that could not be serialized to string/JSON: {result}") from e
+
+
+async def handle_tool_calls(
+    tool_calls: List[ChatCompletionMessageToolCall], # Expect list of Pydantic models
+    functions: List[AgentFunction], # Available functions/tools for the agent
+    context_variables: dict, # Current context
+    debug: bool # Debug logging flag
+) -> Response:
+    """
+    Execute a list of tool calls requested by the LLM and aggregate their results.
+
+    Args:
+        tool_calls: A list of ChatCompletionMessageToolCall objects requested by the LLM.
+        functions: A list of available functions/tools (callables or dicts) for the current agent.
+        context_variables: A dictionary containing the current context variables.
+        debug: If True, enable detailed debugging logs.
+
+    Returns:
+        Response: An object containing a list of messages (tool results) to be added
+                  to the conversation history, the potentially changed agent (due to handoff),
+                  and any updates to context variables from the tool calls.
+    """
+    # Basic validation of input
+    if not tool_calls or not isinstance(tool_calls, list):
+        logger.debug("No valid tool calls provided to handle_tool_calls.")
+        # Return an empty Response if there's nothing to process
+        return Response(messages=[], agent=None, context_variables={})
+
+    logger.debug(f"Handling {len(tool_calls)} tool calls.")
+
+    # Create a mapping from function/tool name to the actual callable object
+    function_map: Dict[str, AgentFunction] = {}
+    for func in functions:
+         # Get name robustly (prefer 'name' attribute, fallback to __name__)
+         func_name = getattr(func, 'name', getattr(func, '__name__', None))
+         if func_name:
+             if func_name in function_map:
+                  logger.warning(f"Duplicate function/tool name '{func_name}' detected. Overwriting previous entry.")
+             function_map[func_name] = func
+         else:
+              logger.warning(f"Available function/tool object {func} is missing a valid name. Skipping.")
+
+    # Initialize Response object to aggregate results
+    aggregated_response = Response(messages=[], agent=None, context_variables={})
+
+    # Process each requested tool call
+    for tool_call in tool_calls:
+        # Ensure it's the expected Pydantic model type
+        if not isinstance(tool_call, ChatCompletionMessageToolCall):
+            logger.warning(f"Skipping invalid item in tool_calls list: Expected ChatCompletionMessageToolCall, got {type(tool_call)}.")
+            continue
+
+        # Extract necessary info from the tool call object
+        tool_name = getattr(tool_call.function, 'name', None)
+        tool_call_id = getattr(tool_call, 'id', None)
+        raw_arguments = getattr(tool_call.function, 'arguments', '{}') # Default to empty JSON object string
+
+        # Validate essential components
+        if not tool_name or not tool_call_id:
+            logger.error(f"Invalid tool call data: Missing name ('{tool_name}') or id ('{tool_call_id}'). Skipping.")
+            # Optionally add an error message to the response
+            aggregated_response.messages.append({
+                "role": "tool", "tool_call_id": tool_call_id or "missing_id", "name": tool_name or "missing_name",
+                "content": json.dumps({"error": "Invalid tool call data received from LLM."})
+            })
+            continue
+
+        # Find the corresponding function/tool in the map
+        func_to_call = function_map.get(tool_name)
+        if not func_to_call:
+            logger.error(f"Tool '{tool_name}' requested by LLM (ID: '{tool_call_id}') not found in agent's available functions.")
+            # Add error message to history
+            aggregated_response.messages.append({
+                "role": "tool", "tool_call_id": tool_call_id, "name": tool_name,
+                "content": json.dumps({"error": f"Tool '{tool_name}' is not available."}) # Use JSON for content
+            })
+            continue
+
+        # Parse arguments string into a dictionary
+        try:
+            args: Dict[str, Any] = json.loads(raw_arguments)
+            if not isinstance(args, dict):
+                logger.warning(f"Parsed arguments for tool '{tool_name}' is not a dictionary ({type(args)}). Using empty dict.")
+                args = {}
+        except json.JSONDecodeError as e:
+            logger.error(f"Failed to parse JSON arguments for tool '{tool_name}' (ID: '{tool_call_id}'): {e}. Raw args: '{raw_arguments}'. Using empty dict.")
+            args = {}
+
+        # Inject context variables if the function expects them
+        try:
+             sig = inspect.signature(func_to_call)
+             if __CTX_VARS_NAME__ in sig.parameters:
+                 args[__CTX_VARS_NAME__] = context_variables
+                 if debug: logger.debug(f"Injecting context variables into tool '{tool_name}'.")
+        except (ValueError, TypeError) as e:
+             # Handle cases where signature cannot be inspected (e.g., built-ins)
+             logger.warning(f"Could not inspect signature for tool '{tool_name}': {e}. Cannot inject context automatically.")
+
+
+        # --- Execute the function/tool ---
+        try:
+            logger.info(f"Executing tool '{tool_name}' (ID: '{tool_call_id}') with args: {redact_sensitive_data(args)}")
+            # Execute the function with parsed arguments
+            raw_result = func_to_call(**args)
+
+            # Handle asynchronous functions/tools if necessary
+            if inspect.isawaitable(raw_result):
+                if debug: logger.debug(f"Awaiting async result for tool '{tool_name}' (ID: '{tool_call_id}')")
+                raw_result = await raw_result
+            # else: (sync function executed directly)
+
+            # Process the raw result (handles handoffs, serialization)
+            processed_result: Result = handle_function_result(raw_result, debug)
+
+            # Add the processed result message to the response
+            # Ensure content is a JSON string as expected by OpenAI 'tool' role message
+            result_content_json = processed_result.value if isinstance(processed_result.value, str) else json.dumps(processed_result.value)
+            aggregated_response.messages.append({
+                "role": "tool",
+                "tool_call_id": tool_call_id,
+                "name": tool_name,
+                "content": result_content_json
+            })
+
+            # Update context variables from the result
+            if processed_result.context_variables:
+                 aggregated_response.context_variables.update(processed_result.context_variables)
+                 if debug: logger.debug(f"Updated context variables from tool '{tool_name}': {processed_result.context_variables.keys()}")
+
+            # Handle potential agent handoff indicated by the result
+            if processed_result.agent:
+                 # If multiple tool calls try to handoff, the last one 'wins' here
+                 if aggregated_response.agent and aggregated_response.agent != processed_result.agent:
+                      logger.warning(f"Multiple agent handoffs detected in one turn. Last handoff to '{getattr(processed_result.agent, 'name', 'UnnamedAgent')}' takes precedence.")
+                 aggregated_response.agent = processed_result.agent
+                 # Update context immediately for subsequent steps within this turn if needed
+                 context_variables["active_agent_name"] = getattr(processed_result.agent, 'name', None)
+                 logger.debug(f"Agent handoff triggered by tool '{tool_name}' to agent '{context_variables['active_agent_name']}'.")
+
+        except Exception as e:
+            # Catch errors during function execution
+            logger.error(f"Error executing tool '{tool_name}' (ID: '{tool_call_id}'): {e}", exc_info=debug)
+            # Add error message to the response history
+            aggregated_response.messages.append({
+                "role": "tool",
+                "tool_call_id": tool_call_id,
+                "name": tool_name,
+                "content": json.dumps({"error": f"Execution failed: {str(e)}"}) # Provide error in JSON content
+            })
+
+    # Return the aggregated response containing all tool result messages and potential updates
+    logger.debug(f"Finished handling tool calls. {len(aggregated_response.messages)} result messages generated.")
+    return aggregated_response

swarm/types.py

@@ -0,0 +1,126 @@
+from openai.types.chat import ChatCompletionMessage
+from openai.types.chat.chat_completion_message_tool_call import (
+    ChatCompletionMessageToolCall,
+    Function as OpenAIFunction, # Renamed to avoid clash
+)
+from typing import List, Callable, Union, Optional, Dict, Any
+
+from pydantic import BaseModel, ConfigDict, Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+import uuid
+from enum import Enum
+
+# --- Pydantic Settings for Swarm Core ---
+class LogFormat(str, Enum):
+    standard = "[%(levelname)s] %(asctime)s - %(name)s:%(lineno)d - %(message)s"
+    simple = "[%(levelname)s] %(name)s - %(message)s"
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(env_prefix='SWARM_', case_sensitive=False)
+
+    log_level: str = Field(default='INFO', description="Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL)")
+    log_format: LogFormat = Field(default=LogFormat.standard, description="Logging format")
+    debug: bool = Field(default=False, description="Global debug flag")
+
+# --- LLMConfig ---
+class LLMConfig(BaseModel):
+    """Configuration for a specific LLM profile."""
+    provider: Optional[str] = "openai"
+    model: Optional[str] = None
+    api_key: Optional[str] = None
+    base_url: Optional[str] = None
+    max_tokens: Optional[int] = None # Max tokens supported by model
+    temperature: Optional[float] = 0.7
+    cost: Optional[float] = None
+    speed: Optional[float] = None
+    intelligence: Optional[float] = None
+    passthrough: Optional[bool] = False
+
+    model_config = ConfigDict(extra='allow')
+
+# --- Moved Tool Types Definition Higher ---
+class ToolFunction(BaseModel):
+    name: str
+    arguments: str # Should be a JSON string
+
+class ToolCall(BaseModel):
+    id: str
+    type: str = "function"
+    function: ToolFunction
+
+class ToolResult(BaseModel):
+    tool_call_id: str
+    role: str = "tool" # Added role for consistency
+    name: Optional[str] = None # Name of the function that was called
+    content: str
+# --- End Tool Types ---
+
+# AgentFunction needs Agent defined, so keep it below Agent
+# AgentFunction = Callable[[], Union[str, "Agent", dict]]
+AgentFunction = Callable[..., Union[str, "Agent", dict]]
+
+class Agent(BaseModel):
+    name: str = "Agent"
+    model: str = "default" # LLM profile name to use
+    instructions: Union[str, Callable[[], str]] = "You are a helpful agent."
+    functions: List[AgentFunction] = []
+    resources: List[Dict[str, Any]] = []
+    tool_choice: Optional[str] = None
+    parallel_tool_calls: bool = False
+    mcp_servers: Optional[List[str]] = None
+    env_vars: Optional[Dict[str, str]] = None
+    response_format: Optional[Dict[str, Any]] = None
+
+# --- ChatMessage Definition (Now ToolCall is defined) ---
+class ChatMessage(BaseModel):
+    """Represents a message in the chat history, potentially with tool calls."""
+    role: str
+    content: Optional[str] = None
+    tool_calls: Optional[List[ToolCall]] = None
+    tool_call_id: Optional[str] = None # For tool results
+    name: Optional[str] = None # For tool results or function name
+    sender: Optional[str] = None # Track the agent sending the message
+
+    model_config = ConfigDict(extra="allow")
+# --- End ChatMessage ---
+
+class Response(BaseModel):
+    id: Optional[str] = Field(default_factory=lambda: f"response-{uuid.uuid4()}")
+    messages: List[ChatMessage] = [] # Use ChatMessage type hint
+    agent: Optional[Agent] = None
+    context_variables: dict = {}
+
+class Result(BaseModel):
+    """
+    Encapsulates the possible return values for an agent function.
+    """
+    value: str = ""
+    agent: Optional[Agent] = None
+    context_variables: dict = {}
+
+# Re-defined Tool class
+class Tool:
+    def __init__(
+        self,
+        name: str,
+        func: Callable,
+        description: str = "",
+        input_schema: Optional[Dict[str, Any]] = None,
+        dynamic: bool = False,
+    ):
+        self.name = name
+        self.func = func
+        self.description = description
+        self.input_schema = input_schema or {"type": "object", "properties": {}} # Default schema
+        self.dynamic = dynamic
+
+    @property
+    def __name__(self): return self.name
+    @property
+    def __code__(self): return getattr(self.func, "__code__", None)
+    def __call__(self, *args, **kwargs): return self.func(*args, **kwargs)
+
+# Type alias for tool definitions used in discovery
+ToolDefinition = Dict[str, Any] # A dictionary representing a tool's schema
+Resource = Dict[str, Any] # A dictionary representing a resource
+

swarm/urls.py

@@ -0,0 +1,89 @@
+from django.contrib import admin
+from django.urls import path, re_path, include
+from django.http import HttpResponse
+from django.conf import settings
+from django.conf.urls.static import static
+import os
+import logging
+
+# Import specific views from their modules
+from swarm.views.core_views import index as core_index_view, serve_swarm_config, custom_login
+from swarm.views.chat_views import chat_completions
+from swarm.views.model_views import list_models
+from swarm.views.message_views import ChatMessageViewSet
+from drf_spectacular.views import SpectacularSwaggerView, SpectacularAPIView as HiddenSpectacularAPIView
+from rest_framework.routers import DefaultRouter
+
+logger = logging.getLogger(__name__)
+
+def favicon(request):
+    favicon_path = settings.BASE_DIR / 'assets' / 'images' / 'favicon.ico'
+    try:
+        with open(favicon_path, 'rb') as f:
+            favicon_data = f.read()
+        return HttpResponse(favicon_data, content_type="image/x-icon")
+    except FileNotFoundError:
+        logger.warning("Favicon not found.")
+        return HttpResponse(status=404)
+
+ENABLE_ADMIN = os.getenv("ENABLE_ADMIN", "false").lower() in ("true", "1", "t")
+ENABLE_WEBUI = os.getenv("ENABLE_WEBUI", "true").lower() in ("true", "1", "t")
+
+logger.debug(f"ENABLE_WEBUI={'true' if ENABLE_WEBUI else 'false'}")
+logger.debug(f"ENABLE_ADMIN={'true' if ENABLE_ADMIN else 'false'}")
+
+router = DefaultRouter()
+# Ensure ChatMessageViewSet is available before registering
+if ChatMessageViewSet:
+    router.register(r'v1/chat/messages', ChatMessageViewSet, basename='chatmessage')
+else:
+     logger.warning("ChatMessageViewSet not imported correctly, skipping API registration.")
+
+# Base URL patterns required by Swarm core
+# Use the imported view functions directly
+base_urlpatterns = [
+    re_path(r'^health/?$', lambda request: HttpResponse("OK"), name='health_check'),
+    re_path(r'^v1/chat/completions/?$', chat_completions, name='chat_completions'),
+    re_path(r'^v1/models/?$', list_models, name='list_models'),
+    re_path(r'^schema/?$', HiddenSpectacularAPIView.as_view(), name='schema'),
+    re_path(r'^swagger-ui/?$', SpectacularSwaggerView.as_view(url_name='schema'), name='swagger-ui'),
+]
+
+# Optional Admin URLs
+admin_urlpatterns = [path('admin/', admin.site.urls)] if ENABLE_ADMIN else []
+
+# Optional Web UI URLs
+webui_urlpatterns = []
+if ENABLE_WEBUI:
+    webui_urlpatterns = [
+        path('', core_index_view, name='index'),
+        path('favicon.ico', favicon, name='favicon'),
+        path('config/swarm_config.json', serve_swarm_config, name='serve_swarm_config'),
+        path('accounts/login/', custom_login, name='custom_login'),
+    ]
+    if settings.DEBUG:
+         if settings.STATIC_URL and settings.STATIC_ROOT:
+              webui_urlpatterns += static(settings.STATIC_URL, document_root=settings.STATIC_ROOT)
+         else:
+              logger.warning("STATIC_URL or STATIC_ROOT not configured, static files may not serve correctly in DEBUG mode.")
+
+# --- Blueprint URLs are now added dynamically via blueprint_base.py -> django_utils.py ---
+blueprint_urlpatterns = [] # Start with empty list, populated by utils
+
+# Combine all URL patterns
+urlpatterns = webui_urlpatterns + admin_urlpatterns + base_urlpatterns + blueprint_urlpatterns + router.urls
+
+# Log final URL patterns (consider moving this to where patterns are finalized if issues persist)
+if settings.DEBUG:
+    try:
+        from django.urls import get_resolver
+        # Note: get_resolver(None) might not reflect dynamically added URLs perfectly here.
+        # Logging within django_utils might be more accurate for dynamic additions.
+        final_patterns = get_resolver(None).url_patterns
+        logger.debug(f"Initial resolved URL patterns ({len(final_patterns)} total):")
+        # for pattern in final_patterns:
+        #      try: pattern_repr = str(pattern)
+        #      except: pattern_repr = f"[Pattern for {getattr(pattern, 'name', 'unnamed')}]"
+        #      logger.debug(f"  {pattern_repr}")
+    except Exception as e:
+        logger.error(f"Could not log initial URL patterns: {e}")

swarm/util.py

@@ -0,0 +1,124 @@
+"""
+Utility functions for the Swarm framework.
+
+This module provides helper functions for serializing functions/tools to JSON and merging streaming response chunks,
+ensuring compatibility with OpenAI API requirements and robust handling of agent interactions.
+"""
+
+import inspect
+import json
+from datetime import datetime
+from .types import Tool  # Adjust import as needed if 'Tool' is in a different location
+
+
+def merge_fields(target: dict, source: dict) -> None:
+    """
+    Recursively merge fields from source into target, appending strings and updating nested dictionaries.
+
+    Args:
+        target (dict): The dictionary to update.
+        source (dict): The dictionary with new values to merge.
+    """
+    for key, value in source.items():
+        if isinstance(value, str):
+            target[key] = target.get(key, "") + value
+        elif value is not None and isinstance(value, dict):
+            if key not in target:
+                target[key] = {}
+            merge_fields(target[key], value)
+
+
+def merge_chunk(final_response: dict, delta: dict) -> None:
+    """
+    Merge a delta update into a response dictionary, handling tool calls and content incrementally.
+
+    Args:
+        final_response (dict): The cumulative response being built.
+        delta (dict): The delta update from a streaming response.
+    """
+    delta.pop("role", None)
+    merge_fields(final_response, delta)
+
+    tool_calls = delta.get("tool_calls")
+    if tool_calls and len(tool_calls) > 0:
+        index = tool_calls[0].pop("index", 0)
+        if "tool_calls" not in final_response:
+            final_response["tool_calls"] = {}
+        if index not in final_response["tool_calls"]:
+            final_response["tool_calls"][index] = {"function": {"arguments": "", "name": ""}, "id": "", "type": ""}
+        merge_fields(final_response["tool_calls"][index], tool_calls[0])
+
+
+def function_to_json(func, truncate_desc: bool = False) -> dict:
+    """
+    Convert a Python callable or Tool instance to a JSON-serializable dictionary for OpenAI API.
+
+    Supports both reflection-based serialization for raw functions and schema-based serialization for Tool objects.
+    Optionally truncates descriptions to 1024 characters to meet API limits.
+
+    Args:
+        func: The function or Tool object to serialize.
+        truncate_desc (bool): If True, truncate the description to 1024 characters.
+
+    Returns:
+        dict: A dictionary with 'type', 'function', 'name', 'description', and 'parameters'.
+
+    Raises:
+        ValueError: If function signature cannot be inspected (for raw functions).
+    """
+    # Handle Tool instances from MCP servers
+    if isinstance(func, Tool):
+        name = func.name
+        description = func.description or ""
+        tool_schema = func.input_schema or {}
+        final_type = tool_schema.get("type", "object")
+        final_properties = tool_schema.get("properties", {})
+        final_required = tool_schema.get("required", [])
+    # Handle raw Python callables via reflection
+    else:
+        try:
+            signature = inspect.signature(func)
+        except ValueError as e:
+            raise ValueError(f"Failed to get signature for function {func.__name__}: {str(e)}")
+        
+        name = getattr(func, "__name__", "unnamed_function")
+        description = (func.__doc__ or "").strip() or f"Calls {name}"
+        type_map = {
+            str: "string",
+            int: "integer",
+            float: "number",
+            bool: "boolean",
+            list: "array",
+            dict: "object",
+            type(None): "null",
+        }
+        parameters = {}
+        required = []
+        for param in signature.parameters.values():
+            ann = param.annotation if param.annotation != inspect.Parameter.empty else str
+            param_type = type_map.get(ann, "string")
+            parameters[param.name] = {"type": param_type}
+            if param.default == inspect.Parameter.empty:
+                required.append(param.name)
+        
+        final_type = "object"
+        final_properties = parameters
+        final_required = required
+
+    # Truncate description if requested
+    if truncate_desc and len(description) > 1024:
+        description = description[:1024]
+        # logger.debug(f"Truncated description for '{name}': {len(description)} -> 1024 characters")
+
+    return {
+        "type": "function",
+        "function": {
+            "name": name,
+            "description": description,
+            "parameters": {
+                "type": final_type,
+                "properties": final_properties,
+                "required": final_required,
+            },
+        },
+    }

swarm/utils/color_utils.py

@@ -0,0 +1,40 @@
+# src/swarm/utils/color_utils.py
+
+from colorama import Fore, Style, init as colorama_init
+
+def initialize_colorama():
+    """
+    Initialize colorama for colored terminal outputs.
+    
+    This function should be called at the start of your application to ensure
+    that ANSI color codes are interpreted correctly across different platforms.
+    """
+    colorama_init(autoreset=True)
+
+def color_text(text: str, color: str) -> str:
+    """
+    Return the text string wrapped in the specified color codes.
+    
+    Args:
+        text (str): The text to color.
+        color (str): The color name. Supported colors: red, green, yellow, blue, magenta, cyan, white.
+    
+    Returns:
+        str: Colored text string.
+    
+    Example:
+        >>> print(color_text("Hello, World!", "green"))
+        Hello, World!  # (in green color)
+    """
+    color_mapping = {
+        "red": Fore.RED,
+        "green": Fore.GREEN,
+        "yellow": Fore.YELLOW,
+        "blue": Fore.BLUE,
+        "magenta": Fore.MAGENTA,
+        "cyan": Fore.CYAN,
+        "white": Fore.WHITE,
+    }
+    
+    color_code = color_mapping.get(color.lower(), Fore.WHITE)
+    return f"{color_code}{text}{Style.RESET_ALL}"