Metadata-Version: 2.4
Name: vtai
Version: 0.7.5
Summary:  VT.ai - Minimal multimodal AI chat app with dynamic conversation routing 
Project-URL: Homepage, https://github.com/vinhnx/VT.ai
Project-URL: Bug Tracker, https://github.com/vinhnx/VT.ai/issues
Author: Vinh Nguyen
License: MIT
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: <3.12,>=3.11
Requires-Dist: aiohttp>=3.13.4
Requires-Dist: chainlit==2.10.1
Requires-Dist: cryptography>=46.0.5
Requires-Dist: google-generativeai==0.8.6
Requires-Dist: httpx==0.28.1
Requires-Dist: litellm==1.83.0
Requires-Dist: mcp>=1.23.0
Requires-Dist: openai==2.30.0
Requires-Dist: pydantic==2.12.5
Requires-Dist: pyjwt>=2.12.0
Requires-Dist: python-dotenv==1.2.2
Requires-Dist: semantic-router[fastembed]==0.1.12
Requires-Dist: tavily-python==0.7.23
Provides-Extra: dev
Requires-Dist: black>=26.3.1; extra == 'dev'
Requires-Dist: flake8==7.3.0; extra == 'dev'
Requires-Dist: isort==8.0.1; extra == 'dev'
Requires-Dist: pytest-asyncio==1.3.0; extra == 'dev'
Requires-Dist: pytest==9.0.2; extra == 'dev'
Requires-Dist: twine==6.2.0; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-llmstxt>=0.2.0; extra == 'docs'
Provides-Extra: http2
Requires-Dist: h2>=4.1.0; extra == 'http2'
Requires-Dist: httpx[http2]>=0.26.0; extra == 'http2'
Description-Content-Type: text/markdown

<h1 align="center">VT</h1>

<p align="center">
  <img src="./public/screenshot.jpg" alt="VT.ai screenshot">
  <p align="center">Multimodal AI Chat App with Dynamic Routing</p>
</p>

<p align="center">
<a href="https://github.com/sponsors/vinhnx"><img alt="Github Sponsors" src="https://img.shields.io/badge/GitHub%20Sponsors-30363D?&logo=GitHub-Sponsors&logoColor=EA4AAA"></a>
</p>

<p align="center">
  <a href="https://pypi.org/project/vtai/"><img alt="PyPI" src="https://img.shields.io/pypi/v/vtai?logo=pypi&logoColor=fff"></a>
  <a href="https://pypi.org/project/vtai/"><img alt="Python" src="https://img.shields.io/pypi/pyversions/vtai?logo=python&logoColor=white"></a>
  <a href="https://huggingface.co/vinhnx90"><img alt="Hugging Face" src="https://img.shields.io/badge/Hugging%20Face-FFD21E?logo=huggingface&logoColor=000"></a>
  <a href="https://codespaces.new/vinhnx/VT.ai"><img alt="Open in GitHub Codespaces" src="https://img.shields.io/badge/Open%20in-Codespaces-blue?logo=github"/></a>
  <a href="https://vinhnx.github.io/VT.ai"><img alt="Documentation" src="https://img.shields.io/badge/Documentation-526CFE?logo=materialformkdocs&logoColor=fff"></a>
  <a href="https://github.com/vinhnx/VT.ai/blob/main/LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-yellow.svg"></a>
  <a href="https://deepwiki.com/vinhnx/VT.ai"><img src="https://deepwiki.com/badge.svg" alt="Ask DeepWiki"></a>
</p>

<p align="center">
  <a href="#"><img alt="Google Gemini" src="https://img.shields.io/badge/Google%20Gemini-886FBF?logo=googlegemini&logoColor=fff"></a>
  <a href="#"><img alt="Claude" src="https://img.shields.io/badge/Claude-D97757?logo=claude&logoColor=fff"></a>
  <a href="#"><img alt="ChatGPT" src="https://img.shields.io/badge/ChatGPT-74aa9c?logo=openai&logoColor=white"></a>
  <a href="#"><img alt="Deepseek" src="https://custom-icon-badges.demolab.com/badge/Deepseek-4D6BFF?logo=deepseek&logoColor=fff"></a>
</p>

## VT.ai

VT.ai is a multimodal AI chat application designed to simplify interaction with different AI models through a unified interface. It employs vector-based semantic routing to direct queries to the most suitable model, eliminating the need to switch between multiple applications and interfaces.

**[Documentation](https://vinhnx.github.io/VT.ai/)**

## Key Features

- **Multi-Provider Integration**: Unified access to models from OpenAI (o1/o3/4o), Anthropic (Claude), Google (Gemini), DeepSeek, Llama, Cohere, and local models via Ollama
- **Semantic Routing System**: Vector-based classification automatically routes queries to appropriate models using FastEmbed embeddings, removing the need for manual model selection
- **Multimodal Capabilities**: Comprehensive support for text, image, and audio inputs with advanced vision analysis
- **Image Generation**: GPT-Image-1 integration with support for transparent backgrounds, multiple formats, and customizable quality parameters
- **Web Search Integration**: Real-time information retrieval with source attribution via Tavily API
- **Voice Processing**: Advanced speech-to-text and text-to-speech functionality with configurable voice options and silence detection
- **Reasoning Visualization**: Step-by-step model reasoning visualization with the `<think>` tag for transparent AI decision processes

## Installation & Setup

Multiple installation methods are available depending on requirements:

```bash
# Standard PyPI installation
uv pip install vtai

# Zero-installation experience with uvx
export OPENAI_API_KEY='your-key-here'
uvx vtai

# Development installation
git clone https://github.com/vinhnx/VT.ai.git
cd VT.ai
uv venv
source .venv/bin/activate  # Linux/Mac
uv pip install -e ".[dev]"  # Install with development dependencies
```

### API Key Configuration

Configure API keys to enable specific model capabilities:

```bash
# Command-line configuration
vtai --api-key openai=sk-your-key-here

# Environment variable configuration
export OPENAI_API_KEY='sk-your-key-here'  # For OpenAI models
export ANTHROPIC_API_KEY='sk-ant-your-key-here'  # For Claude models
export GEMINI_API_KEY='your-key-here'  # For Gemini models
```

API keys are securely stored in `~/.config/vtai/.env` for future use.

## Usage Guide

### Interface Usage

The application provides a clean, intuitive interface with the following capabilities:

1. **Dynamic Conversations**: The semantic router automatically selects the most appropriate model for each query
2. **Image Generation**: Create images using prompts like "generate an image of..." or "draw a..."
3. **Visual Analysis**: Upload or provide URLs to analyze visual content
4. **Reasoning Visualization**: Add `<think>` to prompts to observe step-by-step reasoning
5. **Voice Interaction**: Use the microphone feature for speech input and text-to-speech output

Detailed usage instructions are available in the [Getting Started Guide](https://vinhnx.github.io/VT.ai/user/getting-started/).

## Documentation

The documentation is organized into sections designed for different user needs:

- **[User Guide](https://vinhnx.github.io/VT.ai/user/getting-started/)**: Installation, configuration, and feature documentation
- **[Developer Guide](https://vinhnx.github.io/VT.ai/developer/architecture/)**: Architecture details, extension points, and implementation information
- **[API Reference](https://vinhnx.github.io/VT.ai/api/)**: Comprehensive API documentation for programmatic usage

## Implementation Options

VT.ai offers two distinct implementations:

- **Python Implementation**: Full-featured reference implementation with complete support for all capabilities
- **Rust Implementation**: High-performance alternative with optimized memory usage and native compiled speed

The [implementation documentation](https://vinhnx.github.io/VT.ai/user/getting-started/#implementation-options) provides a detailed comparison of both options.

## Supported Models

| Category       | Models                                                |
|----------------|----------------------------------------------------- |
| **Chat**       | GPT-o1, GPT-o3 Mini, GPT-4o, Claude 3.5/3.7, Gemini 2.0/2.5  |
| **Vision**     | GPT-4o, Gemini 1.5 Pro/Flash, Claude 3, Llama3.2 Vision    |
| **Image Gen**  | GPT-Image-1 with custom parameters                   |
| **TTS**        | GPT-4o mini TTS, TTS-1, TTS-1-HD                     |
| **Local**      | Llama3, Mistral, DeepSeek R1 (1.5B to 70B via Ollama) |

The [Models Documentation](https://vinhnx.github.io/VT.ai/user/models/) provides detailed information about model-specific capabilities and configuration options.

## Technical Architecture

VT.ai leverages several open-source projects to deliver its functionality:

- **[Chainlit](https://chainlit.io)**: Modern chat interface framework
- **[LiteLLM](https://docs.litellm.ai)**: Unified model abstraction layer
- **[SemanticRouter](https://github.com/aurelio-labs/semantic-router)**: Intent classification system
- **[FastEmbed](https://github.com/qdrant/fastembed)**: Efficient embedding generation
- **[Tavily](https://tavily.com)**: Web search capabilities

The application architecture follows a clean, modular design:

- **Entry Point**: `vtai/app.py` - Main application logic
- **Routing Layer**: `vtai/router/` - Semantic classification system
- **Assistants**: `vtai/assistants/` - Specialized handlers for different query types
- **Tools**: `vtai/tools/` - Web search, file operations, and other integrations

## Contributing

Contributions to VT.ai are welcome. The project accepts various types of contributions:

- **Bug Reports**: Submit detailed GitHub issues for any bugs encountered
- **Feature Requests**: Propose new functionality through GitHub issues
- **Pull Requests**: Submit code improvements and bug fixes
- **Documentation**: Enhance documentation or add examples
- **Feedback**: Share user experiences to help improve the project

### Development Setup

Follow these steps to set up a local development environment:

#### Prerequisites
- Python 3.11 or higher
- [uv](https://docs.astral.sh/uv/) package manager (recommended) or pip
- Git

#### Step-by-step Setup

1. **Clone the repository**
   ```bash
   git clone https://github.com/vinhnx/VT.ai.git
   cd VT.ai
   ```

2. **Set up Python virtual environment**
   ```bash
   # Using uv (recommended)
   uv venv
   
   # Or using standard Python venv
   python -m venv .venv
   ```

3. **Activate the virtual environment**
   ```bash
   # On macOS/Linux
   source .venv/bin/activate
   
   # On Windows
   .venv\Scripts\activate
   ```

4. **Install development dependencies**
   ```bash
   # Install the package in editable mode with development dependencies
   uv pip install -e ".[dev]"
   
   # Or if using pip
   pip install -e ".[dev]"
   ```

5. **Set up environment variables**
   Copy the `.env.example` file to create your own `.env` file:
   ```bash
   cp .env.example .env
   ```
   
   Then edit `.env` to add your API keys:
   ```bash
   # Edit the .env file with your preferred editor
   nano .env
   # or
   code .env  # if using VS Code
   ```

6. **Run the application in development mode**
   ```bash
   # Using chainlit (recommended for development)
   chainlit run vtai/app

   # The application will be available at http://localhost:8000
   ```

7. **Run tests to verify your setup**
   ```bash
   # Run all tests
   pytest

   # Run tests with coverage
   pytest --cov=vtai

   # Run specific test categories
   pytest tests/unit/
   pytest tests/integration/
   ```

#### All-in-One Development Run

For convenience, you can use the `run_app.py` script which provides an all-in-one solution for running the application:

```bash
# Direct Python execution (will initialize but not start server)
python run_app.py

# With chainlit for full interactive development
chainlit run run_app.py -w

# Or simply use the main app module
chainlit run vtai/app
```

The `run_app.py` script serves as a wrapper that:
- Sets up the proper Python path
- Initializes the application with all necessary components
- Provides a single entry point for development
- Handles environment setup automatically

#### Alternative Development Setup (using pip)
If you prefer to use pip instead of uv:

```bash
# Clone and navigate to the project
git clone https://github.com/vinhnx/VT.ai.git
cd VT.ai

# Create and activate virtual environment
python -m venv .venv
source .venv/bin/activate  # On macOS/Linux
# .venv\Scripts\activate  # On Windows

# Install in development mode
pip install -e ".[dev]"

# Run the application
chainlit run vtai/app
```

#### Development Commands

Common commands you'll use during development:

- `chainlit run vtai/app` - Run the development server
- `pytest` - Run all tests
- `pytest -x` - Run tests and stop on first failure
- `pytest --cov=vtai` - Run tests with coverage report
- `ruff check .` - Check code for linting issues
- `ruff format .` - Format code according to project standards
- `uv pip install -e ".[dev]"` - Reinstall after dependency changes

#### Troubleshooting Common Issues

**Issue: ModuleNotFoundError when running the application**
- Solution: Make sure you've activated your virtual environment and installed the package in editable mode:
  ```bash
  source .venv/bin/activate
  pip install -e .
  ```

**Issue: Permission denied when creating virtual environment**
- Solution: Make sure you have write permissions in the project directory:
  ```bash
  chmod 755 .
  uv venv
  ```

**Issue: Chainlit not found**
- Solution: Install chainlit separately or make sure you've installed all dependencies:
  ```bash
  pip install chainlit
  # or
  pip install -e ".[dev]"
  ```

**Issue: API keys not being recognized**
- Solution: Verify your `.env` file is in the correct location and contains properly formatted keys:
  ```bash
  # Check if .env file exists in project root
  ls -la .env
  
  # Verify content format
  cat .env
  # Should contain: OPENAI_API_KEY=your_actual_key_here
  ```

**Issue: Application fails to start with port binding errors**
- Solution: Check if another process is using the default port:
  ```bash
  # Find processes using port 8000
  lsof -ti:8000
  # Kill the process if needed
  kill $(lsof -ti:8000)
  ```

**Issue: Slow startup times**
- Solution: You can enable fast startup mode by setting an environment variable:
  ```bash
  export VT_FAST_START=1
  chainlit run vtai/app
  ```

**Issue: Dependency conflicts**
- Solution: Create a fresh virtual environment and reinstall dependencies:
  ```bash
  rm -rf .venv
  python -m venv .venv
  source .venv/bin/activate
  pip install -e ".[dev]"
  ```

## Testing and Quality

Quality is maintained through comprehensive testing:

```bash
# Run the test suite
pytest

# Run with coverage reporting
pytest --cov=vtai

# Run specific test categories
pytest tests/unit/
pytest tests/integration/
```

## License

VT.ai is available under the MIT License - See [LICENSE](LICENSE) for details.
