CycloneAI

CycloneAI is a small Python package that keeps the public API simple:

from cycloneai import Client

ai = Client(provider="auto")
print(ai.ask("Hello"))

What is included

• Client and AsyncClient
• ask(), stream(), compare(), save(), load()
• conversation memory
• provider routing with provider="auto" and fallback
• provider registration for custom backends

What is not included

This package does not automate guest access to third-party hosted LLM websites. The built-in gemini, gpt, and claude providers are explicit placeholders so the public API and provider architecture are ready without shipping code that attempts to bypass official access controls or service terms.

If you want real responses, register your own compliant provider implementation.

Usage

Basic

from cycloneai import Client

ai = Client(provider="auto")
reply = ai.ask("Python study order")
print(reply)

Memory

chat = Client(memory=True)
chat.register_provider(MyProvider())

chat.ask("My name is Hyunho")
chat.ask("What is my name?")

System prompt

ai = Client(system="You are the best coding mentor.")
ai.register_provider(MyProvider())

Streaming

for chunk in ai.stream("Write a short story"):
    print(chunk, end="")

Async

from cycloneai import AsyncClient

ai = AsyncClient()
ai.register_provider(MyProvider())
print(await ai.ask("What is AI?"))

Top-level helper

import cycloneai as cy

provider = MyProvider()
print(cy.ask("Hi", provider=provider))

Custom provider example

from cycloneai import BaseProvider, Client, Response


class MyProvider(BaseProvider):
    name = "demo"

    def ask(self, prompt, *, system=None, history=None, timeout=30):
        return Response(
            text=f"demo reply: {prompt}",
            provider=self.name,
            time=0.01,
            tokens=None,
        )


ai = Client(provider=MyProvider())
print(ai.ask("Hello"))