atlas-chat 0.1.0__py3-none-any.whl

atlas/mcp/sampling_demo/main.py

@@ -0,0 +1,234 @@
+#!/usr/bin/env python3
+"""
+Sampling Demo MCP Server using FastMCP
+
+This server demonstrates LLM sampling capabilities - requesting
+LLM text generation from the client during tool execution.
+
+Supports:
+- Basic text generation
+- Multi-turn conversations
+- System prompts
+- Temperature control
+- Model preferences
+- Agentic workflows with tool use
+"""
+
+from fastmcp import Context, FastMCP
+
+# Initialize the MCP server
+mcp = FastMCP("Sampling Demo")
+
+
+@mcp.tool
+async def summarize_text(text: str, ctx: Context) -> str:
+    """
+    Summarize the provided text using LLM sampling.
+
+    This tool demonstrates basic LLM sampling - requesting the LLM
+    to generate a summary of the given text.
+
+    Args:
+        text: The text to summarize
+
+    Returns:
+        A summary of the input text
+    """
+    result = await ctx.sample(f"Please provide a concise summary of the following text:\n\n{text}")
+    return result.text or "Unable to generate summary"
+
+
+@mcp.tool
+async def analyze_sentiment(text: str, ctx: Context) -> str:
+    """
+    Analyze the sentiment of the provided text using LLM sampling.
+
+    This tool demonstrates sampling with a system prompt that establishes
+    the LLM's role as a sentiment analyzer.
+
+    Args:
+        text: The text to analyze
+
+    Returns:
+        Sentiment analysis result
+    """
+    result = await ctx.sample(
+        messages=f"Analyze the sentiment of this text: {text}",
+        system_prompt="You are a sentiment analysis expert. Provide clear, concise sentiment analysis with reasoning.",
+        temperature=0.3  # Lower temperature for more consistent analysis
+    )
+    return result.text or "Unable to analyze sentiment"
+
+
+@mcp.tool
+async def generate_code(description: str, language: str, ctx: Context) -> str:
+    """
+    Generate code based on a description using LLM sampling.
+
+    This tool demonstrates sampling with model preferences - hinting
+    which models should be used for code generation.
+
+    Args:
+        description: Description of what the code should do
+        language: Programming language to use
+
+    Returns:
+        Generated code
+    """
+    result = await ctx.sample(
+        messages=f"Generate {language} code that does the following: {description}",
+        system_prompt=f"You are an expert {language} programmer. Write clean, well-commented code.",
+        temperature=0.7,
+        max_tokens=1000,
+        model_preferences=["gpt-4", "claude-3-sonnet", "gpt-3.5-turbo"]  # Prefer larger models for code
+    )
+    return result.text or "Unable to generate code"
+
+
+@mcp.tool
+async def creative_story(prompt: str, ctx: Context) -> str:
+    """
+    Generate a creative story using LLM sampling with high temperature.
+
+    This tool demonstrates sampling with higher temperature for more
+    creative and varied outputs.
+
+    Args:
+        prompt: Story prompt or theme
+
+    Returns:
+        Generated creative story
+    """
+    result = await ctx.sample(
+        messages=f"Write a creative short story based on this prompt: {prompt}",
+        system_prompt="You are a creative fiction writer known for imaginative storytelling.",
+        temperature=0.9,  # High temperature for creativity
+        max_tokens=500
+    )
+    return result.text or "Unable to generate story"
+
+
+@mcp.tool
+async def multi_turn_conversation(topic: str, ctx: Context) -> str:
+    """
+    Have a multi-turn conversation about a topic using LLM sampling.
+
+    This tool demonstrates multi-turn sampling - building up a conversation
+    history and maintaining context across multiple sampling calls.
+
+    Args:
+        topic: The topic to discuss
+
+    Returns:
+        Summary of the conversation
+    """
+    from mcp.types import SamplingMessage, TextContent
+
+    # Start with an introduction
+    messages = [
+        SamplingMessage(
+            role="user",
+            content=TextContent(type="text", text=f"Let's discuss {topic}. What are the key aspects to consider?")
+        )
+    ]
+
+    # First sampling: Get initial response
+    result1 = await ctx.sample(
+        messages=messages,
+        system_prompt="You are a knowledgeable assistant engaging in a thoughtful discussion.",
+        temperature=0.7
+    )
+
+    # Add response to history
+    messages.append(
+        SamplingMessage(
+            role="assistant",
+            content=TextContent(type="text", text=result1.text)
+        )
+    )
+
+    # Second turn: Ask a follow-up question
+    messages.append(
+        SamplingMessage(
+            role="user",
+            content=TextContent(type="text", text="That's interesting. Can you elaborate on the most important point?")
+        )
+    )
+
+    # Second sampling: Get follow-up response
+    result2 = await ctx.sample(
+        messages=messages,
+        temperature=0.7
+    )
+
+    # Return summary of conversation
+    return f"**Discussion on {topic}**\n\n**Initial Response:**\n{result1.text}\n\n**Follow-up:**\n{result2.text}"
+
+
+@mcp.tool
+async def research_question(question: str, ctx: Context) -> str:
+    """
+    Research a question using multiple LLM sampling calls.
+
+    This tool demonstrates agentic behavior - using sampling to break down
+    a complex question, gather information, and synthesize an answer.
+
+    Args:
+        question: The research question to answer
+
+    Returns:
+        Comprehensive research-based answer
+    """
+    # Step 1: Break down the question
+    breakdown_result = await ctx.sample(
+        messages=f"Break down this question into 3 key sub-questions that need to be answered: {question}",
+        system_prompt="You are a research assistant. Identify key sub-questions clearly and concisely.",
+        temperature=0.5,
+        max_tokens=200
+    )
+
+    # Step 2: Research each aspect
+    research_result = await ctx.sample(
+        messages=f"Based on these sub-questions:\n{breakdown_result.text}\n\nProvide a comprehensive answer to the original question: {question}",
+        system_prompt="You are a research expert. Provide well-reasoned, evidence-based answers.",
+        temperature=0.6,
+        max_tokens=800
+    )
+
+    return f"**Research Question:** {question}\n\n**Analysis:**\n{breakdown_result.text}\n\n**Answer:**\n{research_result.text}"
+
+
+@mcp.tool
+async def translate_and_explain(text: str, target_language: str, ctx: Context) -> str:
+    """
+    Translate text and explain translation choices using LLM sampling.
+
+    This tool demonstrates sequential sampling for multi-step tasks.
+
+    Args:
+        text: Text to translate
+        target_language: Target language for translation
+
+    Returns:
+        Translation with explanation
+    """
+    # Step 1: Translate
+    translation_result = await ctx.sample(
+        messages=f"Translate the following text to {target_language}:\n\n{text}",
+        system_prompt=f"You are an expert translator. Provide accurate {target_language} translations.",
+        temperature=0.3
+    )
+
+    # Step 2: Explain translation choices
+    explanation_result = await ctx.sample(
+        messages=f"Explain the key translation choices made in translating to {target_language}:\n\nOriginal: {text}\n\nTranslation: {translation_result.text}",
+        system_prompt="You are a translation expert. Explain translation decisions clearly.",
+        temperature=0.4,
+        max_tokens=300
+    )
+
+    return f"**Translation to {target_language}:**\n{translation_result.text}\n\n**Translation Notes:**\n{explanation_result.text}"
+
+
+if __name__ == "__main__":
+    mcp.run()

atlas/mcp/thinking/main.py

@@ -0,0 +1,77 @@
+#!/usr/bin/env python3
+"""
+Thinking MCP Server using FastMCP
+Provides a thinking tool that processes thoughts and breaks down problems step by step.
+"""
+
+from typing import Any, Dict, List
+
+from fastmcp import FastMCP
+
+# Initialize the MCP server
+mcp = FastMCP("Thinking")
+
+
+@mcp.tool
+def thinking(list_of_thoughts: List[str]) -> Dict[str, Any]:
+    """
+    Structured thinking and ideation tool for organizing thoughts, brainstorming, and problem-solving analysis.
+
+    This cognitive assistance tool helps organize and process complex thinking patterns:
+
+    **Thought Organization:**
+    - Structured collection and validation of multiple ideas
+    - Thought counting and enumeration for analysis
+    - List-based organization for sequential thinking
+    - Input validation and error handling for robustness
+
+    **Cognitive Support:**
+    - Brainstorming session facilitation
+    - Problem decomposition and analysis
+    - Creative thinking process documentation
+    - Decision-making support through thought structuring
+
+    **Analysis Features:**
+    - Thought count and quantity analysis
+    - Input validation and quality checks
+    - Structured output for further processing
+    - Error handling for incomplete inputs
+
+    **Use Cases:**
+    - Strategic planning and decision making
+    - Creative brainstorming sessions
+    - Problem-solving workshops
+    - Research idea generation
+    - Project planning and ideation
+    - Learning and knowledge organization
+
+    **Workflow Integration:**
+    - Compatible with other analytical tools
+    - Structured output for downstream processing
+    - Integration with documentation systems
+    - Support for iterative thinking processes
+
+    Args:
+        list_of_thoughts: Collection of thoughts, ideas, or concepts to organize (array of strings)
+
+    Returns:
+        Dictionary containing:
+        - thoughts: Organized list of all provided thoughts
+        - count: Total number of thoughts processed
+        Or error message if no thoughts provided or processing fails
+    """
+    try:
+        if not list_of_thoughts:
+            return {"results": {"error": "No thoughts provided"}}
+
+        return {"results": {
+            "thoughts": list_of_thoughts,
+            "count": len(list_of_thoughts)
+        }}
+
+    except Exception as e:
+        return {"results": {"error": f"Error processing thoughts: {str(e)}"}}
+
+
+if __name__ == "__main__":
+    mcp.run()

atlas/mcp/tool_planner/main.py

@@ -0,0 +1,240 @@
+#!/usr/bin/env python3
+"""
+Tool Planner MCP Server using FastMCP.
+
+Uses _mcp_data injection and MCP sampling to generate bash scripts that
+accomplish a user's task by calling the Atlas CLI with the appropriate tools.
+
+Flow:
+1. User asks the LLM to plan a task (e.g., "create a powerpoint about dogs")
+2. LLM calls plan_with_tools, passing the user's request as `task`
+3. Atlas UI injects `_mcp_data` (all available tools metadata) and `username`
+4. Inside the tool:
+   a. Convert `_mcp_data` into an LLM-friendly CLI tool reference
+   b. Use ctx.sample() to ask the LLM to write a bash script using atlas_chat_cli.py
+   c. Return the generated bash script
+"""
+
+import base64
+import re
+from typing import Any, Dict, Optional
+
+from fastmcp import Context, FastMCP
+
+mcp = FastMCP("Tool Planner")
+
+
+PLANNER_SYSTEM_PROMPT = """\
+You are a task planner. Given a user's request and a list of available CLI tools,
+write a bash script that accomplishes the task using sequential calls to:
+
+  python atlas_chat_cli.py "instruction" --tools tool_name
+
+Rules:
+- Each step is a plain CLI call with a natural language instruction and the right --tools flag
+- Use -o filename.txt to save output to a file when a later step needs it
+- Use loops (for/while) for repetitive operations
+- Include set -e for error checking
+- The script should be self-contained and runnable from the backend/ directory
+- Do NOT use --json unless parsing structured output is truly necessary
+- Keep instructions to the LLM clear and specific in each CLI call
+- Be concise: at most 2 short comment lines between commands, no lengthy explanations
+- The script should be easy to read at a glance
+"""
+
+
+def format_tools_for_llm(mcp_data: Dict[str, Any]) -> str:
+    """Convert _mcp_data into a human-readable CLI tool reference.
+
+    Produces a text block describing each server and its tools with
+    parameter details, suitable for inclusion in an LLM prompt.
+
+    Args:
+        mcp_data: The _mcp_data dict injected by Atlas UI, containing
+                  an ``available_servers`` list.
+
+    Returns:
+        A formatted multi-line string describing available tools.
+    """
+    servers = mcp_data.get("available_servers", [])
+    if not servers:
+        return "(No tools available)"
+
+    lines: list[str] = []
+    for server in servers:
+        server_name = server.get("server_name", "unknown")
+        server_desc = server.get("description", "")
+        desc_part = f" ({server_desc})" if server_desc else ""
+        lines.append(f"Server: {server_name}{desc_part}")
+
+        for tool in server.get("tools", []):
+            tool_name = tool.get("name", "unknown")
+            tool_desc = tool.get("description", "")
+            lines.append(f"  Tool: {tool_name}")
+            if tool_desc:
+                lines.append(f"    Description: {tool_desc}")
+
+            params = tool.get("parameters", {})
+            properties = params.get("properties", {})
+            required = set(params.get("required", []))
+
+            if properties:
+                lines.append("    Parameters:")
+                for param_name, param_schema in properties.items():
+                    if param_name.startswith("_"):
+                        continue
+                    param_type = param_schema.get("type", "any")
+                    req_label = "required" if param_name in required else "optional"
+                    param_desc = param_schema.get("description", "")
+                    desc_suffix = f": {param_desc}" if param_desc else ""
+                    lines.append(
+                        f"      - {param_name} ({param_type}, {req_label}){desc_suffix}"
+                    )
+
+        lines.append("")
+
+    return "\n".join(lines)
+
+
+def build_planning_prompt(task: str, tools_reference: str) -> str:
+    """Build the user message for the sampling call.
+
+    Combines the task description, CLI usage instructions, and the
+    formatted tools reference into a single prompt.
+
+    Args:
+        task: The user's task description.
+        tools_reference: Output of ``format_tools_for_llm()``.
+
+    Returns:
+        The complete user-message string for ctx.sample().
+    """
+    return (
+        f"Task: {task}\n\n"
+        f"Available tools:\n{tools_reference}\n\n"
+        "CLI usage:\n"
+        '  python atlas_chat_cli.py "instruction for the LLM" --tools tool_name\n\n'
+        "Capture output to file if needed:\n"
+        '  python atlas_chat_cli.py "instruction" --tools tool_name -o result.txt\n\n'
+        "Loops:\n"
+        '  for item in "a" "b" "c"; do\n'
+        '    python atlas_chat_cli.py "Do something with $item" --tools tool_name\n'
+        "  done\n\n"
+        "Write a bash script that accomplishes the task."
+    )
+
+
+def _sanitize_filename(task: str, max_length: int = 40) -> str:
+    """Derive a safe filename from the task description."""
+    slug = re.sub(r"[^\w\s-]", "", task.lower())
+    slug = re.sub(r"[\s_-]+", "_", slug).strip("_")
+    return slug[:max_length] if slug else "plan"
+
+
+def _build_artifact_response(
+    script_text: str, task: str
+) -> Dict[str, Any]:
+    """Wrap a script in the Atlas artifact download format.
+
+    Returns a dict with ``results``, ``artifacts``, and ``display``
+    matching the convention used by pptx_generator and csv_reporter.
+    """
+    filename = f"{_sanitize_filename(task)}.sh"
+    script_b64 = base64.b64encode(script_text.encode("utf-8")).decode("utf-8")
+
+    return {
+        "results": {
+            "operation": "plan_with_tools",
+            "task": task,
+            "filename": filename,
+            "message": "Bash script plan generated.",
+        },
+        "artifacts": [
+            {
+                "name": filename,
+                "b64": script_b64,
+                "mime": "application/x-sh",
+                "viewer": "code",
+            }
+        ],
+        "display": {
+            "open_canvas": True,
+            "primary_file": filename,
+            "mode": "replace",
+            "viewer_hint": "code",
+        },
+    }
+
+
+@mcp.tool
+async def plan_with_tools(
+    task: str,
+    _mcp_data: Optional[Dict[str, Any]] = None,
+    username: Optional[str] = None,
+    ctx: Context = None,
+) -> Dict[str, Any]:
+    """Plan how to accomplish a task by generating a bash script that uses the Atlas CLI.
+
+    This tool receives metadata about all available MCP tools via _mcp_data
+    injection, then uses LLM sampling to produce a runnable bash script.
+    Each step in the script calls atlas_chat_cli.py with the appropriate
+    --tools flag. The script is returned as a downloadable .sh file.
+
+    Args:
+        task: Description of the task to accomplish.
+        _mcp_data: Automatically injected by Atlas UI with available tool
+                   metadata. Do not provide this manually.
+        username: The authenticated user (automatically injected by Atlas UI).
+
+    Returns:
+        Atlas artifact dict with the bash script as a downloadable file.
+    """
+    mcp_data = _mcp_data or {}
+    tools_reference = format_tools_for_llm(mcp_data)
+    user_message = build_planning_prompt(task, tools_reference)
+
+    if ctx is None:
+        fallback = (
+            f"#!/bin/bash\nset -e\n"
+            f"# Sampling unavailable -- cannot generate plan.\n"
+            f"# Task: {task}\n"
+            f"# Tools reference:\n{tools_reference}"
+        )
+        return _build_artifact_response(fallback, task)
+
+    server_count = len(mcp_data.get("available_servers", []))
+    await ctx.report_progress(
+        progress=0, total=3,
+        message=f"Discovered {server_count} servers, building prompt...",
+    )
+
+    await ctx.report_progress(
+        progress=1, total=3,
+        message="Asking LLM to generate bash script...",
+    )
+
+    result = await ctx.sample(
+        messages=user_message,
+        system_prompt=PLANNER_SYSTEM_PROMPT,
+        temperature=0.3,
+        max_tokens=10000,
+    )
+
+    await ctx.report_progress(
+        progress=2, total=3,
+        message="Packaging script as downloadable artifact...",
+    )
+
+    script_text = result.text or "#!/bin/bash\nset -e\n# Unable to generate plan"
+    response = _build_artifact_response(script_text, task)
+
+    await ctx.report_progress(
+        progress=3, total=3,
+        message="Done.",
+    )
+
+    return response
+
+
+if __name__ == "__main__":
+    mcp.run()