Metadata-Version: 2.4
Name: chatassist
Version: 0.2.0
Summary: A provider-agnostic Python library for chatting with LLMs: OpenAI, OpenRouter, local Ollama, or any OpenAI-compatible endpoint.
Author-email: Daryoush Alipour <ai.tirotir@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/tirotir-ir/chatassist
Project-URL: BugTracker, https://github.com/tirotir-ir/chatassist/issues
Project-URL: Documentation, https://github.com/tirotir-ir/chatassist/wiki
Keywords: chatgpt,openai,openrouter,ollama,llm,api,assistant
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.20
Provides-Extra: gui
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Dynamic: license-file

# ChatAssist

[![tests](https://github.com/tirotir-ir/chatassist/actions/workflows/tests.yml/badge.svg)](https://github.com/tirotir-ir/chatassist/actions/workflows/tests.yml)
[![PyPI](https://img.shields.io/pypi/v/chatassist.svg)](https://pypi.org/project/chatassist/)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

An advanced, **provider-agnostic** Python library for chatting with LLMs.
Works with OpenAI, OpenRouter, a local Ollama server, or any endpoint that
speaks the OpenAI-compatible `/chat/completions` format.

Made by [تیروتیر — tirotir.ir](https://tirotir.ir).

## What's new in 0.2.0

- **Multi-provider support**: `provider="openai"`, `"openrouter"`, `"ollama"`, or a fully custom `base_url`
- **Streaming responses**: `stream_message()` yields text as it's generated
- **Multi-turn context**: pass `history=` to keep a real conversation going, not just single-shot messages
- **System prompts**: set a persona/instructions once, reused across turns
- **API key optional**: not required for local Ollama
- **Env var support**: `CHATASSIST_API_KEY` or `OPENAI_API_KEY`
- **Fixed CLI packaging**: `chatassist-cli` now actually installs as a command (this was broken in 0.1.0)
- **Interactive CLI chat mode**: just run `chatassist-cli` with no message for a REPL
- **Markdown export** for conversations, alongside JSON
- `ChatGPTAPI` is kept as a backward-compatible alias for existing code

## Installation

```bash
pip install chatassist
```

## Quick start

### OpenAI

```python
from chatassist import LLMClient

client = LLMClient(provider="openai", api_key="sk-...")
print(client.send_message("Hello!"))
```

### OpenRouter

```python
client = LLMClient(
    provider="openrouter",
    api_key="sk-or-...",
    model="anthropic/claude-3.5-sonnet",
)
print(client.send_message("Hello!"))
```

### Local Ollama (no API key needed)

```python
client = LLMClient(provider="ollama", model="llama3.2")
print(client.send_message("Hello!"))
```

### Any custom OpenAI-compatible endpoint

```python
client = LLMClient(
    base_url="https://my-llm-gateway.internal/v1/chat/completions",
    api_key="...",
    model="my-model",
)
```

## Streaming

```python
for chunk in client.stream_message("Write a short poem about the sea."):
    print(chunk, end="", flush=True)
```

## Multi-turn conversations

```python
from chatassist import LLMClient, Conversation

client = LLMClient(provider="ollama", model="llama3.2", system_prompt="You are terse.")
conversation = Conversation(system_prompt="You are terse.")

for user_msg in ["Hi!", "What's 2+2?", "And times 10?"]:
    reply = client.send_message(user_msg, history=conversation.as_api_messages())
    conversation.add_message("user", user_msg)
    conversation.add_message("assistant", reply)
    print(reply)

conversation.save_to_file("conversation.json")
conversation.export_markdown("conversation.md")
```

## Command-line interface

```bash
# One-shot message
chatassist-cli "What is the capital of France?" --provider openai --api-key sk-...

# OpenRouter with a specific model
chatassist-cli "Summarize the plot of Dune" --provider openrouter --api-key sk-or-... --model anthropic/claude-3.5-sonnet

# Local Ollama, streamed
chatassist-cli "Tell me a joke" --provider ollama --model llama3.2 --stream

# Interactive REPL (omit the message)
chatassist-cli --provider ollama --model llama3.2

# Export the session
chatassist-cli "Hello" --export chat.json --export-markdown chat.md
```

## Graphical User Interface

```bash
python -m chatassist.gui
```

On launch you'll get a small setup dialog to pick a provider, model, and
API key (skip the key for Ollama) before the chat window opens.

## 20 examples, simple → advanced

The [`examples/`](examples/) directory is a full lesson plan: 20
standalone, runnable scripts going from a one-line "hello world" up to
streaming multi-turn chat, provider fallback, side-by-side model
comparison, and a small FastAPI web service. See
[`examples/README.md`](examples/README.md) for the full index (in
Persian, with English code/comments).

```bash
git clone https://github.com/tirotir-ir/chatassist.git
cd chatassist
pip install -e .
export OPENAI_API_KEY=sk-...
python examples/01_hello_world_openai.py
```

## Development

```bash
pip install -e ".[dev]"
pytest tests/ -v   # runs fully offline, no API key needed
```

## Configuration reference

| Parameter | Description |
|---|---|
| `provider` | `"openai"`, `"openrouter"`, or `"ollama"` preset |
| `base_url` | Custom endpoint, overrides the provider preset |
| `model` | Model name; defaults to a sensible per-provider default |
| `api_key` | API key; falls back to `CHATASSIST_API_KEY` / `OPENAI_API_KEY` env vars, then `api_key.txt` |
| `system_prompt` | Optional system message sent with every request |
| `temperature`, `top_p`, `max_tokens` | Standard sampling controls |
| `proxies` | Optional `requests`-style proxy dict |

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md).

## License

MIT License — see [LICENSE](LICENSE).

---
ساخته و نگهداری‌شده توسط [تیروتیر](https://tirotir.ir)
