cycls 0.0.2.31__py3-none-any.whl → 0.0.2.32__py3-none-any.whl

cycls/__init__.py

@@ -1 +1,2 @@
-from .cycls import Agent
+from .cycls import Agent
+from .sdk import function

cycls/cycls.py

@@ -164,5 +164,6 @@ class Agent:
                 with modal.enable_output(), run_app(app=self.app, client=self.client): 
                     while True: time.sleep(10)
 
+# poetry config pypi-token.pypi <your-token>
 # poetry run python agent.py
 # poetry publish --build

cycls/runtime.py

@@ -0,0 +1,395 @@
+import docker
+import cloudpickle
+import tempfile
+import hashlib
+import os
+import sys
+import shutil
+from pathlib import Path
+from contextlib import contextmanager
+import tarfile
+
+# --- Docker Client Initialization ---
+try:
+    docker_client = docker.from_env()
+except docker.errors.DockerException:
+    print("❌ Error: Docker is not running or not installed.")
+    print("Please start the Docker daemon and try again.")
+    sys.exit(1)
+
+# --- Top-Level Helper Functions ---
+
+def _bootstrap_script(payload_file: str, result_file: str) -> str:
+    """Generates the Python script that runs inside the Docker container."""
+    return f"""
+import cloudpickle
+import sys
+import os
+import traceback
+from pathlib import Path
+
+if __name__ == "__main__":
+    io_dir = Path(sys.argv[1])
+    payload_path = io_dir / '{payload_file}'
+    result_path = io_dir / '{result_file}'
+
+    try:
+        with open(payload_path, 'rb') as f:
+            func, args, kwargs = cloudpickle.load(f)
+
+        result = func(*args, **kwargs)
+
+        with open(result_path, 'wb') as f:
+            cloudpickle.dump(result, f)
+
+    except Exception as e:
+        traceback.print_exc(file=sys.stderr)
+        sys.exit(1)
+"""
+
+def _hash_path(path_str: str) -> str:
+    """Hashes a file or a directory's contents to create a deterministic signature."""
+    h = hashlib.sha256()
+    p = Path(path_str)
+    if p.is_file():
+        with p.open('rb') as f:
+            while chunk := f.read(65536):
+                h.update(chunk)
+    elif p.is_dir():
+        for root, dirs, files in os.walk(p, topdown=True):
+            dirs.sort()
+            files.sort()
+            for name in files:
+                filepath = Path(root) / name
+                relpath = filepath.relative_to(p)
+                h.update(str(relpath).encode())
+                with filepath.open('rb') as f:
+                    while chunk := f.read(65536):
+                        h.update(chunk)
+    return h.hexdigest()
+
+def _copy_path(src_path: Path, dest_path: Path):
+    """Recursively copies a file or directory to a destination path."""
+    if src_path.is_dir():
+        shutil.copytree(src_path, dest_path, dirs_exist_ok=True)
+    else:
+        dest_path.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copy(src_path, dest_path)
+
+# --- Main Runtime Class ---
+
+class Runtime:
+    """
+    Handles building a Docker image and executing a function within a container.
+    """
+    def __init__(self, func, name, python_version=None, pip_packages=None, apt_packages=None, run_commands=None, copy=None, base_url=None, api_key=None):
+        self.func = func
+        self.python_version = python_version or "3.12"
+        self.pip_packages = sorted(pip_packages or [])
+        self.apt_packages = sorted(apt_packages or [])
+        self.run_commands = sorted(run_commands or [])
+        self.copy = copy or {}
+        self.name = name
+        self.base_url = base_url or "https://service-core-280879789566.me-central1.run.app"
+        self.image_prefix = f"cycls/{name}"
+
+        # Standard paths and filenames used inside the container
+        self.io_dir = "/app/io"
+        self.runner_filename = "runner.py"
+        self.runner_path = f"/app/{self.runner_filename}"
+        self.payload_file = "payload.pkl"
+        self.result_file = "result.pkl"
+
+        self.runner_script = _bootstrap_script(self.payload_file, self.result_file)
+        self.tag = self._generate_base_tag()
+
+        self.api_key = api_key
+
+    def _generate_base_tag(self) -> str:
+        """Creates a unique tag for the base Docker image based on its dependencies."""
+        signature_parts = [
+            "".join(self.python_version),
+            "".join(self.pip_packages),
+            "".join(self.apt_packages),
+            "".join(self.run_commands),
+            self.runner_script
+        ]
+        for src, dst in sorted(self.copy.items()):
+            if not Path(src).exists():
+                raise FileNotFoundError(f"Path in 'copy' not found: {src}")
+            content_hash = _hash_path(src)
+            signature_parts.append(f"copy:{src}>{dst}:{content_hash}")
+
+        signature = "".join(signature_parts)
+        image_hash = hashlib.sha256(signature.encode()).hexdigest()
+        return f"{self.image_prefix}:{image_hash[:16]}"
+
+    def _generate_dockerfile(self, port=None) -> str:
+        """Generates a multi-stage Dockerfile string."""
+        run_pip_install = f"RUN pip install --no-cache-dir cloudpickle {' '.join(self.pip_packages)}"
+        run_apt_install = (
+            f"RUN apt-get update && apt-get install -y --no-install-recommends {' '.join(self.apt_packages)}"
+            if self.apt_packages else ""
+        )
+        run_shell_commands = "\n".join([f"RUN {cmd}" for cmd in self.run_commands]) if self.run_commands else ""
+        copy_lines = "\n".join([f"COPY {src} {dst}" for src, dst in self.copy.items()])
+        expose_line = f"EXPOSE {port}" if port else ""
+
+        return f"""
+# STAGE 1: Base image with all dependencies
+FROM python:{self.python_version}-slim as base
+ENV PIP_ROOT_USER_ACTION=ignore
+ENV PYTHONUNBUFFERED=1
+RUN mkdir -p {self.io_dir}
+{run_apt_install}
+{run_pip_install}
+{run_shell_commands}
+{copy_lines}
+COPY {self.runner_filename} {self.runner_path}
+ENTRYPOINT ["python", "{self.runner_path}", "{self.io_dir}"]
+
+# STAGE 2: Final deployable image with the payload "baked in"
+FROM base
+{expose_line}
+COPY {self.payload_file} {self.io_dir}/
+"""
+
+    def _prepare_build_context(self, workdir: Path, include_payload=False, args=None, kwargs=None):
+        """Prepares a complete build context in the given directory."""
+        port = kwargs.get('port') if kwargs else None
+        
+        (workdir / "Dockerfile").write_text(self._generate_dockerfile(port=port))
+        (workdir / self.runner_filename).write_text(self.runner_script)
+
+        if include_payload:
+            payload_bytes = cloudpickle.dumps((self.func, args or [], kwargs or {}))
+            (workdir / self.payload_file).write_bytes(payload_bytes)
+
+        if self.copy:
+            for src in self.copy.keys():
+                _copy_path(Path(src), workdir / src)
+
+    def _build_image_if_needed(self):
+        """Checks if the base Docker image exists locally and builds it if not."""
+        try:
+            docker_client.images.get(self.tag)
+            print(f"✅ Found cached base image: {self.tag}")
+            return
+        except docker.errors.ImageNotFound:
+            print(f"🛠️  Building new base image: {self.tag}")
+
+        with tempfile.TemporaryDirectory() as tmpdir_str:
+            tmpdir = Path(tmpdir_str)
+            # Prepare context without payload for the base image
+            self._prepare_build_context(tmpdir)
+            
+            print("--- 🐳 Docker Build Logs (Base Image) ---")
+            response_generator = docker_client.api.build(
+                path=str(tmpdir),
+                tag=self.tag,
+                forcerm=True,
+                decode=True,
+                target='base' # Only build the 'base' stage
+            )
+            try:
+                for chunk in response_generator:
+                    if 'stream' in chunk:
+                        print(chunk['stream'].strip())
+                print("----------------------------------------")
+                print(f"✅ Base image built successfully: {self.tag}")
+            except docker.errors.BuildError as e:
+                print(f"\n❌ Docker build failed. Reason: {e}")
+                raise
+
+    @contextmanager
+    def runner(self, *args, **kwargs):
+        """Context manager to set up, run, and tear down the container for local execution."""
+        port = kwargs.get('port', None)
+        self._build_image_if_needed()
+        container = None
+        ports_mapping = {f'{port}/tcp': port} if port else None
+
+        with tempfile.TemporaryDirectory() as tmpdir_str:
+            tmpdir = Path(tmpdir_str)
+            payload_path = tmpdir / self.payload_file
+            result_path = tmpdir / self.result_file
+
+            with payload_path.open('wb') as f:
+                cloudpickle.dump((self.func, args, kwargs), f)
+
+            try:
+                container = docker_client.containers.create(
+                    image=self.tag,
+                    volumes={str(tmpdir): {'bind': self.io_dir, 'mode': 'rw'}},
+                    ports=ports_mapping
+                )
+                container.start()
+                yield container, result_path
+            finally:
+                if container:
+                    print("\n🧹 Cleaning up container...")
+                    try:
+                        container.stop(timeout=5)
+                        container.remove()
+                        print("✅ Container stopped and removed.")
+                    except docker.errors.APIError as e:
+                        print(f"⚠️  Could not clean up container: {e}")
+
+    def run(self, *args, **kwargs):
+        """Executes the function in a new Docker container and waits for the result."""
+        print(f"🚀 Running function '{self.name}' in container...")
+        try:
+            with self.runner(*args, **kwargs) as (container, result_path):
+                print("--- 🪵 Container Logs (streaming) ---")
+                for chunk in container.logs(stream=True, follow=True):
+                    print(chunk.decode('utf-8').strip())
+                print("------------------------------------")
+
+                result_status = container.wait()
+                if result_status['StatusCode'] != 0:
+                    print(f"\n❌ Error: Container exited with code: {result_status['StatusCode']}")
+                    return None
+                
+                if result_path.exists():
+                    with result_path.open('rb') as f:
+                        result = cloudpickle.load(f)
+                    print("✅ Function executed successfully.")
+                    return result
+                else:
+                    print("\n❌ Error: Result file not found.")
+                    return None
+        except (KeyboardInterrupt, docker.errors.DockerException) as e:
+            print(f"\n🛑 Operation stopped: {e}")
+            return None
+
+    def build(self, *args, **kwargs):
+        """Builds a self-contained, deployable Docker image locally."""
+        print("📦 Building self-contained image for deployment...")
+        payload_hash = hashlib.sha256(cloudpickle.dumps((self.func, args, kwargs))).hexdigest()[:16]
+        final_tag = f"{self.image_prefix}:deploy-{payload_hash}"
+
+        try:
+            docker_client.images.get(final_tag)
+            print(f"✅ Found cached deployable image: {final_tag}")
+            return final_tag
+        except docker.errors.ImageNotFound:
+            print(f"🛠️  Building new deployable image: {final_tag}")
+
+        with tempfile.TemporaryDirectory() as tmpdir_str:
+            tmpdir = Path(tmpdir_str)
+            self._prepare_build_context(tmpdir, include_payload=True, args=args, kwargs=kwargs)
+
+            print("--- 🐳 Docker Build Logs (Final Image) ---")
+            response_generator = docker_client.api.build(
+                path=str(tmpdir), tag=final_tag, forcerm=True, decode=True
+            )
+            try:
+                for chunk in response_generator:
+                    if 'stream' in chunk:
+                        print(chunk['stream'].strip())
+                print("-----------------------------------------")
+                print(f"✅ Image built successfully: {final_tag}")
+                port = kwargs.get('port') if kwargs else None
+                print(f"🤖 Run: docker run --rm -d -p {port}:{port} {final_tag}")
+                return final_tag
+            except docker.errors.BuildError as e:
+                print(f"\n❌ Docker build failed. Reason: {e}")
+                return None
+
+    def deploy(self, *args, **kwargs):
+        """Deploys the function by sending it to a remote build server."""
+        import requests
+
+        print(f"🚀 Preparing to deploy function '{self.name}'")
+
+        # 1. Prepare the build context and compress it into a tarball
+        payload_hash = hashlib.sha256(cloudpickle.dumps((self.func, args, kwargs))).hexdigest()[:16]
+        archive_name = f"source-{self.tag.split(':')[1]}-{payload_hash}.tar.gz"
+
+        with tempfile.TemporaryDirectory() as tmpdir_str:
+            tmpdir = Path(tmpdir_str)
+            self._prepare_build_context(tmpdir, include_payload=True, args=args, kwargs=kwargs)
+            
+            archive_path = Path(tmpdir_str) / archive_name
+            with tarfile.open(archive_path, "w:gz") as tar:
+                # Add all files from the context to the tar archive
+                for f in tmpdir.glob("**/*"):
+                    if f.is_file():
+                        tar.add(f, arcname=f.relative_to(tmpdir))
+            
+            # 2. Prepare the request payload
+            port = kwargs.get('port', 8080)
+            data_payload = {
+                "function_name": self.name,
+                "port": port,
+                # "memory": "1Gi" # You could make this a parameter
+            }
+            headers = {
+                "X-API-Key": self.api_key
+            }
+
+            # 3. Upload to the deploy server
+            print("📦 Uploading build context to the deploy server...")
+            try:
+                with open(archive_path, 'rb') as f:
+                    files = {'source_archive': (archive_name, f, 'application/gzip')}
+                    
+                    response = requests.post(
+                        f"{self.base_url}/v1/deploy",
+                        data=data_payload,
+                        files=files,
+                        headers=headers,
+                        timeout=1800 # Set a long timeout for the entire process
+                    )
+
+                # 4. Handle the server's response
+                response.raise_for_status() # Raise an exception for 4xx/5xx errors
+                result = response.json()
+                
+                print(f"✅ Deployment successful!")
+                print(f"🔗 Service is available at: {result['url']}")
+                return result['url']
+
+            except requests.exceptions.HTTPError as e:
+                print(f"❌ Deployment failed. Server returned error: {e.response.status_code}")
+                try:
+                    # Try to print the detailed error message from the server
+                    print(f"   Reason: {e.response.json()['detail']}")
+                except:
+                    print(f"   Reason: {e.response.text}")
+                return None
+            except requests.exceptions.RequestException as e:
+                print(f"❌ Could not connect to the deploy server: {e}")
+                return None
+
+    def Deploy(self, *args, **kwargs):
+        try:
+            from .shared import upload_file_to_cloud, build_and_deploy_to_cloud
+        except ImportError:
+            print("❌ Shared not found. This is an internal method.")
+            return None
+
+        port = kwargs.get('port', 8080)
+        
+        with tempfile.TemporaryDirectory() as tmpdir_str:
+            tmpdir = Path(tmpdir_str)
+            self._prepare_build_context(tmpdir, include_payload=True, args=args, kwargs=kwargs)
+            
+            archive_path = Path(tmpdir_str) / "source.tar.gz"
+            with tarfile.open(archive_path, "w:gz") as tar:
+                for f in tmpdir.glob("**/*"):
+                    if f.is_file():
+                        tar.add(f, arcname=f.relative_to(tmpdir))
+
+            archive_name = upload_file_to_cloud(self.name, archive_path)
+
+        try:
+            service = build_and_deploy_to_cloud(
+            function_name=self.name,
+            gcs_object_name=archive_name,
+            port=port,
+            memory="1Gi"
+            )
+        except Exception as e:
+            print(f"❌ Cloud Deployment Failed: {e}")
+            return None

cycls/sdk.py

@@ -0,0 +1,22 @@
+from .runtime import Runtime
+
+def function(python_version="3.12", pip_install=None, apt_install=None, run_commands=None, copy=None, name=None, base_url=None, api_key=None):
+    # """
+    # A decorator factory that transforms a Python function into a containerized,
+    # remotely executable object.
+
+    # Args:
+    #     pip (list[str], optional): A list of pip packages to install.
+    #     apt (list[str], optional): A list of apt packages to install.
+    #     copy (list[str], optional): A list of local paths to copy to the
+    #         same path inside the image. For static dependencies.
+    #     name (str, optional): A name for this function. Defaults to the function's name.
+
+    # Returns:
+    #     A decorator that replaces the decorated function with a Runtime instance.
+    # """
+    def decorator(func):
+        Name = name or func.__name__ # should be moved to runtime... or default?
+        copy_dict = {i:i for i in copy or []}
+        return Runtime(func, Name.replace('_', '-'), python_version, pip_install, apt_install, run_commands, copy_dict, base_url, api_key)
+    return decorator

{cycls-0.0.2.31.dist-info → cycls-0.0.2.32.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cycls
-Version: 0.0.2.31
+Version: 0.0.2.32
 Summary: Cycls SDK
 Author: Mohammed J. AlRujayi
 Author-email: mj@cycls.com
@@ -12,6 +12,8 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: cloudpickle (>=3.1.1,<4.0.0)
+Requires-Dist: docker (>=7.1.0,<8.0.0)
 Requires-Dist: fastapi (>=0.111.0,<0.112.0)
 Requires-Dist: httpx (>=0.27.0,<0.28.0)
 Requires-Dist: jwt (>=1.4.0,<2.0.0)

cycls-0.0.2.32.dist-info/RECORD

@@ -0,0 +1,9 @@
+cycls/__init__.py,sha256=9oKTafASGMuJbq_Sk0sfCSQKKwUD8mcdYFovDDzVuW4,50
+cycls/cycls.py,sha256=rLhssEPs4EwDbNsO5cGdKkP888dOaYToMPKVLZWan5U,7479
+cycls/runtime.py,sha256=quBV8G8DkqsK_QzTraiYe7P9x9W5X1Zl8XDsvhUlPus,15939
+cycls/sdk.py,sha256=EcUYi0pGKtCajKzwLg3uH8CRPfc78KBHXgB6ShABxdE,1110
+cycls/theme/assets/index-D0-uI8sw.js,sha256=aUsqm9HZtEJz38o-0MW12ZVeOlSeKigwc_fYJBntiyI,1068551
+cycls/theme/index.html,sha256=epB4cgSjC7xJOXpVuCwt9r7ivoGvLiXSrxsoOgINw58,895
+cycls-0.0.2.32.dist-info/METADATA,sha256=si7x9VRhZUM9ZlrBN3Iusp6iemuHyWoOK-UT6WIZrmA,5666
+cycls-0.0.2.32.dist-info/WHEEL,sha256=zp0Cn7JsFoX2ATtOhtaFYIiE2rmFAD4OcMhtUki8W3U,88
+cycls-0.0.2.32.dist-info/RECORD,,

cycls-0.0.2.31.dist-info/RECORD

@@ -1,7 +0,0 @@
-cycls/__init__.py,sha256=D808D5xNP8OdQStdABmWqjGfuDNpVgbJhRo0KRKzo7g,24
-cycls/cycls.py,sha256=qW0KzZ7GLMIJ5tLPYDusvBv0HjKJ1NhfuYVu4BbF8Z4,7434
-cycls/theme/assets/index-D0-uI8sw.js,sha256=aUsqm9HZtEJz38o-0MW12ZVeOlSeKigwc_fYJBntiyI,1068551
-cycls/theme/index.html,sha256=epB4cgSjC7xJOXpVuCwt9r7ivoGvLiXSrxsoOgINw58,895
-cycls-0.0.2.31.dist-info/METADATA,sha256=0ldNTvnYxncmbitmY5oRGIGB1f8abh4uefgp9uEFl3s,5583
-cycls-0.0.2.31.dist-info/WHEEL,sha256=zp0Cn7JsFoX2ATtOhtaFYIiE2rmFAD4OcMhtUki8W3U,88
-cycls-0.0.2.31.dist-info/RECORD,,