# ArielAI

**Build chatbots in minutes using open-source models and Gradio.**

ArielAI wraps HuggingFace Transformers, Ollama, and the HuggingFace Inference API into a single, clean interface — so you go from zero to a working chatbot in just a few lines of code.

---

## Installation

```bash
pip install arielai
```

For local model inference with PyTorch:
```bash
pip install arielai[torch]
```

For Ollama support:
```bash
pip install arielai[ollama]
```

For HuggingFace Inference API (no GPU required):
```bash
pip install arielai[inference]
```

---

## Quick Start

### One-liner

```python
import arielai
arielai.launch("microsoft/DialoGPT-medium")
```

### Basic usage

```python
from arielai import Chatbot

bot = Chatbot(
    model="microsoft/DialoGPT-medium",
    title="My Chatbot",
)
bot.launch()
```

### Using a preset

```python
from arielai import Chatbot

bot = Chatbot.from_preset("zephyr")
bot.launch()
```

---

## Backends

ArielAI supports three backends:

| Backend | `backend=` | Description |
|---|---|---|
| HuggingFace Transformers | `"transformers"` | Download and run models locally |
| Ollama | `"ollama"` | Local models via [Ollama](https://ollama.ai) |
| HF Inference API | `"inference"` | Cloud-hosted, no GPU needed |

### Transformers (default)

```python
bot = Chatbot(
    model="HuggingFaceH4/zephyr-7b-beta",
    backend="transformers",
    system_prompt="You are a helpful assistant.",
)
bot.launch()
```

### Ollama

```bash
# First: install Ollama and pull a model
ollama pull llama3
```

```python
bot = Chatbot(model="llama3", backend="ollama")
bot.launch()
```

### HuggingFace Inference API

```python
bot = Chatbot(
    model="HuggingFaceH4/zephyr-7b-beta",
    backend="inference",
    hf_token="hf_...",  # Optional for public models
)
bot.launch()
```

---

## Presets

ArielAI ships with ready-to-use model presets:

| Preset | Model | Backend |
|---|---|---|
| `tiny` | `facebook/blenderbot-400M-distill` | transformers |
| `dialogue` | `microsoft/DialoGPT-medium` | transformers |
| `zephyr` | `HuggingFaceH4/zephyr-7b-beta` | transformers |
| `mistral` | `mistralai/Mistral-7B-Instruct-v0.2` | transformers |
| `ollama-llama3` | `llama3` | ollama |
| `ollama-mistral` | `mistral` | ollama |
| `ollama-gemma` | `gemma` | ollama |

```python
from arielai import list_presets

for name, description in list_presets().items():
    print(f"{name}: {description}")
```

---

## Full API Reference

### `Chatbot()`

| Parameter | Type | Default | Description |
|---|---|---|---|
| `model` | `str` | `"microsoft/DialoGPT-medium"` | HuggingFace model ID or Ollama model name |
| `backend` | `str` | `"transformers"` | `"transformers"`, `"ollama"`, or `"inference"` |
| `title` | `str` | `"ArielAI Chatbot"` | Chatbot window title |
| `description` | `str` | `""` | Description shown below the title |
| `system_prompt` | `str` | `""` | System instruction for the model |
| `placeholder` | `str` | `"Ask me anything..."` | Input box placeholder |
| `max_new_tokens` | `int` | `512` | Max tokens per response |
| `temperature` | `float` | `0.7` | Sampling temperature |
| `examples` | `list[str]` | `None` | Example messages shown in the UI |
| `theme` | `str` | `"soft"` | Gradio theme (`"soft"`, `"default"`, `"monochrome"`, `"glass"`) |
| `streaming` | `bool` | `True` | Stream responses token-by-token |
| `device` | `str` | `None` | Device for transformers (`"cpu"`, `"cuda"`, `"mps"`) |
| `load_in_8bit` | `bool` | `False` | 8-bit quantization (requires bitsandbytes) |
| `load_in_4bit` | `bool` | `False` | 4-bit quantization (requires bitsandbytes) |
| `hf_token` | `str` | `None` | HuggingFace API token |
| `ollama_host` | `str` | `"http://localhost:11434"` | Ollama server URL |

### `Chatbot.launch()`

| Parameter | Type | Default | Description |
|---|---|---|---|
| `share` | `bool` | `False` | Create a public Gradio share link |
| `server_name` | `str` | `"0.0.0.0"` | Bind address |
| `server_port` | `int` | `None` | Port (auto-selected if None) |
| `inbrowser` | `bool` | `True` | Open browser automatically |

### `Chatbot.build()`

Returns the `gr.ChatInterface` object without launching. Use this to embed ArielAI in an existing Gradio app or deploy to Hugging Face Spaces.

```python
demo = bot.build()
demo.launch(...)
```

---

## ChatUI — Polished Frontend

`ChatUI` wraps your chatbot in a branded, styled interface with a custom header, color themes, dark mode, and a footer. Still powered by Gradio, zero extra dependencies.

```python
from arielai import Chatbot, ChatUI

bot = Chatbot(
    model="microsoft/DialoGPT-medium",
    streaming=True,
    examples=["Tell me something interesting.", "Write a short poem."],
)

ui = ChatUI(
    bot,
    brand_name="My AI Assistant",
    tagline="Powered by open-source AI",
    accent="indigo",        # color theme
    dark_mode=False,        # or True for dark
    footer_text="Built with ArielAI",
)

ui.launch()
```

### ChatUI options

| Parameter | Type | Default | Description |
|---|---|---|---|
| `brand_name` | `str` | `"ArielAI"` | Name shown in the header |
| `tagline` | `str` | `"Powered by open-source AI"` | Subtitle below the brand name |
| `brand_logo` | `str` | `None` | Path or URL to a logo image |
| `accent` | `str` | `"indigo"` | Color accent (see below) |
| `dark_mode` | `bool` | `False` | Dark color scheme |
| `show_footer` | `bool` | `True` | Show a footer below the chat |
| `footer_text` | `str` | `"Built with ArielAI"` | Footer label |
| `footer_link` | `str` | ArielAI GitHub | URL the footer text links to |
| `extra_css` | `str` | `""` | Extra raw CSS to inject |

### Available accents

`indigo` · `emerald` · `rose` · `amber` · `blue` · `violet` · `cyan` · `slate`

Or any hex color: `accent="#ff6b6b"`

```python
from arielai import ChatUI
print(ChatUI.list_accents())
```

---

## Advanced Usage

### Embed in an existing Gradio app

```python
import gradio as gr
from arielai import Chatbot

bot = Chatbot(model="microsoft/DialoGPT-medium")
chat_ui = bot.build()  # returns gr.ChatInterface

with gr.Blocks() as app:
    gr.Markdown("# My App")
    chat_ui.render()

app.launch()
```

### Memory-efficient models (quantization)

```python
bot = Chatbot(
    model="mistralai/Mistral-7B-Instruct-v0.2",
    load_in_4bit=True,  # Requires bitsandbytes + CUDA GPU
)
bot.launch()
```

### Custom backend

```python
from arielai import Chatbot
from arielai.backends import BaseBackend

class MyBackend(BaseBackend):
    def generate(self, message, history, **kwargs):
        return f"You said: {message}"

bot = Chatbot(backend_instance=MyBackend())
bot.launch()
```

---

## Running Tests

```bash
pip install arielai[dev]
pytest
```

---

## Contributing

Contributions are welcome! Please open an issue or pull request on GitHub.

---

## License

MIT © ArielAI Contributors
