appkit-assistant 0.7.2__tar.gz → 0.7.4__tar.gz

appkit_assistant-0.7.4/PKG-INFO

@@ -0,0 +1,330 @@
+Metadata-Version: 2.4
+Name: appkit-assistant
+Version: 0.7.4
+Summary: Add your description here
+Author: Jens Rehpöhler
+Requires-Python: >=3.13
+Requires-Dist: appkit-commons
+Requires-Dist: openai>=2.3.0
+Description-Content-Type: text/markdown
+
+# appkit-assistant
+
+[![Python 3.13+](https://img.shields.io/badge/python-3.13+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**AI assistant component for Reflex applications with MCP server integration.**
+
+appkit-assistant provides a complete conversational AI interface built on Reflex, featuring OpenAI and Perplexity integrations, Model Context Protocol (MCP) server management, and secure credential handling. It includes both backend processing services and ready-to-use UI components for building AI-powered applications.
+
+![Assistant](./docs/assistant.png)
+
+---
+
+## ✨ Features
+
+- **Multi-Model Support** - OpenAI Chat Completions, OpenAI Responses API, Perplexity, and fallback Lorem Ipsum processor
+- **MCP Server Integration** - Manage and connect to Model Context Protocol servers as tools
+- **Secure Credential Management** - Encrypted storage and handling of API keys and server credentials
+- **Reflex UI Components** - Pre-built assistant interface with composer, thread management, and message display
+- **Streaming Responses** - Real-time streaming of AI responses with chunked content
+- **Thread Management** - Persistent conversation threads with state management
+
+---
+
+## 🚀 Installation
+
+### As Part of AppKit Workspace
+
+If you're using the full AppKit workspace:
+
+```bash
+git clone https://github.com/jenreh/appkit.git
+cd appkit
+uv sync
+```
+
+### Standalone Installation
+
+Install from PyPI:
+
+```bash
+pip install appkit-assistant
+```
+
+Or with uv:
+
+```bash
+uv add appkit-assistant
+```
+
+### Dependencies
+
+- `appkit-commons` (shared utilities)
+- `openai>=2.3.0` (OpenAI API client)
+
+---
+
+## 🏁 Quick Start
+
+### Basic Setup
+
+1. Configure your API keys in your application's configuration:
+
+```python
+from appkit_assistant.configuration import AssistantConfig
+
+# In your app configuration
+assistant_config = AssistantConfig(
+    openai_api_key="your-openai-key",
+    perplexity_api_key="your-perplexity-key",
+    # Optional: custom OpenAI base URL
+    openai_base_url="https://api.openai.com/v1"
+)
+```
+
+2. Register processors with the ModelManager:
+
+```python
+from appkit_assistant.backend.model_manager import ModelManager
+from appkit_assistant.backend.processors.openai_chat_completion_processor import OpenAIChatCompletionProcessor
+from appkit_assistant.backend.processors.perplexity_processor import PerplexityProcessor
+
+manager = ModelManager()
+manager.register_processor("openai", OpenAIChatCompletionProcessor(assistant_config))
+manager.register_processor("perplexity", PerplexityProcessor(assistant_config))
+```
+
+3. Use the assistant component in your Reflex app:
+
+```python
+import reflex as rx
+import appkit_assistant as assistant
+
+def assistant_page():
+    return rx.container(
+        assistant.Assistant(),
+        height="100vh"
+    )
+```
+
+---
+
+## 📖 Usage
+
+### Model Management
+
+The `ModelManager` singleton handles all AI processors and models:
+
+```python
+from appkit_assistant.backend.model_manager import ModelManager
+
+manager = ModelManager()
+
+# Get all available models
+models = manager.get_all_models()
+
+# Get a specific model
+model = manager.get_model("gpt-4")
+
+# Set default model
+manager.set_default_model("gpt-4")
+```
+
+### Processing Messages
+
+Process conversations using the registered processors:
+
+```python
+from appkit_assistant.backend.models import Message, MessageType
+
+messages = [
+    Message(role="user", content="Hello, how are you?", type=MessageType.TEXT)
+]
+
+async for chunk in manager.get_processor_for_model("gpt-4").process(messages, "gpt-4"):
+    print(f"Received: {chunk.content}")
+```
+
+### MCP Server Management
+
+Manage MCP servers for tool integration:
+
+```python
+from appkit_assistant.backend.models import MCPServer
+
+mcp_server = MCPServer(
+    name="my-server",
+    command="python",
+    args=["-m", "my_mcp_server"],
+    headers={"Authorization": "Bearer token"}
+)
+
+# Use in processing
+async for chunk in processor.process(messages, "gpt-4", mcp_servers=[mcp_server]):
+    # Handle response with MCP tools
+    pass
+```
+
+### UI Components
+
+#### Assistant Interface
+
+The main `Assistant` component provides a complete chat interface:
+
+```python
+import appkit_assistant as assistant
+
+def chat_page():
+    return assistant.Assistant()
+```
+
+#### Individual Components
+
+Use individual components for custom layouts:
+
+```python
+import appkit_assistant as assistant
+
+def custom_assistant():
+    return rx.vstack(
+        assistant.ThreadList(),
+        assistant.composer(),
+        spacing="4"
+    )
+```
+
+#### MCP Server Management UI
+
+Display and manage MCP servers:
+
+```python
+def servers_page():
+    return assistant.mcp_servers_table()
+```
+
+---
+
+## 🔧 Configuration
+
+### AssistantConfig
+
+Configure API keys and settings:
+
+```python
+from appkit_assistant.configuration import AssistantConfig
+
+config = AssistantConfig(
+    openai_api_key="sk-...",
+    openai_base_url="https://custom.openai.endpoint/v1",
+    perplexity_api_key="pplx-...",
+    google_api_key="AIza..."  # For future Google integrations
+)
+```
+
+### Processor Registration
+
+Register processors based on available credentials:
+
+```python
+from appkit_assistant.backend.processors import (
+    OpenAIChatCompletionProcessor,
+    PerplexityProcessor,
+    LoremIpsumProcessor
+)
+
+manager = ModelManager()
+
+if config.openai_api_key:
+    manager.register_processor("openai", OpenAIChatCompletionProcessor(config))
+
+if config.perplexity_api_key:
+    manager.register_processor("perplexity", PerplexityProcessor(config))
+
+# Always available fallback
+manager.register_processor("lorem", LoremIpsumProcessor())
+```
+
+---
+
+## 📋 API Reference
+
+### Core Classes
+
+- `ModelManager` - Singleton model and processor registry
+- `Processor` - Abstract base for AI processors
+- `AIModel` - Model metadata and configuration
+- `Message` - Conversation message structure
+- `MCPServer` - MCP server configuration
+
+### Component API
+
+- `Assistant` - Complete assistant interface
+- `composer` - Message input component
+- `ThreadList` - Conversation thread list
+- `MessageComponent` - Individual message display
+- `mcp_servers_table` - MCP server management table
+
+### State Management
+
+- `ThreadState` - Individual thread state
+- `ThreadListState` - Thread list management
+
+---
+
+## 🔒 Security
+
+> [!IMPORTANT]
+> API keys and MCP server credentials are handled securely using the appkit-commons configuration system. Never hardcode secrets in your code.
+
+- Use `SecretStr` for sensitive configuration values
+- Credentials are encrypted at rest when stored in the database
+- MCP server headers support encrypted storage
+
+---
+
+## 🤝 Integration Examples
+
+### With AppKit User Management
+
+Combine with appkit-user for authenticated assistants:
+
+```python
+from appkit_user import authenticated, requires_role
+
+@authenticated()
+@requires_role("assistant_user")
+def protected_assistant_page():
+    return assistant.Assistant()
+```
+
+### Custom Processor Implementation
+
+Implement your own AI processor:
+
+```python
+from appkit_assistant.backend.processor import Processor
+from appkit_assistant.backend.models import AIModel, Chunk, Message
+
+class CustomProcessor(Processor):
+    def get_supported_models(self):
+        return {
+            "custom-model": AIModel(
+                id="custom-model",
+                text="Custom AI Model",
+                icon="🤖"
+            )
+        }
+
+    async def process(self, messages, model_id, files=None, mcp_servers=None):
+        # Your AI processing logic here
+        yield Chunk(content="Response from custom model", type="text")
+```
+
+---
+
+## 📚 Related Components
+
+- **[appkit-mantine](./../appkit-mantine)** - UI components used in the assistant interface
+- **[appkit-user](./../appkit-user)** - User authentication and authorization
+- **[appkit-commons](./../appkit-commons)** - Shared utilities and configuration

appkit_assistant-0.7.4/README.md

@@ -0,0 +1,320 @@
+# appkit-assistant
+
+[![Python 3.13+](https://img.shields.io/badge/python-3.13+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**AI assistant component for Reflex applications with MCP server integration.**
+
+appkit-assistant provides a complete conversational AI interface built on Reflex, featuring OpenAI and Perplexity integrations, Model Context Protocol (MCP) server management, and secure credential handling. It includes both backend processing services and ready-to-use UI components for building AI-powered applications.
+
+![Assistant](./docs/assistant.png)
+
+---
+
+## ✨ Features
+
+- **Multi-Model Support** - OpenAI Chat Completions, OpenAI Responses API, Perplexity, and fallback Lorem Ipsum processor
+- **MCP Server Integration** - Manage and connect to Model Context Protocol servers as tools
+- **Secure Credential Management** - Encrypted storage and handling of API keys and server credentials
+- **Reflex UI Components** - Pre-built assistant interface with composer, thread management, and message display
+- **Streaming Responses** - Real-time streaming of AI responses with chunked content
+- **Thread Management** - Persistent conversation threads with state management
+
+---
+
+## 🚀 Installation
+
+### As Part of AppKit Workspace
+
+If you're using the full AppKit workspace:
+
+```bash
+git clone https://github.com/jenreh/appkit.git
+cd appkit
+uv sync
+```
+
+### Standalone Installation
+
+Install from PyPI:
+
+```bash
+pip install appkit-assistant
+```
+
+Or with uv:
+
+```bash
+uv add appkit-assistant
+```
+
+### Dependencies
+
+- `appkit-commons` (shared utilities)
+- `openai>=2.3.0` (OpenAI API client)
+
+---
+
+## 🏁 Quick Start
+
+### Basic Setup
+
+1. Configure your API keys in your application's configuration:
+
+```python
+from appkit_assistant.configuration import AssistantConfig
+
+# In your app configuration
+assistant_config = AssistantConfig(
+    openai_api_key="your-openai-key",
+    perplexity_api_key="your-perplexity-key",
+    # Optional: custom OpenAI base URL
+    openai_base_url="https://api.openai.com/v1"
+)
+```
+
+2. Register processors with the ModelManager:
+
+```python
+from appkit_assistant.backend.model_manager import ModelManager
+from appkit_assistant.backend.processors.openai_chat_completion_processor import OpenAIChatCompletionProcessor
+from appkit_assistant.backend.processors.perplexity_processor import PerplexityProcessor
+
+manager = ModelManager()
+manager.register_processor("openai", OpenAIChatCompletionProcessor(assistant_config))
+manager.register_processor("perplexity", PerplexityProcessor(assistant_config))
+```
+
+3. Use the assistant component in your Reflex app:
+
+```python
+import reflex as rx
+import appkit_assistant as assistant
+
+def assistant_page():
+    return rx.container(
+        assistant.Assistant(),
+        height="100vh"
+    )
+```
+
+---
+
+## 📖 Usage
+
+### Model Management
+
+The `ModelManager` singleton handles all AI processors and models:
+
+```python
+from appkit_assistant.backend.model_manager import ModelManager
+
+manager = ModelManager()
+
+# Get all available models
+models = manager.get_all_models()
+
+# Get a specific model
+model = manager.get_model("gpt-4")
+
+# Set default model
+manager.set_default_model("gpt-4")
+```
+
+### Processing Messages
+
+Process conversations using the registered processors:
+
+```python
+from appkit_assistant.backend.models import Message, MessageType
+
+messages = [
+    Message(role="user", content="Hello, how are you?", type=MessageType.TEXT)
+]
+
+async for chunk in manager.get_processor_for_model("gpt-4").process(messages, "gpt-4"):
+    print(f"Received: {chunk.content}")
+```
+
+### MCP Server Management
+
+Manage MCP servers for tool integration:
+
+```python
+from appkit_assistant.backend.models import MCPServer
+
+mcp_server = MCPServer(
+    name="my-server",
+    command="python",
+    args=["-m", "my_mcp_server"],
+    headers={"Authorization": "Bearer token"}
+)
+
+# Use in processing
+async for chunk in processor.process(messages, "gpt-4", mcp_servers=[mcp_server]):
+    # Handle response with MCP tools
+    pass
+```
+
+### UI Components
+
+#### Assistant Interface
+
+The main `Assistant` component provides a complete chat interface:
+
+```python
+import appkit_assistant as assistant
+
+def chat_page():
+    return assistant.Assistant()
+```
+
+#### Individual Components
+
+Use individual components for custom layouts:
+
+```python
+import appkit_assistant as assistant
+
+def custom_assistant():
+    return rx.vstack(
+        assistant.ThreadList(),
+        assistant.composer(),
+        spacing="4"
+    )
+```
+
+#### MCP Server Management UI
+
+Display and manage MCP servers:
+
+```python
+def servers_page():
+    return assistant.mcp_servers_table()
+```
+
+---
+
+## 🔧 Configuration
+
+### AssistantConfig
+
+Configure API keys and settings:
+
+```python
+from appkit_assistant.configuration import AssistantConfig
+
+config = AssistantConfig(
+    openai_api_key="sk-...",
+    openai_base_url="https://custom.openai.endpoint/v1",
+    perplexity_api_key="pplx-...",
+    google_api_key="AIza..."  # For future Google integrations
+)
+```
+
+### Processor Registration
+
+Register processors based on available credentials:
+
+```python
+from appkit_assistant.backend.processors import (
+    OpenAIChatCompletionProcessor,
+    PerplexityProcessor,
+    LoremIpsumProcessor
+)
+
+manager = ModelManager()
+
+if config.openai_api_key:
+    manager.register_processor("openai", OpenAIChatCompletionProcessor(config))
+
+if config.perplexity_api_key:
+    manager.register_processor("perplexity", PerplexityProcessor(config))
+
+# Always available fallback
+manager.register_processor("lorem", LoremIpsumProcessor())
+```
+
+---
+
+## 📋 API Reference
+
+### Core Classes
+
+- `ModelManager` - Singleton model and processor registry
+- `Processor` - Abstract base for AI processors
+- `AIModel` - Model metadata and configuration
+- `Message` - Conversation message structure
+- `MCPServer` - MCP server configuration
+
+### Component API
+
+- `Assistant` - Complete assistant interface
+- `composer` - Message input component
+- `ThreadList` - Conversation thread list
+- `MessageComponent` - Individual message display
+- `mcp_servers_table` - MCP server management table
+
+### State Management
+
+- `ThreadState` - Individual thread state
+- `ThreadListState` - Thread list management
+
+---
+
+## 🔒 Security
+
+> [!IMPORTANT]
+> API keys and MCP server credentials are handled securely using the appkit-commons configuration system. Never hardcode secrets in your code.
+
+- Use `SecretStr` for sensitive configuration values
+- Credentials are encrypted at rest when stored in the database
+- MCP server headers support encrypted storage
+
+---
+
+## 🤝 Integration Examples
+
+### With AppKit User Management
+
+Combine with appkit-user for authenticated assistants:
+
+```python
+from appkit_user import authenticated, requires_role
+
+@authenticated()
+@requires_role("assistant_user")
+def protected_assistant_page():
+    return assistant.Assistant()
+```
+
+### Custom Processor Implementation
+
+Implement your own AI processor:
+
+```python
+from appkit_assistant.backend.processor import Processor
+from appkit_assistant.backend.models import AIModel, Chunk, Message
+
+class CustomProcessor(Processor):
+    def get_supported_models(self):
+        return {
+            "custom-model": AIModel(
+                id="custom-model",
+                text="Custom AI Model",
+                icon="🤖"
+            )
+        }
+
+    async def process(self, messages, model_id, files=None, mcp_servers=None):
+        # Your AI processing logic here
+        yield Chunk(content="Response from custom model", type="text")
+```
+
+---
+
+## 📚 Related Components
+
+- **[appkit-mantine](./../appkit-mantine)** - UI components used in the assistant interface
+- **[appkit-user](./../appkit-user)** - User authentication and authorization
+- **[appkit-commons](./../appkit-commons)** - Shared utilities and configuration

{appkit_assistant-0.7.2 → appkit_assistant-0.7.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "appkit-assistant"
-version = "0.7.2"
+version = "0.7.4"
 description = "Add your description here"
 readme = "README.md"
 authors = [{ name = "Jens Rehpöhler" }]

{appkit_assistant-0.7.2 → appkit_assistant-0.7.4}/src/appkit_assistant/backend/models.py

@@ -73,6 +73,8 @@ class AIModel(BaseModel):
     temperature: float = 0.05
     supports_tools: bool = False
     supports_attachments: bool = False
+    keywords: list[str] = []
+    disabled: bool = False
 
 
 class Suggestion(BaseModel):

{appkit_assistant-0.7.2 → appkit_assistant-0.7.4}/src/appkit_assistant/backend/processors/ai_models.py

@@ -16,6 +16,7 @@ GEMINI_2_5_FLASH: Final = AIModel(
     icon="googlegemini",
     model="gemini-2-5-flash",
 )
+
 LLAMA_3_2_VISION: Final = AIModel(
     id="llama32_vision_90b",
     text="Llama 3.2 Vision 90B (OnPrem)",
@@ -76,6 +77,17 @@ GPT_5: Final = AIModel(
     temperature=1,
 )
 
+GPT_5_1: Final = AIModel(
+    id="gpt-5.1",
+    text="GPT 5.1",
+    icon="openai",
+    model="gpt-5.1",
+    stream=True,
+    supports_attachments=True,
+    supports_tools=True,
+    temperature=1,
+)
+
 GPT_5_CHAT: Final = AIModel(
     id="gpt-5-chat",
     text="GPT 5 Chat",
@@ -97,6 +109,17 @@ GPT_5_MINI: Final = AIModel(
     temperature=1,
 )
 
+GPT_5_1_MINI: Final = AIModel(
+    id="gpt-5.1-mini",
+    text="GPT 5.1 Mini",
+    icon="openai",
+    model="gpt-5.1-mini",
+    stream=True,
+    supports_attachments=True,
+    supports_tools=True,
+    temperature=1,
+)
+
 GPT_5_NANO: Final = AIModel(
     id="gpt-5-nano",
     text="GPT 5 Nano",

{appkit_assistant-0.7.2 → appkit_assistant-0.7.4}/src/appkit_assistant/backend/processors/perplexity_processor.py

@@ -41,6 +41,7 @@ SONAR_PRO = PerplexityAIModel(
     icon="perplexity",
     model="sonar-pro",
     stream=True,
+    keywords=["sonar", "perplexity"],
 )
 
 SONAR_DEEP_RESEARCH = PerplexityAIModel(
@@ -50,6 +51,7 @@ SONAR_DEEP_RESEARCH = PerplexityAIModel(
     model="sonar-deep-research",
     search_context_size=ContextSize.HIGH,
     stream=True,
+    keywords=["reasoning", "deep", "research", "perplexity"],
 )
 
 SONAR_REASONING = PerplexityAIModel(
@@ -59,6 +61,7 @@ SONAR_REASONING = PerplexityAIModel(
     model="sonar-reasoning",
     search_context_size=ContextSize.HIGH,
     stream=True,
+    keywords=["reasoning", "perplexity"],
 )
 
 ALL_MODELS = {

appkit_assistant-0.7.2/PKG-INFO

@@ -1,8 +0,0 @@
-Metadata-Version: 2.4
-Name: appkit-assistant
-Version: 0.7.2
-Summary: Add your description here
-Author: Jens Rehpöhler
-Requires-Python: >=3.13
-Requires-Dist: appkit-commons
-Requires-Dist: openai>=2.3.0

appkit_assistant-0.7.2/docs/ideas.md

@@ -1,67 +0,0 @@
-# Render information with a dedicated UI
-
-"Action" classes, e.g. something like
-
-```python
-class Calender(AssitantAction):
-   name: str
-   description: str
-   parameters: list[dict]
-
-   def __init__(self):
-      name = "showCalendarMeeting"
-      description = "Displays calendar meeting information"
-      parameters = [
-        {
-            name: "date",
-            type: "string",
-            description: "Meeting date (YYYY-MM-DD)",
-            required: true
-        },
-        {
-            name: "time",
-            type: "string",
-            description: "Meeting time (HH:mm)",
-            required: true
-        },
-        {
-            name: "meetingName",
-            type: "string",
-            description: "Name of the meeting",
-            required: false
-        }
-    ]
-
-    def render(status, **kwargs):
-       if status == Status.LOADING:
-          return loading_view()
-       else:
-          return calendar_entry(**kwargs)
-```
-
-## Next Actions
-
-```python
-class Suggestion(AssitantAction):
-   name: str
-   description: str
-   parameters: list[dict]
-
-   def __init__(self):
-      name = "showSuggestion"
-      description = "Displays suggestions"
-      parameters = [
-        {
-            name: "suggestion",
-            type: "string",
-            description: "Suggestion what how to continue or what to ask next",
-            required: false
-        }
-    ]
-
-    def render(status, **kwargs):
-       if status == Status.LOADING:
-          return loading_view()
-       else:
-          return render_suggestion(**kwargs)
-```