cycls 0.0.2.93__py3-none-any.whl

cycls/__init__.py

@@ -0,0 +1,14 @@
+from . import function as _function_module
+from .function import function, Function
+from .app import app, App
+
+def __getattr__(name):
+    if name in ("api_key", "base_url"):
+        return getattr(_function_module, name)
+    raise AttributeError(f"module 'cycls' has no attribute '{name}'")
+
+def __setattr__(name, value):
+    if name in ("api_key", "base_url"):
+        setattr(_function_module, name, value)
+    else:
+        raise AttributeError(f"module 'cycls' has no attribute '{name}'")

cycls/app.py

@@ -0,0 +1,91 @@
+import os
+import uvicorn
+import importlib.resources
+
+from .function import Function, _get_api_key, _get_base_url
+from .web import web, Config
+
+CYCLS_PATH = importlib.resources.files('cycls')
+
+THEMES = ["default", "dev"]
+
+
+class App(Function):
+    """App extends Function with web UI serving capabilities."""
+
+    def __init__(self, func, name, theme="default", pip=None, apt=None, copy=None, copy_public=None,
+                 auth=False, org=None, header=None, intro=None, title=None, plan="free", analytics=False,
+                 state=False):
+        if theme not in THEMES:
+            raise ValueError(f"Unknown theme: {theme}. Available: {THEMES}")
+        self.user_func = func
+        self.theme = theme
+        self.copy_public = copy_public or []
+        self.state = state
+
+        self.config = Config(
+            header=header,
+            intro=intro,
+            title=title,
+            auth=auth,
+            plan=plan,
+            analytics=analytics,
+            org=org,
+            state=state,
+        )
+
+        # Build files dict for Function (theme is inside cycls/)
+        files = {str(CYCLS_PATH): "cycls"}
+        files.update({f: f for f in copy or []})
+        files.update({f: f"public/{f}" for f in self.copy_public})
+
+        super().__init__(
+            func=func,
+            name=name,
+            pip=["fastapi[standard]", "pyjwt", "cryptography", "uvicorn", "python-dotenv", "docker", "agentfs-sdk", "pyturso==0.4.0rc17", *(pip or [])],
+            apt=apt,
+            copy=files,
+            base_url=_get_base_url(),
+            api_key=_get_api_key()
+        )
+
+    def __call__(self, *args, **kwargs):
+        return self.user_func(*args, **kwargs)
+
+    def _prepare_func(self, prod):
+        self.config.set_prod(prod)
+        self.config.public_path = f"cycls/themes/{self.theme}"
+        user_func, config, name = self.user_func, self.config, self.name
+        self.func = lambda port: __import__("cycls").web.serve(user_func, config, name, port)
+
+    def _local(self, port=8080):
+        """Run directly with uvicorn (no Docker)."""
+        print(f"Starting local server at localhost:{port}")
+        self.config.public_path = str(CYCLS_PATH.joinpath(f"themes/{self.theme}"))
+        self.config.set_prod(False)
+        uvicorn.run(web(self.user_func, self.config), host="0.0.0.0", port=port)
+
+    def local(self, port=8080, watch=True):
+        """Run locally in Docker with file watching by default."""
+        if os.environ.get('_CYCLS_WATCH'):
+            watch = False
+        self._prepare_func(prod=False)
+        self.watch(port=port) if watch else self.run(port=port)
+
+    def deploy(self, port=8080):
+        """Deploy to production."""
+        if self.api_key is None:
+            raise RuntimeError("Missing API key. Set cycls.api_key or CYCLS_API_KEY environment variable.")
+        self._prepare_func(prod=True)
+        return super().deploy(port=port)
+
+
+def app(name=None, **kwargs):
+    """Decorator that transforms a function into a deployable App."""
+    if kwargs.get("plan") == "cycls_pass":
+        kwargs["auth"] = True
+        kwargs["analytics"] = True
+
+    def decorator(func):
+        return App(func=func, name=name or func.__name__, **kwargs)
+    return decorator

cycls/auth.py

@@ -0,0 +1,4 @@
+JWKS_PROD = "https://clerk.cycls.ai/.well-known/jwks.json"
+JWKS_TEST = "https://select-sloth-58.clerk.accounts.dev/.well-known/jwks.json"
+PK_LIVE = "pk_live_Y2xlcmsuY3ljbHMuYWkk"
+PK_TEST = "pk_test_c2VsZWN0LXNsb3RoLTU4LmNsZXJrLmFjY291bnRzLmRldiQ"

cycls/cli.py

@@ -0,0 +1,104 @@
+#!/usr/bin/env python3
+"""cycls chat - Claude Code style CLI for cycls agents"""
+
+import json, os, re, sys
+import httpx
+
+RESET, BOLD, DIM = "\033[0m", "\033[1m", "\033[2m"
+BLUE, GREEN, YELLOW, RED = "\033[34m", "\033[32m", "\033[33m", "\033[31m"
+CALLOUTS = {"success": ("✓", GREEN), "warning": ("⚠", YELLOW), "info": ("ℹ", BLUE), "error": ("✗", RED)}
+
+separator = lambda: f"{DIM}{'─' * min(os.get_terminal_size().columns if sys.stdout.isatty() else 80, 80)}{RESET}"
+markdown = lambda text: re.sub(r"\*\*(.+?)\*\*", f"{BOLD}\\1{RESET}", text)
+header = lambda title, meta, color=GREEN, dim=False: print(f"{color}●{RESET} {BOLD}{title}{RESET}\n  ⎿  {meta}{DIM if dim else ''}", flush=True)
+
+
+def table(headers, rows):
+    if not headers: return
+    widths = [max(len(str(h)), *(len(str(r[i])) for r in rows if i < len(r))) for i, h in enumerate(headers)]
+    line = lambda left, mid, right: left + mid.join("─" * (w + 2) for w in widths) + right
+    row = lambda cells, bold=False: "│" + "│".join(f" {BOLD if bold else ''}{str(cells[i] if i < len(cells) else '').ljust(widths[i])}{RESET if bold else ''} " for i in range(len(widths))) + "│"
+    print(f"{line('┌', '┬', '┐')}\n{row(headers, True)}\n{line('├', '┼', '┤')}")
+    for r in rows: print(row(r))
+    print(line("└", "┴", "┘"))
+
+
+def chat(url):
+    messages, endpoint = [], f"{url.rstrip('/')}/chat/cycls"
+    print(f"\n{BOLD}cycls{RESET} {DIM}|{RESET} {url}\n")
+
+    while True:
+        try:
+            print(separator())
+            user_input = input(f"{BOLD}{BLUE}❯{RESET} ").strip()
+            print(separator())
+
+            if not user_input: continue
+            if user_input in ("/q", "exit", "quit"): break
+            if user_input == "/c": messages, _ = [], print(f"{GREEN}⏺ Cleared{RESET}"); continue
+
+            messages.append({"role": "user", "content": user_input})
+            block, tbl = None, ([], [])
+
+            def close():
+                nonlocal block, tbl
+                if block == "thinking": print(RESET)
+                if block == "text": print()
+                if block == "table" and tbl[0]: table(*tbl); tbl = ([], [])
+                if block: print()
+                block = None
+
+            with httpx.stream("POST", endpoint, json={"messages": messages}, timeout=None) as response:
+                for line in response.iter_lines():
+                    if not line.startswith("data: ") or line == "data: [DONE]": continue
+                    data = json.loads(line[6:])
+                    type = data.get("type")
+
+                    if type is None:
+                        print(markdown(data if isinstance(data, str) else data.get("text", "")), end="", flush=True); continue
+
+                    if type != block: close()
+
+                    if type in ("thinking", "text"):
+                        if block != type: header(type.capitalize(), "Live", dim=(type == "thinking")); block = type
+                        print((markdown if type == "text" else str)(data.get(type, "")), end="", flush=True)
+                    elif type == "code":
+                        code = data.get("code", ""); header(f"Code({data.get('language', '')})", f"{code.count(chr(10))+1} lines"); print(code, flush=True); block = type
+                    elif type == "status":
+                        print(f"{DIM}[{data.get('status', '')}]{RESET} ", end="", flush=True)
+                    elif type == "table":
+                        if "headers" in data:
+                            if tbl[0]: table(*tbl)
+                            header("Table", f"{len(data['headers'])} cols"); tbl, block = (data["headers"], []), type
+                        elif "row" in data: tbl[1].append(data["row"])
+                    elif type == "callout":
+                        style = data.get("style", "info"); icon, color = CALLOUTS.get(style, ("•", RESET))
+                        header(style.capitalize(), f"{icon} {data.get('callout', '')}", color=color); block = type
+                    elif type == "image":
+                        header("Image", data.get("src", "")); block = type
+
+            close()
+
+        except KeyboardInterrupt: print()
+        except EOFError: break
+        except (httpx.ReadError, httpx.ConnectError) as e: print(f"{RED}⏺ Connection error: {e}{RESET}"); messages and messages.pop()
+
+
+def main():
+    if len(sys.argv) < 3:
+        print("Usage: cycls chat <url|port>")
+        sys.exit(1)
+    arg = sys.argv[2]
+    if arg.isdigit():
+        port = int(arg)
+        if not (1 <= port <= 65535):
+            print(f"Error: Invalid port {port}. Must be between 1 and 65535.")
+            sys.exit(1)
+        url = f"http://localhost:{port}"
+    else:
+        url = arg
+    chat(url)
+
+
+if __name__ == "__main__":
+    main()

cycls/function.py

@@ -0,0 +1,407 @@
+import contextlib
+import docker
+import cloudpickle
+import tempfile
+import hashlib
+import json
+import os
+import sys
+import shutil
+from pathlib import Path
+import tarfile
+
+os.environ["DOCKER_BUILDKIT"] = "1"
+
+ENTRYPOINT_PY = '''import sys
+sys.path.insert(0, '/app')
+import cloudpickle
+with open("/app/function.pkl", "rb") as f:
+    func, args, kwargs = cloudpickle.load(f)
+func(*args, **kwargs)
+'''
+
+RUNNER_PY = '''import sys
+sys.path.insert(0, '/app')
+import cloudpickle
+import traceback
+from pathlib import Path
+
+io_dir = Path(sys.argv[1])
+payload_path = io_dir / "payload.pkl"
+result_path = io_dir / "result.pkl"
+
+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:
+    traceback.print_exc()
+    sys.exit(1)
+'''
+
+# Module-level configuration
+api_key = None
+base_url = None
+
+def _get_api_key():
+    return api_key or os.getenv("CYCLS_API_KEY")
+
+def _get_base_url():
+    return base_url or os.getenv("CYCLS_BASE_URL")
+
+def _hash_path(path_str: str) -> str:
+    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
+                h.update(str(filepath.relative_to(p)).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):
+    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)
+
+
+class Function:
+    """Executes functions in Docker containers."""
+
+    def __init__(self, func, name, python_version=None, pip=None, apt=None,
+                 run_commands=None, copy=None, base_url=None, api_key=None):
+        self.func = func
+        self.name = name.replace('_', '-')
+        self.python_version = python_version or f"{sys.version_info.major}.{sys.version_info.minor}"
+        self.base_image = f"python:{self.python_version}-slim"
+        self.apt = sorted(apt or [])
+        self.run_commands = sorted(run_commands or [])
+        self.copy = {f: f for f in copy} if isinstance(copy, list) else (copy or {})
+        self.base_url = base_url or "https://service-core-280879789566.me-central1.run.app"
+        self.api_key = api_key
+        self.pip = sorted(set(pip or []) | {"cloudpickle"})
+
+        self.image_prefix = f"cycls/{self.name}"
+        self.managed_label = "cycls.function"
+        self._docker_client = None
+        self._container = None
+
+    @property
+    def docker_client(self):
+        if self._docker_client is None:
+            try:
+                print("Initializing Docker client...")
+                client = docker.from_env()
+                client.ping()
+                self._docker_client = client
+            except docker.errors.DockerException:
+                print("\nError: Docker is not running or is not installed.")
+                print("Please start the Docker daemon and try again.")
+                sys.exit(1)
+        return self._docker_client
+
+    def _perform_auto_cleanup(self, keep_tag=None):
+        try:
+            current_id = self._container.id if self._container else None
+            for container in self.docker_client.containers.list(all=True, filters={"label": self.managed_label}):
+                if container.id != current_id:
+                    container.remove(force=True)
+
+            cleaned = 0
+            for image in self.docker_client.images.list(filters={"label": self.managed_label}):
+                is_deploy = any(":deploy-" in t for t in image.tags)
+                is_current = keep_tag and keep_tag in image.tags
+                if not is_deploy and not is_current:
+                    self.docker_client.images.remove(image.id, force=True)
+                    cleaned += 1
+            if cleaned:
+                print(f"Cleaned up {cleaned} old dev image(s).")
+        except Exception as e:
+            print(f"Warning: cleanup error: {e}")
+
+    def _image_tag(self, extra_parts=None) -> str:
+        parts = [self.base_image, self.python_version, "".join(self.pip),
+                 "".join(self.apt), "".join(self.run_commands)]
+        for src, dst in sorted(self.copy.items()):
+            if not Path(src).exists():
+                raise FileNotFoundError(f"Path in 'copy' not found: {src}")
+            parts.append(f"{src}>{dst}:{_hash_path(src)}")
+        if extra_parts:
+            parts.extend(extra_parts)
+        return f"{self.image_prefix}:{hashlib.sha256(''.join(parts).encode()).hexdigest()[:16]}"
+
+    def _dockerfile_preamble(self) -> str:
+        lines = [
+            f"FROM {self.base_image}",
+            "ENV PIP_ROOT_USER_ACTION=ignore PYTHONUNBUFFERED=1",
+            "WORKDIR /app",
+            "RUN pip install uv",
+        ]
+
+        if self.apt:
+            lines.append(f"RUN apt-get update && apt-get install -y --no-install-recommends {' '.join(self.apt)}")
+
+        if self.pip:
+            lines.append(f"RUN uv pip install --system --no-cache {' '.join(self.pip)}")
+
+        for cmd in self.run_commands:
+            lines.append(f"RUN {cmd}")
+
+        for dst in self.copy.values():
+            lines.append(f"COPY context_files/{dst} /app/{dst}")
+
+        return "\n".join(lines)
+
+    def _dockerfile_local(self) -> str:
+        return f"""{self._dockerfile_preamble()}
+COPY runner.py /runner.py
+ENTRYPOINT ["python", "/runner.py", "/io"]
+"""
+
+    def _dockerfile_deploy(self, port: int) -> str:
+        return f"""{self._dockerfile_preamble()}
+COPY function.pkl /app/function.pkl
+COPY entrypoint.py /app/entrypoint.py
+EXPOSE {port}
+CMD ["python", "entrypoint.py"]
+"""
+
+    def _copy_user_files(self, workdir: Path):
+        context_files_dir = workdir / "context_files"
+        context_files_dir.mkdir()
+        for src, dst in self.copy.items():
+            _copy_path(Path(src).resolve(), context_files_dir / dst)
+
+    def _build_image(self, tag: str, workdir: Path) -> str:
+        print("--- Docker Build Logs ---")
+        try:
+            for chunk in self.docker_client.api.build(
+                path=str(workdir), tag=tag, forcerm=True, decode=True,
+                labels={self.managed_label: "true"}
+            ):
+                if 'stream' in chunk:
+                    print(chunk['stream'].strip())
+            print("-------------------------")
+            print(f"Image built: {tag}")
+            return tag
+        except docker.errors.BuildError as e:
+            print(f"\nDocker build failed: {e}")
+            raise
+
+    def _ensure_local_image(self) -> str:
+        tag = self._image_tag(extra_parts=["local-v1"])
+        try:
+            self.docker_client.images.get(tag)
+            print(f"Found cached image: {tag}")
+            return tag
+        except docker.errors.ImageNotFound:
+            print(f"Building new image: {tag}")
+
+        with tempfile.TemporaryDirectory() as tmpdir:
+            workdir = Path(tmpdir)
+            self._copy_user_files(workdir)
+            (workdir / "Dockerfile").write_text(self._dockerfile_local())
+            (workdir / "runner.py").write_text(RUNNER_PY)
+            return self._build_image(tag, workdir)
+
+    def _cleanup_container(self):
+        if getattr(self, '_container', None):
+            try:
+                self._container.stop(timeout=3)
+                self._container.remove()
+            except docker.errors.NotFound:
+                pass
+            except docker.errors.APIError:
+                pass
+            self._container = None
+
+    @contextlib.contextmanager
+    def runner(self, *args, **kwargs):
+        service_port = kwargs.get('port')
+        tag = self._ensure_local_image()
+        self._perform_auto_cleanup(keep_tag=tag)
+
+        ports = {f'{service_port}/tcp': service_port} if service_port else None
+
+        with tempfile.TemporaryDirectory() as io_dir:
+            io_path = Path(io_dir)
+            payload_path = io_path / "payload.pkl"
+            result_path = io_path / "result.pkl"
+
+            with open(payload_path, 'wb') as f:
+                cloudpickle.dump((self.func, args, kwargs), f)
+
+            try:
+                self._container = self.docker_client.containers.create(
+                    image=tag,
+                    volumes={str(io_path): {'bind': '/io', 'mode': 'rw'}},
+                    ports=ports,
+                    labels={self.managed_label: "true"}
+                )
+                self._container.start()
+                yield self._container, result_path
+            finally:
+                self._cleanup_container()
+
+    def run(self, *args, **kwargs):
+        service_port = kwargs.get('port')
+        print(f"Running '{self.name}'...")
+
+        try:
+            with self.runner(*args, **kwargs) as (container, result_path):
+                print("--- Container Logs ---")
+                for chunk in container.logs(stream=True, follow=True):
+                    print(chunk.decode(), end='')
+                print("----------------------")
+
+                status = container.wait()
+                if status['StatusCode'] != 0:
+                    print(f"Error: Container exited with code {status['StatusCode']}")
+                    return None
+
+                if service_port:
+                    return None
+
+                if result_path.exists():
+                    with open(result_path, 'rb') as f:
+                        return cloudpickle.load(f)
+                else:
+                    print("Error: Result file not found")
+                    return None
+
+        except KeyboardInterrupt:
+            print("\n----------------------")
+            print("Stopping...")
+            return None
+        except Exception as e:
+            print(f"Error: {e}")
+            return None
+
+    def watch(self, *args, **kwargs):
+        if os.environ.get('_CYCLS_WATCH'):
+            return self.run(*args, **kwargs)
+
+        try:
+            from watchfiles import watch as watchfiles_watch
+        except ImportError:
+            print("watchfiles not installed. pip install watchfiles")
+            return self.run(*args, **kwargs)
+
+        import subprocess
+
+        script = Path(sys.argv[0]).resolve()
+        watch_paths = [script] + [Path(p).resolve() for p in self.copy if Path(p).exists()]
+
+        print(f"Watching: {[p.name for p in watch_paths]}\n")
+
+        while True:
+            proc = subprocess.Popen([sys.executable, str(script)], env={**os.environ, '_CYCLS_WATCH': '1'})
+            try:
+                for changes in watchfiles_watch(*watch_paths):
+                    print(f"\nChanged: {[Path(c[1]).name for c in changes]}")
+                    break
+                proc.terminate()
+                proc.wait(timeout=3)
+            except subprocess.TimeoutExpired:
+                proc.kill()
+            except KeyboardInterrupt:
+                proc.terminate()
+                proc.wait(timeout=3)
+                return
+
+    def _prepare_deploy_context(self, workdir: Path, port: int, args=(), kwargs=None):
+        kwargs = kwargs or {}
+        kwargs['port'] = port
+        self._copy_user_files(workdir)
+        (workdir / "Dockerfile").write_text(self._dockerfile_deploy(port))
+        (workdir / "entrypoint.py").write_text(ENTRYPOINT_PY)
+        with open(workdir / "function.pkl", "wb") as f:
+            cloudpickle.dump((self.func, args, kwargs), f)
+
+    def build(self, *args, **kwargs):
+        port = kwargs.pop('port', 8080)
+        payload = cloudpickle.dumps((self.func, args, {**kwargs, 'port': port}))
+        tag = f"{self.image_prefix}:deploy-{hashlib.sha256(payload).hexdigest()[:16]}"
+
+        try:
+            self.docker_client.images.get(tag)
+            print(f"Found cached image: {tag}")
+            return tag
+        except docker.errors.ImageNotFound:
+            print(f"Building: {tag}")
+
+        with tempfile.TemporaryDirectory() as tmpdir:
+            workdir = Path(tmpdir)
+            self._prepare_deploy_context(workdir, port, args, kwargs)
+            self._build_image(tag, workdir)
+            print(f"Run: docker run --rm -p {port}:{port} {tag}")
+            return tag
+
+    def deploy(self, *args, **kwargs):
+        import requests
+
+        port = kwargs.pop('port', 8080)
+        print(f"Deploying '{self.name}'...")
+
+        payload = cloudpickle.dumps((self.func, args, {**kwargs, 'port': port}))
+        archive_name = f"{self.name}-{hashlib.sha256(payload).hexdigest()[:16]}.tar.gz"
+
+        with tempfile.TemporaryDirectory() as tmpdir:
+            workdir = Path(tmpdir)
+            self._prepare_deploy_context(workdir, port, args, kwargs)
+
+            archive_path = workdir / archive_name
+            with tarfile.open(archive_path, "w:gz") as tar:
+                for f in workdir.glob("**/*"):
+                    if f.is_file() and f != archive_path:
+                        tar.add(f, arcname=f.relative_to(workdir))
+
+            print("Uploading build context...")
+            try:
+                with open(archive_path, 'rb') as f:
+                    response = requests.post(
+                        f"{self.base_url}/v1/deploy",
+                        data={"function_name": self.name, "port": port},
+                        files={'source_archive': (archive_name, f, 'application/gzip')},
+                        headers={"X-API-Key": self.api_key},
+                        timeout=9000
+                    )
+                response.raise_for_status()
+                result = response.json()
+                print(f"Deployed: {result['url']}")
+                return result['url']
+
+            except requests.exceptions.HTTPError as e:
+                print(f"Deploy failed: {e.response.status_code}")
+                try:
+                    print(f"  {e.response.json()['detail']}")
+                except (json.JSONDecodeError, KeyError):
+                    print(f"  {e.response.text}")
+                return None
+            except requests.exceptions.RequestException as e:
+                print(f"Connection error: {e}")
+                return None
+
+    def __del__(self):
+        self._cleanup_container()
+
+
+def function(name=None, **kwargs):
+    """Decorator that transforms a Python function into a containerized Function."""
+    def decorator(func):
+        return Function(func, name or func.__name__, **kwargs, base_url=_get_base_url(), api_key=_get_api_key())
+    return decorator

cycls/state.py

@@ -0,0 +1,6 @@
+from agentfs_sdk import AgentFS, AgentFSOptions
+
+
+async def create_state(user_id: str = "default"):
+    """Create state instance scoped to end-user."""
+    return await AgentFS.open(AgentFSOptions(id=user_id))