# Assistants Framework
Welcome to the AI Assistants Framework! This repository contains the foundational code for creating versatile AI assistants capable of interacting through various front-end interfaces and utilizing interchangeable data layers. The goal is to create a powerful yet flexible assistants framework that can adapt to different user needs and environments.
## Table of Contents
- [Features](#features)
- [Installation](#installation)
- [Usage](#usage)
- [Environment Variables](#environment-variables)
- [Contributing](#contributing)
- [License](#license)
## Features
- **Multi-Front-End Support**: The AI assistant (configured via environment variables) can interact through different user interfaces, including CLI and Telegram.
- **User Data Management**: Efficient handling of user data with a robust backend.
- **Interchangeable Data Layers**: Easily swap out the underlying data storage solutions, such as SQLite or other databases (coming soon).
- **Extensible Architecture**: Built with modularity in mind, allowing for easy addition of new features and integrations.
- **Support For Multiple LLMs**: The assistant can use different models for different tasks, such as reasoning or code generation. As well as OpenAI `gpt-*` (general) & `o1` (reasoning) models, there is also support for models from Anthropic, e.g. `claude-3.5-sonnet-latest` (which we use like a reasoning model). It's also possible to generate images using DALL-E models; however, this is not yet integrated into the CLI (but does have Telegram support).
### CLI Features
- **Code Highlighting**: The CLI supports syntax highlighting for code snippets.
- **Thread Selection/Continuation**: The CLI can continue previous threads for a more seamless conversational experience. Previous thread ids are stored in the DB along with the initial prompt.
- **Editor Integration**: The CLI can open the default editor to compose a prompt.
- **File Input**: The CLI can read the initial prompt from a file.
- **Generate Images**: Generate images using your favourite OpenAI image model (defaults to `dall-e-3`)
- **Natural Interactive Prompt**: Prompt history, copy & paste, auxiliary commands, help menu
## Installation
To get started with the AI Assistant Project, follow these steps:
- \[Optional\] Create a Python virtual environment (recommended, but not required on most systems) (Requires Python 3.10+) (a simple way is to use the built-in `venv` module, e.g., `python -m venv my-venv; source my-venv/bin/activate`)
- Install the package using pip:
```bash
pip install assistants-framework
```
You can then run the following command to start the CLI:
```bash
$ ai-cli
```
NOTE: if your virtual environment is not activated, you may need to use /path/to/venv/bin/ai-cli instead of just ai-cli. Consider adding the virtual environment's bin directory to your PATH or otherwise linking the executable to a location in your PATH or creating an alias.
There is an installation script that can be used to add the `ai-cli`, `ai-tg-bot` & `claude` commands to your PATH. You can run this script with the following command:
```bash
$ ai-cli install
```
If you wish to use the Telegram bot interface, you can install the additional dependencies:
```bash
pip install assistants-framework[telegram]
```
To run the telegram bot polling loop, you can just use the following command:
```bash
$ ai-tg-bot
```
## Usage
### Command Line Interface
For help running the assistant through the CLI, simply run:
```
$ ai-cli --help
usage: ai-cli [-h] [-e] [-f INPUT_FILE] [-i INSTRUCTIONS_FILE] [-t] [-C] [prompt ...]
CLI for AI Assistant
positional arguments:
prompt Positional arguments concatenate into a single prompt. E.g. `ai-cli
Is this a single prompt\?` (question mark escaped) ...will be passed
to the program as a single string (without the backslash). You can
also use quotes to pass a single argument with spaces and special
characters. See the -e and -f options for more advanced prompt
options.
options:
-h, --help show this help message and exit
-e, --editor Open the default editor to compose a prompt.
-f INPUT_FILE, --input-file INPUT_FILE
Read the initial prompt from a file (e.g., 'input.txt').
-i INSTRUCTIONS_FILE, --instructions INSTRUCTIONS_FILE
Read the initial instructions (system message) from a specified
file; if not provided, environment variable `ASSISTANT_INSTRUCTIONS`
or defaults will be used.
-t, --continue-thread
Continue previous thread. (not currently possible with `-C` option)
-C, --code Use specialised reasoning/code model. WARNING: This model will be
slower and more expensive to use.
```
There are also a number if commands that can be invoked in the CLI and these are all prefixed with a forward slash (`/`)
```
$ ai-cli
Assistant CLI v0.5.0; using 'gpt-4o-mini' model.
Type '/help' (or '/h') for a list of commands.
>>> /help
Commands:
/h, /help Show this help message
/e, /editor Open the default editor to compose a prompt
/i, /image <prompt>
Generate an image from the prompt supplied as args
e.g. `/i a dog riding a pony, in the style of Botero`
/c, /copy Copy the previous response to the clipboard
/cc, /copy-code [i]
Copy the code blocks from the previous response to the clipboard
(an optional index can be supplied to copy a single code block)
/n, /new Start a new thread and clear the terminal screen
/t, /threads: List all the threads, and select one to continue
/clear, C-l Clear the terminal screen without starting a new thread
Press Ctrl+C or Ctrl+D to exit the program
Anything else you type will be sent to the assistant for processing.
>>> /image a dog riding a pony, in the style of Botero
```
Note: prompt (& command) history is saved in `$ASSISTANTS_CONFIG_DIR/history` (default `~/.config/assistants/history`); responses are not saved here, just user input; this history file is used to provide a prompt history which can be accessed via up and down arrows as with your bash prompt. Bear this file in mind when auditing security as you would with shell history.
You can customize the behavior of the assistant by modifying the `ASSISTANT_INSTRUCTIONS` environment variable, which defaults to `"You are a helpful assistant."`
To use with Claude.ai (Anthropic) models, you can set the `CODE_MODEL` environment variable to `claude-3.5-sonnet-latest` or another model of your choice and run the program with the `-C` option. You must have an API key for Anthropic models set in the `ANTHROPIC_API_KEY` environment variable (or another variable that you have specified; see below).
There is also a `claude` command that can be used to automatically set the relevant environment variables to use the CLI with the `claude-3.5-sonnet-latest` model.
```bash
$ claude -e # open the editor to compose a prompt for Claude
```
## Environment Variables
In addition to `ASSISTANT_INSTRUCTIONS`, other environment variables that can be configured include:
- `ASSISTANTS_API_KEY_NAME` - The name of the API key environment variable to use for authentication (defaults to `OPENAI_API_KEY`) - remember to also set the corresponding API key value to the environment variable you choose (or the default).
- `ANTHROPIC_API_KEY_NAME` - The name of the API key environment variable to use for authentication with Anthropic models (defaults to `ANTHROPIC_API_KEY`)
- `DEFAULT_MODEL` - The default model to use for OpenAI API requests (defaults to `gpt-4o-mini`)
- `CODE_MODEL` - more advanced reasoning model to use for OpenAI API requests (defaults to `o1-mini`, but also supports `o1`, `o3-mini` & `claude-3-5-sonnet-latest`)
- `IMAGE_MODEL` - defaults to `dall-e-3`
- `CLAUDE_MAX_TOKENS` - the maximum number of tokens claude-* models may use for their responses
- `ASSISTANTS_DATA_DIR` - The directory to store user data (defaults to `~/.local/share/assistants`)
- `ASSISTANTS_CONFIG_DIR` - The directory to store configuration files (defaults to `~/.config/assistants`)
- `TG_BOT_TOKEN` - The Telegram bot token if using the Telegram UI
- `OPEN_IMAGES_IN_BROWSER` - (cli) default `true`; can be set to `0` or `false` to turn off opening images by default
## Contributing
Contributions are welcome! If you have suggestions for improvements, please feel free to submit a pull request or open an issue.
1. Fork the repository.
2. Commit your changes.
3. Open a pull request.
See the dev dependencies in the dev_requirements.txt file for formatting and linting tools.
#### TODOS:
- add postgresql support for data layer
- add support for more models/APIs
- improve local thread/conversation handling to better consider max tokens and truncation of conversation history
## License
This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
---
Thank you for checking out the AI Assistant Project! I hope you find it useful and inspiring. Check out the examples directory to see the assistant in action!
Changelog
---
### 26/02/2025 v0.5.5
- add support for stdin redirection
- add support for new models
- add dummy-model for testing/debugging
- fix duplicated output when using the `/e` (editor) command
---
### 31/01/2025 v0.5.3
- add install command to add environment's bin directory to the PATH
- update README.md
---
### 30/01/2025 v0.5.2
- add `claude` command to automatically set relevant environment variables to use CLI with `claude-3-5-sonnet-latest` model.
---
### 29/01/2025 v0.5.1
- fix typo in setup.py preventing installation
- convert TerminalSelector to use label/value pairs instead of just strings of its values
- alters thread labels when selecting so that the thread id is not shown, just the initial prompt
---
### 12/01/2025 v0.5.0
- add support for image generation via OpenAI API
Raw data
{
"_id": null,
"home_page": "https://github.com/nihilok/assistants",
"name": "assistants-framework",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "openai gpt3 gpt3.5 gpt4 o1 chatgpt chatbot assistant assistants claude anthropic cli telegram llm bot ui tui coding-assistant coding programming",
"author": "Michael Jarvis",
"author_email": "nihilok@jarv.dev",
"download_url": "https://files.pythonhosted.org/packages/d2/ac/a79d23d2554be81c78aad8839120b2a8db9392db9f96df819c00e25dce9b/assistants_framework-0.5.5.tar.gz",
"platform": null,
"description": "# Assistants Framework\n\nWelcome to the AI Assistants Framework! This repository contains the foundational code for creating versatile AI assistants capable of interacting through various front-end interfaces and utilizing interchangeable data layers. The goal is to create a powerful yet flexible assistants framework that can adapt to different user needs and environments.\n\n## Table of Contents\n\n- [Features](#features)\n- [Installation](#installation)\n- [Usage](#usage)\n- [Environment Variables](#environment-variables)\n- [Contributing](#contributing)\n- [License](#license)\n\n## Features\n\n- **Multi-Front-End Support**: The AI assistant (configured via environment variables) can interact through different user interfaces, including CLI and Telegram.\n- **User Data Management**: Efficient handling of user data with a robust backend.\n- **Interchangeable Data Layers**: Easily swap out the underlying data storage solutions, such as SQLite or other databases (coming soon).\n- **Extensible Architecture**: Built with modularity in mind, allowing for easy addition of new features and integrations.\n- **Support For Multiple LLMs**: The assistant can use different models for different tasks, such as reasoning or code generation. As well as OpenAI `gpt-*` (general) & `o1` (reasoning) models, there is also support for models from Anthropic, e.g. `claude-3.5-sonnet-latest` (which we use like a reasoning model). It's also possible to generate images using DALL-E models; however, this is not yet integrated into the CLI (but does have Telegram support).\n\n### CLI Features\n- **Code Highlighting**: The CLI supports syntax highlighting for code snippets.\n- **Thread Selection/Continuation**: The CLI can continue previous threads for a more seamless conversational experience. Previous thread ids are stored in the DB along with the initial prompt.\n- **Editor Integration**: The CLI can open the default editor to compose a prompt.\n- **File Input**: The CLI can read the initial prompt from a file.\n- **Generate Images**: Generate images using your favourite OpenAI image model (defaults to `dall-e-3`)\n- **Natural Interactive Prompt**: Prompt history, copy & paste, auxiliary commands, help menu\n\n## Installation\n\nTo get started with the AI Assistant Project, follow these steps:\n\n- \\[Optional\\] Create a Python virtual environment (recommended, but not required on most systems) (Requires Python 3.10+) (a simple way is to use the built-in `venv` module, e.g., `python -m venv my-venv; source my-venv/bin/activate`)\n\n- Install the package using pip:\n\n```bash\npip install assistants-framework\n```\n\nYou can then run the following command to start the CLI:\n\n```bash\n$ ai-cli\n```\n\nNOTE: if your virtual environment is not activated, you may need to use /path/to/venv/bin/ai-cli instead of just ai-cli. Consider adding the virtual environment's bin directory to your PATH or otherwise linking the executable to a location in your PATH or creating an alias.\n\nThere is an installation script that can be used to add the `ai-cli`, `ai-tg-bot` & `claude` commands to your PATH. You can run this script with the following command:\n\n```bash\n$ ai-cli install\n```\n\nIf you wish to use the Telegram bot interface, you can install the additional dependencies:\n\n```bash\npip install assistants-framework[telegram]\n```\n\nTo run the telegram bot polling loop, you can just use the following command:\n\n```bash\n$ ai-tg-bot\n```\n\n## Usage\n\n### Command Line Interface\n\nFor help running the assistant through the CLI, simply run:\n\n```\n$ ai-cli --help\nusage: ai-cli [-h] [-e] [-f INPUT_FILE] [-i INSTRUCTIONS_FILE] [-t] [-C] [prompt ...]\n\nCLI for AI Assistant\n\npositional arguments:\n prompt Positional arguments concatenate into a single prompt. E.g. `ai-cli\n Is this a single prompt\\?` (question mark escaped) ...will be passed\n to the program as a single string (without the backslash). You can\n also use quotes to pass a single argument with spaces and special\n characters. See the -e and -f options for more advanced prompt\n options.\n\noptions:\n -h, --help show this help message and exit\n -e, --editor Open the default editor to compose a prompt.\n -f INPUT_FILE, --input-file INPUT_FILE\n Read the initial prompt from a file (e.g., 'input.txt').\n -i INSTRUCTIONS_FILE, --instructions INSTRUCTIONS_FILE\n Read the initial instructions (system message) from a specified\n file; if not provided, environment variable `ASSISTANT_INSTRUCTIONS`\n or defaults will be used.\n -t, --continue-thread\n Continue previous thread. (not currently possible with `-C` option)\n -C, --code Use specialised reasoning/code model. WARNING: This model will be\n slower and more expensive to use.\n```\n\nThere are also a number if commands that can be invoked in the CLI and these are all prefixed with a forward slash (`/`)\n\n```\n$ ai-cli\nAssistant CLI v0.5.0; using 'gpt-4o-mini' model.\nType '/help' (or '/h') for a list of commands.\n>>> /help\nCommands:\n\n/h, /help Show this help message\n/e, /editor Open the default editor to compose a prompt\n/i, /image <prompt>\n Generate an image from the prompt supplied as args\n e.g. `/i a dog riding a pony, in the style of Botero`\n/c, /copy Copy the previous response to the clipboard\n/cc, /copy-code [i]\n Copy the code blocks from the previous response to the clipboard\n (an optional index can be supplied to copy a single code block)\n/n, /new Start a new thread and clear the terminal screen\n/t, /threads: List all the threads, and select one to continue\n/clear, C-l Clear the terminal screen without starting a new thread\n\nPress Ctrl+C or Ctrl+D to exit the program\n\nAnything else you type will be sent to the assistant for processing.\n\n>>> /image a dog riding a pony, in the style of Botero\n```\n\nNote: prompt (& command) history is saved in `$ASSISTANTS_CONFIG_DIR/history` (default `~/.config/assistants/history`); responses are not saved here, just user input; this history file is used to provide a prompt history which can be accessed via up and down arrows as with your bash prompt. Bear this file in mind when auditing security as you would with shell history.\n\nYou can customize the behavior of the assistant by modifying the `ASSISTANT_INSTRUCTIONS` environment variable, which defaults to `\"You are a helpful assistant.\"`\n\nTo use with Claude.ai (Anthropic) models, you can set the `CODE_MODEL` environment variable to `claude-3.5-sonnet-latest` or another model of your choice and run the program with the `-C` option. You must have an API key for Anthropic models set in the `ANTHROPIC_API_KEY` environment variable (or another variable that you have specified; see below).\n\nThere is also a `claude` command that can be used to automatically set the relevant environment variables to use the CLI with the `claude-3.5-sonnet-latest` model.\n\n```bash\n$ claude -e # open the editor to compose a prompt for Claude\n```\n\n## Environment Variables\n\nIn addition to `ASSISTANT_INSTRUCTIONS`, other environment variables that can be configured include:\n\n- `ASSISTANTS_API_KEY_NAME` - The name of the API key environment variable to use for authentication (defaults to `OPENAI_API_KEY`) - remember to also set the corresponding API key value to the environment variable you choose (or the default).\n- `ANTHROPIC_API_KEY_NAME` - The name of the API key environment variable to use for authentication with Anthropic models (defaults to `ANTHROPIC_API_KEY`)\n- `DEFAULT_MODEL` - The default model to use for OpenAI API requests (defaults to `gpt-4o-mini`)\n- `CODE_MODEL` - more advanced reasoning model to use for OpenAI API requests (defaults to `o1-mini`, but also supports `o1`, `o3-mini` & `claude-3-5-sonnet-latest`)\n- `IMAGE_MODEL` - defaults to `dall-e-3`\n- `CLAUDE_MAX_TOKENS` - the maximum number of tokens claude-* models may use for their responses\n- `ASSISTANTS_DATA_DIR` - The directory to store user data (defaults to `~/.local/share/assistants`)\n- `ASSISTANTS_CONFIG_DIR` - The directory to store configuration files (defaults to `~/.config/assistants`)\n- `TG_BOT_TOKEN` - The Telegram bot token if using the Telegram UI\n- `OPEN_IMAGES_IN_BROWSER` - (cli) default `true`; can be set to `0` or `false` to turn off opening images by default\n\n## Contributing\n\nContributions are welcome! If you have suggestions for improvements, please feel free to submit a pull request or open an issue.\n\n1. Fork the repository.\n2. Commit your changes.\n3. Open a pull request.\n\nSee the dev dependencies in the dev_requirements.txt file for formatting and linting tools.\n\n#### TODOS: \n\n- add postgresql support for data layer\n- add support for more models/APIs\n- improve local thread/conversation handling to better consider max tokens and truncation of conversation history\n\n## License\n\nThis project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.\n\n---\n\nThank you for checking out the AI Assistant Project! I hope you find it useful and inspiring. Check out the examples directory to see the assistant in action!\n\nChangelog\n---\n\n### 26/02/2025 v0.5.5\n\n- add support for stdin redirection\n- add support for new models\n- add dummy-model for testing/debugging\n- fix duplicated output when using the `/e` (editor) command\n\n---\n\n### 31/01/2025 v0.5.3\n\n- add install command to add environment's bin directory to the PATH\n- update README.md\n\n---\n\n### 30/01/2025 v0.5.2\n\n- add `claude` command to automatically set relevant environment variables to use CLI with `claude-3-5-sonnet-latest` model.\n\n---\n\n### 29/01/2025 v0.5.1\n\n- fix typo in setup.py preventing installation\n- convert TerminalSelector to use label/value pairs instead of just strings of its values\n- alters thread labels when selecting so that the thread id is not shown, just the initial prompt\n\n---\n\n### 12/01/2025 v0.5.0\n\n- add support for image generation via OpenAI API\n",
"bugtrack_url": null,
"license": null,
"summary": "OpenAI Assistants Wrapper, with CLI and Telegram Bot",
"version": "0.5.5",
"project_urls": {
"Homepage": "https://github.com/nihilok/assistants"
},
"split_keywords": [
"openai",
"gpt3",
"gpt3.5",
"gpt4",
"o1",
"chatgpt",
"chatbot",
"assistant",
"assistants",
"claude",
"anthropic",
"cli",
"telegram",
"llm",
"bot",
"ui",
"tui",
"coding-assistant",
"coding",
"programming"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "be5c3e8674c6ab7a14dca8c0ef263ff6de217cf34bd5c3655687b907092fa305",
"md5": "ad9b017e4c26f5ff45e0a8140655304b",
"sha256": "cf7452754478796f91f0ca81ef58378938d61951b124a6757ea60794a4238d2d"
},
"downloads": -1,
"filename": "assistants_framework-0.5.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ad9b017e4c26f5ff45e0a8140655304b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 42044,
"upload_time": "2025-02-26T22:46:29",
"upload_time_iso_8601": "2025-02-26T22:46:29.004802Z",
"url": "https://files.pythonhosted.org/packages/be/5c/3e8674c6ab7a14dca8c0ef263ff6de217cf34bd5c3655687b907092fa305/assistants_framework-0.5.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "d2aca79d23d2554be81c78aad8839120b2a8db9392db9f96df819c00e25dce9b",
"md5": "9ebbd534718c9cde1ea1bef91102695d",
"sha256": "5606533f77e6609706b214dadcaa9dd33e686c389b6ee834fe91593e67a49a5c"
},
"downloads": -1,
"filename": "assistants_framework-0.5.5.tar.gz",
"has_sig": false,
"md5_digest": "9ebbd534718c9cde1ea1bef91102695d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 34124,
"upload_time": "2025-02-26T22:46:31",
"upload_time_iso_8601": "2025-02-26T22:46:31.422134Z",
"url": "https://files.pythonhosted.org/packages/d2/ac/a79d23d2554be81c78aad8839120b2a8db9392db9f96df819c00e25dce9b/assistants_framework-0.5.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-26 22:46:31",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "nihilok",
"github_project": "assistants",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "openai",
"specs": [
[
"==",
"1.59.3"
]
]
},
{
"name": "python-telegram-bot",
"specs": [
[
"==",
"21.10"
]
]
},
{
"name": "aiosqlite",
"specs": [
[
"==",
"0.20.0"
]
]
},
{
"name": "loguru",
"specs": [
[
"==",
"0.7.3"
]
]
},
{
"name": "pyperclip",
"specs": [
[
"==",
"1.9.0"
]
]
},
{
"name": "prompt-toolkit",
"specs": [
[
"==",
"3.0.48"
]
]
},
{
"name": "pygments",
"specs": [
[
"==",
"2.18.0"
]
]
},
{
"name": "aiohttp",
"specs": [
[
"==",
"3.11.11"
]
]
},
{
"name": "anthropic",
"specs": [
[
"==",
"0.42.0"
]
]
},
{
"name": "prompt_toolkit",
"specs": [
[
"~=",
"3.0.48"
]
]
},
{
"name": "aiofiles",
"specs": [
[
"~=",
"24.1.0"
]
]
},
{
"name": "pydantic",
"specs": [
[
"~=",
"2.9.2"
]
]
}
],
"lcname": "assistants-framework"
}
JSON
