atlas-chat 0.1.0__py3-none-any.whl

atlas/mcp/prompts/main.py

@@ -0,0 +1,222 @@
+#!/usr/bin/env python3
+"""
+Prompts MCP Server using FastMCP
+Provides specialized system prompts that can be applied to modify the AI's behavior.
+"""
+
+from typing import Any, Dict
+
+from fastmcp import FastMCP
+from fastmcp.prompts.prompt import PromptMessage, TextContent
+
+# Initialize the MCP server
+mcp = FastMCP("Prompts")
+
+
+@mcp.prompt
+def financial_tech_wizard() -> PromptMessage:
+    """Think like a financial tech wizard - expert in fintech, trading algorithms, and financial markets."""
+    content = """You are a financial technology wizard with deep expertise in:
+- Financial markets, trading strategies, and algorithmic trading
+- Fintech solutions, payment systems, and blockchain technology
+- Risk management, quantitative analysis, and financial modeling
+- Regulatory compliance and financial technology innovation
+
+Think analytically, provide data-driven insights, and consider both technical and business aspects when responding to financial questions. Use precise financial terminology and cite relevant market examples when appropriate."""
+
+    return PromptMessage(role="user", content=TextContent(type="text", text=f"System: {content}\n\nUser: Please adopt this personality and expertise for our conversation."))
+
+
+@mcp.prompt
+def expert_dog_trainer() -> PromptMessage:
+    """You are an expert dog trainer with years of experience in canine behavior and training."""
+    content = """You are an expert dog trainer with over 15 years of experience in:
+- Canine behavior analysis and psychology
+- Positive reinforcement training methods
+- Puppy training, obedience training, and behavioral modification
+- Working with different breeds and temperaments
+- Problem solving for common behavioral issues
+
+Always provide practical, humane, and evidence-based training advice. Consider the dog's age, breed, and individual personality when making recommendations. Emphasize positive reinforcement and building trust between dog and owner."""
+
+    return PromptMessage(role="user", content=TextContent(type="text", text=f"System: {content}\n\nUser: Please adopt this expertise for our conversation."))
+
+
+@mcp.prompt
+def creative_writer() -> PromptMessage:
+    """You are a creative writing expert focused on storytelling, character development, and narrative craft."""
+    content = """You are a creative writing expert with expertise in:
+- Storytelling techniques, plot development, and narrative structure
+- Character development, dialogue writing, and world-building
+- Multiple genres including fiction, poetry, screenwriting, and creative nonfiction
+- Writing craft, style, and literary devices
+- Workshop facilitation and constructive feedback
+
+Approach writing with creativity, technical skill, and attention to voice and style. Provide specific, actionable advice that helps writers develop their craft while honoring their unique creative vision."""
+
+    return PromptMessage(role="user", content=TextContent(type="text", text=f"System: {content}\n\nUser: Please adopt this creative writing expertise for our conversation."))
+
+
+@mcp.prompt
+def truncation_demo_super_long_description() -> PromptMessage:
+    """Truncation demo: intentionally long description for UI testing.
+
+    This prompt exists to validate that the frontend truncation logic for prompt descriptions works as intended.
+    It is deliberately verbose (well over 500 characters) so the Tools & Integrations UI can show:
+    - An info icon next to the prompt name
+    - An expandable description panel
+    - The truncated rendering (start + "..." + end) for very long descriptions
+
+    Suggested manual check:
+    1) Open Tools & Integrations
+    2) Expand the MCP server named "Prompts"
+    3) Find this prompt and click the info icon
+    4) Confirm the description is truncated with the first and last portions visible
+
+    Additional filler to ensure we exceed the truncation threshold:
+    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+    Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
+    Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.
+    Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
+    Repeat for length: lorem ipsum, lorem ipsum, lorem ipsum, lorem ipsum, lorem ipsum, lorem ipsum, lorem ipsum.
+
+    Now let's talk about road runners and cactus in New Mexico - these iconic symbols of the American southwest have captivated people for generations. The roadrunner, known scientifically as Geococcyx californianus, is a large ground-dwelling bird that can reach speeds up to 20 miles per hour. These clever birds are often found in the deserts and grasslands of New Mexico, using their long legs and tails for balance while navigating the rugged terrain. Famous for their distinctive cooing calls and the legendary belief that they run in front of cars to create a wind vacuum that helps them fly, roadrunners are actually quite terrestrial.
+
+    The cactus of New Mexico are equally fascinating, with over 100 species found throughout the state. Perhaps most iconic is the saguaro cactus, though they're more common in Arizona. In New Mexico, you'll find the cholla cactus with its distinctive hooked spines that easily detach and cling to anything that brushes against them, the prickly pear cactus that produces sweet edible fruits, and the yucca plant which, while technically not a cactus, shares many similar adaptations for desert life. These plants have evolved amazing survival strategies including thick waxy coatings to reduce water loss, shallow but extensive root systems to capture rare rainfall, and spines that not only deter herbivores but also create shade for the plant itself.
+
+    The relationship between roadrunners and cactus in New Mexico's ecosystem is quite interesting. Roadrunners often use cactus as perches to survey their hunting grounds, and they've developed hunting techniques that involve luring prey toward prickly barriers where the animal gets stuck, allowing the roadrunner to easily capture it. This predator-prey dynamic has been playing out across New Mexico's deserts for thousands of years, adapting to the harsh environmental conditions that both species share.
+
+    Speaking of desert adaptations, both roadrunners and cactus have remarkable abilities to survive extreme heat and minimal water. Roadrunners can go without drinking water for long periods by obtaining moisture from their food, particularly from the insects and small reptiles they consume. Cactus store water in their thick stems and can go months without rainfall. During the monsoon season in New Mexico, typically from June through September, both roadrunners and cactus benefit from the sudden abundance of water and food sources.
+
+    The cultural significance of roadrunners and cactus in New Mexico cannot be overstated. The roadrunner appears in Native American folklore, particularly in the stories of the Pueblo people, where it represents cleverness and survival. Cactus have been used for food, medicine, and even as building materials by indigenous peoples for centuries. Today, both continue to symbolize the beauty and resilience of the desert southwest, appearing in art, literature, and popular culture.
+
+    Interestingly, New Mexico's roadsides and walking trails are often lined with various cactus species, creating natural barriers and habitats for wildlife. Roadrunners can frequently be seen darting across highways or scurrying alongside desert paths, sometimes pausing to bob their heads in that characteristic way that has made them so endearing. The state's diverse geography means you'll find different cactus species at varying elevations - from the lowland deserts around Las Cruces to the mountain foothills near Santa Fe.
+
+    End marker: the UI should still show this ending segment after truncation, and we've now covered the fascinating intersection of roadrunners and cactus in New Mexico's unique ecosystem.
+    """
+    content = """You are running a UI truncation demo. Keep responses short.
+
+If the user asks what this is for, explain that it is a test prompt whose description is intentionally long to validate UI truncation behavior, and that it also contains extended information about roadrunners and cactus found in New Mexico."""
+
+    return PromptMessage(
+        role="user",
+        content=TextContent(
+            type="text",
+            text=f"System: {content}\n\nUser: Please adopt this behavior for our conversation.",
+        ),
+    )
+
+
+@mcp.prompt
+def ask_about_topic(topic: str) -> str:
+    """Generates a user message asking for an explanation of a topic."""
+    return f"Can you please explain the concept of '{topic}'?"
+
+
+@mcp.prompt
+def generate_code_request(language: str, task_description: str) -> PromptMessage:
+    """Generates a user message requesting code generation."""
+    content = f"Write a {language} function that performs the following task: {task_description}"
+    return PromptMessage(role="user", content=TextContent(type="text", text=content))
+
+
+@mcp.tool
+def list_available_prompts() -> Dict[str, Any]:
+    """
+    Discover and enumerate all available AI personality and expertise system prompts for customizing assistant behavior.
+
+    This prompt management tool provides comprehensive access to AI behavior modification capabilities:
+
+    **System Prompt Categories:**
+    - Professional expertise prompts (financial, technical, business)
+    - Creative and artistic personality prompts (writing, design, storytelling)
+    - Educational and training-focused prompts (teaching, coaching, mentoring)
+    - Specialized domain knowledge prompts (industry-specific expertise)
+
+    **Available Professional Prompts:**
+    - Financial Tech Wizard: Fintech expertise, trading algorithms, market analysis
+    - Expert Dog Trainer: Canine behavior, training methods, pet psychology
+    - Creative Writer: Storytelling, character development, narrative craft
+
+    **Prompt Customization Features:**
+    - Detailed personality and expertise descriptions
+    - Behavioral modification instructions
+    - Domain-specific knowledge activation
+    - Communication style and approach guidance
+
+    **AI Behavior Modification:**
+    - Specialized knowledge domain activation
+    - Professional communication style adaptation
+    - Expert-level analytical thinking patterns
+    - Industry-specific terminology and concepts
+
+    **Use Cases:**
+    - Specialized consulting and advisory interactions
+    - Educational content creation and tutoring
+    - Professional analysis and problem-solving
+    - Creative project development and brainstorming
+    - Domain-specific research and investigation
+    - Training and skill development sessions
+
+    **Integration Features:**
+    - Compatible with conversation management systems
+    - Seamless personality switching capabilities
+    - Context-aware prompt application
+    - Multi-session personality persistence
+
+    **Customization Benefits:**
+    - Enhanced subject matter expertise
+    - Improved response relevance and accuracy
+    - Professional-grade analytical capabilities
+    - Specialized communication patterns
+
+    Returns:
+        Dictionary containing:
+        - available_prompts: Complete catalog of system prompts with descriptions
+        - Each prompt includes: description, type, category, and usage guidelines
+        - total_count: Number of available prompts
+        - categories: Organized groupings of prompt types
+        Or error message if prompt discovery fails
+    """
+    prompts = {
+        "financial_tech_wizard": {
+            "description": "Think like a financial tech wizard - expert in fintech, trading algorithms, and financial markets",
+            "type": "system_prompt",
+            "category": "professional"
+        },
+        "expert_dog_trainer": {
+            "description": "You are an expert dog trainer with years of experience in canine behavior and training",
+            "type": "system_prompt",
+            "category": "professional"
+        },
+        "creative_writer": {
+            "description": "You are a creative writing expert focused on storytelling, character development, and narrative craft",
+            "type": "system_prompt",
+            "category": "creative"
+        },
+        "truncation_demo_super_long_description": {
+            "description": (
+                "Truncation demo: intentionally long description for UI testing. "
+                "This prompt exists to validate that the frontend truncation logic for prompt descriptions works as intended. "
+                "It is deliberately verbose (well over 500 characters) so the Tools & Integrations UI can show an info icon, "
+                "an expandable description panel, and a truncated rendering (start + '...' + end) for very long descriptions. "
+                "Additional filler to ensure we exceed the truncation threshold: Lorem ipsum dolor sit amet, consectetur adipiscing elit. "
+                "Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation. "
+                "End marker: the UI should still show this ending segment after truncation."
+            ),
+            "type": "system_prompt",
+            "category": "demo"
+        }
+    }
+
+    return {
+        "results": {
+            "available_prompts": prompts,
+            "total_count": len(prompts),
+            "categories": list(set(p["category"] for p in prompts.values()))
+        }
+    }
+
+
+if __name__ == "__main__":
+    mcp.run()

atlas/mcp/public_demo/main.py

@@ -0,0 +1,189 @@
+#!/usr/bin/env python3
+"""
+Public Demo MCP Server - No Authentication Required
+
+This server demonstrates tools that are publicly accessible without any
+authentication. Use this as an example of a server that anyone can use.
+
+Authentication Type: none
+Transport: stdio, http, or sse
+
+Updated: 2025-01-21
+"""
+
+import hashlib
+import random
+import time
+from datetime import datetime, timezone
+from typing import Any
+
+from fastmcp import FastMCP
+
+mcp = FastMCP("Public Demo")
+
+
+@mcp.tool
+def get_server_time() -> dict[str, Any]:
+    """
+    Get the current server time in various formats.
+
+    This tool is publicly accessible - no authentication required.
+    Useful for testing connectivity and server responsiveness.
+    """
+    start = time.perf_counter()
+    now = datetime.now(timezone.utc)
+
+    return {
+        "results": {
+            "utc_iso": now.isoformat(),
+            "utc_timestamp": int(now.timestamp()),
+            "formatted": now.strftime("%Y-%m-%d %H:%M:%S UTC"),
+            "day_of_week": now.strftime("%A"),
+            "timezone": "UTC"
+        },
+        "meta_data": {
+            "is_error": False,
+            "elapsed_ms": round((time.perf_counter() - start) * 1000, 2),
+            "auth_required": False
+        }
+    }
+
+
+@mcp.tool
+def generate_uuid() -> dict[str, Any]:
+    """
+    Generate a random UUID (version 4).
+
+    This tool is publicly accessible - no authentication required.
+    Useful for generating unique identifiers.
+    """
+    import uuid
+    start = time.perf_counter()
+
+    new_uuid = str(uuid.uuid4())
+
+    return {
+        "results": {
+            "uuid": new_uuid,
+            "uuid_hex": new_uuid.replace("-", ""),
+            "version": 4
+        },
+        "meta_data": {
+            "is_error": False,
+            "elapsed_ms": round((time.perf_counter() - start) * 1000, 2),
+            "auth_required": False
+        }
+    }
+
+
+@mcp.tool
+def hash_text(text: str, algorithm: str = "sha256") -> dict[str, Any]:
+    """
+    Hash text using a specified algorithm.
+
+    This tool is publicly accessible - no authentication required.
+
+    Args:
+        text: The text to hash
+        algorithm: Hash algorithm (md5, sha1, sha256, sha512). Default: sha256
+    """
+    start = time.perf_counter()
+
+    valid_algorithms = ["md5", "sha1", "sha256", "sha512"]
+    if algorithm.lower() not in valid_algorithms:
+        return {
+            "results": None,
+            "meta_data": {
+                "is_error": True,
+                "error_message": f"Invalid algorithm. Choose from: {', '.join(valid_algorithms)}",
+                "elapsed_ms": round((time.perf_counter() - start) * 1000, 2),
+                "auth_required": False
+            }
+        }
+
+    hash_obj = hashlib.new(algorithm.lower())
+    hash_obj.update(text.encode('utf-8'))
+    hash_result = hash_obj.hexdigest()
+
+    return {
+        "results": {
+            "input_text": text[:50] + "..." if len(text) > 50 else text,
+            "algorithm": algorithm.lower(),
+            "hash": hash_result,
+            "hash_length": len(hash_result)
+        },
+        "meta_data": {
+            "is_error": False,
+            "elapsed_ms": round((time.perf_counter() - start) * 1000, 2),
+            "auth_required": False
+        }
+    }
+
+
+@mcp.tool
+def random_number(min_value: int = 1, max_value: int = 100) -> dict[str, Any]:
+    """
+    Generate a random integer within a range.
+
+    This tool is publicly accessible - no authentication required.
+
+    Args:
+        min_value: Minimum value (inclusive). Default: 1
+        max_value: Maximum value (inclusive). Default: 100
+    """
+    start = time.perf_counter()
+
+    if min_value > max_value:
+        return {
+            "results": None,
+            "meta_data": {
+                "is_error": True,
+                "error_message": "min_value must be less than or equal to max_value",
+                "elapsed_ms": round((time.perf_counter() - start) * 1000, 2),
+                "auth_required": False
+            }
+        }
+
+    result = random.randint(min_value, max_value)
+
+    return {
+        "results": {
+            "number": result,
+            "range": f"[{min_value}, {max_value}]"
+        },
+        "meta_data": {
+            "is_error": False,
+            "elapsed_ms": round((time.perf_counter() - start) * 1000, 2),
+            "auth_required": False
+        }
+    }
+
+
+@mcp.tool
+def echo(message: str) -> dict[str, Any]:
+    """
+    Echo back a message - simple connectivity test.
+
+    This tool is publicly accessible - no authentication required.
+
+    Args:
+        message: The message to echo back
+    """
+    start = time.perf_counter()
+
+    return {
+        "results": {
+            "echo": message,
+            "length": len(message),
+            "server": "public_demo"
+        },
+        "meta_data": {
+            "is_error": False,
+            "elapsed_ms": round((time.perf_counter() - start) * 1000, 2),
+            "auth_required": False
+        }
+    }
+
+
+if __name__ == "__main__":
+    mcp.run()

atlas/mcp/sampling_demo/README.md

@@ -0,0 +1,169 @@
+# Sampling Demo MCP Server
+
+This MCP server demonstrates **LLM sampling** capabilities introduced in FastMCP 2.0.0+. Sampling allows tools to request text generation from an LLM during execution, enabling AI-powered analysis, generation, reasoning, and more without the client needing to orchestrate multiple calls.
+
+## Overview
+
+LLM sampling enables interactive workflows where tools can:
+- Request LLM text generation mid-execution
+- Build multi-turn conversations with context
+- Leverage AI capabilities for analysis and generation
+- Implement agentic workflows with reasoning
+- Control generation parameters (temperature, max_tokens, model preferences)
+
+## Available Tools
+
+### Basic Sampling
+
+1. **`summarize_text(text)`** - Text Summarization
+   - Demonstrates basic LLM sampling
+   - Requests the LLM to generate a concise summary
+   - Uses simple prompt without additional parameters
+
+2. **`analyze_sentiment(text)`** - Sentiment Analysis
+   - Demonstrates sampling with system prompts
+   - Uses lower temperature (0.3) for consistent analysis
+   - System prompt establishes LLM role as sentiment analyzer
+
+3. **`generate_code(description, language)`** - Code Generation
+   - Demonstrates sampling with model preferences
+   - Hints which models should be preferred (gpt-4, claude-3-sonnet, etc.)
+   - Uses higher max_tokens (1000) for code generation
+
+4. **`creative_story(prompt)`** - Creative Writing
+   - Demonstrates high temperature sampling for creativity
+   - Uses temperature=0.9 for varied, creative outputs
+   - Limited to 500 tokens for short stories
+
+### Advanced Sampling
+
+5. **`multi_turn_conversation(topic)`** - Multi-turn Conversation
+   - Demonstrates maintaining conversation context
+   - Multiple sequential sampling calls with message history
+   - Builds up conversation across sampling requests
+
+6. **`research_question(question)`** - Agentic Research
+   - Demonstrates agentic workflow with sampling
+   - Multiple sampling calls to break down and answer questions
+   - Shows complex reasoning and synthesis
+
+7. **`translate_and_explain(text, target_language)`** - Sequential Tasks
+   - Demonstrates multi-step workflows
+   - First sampling for translation, second for explanation
+   - Shows how to chain sampling results
+
+## Usage Examples
+
+### In Atlas UI Chat
+
+After the sampling_demo server is enabled, you can test it with prompts like:
+
+```
+"Summarize this text using the sampling demo: [your text]"
+"Analyze the sentiment of this review: [review text]"
+"Generate Python code that calculates fibonacci numbers"
+"Write a creative story about a robot learning to paint"
+"Have a conversation about artificial intelligence"
+"Research this question: What are the benefits of renewable energy?"
+"Translate 'Hello, how are you?' to Spanish and explain the choices"
+```
+
+## Technical Details
+
+### Sampling Parameters
+
+Tools can control LLM generation with parameters:
+
+- **messages**: Simple string or list of SamplingMessage objects for multi-turn
+- **system_prompt**: Establishes LLM role and behavior
+- **temperature**: Controls randomness (0.0 = deterministic, 1.0 = creative)
+- **max_tokens**: Maximum tokens to generate (default: 512)
+- **model_preferences**: Hints for which models the client should prefer
+
+### Sampling Flow
+
+1. Tool calls `ctx.sample()` with parameters
+2. FastMCP client sends sampling request to Atlas backend
+3. Backend's sampling handler routes request to configured LLM (via LiteLLM)
+4. LLM generates response based on parameters
+5. Response is returned to the tool execution
+6. Tool processes and returns result to user
+
+### Model Selection
+
+The sampling handler selects models based on:
+1. **Model preferences** provided in the sampling request
+2. **Configured models** in Atlas llmconfig.yml
+3. **Default model** as fallback
+
+Model preferences are hints, not requirements. The backend uses the first matching configured model or falls back to the default.
+
+## Configuration
+
+This server is configured in `config/overrides/mcp.json`:
+
+```json
+{
+  "sampling_demo": {
+    "command": ["python", "mcp/sampling_demo/main.py"],
+    "cwd": "atlas",
+    "groups": ["users"],
+    "description": "Demonstrates MCP LLM sampling capabilities...",
+    "compliance_level": "Public"
+  }
+}
+```
+
+## Development
+
+To run the server standalone for testing:
+
+```bash
+cd atlas
+python mcp/sampling_demo/main.py
+```
+
+The FastMCP framework will display available tools and their schemas.
+
+## References
+
+- [FastMCP Sampling Documentation](https://gofastmcp.com/clients/sampling)
+- [MCP Specification - Sampling](https://spec.modelcontextprotocol.io/)
+- FastMCP Version: 2.0.0+
+
+## Example Tool Implementation
+
+```python
+from fastmcp import FastMCP, Context
+
+mcp = FastMCP("My Server")
+
+@mcp.tool
+async def analyze_text(text: str, ctx: Context) -> str:
+    """Analyze text using LLM sampling."""
+    result = await ctx.sample(
+        messages=f"Analyze this text: {text}",
+        system_prompt="You are an expert analyst.",
+        temperature=0.5,
+        max_tokens=500
+    )
+    return result.text or "Analysis failed"
+```
+
+## Comparison with Elicitation
+
+| Feature | Elicitation | Sampling |
+|---------|------------|----------|
+| Purpose | Get user input | Get LLM generation |
+| Who responds | Human user | LLM model |
+| Use cases | Forms, confirmations | Analysis, generation |
+| Timeout | 5 minutes | 5 minutes |
+| Multiple turns | Supported | Supported |
+| Parameters | Response schema | Temperature, max_tokens, model preferences |
+
+## Support
+
+For issues or questions about sampling:
+- Check Atlas UI documentation in `/docs` folder
+- Review FastMCP sampling docs at https://gofastmcp.com
+- Report bugs via GitHub issues