Metadata-Version: 2.5
Name: charla
Version: 3.1.0
Summary: A terminal based chat application that works with language models.
Project-URL: Documentation, https://github.com/yaph/charla#readme
Project-URL: Issues, https://github.com/yaph/charla/issues
Project-URL: Source, https://github.com/yaph/charla
Author-email: Ramiro Gómez <code@ramiro.org>
License-Expression: MIT
License-File: LICENSE.txt
Keywords: chat-client,chatbot,chatgpt,cli,llama,llm,ollama,terminal
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Requires-Python: >=3.10
Requires-Dist: html2text
Requires-Dist: httpx
Requires-Dist: markdown
Requires-Dist: ollama>=0.6
Requires-Dist: platformdirs
Requires-Dist: prompt-toolkit
Description-Content-Type: text/markdown

# Charla: Chat with Language Models in a Terminal

[![PyPI - Version](https://img.shields.io/pypi/v/charla.svg)](https://pypi.org/project/charla)
[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/charla.svg)](https://pypi.org/project/charla)

**Charla** is a terminal based application for chatting with language models. Charla integrates with Ollama for exchanging messages with model services.

![preview](https://geeksta.net/img/tools/charla-chat-demo.gif)

## Features

* Terminal-based chat system that supports context aware conversations with language models.
* Support for local and cloud models via Ollama.
* Chat messages are automatically saved during and at the end of chat sessions.
* Saved chat sessions can be continued.
* Prompt history is saved and previously entered prompts are auto-suggested.
* Switch between single-line and multi-line input modes without interrupting the chat session.
* Store user preferences in user config or current directory settings files.
* Provide a system prompt for a chat session.
* Load content from local files and web pages to append to prompts.
* Markdown in assistant responses and system prompts is rendered in the terminal.

## Installation

To use Charla with models on your computer, you need a running installation of the [Ollama server](https://ollama.com/download) and at least one supported language model must be installed.

Install Charla using `pipx`:

```console
pipx install charla
```
## Usage

After successful installation and setup you can launch the chat console with the `charla` command in your terminal.

If you use Charla with Ollama, the default provider, you only need to specify the model to use, e.g.:

```console
charla -m gpt-oss
```

To use Ollama cloud models, you need to run them once with the `ollama` command and then you can use them, e.g.:

```console
ollama run gpt-oss:cloud
charla -m gpt-oss:cloud
```

You can set a default model in your user settings file.

## Settings

Settings can be specified as command line arguments and in the settings files. Command line arguments have the highest priority. The location of your user config settings file depends on your operating system. Use the following command to show the location:

```console
charla settings --location
```

You can also store settings in the current working directory in a file named `.charla.json`. The settings in this local override the user config settings.

To save the current settings to a `.charla.json` file in the current directory, use the `--save` argument:

```console
charla settings --save
```

Example settings for using OpenAI's GPT OSS model by default.

```json
{
    "model": "gpt-oss:20b-cloud",
    "chats_path": "./chats",
    "prompt_history": "./prompt-history.txt",
    "provider": "ollama",
    "message_limit": 20,
    "multiline": false
}
```

## CLI Help

Output of `charla -h` with information on all available command line options.

<!-- START: DO NOT EDIT -->
```text
usage: charla [-h] [--model MODEL] [--chats-path CHATS_PATH] [--continue-chat CONTINUE_CHAT]
                             [--prompt-history PROMPT_HISTORY] [--provider PROVIDER] [--message-limit MESSAGE_LIMIT]
                             [--multiline] [--system-prompt SYSTEM_PROMPT] [--think {true,false,low,medium,high}] [--version]
                             {convert,settings} ...

Chat with language models.

positional arguments:
  {convert,settings}    Sub Commands
    convert             Convert chat file to markdown.
    settings            Show current settings.

options:
  -h, --help            show this help message and exit
  --model MODEL, -m MODEL
                        Name of language model to chat with.
  --chats-path CHATS_PATH
                        Directory to store chats.
  --continue-chat CONTINUE_CHAT, -c CONTINUE_CHAT
                        File that contains chat to continue.
  --prompt-history PROMPT_HISTORY
                        File to store prompt history.
  --provider PROVIDER   Name of the provider to use.
  --message-limit MESSAGE_LIMIT
                        Maximum number of messages to use for context.
  --multiline           Use multiline mode.
  --system-prompt SYSTEM_PROMPT, -sp SYSTEM_PROMPT
                        File that contains system prompt to use.
  --think {true,false,low,medium,high}
                        Enable thinking for Ollama models that support it.
  --version             show program's version number and exit

```
<!-- END: DO NOT EDIT -->

## Development

Run the command-line interface directly from the project source without installing the package:

```console
python -m charla.cli
```

## License

Charla is distributed under the terms of the [MIT](https://spdx.org/licenses/MIT.html) license.
