Metadata-Version: 2.3
Name: chatnificent
Version: 0.0.13
Summary: LLM chat app framework - Minimally complete. Maximally hackable
Keywords: llm,chatbot,chat,ai,web-framework,openai,anthropic,conversational-ai
Author: Elias Dabbas
Author-email: Elias Dabbas <eliasdabbas@gmail.com>
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Web Environment
Classifier: Framework :: Dash
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Communications :: Chat
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Classifier: Topic :: Internet :: WWW/HTTP :: WSGI :: Application
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: User Interfaces
Classifier: Typing :: Typed
Requires-Dist: anthropic>=0.30.0 ; extra == 'anthropic'
Requires-Dist: dash>=3.0.0 ; extra == 'dash'
Requires-Dist: dash-bootstrap-components>=2.0.0 ; extra == 'dash'
Requires-Dist: chatnificent[dash,openai] ; extra == 'default'
Requires-Dist: chatnificent[dash,mantine,openai,anthropic,gemini,ollama] ; extra == 'dev'
Requires-Dist: pytest ; extra == 'dev'
Requires-Dist: pytest-mock ; extra == 'dev'
Requires-Dist: google-genai ; extra == 'gemini'
Requires-Dist: chatnificent[dash] ; extra == 'mantine'
Requires-Dist: dash-mantine-components>=1.1.0 ; extra == 'mantine'
Requires-Dist: dash-iconify==0.1.2 ; extra == 'mantine'
Requires-Dist: ollama ; extra == 'ollama'
Requires-Dist: openai>=1.0.0 ; extra == 'openai'
Requires-Python: >=3.9
Project-URL: Bug Tracker, https://github.com/eliasdabbas/chatnificent/issues
Project-URL: Homepage, https://github.com/eliasdabbas/chatnificent
Project-URL: Repository, https://github.com/eliasdabbas/chatnificent
Provides-Extra: anthropic
Provides-Extra: dash
Provides-Extra: default
Provides-Extra: dev
Provides-Extra: gemini
Provides-Extra: mantine
Provides-Extra: ollama
Provides-Extra: openai
Description-Content-Type: text/markdown


<img src="chatnificent_logo.png" width="350">

# Chatnificent

**LLM chat app framework. Minimally complete. Maximally hackable.**

[![PyPI version](https://img.shields.io/pypi/v/chatnificent.svg)](https://pypi.python.org/pypi/chatnificent) [![DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/eliasdabbas/chatnificent)

Pre-built chat UIs give you a working app but almost no way to customize it. Building from scratch gives you full control but means wiring up a UI, LLM client, message store, streaming, auth, and tool calling yourself.

Chatnificent is a Python framework where each of those concerns is an independent, swappable component. You get a working app immediately. When you need to change something — the LLM provider, the database, the entire UI — you swap one component, instead of rewriting the whole app.

## Quickstart

```bash
pip install chatnificent
```

```python
import chatnificent as chat

app = chat.Chatnificent()
app.run()  # http://127.0.0.1:8050
```

No API keys, no extras, no configuration. You get a working chat UI with the built-in Echo LLM, a stdlib HTTP server, and an HTML/JS frontend — all with zero dependencies.

## One Install Away from Real LLM Responses

```bash
pip install openai
export OPENAI_API_KEY="sk-..."
```

Run the same code. Chatnificent auto-detects the installed OpenAI SDK and your API key — no code change needed.

## Swap Anything

Every component is a pillar you can swap independently:

```python
import chatnificent as chat

# Different LLM providers
app = chat.Chatnificent(llm=chat.llm.Anthropic())   # pip install anthropic
app = chat.Chatnificent(llm=chat.llm.Gemini())       # pip install google-genai
app = chat.Chatnificent(llm=chat.llm.Ollama())       # pip install ollama (local)

# Persistent storage
app = chat.Chatnificent(store=chat.store.SQLite(db_path="chats.db"))
app = chat.Chatnificent(store=chat.store.File(directory="./conversations"))

# Mix and match
app = chat.Chatnificent(
    llm=chat.llm.Anthropic(),
    store=chat.store.SQLite(db_path="conversations.db"),
    layout=chat.layout.Bootstrap(),  # Requires: pip install "chatnificent[dash]"
)
```

## Streaming by Default

All LLM providers stream by default — token-by-token delivery via Server-Sent Events. Opt out with `stream=False`:

```python
app = chat.Chatnificent(llm=chat.llm.OpenAI(stream=False))
```

## The Architecture: 9 Pillars

Every major function is handled by an independent pillar with an abstract interface:

| Pillar | Purpose | Default | Implementations |
| :--- | :--- | :--- | :--- |
| **Server** | HTTP transport | `DevServer` (stdlib) | DevServer, DashServer |
| **Layout** | UI rendering | `DefaultLayout` (HTML/JS) | DefaultLayout, Bootstrap, Mantine, Minimal |
| **LLM** | LLM API calls | `OpenAI` / `Echo` | OpenAI, Anthropic, Gemini, OpenRouter, DeepSeek, Ollama, Echo |
| **Store** | Persistence | `InMemory` | InMemory, File, SQLite |
| **Engine** | Orchestration | `Orchestrator` | Orchestrator |
| **Auth** | User identification | `Anonymous` | Anonymous, SingleUser |
| **Tools** | Function calling | `NoTool` | PythonTool, NoTool |
| **Retrieval** | RAG / context | `NoRetrieval` | NoRetrieval |
| **URL** | Route parsing | `PathBased` | PathBased, QueryParams |

Dash-based layouts (Bootstrap, Mantine, Minimal) require `pip install "chatnificent[dash]"` and the `DashServer`.

## Customize the Engine

The `Orchestrator` manages the full request lifecycle: conversation resolution, RAG retrieval, the agentic tool-calling loop, and persistence. Override hooks (for monitoring) and seams (for logic):

```python
import chatnificent as chat
from typing import Any, Optional

class CustomEngine(chat.engine.Orchestrator):

    def _after_llm_call(self, llm_response: Any) -> None:
        tokens = getattr(llm_response, 'usage', 'N/A')
        print(f"Tokens: {tokens}")

    def _prepare_llm_payload(self, conversation, retrieval_context: Optional[str]):
        payload = super()._prepare_llm_payload(conversation, retrieval_context)
        if not any(m['role'] == 'system' for m in payload):
            payload.insert(0, {"role": "system", "content": "Be concise."})
        return payload

app = chat.Chatnificent(engine=CustomEngine())
```

## Build Your Own Pillars

Implement the abstract interface and inject it:

```python
import chatnificent as chat
from chatnificent.models import Conversation

class MongoStore(chat.store.Store):
    def save_conversation(self, user_id, conversation): ...
    def load_conversation(self, user_id, convo_id): ...
    def list_conversations(self, user_id): ...
    def get_next_conversation_id(self, user_id): ...

app = chat.Chatnificent(store=MongoStore())
```

Every pillar works the same way: subclass the ABC, implement the required methods, pass it in.
