Metadata-Version: 2.4
Name: raw-llm
Version: 1.0.8
Summary: The simplest way to context engineer. Minimal streaming CLI clients for Claude and Gemini.
Author-email: Rodolfo Villaruz <rodolfo@yes.ph>
License-Expression: MIT
Project-URL: Homepage, https://github.com/rodolfovillaruz/raw-llm
Project-URL: Bug Tracker, https://github.com/rodolfovillaruz/raw-llm/issues
Project-URL: Repository, https://github.com/rodolfovillaruz/raw-llm.git
Keywords: llm,claude,gemini,cli,streaming,context-engineering
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: anthropic>=0.25.0
Requires-Dist: google-genai>=0.3.0
Provides-Extra: dev
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: isort>=5.12.0; extra == "dev"
Requires-Dist: pylint>=2.17.0; extra == "dev"
Requires-Dist: flake8>=6.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: pytest>=7.3.0; extra == "dev"
Requires-Dist: build>=0.10.0; extra == "dev"
Requires-Dist: twine>=4.0.0; extra == "dev"
Dynamic: license-file

# Raw LLM

**The simplest way to context engineer.**

Minimal, streaming CLI clients for Claude and Gemini that keep your conversations in plain JSON files.

[![PyPI version](https://img.shields.io/pypi/v/raw-llm)](https://pypi.org/project/raw-llm/)
[![Python versions](https://img.shields.io/pypi/pyversions/raw-llm)](https://pypi.org/project/raw-llm/)
[![License: MIT](https://img.shields.io/pypi/l/raw-llm)](https://pypi.org/project/raw-llm/)

## What is this?

Raw LLM is a pair of thin Python scripts that talk to the Anthropic and Google GenAI APIs. No frameworks, no agents, no abstractions you don't need. Just a prompt, a streaming response, and a JSON file you can version, diff, edit, and pipe.

The entire idea: your conversation _is_ a file. You build context by editing that file. That's it. That's the context engineering.

## Features

- **Streaming output** — responses print token-by-token as they arrive
- **Conversation persistence** — every exchange is saved to a plain JSON file you own
- **Resume any conversation** — pass the JSON file back in to continue where you left off
- **Pipe-friendly** — reads from stdin, writes content to stdout, writes diagnostics to stderr
- **Colored output** — reasoning in gray (stderr), content in cyan (stdout), auto-disabled when piped
- **Conflict detection** — refuses to overwrite a conversation file modified by another process
- **Symlink to switch models** — symlink `claude.py` as `opus` or `haiku` to change the default model

## Installation

### From [PyPI](https://pypi.org/project/raw-llm/)

```bash
pip install raw-llm
```

This installs the `claude`, `sonnet`, `opus`, `haiku`, and `gemini` commands globally.

### From source

```bash
git clone https://github.com/rodolfovillaruz/raw-llm.git
cd raw-llm
pip install .
```

### Development install

```bash
git clone https://github.com/rodolfovillaruz/raw-llm.git
cd raw-llm
pip install -e ".[dev]"
```

Set your API keys:

```bash
export ANTHROPIC_API_KEY="sk-ant-..."
export GEMINI_API_KEY="..."       # or GOOGLE_API_KEY, per google-genai docs
```

## Usage

### Start a new conversation

```bash
claude
# Type your prompt, then press Ctrl+D to submit
```

```bash
echo "Explain monads in one paragraph" | claude
```

```bash
gemini
```

### Resume an existing conversation

```bash
claude .prompt/some-conversation.json
```

The JSON file contains the full message history. Edit it with any text editor to reshape context before your next turn.

### Pipe a file as context

```bash
cat code.py | claude conversation.json
```

### Switch models

```bash
# By flag
claude -m claude-opus-4-6

# By command name
opus
haiku
sonnet
```

| Command              | Default model              |
| -------------------- | -------------------------- |
| `claude` / `sonnet`  | `claude-sonnet-4-6`        |
| `opus`               | `claude-opus-4-6`          |
| `haiku`              | `claude-haiku-4-5`         |
| `gemini`             | `gemini-3.1-pro-preview`   |

### Options

```
usage: claude [-h] [-n] [-v] [-m MODEL] [-t MAX_TOKENS] [-i] [conversation_file]

positional arguments:
  conversation_file         JSON file to resume (omit to start fresh)

options:
  -n, --dry-run             Build the prompt but don't send it
  -v, --verbose             Show model name and prompt preview
  -m, --model MODEL         Override the default model
  -t, --max-tokens TOKENS   Cap the response length
  -i, --interactive         Interactive REPL mode
```

## Conversation format

Conversations are stored as a JSON array of message objects. Each message
carries the standard API fields plus metadata that Raw LLM writes automatically:

```json
[
  {
    "role": "user",
    "content": "What is context engineering?",
    "timestamp": "2025-01-15T10:23:45.123456+00:00"
  },
  {
    "role": "assistant",
    "content": "Context engineering is the practice of ...",
    "timestamp": "2025-01-15T10:23:47.654321+00:00",
    "usage": { "input": 18, "output": 312 },
    "model": "claude-sonnet-4-6"
  }
]
```

| Field       | Added to    | Description                              |
| ----------- | ----------- | ---------------------------------------- |
| `timestamp` | every turn  | UTC time the message was appended (ISO-8601) |
| `usage`     | `assistant` | `input` and `output` token counts for that turn |
| `model`     | `assistant` | Model that produced the response         |

Metadata fields are stripped automatically before the conversation is sent to
the API, so you can safely edit or add them without breaking future turns.

You can create these files by hand, merge them, truncate them, or generate them with other tools. Raw LLM doesn't care. It reads the array, appends your new message, streams the response, and appends that too.

## Project structure

```
.
├── src/
│   └── raw_llm/
│       ├── claude.py       # Claude CLI client
│       ├── gemini.py       # Gemini CLI client
│       └── common.py       # Shared utilities (streaming, I/O, conversation management)
├── pyproject.toml          # Package configuration and entry points
├── Makefile                # Formatting, linting, typing
└── .prompt/                # Default directory for conversation files (auto-used if present)
```

## Development

```bash
make fmt      # Format with black/isort
make lint     # Lint with pylint/flake8
make type     # Type-check with mypy
make all      # All of the above
```

## Why?

Most LLM tools add layers between you and the model. Raw LLM removes them. The conversation is a file. The prompt is stdin. The response is stdout. Everything else is up to you.

## License

MIT
