Skip to content

getting-started.md

Latest commit

 

History

History
98 lines (70 loc) · 3.7 KB

getting-started.md

File metadata and controls

98 lines (70 loc) · 3.7 KB
Raw

Getting started (no experience needed)

New to AI and not sure what any of this means? Start here. This page explains what cascade is, the handful of words you'll see everywhere, and how to send your very first message — step by step.

What is cascade, in one sentence?

It's a free middleman between your program and AI models. Your program asks it a question; it quietly finds a free AI provider that's available and gets you an answer — switching to another provider automatically if one is busy or rate-limited.

An analogy: imagine a phone operator with a stack of calling cards from different networks. You ask to make a call; the operator tries one card, and if it's out of minutes, instantly tries the next — you never get a busy signal. cascade is that operator, and the "cards" are free API keys from providers like Google Gemini, Groq, and others.

Why would I want it?

  • It's free. It uses the free tiers of many AI providers.
  • It doesn't go down. When one provider hits its limit, it falls back to another, so your app keeps working.
  • It's a drop-in. If you already use code that talks to OpenAI or Anthropic, you change one line (the address) and it works.

Words you'll keep seeing

You don't need to memorize these — skim them, and come back when one shows up. There's a fuller list in concepts.md.

  • LLM (Large Language Model) — the actual AI "brain" that reads text and writes a reply (e.g. GPT, Gemini, Claude, Llama).
  • API key — a secret password that lets your program use a provider. You get these free from the providers (see providers.md).
  • Provider — a company that hosts LLMs you can call over the internet (Gemini, Groq…).
  • Token — roughly ¾ of a word. AI usage and limits are measured in tokens.
  • Prompt — the text you send to the AI.

Step 1 — Install it

curl -fsSL https://raw.githubusercontent.com/chrisluersen/cascade/main/get.sh | bash

This downloads cascade and adds a cascade command to your terminal.

Step 2 — Add your first free key

Run the friendly setup wizard:

cascade setup

It will ask which provider you have a key for and walk you through it. Don't have one yet? Gemini is the easiest and most generous — get a free key at aistudio.google.com, then paste it when asked. (More options in providers.md.)

Step 3 — Check it's running

curl http://localhost:8319/health

You should see {"status":"ok",...}. That means cascade is up and listening.

Step 4 — Send your first message

cascade understands the same "language" as the popular OpenAI library, so any OpenAI example works — you just point it at cascade. Install the library and run this:

pip install openai
from openai import OpenAI

# api_key here is cascade's own password (default "sk-cascade-1"), NOT a provider key.
client = OpenAI(base_url="http://localhost:8319/v1", api_key="sk-cascade-1")

reply = client.chat.completions.create(
    model="cascade",
    messages=[{"role": "user", "content": "Explain what an AI agent is, simply."}],
)
print(reply.choices[0].message.content)

Run it — you just made your first AI call, for free, through cascade. 🎉

Where to go next

  • Want to build something that does things, not just chat? → build-an-agent.md walks you from a chatbot to a real AI agent, step by step.
  • Confused by a term? → concepts.md is a plain-language glossary.
  • Want more providers / more reliability? → providers.md.
  • Want to change settings? → configuration.md.