smartify-ai 0.1.0__py3-none-any.whl

smartify/models/grid.py

@@ -0,0 +1,625 @@
+"""Pydantic models for Grid YAML specification."""
+
+from enum import Enum
+from typing import Any, Dict, List, Optional, Union
+from pydantic import BaseModel, Field, field_validator
+
+
+# ============================================================================
+# Enums
+# ============================================================================
+
+class NodeKind(str, Enum):
+    """Types of nodes in the grid topology."""
+    CONTROLLER = "controller"
+    RELAY = "relay"
+    SUBSTATION = "substation"
+    SPARK = "spark"  # Runtime-only, not user-defined
+    FOREACH = "foreach"
+    EXPR = "expr"
+    AGGREGATE = "aggregate"
+    APPROVAL = "approval"
+
+
+class TriggerType(str, Enum):
+    """Types of grid triggers."""
+    MANUAL = "manual"
+    SCHEDULE = "schedule"
+    WEBHOOK = "webhook"
+    EVENT = "event"
+
+
+class ExecutionMode(str, Enum):
+    """How node activation order is determined."""
+    PARENT = "parent"
+    EXPLICIT = "explicit"
+    DYNAMIC = "dynamic"
+
+
+class AutonomyMode(str, Enum):
+    """Level of autonomous action permitted."""
+    OBSERVE = "observe"
+    RECOMMEND = "recommend"
+    ACT_WITH_LIMITS = "act_with_limits"
+    FULL_AUTONOMY = "full_autonomy"
+
+
+class TripAction(str, Enum):
+    """Actions when a breaker trips."""
+    NOTIFY = "notify"
+    PAUSE = "pause"
+    COOLDOWN = "cooldown"
+    REQUIRE_APPROVAL = "require_approval"
+    STOP = "stop"
+    DOWNGRADE = "downgrade"
+    BLOCK = "block"
+
+
+class BreakerStatus(str, Enum):
+    """Breaker status levels."""
+    OK = "ok"
+    WARNING = "warning"
+    TRIPPED = "tripped"
+
+
+class GridState(str, Enum):
+    """Grid execution states."""
+    DRAFT = "draft"
+    READY = "ready"
+    ENERGIZED = "energized"
+    RUNNING = "running"
+    COMPLETED = "completed"
+    PAUSED = "paused"
+    STOPPED = "stopped"
+    FAILED = "failed"
+
+
+class WorkspaceType(str, Enum):
+    """Workspace environment types."""
+    CONTAINER = "container"
+    LOCAL = "local"
+
+
+class ArtifactType(str, Enum):
+    """Types of output artifacts."""
+    CODE = "code"
+    CONFIG = "config"
+    DOCS = "docs"
+    DATA = "data"
+    REPORT = "report"
+    SCREENSHOT = "screenshot"
+
+
+class AggregateStrategy(str, Enum):
+    """Merge strategies for aggregate nodes."""
+    MERGE_OBJECTS = "merge_objects"
+    CONCAT_ARRAYS = "concat_arrays"
+    SUM = "sum"
+    FIRST = "first"
+    LAST = "last"
+
+
+# ============================================================================
+# Metadata
+# ============================================================================
+
+class CompatibilitySpec(BaseModel):
+    """Runtime compatibility requirements."""
+    minRuntimeVersion: str = "0.1.0"
+
+
+class MetadataSpec(BaseModel):
+    """Grid metadata."""
+    id: str
+    name: str
+    description: Optional[str] = None
+    version: str = "1.0.0"
+    owner: str = "default"
+    tags: List[str] = Field(default_factory=list)
+    compatibility: Optional[CompatibilitySpec] = None
+
+
+# ============================================================================
+# Topology
+# ============================================================================
+
+class TriggerConfig(BaseModel):
+    """Trigger configuration."""
+    requireConfirmation: bool = False
+    # Schedule-specific
+    cron: Optional[str] = None
+    # Webhook-specific
+    path: Optional[str] = None
+    secret: Optional[str] = None
+
+
+class TriggerSpec(BaseModel):
+    """How grid execution is started."""
+    type: TriggerType = TriggerType.MANUAL
+    config: TriggerConfig = Field(default_factory=TriggerConfig)
+
+
+class RetrySpec(BaseModel):
+    """Retry configuration for nodes."""
+    maxAttempts: int = Field(default=1, ge=0, le=10)
+    backoffSeconds: int = Field(default=5, ge=0, le=300)
+    retryOn: List[str] = Field(default_factory=lambda: ["error"])
+
+
+class ForeachSpec(BaseModel):
+    """Configuration for foreach nodes."""
+    over: str  # Expression returning list
+    as_: str = Field(default="item", alias="as")
+    maxIterations: int = Field(default=50, le=100)
+    parallel: bool = True
+    body: Dict[str, Any] = Field(default_factory=dict)  # {to: node_id}
+
+
+class AggregateSpec(BaseModel):
+    """Configuration for aggregate nodes."""
+    from_: List[str] = Field(alias="from")  # Source node IDs
+    strategy: AggregateStrategy = AggregateStrategy.MERGE_OBJECTS
+    waitFor: Union[str, int] = "all"  # "all", "any", or number
+
+
+class ApprovalSpec(BaseModel):
+    """Configuration for approval nodes."""
+    prompt: str = "Please review and approve to continue"
+    showOutputsFrom: List[str] = Field(default_factory=list)
+    timeout: int = Field(default=86400, le=604800)  # Max 7 days
+    requiredApprovers: int = 1
+    allowedApprovers: List[str] = Field(default_factory=list)
+    autoApprove: Optional[Dict[str, str]] = None  # {when: expression}
+
+
+class PromptSpec(BaseModel):
+    """Prompt configuration for agent nodes."""
+    system: Optional[str] = None  # System prompt
+    template: Optional[str] = None  # User message template with {{variable}} placeholders
+    context: Optional[List[str]] = None  # Additional context sources
+
+
+class NodeSpec(BaseModel):
+    """A node in the grid topology."""
+    id: str
+    kind: NodeKind
+    name: str
+    description: Optional[str] = None
+    parent: Optional[str] = None
+    agent: Optional[str] = None
+    capabilities: List[str] = Field(default_factory=list)
+    when: Optional[str] = None  # Activation condition expression
+    parallel: bool = True
+    runAfter: Optional[List[str]] = None
+    retry: Optional[RetrySpec] = None
+    outputSchema: Optional[Dict[str, Any]] = None
+    prompt: Optional[PromptSpec] = None  # Prompt configuration for agent nodes
+    tools: Optional[List[str]] = None  # Tools available to this node
+    
+    # Kind-specific configs
+    foreach: Optional[ForeachSpec] = None
+    aggregate: Optional[AggregateSpec] = None
+    approval: Optional[ApprovalSpec] = None
+    expr: Optional[str] = None  # Expression string for expr nodes
+    
+    @field_validator('kind')
+    @classmethod
+    def validate_kind(cls, v: NodeKind) -> NodeKind:
+        if v == NodeKind.SPARK:
+            raise ValueError("spark nodes cannot be user-defined; they are spawned at runtime")
+        return v
+
+
+class EdgeSpec(BaseModel):
+    """Explicit connection between nodes."""
+    from_: str = Field(alias="from")
+    to: Union[str, List[str]]
+    when: Optional[str] = None
+    condition: Optional[str] = None  # Legacy: "always", "never"
+    parallel: bool = False
+
+
+class DynamicSpawningLimits(BaseModel):
+    """Limits for dynamic node spawning."""
+    maxRelaysPerController: int = 4
+    maxSubstationsPerRelay: int = 3
+    maxSparksPerSubstation: int = 3
+    maxTotalNodes: int = 20
+
+
+class DynamicSpawningDefaults(BaseModel):
+    """Default agents for spawned nodes."""
+    relay: Optional[str] = None
+    substation: Optional[str] = None
+    spark: Optional[str] = None
+
+
+class DynamicSpawningSpec(BaseModel):
+    """Runtime node creation configuration."""
+    enabled: bool = True
+    enableSparks: bool = True
+    limits: DynamicSpawningLimits = Field(default_factory=DynamicSpawningLimits)
+    defaults: DynamicSpawningDefaults = Field(default_factory=DynamicSpawningDefaults)
+    requireApproval: bool = False
+
+
+class TopologySpec(BaseModel):
+    """Grid topology definition."""
+    trigger: TriggerSpec = Field(default_factory=TriggerSpec)
+    executionMode: ExecutionMode = ExecutionMode.PARENT
+    nodes: List[NodeSpec]
+    edges: Optional[List[EdgeSpec]] = None
+    dynamicSpawning: DynamicSpawningSpec = Field(default_factory=DynamicSpawningSpec)
+
+
+# ============================================================================
+# Inputs
+# ============================================================================
+
+class InputSpec(BaseModel):
+    """Input parameter definition."""
+    name: str
+    type: str = "string"  # string, boolean, number, integer, array, object
+    required: bool = False
+    default: Optional[Any] = None
+    enum: Optional[List[Any]] = None
+    description: Optional[str] = None
+
+
+# ============================================================================
+# Environment
+# ============================================================================
+
+class SecretSpec(BaseModel):
+    """Secret definition."""
+    name: str
+    source: str = "env"  # "env" or "prompt"
+    optional: bool = True
+
+
+class EnvironmentSpec(BaseModel):
+    """Environment variables and secrets."""
+    variables: Dict[str, str] = Field(default_factory=dict)
+    secrets: List[SecretSpec] = Field(default_factory=list)
+
+
+# ============================================================================
+# Outputs
+# ============================================================================
+
+class ArtifactSpec(BaseModel):
+    """Output artifact definition."""
+    path: str
+    type: Optional[ArtifactType] = None
+    description: Optional[str] = None
+
+
+class SuccessCriterion(BaseModel):
+    """Success criterion for grid completion."""
+    name: str
+    command: Optional[str] = None
+    exitCode: int = 0
+    optional: bool = False
+
+
+class OutputsSpec(BaseModel):
+    """Expected outputs from the grid."""
+    artifacts: List[ArtifactSpec] = Field(default_factory=list)
+    successCriteria: List[SuccessCriterion] = Field(default_factory=list)
+
+
+# ============================================================================
+# Agents
+# ============================================================================
+
+class ModelPolicy(BaseModel):
+    """Model selection policy."""
+    preferred: str = "claude-sonnet-4-20250514"
+    fallback: List[str] = Field(default_factory=list)
+
+
+class ContextSource(BaseModel):
+    """Context source for agents."""
+    type: str  # "artifacts", "memory", "files"
+    filter: Optional[str] = None  # Glob pattern
+    key: Optional[str] = None  # Memory key
+
+
+class AgentSpec(BaseModel):
+    """Agent definition."""
+    modelPolicy: Optional[ModelPolicy] = None
+    systemPrompt: Optional[str] = None
+    systemPromptRef: Optional[str] = None  # "builtin:controller" or "prompts/file.md"
+    maxDelegation: int = 4
+    tools: Optional[List[str]] = None
+    contextSources: List[ContextSource] = Field(default_factory=list)
+    role: Optional[str] = None  # "controller", "relay", "substation", "spark"
+
+
+# ============================================================================
+# Tools
+# ============================================================================
+
+class ToolSpec(BaseModel):
+    """Tool configuration."""
+    id: str
+    enabled: bool = True
+    config: Dict[str, Any] = Field(default_factory=dict)
+
+
+class McpServerSpec(BaseModel):
+    """MCP server configuration for external tool integration.
+    
+    Allows grids to use tools from external MCP servers.
+    
+    Example:
+        mcpServers:
+          - id: filesystem
+            transport: stdio
+            command: npx
+            args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
+            prefix: fs
+    """
+    id: str = Field(..., description="Unique identifier for this MCP server")
+    transport: str = Field(
+        default="stdio",
+        description="Transport type: 'stdio', 'sse', or 'streamable_http'"
+    )
+    
+    # For stdio transport
+    command: Optional[str] = Field(None, description="Command to start the MCP server")
+    args: List[str] = Field(default_factory=list, description="Command arguments")
+    env: Optional[Dict[str, str]] = Field(None, description="Environment variables")
+    cwd: Optional[str] = Field(None, description="Working directory")
+    
+    # For SSE/HTTP transport  
+    url: Optional[str] = Field(None, description="URL for SSE or HTTP transport")
+    headers: Optional[Dict[str, str]] = Field(None, description="HTTP headers")
+    
+    # Tool naming and filtering
+    prefix: Optional[str] = Field(
+        None, 
+        description="Prefix for tool names (e.g. 'fs' -> 'fs_read_file')"
+    )
+    tools: Optional[List[str]] = Field(
+        None,
+        description="Only expose these tools (if set)"
+    )
+
+
+class ToolsSpec(BaseModel):
+    """Tool configuration section."""
+    enabled: List[str] = Field(default_factory=list)
+    disabled: List[str] = Field(default_factory=list)
+    custom: List[ToolSpec] = Field(default_factory=list)
+    mcpServers: List[McpServerSpec] = Field(
+        default_factory=list,
+        description="External MCP servers to connect to for additional tools"
+    )
+
+
+# ============================================================================
+# Guardrails
+# ============================================================================
+
+class TokenLimits(BaseModel):
+    """Token usage limits."""
+    maxInputTokensPerRequest: int = 100_000
+    maxOutputTokensPerRequest: int = 16_000
+    maxTotalTokensPerRun: int = 1_000_000
+
+
+class TimeLimits(BaseModel):
+    """Time limits."""
+    maxRuntimeSeconds: int = 3600
+    maxTaskSeconds: int = 300
+
+
+class CostLimits(BaseModel):
+    """Cost limits."""
+    maxCostPerRun: float = 10.0
+    maxCostPerDay: float = 100.0
+
+
+class RequestLimits(BaseModel):
+    """Request rate limits."""
+    maxRequestsPerMinute: int = 60
+    maxConcurrentAgents: int = 5
+
+
+class BreakerSpec(BaseModel):
+    """Breaker configuration."""
+    tokens: Optional[TokenLimits] = None
+    time: Optional[TimeLimits] = None
+    cost: Optional[CostLimits] = None
+    requests: Optional[RequestLimits] = None
+
+
+class BreakerActions(BaseModel):
+    """Actions when breakers trip."""
+    onTokensLimit: TripAction = TripAction.PAUSE
+    onTimeLimit: TripAction = TripAction.STOP
+    onCostLimit: TripAction = TripAction.PAUSE
+    onRequestsLimit: TripAction = TripAction.COOLDOWN
+    cooldownSeconds: int = 60
+
+
+class AutonomySpec(BaseModel):
+    """Autonomy configuration."""
+    mode: AutonomyMode = AutonomyMode.ACT_WITH_LIMITS
+    requireApprovalFor: List[str] = Field(default_factory=list)
+
+
+class GuardrailsSpec(BaseModel):
+    """Guardrails configuration."""
+    breakers: BreakerSpec = Field(default_factory=BreakerSpec)
+    breakerActions: BreakerActions = Field(default_factory=BreakerActions)
+    autonomy: AutonomySpec = Field(default_factory=AutonomySpec)
+
+
+# ============================================================================
+# Workspace
+# ============================================================================
+
+class WorkspaceResourcesSpec(BaseModel):
+    """Workspace resource limits."""
+    cpus: int = 2
+    memoryMb: int = 4096
+
+
+class WorkspaceMountSpec(BaseModel):
+    """Workspace mount configuration."""
+    src: str
+    dst: str
+    readonly: bool = False
+
+
+class WorkspaceContainerConfig(BaseModel):
+    """Container workspace configuration."""
+    image: str = "smartify-sandbox:latest"
+    resources: WorkspaceResourcesSpec = Field(default_factory=WorkspaceResourcesSpec)
+    mounts: List[WorkspaceMountSpec] = Field(default_factory=list)
+
+
+class WorkspaceSpec(BaseModel):
+    """Workspace configuration."""
+    type: WorkspaceType = WorkspaceType.LOCAL
+    config: Optional[WorkspaceContainerConfig] = None
+    rootPath: str = "./workspace"
+    persistent: bool = True
+
+
+# ============================================================================
+# Coordination
+# ============================================================================
+
+class CoordinationSpec(BaseModel):
+    """State management configuration."""
+    stateBackend: str = "memory"  # "memory", "sqlite", "redis"
+    checkpointInterval: int = 60
+
+
+# ============================================================================
+# Notifications
+# ============================================================================
+
+class WebhookConfigSpec(BaseModel):
+    """Webhook endpoint configuration."""
+    url: str
+    events: List[str] = Field(
+        default_factory=lambda: [
+            "run_completed", "run_failed", "approval_needed", "breaker_tripped"
+        ],
+        description="Event types to send: run_started, run_completed, run_failed, "
+                    "run_paused, run_stopped, approval_needed, breaker_tripped, node_completed"
+    )
+    secret: Optional[str] = Field(
+        None, 
+        description="Secret for HMAC-SHA256 signature (X-Smartify-Signature header)"
+    )
+    headers: Dict[str, str] = Field(
+        default_factory=dict,
+        description="Custom headers to include with webhook requests"
+    )
+    maxRetries: int = Field(3, ge=0, le=10, description="Maximum retry attempts")
+    timeout: float = Field(30.0, ge=1, le=120, description="Request timeout in seconds")
+    enabled: bool = True
+
+
+class NotificationsSpec(BaseModel):
+    """Notification configuration for grid events."""
+    webhooks: List[WebhookConfigSpec] = Field(default_factory=list)
+    
+    # Slack notifications (convenience)
+    slack: Optional[Dict[str, Any]] = Field(
+        None,
+        description="Slack notification config: {webhook_url, channel, events}"
+    )
+
+
+# ============================================================================
+# Observability
+# ============================================================================
+
+class ObservabilitySpec(BaseModel):
+    """Logging and events configuration."""
+    logLevel: str = "info"
+    enableMetrics: bool = True
+    enableTracing: bool = False
+    # Legacy: simple webhook URLs (use notifications.webhooks for full config)
+    webhooks: List[str] = Field(default_factory=list)
+
+
+# ============================================================================
+# UI (optional hints)
+# ============================================================================
+
+class UISpec(BaseModel):
+    """Dashboard hints."""
+    color: Optional[str] = None
+    icon: Optional[str] = None
+
+
+# ============================================================================
+# Root GridSpec
+# ============================================================================
+
+class GridSpec(BaseModel):
+    """Root Grid YAML specification."""
+    apiVersion: str = "smartify.ai/v1"
+    kind: str = "GridSpec"
+    metadata: MetadataSpec
+    topology: TopologySpec
+    inputs: Optional[List[InputSpec]] = None
+    environment: Optional[EnvironmentSpec] = None
+    outputs: Optional[OutputsSpec] = None
+    agents: Optional[Dict[str, AgentSpec]] = None
+    tools: Optional[ToolsSpec] = None
+    guardrails: Optional[GuardrailsSpec] = None
+    workspace: Optional[WorkspaceSpec] = None
+    coordination: Optional[CoordinationSpec] = None
+    notifications: Optional[NotificationsSpec] = None
+    observability: Optional[ObservabilitySpec] = None
+    ui: Optional[UISpec] = None
+    
+    @field_validator('kind')
+    @classmethod
+    def validate_kind(cls, v: str) -> str:
+        if v != "GridSpec":
+            raise ValueError(f"kind must be 'GridSpec', got '{v}'")
+        return v
+    
+    @field_validator('apiVersion')
+    @classmethod
+    def validate_api_version(cls, v: str) -> str:
+        if not v.startswith("smartify.ai/"):
+            raise ValueError(f"apiVersion must start with 'smartify.ai/', got '{v}'")
+        return v
+    
+    # Convenience properties
+    @property
+    def id(self) -> str:
+        """Grid ID from metadata."""
+        return self.metadata.id
+    
+    @id.setter
+    def id(self, value: str) -> None:
+        """Set grid ID in metadata."""
+        self.metadata.id = value
+    
+    @property
+    def name(self) -> str:
+        """Grid name from metadata."""
+        return self.metadata.name
+    
+    @property
+    def nodes(self) -> List["NodeSpec"]:
+        """Nodes from topology."""
+        return self.topology.nodes
+    
+    @property
+    def breakers(self) -> Optional[BreakerSpec]:
+        """Breakers from guardrails."""
+        if self.guardrails:
+            return self.guardrails.breakers
+        return None

smartify/notifications/__init__.py

@@ -0,0 +1,22 @@
+"""Notification system for Smartify events.
+
+Supports webhook notifications for:
+- run_completed
+- run_failed
+- approval_needed
+- breaker_tripped
+"""
+
+from smartify.notifications.webhook import (
+    WebhookNotifier,
+    WebhookConfig,
+    WebhookEvent,
+    EventType,
+)
+
+__all__ = [
+    "WebhookNotifier",
+    "WebhookConfig", 
+    "WebhookEvent",
+    "EventType",
+]