@almadar/cli 0.3.2 → 1.0.3

package/shells/python-shell/src/orbital_app/main.py

@@ -0,0 +1,108 @@
+"""
+Orbital Python Shell - FastAPI Server
+
+Handles event processing for Orbital applications with PyTorch support.
+Generated code goes in orbital_app/generated/
+"""
+from fastapi import FastAPI, WebSocket, WebSocketDisconnect
+from fastapi.middleware.cors import CORSMiddleware
+from contextlib import asynccontextmanager
+import uvicorn
+
+from .core.settings import get_settings
+from .core.firebase import initialize_firebase
+from .core.websocket import connection_manager
+from .generated.routes import register_routes
+
+# Load settings
+settings = get_settings()
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """Application lifespan handler."""
+    print(f"Starting Orbital Python Server (env: {settings.environment})...")
+
+    # Initialize Firebase Admin SDK
+    try:
+        initialize_firebase()
+        if settings.is_emulator:
+            print(f"Firebase Admin SDK initialized (emulator: {settings.firestore_emulator_host})")
+        else:
+            print("Firebase Admin SDK initialized")
+    except Exception as e:
+        print(f"Warning: Firebase initialization failed: {e}")
+        print("Running without Firebase authentication")
+
+    yield
+    print("Shutting down...")
+
+
+app = FastAPI(
+    title="Orbital Python Shell",
+    description="FastAPI server for Orbital applications with PyTorch support",
+    version="0.1.0",
+    lifespan=lifespan,
+)
+
+# CORS middleware for React client
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=settings.cors_origins_list,
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+
+# Health check endpoint
+@app.get("/health")
+async def health_check():
+    """Health check endpoint."""
+    return {
+        "status": "healthy",
+        "version": "0.1.0",
+        "environment": settings.environment,
+    }
+
+
+# WebSocket endpoint for real-time updates
+@app.websocket("/ws")
+async def websocket_global(websocket: WebSocket):
+    """Global WebSocket connection for all updates."""
+    await connection_manager.connect(websocket)
+    try:
+        while True:
+            # Keep connection alive, handle incoming messages
+            data = await websocket.receive_text()
+            # Echo back for ping/pong
+            if data == "ping":
+                await websocket.send_text("pong")
+    except WebSocketDisconnect:
+        await connection_manager.disconnect(websocket)
+
+
+@app.websocket("/ws/{entity_type}/{entity_id}")
+async def websocket_entity(websocket: WebSocket, entity_type: str, entity_id: str):
+    """Entity-specific WebSocket connection."""
+    await connection_manager.connect(websocket, entity_type, entity_id)
+    try:
+        while True:
+            data = await websocket.receive_text()
+            if data == "ping":
+                await websocket.send_text("pong")
+    except WebSocketDisconnect:
+        await connection_manager.disconnect(websocket, entity_type, entity_id)
+
+
+# Register generated routes
+register_routes(app)
+
+
+if __name__ == "__main__":
+    uvicorn.run(
+        "orbital_app.main:app",
+        host="0.0.0.0",
+        port=settings.port,
+        reload=settings.is_development,
+    )

package/shells/python-shell/src/orbital_app/middleware/__init__.py

@@ -0,0 +1,18 @@
+"""
+Middleware for Orbital Python Shell.
+
+- auth: Firebase authentication middleware
+"""
+from .auth import (
+    FirebaseUser,
+    get_current_user,
+    get_optional_user,
+    require_auth,
+)
+
+__all__ = [
+    "FirebaseUser",
+    "get_current_user",
+    "get_optional_user",
+    "require_auth",
+]

package/shells/python-shell/src/orbital_app/middleware/auth.py

@@ -0,0 +1,126 @@
+"""
+Firebase Authentication Middleware
+
+Provides FastAPI dependencies for authenticating requests using Firebase ID tokens.
+The decoded token provides the @user context for guard evaluation.
+"""
+from typing import Optional, Annotated
+from fastapi import Depends, HTTPException, Header, status
+from pydantic import BaseModel
+
+from ..core.firebase import verify_id_token
+
+
+class FirebaseUser(BaseModel):
+    """
+    Decoded Firebase user from ID token.
+
+    This becomes the @user context in guard expressions.
+    """
+
+    uid: str
+    email: Optional[str] = None
+    email_verified: bool = False
+    name: Optional[str] = None
+    picture: Optional[str] = None
+    # Custom claims (e.g., role, permissions)
+    role: Optional[str] = None
+    # Raw claims for accessing any custom data
+    claims: dict = {}
+
+    @classmethod
+    def from_decoded_token(cls, decoded: dict) -> "FirebaseUser":
+        """Create FirebaseUser from decoded Firebase token."""
+        return cls(
+            uid=decoded.get("uid", ""),
+            email=decoded.get("email"),
+            email_verified=decoded.get("email_verified", False),
+            name=decoded.get("name"),
+            picture=decoded.get("picture"),
+            role=decoded.get("role"),  # Custom claim
+            claims=decoded,
+        )
+
+
+async def get_current_user(
+    authorization: Annotated[str | None, Header()] = None
+) -> FirebaseUser:
+    """
+    FastAPI dependency to get the current authenticated user.
+
+    Extracts Bearer token from Authorization header and verifies it.
+
+    Usage:
+        @router.post("/events/{event}")
+        async def handle_event(user: FirebaseUser = Depends(get_current_user)):
+            # user is now available for @user bindings
+            pass
+
+    Raises:
+        HTTPException 401: If no token or invalid token
+    """
+    if not authorization:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Authorization header missing",
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+
+    if not authorization.startswith("Bearer "):
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Authorization header must start with 'Bearer '",
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+
+    token = authorization[7:]  # Remove "Bearer " prefix
+
+    try:
+        decoded = verify_id_token(token)
+        return FirebaseUser.from_decoded_token(decoded)
+    except Exception as e:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail=f"Invalid or expired token: {str(e)}",
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+
+
+async def get_optional_user(
+    authorization: Annotated[str | None, Header()] = None
+) -> Optional[FirebaseUser]:
+    """
+    FastAPI dependency to get the current user if authenticated.
+
+    Returns None if no token provided (for public endpoints).
+
+    Usage:
+        @router.post("/events/{event}")
+        async def handle_event(user: Optional[FirebaseUser] = Depends(get_optional_user)):
+            if user:
+                # Authenticated user
+            else:
+                # Anonymous access
+    """
+    if not authorization or not authorization.startswith("Bearer "):
+        return None
+
+    token = authorization[7:]
+
+    try:
+        decoded = verify_id_token(token)
+        return FirebaseUser.from_decoded_token(decoded)
+    except Exception:
+        return None
+
+
+def require_auth(user: FirebaseUser = Depends(get_current_user)) -> FirebaseUser:
+    """
+    Alias for get_current_user for clearer intent.
+
+    Usage:
+        @router.post("/admin/action")
+        async def admin_action(user: FirebaseUser = Depends(require_auth)):
+            pass
+    """
+    return user

package/shells/python-shell/src/orbital_app/nn/__init__.py

@@ -0,0 +1,28 @@
+"""
+Neural Network Runtime - PyTorch implementations for nn/* operators.
+
+- builder: S-expr architecture → PyTorch Module
+- forward: nn/forward inference
+- training: train/loop training
+- constraints: Weight/gradient constraints
+"""
+from .builder import build_network, build_layer
+from .forward import forward
+from .training import train_loop
+from .constraints import (
+    apply_gradient_clipping,
+    apply_weight_clipping,
+    check_forbidden_regions,
+    compute_constraint_loss,
+)
+
+__all__ = [
+    "build_network",
+    "build_layer",
+    "forward",
+    "train_loop",
+    "apply_gradient_clipping",
+    "apply_weight_clipping",
+    "check_forbidden_regions",
+    "compute_constraint_loss",
+]

package/shells/python-shell/src/orbital_app/nn/constraints.py

@@ -0,0 +1,104 @@
+"""
+Constraint Enforcement - Explicit safety guarantees.
+
+Implements constraint checking and enforcement for neural networks:
+- Gradient clipping: Prevent exploding gradients
+- Weight clipping: Keep weights bounded
+- Forbidden regions: Penalize outputs in dangerous ranges
+"""
+import torch
+import torch.nn as nn
+from typing import Dict, Any, List
+
+
+def apply_gradient_clipping(module: nn.Module, max_norm: float) -> None:
+    """
+    Clip gradients to max norm.
+
+    Args:
+        module: PyTorch module with gradients
+        max_norm: Maximum gradient norm
+    """
+    torch.nn.utils.clip_grad_norm_(module.parameters(), max_norm)
+
+
+def apply_weight_clipping(module: nn.Module, max_magnitude: float) -> None:
+    """
+    Clamp weights to [-max, max].
+
+    Args:
+        module: PyTorch module
+        max_magnitude: Maximum absolute weight value
+    """
+    with torch.no_grad():
+        for param in module.parameters():
+            param.clamp_(-max_magnitude, max_magnitude)
+
+
+def check_forbidden_regions(
+    output: torch.Tensor,
+    forbidden: List[Dict[str, Any]],
+) -> List[Dict[str, Any]]:
+    """
+    Check if output violates forbidden regions.
+
+    Args:
+        output: Network output tensor
+        forbidden: List of forbidden region specs with 'dim', 'min', 'max'
+
+    Returns:
+        List of violations with dim, value, and reason
+    """
+    violations = []
+    for region in forbidden:
+        dim = region["dim"]
+        min_val = region["min"]
+        max_val = region["max"]
+        value = output[dim].item()
+
+        if min_val <= value <= max_val:
+            violations.append(
+                {
+                    "dim": dim,
+                    "value": value,
+                    "min": min_val,
+                    "max": max_val,
+                    "reason": region.get("reason", "forbidden region"),
+                }
+            )
+
+    return violations
+
+
+def compute_constraint_loss(
+    output: torch.Tensor,
+    forbidden: List[Dict[str, Any]],
+    penalty: float = 10.0,
+) -> torch.Tensor:
+    """
+    Compute penalty loss for forbidden regions.
+
+    Args:
+        output: Network output tensor
+        forbidden: List of forbidden region specs
+        penalty: Penalty multiplier
+
+    Returns:
+        Scalar loss tensor
+    """
+    loss = torch.tensor(0.0)
+
+    for region in forbidden:
+        dim = region["dim"]
+        min_val = region["min"]
+        max_val = region["max"]
+        value = output[dim]
+
+        # Penalty for being in forbidden region
+        if min_val <= value.item() <= max_val:
+            # Distance to nearest boundary
+            dist_to_min = (value - min_val).abs()
+            dist_to_max = (max_val - value).abs()
+            loss = loss + penalty * torch.min(dist_to_min, dist_to_max)
+
+    return loss

package/shells/python-shell/src/orbital_app/nn/forward.py

@@ -0,0 +1,34 @@
+"""
+Forward Pass - Execute neural network inference.
+
+Used by server-side effects when a trait needs to run nn/forward.
+"""
+import torch
+import torch.nn as nn
+from typing import Union, List
+
+
+def forward(
+    module: nn.Module, input_data: Union[torch.Tensor, List[float]]
+) -> torch.Tensor:
+    """
+    Execute forward pass (inference mode).
+
+    Args:
+        module: PyTorch neural network module
+        input_data: Input tensor or list of floats
+
+    Returns:
+        Output tensor from the network
+    """
+    module.eval()
+
+    # Convert to tensor if needed
+    if not isinstance(input_data, torch.Tensor):
+        input_tensor = torch.tensor(input_data, dtype=torch.float32)
+    else:
+        input_tensor = input_data
+
+    # Run inference without gradient tracking
+    with torch.no_grad():
+        return module(input_tensor)

package/shells/python-shell/src/orbital_app/nn/training.py

@@ -0,0 +1,101 @@
+"""
+Training Loop - Execute train/loop S-expression.
+
+Supports:
+- Configurable epochs, learning rate, optimizer
+- Gradient clipping (maxGradientNorm)
+- Weight clipping (maxWeightMagnitude)
+- Forbidden output regions (constraint loss)
+"""
+import torch
+import torch.nn as nn
+import torch.optim as optim
+from typing import List, Dict, Any, Tuple
+from .constraints import (
+    apply_gradient_clipping,
+    apply_weight_clipping,
+    compute_constraint_loss,
+)
+
+
+def train_loop(
+    module: nn.Module,
+    data: List[Dict[str, Any]],
+    config: Dict[str, Any],
+) -> Tuple[nn.Module, Dict[str, Any]]:
+    """
+    Training loop with explicit constraints.
+
+    Args:
+        module: PyTorch neural network to train
+        data: Training data as list of dicts with 'observation' and 'target'
+        config: Training configuration
+
+    Config fields:
+        - epochs: int (default 100)
+        - learningRate: float (default 0.001)
+        - maxGradientNorm: float (optional) - clip gradients to this norm
+        - maxWeightMagnitude: float (optional) - clip weights to [-max, max]
+        - forbiddenOutputRegions: List[Dict] (optional) - constraint regions
+
+    Returns:
+        Tuple of (trained module, training history)
+    """
+    epochs = config.get("epochs", 100)
+    lr = config.get("learningRate", 0.001)
+    max_grad_norm = config.get("maxGradientNorm")
+    max_weight_mag = config.get("maxWeightMagnitude")
+    forbidden = config.get("forbiddenOutputRegions", [])
+
+    optimizer = optim.Adam(module.parameters(), lr=lr)
+    criterion = nn.MSELoss()
+
+    history = {"losses": [], "constraint_violations": []}
+
+    module.train()
+
+    for epoch in range(epochs):
+        total_loss = 0.0
+        violations = 0
+
+        for sample in data:
+            optimizer.zero_grad()
+
+            # Prepare tensors
+            input_tensor = torch.tensor(sample["observation"], dtype=torch.float32)
+            target = torch.tensor(sample["target"], dtype=torch.float32)
+
+            # Forward pass
+            output = module(input_tensor)
+
+            # Base loss
+            loss = criterion(output, target)
+
+            # Add constraint loss if forbidden regions defined
+            if forbidden:
+                constraint_loss = compute_constraint_loss(output, forbidden)
+                loss = loss + constraint_loss
+                if constraint_loss > 0:
+                    violations += 1
+
+            # Backward pass
+            loss.backward()
+
+            # Gradient clipping
+            if max_grad_norm:
+                apply_gradient_clipping(module, max_grad_norm)
+
+            # Update weights
+            optimizer.step()
+
+            # Weight clipping
+            if max_weight_mag:
+                apply_weight_clipping(module, max_weight_mag)
+
+            total_loss += loss.item()
+
+        avg_loss = total_loss / len(data) if data else 0
+        history["losses"].append(avg_loss)
+        history["constraint_violations"].append(violations)
+
+    return module, history

package/shells/python-shell/src/orbital_app/tensor/__init__.py

@@ -0,0 +1,46 @@
+"""
+Tensor Operations - PyTorch implementations for tensor/* operators.
+
+All 28 tensor operators from orbital-shared/std/modules/tensor.ts.
+"""
+from .ops import *
+from .contracts import InputContract, OutputContract
+
+__all__ = [
+    # Creation
+    "tensor_from",
+    "tensor_zeros",
+    "tensor_ones",
+    "tensor_rand",
+    "tensor_randn",
+    # Shape/Indexing
+    "tensor_shape",
+    "tensor_get",
+    "tensor_slice",
+    "tensor_reshape",
+    "tensor_flatten",
+    # Math
+    "tensor_add",
+    "tensor_sub",
+    "tensor_mul",
+    "tensor_div",
+    "tensor_matmul",
+    "tensor_dot",
+    # Reductions
+    "tensor_sum",
+    "tensor_mean",
+    "tensor_max",
+    "tensor_min",
+    "tensor_argmax",
+    "tensor_norm",
+    # Range Validation
+    "tensor_all_in_range",
+    "tensor_clamp",
+    "tensor_clamp_per_dim",
+    "tensor_out_of_range_dims",
+    # Conversion
+    "tensor_to_list",
+    # Contracts
+    "InputContract",
+    "OutputContract",
+]

package/shells/python-shell/src/orbital_app/tensor/contracts.py

@@ -0,0 +1,112 @@
+"""
+Tensor Contracts - Validate inputs and outputs against specifications.
+
+Per Orbital_Trait_Machines.md, contracts ensure:
+- Input shape and range validation
+- Output clamping to safe ranges
+- Violation reporting for debugging
+"""
+import torch
+from typing import Dict, Any, List, Optional
+from dataclasses import dataclass
+
+
+@dataclass
+class InputContract:
+    """
+    Input contract specification.
+
+    Validates that input tensors match expected shape and range.
+    """
+
+    shape: List[int]
+    range: List[float]  # [min, max]
+    meaning: List[str]  # Human-readable meaning for each dimension
+
+    def validate(self, tensor: torch.Tensor) -> Optional[Dict[str, Any]]:
+        """
+        Validate input against contract.
+
+        Args:
+            tensor: Input tensor to validate
+
+        Returns:
+            Violation dict if invalid, None if valid
+        """
+        # Check shape
+        if list(tensor.shape) != self.shape:
+            return {
+                "type": "shape_mismatch",
+                "expected": self.shape,
+                "received": list(tensor.shape),
+            }
+
+        # Check range
+        min_val, max_val = self.range
+        if not ((tensor >= min_val).all() and (tensor <= max_val).all()):
+            out_of_range = [
+                i
+                for i, val in enumerate(tensor.tolist())
+                if val < min_val or val > max_val
+            ]
+            return {
+                "type": "out_of_range",
+                "allowed_range": self.range,
+                "out_of_range_indices": out_of_range,
+            }
+
+        return None
+
+
+@dataclass
+class OutputContract:
+    """
+    Output contract specification.
+
+    Clamps outputs to safe ranges and reports violations.
+    """
+
+    shape: List[int]
+    ranges: Dict[str, Dict[str, Any]]  # Per-dimension ranges with meaning
+
+    def clamp(self, tensor: torch.Tensor) -> torch.Tensor:
+        """
+        Clamp output to contract ranges.
+
+        Args:
+            tensor: Output tensor to clamp
+
+        Returns:
+            Clamped tensor
+        """
+        result = tensor.clone()
+        for dim_str, bounds in self.ranges.items():
+            dim = int(dim_str)
+            result[dim] = result[dim].clamp(bounds["min"], bounds["max"])
+        return result
+
+    def get_violations(self, tensor: torch.Tensor) -> List[Dict[str, Any]]:
+        """
+        Get dimensions that violate contract.
+
+        Args:
+            tensor: Output tensor to check
+
+        Returns:
+            List of violations with dim, value, bounds, and meaning
+        """
+        violations = []
+        for dim_str, bounds in self.ranges.items():
+            dim = int(dim_str)
+            value = tensor[dim].item()
+            if value < bounds["min"] or value > bounds["max"]:
+                violations.append(
+                    {
+                        "dim": dim,
+                        "value": value,
+                        "min": bounds["min"],
+                        "max": bounds["max"],
+                        "meaning": bounds.get("meaning", f"dim_{dim}"),
+                    }
+                )
+        return violations