Upload folder using huggingface_hub

.dockerignore

@@ -0,0 +1,9 @@
+**/__pycache__/
+.deepsource.toml
+.env
+.github/
+.idea/
+.mypy_cache/
+.ruff_cache/
+.venv/
+.vscode/

.gitattributes

@@ -1,35 +1,132 @@
-*.7z filter=lfs diff=lfs merge=lfs -text
-*.arrow filter=lfs diff=lfs merge=lfs -text
-*.bin filter=lfs diff=lfs merge=lfs -text
-*.bz2 filter=lfs diff=lfs merge=lfs -text
-*.ckpt filter=lfs diff=lfs merge=lfs -text
-*.ftz filter=lfs diff=lfs merge=lfs -text
-*.gz filter=lfs diff=lfs merge=lfs -text
-*.h5 filter=lfs diff=lfs merge=lfs -text
-*.joblib filter=lfs diff=lfs merge=lfs -text
-*.lfs.* filter=lfs diff=lfs merge=lfs -text
-*.mlmodel filter=lfs diff=lfs merge=lfs -text
-*.model filter=lfs diff=lfs merge=lfs -text
-*.msgpack filter=lfs diff=lfs merge=lfs -text
-*.npy filter=lfs diff=lfs merge=lfs -text
-*.npz filter=lfs diff=lfs merge=lfs -text
-*.onnx filter=lfs diff=lfs merge=lfs -text
-*.ot filter=lfs diff=lfs merge=lfs -text
-*.parquet filter=lfs diff=lfs merge=lfs -text
-*.pb filter=lfs diff=lfs merge=lfs -text
-*.pickle filter=lfs diff=lfs merge=lfs -text
-*.pkl filter=lfs diff=lfs merge=lfs -text
-*.pt filter=lfs diff=lfs merge=lfs -text
-*.pth filter=lfs diff=lfs merge=lfs -text
-*.rar filter=lfs diff=lfs merge=lfs -text
-*.safetensors filter=lfs diff=lfs merge=lfs -text
-saved_model/**/* filter=lfs diff=lfs merge=lfs -text
-*.tar.* filter=lfs diff=lfs merge=lfs -text
-*.tar filter=lfs diff=lfs merge=lfs -text
-*.tflite filter=lfs diff=lfs merge=lfs -text
-*.tgz filter=lfs diff=lfs merge=lfs -text
-*.wasm filter=lfs diff=lfs merge=lfs -text
-*.xz filter=lfs diff=lfs merge=lfs -text
-*.zip filter=lfs diff=lfs merge=lfs -text
-*.zst filter=lfs diff=lfs merge=lfs -text
-*tfevents* filter=lfs diff=lfs merge=lfs -text
+# Apply override to all files in the directory
+*.md linguist-detectable
+
+# Basic .gitattributes for a python repo.
+
+# Source files
+# ============
+*.pxd    text diff=python
+*.py     text diff=python
+*.py3    text diff=python
+*.pyw    text diff=python
+*.pyx    text diff=python
+*.pyz    text diff=python
+*.pyi    text diff=python
+
+# Binary files
+# ============
+*.db     binary
+*.p      binary
+*.pkl    binary
+*.pickle binary
+*.pyc    binary export-ignore
+*.pyo    binary export-ignore
+*.pyd    binary
+
+# Jupyter notebook
+*.ipynb  text eol=lf
+
+# Note: .db, .p, and .pkl files are associated
+# with the python modules ``pickle``, ``dbm.*``,
+# ``shelve``, ``marshal``, ``anydbm``, & ``bsddb``
+# (among others).
+
+# Common settings that generally should always be used with your language specific settings
+
+# Auto detect text files and perform LF normalization
+*          text=auto
+
+#
+# The above will handle all files NOT found below
+#
+
+# Documents
+*.bibtex   text diff=bibtex
+*.doc      diff=astextplain
+*.DOC      diff=astextplain
+*.docx     diff=astextplain
+*.DOCX     diff=astextplain
+*.dot      diff=astextplain
+*.DOT      diff=astextplain
+*.pdf      diff=astextplain
+*.PDF      diff=astextplain
+*.rtf      diff=astextplain
+*.RTF      diff=astextplain
+*.md       text diff=markdown
+*.mdx      text diff=markdown
+*.tex      text diff=tex
+*.adoc     text
+*.textile  text
+*.mustache text
+*.csv      text eol=crlf
+*.tab      text
+*.tsv      text
+*.txt      text
+*.sql      text
+*.epub     diff=astextplain
+
+# Graphics
+*.png      binary
+*.jpg      binary
+*.jpeg     binary
+*.gif      binary
+*.tif      binary
+*.tiff     binary
+*.ico      binary
+# SVG treated as text by default.
+*.svg      text
+# If you want to treat it as binary,
+# use the following line instead.
+# *.svg    binary
+*.eps      binary
+
+# Scripts
+*.bash     text eol=lf
+*.fish     text eol=lf
+*.ksh      text eol=lf
+*.sh       text eol=lf
+*.zsh      text eol=lf
+# These are explicitly windows files and should use crlf
+*.bat      text eol=crlf
+*.cmd      text eol=crlf
+*.ps1      text eol=crlf
+
+# Serialisation
+*.json     text eol=lf
+*.toml     text eol=lf
+*.xml      text eol=lf
+*.yaml     text eol=lf
+*.yml      text eol=lf
+
+# Archives
+*.7z       binary
+*.bz       binary
+*.bz2      binary
+*.bzip2    binary
+*.gz       binary
+*.lz       binary
+*.lzma     binary
+*.rar      binary
+*.tar      binary
+*.taz      binary
+*.tbz      binary
+*.tbz2     binary
+*.tgz      binary
+*.tlz      binary
+*.txz      binary
+*.xz       binary
+*.Z        binary
+*.zip      binary
+*.zst      binary
+
+# Text files where line endings should be preserved
+*.patch    -text
+
+#
+# Exclude files from exporting
+#
+
+.gitattributes export-ignore
+.gitignore     export-ignore
+.gitkeep       export-ignore
+assets/image/Einstein.jpg filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,14 @@
+**/__pycache__/
+.env
+.mypy_cache/
+.ruff_cache/
+.venv/
+logs/
+results/
+.github/
+.trunk/
+.idea/
+renovate.json
+.deepsource.toml
+.pre-commit-config.yaml
+compose.yaml

.python-version

@@ -0,0 +1 @@
+3.13

.sonarlint/connectedMode.json

@@ -0,0 +1,5 @@
+{
+  "sonarCloudOrganization": "alphaspheredotai",
+  "projectKey": "AlphaSphereDotAI_chatacter_backend_app",
+  "region": "EU"
+}

Dockerfile

@@ -0,0 +1,47 @@
+FROM python:3.13@sha256:5f69d22a88dd4cc4ee1576def19aef48c8faa1b566054c44291183831cbad13b AS builder
+
+SHELL ["/bin/bash", "-c"]
+
+ENV UV_LINK_MODE=copy \
+    UV_COMPILE_BYTECODE=1 \
+    UV_PYTHON_DOWNLOADS=0
+
+COPY --from=ghcr.io/astral-sh/uv:latest@sha256:68a26194ea8da0dbb014e8ae1d8ab08a469ee3ba0f4e2ac07b8bb66c0f8185c1 \
+    /uv /uvx /bin/
+
+WORKDIR /app
+
+RUN --mount=type=cache,target=/root/.cache/uv \
+    --mount=type=bind,source=uv.lock,target=uv.lock \
+    --mount=type=bind,source=pyproject.toml,target=pyproject.toml \
+    --mount=type=bind,source=README.md,target=README.md \
+    uv sync --no-install-project --no-dev --locked --no-editable
+
+COPY . /app
+
+RUN --mount=type=cache,target=/root/.cache/uv \
+    uv sync --no-dev --locked --no-editable
+
+FROM python:3.13-slim@sha256:f2fdaec50160418e0c2867ba3e254755edd067171725886d5d303fd7057bbf81 AS production
+
+SHELL ["/bin/bash", "-c"]
+
+ENV GRADIO_SERVER_PORT=7860 \
+    GRADIO_SERVER_NAME=0.0.0.0
+
+RUN groupadd app && \
+    useradd -m -g app -s /bin/bash app && \
+    apt-get update > /dev/null && \
+    apt-get install -y --no-install-recommends curl > /dev/null && \
+    apt-get clean > /dev/null && \
+    rm -rf /var/lib/apt/lists/*
+
+WORKDIR /home/app
+
+COPY --from=builder --chown=app:app --chmod=555 /app/.venv /app/.venv
+
+USER app
+
+EXPOSE ${GRADIO_SERVER_PORT}
+
+CMD ["/app/.venv/bin/chattr"]

README.md

@@ -1,12 +1,11 @@
 ---
 title: Chattr
-emoji: 🔥
+emoji: 💬
 colorFrom: gray
-colorTo: yellow
-sdk: gradio
-sdk_version: 5.36.2
-app_file: app.py
-pinned: false
+colorTo: blue
+sdk: docker
+app_port: 7860
+short_description: Chat with Characters
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# **Chattr**: App part of the Chatacter Backend

pyproject.toml

@@ -0,0 +1,28 @@
+[project]
+name = "chattr"
+version = "0.1.0"
+description = "App part of the Chatacter Backend"
+readme = "README.md"
+authors = [
+  { name = "Mohamed Hisham Abdelzaher", email = "mohamed.hisham.abdelzaher@gmail.com" },
+]
+requires-python = ">=3.12"
+dependencies = [
+  "gradio>=5.36.2",
+  "langchain>=0.3.26",
+  "langchain-mcp-adapters>=0.1.9",
+  "langchain-openai>=0.3.27",
+  "langgraph>=0.5.2",
+  "loguru>=0.7.3",
+  "python-dotenv>=1.1.1",
+]
+
+[project.scripts]
+chattr = "chattr.__main__:main"
+
+[build-system]
+requires = ["uv_build"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = ["ruff>=0.12.2", "ty>=0.0.1a12"]

src/chattr/__init__.py

@@ -0,0 +1,76 @@
+from datetime import datetime
+from os import getenv
+from pathlib import Path
+
+from dotenv import load_dotenv
+from loguru import logger
+from requests import get
+
+load_dotenv()
+
+SERVER_URL: str = getenv(key="SERVER_URL", default="127.0.0.1")
+SERVER_PORT: int = getenv(key="SERVER_PORT", default=7860)
+CURRENT_DATE: str = datetime.now().strftime(format="%Y-%m-%d_%H-%M-%S")
+MCP_VOICE_GENERATOR: str = getenv(
+    key="MCP_VOICE_GENERATOR", default="http://localhost:8001/"
+)
+MCP_VIDEO_GENERATOR: str = getenv(
+    key="MCP_VIDEO_GENERATOR", default="http://localhost:8002/"
+)
+VECTOR_DATABASE_NAME: str = getenv(key="VECTOR_DATABASE_NAME", default="chattr")
+DOCKER_MODEL_RUNNER_URL: str = getenv(
+    key="DOCKER_MODEL_RUNNER_URL", default="http://127.0.0.1:12434/engines/v1"
+)
+DOCKER_MODEL_RUNNER_MODEL_NAME: str = getenv(
+    key="DOCKER_MODEL_RUNNER_MODEL_NAME",
+    default="ai/qwen3:0.6B-Q4_0",
+)
+GROQ_URL: str = getenv(key="MODEL_URL", default="https://api.groq.com/openai/v1")
+GROQ_MODEL_NAME: str = getenv(key="GROQ_MODEL_NAME", default="llama3-70b-8192")
+
+BASE_DIR: Path = Path.cwd()
+ASSETS_DIR: Path = BASE_DIR / "assets"
+LOG_DIR: Path = BASE_DIR / "logs"
+IMAGE_DIR: Path = ASSETS_DIR / "image"
+AUDIO_DIR: Path = ASSETS_DIR / "audio"
+VIDEO_DIR: Path = ASSETS_DIR / "video"
+
+LOG_FILE_PATH: Path = LOG_DIR / f"{CURRENT_DATE}.log"
+AUDIO_FILE_PATH: Path = AUDIO_DIR / f"{CURRENT_DATE}.wav"
+VIDEO_FILE_PATH: Path = VIDEO_DIR / f"{CURRENT_DATE}.mp4"
+
+ASSETS_DIR.mkdir(exist_ok=True)
+IMAGE_DIR.mkdir(exist_ok=True)
+AUDIO_DIR.mkdir(exist_ok=True)
+VIDEO_DIR.mkdir(exist_ok=True)
+LOG_DIR.mkdir(exist_ok=True)
+
+MODEL_URL: str = (
+    DOCKER_MODEL_RUNNER_URL
+    if get(DOCKER_MODEL_RUNNER_URL, timeout=5).status_code == 200
+    else GROQ_URL
+)
+MODEL_NAME: str = (
+    DOCKER_MODEL_RUNNER_MODEL_NAME
+    if MODEL_URL == DOCKER_MODEL_RUNNER_URL
+    else GROQ_MODEL_NAME
+)
+MODEL_API_KEY: str = (
+    "not-needed" if MODEL_URL == DOCKER_MODEL_RUNNER_URL else getenv("GROQ_API_KEY")
+)
+MODEL_TEMPERATURE: float = float(getenv(key="MODEL_TEMPERATURE", default=0.0))
+
+logger.add(
+    sink=LOG_FILE_PATH,
+    format="{time:YYYY-MM-DD at HH:mm:ss} | {level} | {message}",
+    colorize=True,
+)
+logger.info(f"Current date: {CURRENT_DATE}")
+logger.info(f"Base directory: {BASE_DIR}")
+logger.info(f"Assets directory: {ASSETS_DIR}")
+logger.info(f"Log directory: {LOG_DIR}")
+logger.info(f"Audio file path: {AUDIO_FILE_PATH}")
+logger.info(f"Log file path: {LOG_FILE_PATH}")
+logger.info(f"Model URL is going to be used is {MODEL_URL}")
+logger.info(f"Model name is going to be used is {MODEL_NAME}")
+logger.info(f"Model temperature is going to be used is {MODEL_TEMPERATURE}")

src/chattr/__main__.py

@@ -0,0 +1,24 @@
+from gradio import Blocks
+
+from chattr import SERVER_PORT, SERVER_URL
+from chattr.gui import app_block
+
+
+def main() -> None:
+    """
+    Initializes and launches the Gradio-based Chattr application server with API access, monitoring, and PWA support enabled.
+    """
+    app: Blocks = app_block()
+    app.queue(api_open=True).launch(
+        server_name=SERVER_URL,
+        server_port=SERVER_PORT,
+        debug=True,
+        show_api=True,
+        enable_monitoring=True,
+        show_error=True,
+        pwa=True,
+    )
+
+
+if __name__ == "__main__":
+    main()

src/chattr/graph.py

@@ -0,0 +1,96 @@
+from langchain_core.messages import HumanMessage, SystemMessage
+from langchain_core.tools import BaseTool
+from langchain_mcp_adapters.client import MultiServerMCPClient
+from langchain_openai import ChatOpenAI
+from langgraph.graph import START, StateGraph
+from langgraph.graph.message import MessagesState
+from langgraph.graph.state import CompiledStateGraph
+from langgraph.prebuilt import ToolNode, tools_condition
+
+from chattr import (
+    ASSETS_DIR,
+    MODEL_API_KEY,
+    MODEL_NAME,
+    MODEL_TEMPERATURE,
+    MODEL_URL,
+)
+
+SYSTEM_MESSAGE: SystemMessage = SystemMessage(
+    content="You are a helpful assistant that can answer questions about the time."
+)
+
+
+async def create_graph() -> CompiledStateGraph:
+    """
+    Asynchronously creates and compiles a conversational state graph for a time-answering assistant with integrated external tools.
+
+    Returns:
+        CompiledStateGraph: The compiled state graph ready for execution, with nodes for agent responses and tool invocation.
+    """
+    _mcp_client = MultiServerMCPClient(
+        {
+            "time": {
+                "command": "docker",
+                "args": ["run", "-i", "--rm", "mcp/time"],
+                "transport": "stdio",
+            }
+        }
+    )
+    _tools: list[BaseTool] = await _mcp_client.get_tools()
+    try:
+        _model: ChatOpenAI = ChatOpenAI(
+            base_url=MODEL_URL,
+            model=MODEL_NAME,
+            api_key=MODEL_API_KEY,
+            temperature=MODEL_TEMPERATURE,
+        )
+        _model = _model.bind_tools(_tools, parallel_tool_calls=False)
+    except Exception as e:
+        raise RuntimeError(f"Failed to initialize ChatOpenAI model: {e}") from e
+
+    def call_model(state: MessagesState) -> MessagesState:
+        """
+        Generate a new message state by invoking the chat model with the system message prepended to the current messages.
+
+        Parameters:
+            state (MessagesState): The current state containing a list of messages.
+
+        Returns:
+            MessagesState: A new state with the model's response appended to the messages.
+        """
+        return {"messages": [_model.invoke([SYSTEM_MESSAGE] + state["messages"])]}
+
+    _builder: StateGraph = StateGraph(MessagesState)
+    _builder.add_node("agent", call_model)
+    _builder.add_node("tools", ToolNode(_tools))
+    _builder.add_edge(START, "agent")
+    _builder.add_conditional_edges("agent", tools_condition)
+    _builder.add_edge("tools", "agent")
+    graph: CompiledStateGraph = _builder.compile()
+    return graph
+
+
+def draw_graph(graph: CompiledStateGraph) -> None:
+    """
+    Render the compiled state graph as a Mermaid PNG image and save it to the assets directory.
+    """
+    graph.get_graph().draw_mermaid_png(output_file_path=ASSETS_DIR / "graph.png")
+
+
+if __name__ == "__main__":
+    import asyncio
+
+    async def test_graph():
+        """
+        Asynchronously creates and tests the conversational state graph by sending a time-related query and printing the resulting messages.
+        """
+        g: CompiledStateGraph = await create_graph()
+
+        messages = await g.ainvoke(
+            {"messages": [HumanMessage(content="What is the time?")]}
+        )
+
+        for m in messages["messages"]:
+            m.pretty_print()
+
+    asyncio.run(test_graph())

src/chattr/gui.py

@@ -0,0 +1,55 @@
+import gradio
+from gradio import Blocks, Button, Chatbot, ChatMessage, Row, Textbox
+
+
+def generate_response(history: list[ChatMessage], thread_id: str) -> list[ChatMessage]:
+    """
+    Appends an assistant message about a quarterly sales plot to the chat history for the specified thread ID.
+
+    If the thread ID is 0, raises a Gradio error prompting for a valid thread ID.
+
+    Returns:
+        The updated chat history including the new assistant message.
+    """
+    if thread_id == 0:
+        raise gradio.Error("Please enter a thread ID.")
+    history.append(
+        ChatMessage(
+            role="assistant",
+            content=f"Here is the plot of quarterly sales for {thread_id}.",
+            metadata={
+                "title": "🛠️ Used tool Weather API",
+            },
+        )
+    )
+    return history
+
+
+def app_block() -> Blocks:
+    """
+    Constructs and returns the main Gradio chat application interface with a thread ID input, chatbot display, and control buttons.
+
+    Returns:
+        Blocks: The complete Gradio Blocks interface for the chat application.
+    """
+
+    history = [
+        ChatMessage(role="assistant", content="How can I help you?"),
+        ChatMessage(role="user", content="Can you make me a plot of quarterly sales?"),
+        ChatMessage(
+            role="assistant",
+            content="I am happy to provide you that report and plot.",
+        ),
+    ]
+    with Blocks() as app:
+        with Row():
+            thread_id: Textbox = Textbox(label="Thread ID", info="Enter Thread ID")
+
+        chatbot: Chatbot = Chatbot(history, type="messages")
+
+        with Row():
+            generate_btn: Button = Button(value="Generate", variant="primary")
+            stop_btn: Button = Button(value="Stop", variant="stop")
+        _event = generate_btn.click(generate_response, [chatbot, thread_id], chatbot)
+        stop_btn.click(cancels=[_event])
+    return app

src/chattr/tools.py

@@ -0,0 +1,25 @@
+from typing import Literal
+
+from langchain_core.tools import tool
+
+
+@tool
+def get_weather(city: Literal["nyc", "sf"]) -> str:
+    """
+    Returns a weather description for the specified city.
+
+    Parameters:
+        city (Literal["nyc", "sf"]): The city for which to retrieve weather information.
+
+    Returns:
+        str: A message describing the weather in the specified city.
+
+    Raises:
+        AssertionError: If the city is not "nyc" or "sf".
+    """
+    if city == "nyc":
+        return "It might be cloudy in nyc"
+    elif city == "sf":
+        return "It's always sunny in sf"
+    else:
+        raise AssertionError("Unknown city")