Metadata-Version: 2.5
Name: paella-ai
Version: 1.0.2
Summary: An interactive AI agent in your terminal.
Project-URL: Homepage, https://github.com/PaellaAI/paella
Project-URL: Repository, https://github.com/PaellaAI/paella
Project-URL: Issues, https://github.com/PaellaAI/paella/issues
Author: PaellaAI
License-Expression: MIT
License-File: LICENSE
Keywords: agent,ai,cli,llm,paella
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
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: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Requires-Dist: anthropic>=0.69.0
Requires-Dist: openai>=1.40.0
Requires-Dist: textual>=0.80.0
Requires-Dist: typer>=0.12.0
Description-Content-Type: text/markdown

# paella

[![CI](https://github.com/PaellaAI/paella/actions/workflows/ci.yml/badge.svg)](https://github.com/PaellaAI/paella/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/paella-ai.svg)](https://pypi.org/project/paella-ai/)

An interactive AI agent in your terminal — like Claude Code.

## Installation

**One-liner (recommended — no Python needed):**

```bash
curl -fsSL https://raw.githubusercontent.com/PaellaAI/paella/main/install.sh | sh
```

**Homebrew:**

```bash
brew install PaellaAI/tap/paella
```

**pip (if you already have Python):**

```bash
pip install paella-ai
```

All three install the `paella` command.

## The interactive agent

Just run `paella` (or `paella chat`) to start an interactive session:

```bash
paella
```

On a real terminal this opens a **full-screen app** (scrolling transcript +
anchored input). Piped/non-interactive input falls back to a line REPL
automatically; force it with `paella chat --classic`.

You get a streaming chat loop with **tool use** — the agent can read files,
list directories, run shell commands (with your approval), and search the web.
Responses render as Markdown with syntax-highlighted code blocks; extended
thinking is streamed inline.

### Slash commands & prefixes

| Command / prefix   | Description                              |
| ------------------ | ---------------------------------------- |
| `/help`            | show available commands                  |
| `/model [name]`    | switch model (Claude/OpenAI); no name opens a picker |
| `/clear`           | reset the context window                 |
| `/copy`            | copy the last reply to the clipboard     |
| `/compact`         | summarize older turns to shrink context  |
| `/tools`           | list the tools the agent can call        |
| `/exit`, `/quit`   | leave (or `exit`, or `ctrl+c` twice)     |
| `!<cmd>`           | run a shell command directly             |
| `@<path>`          | attach a file (opens a file picker)      |

## Models

Run `/model` for a picker across **Claude** (Opus 4.8, Fable 5, Sonnet 5,
Haiku 4.5) and **OpenAI** (GPT-5 Codex, GPT-5, o4-mini), or `/model <name>` to
switch directly — the backend is inferred from the id (`gpt-*`/`o*` → OpenAI,
`claude-*` → Anthropic; or force with `openai:<id>`). Switching starts a fresh
session.

Set credentials via environment variables or config:

```bash
export ANTHROPIC_API_KEY=sk-ant-...     # or: paella config set anthropic_api_key ...
export OPENAI_API_KEY=sk-...            # or: paella config set openai_api_key ...
```

Config is stored at `~/.config/paella/config.json`. Relevant keys:
`backend`, `model`, `anthropic_api_key`, `openai_api_key`, `web` (default on).

## Context compaction

Long sessions are kept from overflowing the model's context window by
**auto-summarization**: when the transcript grows past a threshold, the oldest
turns are replaced by a single summary while the most recent turns are kept
verbatim. Run `/compact` to trigger it manually. It rewrites history rarely and
in one batch, so the compacted prefix stays cache-friendly. Config keys:
`compact` (default `true`), `compact_threshold_tokens` (`120000`),
`compact_keep_tokens` (`40000`).

## Other commands

```bash
paella --version
paella config set|get|list|path
```

## Development

This project uses [uv](https://docs.astral.sh/uv/).

```bash
uv sync                   # install deps into a local venv
uv run paella             # run the agent from source
uv run pytest             # run the test suite
```

## Building & publishing

```bash
uv build                  # produces wheel + sdist in dist/
uv publish                # upload to PyPI
```

## License

MIT
