Cycls is a lightweight python framework for publishing and sharing AI chat-apps. It comes with everything you need to get started, with support for local development. All in pure python. No front-end work required.

​
1. Install

You can install Cycls via pip as follows:

pip install cycls

If you use poetry, you can also install Cycls as:

poetry add cycls

​
2. Obtain Your Secret Key

1

First Step

Visit the registration page at platform.cycls.com

2

Second Step

Complete the sign-up process

3

Third Step

Navigate to the dashboard, and get your secret key

Important Notes About Your Secret Key:

Your secret key will have a prefix of sk-
Never share your secret key publicly as it is used to ensure secure communication between your app and Cycls

​
3. Define Your App Object

Create a new Python file for e.g. main.py in your project directory, and pick a handler for the app’s URL:

main.py
from cycls import App

app = App(secret="sk-secret",
          handler="@handler-name", # app url: handler-name.cycls.app
)

Cycle provides additional optional fields

main.py
from cycls import App

app = App(
    secret="sk-secret",
    handler="@handler-name", # handler-name.cycls.app
    name="Application Name", # optional
    image="Image URL"        # optional
)

​
4. Define the Entry Point for the App

After creating the app object, you’ll need to define your app entry point, which is decorated with @app

main.py
@app
def entry_point(context):
    ...

The context object contains important information:

  • id: A session id, which can be thought of as a conversation id
  • message: An object containing the user’s message
  • send.text: An action to reply to a message with text without streaming
  • stream.text: An action to reply to a message with text streaming

​
5. Full Working Example

Here’s how you might have a complete working app that just resends whatever the user types:

main.py
from cycls import App

app = App(secret="sk-secret",
          handler="@handler-name")

@app
def entry_point(context):
    # Capture the received message
    received_message = context.message.content.text
    # Reply back with a simple message
    context.send.text(f"Received message: {received_message}")

app.publish()

Run your app in the directory containing main.py:

terminal
python main.py

​
6. Async Support for Streaming (WIP)

Cycls also supports asynchronous (async) application connections. Async connections are used for streaming responses like how chat-gpt streams the text back to the user in real time.

Import AsyncApp instead of App

main.py
from cycls import AsyncApp

app = AsyncApp(secret="sk-secret"
               handler="@handler-name")

[WIP] This example demonstrates the implementation of asynchronous streaming. Follow these steps to modify the synchronous behavior:

  1. Replace context.send.text with context.stream.text to enable streaming responses
  2. Utilize yield to send the response incrementally
main.py
from cycls import AsyncApp

app = AsyncApp(secret="sk-secret",
               handler="@handler-name")

async def stream_response(received_message: str):
    # Stream each word in the received message, one at a time
    for word in f"Received message: {received_message}".split():
        yield word

@app
async def entry_point(context):
    # Capture the received message
    received_message = context.message.content.text
    # Initiate streaming of the received message
    await context.stream.text(stream_response(received_message))

app.publish()
In this code, stream_response is a generator function that yields each word from the received message one by one. The entry_point function captures the incoming message and begins the streaming response using context.stream.text.

Run your app in the directory containing main.py:

terminal
python main.py
Overview