chat-in-a-nutshell 1.6.0

A terminal-based script for interacting with OpenAI's and Anthropic's API.

chat-in-a-nutshell

This script provides a simple way to chat with AI models from OpenAI and Anthropic directly from your terminal. It lets you send messages and receive responses without leaving the command line interface.

Example

Input

$ ch -m 'Write a Python function to greet the person reading this text.'

Output

Chat
Model: gpt-3.5-turbo, temperature: 0.0
System: You are a skilled Python programmer who writes tersely.
Message: Write a Python function to greet the person reading this text.

Sure, here you go!

```python
def greet():
    print("Hello there!")
```

This code defines a function called `greet()` that, when called, will print the greeting "Hello there!" to the console.
(83 tokens used.)

Output overview

First, there is a recap of the request sent to the API with selected arguments. Next, chat completion API's response is displayed. Output also includes token count (e.g., 83 tokens used) at the end.

Arguments

-m

The message is specified using the --message, -m argument.

$ ch -m 'Write a Python function `hello_world`.'

-s

The default system message is: 'You are a skilled Python programmer who writes tersely.' You can change it by specifying the --system, -s argument inside the current command:

$ ch -s 'You are a remarkable Italian teacher.' -m 'Translate "Hello there!"'

From the version v1.1.0 the recent system message becomes the default one until further change (or configuration file deletion).

-c

On/off flag indicating whether a conversation is intended and messages will be appended to the list of messages in the configuration file. Use --conversation, -c argument inside the current command.

--model

You may specify the model that will be used for the API requests (until further change).

-t

The temperature may be set using the --temperature, -t argument. The default value for this script is 0 (lowest).

--save-audio

Specify the path to save the audio response using the --save-audio argument.

--available-models

List available provider models using the --available-models argument. Not all models are suitable to use with this script.

--available-models-gpt

List available ChatGPT models using the --available-models-gpt argument. Not all models are suitable to use with this script.

--available-tools

List available tools for function calling using the --available-tools argument.

--use-tools, --no-tools

Specify --use-tools to enable the model the access to user-defined tools. Specify --no-tools to disable it. The option is saved for future requests. Tools are disabled by default. Note: To use tools, you must set the TOOLS_URL environment variable to the URL path of your tool definitions. You can refer to example_tools.json in the repository to see the example tool definition file structure.

-e, --reasoning-effort

Set the reasoning effort by specifying --reasoning-effort, -e. Choose one of the available options: low, medium, high. The option is saved for future requests. The default value for this script is low reasoning effort. This configuration is only applicable to reasoning models.

-p, --provider

Set the provider by specifying --provider, -p. Choose one of the available options: openai, anthropic. The option is saved for future requests. The default value for this script is openai. Example usage:

$ ch -p anthropic --model claude-3-7-sonnet-latest

$ ch -p openai --model gpt-4o

Requirements

To use this script, you will need to have the following:

• Python 3.8 or higher
• A provider API key (stored in an environment variable OPENAI_API_KEY for provider openai, ANTHROPIC_API_KEY for anthropic)

Usage

To use the script:

1. Add your API key to the OPENAI_API_KEY environment variable (ANTHROPIC_API_KEY for Anthropic).
2. Install the package using: pip install chat-in-a-nutshell

Debug Mode

To see detailed error logs and tracebacks, set the CHAT_LOG_LEVEL environment variable to DEBUG:

export CHAT_LOG_LEVEL=DEBUG
ch -m "Your message"

Limitations

This script was developed for chatting with OpenAI's ChatGPT from the comfort of the terminal. The API used in the script incurs charges (depending on its usage). For more information about pricing, refer to the provider documentation. Please note that there is no warranty for script functionality. Also, keep in mind that it is suitable for brief and straightforward messages.

Release Notes

Version 1.6.0 (2025-07-17)

• Documentation for this release will be updated in the next version.

Version 1.5.1 (2025-03-02)

• Added --max-tokens parameter to limit token generation (default: 4096)
• Enhanced error handling with formatted error messages
• Improved provider model listings with tabular display
• Renamed main script to chat_provider.py for clarity

Version 1.5.0 (2025-03-02)

• Anthropic Provider Integration:
  • Added support for Anthropic as a provider.
  • Select provider with -p or --provider flag.
  • Requires ANTHROPIC_API_KEY environment variable for authentication.
  • Required parameter max_tokens is set to 8,000 tokens (the absolute maximum number of tokens to generate)
• Dependencies: Added anthropic~=0.49.0.

Version 1.4.0 (2025-02-24)

• OpenAI requests refactoring:

  • Added back system messages for o1 and o3 models, now supported as developer messages.
  • Introduced an option to specify reasoning effort for reasoning models.
  • Improved readability of --available-models and --available-models-gpt outputs.

• Tool calling:

  • The feature can be toggled with --use-tools to enable and --no-tools to disable.
  • To use your own tools, specify the URL path using the TOOLS_URL environment variable. Check example_tools.json in the repo for the example tool definition file structure.
  • Review available tools with --available-tools.

Version 1.3.0 (2024-11-17)

• o1 model support:

  • Removed system message from requests to o1 models because they are currently not supported.
  • Set temperature to 1 for o1 models; other values are not currently supported.

• Added CI/CD Pipeline:

  • Added GitHub Actions pipeline for deploying to PyPI.

Version 1.2.0 (2024-07-05)

• Migrated to OpenAI v1
• Published as PyPi package (https://pypi.org/project/chat-in-a-nutshell/)
• Updated executable name from chat to ch to avoid conflicts with other programs.
• Configuration file containing system message, temperature, model and conversation if in conversation mode is now saved in the home directory (~/.chatconfig.json).
• Added the option to save the response as audio file to a specified path.
• Added the option to list available OpenAI and ChatGPT models.

Version 1.1.0 (2023-06-22)

• Added the option to make a new system message as default by creating a config file.
• Added the option to select a model (--help now prints the list of available gpt models)
• Added the option to select a temperature for a model.
• The chatbot is now initialized as a class instance.
• Added a flag conversation that enables longer conversation.

Version 1.0.0 (2023-04-22)

• Initial release of the script

Contribution

Feel free to leave suggestions in the form of GitHub issues. Thank you!