cycls 0.0.1.1__tar.gz → 0.0.2.86__tar.gz

cycls-0.0.2.86/PKG-INFO

@@ -0,0 +1,276 @@
+Metadata-Version: 2.4
+Name: cycls
+Version: 0.0.2.86
+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
+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: 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.
+
+```
+  Agent extends App (prompts, skills)
+      └── App extends Function (web UI)
+          └── Function (containerization)
+```
+
+## 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.app(pip=["openai"])
+async def app(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
+
+app.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
+app.local()             # Development with hot-reload (localhost:8080)
+app.local(watch=False)  # Development without hot-reload
+app.deploy()            # Production: https://agent.cycls.ai
+```
+
+Get an API key at [cycls.com](https://cycls.com).
+
+## Authentication & Analytics
+
+```python
+@cycls.app(pip=["openai"], auth=True, analytics=True)
+async def app(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.app()
+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.app()
+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.app(
+    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_app(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.app(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-app.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.86/README.md

@@ -0,0 +1,254 @@
+<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.
+
+```
+  Agent extends App (prompts, skills)
+      └── App extends Function (web UI)
+          └── Function (containerization)
+```
+
+## 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.app(pip=["openai"])
+async def app(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
+
+app.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
+app.local()             # Development with hot-reload (localhost:8080)
+app.local(watch=False)  # Development without hot-reload
+app.deploy()            # Production: https://agent.cycls.ai
+```
+
+Get an API key at [cycls.com](https://cycls.com).
+
+## Authentication & Analytics
+
+```python
+@cycls.app(pip=["openai"], auth=True, analytics=True)
+async def app(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.app()
+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.app()
+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.app(
+    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_app(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.app(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-app.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.86/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-0.0.2.86/cycls/app.py

@@ -0,0 +1,88 @@
+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):
+        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.config = Config(
+            header=header,
+            intro=intro,
+            title=title,
+            auth=auth,
+            plan=plan,
+            analytics=analytics,
+            org=org,
+        )
+
+        # 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", *(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-0.0.2.86/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"