Metadata-Version: 2.4
Name: litellm-sage
Version: 0.1.0
Summary: Sage - a terminal AI assistant for OpenAI-compatible API endpoints
Author: ikeawesom
Keywords: cli,ai,assistant,llm,terminal
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: Programming Language :: Python :: 3 :: Only
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: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: openai>=1.30.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: urllib3>=2.0.0
Requires-Dist: rich>=13.0.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: build; extra == "dev"

# 🧙 Sage — Your AI Assistant in the Terminal

Sage is a smart AI helper that lives in your computer's terminal. You type
what you want in plain English, and Sage helps you get it done — reading and
writing files, running tasks, understanding images, and even creating images.

Think of it as a helpful assistant you can chat with, right in your terminal.

Sage connects to any **OpenAI-compatible API endpoint** (such as a
[LiteLLM](https://github.com/BerriAI/litellm) proxy), so you can point it at
whatever models your provider offers.

---

## ⚠️ Before You Start

You need **three things** for Sage to work:

1. **Python installed** on your computer (version 3.10 or newer). If you
   don't have it, download it from https://www.python.org/downloads/ and
   during installation, **tick the box that says "Add python.exe to PATH"**.
2. **An API endpoint URL** — the address of your OpenAI-compatible / LiteLLM
   server (for example, `https://your-litellm-server.com`).
3. **An API key** for that endpoint.

*(If you don't have the endpoint URL or key, ask whoever set up your AI
gateway.)*

---

## 📥 How to Install (One Time)

Sage is installed with [pipx](https://pipx.pypa.io/), a tool that installs
Python command-line apps in their own isolated environment so they don't
clash with anything else on your machine.

1. **Install pipx** (skip if you already have it) — open a terminal and run:
   ```
   python -m pip install --user pipx
   python -m pipx ensurepath
   ```

2. **Close that terminal and open a new one.**
   (Search for "Command Prompt" or "Terminal" in the Windows Start menu.)
   This step is needed so your terminal picks up the updated PATH.

3. **Install Sage:**
   ```
   pipx install litellm-sage
   ```

4. **Test it** — type this and press Enter:
   ```
   sage --version
   ```
   If you see a version number, you're ready! 🎉

   The first time you actually run `sage` (see below), it will start a
   short guided setup to collect your endpoint URL and API key.

You only do this once. To upgrade later, run `pipx upgrade litellm-sage`.

---

## ⚙️ Your Settings

The first time you run `sage` and it can't find a settings file, it
automatically starts a short guided setup right there in the terminal:

1. It creates a `.sage` folder in your user folder for you.
2. It asks for your **endpoint URL** and **API key** — just answer the two
   questions.
3. Everything else (`MODEL`, `IMAGE_MODEL`, `VERIFY_TLS`) is filled in with
   sensible defaults automatically.

That's it — once setup finishes, Sage starts normally and remembers your
answers for next time. If you quit partway through (e.g. with `Ctrl + C`),
no settings file is created, so the same guided setup will simply run again
the next time you start `sage`.

Sage stores these settings in a file at:

```
C:\Users\<your-name>\.sage\.env
```

**To change your settings later**, you can edit this file directly instead
of redoing the guided setup:

1. Open `.env` in a text editor (make sure it's not saved as `.env.txt` — in
   Notepad, choose "All Files" as the type when saving).
2. Update the values, one per line, like this:
   ```
   API_KEY=your-api-key-here
   BASE_URL=https://your-litellm-server.com
   MODEL=claude-opus-4-8
   IMAGE_MODEL=gemini-3-pro-image
   VERIFY_TLS=true
   ```

The available settings are:

| Setting       | What it is                                  |
|---------------|----------------------------------------------|
| `API_KEY`     | Your API key                                |
| `BASE_URL`    | Your endpoint URL                           |
| `MODEL`       | The default AI model to chat with           |
| `IMAGE_MODEL` | The model used for creating images          |
| `VERIFY_TLS`  | Set to `false` if your server uses a private certificate |

`API_KEY` and `BASE_URL` are required — Sage won't start without them.
`MODEL`, `IMAGE_MODEL`, and `VERIFY_TLS` are optional and fall back to
sensible defaults if you leave them out.

---

## 🚀 How to Use Sage

1. Open a terminal **in the folder you want to work in**.
   *(Tip: in File Explorer, type `cmd` in the address bar and press Enter to
   open a terminal in that folder.)*

2. Type:
   ```
   sage
   ```

3. Now just **talk to it** in plain English. For example:
   ```
   › summarize what the files in this folder are about
   › create a to-do list file with 5 example tasks
   › what does this spreadsheet contain?
   ```

4. When you're done, type `/exit` or press `Ctrl + C`.

---

## 🎨 Fun & Useful Things Sage Can Do

### Look at an image and describe it
```
› /attach photo.png
› what's in this picture?
```
*(Replace `photo.png` with your image's name. It must be in the same folder.)*

### Create an image from words
```
› /image a cute cartoon airplane flying over clouds
```
Sage will create the image, save it in your folder, and open it for you.

### Ask it to do a task and check its own work
```
› create a file called notes.txt with today's date, then show me it worked
```

---

## 🎚️ Modes — Controlling How Much Sage Does on Its Own

Sage asks for your permission before making changes. You can change how
cautious it is by typing `/mode` followed by a name:

| Type this          | What it does                                        |
|---------------------|-----------------------------------------------------|
| `/mode plan`        | Only looks and suggests — **changes nothing**       |
| `/mode normal`      | Asks you before every change *(this is the default)*|
| `/mode auto-edits`  | Edits files automatically, asks before running tasks|
| `/mode auto`        | Does everything automatically (still safe)          |

**Tip for beginners:** stay in **normal** mode. It always asks first, so
nothing happens without your OK.

---

## 💬 Handy Commands

Type these at any time:

| Command            | What it does                                |
|---------------------|---------------------------------------------|
| `/help`             | Shows the list of commands                  |
| `/mode`             | Shows or changes how cautious Sage is       |
| `/model`            | Shows the AI models you can pick from       |
| `/image <words>`    | Creates a picture from your description     |
| `/attach <file>`    | Adds an image so Sage can look at it        |
| `/reset`            | Starts a fresh conversation                 |
| `/exit`             | Closes Sage                                 |

---

## 🤖 Choosing a Different AI Model

Different AI models are better at different things. To see and switch:

```
› /model
```
You'll see a numbered list. To switch, type `/model` and a number:
```
› /model 2
```
Sage remembers your choice for next time.

> **Note:** The models Sage can use depend on what your API endpoint
> provides. If you pick a model your endpoint doesn't offer, Sage will let
> you know.

---

## 🔒 Is It Safe?

Yes — Sage is built to be careful:

- It only works inside the folder you open it in. It **can't touch the rest
  of your computer**.
- It **asks before making changes** (in normal mode).
- It **refuses dangerous commands** (like deleting everything).
- Before editing a file, it **shows you exactly what will change**.

---

## 📤 Sharing Sage With Someone Else

Want to give Sage to a colleague? There's no package to build or file to
send — Sage is published on PyPI, so anyone can install it the same way you
did.

Just point them at this same guide, or tell them:

1. Install pipx (if they don't have it):
   ```
   python -m pip install --user pipx
   python -m pipx ensurepath
   ```
2. Open a new terminal, then install Sage:
   ```
   pipx install litellm-sage
   ```
3. Run `sage` — it walks them through entering their own endpoint URL and
   API key (see "Your Settings" above), then starts right up.

Each person uses their own API key in their own `.env` file, so nobody's
credentials are shared.

*(They'll need Python 3.10+ installed, plus their own endpoint URL and API
key.)*

---

## ❓ Something Went Wrong?

**"sage is not recognized"**
Close the terminal and open a brand-new one — pipx needs a fresh terminal to
pick up the PATH changes. If it still doesn't work, run
`python -m pipx ensurepath` again, then open another new terminal.

**"Connection error"**
Sage can't reach your endpoint. Check that the `BASE_URL` in your settings is
correct and that you can reach the server (e.g. you're on the right network
or VPN if it's a private endpoint).

**"[config error] Missing API_KEY" or "Missing BASE_URL"**
This usually means your settings file exists but is missing a value — edit
`C:\Users\<your-name>\.sage\.env` and fill in `API_KEY` and `BASE_URL` (see
"Your Settings" above). If the file doesn't exist at all, just run `sage`
to get the guided setup.

**"team not allowed to access model" / model error**
The selected model isn't available on your endpoint. Use `/model` to pick a
different one.

**Sage can't see my image**
Make sure the image is in the same folder you opened Sage in, and that you
typed `/attach` with the correct file name first. Also make sure your chosen
model supports image analysis.

---

## 📝 Quick Reference Card

```
Install:           pipx install litellm-sage
First run:         sage   (walks you through setup — endpoint URL + API key)
Start Sage:        sage
Ask something:     just type it and press Enter
Look at an image:  /attach picture.png   then ask about it
Make an image:     /image a sunset over the ocean
Change caution:    /mode plan | normal | auto-edits | auto
Pick a model:      /model   then   /model <number>
Get help:          /help
Quit:              /exit
```

Enjoy using Sage! 🧙✨
