agentex-sdk 0.4.0__py3-none-any.whl → 0.4.1__py3-none-any.whl

agentex/lib/cli/utils/auth_utils.py

@@ -1,16 +1,56 @@
 import base64
 import json
+from typing import Any, Dict
 
 from agentex.lib.sdk.config.agent_manifest import AgentManifest
+from agentex.lib.sdk.config.environment_config import AgentAuthConfig
 
+# DEPRECATED: Old function for backward compatibility
+# Will be removed in future version
+def _encode_principal_context(manifest: AgentManifest) -> str | None:
+    """
+    DEPRECATED: This function is deprecated as AgentManifest no longer contains auth.
+    Use _encode_principal_context_from_env_config instead.
+    
+    This function is kept temporarily for backward compatibility during migration.
+    """
+    # AgentManifest no longer has auth field - this will always return None
+    return None
 
-# Base 64 encode principal dictionary
-def _encode_principal_context(manifest: AgentManifest):
-    if manifest.auth is None:
+
+def _encode_principal_context_from_env_config(auth_config: "AgentAuthConfig | None") -> str | None:
+    """
+    Encode principal context from environment configuration.
+    
+    Args:
+        auth_config: AgentAuthConfig containing principal configuration
+        
+    Returns:
+        Base64-encoded JSON string of the principal, or None if no principal
+    """
+    if auth_config is None:
+        return None
+    
+    principal = auth_config.principal
+    if not principal:
         return None
 
-    principal = manifest.auth.principal
-    if principal is None:
+    json_str = json.dumps(principal, separators=(',', ':'))
+    encoded_bytes = base64.b64encode(json_str.encode('utf-8'))
+    return encoded_bytes.decode('utf-8')
+
+
+def _encode_principal_dict(principal: Dict[str, Any]) -> str | None:
+    """
+    Encode principal dictionary directly.
+    
+    Args:
+        principal: Dictionary containing principal configuration
+        
+    Returns:
+        Base64-encoded JSON string of the principal, or None if principal is empty
+    """
+    if not principal:
         return None
 
     json_str = json.dumps(principal, separators=(',', ':'))

agentex/lib/core/services/adk/providers/openai.py

@@ -656,7 +656,7 @@ class OpenAIService:
                                 reasoning_content = ReasoningContent(
                                     author="agent",
                                     summary=[summary.text for summary in reasoning_item.summary],
-                                    content=[content.text for content in reasoning_item.content] if reasoning_item.content else None,
+                                    content=[content.text for content in reasoning_item.content] if hasattr(reasoning_item, "content") else None,
                                 )
 
                                 # Create reasoning content using streaming context (immediate completion)

agentex/lib/sdk/config/agent_manifest.py

@@ -15,7 +15,8 @@ from pydantic import Field
 
 from agentex.lib.sdk.config.agent_config import AgentConfig
 from agentex.lib.sdk.config.build_config import BuildConfig
-from agentex.lib.sdk.config.deployment_config import DeploymentConfig, AuthenticationConfig
+from agentex.lib.sdk.config.environment_config import AgentEnvironmentsConfig
+from agentex.lib.sdk.config.deployment_config import DeploymentConfig
 from agentex.lib.sdk.config.local_development_config import LocalDevelopmentConfig
 from agentex.lib.utils.logging import make_logger
 from agentex.lib.utils.model_utils import BaseModel
@@ -36,7 +37,7 @@ class AgentManifest(BaseModel):
     deployment: DeploymentConfig | None = Field(
         default=None, description="Deployment configuration for the agent"
     )
-    auth: AuthenticationConfig | None = Field(default=None, description="Authentication configuration")
+
 
     def context_manager(self, build_context_root: Path) -> BuildContextManager:
         """
@@ -45,6 +46,23 @@ class AgentManifest(BaseModel):
         return BuildContextManager(
             agent_manifest=self, build_context_root=build_context_root
         )
+    
+    def load_environments_config(self, manifest_dir: Path) -> "AgentEnvironmentsConfig | None":
+        """Load environments.yaml from same directory as manifest.yaml.
+        
+        Args:
+            manifest_dir: Directory containing manifest.yaml
+            
+        Returns:
+            AgentEnvironmentsConfig if environments.yaml exists, None otherwise
+            
+        Raises:
+            ValueError: If environments.yaml exists but is invalid
+        """
+        # Import here to avoid circular imports
+        from agentex.lib.sdk.config.environment_config import load_environments_config_from_manifest_dir
+        
+        return load_environments_config_from_manifest_dir(manifest_dir)
 
 
 class BuildContextManager:

agentex/lib/sdk/config/environment_config.py

@@ -0,0 +1,188 @@
+"""
+Environment-specific configuration models for agent deployments.
+
+This module provides Pydantic models for managing environment-specific
+configurations that are separate from the main manifest.yaml file.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Dict, override
+
+import yaml
+from pydantic import BaseModel, Field, field_validator
+
+from agentex.lib.utils.model_utils import BaseModel as UtilsBaseModel
+
+
+class AgentAuthConfig(BaseModel):
+    """Authentication configuration for an agent in a specific environment."""
+    
+    principal: Dict[str, Any] = Field(
+        ..., 
+        description="Principal configuration for agent authorization and registration"
+    )
+    
+    @field_validator('principal')
+    @classmethod
+    def validate_principal_required_fields(cls, v: Any) -> Dict[str, Any]:
+        """Ensure principal has required fields for agent registration."""
+        if not isinstance(v, dict):
+            raise ValueError("Principal must be a dictionary")
+        return v
+
+
+class AgentKubernetesConfig(BaseModel):
+    """Kubernetes configuration for an agent in a specific environment."""
+    
+    namespace: str = Field(
+        ..., 
+        description="Kubernetes namespace where the agent will be deployed"
+    )
+    
+    @field_validator('namespace')
+    @classmethod
+    def validate_namespace_format(cls, v: str) -> str:
+        """Ensure namespace follows Kubernetes naming conventions."""
+        if not v or not v.strip():
+            raise ValueError("Namespace cannot be empty")
+        
+        # Basic Kubernetes namespace validation
+        namespace = v.strip().lower()
+        if not namespace.replace('-', '').replace('.', '').isalnum():
+            raise ValueError(
+                f"Namespace '{v}' must contain only lowercase letters, numbers, "
+                "hyphens, and periods"
+            )
+        
+        if len(namespace) > 63:
+            raise ValueError(f"Namespace '{v}' cannot exceed 63 characters")
+        
+        return namespace
+
+
+class AgentEnvironmentConfig(BaseModel):
+    """Complete configuration for an agent in a specific environment."""
+    
+    kubernetes: AgentKubernetesConfig | None = Field(
+        default=None, 
+        description="Kubernetes deployment configuration"
+    )
+    auth: AgentAuthConfig = Field(
+        ..., 
+        description="Authentication and authorization configuration"
+    )
+    helm_overrides: Dict[str, Any] = Field(
+        default_factory=dict, 
+        description="Helm chart value overrides for environment-specific tuning"
+    )
+
+
+class AgentEnvironmentsConfig(UtilsBaseModel):
+    """All environment configurations for an agent."""
+    
+    schema_version: str = Field(
+        default="v1", 
+        description="Schema version for validation and compatibility"
+    )
+    environments: Dict[str, AgentEnvironmentConfig] = Field(
+        ..., 
+        description="Environment-specific configurations (dev, prod, etc.)"
+    )
+    
+    @field_validator('schema_version')
+    @classmethod
+    def validate_schema_version(cls, v: str) -> str:
+        """Ensure schema version is supported."""
+        supported_versions = ['v1']
+        if v not in supported_versions:
+            raise ValueError(
+                f"Schema version '{v}' not supported. "
+                f"Supported versions: {', '.join(supported_versions)}"
+            )
+        return v
+    
+    @field_validator('environments')
+    @classmethod
+    def validate_environments_not_empty(cls, v: Dict[str, AgentEnvironmentConfig]) -> Dict[str, AgentEnvironmentConfig]:
+        """Ensure at least one environment is defined."""
+        if not v:
+            raise ValueError("At least one environment must be defined")
+        return v
+    
+    def get_config_for_env(self, env_name: str) -> AgentEnvironmentConfig:
+        """Get configuration for a specific environment.
+        
+        Args:
+            env_name: Name of the environment (e.g., 'dev', 'prod')
+            
+        Returns:
+            AgentEnvironmentConfig for the specified environment
+            
+        Raises:
+            ValueError: If environment is not found
+        """
+        if env_name not in self.environments:
+            available_envs = ', '.join(self.environments.keys())
+            raise ValueError(
+                f"Environment '{env_name}' not found in environments.yaml. "
+                f"Available environments: {available_envs}"
+            )
+        return self.environments[env_name]
+    
+    def list_environments(self) -> list[str]:
+        """Get list of all configured environment names."""
+        return list(self.environments.keys())
+    
+    @classmethod
+    @override
+    def from_yaml(cls, file_path: str) -> "AgentEnvironmentsConfig":
+        """Load configuration from environments.yaml file.
+        
+        Args:
+            file_path: Path to environments.yaml file
+            
+        Returns:
+            Parsed and validated AgentEnvironmentsConfig
+            
+        Raises:
+            FileNotFoundError: If file doesn't exist
+            ValueError: If file is invalid or doesn't validate
+        """
+        path = Path(file_path)
+        if not path.exists():
+            raise FileNotFoundError(f"environments.yaml not found: {file_path}")
+        
+        try:
+            with open(path, 'r') as f:
+                data = yaml.safe_load(f)
+            
+            if not data:
+                raise ValueError("environments.yaml file is empty")
+            
+            return cls.model_validate(data)
+            
+        except yaml.YAMLError as e:
+            raise ValueError(f"Invalid YAML format in {file_path}: {e}") from e
+        except Exception as e:
+            raise ValueError(f"Failed to load environments.yaml from {file_path}: {e}") from e
+
+
+def load_environments_config_from_manifest_dir(manifest_dir: Path) -> AgentEnvironmentsConfig | None:
+    """Helper function to load environments.yaml from same directory as manifest.yaml.
+    
+    Args:
+        manifest_dir: Directory containing manifest.yaml
+        
+    Returns:
+        AgentEnvironmentsConfig if environments.yaml exists, None otherwise
+        
+    Raises:
+        ValueError: If environments.yaml exists but is invalid
+    """
+    environments_file = manifest_dir / "environments.yaml"
+    if not environments_file.exists():
+        return None
+    
+    return AgentEnvironmentsConfig.from_yaml(str(environments_file))

agentex/lib/sdk/config/validation.py

@@ -0,0 +1,252 @@
+"""
+Validation framework for agent configuration files.
+
+This module provides validation functions for agent configurations,
+with clear error messages and best practices enforcement.
+"""
+
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from agentex.lib.sdk.config.environment_config import AgentEnvironmentsConfig, AgentEnvironmentConfig
+from agentex.lib.utils.logging import make_logger
+
+logger = make_logger(__name__)
+
+
+class ConfigValidationError(Exception):
+    """Exception raised when configuration validation fails."""
+    
+    def __init__(self, message: str, file_path: Optional[str] = None):
+        self.file_path = file_path
+        super().__init__(message)
+
+
+class EnvironmentsValidationError(ConfigValidationError):
+    """Exception raised when environments.yaml validation fails."""
+    pass
+
+
+def validate_environments_config(
+    environments_config: AgentEnvironmentsConfig, 
+    required_environments: Optional[List[str]] = None
+) -> None:
+    """
+    Validate environments configuration with comprehensive checks.
+    
+    Args:
+        environments_config: The loaded environments configuration
+        required_environments: List of environment names that must be present
+        
+    Raises:
+        EnvironmentsValidationError: If validation fails
+    """
+    # Check for required environments
+    if required_environments:
+        missing_envs: List[str] = []
+        for env_name in required_environments:
+            if env_name not in environments_config.environments:
+                missing_envs.append(env_name)
+        
+        if missing_envs:
+            available_envs = list(environments_config.environments.keys())
+            raise EnvironmentsValidationError(
+                f"Missing required environments: {', '.join(missing_envs)}. "
+                f"Available environments: {', '.join(available_envs)}"
+            )
+    
+    # Validate each environment configuration
+    for env_name, env_config in environments_config.environments.items():
+        try:
+            _validate_single_environment_config(env_name, env_config)
+        except Exception as e:
+            raise EnvironmentsValidationError(
+                f"Environment '{env_name}' configuration error: {str(e)}"
+            ) from e
+
+
+def _validate_single_environment_config(env_name: str, env_config: AgentEnvironmentConfig) -> None:
+    """
+    Validate a single environment configuration.
+    
+    Args:
+        env_name: Name of the environment
+        env_config: AgentEnvironmentConfig instance
+        
+    Raises:
+        ValueError: If validation fails
+    """
+    # Validate namespace naming conventions if kubernetes config exists
+    if env_config.kubernetes and env_config.kubernetes.namespace:
+        namespace = env_config.kubernetes.namespace
+        
+        # Check for common namespace naming issues
+        if namespace != namespace.lower():
+            logger.warning(
+                f"Namespace '{namespace}' contains uppercase letters. "
+                "Kubernetes namespaces should be lowercase."
+            )
+        
+        if namespace.startswith('-') or namespace.endswith('-'):
+            raise ValueError(
+                f"Namespace '{namespace}' cannot start or end with hyphens"
+            )
+    
+    # Validate auth principal
+    principal = env_config.auth.principal
+    if not principal.get('user_id'):
+        raise ValueError("Auth principal must contain non-empty 'user_id'")
+    
+    # Check for environment-specific user_id patterns
+    user_id = principal['user_id']
+    if isinstance(user_id, str):
+        if not any(env_name.lower() in user_id.lower() for env_name in ['dev', 'prod', 'staging', env_name]):
+            logger.warning(
+                f"User ID '{user_id}' doesn't contain environment indicator. "
+                f"Consider including '{env_name}' in the user_id for clarity."
+            )
+    
+    # Validate helm overrides if present
+    if env_config.helm_overrides:
+        _validate_helm_overrides(env_config.helm_overrides)
+
+
+def _validate_helm_overrides(helm_overrides: Dict[str, Any]) -> None:
+    """
+    Validate helm override configuration.
+    
+    Args:
+        helm_overrides: Dictionary of helm overrides
+        
+    Raises:
+        ValueError: If validation fails
+    """
+    # Check for common helm override issues
+    if 'resources' in helm_overrides:
+        resources = helm_overrides['resources']
+        if isinstance(resources, dict):
+            # Validate resource format
+            if 'requests' in resources or 'limits' in resources:
+                for resource_type in ['requests', 'limits']:
+                    if resource_type in resources:
+                        resource_config: Any = resources[resource_type]
+                        if isinstance(resource_config, dict):
+                            # Check for valid resource specifications
+                            for key, value in resource_config.items():
+                                if key in ['cpu', 'memory'] and not isinstance(value, str):
+                                    logger.warning(
+                                        f"Resource {key} should be a string (e.g., '500m', '1Gi'), "
+                                        f"got {type(value).__name__}: {value}"
+                                    )
+
+
+def validate_environments_yaml_file(file_path: str) -> AgentEnvironmentsConfig:
+    """
+    Load and validate environments.yaml file.
+    
+    Args:
+        file_path: Path to environments.yaml file
+        
+    Returns:
+        Validated AgentEnvironmentsConfig
+        
+    Raises:
+        EnvironmentsValidationError: If file is invalid
+    """
+    try:
+        environments_config = AgentEnvironmentsConfig.from_yaml(file_path)
+        validate_environments_config(environments_config)
+        return environments_config
+    except FileNotFoundError:
+        raise EnvironmentsValidationError(
+            f"environments.yaml not found: {file_path}\n\n"
+            "💡 To create one:\n"
+            "   agentex agents init-environments\n\n"
+            "📋 Why required:\n"
+            "   Environment-specific settings (auth, namespace, resources)\n"
+            "   must be separated from global manifest for proper isolation.",
+            file_path=file_path
+        ) from None
+    except Exception as e:
+        raise EnvironmentsValidationError(
+            f"Invalid environments.yaml file: {str(e)}",
+            file_path=file_path
+        ) from e
+
+
+def validate_manifest_and_environments(
+    manifest_path: str, 
+    required_environment: Optional[str] = None
+) -> tuple[str, AgentEnvironmentsConfig]:
+    """
+    Validate both manifest.yaml and environments.yaml files together.
+    
+    Args:
+        manifest_path: Path to manifest.yaml file
+        required_environment: Specific environment that must be present
+        
+    Returns:
+        Tuple of (manifest_path, environments_config)
+        
+    Raises:
+        ConfigValidationError: If validation fails
+    """
+    manifest_file = Path(manifest_path)
+    if not manifest_file.exists():
+        raise ConfigValidationError(f"Manifest file not found: {manifest_path}")
+    
+    # Look for environments.yaml in same directory
+    environments_file = manifest_file.parent / "environments.yaml"
+    environments_config = validate_environments_yaml_file(str(environments_file))
+    
+    # Validate specific environment if requested
+    if required_environment:
+        validate_environments_config(
+            environments_config, 
+            required_environments=[required_environment]
+        )
+    
+    return manifest_path, environments_config
+
+
+def generate_helpful_error_message(error: Exception, context: str = "") -> str:
+    """
+    Generate helpful error message with troubleshooting tips.
+    
+    Args:
+        error: The original exception
+        context: Additional context about where the error occurred
+        
+    Returns:
+        Formatted error message with troubleshooting tips
+    """
+    base_msg = str(error)
+    
+    if context:
+        base_msg = f"{context}: {base_msg}"
+    
+    # Add troubleshooting tips based on error type
+    if isinstance(error, FileNotFoundError):
+        if "environments.yaml" in base_msg:
+            base_msg += (
+                "\n\n🔧 Troubleshooting:\n"
+                "1. Create environments.yaml: agentex agents init-environments\n"
+                "2. Check file location: should be next to manifest.yaml\n"
+                "3. Verify file permissions"
+            )
+    elif "user_id" in base_msg.lower():
+        base_msg += (
+            "\n\n💡 Auth Principal Tips:\n"
+            "- user_id should be unique per environment\n"
+            "- Include environment name (e.g., 'dev_my_agent')\n"
+            "- Use consistent naming convention across agents"
+        )
+    elif "namespace" in base_msg.lower():
+        base_msg += (
+            "\n\n🏷️  Namespace Tips:\n"
+            "- Use lowercase letters, numbers, and hyphens only\n"
+            "- Include team and environment (e.g., 'team-dev-agent')\n"
+            "- Keep under 63 characters"
+        )
+    
+    return base_msg

{agentex_sdk-0.4.0.dist-info → agentex_sdk-0.4.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: agentex-sdk
-Version: 0.4.0
+Version: 0.4.1
 Summary: The official Python library for the agentex API
 Project-URL: Homepage, https://github.com/scaleapi/agentex-python
 Project-URL: Repository, https://github.com/scaleapi/agentex-python
@@ -31,7 +31,7 @@ Requires-Dist: jsonschema<5,>=4.23.0
 Requires-Dist: kubernetes<29.0.0,>=25.0.0
 Requires-Dist: litellm<2,>=1.66.0
 Requires-Dist: mcp[cli]>=1.4.1
-Requires-Dist: openai-agents!=0.2.3,>=0.0.7
+Requires-Dist: openai-agents==0.2.7
 Requires-Dist: openai>=1.99.9
 Requires-Dist: pydantic<3,>=2.0.0
 Requires-Dist: pytest-asyncio>=1.0.0