cycls 0.0.2.24__tar.gz → 0.0.2.31__tar.gz

cycls-0.0.2.31/PKG-INFO

@@ -0,0 +1,146 @@
+Metadata-Version: 2.4
+Name: cycls
+Version: 0.0.2.31
+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: 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.31/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.31/cycls/__init__.py

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

cycls-0.0.2.31/cycls/cycls.py

@@ -0,0 +1,168 @@
+import json, time, modal, inspect, uvicorn
+from modal.runner import run_app
+
+import importlib.resources
+theme_path = importlib.resources.files('cycls').joinpath('theme')
+
+async def openai_encoder(stream): # clean up the meta data / new API?
+    async for message in stream:
+        payload = {"id": "chatcmpl-123",
+                   "object": "chat.completion.chunk",
+                   "created": 1728083325,
+                   "model": "model-1-2025-01-01",
+                   "system_fingerprint": "fp_123456",
+                   "choices": [{"delta": {"content": message}}]}
+        if message:
+            yield f"data: {json.dumps(payload)}\n\n"
+    yield "data: [DONE]\n\n"
+
+test_auth_public_key = """
+-----BEGIN PUBLIC KEY-----
+MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAyDudrDtQ5irw6hPWf2rw
+FvNAFWeOouOO3XNWVQrjXCZfegiLYkL4cJdm4eqIuMdFHGnXU+gWT5P0EkLIkbtE
+zpqDb5Wp27WpSRb5lqJehpU7FE+oQuovCwR9m5gYXP5rfM+CQ7ZPw/CcOQPtOB5G
+0UijBhmYqws3SFp1Rk1uFed1F/esspt6Ifq2uDSHESleylqTKUCQiBa++z4wllcV
+PbNiooLRpsF0kGljP2dXXy/ViF7q9Cblgl+FdrqtGfHD+DHJuOSYcPnRa0IHZYS4
+r5i9C2lejVrEDqgJk5IbmQgez0wmEG4ynAxiDLvfdtvrd27PyBI75FsyLER/ydBH
+WwIDAQAB
+-----END PUBLIC KEY-----
+"""
+
+live_auth_public_key = """
+-----BEGIN PUBLIC KEY-----
+MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAorfL7XyxrLG/X+Kq9ImY
+oSQ+Y3PY5qi8t8R4urY9u4ADJ48j9LkmFz8ALbubQkl3IByDDuVbka49m8id9isy
+F9ZJErsZzzlYztrgI5Sg4R6OJXcNWLqh/tzutMWJFOrE3LnHXpeyQMo/6qAd59Dx
+sNqzGxBTGPV1BZvpfhp/TT/sjgbPQWHS4PMpKD4vZLKXeTNJ913fMTUoFAIaL0sT
+EhoeLUwvIuhLx4UYTmjO/sa+fS6mdghjddOkjSS/AWr/K8mN3IXDImGqh83L7/P0
+RCru4Hvarm0qPIhfwEFfWhKFXONMj3x2fT4MM1Uw1H7qKTER2MtOjmdchKNX7x9b
+XwIDAQAB
+-----END PUBLIC KEY-----
+"""
+
+def web(func, front_end_path="", prod=False, org=None, api_token=None, header="", intro="", auth=True): # API auth
+    print(front_end_path)
+    from fastapi import FastAPI, Request, HTTPException, status, Depends
+    from fastapi.responses import StreamingResponse , HTMLResponse
+    from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials
+    import jwt
+    from pydantic import BaseModel, EmailStr
+    from typing import List, Optional
+    from fastapi.templating import Jinja2Templates
+    from fastapi.staticfiles import StaticFiles
+
+    class User(BaseModel):
+        id: str
+        name: str
+        email: EmailStr
+        org: Optional[str] = None
+        plans: List[str] = []
+
+    class Context(BaseModel):
+        messages: List[dict]
+        user: Optional[User] = None
+
+    app = FastAPI()
+    bearer_scheme = HTTPBearer()
+
+    def validate(bearer: HTTPAuthorizationCredentials = Depends(bearer_scheme)):
+        # if api_token and api_token==""
+        try:
+            public_key = live_auth_public_key if prod else test_auth_public_key
+            decoded = jwt.decode(bearer.credentials, public_key, algorithms=["RS256"])
+            # print(decoded)
+            return {"type": "user", 
+                    "user": {"id": decoded.get("id"), "name": decoded.get("name"), "email": decoded.get("email"), "org": decoded.get("org"),
+                             "plans": decoded.get("public").get("plans", [])}}
+        except:
+            raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="Invalid credentials", headers={"WWW-Authenticate": "Bearer"})
+    
+    @app.post("/")
+    @app.post("/chat/completions")
+    async def back(request: Request, jwt: Optional[dict] = Depends(validate) if auth else None):
+        data = await request.json()
+        messages = data.get("messages")
+        user_data = jwt.get("user") if jwt else None
+        context = Context(messages = messages, user = User(**user_data) if user_data else None)
+        stream = await func(context) if inspect.iscoroutinefunction(func) else func(context)
+        if request.url.path == "/chat/completions":
+            stream = openai_encoder(stream)
+        return StreamingResponse(stream, media_type="text/event-stream")
+
+    templates = Jinja2Templates(directory=front_end_path)
+    @app.get("/", response_class=HTMLResponse)
+    async def front(request: Request):
+        return templates.TemplateResponse("index.html", {
+                "request": request, "header": header, "intro": intro, "prod": prod, "auth": auth, "org": org,
+                "pk_live": "pk_live_Y2xlcmsuY3ljbHMuY29tJA", "pk_test": "pk_test_c2VsZWN0LXNsb3RoLTU4LmNsZXJrLmFjY291bnRzLmRldiQ"
+            })
+    app.mount("/", StaticFiles(directory=front_end_path, html=False))
+    return app
+
+class Agent:
+    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 = []
+
+    def __call__(self, name="", header="", intro="", domain=None, auth=False):
+        def decorator(f):
+            self.registered_functions.append({
+                "func": f,
+                "config": ["public", False, self.org, self.api_token, header, intro, auth],
+                "name": name,
+                "domain": domain or f"{name}.cycls.ai",
+            })
+            return f
+        return decorator
+
+    def run(self, port=8000):
+        if not self.registered_functions:
+            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 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, 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:
+            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 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"])
+            return
+        else:
+            with modal.enable_output():
+                run_app(app=self.app, client=self.client)
+                print(" Modal development server is running. Press Ctrl+C to stop.")
+                with modal.enable_output(), run_app(app=self.app, client=self.client): 
+                    while True: time.sleep(10)
+
+# poetry run python agent.py
+# poetry publish --build