cycls 0.0.2.30__tar.gz → 0.0.2.32__tar.gz

cycls-0.0.2.32/PKG-INFO

@@ -0,0 +1,148 @@
+Metadata-Version: 2.4
+Name: cycls
+Version: 0.0.2.32
+Summary: Cycls SDK
+Author: Mohammed J. AlRujayi
+Author-email: mj@cycls.com
+Requires-Python: >=3.9,<4.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+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)
+Requires-Dist: modal (>=1.1.0,<2.0.0)
+Description-Content-Type: text/markdown
+
+<h3 align="center">
+The Distribution SDK for AI Agents.
+</h3>
+
+<h4 align="center">
+  <a href="https://cycls.com">Website</a> |
+  <a href="https://docs.cycls.com">Docs</a>
+</h4>
+
+<h4 align="center">
+  <a href="https://pypi.python.org/pypi/cycls"><img src="https://img.shields.io/pypi/v/cycls.svg?label=cycls+pypi&color=blueviolet" alt="cycls Python package on PyPi" /></a>
+  <a href="https://blog.cycls.com"><img src="https://img.shields.io/badge/newsletter-blueviolet.svg?logo=substack&label=cycls" alt="Cycls newsletter" /></a>
+  <a href="https://x.com/cyclsai">
+    <img src="https://img.shields.io/twitter/follow/CyclsAI" alt="Cycls Twitter" />
+  </a>
+</h4>
+
+
+# Cycls 🚲
+
+`cycls` is a zero-config framework for building and publishing AI agents. With a single decorator and one command, you can deploy your code as a web application complete with a front-end UI and an OpenAI-compatible API endpoint.
+
+### Design Philosophy
+`cycls` is an anti-framework. We treat the boilerplate, config files, and infrastructure that surround modern applications as a bug to be eliminated. A developer's focus is the most valuable resource, and context-switching is its greatest enemy.
+
+Our zero-config approach makes your Python script the single source of truth for the entire application. When your code is all you need, you stay focused, iterate faster, and ship with confidence.
+
+This philosophy has a powerful side-effect: it makes development genuinely iterative. The self-contained nature of an agent encourages you to 'build in cycles'—starting simple and adding complexity without penalty. This same simplicity also makes `cycls` an ideal target for code generation. Because the entire application can be expressed in one file, LLMs can write, modify, and reason about `cycls` agents far more effectively than with traditional frameworks. It's a seamless interface for both human and machine.
+
+
+## Key Features
+
+* ✨ **Zero-Config Deployment:** No YAML or Dockerfiles. `cycls` infers your dependencies, and APIs directly from your Python code.
+* 🚀 **One-Command Push to Cloud:** Go from local code to a globally scalable, serverless application with a single `agent.push()`.
+* 💻 **Instant Local Testing:** Run `agent.run()` to spin up a local server with hot-reloading for rapid iteration and debugging.
+* 🤖 **OpenAI-Compatible API:** Automatically serves a streaming `/chat/completions` endpoint.
+* 🌐 **Automatic Web UI:** Get a clean, interactive front-end for your agent out of the box, with no front-end code required.
+* 🔐 **Built-in Authentication:** Secure your agent for production with a simple `auth=True` flag that enables JWT-based authentication.
+* 📦 **Declarative Dependencies:** Define all your `pip`, `apt`, or local file dependencies directly in Python.
+
+
+## Installation
+
+```bash
+pip install cycls
+```
+
+## How to Use
+### 1. Local Development: "Hello, World!"
+
+Create a file main.py. This simple example creates an agent that streams back the message "hi".
+
+```py
+import cycls
+
+# Initialize the agent
+agent = cycls.Agent()
+
+# Decorate your function to register it as an agent
+@agent()
+async def hello(context):
+    yield "hi"
+
+agent.run()
+```
+
+Run it from your terminal:
+
+```bash
+python main.py
+```
+This will start a local server. Open your browser to http://127.0.0.1:8000 to interact with your agent.
+
+### 2. Cloud Deployment: An OpenAI-Powered Agent
+This example creates a more advanced agent that calls the OpenAI API. It will be deployed to the cloud with authentication enabled.
+
+```py
+# deploy.py
+import cycls
+
+# Initialize the agent with dependencies and API keys
+agent = cycls.Agent(
+    pip=["openai"],
+    keys=["ak-<token_id>", "as-<token_secret>"]
+)
+
+# A helper function to call the LLM
+async def llm(messages):
+    # Import inside the function: 'openai' is only needed at runtime in the container.
+    import openai
+    client = openai.AsyncOpenAI(api_key="sk-...") # Your OpenAI key
+    model = "gpt-4o"
+    response = await client.chat.completions.create(
+        model=model,
+        messages=messages,
+        temperature=1.0,
+        stream=True
+    )
+    # Yield the content from the streaming response
+    async def event_stream():
+        async for chunk in response:
+            content = chunk.choices[0].delta.content
+            if content:
+                yield content
+    return event_stream()
+
+# Register the function as an agent named "cake" and enable auth
+@agent("cake", auth=True)
+async def cake_agent(context):
+    # The context object contains the message history
+    return await llm(context.messages)
+
+# Deploy the agent to the cloud
+agent.push(prod=True)
+```
+
+Run the deployment command from your terminal:
+
+```bash
+python main.py
+```
+After a few moments, your agent will be live and accessible at a public URL like https://cake.cycls.ai.
+
+### License
+This project is licensed under the MIT License.
+

cycls-0.0.2.32/README.md

@@ -0,0 +1,125 @@
+<h3 align="center">
+The Distribution SDK for AI Agents.
+</h3>
+
+<h4 align="center">
+  <a href="https://cycls.com">Website</a> |
+  <a href="https://docs.cycls.com">Docs</a>
+</h4>
+
+<h4 align="center">
+  <a href="https://pypi.python.org/pypi/cycls"><img src="https://img.shields.io/pypi/v/cycls.svg?label=cycls+pypi&color=blueviolet" alt="cycls Python package on PyPi" /></a>
+  <a href="https://blog.cycls.com"><img src="https://img.shields.io/badge/newsletter-blueviolet.svg?logo=substack&label=cycls" alt="Cycls newsletter" /></a>
+  <a href="https://x.com/cyclsai">
+    <img src="https://img.shields.io/twitter/follow/CyclsAI" alt="Cycls Twitter" />
+  </a>
+</h4>
+
+
+# Cycls 🚲
+
+`cycls` is a zero-config framework for building and publishing AI agents. With a single decorator and one command, you can deploy your code as a web application complete with a front-end UI and an OpenAI-compatible API endpoint.
+
+### Design Philosophy
+`cycls` is an anti-framework. We treat the boilerplate, config files, and infrastructure that surround modern applications as a bug to be eliminated. A developer's focus is the most valuable resource, and context-switching is its greatest enemy.
+
+Our zero-config approach makes your Python script the single source of truth for the entire application. When your code is all you need, you stay focused, iterate faster, and ship with confidence.
+
+This philosophy has a powerful side-effect: it makes development genuinely iterative. The self-contained nature of an agent encourages you to 'build in cycles'—starting simple and adding complexity without penalty. This same simplicity also makes `cycls` an ideal target for code generation. Because the entire application can be expressed in one file, LLMs can write, modify, and reason about `cycls` agents far more effectively than with traditional frameworks. It's a seamless interface for both human and machine.
+
+
+## Key Features
+
+* ✨ **Zero-Config Deployment:** No YAML or Dockerfiles. `cycls` infers your dependencies, and APIs directly from your Python code.
+* 🚀 **One-Command Push to Cloud:** Go from local code to a globally scalable, serverless application with a single `agent.push()`.
+* 💻 **Instant Local Testing:** Run `agent.run()` to spin up a local server with hot-reloading for rapid iteration and debugging.
+* 🤖 **OpenAI-Compatible API:** Automatically serves a streaming `/chat/completions` endpoint.
+* 🌐 **Automatic Web UI:** Get a clean, interactive front-end for your agent out of the box, with no front-end code required.
+* 🔐 **Built-in Authentication:** Secure your agent for production with a simple `auth=True` flag that enables JWT-based authentication.
+* 📦 **Declarative Dependencies:** Define all your `pip`, `apt`, or local file dependencies directly in Python.
+
+
+## Installation
+
+```bash
+pip install cycls
+```
+
+## How to Use
+### 1. Local Development: "Hello, World!"
+
+Create a file main.py. This simple example creates an agent that streams back the message "hi".
+
+```py
+import cycls
+
+# Initialize the agent
+agent = cycls.Agent()
+
+# Decorate your function to register it as an agent
+@agent()
+async def hello(context):
+    yield "hi"
+
+agent.run()
+```
+
+Run it from your terminal:
+
+```bash
+python main.py
+```
+This will start a local server. Open your browser to http://127.0.0.1:8000 to interact with your agent.
+
+### 2. Cloud Deployment: An OpenAI-Powered Agent
+This example creates a more advanced agent that calls the OpenAI API. It will be deployed to the cloud with authentication enabled.
+
+```py
+# deploy.py
+import cycls
+
+# Initialize the agent with dependencies and API keys
+agent = cycls.Agent(
+    pip=["openai"],
+    keys=["ak-<token_id>", "as-<token_secret>"]
+)
+
+# A helper function to call the LLM
+async def llm(messages):
+    # Import inside the function: 'openai' is only needed at runtime in the container.
+    import openai
+    client = openai.AsyncOpenAI(api_key="sk-...") # Your OpenAI key
+    model = "gpt-4o"
+    response = await client.chat.completions.create(
+        model=model,
+        messages=messages,
+        temperature=1.0,
+        stream=True
+    )
+    # Yield the content from the streaming response
+    async def event_stream():
+        async for chunk in response:
+            content = chunk.choices[0].delta.content
+            if content:
+                yield content
+    return event_stream()
+
+# Register the function as an agent named "cake" and enable auth
+@agent("cake", auth=True)
+async def cake_agent(context):
+    # The context object contains the message history
+    return await llm(context.messages)
+
+# Deploy the agent to the cloud
+agent.push(prod=True)
+```
+
+Run the deployment command from your terminal:
+
+```bash
+python main.py
+```
+After a few moments, your agent will be live and accessible at a public URL like https://cake.cycls.ai.
+
+### License
+This project is licensed under the MIT License.

cycls-0.0.2.32/cycls/__init__.py

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

{cycls-0.0.2.30 → cycls-0.0.2.32}/cycls/cycls.py

@@ -100,25 +100,18 @@ def web(func, front_end_path="", prod=False, org=None, api_token=None, header=""
     return app
 
 class Agent:
-    def __init__(self, front_end=theme_path, organization=None, api_token=None, pip=[], apt=[], copy=[], production=False, keys=["",""]):
-        self.prod, self.org, self.api_token = production, organization, api_token
-        self.front_end = front_end
+    def __init__(self, theme=theme_path, org=None, api_token=None, pip=[], apt=[], copy=[], keys=["",""]):
+        self.org, self.api_token = org, api_token
+        self.theme = theme
+        self.keys, self.pip, self.apt, self.copy = keys, pip, apt, copy
+
         self.registered_functions = []
-        self.client = modal.Client.from_credentials(*keys)
-        image = (modal.Image.debian_slim()
-                            .pip_install("fastapi[standard]", "pyjwt", "cryptography", *pip)
-                            .apt_install(*apt)
-                            .add_local_dir(front_end, "/root/public")
-                            .add_local_python_source("cycls"))        
-        for item in copy:
-            image = image.add_local_file(item, f"/root/{item}") if "." in item else image.add_local_dir(item, f'/root/{item}')
-        self.app = modal.App("development", image=image)
 
     def __call__(self, name="", header="", intro="", domain=None, auth=False):
         def decorator(f):
             self.registered_functions.append({
                 "func": f,
-                "config": ["public", self.prod, self.org, self.api_token, header, intro, auth],
+                "config": ["public", False, self.org, self.api_token, header, intro, auth],
                 "name": name,
                 "domain": domain or f"{name}.cycls.ai",
             })
@@ -127,26 +120,39 @@ class Agent:
 
     def run(self, port=8000):
         if not self.registered_functions:
-            return print("Error: No @agent decorated function found.")
+            print("Error: No @agent decorated function found.")
+            return
         
         i = self.registered_functions[0]
         if len(self.registered_functions) > 1:
             print(f"⚠️  Warning: Multiple agents found. Running '{i['name']}'.")
-        print(f"🚀 Starting local server at http://127.0.0.1:{port}")
-        i["config"][0] = self.front_end
-        uvicorn.run(web(i["func"], *i["config"]), host="127.0.0.1", port=port)
+        print(f"🚀 Starting local server at localhost:{port}")
+        i["config"][0], i["config"][6] = self.theme, False
+        uvicorn.run(web(i["func"], *i["config"]), host="0.0.0.0", port=port)
         return
 
-    def push(self): # local / prod?
+    def push(self, prod=False):
+        self.client = modal.Client.from_credentials(*self.keys)
+        image = (modal.Image.debian_slim()
+                            .pip_install("fastapi[standard]", "pyjwt", "cryptography", *self.pip)
+                            .apt_install(*self.apt)
+                            .add_local_dir(self.theme, "/root/public")
+                            .add_local_python_source("cycls"))        
+        for item in self.copy:
+            image = image.add_local_file(item, f"/root/{item}") if "." in item else image.add_local_dir(item, f'/root/{item}')
+        self.app = modal.App("development", image=image)
+    
         if not self.registered_functions:
-            return print("Error: No @agent decorated function found.")
+            print("Error: No @agent decorated function found.")
+            return
 
         for i in self.registered_functions:
+            i["config"][1] = True if prod else False
             self.app.function(serialized=True, name=i["name"])(
                 modal.asgi_app(label=i["name"], custom_domains=[i["domain"]])
                 (lambda: web(i["func"], *i["config"]))
             )
-        if self.prod:
+        if prod:
             for i in self.registered_functions:
                 print(f"✅ Deployed to ⇒ https://{i['domain']}")
             self.app.deploy(client=self.client, name=self.registered_functions[0]["name"])
@@ -158,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-0.0.2.32/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-0.0.2.32/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.30 → cycls-0.0.2.32}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "cycls"
-version = "0.0.2.30"
+version = "0.0.2.32"
 
 packages = [{ include = "cycls" }]
 include = ["cycls/theme/**/*"]
@@ -14,6 +14,8 @@ fastapi = "^0.111.0"
 httpx = "^0.27.0"
 modal = "^1.1.0"
 jwt = "^1.4.0"
+docker = "^7.1.0"
+cloudpickle = "^3.1.1"
 
 
 [build-system]

cycls-0.0.2.30/PKG-INFO

@@ -1,103 +0,0 @@
-Metadata-Version: 2.3
-Name: cycls
-Version: 0.0.2.30
-Summary: Cycls SDK
-Author: Mohammed J. AlRujayi
-Author-email: mj@cycls.com
-Requires-Python: >=3.9,<4.0
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.9
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-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)
-Requires-Dist: modal (>=1.1.0,<2.0.0)
-Description-Content-Type: text/markdown
-
-<p align="center">
-  <img src="https://github.com/user-attachments/assets/96bd304d-8116-4bce-8b8f-b08980875ad7" width="800px" alt="Cycls Banner">
-</p>
-
-<h3 align="center">
-Generate live apps from code in minutes with built-in memory, <br/>rich hypermedia content, and cross-platform support
-</h3>
-
-<h4 align="center">
-  <a href="https://cycls.com">Website</a> |
-  <a href="https://docs.cycls.com">Docs</a> |
-  <a href="https://docs.cycls.com">Blog</a>
-</h4>
-
-<h4 align="center">
-  <a href="https://pypi.python.org/pypi/cycls"><img src="https://img.shields.io/pypi/v/cycls.svg?label=cycls+pypi&color=blueviolet" alt="cycls Python package on PyPi" /></a>
-  <a href="https://blog.cycls.com"><img src="https://img.shields.io/badge/newsletter-blueviolet.svg?logo=substack&label=cycls" alt="Cycls newsletter" /></a>
-  <a href="https://x.com/cycls_">
-    <img src="https://img.shields.io/twitter/follow/cycls_" alt="Cycls Twitter" />
-  </a>
-</h4>
-
-
-## Cycls: The AI App Generator
-Cycls[^1] streamlines AI application development by generating apps from high-level descriptions. It eliminates boilerplate, ensures cross-platform compatibility, and manages memory - all from a single codebase.
-
-With Cycls, you can quickly prototype ideas and then turn them into production apps, while focusing on AI logic and user interactions rather than wrestling with implementation details.
-
-## ✨ Core Features
-- **Fast App Generation**: Create live web apps from code in minutes
-- **Built-in Memory Management**: Integrated state and session management
-- **Rich Hypermedia Content**: Support for various media types (text, images, audio, video, interactive elements)
-- **Framework Agnostic**: Compatible with a wide range of AI frameworks and models
-
-## 🚀 Quickstart
-### Installation
-```
-pip install cycls
-```
-
-### Basic usage
-```py
-from cycls import Cycls
-
-cycls = Cycls()
-
-@cycls("@my-app")
-def app():
-    return "Hello World!"
-
-cycls.push()
-```
-This creates an app named "@my-app" that responds with "Hello World!".
-
-The `@cycls("@my-app")` decorator registers your app, and `cycls.push()` streams it to Cycls platform.
-
-To see a live example, visit https://cycls.com/@spark.
-
-> [!IMPORTANT]
-> Use a unique name for your app (like "@my-app"). This is your app's identifier on Cycls.
-
-> [!NOTE]
-> Your apps run on your infrastructure and are streamed in real-time to Cycls.
-
-## 📖 Documentation
-For more detailes and instructions, visit our documentation at [docs.cycls.com](https://docs.cycls.com/).
-
-## 🗺️ Roadmap
-- **iOS and Android apps**
-- **User management**
-- **JavaScript SDK**
-- **Public API**
-- **Cross-app communication**
-
-## 🙌 Support 
-Join our Discord community for support and discussions. You can reach us on:
-
-- [Join our Discord](https://discord.gg/XbxcTFBf7J)
-- [Join our newsletter](https://blog.cycls.com)
-- [Follow us on Twitter](https://x.com/cycls_)
-- [Email us](mailto:hi@cycls.com)
-
-[^1]: The name "Cycls" is a play on "cycles," referring to the continuous exchange between AI prompts (generators) and their responses (generated).
-

cycls-0.0.2.30/README.md

@@ -1,83 +0,0 @@
-<p align="center">
-  <img src="https://github.com/user-attachments/assets/96bd304d-8116-4bce-8b8f-b08980875ad7" width="800px" alt="Cycls Banner">
-</p>
-
-<h3 align="center">
-Generate live apps from code in minutes with built-in memory, <br/>rich hypermedia content, and cross-platform support
-</h3>
-
-<h4 align="center">
-  <a href="https://cycls.com">Website</a> |
-  <a href="https://docs.cycls.com">Docs</a> |
-  <a href="https://docs.cycls.com">Blog</a>
-</h4>
-
-<h4 align="center">
-  <a href="https://pypi.python.org/pypi/cycls"><img src="https://img.shields.io/pypi/v/cycls.svg?label=cycls+pypi&color=blueviolet" alt="cycls Python package on PyPi" /></a>
-  <a href="https://blog.cycls.com"><img src="https://img.shields.io/badge/newsletter-blueviolet.svg?logo=substack&label=cycls" alt="Cycls newsletter" /></a>
-  <a href="https://x.com/cycls_">
-    <img src="https://img.shields.io/twitter/follow/cycls_" alt="Cycls Twitter" />
-  </a>
-</h4>
-
-
-## Cycls: The AI App Generator
-Cycls[^1] streamlines AI application development by generating apps from high-level descriptions. It eliminates boilerplate, ensures cross-platform compatibility, and manages memory - all from a single codebase.
-
-With Cycls, you can quickly prototype ideas and then turn them into production apps, while focusing on AI logic and user interactions rather than wrestling with implementation details.
-
-## ✨ Core Features
-- **Fast App Generation**: Create live web apps from code in minutes
-- **Built-in Memory Management**: Integrated state and session management
-- **Rich Hypermedia Content**: Support for various media types (text, images, audio, video, interactive elements)
-- **Framework Agnostic**: Compatible with a wide range of AI frameworks and models
-
-## 🚀 Quickstart
-### Installation
-```
-pip install cycls
-```
-
-### Basic usage
-```py
-from cycls import Cycls
-
-cycls = Cycls()
-
-@cycls("@my-app")
-def app():
-    return "Hello World!"
-
-cycls.push()
-```
-This creates an app named "@my-app" that responds with "Hello World!".
-
-The `@cycls("@my-app")` decorator registers your app, and `cycls.push()` streams it to Cycls platform.
-
-To see a live example, visit https://cycls.com/@spark.
-
-> [!IMPORTANT]
-> Use a unique name for your app (like "@my-app"). This is your app's identifier on Cycls.
-
-> [!NOTE]
-> Your apps run on your infrastructure and are streamed in real-time to Cycls.
-
-## 📖 Documentation
-For more detailes and instructions, visit our documentation at [docs.cycls.com](https://docs.cycls.com/).
-
-## 🗺️ Roadmap
-- **iOS and Android apps**
-- **User management**
-- **JavaScript SDK**
-- **Public API**
-- **Cross-app communication**
-
-## 🙌 Support 
-Join our Discord community for support and discussions. You can reach us on:
-
-- [Join our Discord](https://discord.gg/XbxcTFBf7J)
-- [Join our newsletter](https://blog.cycls.com)
-- [Follow us on Twitter](https://x.com/cycls_)
-- [Email us](mailto:hi@cycls.com)
-
-[^1]: The name "Cycls" is a play on "cycles," referring to the continuous exchange between AI prompts (generators) and their responses (generated).

cycls-0.0.2.30/cycls/__init__.py

@@ -1 +0,0 @@
-from .cycls import Agent