xenfra-sdk 0.1.0__py3-none-any.whl

xenfra_sdk/models.py

@@ -0,0 +1,170 @@
+"""
+Pydantic models for the Xenfra SDK, representing API request and response data structures.
+These models are used for data validation, serialization, and providing clear schemas
+for external tools like OpenAI function calling.
+"""
+
+from datetime import datetime
+from enum import Enum
+
+from pydantic import BaseModel, Field
+
+
+class DeploymentStatus(str, Enum):
+    """
+    Represents the possible statuses of a deployment.
+    """
+
+    PENDING = "pending"
+    IN_PROGRESS = "in_progress"
+    SUCCESS = "success"
+    FAILED = "failed"
+
+
+class SourceType(str, Enum):
+    """
+    Represents the source type of a deployment.
+    """
+
+    LOCAL = "local"
+    GIT = "git"
+
+
+class Deployment(BaseModel):
+    """
+    Represents a single deployment instance.
+    """
+
+    id: str = Field(..., description="Unique identifier for the deployment")
+    projectId: str = Field(..., description="Identifier of the project being deployed")
+    status: DeploymentStatus = Field(..., description="Current status of the deployment")
+    source: str = Field(..., description="Source of the deployment (e.g., 'cli', 'api')")
+    created_at: datetime = Field(..., description="Timestamp when the deployment was created")
+    finished_at: datetime | None = Field(None, description="Timestamp when the deployment finished")
+
+
+class DeploymentRecord(BaseModel):
+    """
+    Represents a record of a completed deployment.
+    """
+
+    deployment_id: str = Field(..., description="Unique identifier for this deployment instance.")
+    timestamp: datetime = Field(..., description="Timestamp of when the deployment succeeded.")
+    source_type: SourceType = Field(..., description="The type of the source code (local or git).")
+    source_identifier: str = Field(
+        ...,
+        description="The identifier for the source (commit SHA for git, archive path for local).",
+    )
+
+
+class BalanceRead(BaseModel):
+    """
+    Represents a snapshot of the user's account balance and usage.
+    """
+
+    month_to_date_balance: str = Field(
+        ..., description="The account balance in USD at the beginning of the month."
+    )
+    account_balance: str = Field(..., description="The current total account balance in USD.")
+    month_to_date_usage: str = Field(
+        ..., description="The total usage in USD for the current month."
+    )
+    generated_at: str = Field(
+        ..., description="The timestamp when this balance report was generated."
+    )
+    error: str | None = Field(
+        None, description="Any error message associated with fetching the balance."
+    )
+
+
+class DropletCostRead(BaseModel):
+    """
+    Represents the cost information for a single DigitalOcean Droplet.
+    """
+
+    id: int = Field(..., description="The unique identifier for the Droplet.")
+    name: str = Field(..., description="The user-given name of the Droplet.")
+    ip_address: str = Field(..., description="The public IP address of the Droplet.")
+    status: str = Field(
+        ..., description="The current status of the Droplet (e.g., 'active', 'off')."
+    )
+    size_slug: str = Field(
+        ..., description="The size slug representing the Droplet's resources (e.g., 's-1vcpu-1gb')."
+    )
+    monthly_price: float = Field(..., description="The monthly cost of this Droplet in USD.")
+
+
+class ProjectRead(BaseModel):
+    """
+    Represents a project, including its deployment status and estimated costs.
+    """
+
+    id: int = Field(..., description="The unique identifier for the project.")
+    name: str = Field(..., description="The user-given name of the project.")
+    ip_address: str | None = Field(
+        None, description="The public IP address of the server running the project."
+    )
+    status: str = Field(
+        ..., description="The current status of the project (e.g., 'LIVE', 'FAILED')."
+    )
+    region: str = Field(
+        ..., description="The geographical region where the project is deployed (e.g., 'nyc3')."
+    )
+    size_slug: str = Field(..., description="The size slug of the server running the project.")
+    estimated_monthly_cost: float | None = Field(
+        None, description="The estimated monthly cost of the project's infrastructure in USD."
+    )
+    created_at: datetime = Field(..., description="The timestamp when the project was created.")
+
+
+# Intelligence Service Models
+
+class PatchObject(BaseModel):
+    """
+    Represents a structured patch for a configuration file.
+    """
+
+    file: str | None = Field(None, description="The name of the file to be patched (e.g., 'requirements.txt')")
+    operation: str | None = Field(None, description="The patch operation (e.g., 'add', 'replace')")
+    path: str | None = Field(None, description="A JSON-like path to the field to be changed")
+    value: str | None = Field(None, description="The new value to apply")
+
+
+class DiagnosisResponse(BaseModel):
+    """
+    Response from the AI diagnosis endpoint.
+    """
+
+    diagnosis: str = Field(..., description="Human-readable explanation of the problem")
+    suggestion: str = Field(..., description="Recommended course of action")
+    patch: PatchObject | None = Field(None, description="Optional machine-applicable patch")
+
+
+class PackageManagerOption(BaseModel):
+    """
+    Represents a detected package manager option.
+    """
+
+    manager: str = Field(..., description="Package manager name (uv, pip, poetry, npm, etc.)")
+    file: str = Field(..., description="Associated dependency file")
+
+
+class CodebaseAnalysisResponse(BaseModel):
+    """
+    Response from the codebase analysis endpoint.
+    """
+
+    framework: str = Field(..., description="Detected framework (fastapi, flask, django)")
+    port: int = Field(..., description="Detected application port")
+    database: str = Field(..., description="Detected database (postgresql, mysql, sqlite, none)")
+    cache: str | None = Field(None, description="Detected cache (redis, memcached, none)")
+    workers: list[str] | None = Field(None, description="Detected background workers (celery, rq)")
+    env_vars: list[str] | None = Field(None, description="Required environment variables")
+    package_manager: str = Field(..., description="Detected package manager (uv, pip, poetry, npm, pnpm, yarn, go, bundler)")
+    dependency_file: str = Field(..., description="Dependency manifest file (pyproject.toml, requirements.txt, package.json, go.mod, Gemfile)")
+    has_conflict: bool = Field(False, description="True if multiple package managers detected")
+    detected_package_managers: list[PackageManagerOption] | None = Field(None, description="All detected package managers (if conflict)")
+    instance_size: str = Field(..., description="Recommended instance size (basic, standard, premium)")
+    estimated_cost_monthly: float = Field(..., description="Estimated monthly cost in USD")
+    confidence: float = Field(..., description="Confidence score (0.0-1.0)")
+    notes: str | None = Field(None, description="Additional observations")

xenfra_sdk/patterns.json

@@ -0,0 +1,14 @@
+{
+    "redaction_patterns": [
+        "dop_v1_[a-f0-9]{64}",
+        "[sp]k_live_[a-zA-Z0-9]{24,}",
+        "[sp]k_test_[a-zA-Z0-9]{24,}",
+        "(https?://)[^\\s:]+:[^\\s@]+",
+        "Bearer\\s[a-zA-Z0-9\\._\\-]{20,}",
+        "(password|pwd|pass)=([^\\s&]+)",
+        "AKIA[0-9A-Z]{16}",
+        "[0-9a-zA-Z/+]{40}",
+        "\\b\\d{1,3}\\.\\d{1,3}\\.\\d{1,3}\\.\\d{1,3}\\b",
+        "[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}"
+    ]
+}

xenfra_sdk/privacy.py

@@ -0,0 +1,118 @@
+"""
+This module contains the Privacy Scrubber for the Xenfra SDK.
+Its purpose is to redact sensitive information from logs or other text
+before it is sent to diagnostic endpoints, upholding privacy-first principles.
+"""
+
+import json
+import re
+from pathlib import Path
+from typing import List, Optional
+
+import httpx  # For fetching patterns from URL
+
+# Path to the patterns file within the SDK
+_PATTERNS_FILE_PATH = Path(__file__).parent / "patterns.json"
+_REDACTION_PLACEHOLDER = "[REDACTED]"
+_CACHED_PATTERNS: List[re.Pattern] = []
+
+
+def _load_patterns_from_file(file_path: Path) -> List[str]:
+    """Loads raw regex patterns from a JSON file."""
+    if not file_path.exists():
+        print(
+            f"Warning: Patterns file not found at {file_path}. No patterns will be used for scrubbing."
+        )
+        return []
+    try:
+        with open(file_path, "r") as f:
+            config = json.load(f)
+        return config.get("redaction_patterns", [])
+    except json.JSONDecodeError as e:
+        print(f"Error decoding patterns.json: {e}. Falling back to empty patterns.")
+        return []
+
+
+async def _refresh_patterns_from_url(url: str) -> Optional[List[str]]:
+    """
+    Fetches updated patterns from a URL asynchronously.
+    """
+    try:
+        async with httpx.AsyncClient() as client:
+            response = await client.get(url, timeout=5.0)
+            response.raise_for_status()
+            config = response.json()
+            return config.get("redaction_patterns", [])
+    except httpx.RequestError as e:
+        print(f"Error fetching patterns from {url}: {e}")
+        return None
+    except json.JSONDecodeError as e:
+        print(f"Error decoding JSON from patterns URL {url}: {e}")
+        return None
+
+
+async def initialize_scrubber(refresh_from_url: Optional[str] = None):
+    """
+    Initializes or refreshes the scrubber patterns.
+    Can optionally fetch patterns from a URL. This should be called on app startup.
+    """
+    global _CACHED_PATTERNS
+    raw_patterns = []
+
+    if refresh_from_url:
+        refreshed = await _refresh_patterns_from_url(refresh_from_url)
+        if refreshed:
+            raw_patterns = refreshed
+
+    if not raw_patterns:  # Fallback to file if no refresh URL or refresh failed
+        raw_patterns = _load_patterns_from_file(_PATTERNS_FILE_PATH)
+
+    _CACHED_PATTERNS = [re.compile(p, re.IGNORECASE) for p in raw_patterns]
+
+
+# Initialize patterns on module load (synchronously for initial load)
+# For dynamic refresh, initialize_scrubber should be called during app startup
+_raw_initial_patterns = _load_patterns_from_file(_PATTERNS_FILE_PATH)
+_CACHED_PATTERNS = [re.compile(p, re.IGNORECASE) for p in _raw_initial_patterns]
+
+
+def scrub_logs(logs: str) -> str:
+    """
+    Redacts sensitive information from log strings using loaded patterns.
+    """
+    if not logs:
+        return logs
+
+    scrubbed_logs = logs
+    for pattern_re in _CACHED_PATTERNS:
+        scrubbed_logs = pattern_re.sub(_REDACTION_PLACEHOLDER, scrubbed_logs)
+
+    return scrubbed_logs
+
+
+if __name__ == "__main__":
+    # Example Usage
+    test_logs = """
+    Deployment failed. Error: Authentication failed with token dop_v1_abcdefghijklmnopqrstuvwxyz1234567890abcdef.
+    Connecting to database at postgres://user:mypassword@127.0.0.1:5432/mydb.
+    Received request from 192.168.1.100. User: test@example.com.
+    Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.
+    eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.
+    SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c.
+    AWS Secret: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY.
+    """
+
+    # Test with file-based patterns
+    print("--- Original Logs ---")
+    print(test_logs)
+    print("\n--- Scrubbed Logs (from file) ---")
+    scrubbed_logs_from_file = scrub_logs(test_logs)
+    print(scrubbed_logs_from_file)
+
+    # Example of refreshing (conceptual)
+    # import asyncio
+    # async def demo_refresh():
+    #     await initialize_scrubber(refresh_from_url="http://example.com/new-patterns.json")
+    #     print("\n--- Scrubbed Logs (after conceptual refresh) ---")
+    #     print(scrub_logs(test_logs))
+    # asyncio.run(demo_refresh())

xenfra_sdk/recipes.py

@@ -0,0 +1,25 @@
+from pathlib import Path
+
+from jinja2 import Environment, FileSystemLoader
+
+
+def generate_stack(context: dict):
+    """
+    Generates a cloud-init startup script from a Jinja2 template.
+
+    Args:
+        context: A dictionary containing information for rendering the template,
+                 e.g., {'domain': 'example.com', 'email': 'user@example.com'}
+    """
+    # Path to the templates directory
+    template_dir = Path(__file__).parent / "templates"
+    env = Environment(loader=FileSystemLoader(template_dir))
+
+    template = env.get_template("cloud-init.sh.j2")
+
+    # The non-dockerized logic has been removed as we are focusing on
+    # a purely Docker-based deployment strategy for simplicity and scalability.
+    # The context will contain all necessary variables for the template.
+    script = template.render(context)
+
+    return script

xenfra_sdk/resources/base.py

@@ -0,0 +1,3 @@
+class BaseManager:
+    def __init__(self, client):
+        self._client = client

xenfra_sdk/resources/deployments.py

@@ -0,0 +1,83 @@
+import logging
+
+# Import Deployment model when it's defined in models.py
+# from ..models import Deployment
+from ..exceptions import XenfraAPIError, XenfraError  # Add XenfraError
+from .base import BaseManager
+
+logger = logging.getLogger(__name__)
+
+
+class DeploymentsManager(BaseManager):
+    def create(self, project_name: str, git_repo: str, branch: str, framework: str) -> dict:
+        """Creates a new deployment."""
+        try:
+            payload = {
+                "project_name": project_name,
+                "git_repo": git_repo,
+                "branch": branch,
+                "framework": framework,
+            }
+            response = self._client._request("POST", "/deployments", json=payload)
+            response.raise_for_status()
+            # Assuming the API returns a dict, which will be parsed into a Deployment model
+            return response.json()
+        except XenfraAPIError:
+            raise
+        except Exception as e:
+            raise XenfraError(f"Failed to create deployment: {e}")
+
+    def get_status(self, deployment_id: str) -> dict:
+        """Get status for a specific deployment.
+
+        Args:
+            deployment_id: The unique identifier for the deployment.
+
+        Returns:
+            dict: Deployment status information including state, progress, etc.
+
+        Raises:
+            XenfraAPIError: If the API returns an error (e.g., 404 not found).
+            XenfraError: If there's a network or parsing error.
+        """
+        try:
+            response = self._client._request("GET", f"/deployments/{deployment_id}/status")
+            logger.debug(f"DeploymentsManager.get_status({deployment_id}) response: {response.status_code}")
+            response.raise_for_status()
+            return response.json()
+        except XenfraAPIError:
+            raise  # Re-raise API errors
+        except Exception as e:
+            raise XenfraError(f"Failed to get status for deployment {deployment_id}: {e}")
+
+    def get_logs(self, deployment_id: str) -> str:
+        """Get logs for a specific deployment.
+
+        Args:
+            deployment_id: The unique identifier for the deployment.
+
+        Returns:
+            str: The deployment logs as plain text.
+
+        Raises:
+            XenfraAPIError: If the API returns an error (e.g., 404 not found).
+            XenfraError: If there's a network or parsing error.
+        """
+        try:
+            response = self._client._request("GET", f"/deployments/{deployment_id}/logs")
+            logger.debug(f"DeploymentsManager.get_logs({deployment_id}) response: {response.status_code}")
+            response.raise_for_status()
+
+            # Parse response - API should return {"logs": "log content"}
+            data = response.json()
+            logs = data.get("logs", "")
+
+            if not logs:
+                logger.warning(f"No logs found for deployment {deployment_id}")
+
+            return logs
+
+        except XenfraAPIError:
+            raise  # Re-raise API errors
+        except Exception as e:
+            raise XenfraError(f"Failed to get logs for deployment {deployment_id}: {e}")

xenfra_sdk/resources/intelligence.py

@@ -0,0 +1,102 @@
+"""
+Intelligence resource manager for Xenfra SDK.
+Provides AI-powered deployment diagnosis and codebase analysis.
+"""
+import logging
+
+from ..exceptions import XenfraAPIError, XenfraError
+from ..models import CodebaseAnalysisResponse, DiagnosisResponse
+from .base import BaseManager
+
+logger = logging.getLogger(__name__)
+
+
+class IntelligenceManager(BaseManager):
+    """
+    Manager for AI-powered intelligence operations.
+
+    Provides:
+    - Deployment failure diagnosis (Zen Nod)
+    - Codebase analysis for zero-config init (Zen Init)
+    """
+
+    def diagnose(
+        self,
+        logs: str,
+        package_manager: str | None = None,
+        dependency_file: str | None = None
+    ) -> DiagnosisResponse:
+        """
+        Diagnose deployment failure from logs using AI.
+
+        Args:
+            logs: The deployment logs to analyze
+            package_manager: Optional package manager context (uv, pip, poetry, npm, etc.)
+                           If provided, AI will target this manager's dependency file
+            dependency_file: Optional dependency file context (pyproject.toml, requirements.txt, etc.)
+                           If provided, AI will suggest patches for this file
+
+        Returns:
+            DiagnosisResponse with diagnosis, suggestion, and optional patch
+
+        Raises:
+            XenfraAPIError: If the API request fails
+            XenfraError: If parsing the response fails
+        """
+        try:
+            # Build request payload
+            payload = {"logs": logs}
+            if package_manager:
+                payload["package_manager"] = package_manager
+            if dependency_file:
+                payload["dependency_file"] = dependency_file
+
+            response = self._client._request(
+                "POST",
+                "/intelligence/diagnose",
+                json=payload
+            )
+
+            logger.debug(
+                f"IntelligenceManager.diagnose response: status={response.status_code}"
+            )
+
+            response.raise_for_status()
+            return DiagnosisResponse(**response.json())
+        except XenfraAPIError:
+            raise
+        except Exception as e:
+            raise XenfraError(f"Failed to diagnose logs: {e}")
+
+    def analyze_codebase(self, code_snippets: dict[str, str]) -> CodebaseAnalysisResponse:
+        """
+        Analyze codebase to detect framework, dependencies, and deployment config.
+
+        Args:
+            code_snippets: Dictionary of filename -> content
+                           e.g., {"main.py": "...", "requirements.txt": "..."}
+
+        Returns:
+            CodebaseAnalysisResponse with detected configuration
+
+        Raises:
+            XenfraAPIError: If the API request fails
+            XenfraError: If parsing the response fails
+        """
+        try:
+            response = self._client._request(
+                "POST",
+                "/intelligence/analyze-codebase",
+                json={"code_snippets": code_snippets}
+            )
+
+            logger.debug(
+                f"IntelligenceManager.analyze_codebase response: status={response.status_code}"
+            )
+
+            response.raise_for_status()
+            return CodebaseAnalysisResponse(**response.json())
+        except XenfraAPIError:
+            raise
+        except Exception as e:
+            raise XenfraError(f"Failed to analyze codebase: {e}")

xenfra_sdk/resources/projects.py

@@ -0,0 +1,95 @@
+import logging
+
+from ..exceptions import XenfraAPIError, XenfraError  # Add XenfraError
+from ..models import ProjectRead
+from .base import BaseManager
+
+logger = logging.getLogger(__name__)
+
+
+class ProjectsManager(BaseManager):
+    def list(self) -> list[ProjectRead]:
+        """Retrieves a list of all projects."""
+        try:
+            response = self._client._request("GET", "/projects/")  # Added trailing slash
+
+            logger.debug(
+                f"ProjectsManager.list response: status={response.status_code}, "
+                f"body={response.text[:200]}..."  # Truncate long responses
+            )
+
+            response.raise_for_status()
+            return [ProjectRead(**p) for p in response.json()["projects"]]
+        except XenfraAPIError:
+            raise  # Re-raise API errors
+        except Exception as e:
+            # Handle other exceptions like JSON parsing errors
+            raise XenfraError(f"Failed to list projects: {e}")
+
+    def show(self, project_id: int) -> ProjectRead:
+        """Get details for a specific project.
+
+        Args:
+            project_id: The unique identifier for the project.
+
+        Returns:
+            ProjectRead: The project details.
+
+        Raises:
+            XenfraAPIError: If the API returns an error (e.g., 404 not found).
+            XenfraError: If there's a network or parsing error.
+        """
+        try:
+            response = self._client._request("GET", f"/projects/{project_id}")
+            logger.debug(f"ProjectsManager.show({project_id}) response: {response.status_code}")
+            response.raise_for_status()
+            return ProjectRead(**response.json())
+        except XenfraAPIError:
+            raise  # Re-raise API errors
+        except Exception as e:
+            raise XenfraError(f"Failed to get project {project_id}: {e}")
+
+    def create(
+        self,
+        name: str,
+        region: str = "nyc3",
+        size_slug: str = "s-1vcpu-1gb"
+    ) -> ProjectRead:
+        """Create a new project.
+
+        Args:
+            name: The name for the new project.
+            region: The DigitalOcean region (default: nyc3).
+            size_slug: The droplet size slug (default: s-1vcpu-1gb).
+
+        Returns:
+            ProjectRead: The newly created project details.
+
+        Raises:
+            XenfraAPIError: If the API returns an error.
+            XenfraError: If there's a network or parsing error.
+        """
+        try:
+            payload = {
+                "name": name,
+                "region": region,
+                "size_slug": size_slug
+            }
+            logger.debug(f"ProjectsManager.create payload: {payload}")
+            response = self._client._request("POST", "/projects/", json=payload)
+            response.raise_for_status()
+            return ProjectRead(**response.json())
+        except XenfraAPIError:
+            raise
+        except Exception as e:
+            raise XenfraError(f"Failed to create project '{name}': {e}")
+
+    def delete(self, project_id: str) -> None:
+        """Deletes a project."""
+        try:
+            response = self._client._request("DELETE", f"/projects/{project_id}")
+            response.raise_for_status()
+        except XenfraAPIError:
+            raise
+        except Exception as e:
+            raise XenfraError(f"Failed to delete project {project_id}: {e}")

xenfra_sdk/security.py

@@ -0,0 +1,41 @@
+# src/xenfra_sdk/security.py
+"""
+Security utilities for the Xenfra SDK.
+Provides token encryption/decryption for storing OAuth credentials.
+"""
+
+import os
+from typing import Optional
+
+from cryptography.fernet import Fernet
+
+# --- Configuration from Environment ---
+# These should be set in the service's environment
+ENCRYPTION_KEY = os.getenv("ENCRYPTION_KEY", "")
+
+
+def _get_fernet() -> Optional[Fernet]:
+    """Get Fernet instance for encryption/decryption."""
+    if not ENCRYPTION_KEY:
+        return None
+    try:
+        return Fernet(ENCRYPTION_KEY.encode())
+    except Exception:
+        return None
+
+
+# --- Token Encryption ---
+def encrypt_token(token: str) -> str:
+    """Encrypts a token using Fernet symmetric encryption."""
+    fernet = _get_fernet()
+    if fernet is None:
+        raise ValueError("ENCRYPTION_KEY environment variable is not set or invalid")
+    return fernet.encrypt(token.encode()).decode()
+
+
+def decrypt_token(encrypted_token: str) -> str:
+    """Decrypts a token."""
+    fernet = _get_fernet()
+    if fernet is None:
+        raise ValueError("ENCRYPTION_KEY environment variable is not set or invalid")
+    return fernet.decrypt(encrypted_token.encode()).decode()

xenfra_sdk/templates/Dockerfile.j2

@@ -0,0 +1,25 @@
+# Dockerfile template for Python web applications
+FROM {{ python_version | default('python:3.11-slim') }}
+
+WORKDIR /app
+
+# Install uv, our preferred package manager
+RUN apt-get update && apt-get install -y curl && \
+    curl -LsSf https://astral.sh/uv/install.sh | sh && \
+    apt-get remove -y curl && \
+    apt-get clean && \
+    rm -rf /var/lib/apt/lists/*
+
+COPY requirements.txt .
+
+# Install dependencies
+RUN /root/.cargo/bin/uv pip install --system --no-cache -r requirements.txt
+
+COPY . .
+
+# Expose the application port
+EXPOSE {{ port | default(8000) }}
+
+# The command to run the application will be in docker-compose.yml
+# This allows for more flexibility
+