cycls 0.0.1.1__tar.gz → 0.0.2.81__tar.gz

cycls-0.0.2.81/PKG-INFO

@@ -0,0 +1,276 @@
+Metadata-Version: 2.4
+Name: cycls
+Version: 0.0.2.81
+Summary: Distribute Intelligence
+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
+Provides-Extra: modal
+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: grpcio (>=1.76.0,<2.0.0)
+Requires-Dist: httpx (>=0.27.0,<0.28.0)
+Requires-Dist: modal (>=1.1.0,<2.0.0) ; extra == "modal"
+Requires-Dist: protobuf (>=6.0,<7.0)
+Requires-Dist: pyjwt (>=2.8.0,<3.0.0)
+Description-Content-Type: text/markdown
+
+<h3 align="center">
+Distribute Intelligence
+</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://github.com/Cycls/cycls/actions/workflows/tests.yml"><img src="https://github.com/Cycls/cycls/actions/workflows/tests.yml/badge.svg" alt="Tests" /></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
+
+The open-source SDK for distributing AI agents.
+
+The function is the unit of abstraction in cycls. Your agent logic lives in a plain Python function — the decorator layers on everything else: containerization, authentication, deployment, analytics. You write the function, the `@` handles the infrastructure.
+
+## Distribute Intelligence
+
+Write a function. Deploy it as an API, a web interface, or both. Add authentication, analytics, and monetization with flags.
+
+```python
+import cycls
+
+cycls.api_key = "YOUR_CYCLS_API_KEY"
+
+@cycls.agent(pip=["openai"])
+async def agent(context):
+    from openai import AsyncOpenAI
+    client = AsyncOpenAI()
+
+    stream = await client.responses.create(
+        model="o3-mini",
+        input=context.messages,
+        stream=True,
+        reasoning={"effort": "medium", "summary": "auto"},
+    )
+
+    async for event in stream:
+        if event.type == "response.reasoning_summary_text.delta":
+            yield {"type": "thinking", "thinking": event.delta}  # Renders as thinking bubble
+        elif event.type == "response.output_text.delta":
+            yield event.delta
+
+agent.deploy()  # Live at https://agent.cycls.ai
+```
+
+## Installation
+
+```bash
+pip install cycls
+```
+
+Requires Docker.
+
+## What You Get
+
+- **Streaming API** - OpenAI-compatible `/chat/completions` endpoint
+- **Web Interface** - Chat UI served automatically
+- **Authentication** - `auth=True` enables JWT-based access control
+- **Analytics** - `analytics=True` tracks usage
+- **Monetization** - `plan="cycls_pass"` integrates with [Cycls Pass](https://cycls.ai) subscriptions
+- **Native UI Components** - Render thinking bubbles, tables, code blocks in responses
+
+## Running
+
+```python
+agent.local()             # Development with hot-reload (localhost:8080)
+agent.local(watch=False)  # Development without hot-reload
+agent.deploy()            # Production: https://agent.cycls.ai
+```
+
+Get an API key at [cycls.com](https://cycls.com).
+
+## Authentication & Analytics
+
+```python
+@cycls.agent(pip=["openai"], auth=True, analytics=True)
+async def agent(context):
+    # context.user available when auth=True
+    user = context.user  # User(id, email, name, plans)
+    yield f"Hello {user.name}!"
+```
+
+| Flag | Description |
+|------|-------------|
+| `auth=True` | Universal user pool via Cycls Pass (Clerk-based). You can also use your own Clerk auth. |
+| `analytics=True` | Rich usage metrics available on the Cycls dashboard. |
+| `plan="cycls_pass"` | Monetization via Cycls Pass subscriptions. Enables both auth and analytics. |
+
+## Native UI Components
+
+Yield structured objects for rich streaming responses:
+
+```python
+@cycls.agent()
+async def demo(context):
+    yield {"type": "thinking", "thinking": "Analyzing the request..."}
+    yield "Here's what I found:\n\n"
+
+    yield {"type": "table", "headers": ["Name", "Status"]}
+    yield {"type": "table", "row": ["Server 1", "Online"]}
+    yield {"type": "table", "row": ["Server 2", "Offline"]}
+
+    yield {"type": "code", "code": "result = analyze(data)", "language": "python"}
+    yield {"type": "callout", "callout": "Analysis complete!", "style": "success"}
+```
+
+| Component | Streaming |
+|-----------|-----------|
+| `{"type": "thinking", "thinking": "..."}` | Yes |
+| `{"type": "code", "code": "...", "language": "..."}` | Yes |
+| `{"type": "table", "headers": [...]}` | Yes |
+| `{"type": "table", "row": [...]}` | Yes |
+| `{"type": "status", "status": "..."}` | Yes |
+| `{"type": "callout", "callout": "...", "style": "..."}` | Yes |
+| `{"type": "image", "src": "..."}` | Yes |
+
+### Thinking Bubbles
+
+The `{"type": "thinking", "thinking": "..."}` component renders as a collapsible thinking bubble in the UI. Each yield appends to the same bubble until a different component type is yielded:
+
+```python
+# Multiple yields build one thinking bubble
+yield {"type": "thinking", "thinking": "Let me "}
+yield {"type": "thinking", "thinking": "analyze this..."}
+yield {"type": "thinking", "thinking": " Done thinking."}
+
+# Then output the response
+yield "Here's what I found..."
+```
+
+This works seamlessly with OpenAI's reasoning models - just map reasoning summaries to the thinking component.
+
+## Context Object
+
+```python
+@cycls.agent()
+async def chat(context):
+    context.messages      # [{"role": "user", "content": "..."}]
+    context.messages.raw  # Full data including UI component parts
+    context.user          # User(id, email, name, plans) when auth=True
+```
+
+## API Endpoints
+
+| Endpoint | Format |
+|----------|--------|
+| `POST chat/cycls` | Cycls streaming protocol |
+| `POST chat/completions` | OpenAI-compatible |
+
+## Streaming Protocol
+
+Cycls streams structured components over SSE:
+
+```
+data: {"type": "thinking", "thinking": "Let me "}
+data: {"type": "thinking", "thinking": "analyze..."}
+data: {"type": "text", "text": "Here's the answer"}
+data: {"type": "callout", "callout": "Done!", "style": "success"}
+data: [DONE]
+```
+
+See [docs/streaming-protocol.md](docs/streaming-protocol.md) for frontend integration.
+
+## Declarative Infrastructure
+
+Define your entire runtime in the decorator:
+
+```python
+@cycls.agent(
+    pip=["openai", "pandas", "numpy"],
+    apt=["ffmpeg", "libmagic1"],
+    copy=["./utils.py", "./models/", "/absolute/path/to/config.json"],
+    copy_public=["./assets/logo.png", "./static/"],
+)
+async def my_agent(context):
+    ...
+```
+
+### `pip` - Python Packages
+
+Install any packages from PyPI. These are installed during the container build.
+
+```python
+pip=["openai", "pandas", "numpy", "transformers"]
+```
+
+### `apt` - System Packages
+
+Install system-level dependencies via apt-get. Need ffmpeg for audio processing? ImageMagick for images? Just declare it.
+
+```python
+apt=["ffmpeg", "imagemagick", "libpq-dev"]
+```
+
+### `copy` - Bundle Files and Directories
+
+Include local files and directories in your container. Works with both relative and absolute paths. Copies files and entire directory trees.
+
+```python
+copy=[
+    "./utils.py",                    # Single file, relative path
+    "./models/",                     # Entire directory
+    "/home/user/configs/app.json",   # Absolute path
+]
+```
+
+Then import them in your function:
+
+```python
+@cycls.agent(copy=["./utils.py"])
+async def chat(context):
+    from utils import helper_function  # Your bundled module
+    ...
+```
+
+### `copy_public` - Static Files
+
+Files and directories served at the `/public` endpoint. Perfect for images, downloads, or any static assets your agent needs to reference.
+
+```python
+copy_public=["./assets/logo.png", "./downloads/"]
+```
+
+Access them at `https://your-agent.cycls.ai/public/logo.png`.
+
+---
+
+### What You Get
+
+- **One file** - Code, dependencies, configuration, and infrastructure together
+- **Instant deploys** - Unchanged code deploys in seconds from cache
+- **No drift** - What you see is what runs. Always.
+- **Just works** - Closures, lambdas, dynamic imports - your function runs exactly as written
+
+No YAML. No Dockerfiles. No infrastructure repo. The code is the deployment.
+
+## License
+
+MIT
+

cycls-0.0.2.81/README.md

@@ -0,0 +1,250 @@
+<h3 align="center">
+Distribute Intelligence
+</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://github.com/Cycls/cycls/actions/workflows/tests.yml"><img src="https://github.com/Cycls/cycls/actions/workflows/tests.yml/badge.svg" alt="Tests" /></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
+
+The open-source SDK for distributing AI agents.
+
+The function is the unit of abstraction in cycls. Your agent logic lives in a plain Python function — the decorator layers on everything else: containerization, authentication, deployment, analytics. You write the function, the `@` handles the infrastructure.
+
+## Distribute Intelligence
+
+Write a function. Deploy it as an API, a web interface, or both. Add authentication, analytics, and monetization with flags.
+
+```python
+import cycls
+
+cycls.api_key = "YOUR_CYCLS_API_KEY"
+
+@cycls.agent(pip=["openai"])
+async def agent(context):
+    from openai import AsyncOpenAI
+    client = AsyncOpenAI()
+
+    stream = await client.responses.create(
+        model="o3-mini",
+        input=context.messages,
+        stream=True,
+        reasoning={"effort": "medium", "summary": "auto"},
+    )
+
+    async for event in stream:
+        if event.type == "response.reasoning_summary_text.delta":
+            yield {"type": "thinking", "thinking": event.delta}  # Renders as thinking bubble
+        elif event.type == "response.output_text.delta":
+            yield event.delta
+
+agent.deploy()  # Live at https://agent.cycls.ai
+```
+
+## Installation
+
+```bash
+pip install cycls
+```
+
+Requires Docker.
+
+## What You Get
+
+- **Streaming API** - OpenAI-compatible `/chat/completions` endpoint
+- **Web Interface** - Chat UI served automatically
+- **Authentication** - `auth=True` enables JWT-based access control
+- **Analytics** - `analytics=True` tracks usage
+- **Monetization** - `plan="cycls_pass"` integrates with [Cycls Pass](https://cycls.ai) subscriptions
+- **Native UI Components** - Render thinking bubbles, tables, code blocks in responses
+
+## Running
+
+```python
+agent.local()             # Development with hot-reload (localhost:8080)
+agent.local(watch=False)  # Development without hot-reload
+agent.deploy()            # Production: https://agent.cycls.ai
+```
+
+Get an API key at [cycls.com](https://cycls.com).
+
+## Authentication & Analytics
+
+```python
+@cycls.agent(pip=["openai"], auth=True, analytics=True)
+async def agent(context):
+    # context.user available when auth=True
+    user = context.user  # User(id, email, name, plans)
+    yield f"Hello {user.name}!"
+```
+
+| Flag | Description |
+|------|-------------|
+| `auth=True` | Universal user pool via Cycls Pass (Clerk-based). You can also use your own Clerk auth. |
+| `analytics=True` | Rich usage metrics available on the Cycls dashboard. |
+| `plan="cycls_pass"` | Monetization via Cycls Pass subscriptions. Enables both auth and analytics. |
+
+## Native UI Components
+
+Yield structured objects for rich streaming responses:
+
+```python
+@cycls.agent()
+async def demo(context):
+    yield {"type": "thinking", "thinking": "Analyzing the request..."}
+    yield "Here's what I found:\n\n"
+
+    yield {"type": "table", "headers": ["Name", "Status"]}
+    yield {"type": "table", "row": ["Server 1", "Online"]}
+    yield {"type": "table", "row": ["Server 2", "Offline"]}
+
+    yield {"type": "code", "code": "result = analyze(data)", "language": "python"}
+    yield {"type": "callout", "callout": "Analysis complete!", "style": "success"}
+```
+
+| Component | Streaming |
+|-----------|-----------|
+| `{"type": "thinking", "thinking": "..."}` | Yes |
+| `{"type": "code", "code": "...", "language": "..."}` | Yes |
+| `{"type": "table", "headers": [...]}` | Yes |
+| `{"type": "table", "row": [...]}` | Yes |
+| `{"type": "status", "status": "..."}` | Yes |
+| `{"type": "callout", "callout": "...", "style": "..."}` | Yes |
+| `{"type": "image", "src": "..."}` | Yes |
+
+### Thinking Bubbles
+
+The `{"type": "thinking", "thinking": "..."}` component renders as a collapsible thinking bubble in the UI. Each yield appends to the same bubble until a different component type is yielded:
+
+```python
+# Multiple yields build one thinking bubble
+yield {"type": "thinking", "thinking": "Let me "}
+yield {"type": "thinking", "thinking": "analyze this..."}
+yield {"type": "thinking", "thinking": " Done thinking."}
+
+# Then output the response
+yield "Here's what I found..."
+```
+
+This works seamlessly with OpenAI's reasoning models - just map reasoning summaries to the thinking component.
+
+## Context Object
+
+```python
+@cycls.agent()
+async def chat(context):
+    context.messages      # [{"role": "user", "content": "..."}]
+    context.messages.raw  # Full data including UI component parts
+    context.user          # User(id, email, name, plans) when auth=True
+```
+
+## API Endpoints
+
+| Endpoint | Format |
+|----------|--------|
+| `POST chat/cycls` | Cycls streaming protocol |
+| `POST chat/completions` | OpenAI-compatible |
+
+## Streaming Protocol
+
+Cycls streams structured components over SSE:
+
+```
+data: {"type": "thinking", "thinking": "Let me "}
+data: {"type": "thinking", "thinking": "analyze..."}
+data: {"type": "text", "text": "Here's the answer"}
+data: {"type": "callout", "callout": "Done!", "style": "success"}
+data: [DONE]
+```
+
+See [docs/streaming-protocol.md](docs/streaming-protocol.md) for frontend integration.
+
+## Declarative Infrastructure
+
+Define your entire runtime in the decorator:
+
+```python
+@cycls.agent(
+    pip=["openai", "pandas", "numpy"],
+    apt=["ffmpeg", "libmagic1"],
+    copy=["./utils.py", "./models/", "/absolute/path/to/config.json"],
+    copy_public=["./assets/logo.png", "./static/"],
+)
+async def my_agent(context):
+    ...
+```
+
+### `pip` - Python Packages
+
+Install any packages from PyPI. These are installed during the container build.
+
+```python
+pip=["openai", "pandas", "numpy", "transformers"]
+```
+
+### `apt` - System Packages
+
+Install system-level dependencies via apt-get. Need ffmpeg for audio processing? ImageMagick for images? Just declare it.
+
+```python
+apt=["ffmpeg", "imagemagick", "libpq-dev"]
+```
+
+### `copy` - Bundle Files and Directories
+
+Include local files and directories in your container. Works with both relative and absolute paths. Copies files and entire directory trees.
+
+```python
+copy=[
+    "./utils.py",                    # Single file, relative path
+    "./models/",                     # Entire directory
+    "/home/user/configs/app.json",   # Absolute path
+]
+```
+
+Then import them in your function:
+
+```python
+@cycls.agent(copy=["./utils.py"])
+async def chat(context):
+    from utils import helper_function  # Your bundled module
+    ...
+```
+
+### `copy_public` - Static Files
+
+Files and directories served at the `/public` endpoint. Perfect for images, downloads, or any static assets your agent needs to reference.
+
+```python
+copy_public=["./assets/logo.png", "./downloads/"]
+```
+
+Access them at `https://your-agent.cycls.ai/public/logo.png`.
+
+---
+
+### What You Get
+
+- **One file** - Code, dependencies, configuration, and infrastructure together
+- **Instant deploys** - Unchanged code deploys in seconds from cache
+- **No drift** - What you see is what runs. Always.
+- **Just works** - Closures, lambdas, dynamic imports - your function runs exactly as written
+
+No YAML. No Dockerfiles. No infrastructure repo. The code is the deployment.
+
+## License
+
+MIT

cycls-0.0.2.81/cycls/__init__.py

@@ -0,0 +1,20 @@
+import sys
+from types import ModuleType
+from .sdk import function, agent
+from .runtime import Runtime
+
+class _Module(ModuleType):
+    def __getattr__(self, name):
+        from . import sdk
+        if name in ("api_key", "base_url"):
+            return getattr(sdk, name)
+        raise AttributeError(f"module 'cycls' has no attribute '{name}'")
+
+    def __setattr__(self, name, value):
+        from . import sdk
+        if name in ("api_key", "base_url"):
+            setattr(sdk, name, value)
+            return
+        super().__setattr__(name, value)
+
+sys.modules[__name__].__class__ = _Module

cycls-0.0.2.81/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-0.0.2.81/cycls/chat.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) < 2:
+        print("Usage: cycls chat <url|port>")
+        sys.exit(1)
+    arg = sys.argv[1]
+    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()