Metadata-Version: 2.2
Name: assistants-framework
Version: 0.7.4
Summary: AI Assistant Framework with CLI and Telegram Bot
Author-email: Michael Jarvis <nihilok@jarv.dev>
License: MIT License
Project-URL: Homepage, https://github.com/nihilok/assistants
Project-URL: Bug Tracker, https://github.com/nihilok/assistants/issues
Keywords: openai,gpt3,gpt3.5,gpt4,o1,chatgpt,chatbot,assistant,assistants,claude,anthropic,cli,telegram,llm,bot,ui,tui,coding-assistant,coding,programming
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: openai==1.84.0
Requires-Dist: aiosqlite==0.21.0
Requires-Dist: loguru==0.7.3
Requires-Dist: pyperclip==1.9.0
Requires-Dist: prompt-toolkit==3.0.51
Requires-Dist: pygments-tsx==1.0.3
Requires-Dist: pyyaml==6.0.2
Requires-Dist: anthropic==0.52.2
Requires-Dist: aiofiles==24.1.0
Requires-Dist: aiohttp==3.12.11
Requires-Dist: setproctitle==1.3.6
Requires-Dist: tiktoken==0.9.0
Requires-Dist: pydantic~=2.11.5
Requires-Dist: mistralai~=1.8.1
Requires-Dist: types-pygments~=2.19.0.20250516
Requires-Dist: types-aiofiles~=24.1.0.20250606
Requires-Dist: types-PyYAML~=6.0.12.20250516
Provides-Extra: telegram
Requires-Dist: python-telegram-bot==21.1; extra == "telegram"
Provides-Extra: dev
Requires-Dist: ruff==0.11.13; extra == "dev"
Requires-Dist: pytest==8.3.4; extra == "dev"
Requires-Dist: pytest-mock; extra == "dev"
Requires-Dist: pytest-asyncio; extra == "dev"

# Assistants Framework

A flexible framework for creating AI assistants with multiple frontend interfaces.

## Features

- **Multi-Front-End Support**: CLI and Telegram interfaces built on the same core framework
- **CLI Features**: Code highlighting, thread management, editor integration, file input, image generation
- **Multiple LLM Support**: OpenAI (`gpt-*`, `o*`), Anthropic (`claude-*`), MistralAI (`mistral-*`, `codestral-*`,
  `devstral-*`), and image generation (DALL-E)

## Installation

Requires Python 3.11+

```bash
pip install assistants-framework
```

For Telegram bot functionality:

```bash
pip install assistants-framework[telegram]
```

Add commands to your PATH:

```bash
ai-cli install
```

## Usage

### Command Line Interface

```bash
ai-cli --help
```

Key CLI commands (prefixed with `/`):

- `/help` - Show help message
- `/editor` - Open editor for prompt composition
- `/image <prompt>` - Generate an image
- `/copy` - Copy response to clipboard
- `/new` - Start new thread
- `/threads` - List and select threads
- `/thinking <level>` - Toggle thinking mode (for reasoning models)
- `/last` - Retrieve last message

Use the `claude` command for Anthropic models (Now defaults to Claude 4):

```bash
claude -e  # Open editor for Claude
```

There's also a `chatgpt` command that uses the default ChatGPT model:

```bash
chatgpt -t  # Continue the last thread with ChatGPT (`gpt-4.1-mini`)
```

Run migrations in case of breaking changes:

```bash
ai-cli migrate
```

Rebuild the database:

```bash
ai-cli rebuild
```

### Telegram Interface

The framework includes a Telegram bot interface with the following features:

- **User Management**: Authorise/deauthorise users and chats, promote/demote users
- **Thread Management**: Start new conversation threads
- **Auto-Reply Toggle**: Enable/disable automatic responses
- **Media Generation**: Generate images from text prompts
- **Voice Responses**: Generate audio responses with the `/voice` command

Key Telegram commands:

- `/new_thread` - Clear conversation history and start a new thread
- `/auto_reply` - Toggle automatic responses on/off
- `/image <prompt>` - Generate an image from a text prompt
- `/voice <text>` - Generate an audio response.

## Environment Variables

- `ASSISTANT_INSTRUCTIONS` - System message (default: "You are a helpful assistant")
- `ASSISTANTS_API_KEY_NAME` - API key variable name (default: `OPENAI_API_KEY`)
- `ANTHROPIC_API_KEY_NAME` - Anthropic API key variable (default: `ANTHROPIC_API_KEY`)
- `MISTRAL_API_KEY_NAME` - Mistral API key variable (default: `MISTRAL_API_KEY`)
- `DEFAULT_MODEL` - Default model (default: `gpt-4o-mini`)
- `DEFAULT_CLAUDE_SONNET_MODEL` - Default Claude model (default: `claude-sonnet-4-20250514`)
- `DEFAULT_CLAUDE_OPUS_MODEL` - Default Claude Opus model (default: `claude-opus-4-20250514`)
- `DEFAULT_CHATGPT_MODEL` - Default ChatGPT model (default: `gpt-4.1-mini`)
- `DEFAULT_GPT_REASONING_MODEL` - Default GPT reasoning model (default: `o4-mini`)
- `CODE_MODEL` - Reasoning model (default: `o3-mini`)
- `IMAGE_MODEL` - Image model (default: `dall-e-3`)
- `ASSISTANTS_DATA_DIR` - Data directory (default: `~/.local/share/assistants`)
- `ASSISTANTS_CONFIG_DIR` - Config directory (default: `~/.config/assistants`)
- `TG_BOT_TOKEN` - Telegram bot token
- `OPEN_IMAGES_IN_BROWSER` - Open images automatically (default: `true`)
- `DEFAULT_MAX_RESPONSE_TOKENS` - Default max response tokens (default: `4096`)
- `DEFAULT_MAX_HISTORY_TOKENS` - Default max history tokens (default: `10000`)

## Contributing

Contributions welcome! Fork the repository, make changes, and submit a pull request.

#### TODOs:

- Improved conversation handling/truncation for token limits - currently uses tiktoken for all models
- Additional model/API support
- Additional database support

## License

MIT License
