xenfra-sdk 0.2.5__tar.gz → 0.2.7__tar.gz

xenfra_sdk-0.2.7/PKG-INFO

@@ -0,0 +1,118 @@
+Metadata-Version: 2.3
+Name: xenfra-sdk
+Version: 0.2.7
+Summary: Xenfra SDK: Core engine and utilities for the Xenfra platform.
+Author: xenfra-cloud
+Author-email: xenfra-cloud <xenfracloud@gmail.com>
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: System :: Systems Administration
+Requires-Dist: fabric>=3.2.2
+Requires-Dist: python-digitalocean>=1.17.0
+Requires-Dist: python-dotenv>=1.2.1
+Requires-Dist: rich>=14.2.0
+Requires-Dist: sqlmodel>=0.0.16
+Requires-Dist: pyyaml>=6.0.1
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: jinja2>=3.1.3
+Requires-Dist: python-jose[cryptography]>=3.3.0
+Requires-Dist: passlib>=1.7.4
+Requires-Dist: cryptography>=41.0.0
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+
+# Xenfra Python SDK
+
+The official, open-source Python SDK for interacting with the Xenfra API.
+
+This SDK provides a simple and Pythonic interface for developers and AI Agents to programmatically manage infrastructure, deployments, and other platform resources.
+
+## Installation
+
+```bash
+pip install xenfra-sdk
+```
+
+## Basic Usage
+
+Initialize the client with your API token (or ensure the `XENFRA_TOKEN` environment variable is set).
+
+```python
+import os
+from xenfra_sdk import XenfraClient
+from xenfra_sdk.exceptions import XenfraAPIError
+
+client = XenfraClient(token=os.getenv("XENFRA_TOKEN"))
+
+try:
+    projects = client.projects.list()
+    for p in projects:
+        print(f"Found project: {p.name} (Status: {p.status})")
+except XenfraAPIError as e:
+    print(f"API Error: {e.detail}")
+```
+
+## Usage for Agentic Workflows
+
+The Xenfra SDK is designed to be used as a "tool" by AI Agents (e.g., OpenAI Assistants). The Pydantic models are compatible with function-calling schemas, allowing an agent to easily call these methods.
+
+Here is a conceptual example of how an agent might use the SDK to fulfill a user's request.
+
+```python
+# This is a conceptual representation of an agent's internal logic.
+# The agent would be configured with functions that call these SDK methods.
+
+def list_all_projects():
+    """Lists all available projects in the Xenfra account."""
+    return client.projects.list()
+
+def create_new_deployment(project_name: str, git_repo: str, branch: str = "main"):
+    """
+    Creates a new deployment for a project.
+    
+    Args:
+        project_name: The name for the new deployment.
+        git_repo: The URL of the git repository to deploy.
+        branch: The branch to deploy (defaults to 'main').
+    """
+    return client.deployments.create(
+        project_name=project_name,
+        git_repo=git_repo,
+        branch=branch,
+        framework="fastapi" # Framework detection would be part of a more complex agent
+    )
+
+# --- Agent Execution Flow ---
+
+# User prompt: "Deploy my new app from github.com/user/my-app"
+
+# 1. Agent decides which tool to use: `create_new_deployment`
+# 2. Agent extracts parameters:
+#    - project_name = "my-app" (inferred)
+#    - git_repo = "https://github.com/user/my-app"
+# 3. Agent calls the tool:
+#    create_new_deployment(
+#        project_name="my-app",
+#        git_repo="https://github.com/user/my-app"
+#    )
+```
+
+## Error Handling
+
+The SDK uses custom exceptions for clear error handling. All API-related errors will raise a `XenfraAPIError`, which contains the `status_code` and a `detail` message from the API response.
+
+```python
+from xenfra_sdk.exceptions import XenfraAPIError, AuthenticationError
+
+try:
+    # Make an API call
+    ...
+except AuthenticationError as e:
+    print("Authentication failed. Please check your token.")
+except XenfraAPIError as e:
+    print(f"An API error occurred with status {e.status_code}: {e.detail}")
+```

xenfra_sdk-0.2.7/README.md

@@ -0,0 +1,91 @@
+# Xenfra Python SDK
+
+The official, open-source Python SDK for interacting with the Xenfra API.
+
+This SDK provides a simple and Pythonic interface for developers and AI Agents to programmatically manage infrastructure, deployments, and other platform resources.
+
+## Installation
+
+```bash
+pip install xenfra-sdk
+```
+
+## Basic Usage
+
+Initialize the client with your API token (or ensure the `XENFRA_TOKEN` environment variable is set).
+
+```python
+import os
+from xenfra_sdk import XenfraClient
+from xenfra_sdk.exceptions import XenfraAPIError
+
+client = XenfraClient(token=os.getenv("XENFRA_TOKEN"))
+
+try:
+    projects = client.projects.list()
+    for p in projects:
+        print(f"Found project: {p.name} (Status: {p.status})")
+except XenfraAPIError as e:
+    print(f"API Error: {e.detail}")
+```
+
+## Usage for Agentic Workflows
+
+The Xenfra SDK is designed to be used as a "tool" by AI Agents (e.g., OpenAI Assistants). The Pydantic models are compatible with function-calling schemas, allowing an agent to easily call these methods.
+
+Here is a conceptual example of how an agent might use the SDK to fulfill a user's request.
+
+```python
+# This is a conceptual representation of an agent's internal logic.
+# The agent would be configured with functions that call these SDK methods.
+
+def list_all_projects():
+    """Lists all available projects in the Xenfra account."""
+    return client.projects.list()
+
+def create_new_deployment(project_name: str, git_repo: str, branch: str = "main"):
+    """
+    Creates a new deployment for a project.
+    
+    Args:
+        project_name: The name for the new deployment.
+        git_repo: The URL of the git repository to deploy.
+        branch: The branch to deploy (defaults to 'main').
+    """
+    return client.deployments.create(
+        project_name=project_name,
+        git_repo=git_repo,
+        branch=branch,
+        framework="fastapi" # Framework detection would be part of a more complex agent
+    )
+
+# --- Agent Execution Flow ---
+
+# User prompt: "Deploy my new app from github.com/user/my-app"
+
+# 1. Agent decides which tool to use: `create_new_deployment`
+# 2. Agent extracts parameters:
+#    - project_name = "my-app" (inferred)
+#    - git_repo = "https://github.com/user/my-app"
+# 3. Agent calls the tool:
+#    create_new_deployment(
+#        project_name="my-app",
+#        git_repo="https://github.com/user/my-app"
+#    )
+```
+
+## Error Handling
+
+The SDK uses custom exceptions for clear error handling. All API-related errors will raise a `XenfraAPIError`, which contains the `status_code` and a `detail` message from the API response.
+
+```python
+from xenfra_sdk.exceptions import XenfraAPIError, AuthenticationError
+
+try:
+    # Make an API call
+    ...
+except AuthenticationError as e:
+    print("Authentication failed. Please check your token.")
+except XenfraAPIError as e:
+    print(f"An API error occurred with status {e.status_code}: {e.detail}")
+```

{xenfra_sdk-0.2.5 → xenfra_sdk-0.2.7}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "xenfra-sdk"
-version = "0.2.5"
+version = "0.2.7"
 description = "Xenfra SDK: Core engine and utilities for the Xenfra platform."
 readme = "README.md"
 authors = [
@@ -30,24 +30,7 @@ dependencies = [
     "passlib>=1.7.4",
     "cryptography>=41.0.0",
 ]
-requires-python = ">=3.11"
-
-[project.urls]
-Homepage = "https://github.com/xenfra-cloud/xenfra-sdk"
-Issues = "https://github.com/xenfra-cloud/xenfra-sdk/issues"
-
-[project.optional-dependencies]
-dev = [
-    "pytest>=8.0.0",
-    "pytest-mock>=3.12.0",
-    "pytest-cov>=4.0.0",
-    "pytest-asyncio>=0.21.0"
-]
-
-[tool.pytest.ini_options]
-asyncio_mode = "auto"
-testpaths = ["tests"]
-python_files = ["test_*.py"]
+requires-python = ">=3.13"
 
 [build-system]
 requires = ["uv_build>=0.9.18,<0.10.0"]

{xenfra_sdk-0.2.5 → xenfra_sdk-0.2.7}/src/xenfra_sdk/__init__.py

@@ -1,16 +1,23 @@
 # This file makes src/xenfra_sdk a Python package.
 
 from .client import XenfraClient
-from .exceptions import AuthenticationError, XenfraAPIError, XenfraError
+from .engine import InfraEngine
+from .events import BuildEvent, DeploymentPhase, EventEmitter, EventStatus
+from .exceptions import AuthenticationError, DeploymentError, XenfraAPIError, XenfraError
+from .protocol import ProtocolRegistry
 from .models import (
+    BalanceRead,
     CodebaseAnalysisResponse,
     DiagnosisResponse,
+    DropletCostRead,
     PatchObject,
     ProjectRead,
 )
 
-# Microservices support
+# Microservices & Config support
 from .manifest import (
+    XenfraConfig,
+    load_xenfra_config,
     ServiceDefinition,
     load_services_from_xenfra_yaml,
     is_microservices_project,
@@ -37,6 +44,22 @@ from .security_scanner import (
     Severity,
 )
 
+# Railpack Integration
+from .railpack_detector import (
+    RailpackDetector,
+    RailpackDetectionResult,
+    EnvVariable,
+    get_railpack_detector,
+)
+from .railpack_manager import (
+    RailpackManager,
+    get_railpack_manager,
+)
+from .railpack_adapter import (
+    RailpackAdapter,
+    RailpackPlan,
+)
+
 __all__ = [
     "XenfraClient",
     "XenfraError",
@@ -46,6 +69,11 @@ __all__ = [
     "CodebaseAnalysisResponse",
     "PatchObject",
     "ProjectRead",
+    "BalanceRead",
+    "DropletCostRead",
+    # Config
+    "XenfraConfig",
+    "load_xenfra_config",
     # Microservices
     "ServiceDefinition",
     "load_services_from_xenfra_yaml",
@@ -58,4 +86,20 @@ __all__ = [
     "detect_pyproject_services",
     "ServiceOrchestrator",
     "get_orchestrator_for_project",
+    "InfraEngine",
+    "DeploymentError",
+    "ProtocolRegistry",
+    "EventEmitter",
+    "BuildEvent",
+    "DeploymentPhase",
+    "EventStatus",
+    # Railpack Integration
+    "RailpackDetector",
+    "RailpackDetectionResult",
+    "EnvVariable",
+    "get_railpack_detector",
+    "RailpackManager",
+    "get_railpack_manager",
+    "RailpackAdapter",
+    "RailpackPlan",
 ]

xenfra_sdk-0.2.7/src/xenfra_sdk/blueprints/base.py

@@ -0,0 +1,150 @@
+import yaml
+from abc import ABC, abstractmethod
+from typing import Dict, List, Optional
+from pathlib import Path
+
+from xenfra_sdk.blueprints.schema import (
+    DeploymentBlueprintManifest, DockerfileModel, ComposeModel, ServiceDetail,
+    DeployModel, DeployResourcesModel, ResourceLimitsModel, ResourceReservationsModel
+)
+
+from xenfra_sdk.constants import DEFAULT_PORT_RANGE_START
+
+class BaseBlueprint(ABC):
+    """
+    Abstract base class for all Xenfra Blueprints (Build Packs).
+    
+    A Blueprint is responsible for:
+    1. Analyzing code to detect requirements.
+    2. Building a valid Pydantic manifest.
+    3. Rendering that manifest to files (Dockerfile, compose, env).
+    """
+
+    def __init__(self, context: dict):
+        self.context = context
+        self.framework = context.get("framework")
+        self.port = context.get("port") or DEFAULT_PORT_RANGE_START
+        self.file_manifest = context.get("file_manifest", [])
+        self.resource_limits = context.get("resource_limits", {})
+
+    def _generate_deploy_model(self) -> DeployModel:
+        """Centralized helper for resource governance."""
+        return DeployModel(
+            resources=DeployResourcesModel(
+                limits=ResourceLimitsModel(
+                    memory=self.resource_limits.get("memory", "512m"),
+                    cpus=self.resource_limits.get("cpus", "0.5"),
+                ),
+                reservations=ResourceReservationsModel(
+                    memory=self.resource_limits.get("memory_reserved", "128m"),
+                    cpus=self.resource_limits.get("cpus_reserved", "0.25"),
+                ),
+            )
+        )
+
+    @abstractmethod
+    def generate_manifest(self) -> DeploymentBlueprintManifest:
+        """Analyze context and files to build the Pydantic manifest."""
+        pass
+
+    def render(self) -> Dict[str, str]:
+        """Renders the generated manifest into final deployment strings."""
+        manifest = self.generate_manifest()
+        result = {}
+
+        # 1. Render Dockerfile
+        result["Dockerfile"] = self._render_dockerfile(manifest.dockerfile)
+
+        # 2. Render docker-compose.yml
+        result["docker-compose.yml"] = self._render_compose(manifest.compose)
+
+        # 3. Render .env
+        if manifest.env_file:
+            result[".env"] = "\n".join([f'{k}="{v}"' for k, v in manifest.env_file.items()])
+
+        # 4. Render Caddyfile (if provided)
+        if manifest.caddyfile:
+            result["Caddyfile"] = manifest.caddyfile
+
+        # 5. Render Railpack Plan (if provided)
+        if hasattr(manifest, "railpack_plan") and manifest.railpack_plan:
+            result["railpack-plan.json"] = manifest.railpack_plan
+
+        return result
+
+    def _render_dockerfile(self, model: DockerfileModel) -> str:
+        """Converts DockerfileModel to a string."""
+        lines = [f"FROM {model.base_image}"]
+        
+        # Inject ARG instructions (Build-time variables)
+        # Must come after FROM (usually) or before depending on if they affect FROM
+        # Standard practice: FROM -> ARG -> WORKDIR -> COPY -> RUN
+        if model.args:
+            for arg in model.args:
+                lines.append(f"ARG {arg}")
+
+        # APT packages
+        if model.system_packages:
+            packages = " ".join(model.system_packages)
+            lines.append("RUN apt-get update && apt-get install -y " + packages + " && rm -rf /var/lib/apt/lists/*")
+
+        lines.append(f"WORKDIR {model.workdir}")
+
+        # Env vars (Non-secret defaults only)
+        # We rely on .env + docker-compose for actual deployment values.
+        # ARGs are already available during build.
+        arg_keys = set(model.args)
+        for k, v in model.env_vars.items():
+            if k in arg_keys:
+                # Skip ENV if it's already an ARG, to keep secrets out of Dockerfile and fix syntax errors
+                continue
+            # Quote values for safety
+            lines.append(f'ENV {k}="{v}"')
+
+        # Copy commands
+        if model.copy_dirs:
+            for d in model.copy_dirs:
+                lines.append(f"COPY {d} .")
+        else:
+            lines.append("COPY . .")
+
+        # Custom RUN commands
+        for cmd in model.run_commands:
+            lines.append(f"RUN {cmd}")
+
+        if model.expose_port:
+            lines.append(f"EXPOSE {model.expose_port}")
+
+        if model.entrypoint:
+            if isinstance(model.entrypoint, list):
+                ep = ", ".join([f'"{x}"' for x in model.entrypoint])
+                lines.append(f"ENTRYPOINT [{ep}]")
+            else:
+                lines.append(f"ENTRYPOINT {model.entrypoint}")
+
+        if model.command:
+            if isinstance(model.command, list):
+                cmd = ", ".join([f'"{x}"' for x in model.command])
+                lines.append(f"CMD [{cmd}]")
+            else:
+                lines.append(f"CMD {model.command}")
+
+        return "\n".join(lines)
+
+    def _render_compose(self, model: ComposeModel) -> str:
+        """Converts ComposeModel to a YAML string."""
+        # We use a custom dumper to ensure services come first etc if needed
+        # But standard yaml works for start
+        data = model.model_dump(by_alias=True, exclude_none=True)
+        return yaml.dump(data, sort_keys=False, default_flow_style=False)
+
+    def has_file(self, filename: str) -> bool:
+        """Helper to check if a file exists in the manifest."""
+        return any(f.get("path") == filename for f in self.file_manifest)
+
+    def get_file_content(self, filename: str) -> Optional[str]:
+        """Helper to get file content from manifest."""
+        for f in self.file_manifest:
+            if f.get("path") == filename:
+                return f.get("content")
+        return None

xenfra_sdk-0.2.7/src/xenfra_sdk/blueprints/factory.py

@@ -0,0 +1,99 @@
+from typing import Type, Dict, List
+from xenfra_sdk.blueprints.base import BaseBlueprint
+from xenfra_sdk.blueprints.python import PythonBlueprint
+from xenfra_sdk.blueprints.node import NodeBlueprint
+from xenfra_sdk.blueprints.railpack import RailpackBlueprint
+from xenfra_sdk.governance import get_resource_limits, ResourceLimits
+
+
+def resolve_blueprint_class(context: dict) -> Type[BaseBlueprint]:
+    """
+    The 'Check-In Desk' for manifest generation.
+    Decides between Sovereign (Lean) and Specialist (Railpack) paths.
+    
+    Priority:
+    1. Explicit framework selection (user-specified)
+    2. File-based detection fallback
+    """
+    framework = str(context.get("framework", "")).lower().strip()
+    file_manifest = context.get("file_manifest", [])
+    file_names = {f.get("path") for f in file_manifest}
+
+    # 1. EXPLICIT FRAMEWORK SELECTION (takes priority)
+    # If user explicitly selected a framework, respect that choice
+    SOVEREIGN_PYTHON = ("python", "fastapi", "flask", "django")
+    
+    # Modern Node.js frameworks that need railpack (auto-detect + build)
+    # These have complex build pipelines that railpack/nixpacks handles better
+    RAILPACK_NODE = ("next", "nextjs", "nuxt", "vite", "nestjs", "nest")
+    
+    # Simple Node.js that can use our lean NodeBlueprint
+    # Only for Express-style apps without complex build steps
+    SOVEREIGN_NODE = ("express",)
+    
+    if framework in SOVEREIGN_PYTHON:
+        # Check for complex package managers (uv, poetry, pipenv) -> Use Railpack
+        if any(f in file_names for f in ("uv.lock", "poetry.lock", "Pipfile.lock")):
+            return RailpackBlueprint
+        return PythonBlueprint
+    
+    # Route modern frameworks to RailpackBlueprint
+    if framework in RAILPACK_NODE:
+        return RailpackBlueprint
+    
+    # Generic "node" or "nodejs" → check file_manifest for framework hints
+    if framework in ("node", "nodejs"):
+        # Check for Next.js, Nuxt, etc. config files
+        nextjs_configs = {"next.config.js", "next.config.ts", "next.config.mjs"}
+        nuxt_configs = {"nuxt.config.js", "nuxt.config.ts"}
+        vite_configs = {"vite.config.js", "vite.config.ts"}
+        
+        if nextjs_configs & file_names or nuxt_configs & file_names or vite_configs & file_names:
+            return RailpackBlueprint
+        
+        # Default to RailpackBlueprint for generic Node.js (safer, handles more cases)
+        return RailpackBlueprint
+    
+    if framework in SOVEREIGN_NODE:
+        return NodeBlueprint
+        
+    # 2. FILE-BASED DETECTION FALLBACK (only if no explicit framework)
+    # Check for Python Sovereign Path (Strict Golden Path)
+    if "requirements.txt" in file_names and "pyproject.toml" not in file_names:
+        return PythonBlueprint
+        
+    # Check for Node Sovereign Path (Strict Golden Path) 
+    # Only for simple Express apps with package-lock.json
+    if "package-lock.json" in file_names and "package.json" in file_names:
+        # If has modern framework config files, use Railpack
+        nextjs_configs = {"next.config.js", "next.config.ts", "next.config.mjs"}
+        if nextjs_configs & file_names:
+            return RailpackBlueprint
+        # Otherwise, still prefer RailpackBlueprint for safety
+        return RailpackBlueprint
+
+    # 3. Specialist Path (The Delegate)
+    # Handles EVERYTHING else: Rust, Go, Bun, UV, Poetry, etc.
+    return RailpackBlueprint
+
+
+def render_blueprint(context: dict) -> Dict[str, str]:
+    """
+    Main entry point for manifest generation.
+    Resolves the blueprint and renders it to strings.
+
+    ZEN GAP FIX: Automatically injects tier-based resource limits.
+    """
+    # Inject resource limits if tier is provided but resource_limits isn't
+    if "resource_limits" not in context and "tier" in context:
+        limits = get_resource_limits(context["tier"])
+        context["resource_limits"] = {
+            "memory": limits.memory,
+            "cpus": limits.cpus,
+            "memory_reserved": limits.memory_reserved,
+            "cpus_reserved": limits.cpus_reserved,
+        }
+
+    blueprint_class = resolve_blueprint_class(context)
+    blueprint = blueprint_class(context)
+    return blueprint.render()