snowglobe 0.4.0__py3-none-any.whl

snowglobe/client/src/project_manager.py

@@ -0,0 +1,290 @@
+"""
+Project and agent management for the new clean file structure
+"""
+
+import json
+import os
+import re
+from datetime import datetime
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple
+
+SNOWGLOBE_DIR = ".snowglobe"
+AGENTS_FILE = "agents.json"
+CONFIG_FILE = "config.json"
+
+
+class ProjectManager:
+    """Manages snowglobe project structure and agent mappings"""
+
+    def __init__(self, project_root: str = None):
+        self.project_root = Path(project_root or os.getcwd())
+        self.snowglobe_dir = self.project_root / SNOWGLOBE_DIR
+        self.agents_file = self.snowglobe_dir / AGENTS_FILE
+        self.config_file = self.snowglobe_dir / CONFIG_FILE
+
+    def ensure_project_structure(self) -> None:
+        """Create .snowglobe directory if it doesn't exist"""
+        self.snowglobe_dir.mkdir(exist_ok=True)
+
+        # Create agents.json if it doesn't exist
+        if not self.agents_file.exists():
+            with open(self.agents_file, "w") as f:
+                json.dump({}, f, indent=2)
+
+    def load_agents_mapping(self) -> Dict[str, Dict[str, Any]]:
+        """Load agent UUID mappings from .snowglobe/agents.json"""
+        if not self.agents_file.exists():
+            return {}
+
+        try:
+            with open(self.agents_file, "r") as f:
+                return json.load(f)
+        except (json.JSONDecodeError, IOError):
+            # Return empty dict if file is corrupted
+            return {}
+
+    def save_agents_mapping(self, mapping: Dict[str, Dict[str, Any]]) -> None:
+        """Save agent UUID mappings to .snowglobe/agents.json"""
+        # Only ensure directory exists, not the full structure to avoid recursion
+        self.snowglobe_dir.mkdir(exist_ok=True)
+
+        with open(self.agents_file, "w") as f:
+            json.dump(mapping, f, indent=2, sort_keys=True)
+
+    def add_agent_mapping(self, filename: str, uuid: str, name: str) -> None:
+        """Add a new agent mapping"""
+        mapping = self.load_agents_mapping()
+
+        mapping[filename] = {
+            "uuid": uuid,
+            "name": name,
+            "created": datetime.utcnow().isoformat() + "Z",
+        }
+
+        self.save_agents_mapping(mapping)
+
+    def get_agent_by_filename(self, filename: str) -> Optional[Dict[str, Any]]:
+        """Get agent info by filename"""
+        mapping = self.load_agents_mapping()
+        return mapping.get(filename)
+
+    def get_agent_by_uuid(self, uuid: str) -> Optional[Tuple[str, Dict[str, Any]]]:
+        """Get agent filename and info by UUID"""
+        mapping = self.load_agents_mapping()
+
+        for filename, info in mapping.items():
+            if info.get("uuid") == uuid:
+                return filename, info
+
+        return None
+
+    def list_agents(self) -> List[Tuple[str, Dict[str, Any]]]:
+        """List all agents in the project"""
+        mapping = self.load_agents_mapping()
+        agents = []
+
+        for filename, info in mapping.items():
+            # Check if the file actually exists
+            file_path = self.project_root / filename
+            if file_path.exists():
+                agents.append((filename, info))
+
+        return agents
+
+    def remove_agent_mapping(self, filename: str) -> bool:
+        """Remove an agent mapping"""
+        mapping = self.load_agents_mapping()
+
+        if filename in mapping:
+            del mapping[filename]
+            self.save_agents_mapping(mapping)
+            return True
+
+        return False
+
+    def sanitize_filename(self, name: str, default: str = "agent_wrapper") -> str:
+        """Convert agent name to safe filename"""
+        if not name or not name.strip():
+            return f"{default}.py"
+
+        # Replace spaces and special chars with underscores
+        safe_name = re.sub(r"[^\w\s-]", "", name)
+        safe_name = re.sub(r"[-\s]+", "_", safe_name)
+        safe_name = safe_name.lower().strip("_")
+
+        # Ensure it's not empty and has .py extension
+        if not safe_name:
+            safe_name = default
+
+        return f"{safe_name}.py"
+
+    def find_available_filename(self, preferred_name: str) -> str:
+        """Find an available filename, adding numbers if needed"""
+        base_name = preferred_name
+        if base_name.endswith(".py"):
+            base_name = base_name[:-3]
+
+        counter = 1
+        filename = f"{base_name}.py"
+
+        while (self.project_root / filename).exists():
+            filename = f"{base_name}_{counter}.py"
+            counter += 1
+
+        return filename
+
+    def load_config(self) -> Dict[str, Any]:
+        """Load configuration from .snowglobe/config.json"""
+        if not self.config_file.exists():
+            return {}
+
+        try:
+            with open(self.config_file, "r") as f:
+                return json.load(f)
+        except (json.JSONDecodeError, IOError):
+            return {}
+
+    def save_config(self, config: Dict[str, Any]) -> None:
+        """Save configuration to .snowglobe/config.json"""
+        self.snowglobe_dir.mkdir(exist_ok=True)
+
+        with open(self.config_file, "w") as f:
+            json.dump(config, f, indent=2, sort_keys=True)
+
+    def get_api_key(self) -> Optional[str]:
+        """Get API key from config or environment"""
+        # Check environment first
+        api_key = os.getenv("SNOWGLOBE_API_KEY") or os.getenv("GUARDRAILS_API_KEY")
+        if api_key:
+            return api_key
+
+        # Check .snowglobe/config.json
+        config = self.load_config()
+        api_key = config.get("api_key")
+        if api_key:
+            return api_key
+
+        # Check legacy .snowgloberc in current directory
+        rc_path = self.project_root / ".snowgloberc"
+        if rc_path.exists():
+            try:
+                with open(rc_path, "r") as f:
+                    for line in f:
+                        if line.startswith("SNOWGLOBE_API_KEY="):
+                            return line.strip().split("=", 1)[1]
+            except IOError:
+                pass
+
+        return None
+
+    def set_api_key(self, api_key: str) -> None:
+        """Set API key in config"""
+        config = self.load_config()
+        config["api_key"] = api_key
+        self.save_config(config)
+
+    def get_control_plane_url(self) -> str:
+        """Get control plane URL from config or environment"""
+        # Check environment first
+        url = os.getenv("CONTROL_PLANE_URL")
+        if url:
+            return url
+
+        # Check .snowglobe/config.json
+        config = self.load_config()
+        url = config.get("control_plane_url")
+        if url:
+            return url
+
+        # Check legacy .snowgloberc in current directory
+        rc_path = self.project_root / ".snowgloberc"
+        if rc_path.exists():
+            try:
+                with open(rc_path, "r") as f:
+                    for line in f:
+                        if line.startswith("CONTROL_PLANE_URL="):
+                            return line.strip().split("=", 1)[1]
+            except IOError:
+                pass
+
+        return "https://api.snowglobe.guardrailsai.com"
+
+    def set_control_plane_url(self, url: str) -> None:
+        """Set control plane URL in config"""
+        config = self.load_config()
+        config["control_plane_url"] = url
+        self.save_config(config)
+
+    def migrate_legacy_config(self) -> bool:
+        """Migrate .snowgloberc to .snowglobe/config.json"""
+        rc_path = self.project_root / ".snowgloberc"
+        if not rc_path.exists():
+            return False
+
+        config = self.load_config()
+        migrated = False
+
+        try:
+            with open(rc_path, "r") as f:
+                for line in f:
+                    line = line.strip()
+                    if line.startswith("SNOWGLOBE_API_KEY="):
+                        api_key = line.split("=", 1)[1]
+                        if api_key and not config.get("api_key"):
+                            config["api_key"] = api_key
+                            migrated = True
+                    elif line.startswith("CONTROL_PLANE_URL="):
+                        url = line.split("=", 1)[1]
+                        if url and not config.get("control_plane_url"):
+                            config["control_plane_url"] = url
+                            migrated = True
+
+            if migrated:
+                self.save_config(config)
+                # Optionally remove the old file
+                # rc_path.unlink()  # Uncomment to delete legacy file
+
+            return migrated
+        except IOError:
+            return False
+
+    def validate_project(self) -> Tuple[bool, List[str]]:
+        """Validate project structure and return issues"""
+        issues = []
+
+        # Check if .snowglobe directory exists
+        if not self.snowglobe_dir.exists():
+            issues.append(
+                "No .snowglobe directory found. Run 'snowglobe-connect init' to set up."
+            )
+            return False, issues
+
+        # Check if agents.json exists and is valid
+        if not self.agents_file.exists():
+            issues.append("No agents.json file found in .snowglobe/")
+        else:
+            try:
+                mapping = self.load_agents_mapping()
+
+                # Check for orphaned files
+                for filename in mapping.keys():
+                    file_path = self.project_root / filename
+                    if not file_path.exists():
+                        issues.append(f"Agent file missing: {filename}")
+
+                # Check for unmapped agent files
+                for py_file in self.project_root.glob("*_wrapper.py"):
+                    if py_file.name not in mapping:
+                        issues.append(f"Unmapped agent file found: {py_file.name}")
+
+            except Exception as e:
+                issues.append(f"Invalid agents.json file: {e}")
+
+        is_valid = len(issues) == 0
+        return is_valid, issues
+
+
+def get_project_manager(project_root: str = None) -> ProjectManager:
+    """Get a ProjectManager instance"""
+    return ProjectManager(project_root)

snowglobe/client/src/stats.py

@@ -0,0 +1,53 @@
+"""
+Shared statistics tracking for Snowglobe client.
+This module avoids circular imports by providing a neutral location
+for stats that both app.py and cli.py need to access.
+"""
+
+import datetime
+
+# Tracking state
+ui_stats = {
+    "last_activity_time": None,
+    "start_time": None,
+    "total_messages": 0,
+    "experiment_totals": {},  # experiment_name -> total_count
+}
+
+
+def initialize_stats():
+    """Initialize stats tracking when server starts"""
+    ui_stats["start_time"] = datetime.datetime.now()
+
+
+def track_batch_completion(experiment_name: str, count: int):
+    """Track completed batch of scenarios"""
+    ui_stats["total_messages"] += count
+    if experiment_name not in ui_stats["experiment_totals"]:
+        ui_stats["experiment_totals"][experiment_name] = 0
+    ui_stats["experiment_totals"][experiment_name] += count
+    ui_stats["last_activity_time"] = datetime.datetime.now()
+
+
+def get_shutdown_stats():
+    """Get stats for graceful shutdown summary"""
+    if not ui_stats["start_time"]:
+        return None
+
+    uptime = datetime.datetime.now() - ui_stats["start_time"]
+    hours = int(uptime.total_seconds() // 3600)
+    minutes = int((uptime.total_seconds() % 3600) // 60)
+    seconds = int(uptime.total_seconds() % 60)
+
+    if hours > 0:
+        uptime_str = f"{hours}h {minutes}m {seconds}s"
+    elif minutes > 0:
+        uptime_str = f"{minutes}m {seconds}s"
+    else:
+        uptime_str = f"{seconds}s"
+
+    return {
+        "total_messages": ui_stats["total_messages"],
+        "experiment_totals": ui_stats["experiment_totals"],
+        "uptime": uptime_str,
+    }

snowglobe/client/src/utils.py

@@ -0,0 +1,117 @@
+from logging import getLogger
+
+import httpx
+
+from .config import config
+from .models import SnowglobeData, SnowglobeMessage
+
+LOGGER = getLogger(__name__)
+
+
+async def fetch_experiments(app_id: str = None) -> list[dict]:
+    """
+    Fetch experiments from the Snowglobe server.
+
+    Returns:
+        list[dict]: A list of experiments.
+    """
+    async with httpx.AsyncClient() as client:
+        experiments_url = f"{config.CONTROL_PLANE_URL}/api/experiments?&evaluated=false"
+        if app_id:
+            experiments_url += f"&appId={config.APPLICATION_ID}"
+        experiments_response = await client.get(
+            experiments_url,
+            headers={"x-api-key": config.API_KEY},
+        )
+
+    if not experiments_response.status_code == 200:
+        try:
+            message = experiments_response.json().get("message")
+        except Exception:
+            message = experiments_response.text
+        LOGGER.error(f"Error fetching experiments: {message}")
+        raise Exception(
+            f"{experiments_response.status_code} - {message or 'Unknown error'}"
+        )
+    experiments = experiments_response.json()
+    return experiments
+
+
+async def fetch_messages(*, test) -> list[SnowglobeMessage]:
+    """
+    Fetch messages from the Snowglobe server for a given test.
+
+    Args:
+        test (str): The test identifier.
+
+    Returns:
+        list[SnowglobeMessage]: A list of messages associated with the test.
+    """
+    # init messages
+    messages = [
+        SnowglobeMessage(
+            role="user",
+            content=test["prompt"],
+            snowglobe_data=SnowglobeData(
+                conversation_id=test["conversation_id"],
+                test_id=test["id"],
+            ),
+        ),
+    ]
+    # if full turn append response
+    if "response" in test and test["response"]:
+        messages.append(
+            SnowglobeMessage(
+                role="assistant",
+                content=test["response"],
+                snowglobe_data=SnowglobeData(
+                    conversation_id=test["conversation_id"],
+                    test_id=test["id"],
+                ),
+            )
+        )
+
+    # build rest of messages
+    parent_id = test.get("parent_test_id")
+    async with httpx.AsyncClient() as client:
+        while parent_id:
+            # get parent test
+            parent_test_response = await client.get(
+                f"{config.CONTROL_PLANE_URL}/api/experiments/{test['experiment_id']}/tests/{parent_id}",
+                headers={"x-api-key": config.API_KEY},
+            )
+
+            if not parent_test_response.status_code == 200:
+                raise Exception(
+                    f"Error fetching parent test {parent_id}: {parent_test_response.text}"
+                )
+
+            parent_test = parent_test_response.json()
+
+            parent_id = parent_test.get("parent_test_id")
+
+            messages.insert(
+                0,
+                SnowglobeMessage(
+                    role="assistant",
+                    content=parent_test["response"],
+                    snowglobe_data=SnowglobeData(
+                        conversation_id=parent_test["conversation_id"],
+                        test_id=parent_test["id"],
+                    ),
+                ),
+            )
+
+            messages.insert(
+                0,
+                SnowglobeMessage(
+                    role="user",
+                    content=parent_test["prompt"],
+                    snowglobe_data=SnowglobeData(
+                        conversation_id=parent_test["conversation_id"],
+                        test_id=parent_test["id"],
+                    ),
+                ),
+            )
+
+    return messages

snowglobe-0.4.0.dist-info/METADATA

@@ -0,0 +1,128 @@
+Metadata-Version: 2.4
+Name: snowglobe
+Version: 0.4.0
+Summary: client server for usage with snowglobe experiments
+Author-email: Guardrails AI <contact@guardrailsai.com>
+License: MIT License
+        
+        Copyright (c) 2024 Guardrails AI
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typer>=0.9.0
+Requires-Dist: fastapi>=0.115.6
+Requires-Dist: uvicorn[standard]>=0.23.0
+Requires-Dist: requests>=2.31.0
+Requires-Dist: pydantic>=2.11.5
+Requires-Dist: APScheduler==4.0.0a6
+Requires-Dist: httpx==0.28.1
+Requires-Dist: rich>=13.0.0
+Provides-Extra: dev
+Requires-Dist: ruff<0.2.0,>=0.1.0; extra == "dev"
+Requires-Dist: mypy<2.0.0,>=1.5.0; extra == "dev"
+Requires-Dist: pre-commit>=4.1.0; extra == "dev"
+Requires-Dist: coverage>=7.6.12; extra == "dev"
+Dynamic: license-file
+
+# Snowlgobe Connect SDK
+
+The Snowglobe Connect SDK helps you connect your AI agents to Snowglobe. It sends simulated user messages to your LLM-based application during experiments. Your application should process these messages and return a response, enabling simulated conversations and custom code based risk assessment.
+
+## Installation
+
+```bash
+# Paste Guardrails Client or extract from guardrailsrc
+export GUARDRAILS_TOKEN=$(cat ~/.guardrailsrc| awk -F 'token=' '{print $2}' | awk '{print $1}' | tr -d '\n')
+```
+
+```
+# Install client
+pip install -U --index-url="https://__token__:$GUARDRAILS_TOKEN@pypi.guardrailsai.com/simple" \
+    --extra-index-url="https://pypi.org/simple" snowglobe-connect
+```
+
+If using uv, set the `--prerelease=allow` flag
+```
+pip install -U --index-url="https://__token__:$GUARDRAILS_TOKEN@pypi.guardrailsai.com/simple" \
+    --extra-index-url="https://pypi.org/simple" --prerelease=allow snowglobe-connect
+```
+
+
+## `snowglobe-connect` commands
+
+```bash
+snowglobe-connect auth  # Sets up your API key
+snowglobe-connect init  # Initializes a new agent connection and creates an agent wrapper file
+snowglobe-connect test  # Tests your agent connection
+snowglobe-connect start  # Starts the process of processing simulated user messages
+snowglobe-connect --help
+```
+
+When using one of our specific preview environments in .snowgloberc one can override our server's URL with:
+
+```bash
+CONTROL_PLANE_URL=
+```
+
+## Sample custom llm usage in agent wrapper file
+
+Each agent wrapper file resides in the root directory of your project, and is named after the agent (e.g. `My Agent Name` becomes `my_agent_name.py`).
+
+```python
+from snowglobe.client import CompletionRequest, CompletionFunctionOutputs
+from openai import OpenAI
+import os
+
+client = OpenAI(api_key=os.getenv("SNOWGLOBE_API_KEY"))
+
+def process_scenario(request: CompletionRequest) -> CompletionFunctionOutputs:
+    """
+    Process a scenario request from Snowglobe.
+    
+    This function is called by the Snowglobe client to process requests. It should return a
+    CompletionFunctionOutputs object with the response content.
+
+    Example CompletionRequest:
+    CompletionRequest(
+        messages=[
+            SnowglobeMessage(role="user", content="Hello, how are you?", snowglobe_data=None),
+        ]
+    )
+
+    Example CompletionFunctionOutputs:
+    CompletionFunctionOutputs(response="This is a string response from your application")
+    
+    Args:
+        request (CompletionRequest): The request object containing the messages.
+
+    Returns:
+        CompletionFunctionOutputs: The response object with the generated content.
+    """
+
+    # Process the request using the messages. Example:
+    messages = request.to_openai_messages()
+    response = client.chat.completions.create(
+        model="gpt-4o-mini",
+        messages=messages
+    )
+    return CompletionFunctionOutputs(response=response.choices[0].message.content)
+```

snowglobe-0.4.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+snowglobe/client/__init__.py,sha256=kzp9wPUUYBXqDSKZbfmD4vrAQvrWSW5HOvtpFlEJWfs,353
+snowglobe/client/src/app.py,sha256=PZCTwF3n_2Bi825dOflGeN8GSjuf5ebKLSxV7S90TxA,30289
+snowglobe/client/src/cli.py,sha256=f8AKB0mAcMK-63aZczs4LxnB33RqoxKPEnv2w1lgu1c,25159
+snowglobe/client/src/cli_utils.py,sha256=PRWpbrALfTc3fpAXl32pfyZWkLYi_3N03csTQR1wnjc,11911
+snowglobe/client/src/config.py,sha256=HAJD7RkO6IB_mFkmGLpy9Ma3sB0KpZE7zmGsa9K__iE,9284
+snowglobe/client/src/models.py,sha256=BX310WrDN9Fd8v68me3XGL_ic1ulvjCrZyIT2ND1eUo,866
+snowglobe/client/src/project_manager.py,sha256=Ze-qs4dQI2kIV-PmtWZ1b67hMUfsnsMHus90aT8HOow,9970
+snowglobe/client/src/stats.py,sha256=IdaXroOZBmvLVa_p9pDE6hsxsc7-fBEDnLf8O6Ch0GA,1596
+snowglobe/client/src/utils.py,sha256=U0nQjTjO28OghG7lV6BuI_2MkcsOhu31Nz00nCJU4sM,3670
+snowglobe-0.4.0.dist-info/licenses/LICENSE,sha256=S90V6iFU5ZeSg44JQYS1To3pa7ZEobrHc_t483qSKSI,1070
+snowglobe-0.4.0.dist-info/METADATA,sha256=OEuNnqFkNHhu3z0cgORX17kyKGOhoAvo7IxUfkopMTM,4921
+snowglobe-0.4.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+snowglobe-0.4.0.dist-info/entry_points.txt,sha256=mqx4mTwFPHttjctE2ceYTYWCCIG30Ji2C89aaCYgHcM,71
+snowglobe-0.4.0.dist-info/top_level.txt,sha256=PoyYihnCBjRyjeIT19yBcE47JTe7i1OwRXvJ4d5EohM,10
+snowglobe-0.4.0.dist-info/RECORD,,

snowglobe-0.4.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

snowglobe-0.4.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+snowglobe-connect = snowglobe.client.src.cli:cli_app

snowglobe-0.4.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Guardrails AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

snowglobe-0.4.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+snowglobe