ragbits-chat 1.4.0.dev202509220622__py3-none-any.whl → 1.4.0.dev202511290233__py3-none-any.whl

ragbits/chat/__init__.py

@@ -14,10 +14,32 @@ from ragbits.chat.client import (
 from ragbits.chat.interface.types import (
     ChatResponse,
     ChatResponseType,
+    ChatResponseUnion,
+    ClearMessageContent,
+    ClearMessageResponse,
+    ConversationIdContent,
+    ConversationIdResponse,
+    ConversationSummaryContent,
+    ConversationSummaryResponse,
+    FollowupMessagesContent,
+    FollowupMessagesResponse,
+    ImageResponse,
+    LiveUpdateResponse,
     Message,
+    MessageIdContent,
+    MessageIdResponse,
     MessageRole,
     Reference,
+    ReferenceResponse,
+    ResponseContent,
     StateUpdate,
+    StateUpdateResponse,
+    TextContent,
+    TextResponse,
+    TodoItemContent,
+    TodoItemResponse,
+    UsageContent,
+    UsageResponse,
 )
 
 __all__ = [
@@ -25,15 +47,37 @@ __all__ = [
     "AuthenticationResponse",
     "ChatResponse",
     "ChatResponseType",
+    "ChatResponseUnion",
+    "ClearMessageContent",
+    "ClearMessageResponse",
+    "ConversationIdContent",
+    "ConversationIdResponse",
+    "ConversationSummaryContent",
+    "ConversationSummaryResponse",
+    "FollowupMessagesContent",
+    "FollowupMessagesResponse",
+    "ImageResponse",
     "ListAuthenticationBackend",
+    "LiveUpdateResponse",
     "Message",
+    "MessageIdContent",
+    "MessageIdResponse",
     "MessageRole",
     "RagbitsChatClient",
     "RagbitsConversation",
     "Reference",
+    "ReferenceResponse",
+    "ResponseContent",
     "StateUpdate",
+    "StateUpdateResponse",
     "SyncRagbitsChatClient",
     "SyncRagbitsConversation",
+    "TextContent",
+    "TextResponse",
+    "TodoItemContent",
+    "TodoItemResponse",
+    "UsageContent",
+    "UsageResponse",
     "User",
     "UserCredentials",
 ]

ragbits/chat/_utils.py

@@ -5,7 +5,7 @@ import logging
 
 from pydantic import TypeAdapter
 
-from .interface.types import ChatResponse
+from .interface.types import ChatResponse, ChatResponseUnion
 
 logger = logging.getLogger(__name__)
 
@@ -33,7 +33,7 @@ def parse_sse_line(line: str) -> ChatResponse | None:
     try:
         json_payload = line[len(PREFIX) :].strip()
         data = json.loads(json_payload)
-        adapter: TypeAdapter[ChatResponse] = TypeAdapter(ChatResponse)
+        adapter: TypeAdapter[ChatResponseUnion] = TypeAdapter(ChatResponseUnion)
         return adapter.validate_python(data)
     except Exception as exc:
         logger.error("Failed to parse SSE line: %s", exc, exc_info=True)

ragbits/chat/api.py

@@ -1,17 +1,18 @@
 import importlib
 import json
 import logging
+import re
 import time
 from collections.abc import AsyncGenerator
 from contextlib import asynccontextmanager
 from pathlib import Path
-from typing import Any, Literal, cast
+from typing import Any, cast
 
 import uvicorn
 from fastapi import Depends, FastAPI, HTTPException, Request, status
 from fastapi.exceptions import RequestValidationError
 from fastapi.middleware.cors import CORSMiddleware
-from fastapi.responses import HTMLResponse, JSONResponse, StreamingResponse
+from fastapi.responses import HTMLResponse, JSONResponse, PlainTextResponse, StreamingResponse
 from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
 from fastapi.staticfiles import StaticFiles
 from pydantic import BaseModel
@@ -24,14 +25,14 @@ from ragbits.chat.interface.types import (
     AuthType,
     ChatContext,
     ChatMessageRequest,
-    ChatResponse,
-    ChatResponseType,
+    ChatResponseUnion,
     ChunkedContent,
     ConfigResponse,
     FeedbackConfig,
     FeedbackItem,
     FeedbackRequest,
     Image,
+    ImageResponse,
 )
 from ragbits.core.audit.metrics import record_metric
 from ragbits.core.audit.metrics.base import MetricType
@@ -59,6 +60,7 @@ class RagbitsAPI:
         ui_build_dir: str | None = None,
         debug_mode: bool = False,
         auth_backend: AuthenticationBackend | type[AuthenticationBackend] | str | None = None,
+        theme_path: str | None = None,
     ) -> None:
         """
         Initialize the RagbitsAPI.
@@ -70,6 +72,7 @@ class RagbitsAPI:
             ui_build_dir: Path to a custom UI build directory. If None, uses the default package UI.
             debug_mode: Flag enabling debug tools in the default UI
             auth_backend: Authentication backend for user authentication. If None, no authentication required.
+            theme_path: Path to a JSON file containing HeroUI theme configuration from heroui.com/themes
         """
         self.chat_interface: ChatInterface = self._load_chat_interface(chat_interface)
         self.dist_dir = Path(ui_build_dir) if ui_build_dir else Path(__file__).parent / "ui-build"
@@ -77,6 +80,7 @@ class RagbitsAPI:
         self.debug_mode = debug_mode
         self.auth_backend = self._load_auth_backend(auth_backend)
         self.security = HTTPBearer(auto_error=False) if auth_backend else None
+        self.theme_path = Path(theme_path) if theme_path else None
 
         @asynccontextmanager
         async def lifespan(app: FastAPI) -> AsyncGenerator[None, None]:
@@ -188,6 +192,25 @@ class RagbitsAPI:
 
             return JSONResponse(content=config_response.model_dump())
 
+        # Theme CSS endpoint - always available, returns 404 if no theme configured
+        @self.app.get("/api/theme", response_class=PlainTextResponse)
+        async def theme() -> PlainTextResponse:
+            if not self.theme_path or not self.theme_path.exists():
+                raise HTTPException(status_code=404, detail="No theme configured")
+
+            try:
+                with open(self.theme_path, encoding="utf-8") as f:
+                    json_content = f.read().strip()
+
+                css_content = RagbitsAPI._convert_heroui_json_to_css(json_content)
+
+                return PlainTextResponse(
+                    content=css_content, media_type="text/css", headers={"Cache-Control": "public, max-age=3600"}
+                )
+            except Exception as e:
+                logger.error(f"Error serving theme: {e}")
+                raise HTTPException(status_code=500, detail="Error loading theme") from e
+
         @self.app.get("/{full_path:path}", response_class=HTMLResponse)
         async def root() -> HTMLResponse:
             index_file = self.dist_dir / "index.html"
@@ -305,17 +328,17 @@ class RagbitsAPI:
                         content = str(data_dict.get("content", ""))
 
                         match data_dict.get("type"):
-                            case ChatResponseType.TEXT:
+                            case "text":
                                 response_text += content
-                            case ChatResponseType.REFERENCE:
+                            case "reference":
                                 reference_text += content
-                            case ChatResponseType.STATE_UPDATE:
+                            case "state_update":
                                 state_update_text += content
-                            case ChatResponseType.MESSAGE_ID:
+                            case "message_id":
                                 outputs.message_id = content
-                            case ChatResponseType.CONVERSATION_ID:
+                            case "conversation_id":
                                 outputs.conversation_id = content
-                            case ChatResponseType.IMAGE:
+                            case "image":
                                 outputs.image_url = content
 
                         yield chunk
@@ -532,7 +555,7 @@ class RagbitsAPI:
 
     @staticmethod
     async def _chat_response_to_sse(
-        responses: AsyncGenerator[ChatResponse],
+        responses: AsyncGenerator[ChatResponseUnion],
     ) -> AsyncGenerator[str, None]:
         """
         Formats chat responses into Server-Sent Events (SSE) format for streaming to the client.
@@ -556,9 +579,9 @@ class RagbitsAPI:
                     }
 
                 # Auto-chunk large images using ChunkedContent model
-                if response.type == ChatResponseType.IMAGE and cast(Image, response.content).url.startswith("data:"):
+                if isinstance(response, ImageResponse) and cast(Image, response.content).url.startswith("data:"):
                     # Auto-chunk the image
-                    async for chunk_response in RagbitsAPI._create_chunked_responses(ChatResponseType.IMAGE, response):
+                    async for chunk_response in RagbitsAPI._create_chunked_responses(response):
                         yield f"data: {json.dumps(chunk_response)}\n\n"
 
                     continue  # Skip normal processing for chunked images
@@ -568,7 +591,7 @@ class RagbitsAPI:
                 # - Regular URL images (https://..., http://..., /path/to/image.jpg)
                 data = json.dumps(
                     {
-                        "type": response.type.value,
+                        "type": response.get_type(),
                         "content": response_to_send.model_dump()
                         if isinstance(response_to_send, BaseModel)
                         else response_to_send,
@@ -592,9 +615,7 @@ class RagbitsAPI:
             )
 
     @staticmethod
-    async def _create_chunked_responses(
-        type: Literal[ChatResponseType.IMAGE], base64_response: ChatResponse
-    ) -> AsyncGenerator[dict, None]:
+    async def _create_chunked_responses(base64_response: ImageResponse) -> AsyncGenerator[dict, None]:
         """Create chunked responses from a base64 response."""
         image_content = cast(Image, base64_response.content)
         mime_type, base64_data = image_content.url.split(",", 1)
@@ -604,14 +625,14 @@ class RagbitsAPI:
         for i, chunk in enumerate(chunks):
             chunked_content = ChunkedContent(
                 id=image_content.id,
-                content_type=type.value,
+                content_type="image",
                 chunk_index=i,
                 total_chunks=len(chunks),
                 mime_type=mime_type,
                 data=chunk,
             )
 
-            yield {"type": ChatResponseType.CHUNKED_CONTENT.value, "content": chunked_content.model_dump()}
+            yield {"type": "chunked_content", "content": chunked_content.model_dump()}
 
     @staticmethod
     def _load_chat_interface(implementation: type[ChatInterface] | str) -> ChatInterface:
@@ -680,3 +701,78 @@ class RagbitsAPI:
         Used for starting the API
         """
         uvicorn.run(self.app, host=host, port=port)
+
+    @staticmethod
+    def _convert_heroui_json_to_css(json_content: str) -> str:
+        """Convert HeroUI JSON theme configuration to CSS variables."""
+        try:
+            theme_config = json.loads(json_content)
+            css_lines = [
+                "/* Auto-generated CSS from HeroUI theme configuration */",
+                "",
+                ":root {",
+            ]
+
+            # Process light theme
+            if "themes" in theme_config and "light" in theme_config["themes"]:
+                light_colors = theme_config["themes"]["light"]["colors"]
+                css_lines.extend(RagbitsAPI._process_theme_colors(light_colors))
+
+            # Add layout properties
+            if "layout" in theme_config:
+                for prop, value in theme_config["layout"].items():
+                    css_prop = re.sub(r"([A-Z])", r"-\1", prop).lower()
+                    css_lines.append(f"  --heroui-{css_prop}: {value};")
+
+            css_lines.append("}")
+            css_lines.append("")
+
+            # Process dark theme
+            if "themes" in theme_config and "dark" in theme_config["themes"]:
+                css_lines.append(".dark {")
+                dark_colors = theme_config["themes"]["dark"]["colors"]
+                css_lines.extend(RagbitsAPI._process_theme_colors(dark_colors))
+
+                if "layout" in theme_config:
+                    for prop, value in theme_config["layout"].items():
+                        css_prop = re.sub(r"([A-Z])", r"-\1", prop).lower()
+                        css_lines.append(f"  --heroui-{css_prop}: {value};")
+
+                css_lines.append("}")
+
+            # Add body styling
+            css_lines.extend(
+                [
+                    "",
+                    "body {",
+                    "  background-color: var(--heroui-background);",
+                    "  color: var(--heroui-foreground);",
+                    "}",
+                ]
+            )
+
+            return "\n".join(css_lines)
+
+        except json.JSONDecodeError as e:
+            logger.error(f"Invalid JSON in theme file: {e}")
+            raise HTTPException(status_code=400, detail="Invalid JSON theme file") from e
+        except Exception as e:
+            logger.error(f"Error converting theme: {e}")
+            raise HTTPException(status_code=500, detail="Error processing theme") from e
+
+    @staticmethod
+    def _process_theme_colors(colors: dict) -> list[str]:
+        """Process theme colors and return CSS variable declarations."""
+        css_lines = []
+
+        for color_name, color_value in colors.items():
+            if isinstance(color_value, dict):
+                for shade, value in color_value.items():
+                    if shade == "DEFAULT":
+                        css_lines.append(f"  --heroui-{color_name}: {value};")
+                    elif isinstance(value, str):
+                        css_lines.append(f"  --heroui-{color_name}-{shade}: {value};")
+            elif isinstance(color_value, str):
+                css_lines.append(f"  --heroui-{color_name}: {color_value};")
+
+        return css_lines

ragbits/chat/cli.py

@@ -32,6 +32,11 @@ def run(
     ),
     debug_mode: bool = typer.Option(False, "--debug", help="Flag enabling debug tools in the default UI"),
     auth: str = typer.Option(None, help="Path to a module with Authentication Backend"),
+    theme: str = typer.Option(
+        None,
+        "--theme",
+        help="Path to a HeroUI theme JSON file from heroui.com/themes",
+    ),
 ) -> None:
     """
     Run API service with UI demo
@@ -42,5 +47,6 @@ def run(
         ui_build_dir=ui_build_dir,
         debug_mode=debug_mode,
         auth_backend=auth,
+        theme_path=theme,
     )
     api.run(host=host, port=port)

ragbits/chat/client/conversation.py

@@ -8,10 +8,15 @@ import httpx
 from .._utils import build_api_url, parse_sse_line
 from ..interface.types import (
     ChatResponse,
-    ChatResponseType,
+    ConversationIdResponse,
+    LiveUpdateResponse,
     Message,
+    MessageIdResponse,
     MessageRole,
+    ReferenceResponse,
     StateUpdate,
+    StateUpdateResponse,
+    TextResponse,
 )
 from .exceptions import ChatClientRequestError, ChatClientResponseError
 
@@ -103,21 +108,21 @@ class RagbitsConversation:
 
     def _process_incoming(self, resp: ChatResponse, assistant_index: int) -> None:
         """Update local state based on *resp*."""
-        if resp.as_state_update() is not None:
-            self.conversation_state = resp.as_state_update()
-        elif resp.as_conversation_id() is not None:
-            self.conversation_id = resp.as_conversation_id()
-        elif resp.type is ChatResponseType.MESSAGE_ID:
+        if isinstance(resp, StateUpdateResponse):
+            self.conversation_state = resp.content
+        elif isinstance(resp, ConversationIdResponse):
+            self.conversation_id = resp.content.conversation_id
+        elif isinstance(resp, MessageIdResponse):
             return
 
         assistant_msg = self.history[assistant_index]
 
-        if resp.type is ChatResponseType.LIVE_UPDATE:
+        if isinstance(resp, LiveUpdateResponse):
             assistant_msg.content += f"\n[LIVE_UPDATE]: {resp.content}\n"
-        elif resp.as_reference() is not None:
+        elif isinstance(resp, ReferenceResponse):
             assistant_msg.content += f"\n[REFERENCE]: {resp.content}\n"
-        elif (text_content := resp.as_text()) is not None:
-            assistant_msg.content += text_content
+        elif isinstance(resp, TextResponse):
+            assistant_msg.content += resp.content.text
 
 
 class SyncRagbitsConversation:
@@ -212,18 +217,18 @@ class SyncRagbitsConversation:
 
     def _process_incoming(self, resp: ChatResponse, assistant_index: int) -> None:
         """Update local state based on *resp*."""
-        if resp.as_state_update() is not None:
-            self.conversation_state = resp.as_state_update()
-        elif resp.as_conversation_id() is not None:
-            self.conversation_id = resp.as_conversation_id()
-        elif resp.type is ChatResponseType.MESSAGE_ID:
+        if isinstance(resp, StateUpdateResponse):
+            self.conversation_state = resp.content
+        elif isinstance(resp, ConversationIdResponse):
+            self.conversation_id = resp.content.conversation_id
+        elif isinstance(resp, MessageIdResponse):
             return
 
         assistant_msg = self.history[assistant_index]
 
-        if resp.type is ChatResponseType.LIVE_UPDATE:
+        if isinstance(resp, LiveUpdateResponse):
             assistant_msg.content += f"\n[LIVE_UPDATE]: {resp.content}\n"
-        elif resp.as_reference() is not None:
+        elif isinstance(resp, ReferenceResponse):
             assistant_msg.content += f"\n[REFERENCE]: {resp.content}\n"
-        elif (text_content := resp.as_text()) is not None:
-            assistant_msg.content += text_content
+        elif isinstance(resp, TextResponse):
+            assistant_msg.content += resp.content.text