{"id":31049362,"url":"https://github.com/eliasdabbas/chatnificent","last_synced_at":"2025-09-14T21:59:56.303Z","repository":{"id":313168537,"uuid":"1050305894","full_name":"eliasdabbas/chatnificent","owner":"eliasdabbas","description":"Chatnificent: LLM chat app framework – Minimally complete. Maximally hackable.","archived":false,"fork":false,"pushed_at":"2025-09-13T07:33:18.000Z","size":168,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-13T09:41:13.172Z","etag":null,"topics":["ai","anthropic","chatbot","flask","gemini","generative-ai","llm","openai","plotly-dash","rag-chatbot"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/eliasdabbas.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-04T08:42:38.000Z","updated_at":"2025-09-13T07:33:21.000Z","dependencies_parsed_at":"2025-09-04T10:35:04.473Z","dependency_job_id":"f5e4e378-55e5-4eac-a5f4-c98d391409a8","html_url":"https://github.com/eliasdabbas/chatnificent","commit_stats":null,"previous_names":["eliasdabbas/chatnificent"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/eliasdabbas/chatnificent","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eliasdabbas%2Fchatnificent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eliasdabbas%2Fchatnificent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eliasdabbas%2Fchatnificent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eliasdabbas%2Fchatnificent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/eliasdabbas","download_url":"https://codeload.github.com/eliasdabbas/chatnificent/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eliasdabbas%2Fchatnificent/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":275174446,"owners_count":25418063,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-14T02:00:10.474Z","response_time":75,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","anthropic","chatbot","flask","gemini","generative-ai","llm","openai","plotly-dash","rag-chatbot"],"created_at":"2025-09-14T21:59:53.036Z","updated_at":"2025-09-14T21:59:56.294Z","avatar_url":"https://github.com/eliasdabbas.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n\u003cimg src=\"chatnificent_logo.png\" width=\"350\"\u003e\n\n# 🗯️ Chatnificent\n\n### LLM chat app framework\n### Minimally complete. Maximally hackable.\n\nBuild production-ready, full-stack chat applications in minutes. Customize everything in hours.\n\n\nChatnificent is a Python framework built on [Plotly's Dash](https://dash.plotly.com/) designed to get your LLM chat applications up and running instantly, while providing a robust, decoupled architecture for unlimited customization.\n\nStop wrestling with UI components, state management, and backend integrations. Start building magnificent chat apps.\n\n\n[![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)\n\n## The Ethos\n\nFrameworks should get out of your way.\n\n  * **Minimally Complete:** Out of the box, `Chatnificent` provides a fully functional, stateful, multi-user chat application with sensible defaults.\n  * **Maximally Hackable:** Every core pillar—the UI, the LLM provider, the database, the authentication, the RAG pipeline, and the core orchestration—is  swappable. Customize or replace any part without fighting the framework.\n\n## Features\n\n  * **LLM Agnostic:** Built-in support for OpenAI, Anthropic, Gemini, Ollama, OpenRouter, DeepSeek, and any other LLM API.\n  * **Flexible UI:** Default Bootstrap layout, with built-in Mantine and Minimal (pure HTML) layouts. Easily customizable with any Dash components.\n  * **Pluggable Storage:** InMemory, File-system, and SQLite included. Easily extendable to Redis, Postgres, etc.\n  * **Agentic Engine:** The core engine manages multi-turn conversations and standardized tool calling across providers.\n  * **Auth Ready:** Abstracted authentication layer for easy integration. No-login anonymous user auth enabled by default.\n  * **RTL Support:** Automatic detection and rendering of Right-to-Left languages.\n  * **Dash Native:** Leverage the full power of Plotly's Dash to integrate complex data visualizations and analytics.\n\n## Installation\n\nTo get started quickly with the default UI (Bootstrap) and the default LLM provider (OpenAI):\n\n```bash\npip install \"chatnificent[default]\"\n\nexport OPENAI_API_KEY=\"YOUR_API_KEY\"\n```\n\nFor a minimal installation (no UI libraries or LLM SDKs included):\n\n```bash\npip install chatnificent\n```\n\n\n\n## Quickstart: Hello World (3 Lines)\n\nThis is a complete, working chat application.\n\nCreate a file `app.py`:\n\n```python\nfrom chatnificent import Chatnificent\n\napp = Chatnificent()\n\nif __name__ == \"__main__\":\n    app.run(debug=True)\n```\n\nRun it:\n\n```bash\npython app.py\n```\n\nOpen your browser to [`http://127.0.0.1:8050`](http://127.0.0.1:8050). That's it. You have a fully functional chat UI with conversation history, mobile responsiveness, and URL-based session management.\n\n## The Pillars of Hackability\n\nChatnificent's architecture is built around extensible Pillars. Every major function is handled by a dedicated component adhering to a strict interface.\n\n| Pillar | Description | Defaults | Included Implementations |\n| :--- | :--- | :--- | :--- |\n| **`LLM`** | The brain (API calls, parsing). | `OpenAI` (or `Echo`) | OpenAI, Anthropic, Gemini, OpenRouter, DeepSeek, Ollama, Echo |\n| **`Layout`** | The look and feel (UI components). | `Bootstrap` (or `Minimal`) | Bootstrap, Mantine, Minimal (HTML) |\n| **`Store`** | The memory (Persistence). | `InMemory` | InMemory, File, SQLite |\n| **`Auth`** | The gatekeeper (User identification). | `Anonymous` | Anonymous, SingleUser |\n| **`Engine`** | The orchestrator (Request lifecycle). | `Synchronous` | Synchronous |\n| **`Tools`** | Tool/function calling capabilities. | `NoTool` | PythonTool, NoTool |\n| **`Retrieval`** | RAG knowledge retrieval. | `NoRetrieval` | NoRetrieval |\n| **`URL`** | URL parsing and routing. | `PathBased` | PathBased, QueryParams |\n\nYou customize the app by injecting the implementations you need during initialization:\n\n```python\nfrom chatnificent import Chatnificent\nimport chatnificent as chat\n\napp = Chatnificent(\n    llm=chat.llm.Anthropic(),\n    store=chat.store.SQLite(db_path=\"conversations.db\"),\n    layout=chat.layout.Mantine()\n)\n```\n\n## Progressive Power: Swapping the Pillars\n\nLet's evolve the \"Hello World\" example by swapping pillars.\n\n### Level 1: Swapping the LLM 🧠\n\nWant to use Anthropic's Claude 3.5 Sonnet? Just swap the `llm` pillar.\n\n*(Requires `pip install anthropic` and setting `ANTHROPIC_API_KEY`)*\n\n```python\nfrom chatnificent import Chatnificent\nimport chatnificent as chat\n\n\napp = Chatnificent(\n    llm=chat.llm.Anthropic(model=\"claude-3-5-sonnet-20240620\")\n)\n\n# Or try Gemini: app = Chatnificent(llm=chat.llm.Gemini())\n# Or local Ollama: app = Chatnificent(llm=chat.llm.Ollama(model=\"llama3.1\"))\n```\n\nChatnificent handles the translation of message formats and tool-calling protocols automatically.\n\n### Level 2: Adding Persistent Storage\n\nThe default `InMemory` store is ephemeral. Let's use `SQLite` for persistence.\n\n```python\nfrom chatnificent import Chatnificent\nimport chatnificent as chat\n\napp = Chatnificent(\n    store=store.SQLite(db_path=\"conversations.db\")\n)\n# Or use the filesystem: store=chat.store.File(base_dir=\"./chat_data\")\n```\n\nConversations are now persisted across server restarts, and the sidebar automatically loads your history.\n\n### Level 3: Changing the Look and Feel 🎨\n\nDon't want Bootstrap? Let's try the Mantine layout.\n\n*(Requires `pip install dash-mantine-components`)*\n\n```python\nfrom chatnificent import Chatnificent\nimport chatnificent as chat\n\napp = Chatnificent(layout=chat.layout.Mantine())\n\n# Or use the barebones HTML layout: layout=layout.Minimal()\n```\n\nWant a completely custom design? Implement the `layout.Layout` abstract base class. The framework ensures your custom layout integrates seamlessly, provided you include the required component IDs (e.g., `input_textarea`, `messages_container`, etc.).\n\n### Level 4: Custom Authentication\n\nThe default `Anonymous` auth isolates users by random user ID. You can easily implement custom logic.\n\n```python\nfrom chatnificent import Chatnificent, auth\n\nclass HeaderAuth(auth.Auth):\n    def get_current_user_id(self, **kwargs) -\u003e str:\n        from flask import request\n        # Identify user based on a header (e.g., provided by an auth proxy)\n        return request.headers.get(\"X-User-Id\", \"unknown_user\")\n\napp = Chatnificent(auth=HeaderAuth())\n```\n\n### Level 5: The Engine (Advanced Orchestration)\n\nThe `Engine` orchestrates the entire request lifecycle: resolving the conversation, RAG retrieval, the agentic loop (Tools + LLM calls), and persistence.\n\nThe default `Synchronous` engine provides \"hooks\" (empty methods called at specific points) and \"seams\" (core logic methods) that you can override to deeply customize behavior without rewriting the core logic.\n\n```python\nfrom chatnificent import Chatnificent\nimport chatnificent as chat\nfrom typing import Any, Optional\n\n# Create a custom engine by inheriting from the default\nclass CustomEngine(chat.engine.Synchronous):\n\n    # 1. Override a HOOK to add monitoring/logging\n    def _after_llm_call(self, llm_response: Any) -\u003e None:\n        # Example: Extract token usage if the LLM response object has a 'usage' attribute\n        tokens = getattr(llm_response, 'usage', 'N/A')\n        print(f\"[MONITORING] LLM call complete. Tokens: {tokens}\")\n\n    # 2. Override a SEAM to modify core logic (e.g., prompt engineering)\n    def _prepare_llm_payload(self, conversation, retrieval_context: Optional[str]):\n        # Get the default payload (which already includes the context if present)\n        payload = super()._prepare_llm_payload(conversation, retrieval_context)\n\n        # Inject a custom system prompt if none exists\n        if not any(m['role'] == 'system' for m in payload):\n            payload.insert(0, {\"role\": \"system\", \"content\": \"Be brief and professional.\"})\n        return payload\n\n\n# Initialize the app, passing the engine instance.\n# Chatnificent's constructor will automatically bind the app reference to the engine.\napp = Chatnificent(engine=CustomEngine())\n```\n\n## Architecture Overview\n\nHow the pillars work together during a request:\n\n1.  **User Input**: The user submits a message via the `Layout`.\n2.  **Callback Trigger**: A Dash callback delegates the input to the `Engine`.\n3.  **Context Resolution**: The `Engine` uses `Auth`, `URL`, and `Store` to identify the user and load the conversation history.\n4.  **Agentic Loop**:\n      * The `Engine` calls `Retrieval` to gather context (RAG).\n      * The `Engine` sends the history and context to the `LLM`.\n      * If the `LLM` requests a tool call, the `Engine` executes it via `Tools` and loops back.\n      * If the `LLM` returns a final response, the loop exits.\n5.  **Persistence**: The `Engine` saves the updated conversation via the `Store`.\n6.  **Rendering**: The `Engine` formats the messages using the `Layout` and updates the client UI.\n\n## Building Your Own Pillars\n\nThe ultimate hackability comes from implementing your own pillars. Want to use MongoDB? Just implement the `store.Store` interface.\n\n### Example: Custom Storage Implementation\n\n```python\nfrom chatnificent import Chatnificent\nimport chatnificent as chat\nfrom typing import Optional, List\n\nclass MongoDBStore(chat.store.Store):\n    def __init__(self, connection_string):\n        # Initialize MongoDB client...\n        print(f\"Connecting to MongoDB at {connection_string}...\")\n        pass\n\n    def load_conversation(self, user_id: str, convo_id: str) -\u003e Optional[Conversation]:\n        # Implement loading logic...\n        return None\n\n    # Implement the other required methods...\n    def save_conversation(self, user_id: str, conversation: Conversation):\n        pass\n    def list_conversations(self, user_id: str) -\u003e List[str]:\n        return []\n    def get_next_conversation_id(self, user_id: str) -\u003e str:\n        return \"1\"\n\n# Use your custom implementation\n# app = Chatnificent(store=MongoDBStore(connection_string=\"mongodb://...\"))\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feliasdabbas%2Fchatnificent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Feliasdabbas%2Fchatnificent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feliasdabbas%2Fchatnificent/lists"}