appkit-assistant 0.7.3__py3-none-any.whl → 0.7.4__py3-none-any.whl

appkit_assistant-0.7.4.dist-info/METADATA

@@ -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.3.dist-info → appkit_assistant-0.7.4.dist-info}/RECORD

@@ -22,6 +22,6 @@ appkit_assistant/components/threadlist.py,sha256=NKB9GshghdSlUY2hVIRdhX9nxd6mxJe
 appkit_assistant/components/tools_modal.py,sha256=gThgOzYa_r74IHWEKxmmT85c2MiHLIhOFtiV9IT_r3E,3355
 appkit_assistant/state/mcp_server_state.py,sha256=L5r3Bd_OzFh_kgWH81cKVBWhE3Ys6m8TsJs2vadCWhU,7945
 appkit_assistant/state/thread_state.py,sha256=h8jmE0hZmSWJ5-D4EqxBTO0ydBSNa9IxUTa5tfYdkMk,32618
-appkit_assistant-0.7.3.dist-info/METADATA,sha256=tGfeVHTUrVIoJds2L5-4ZXOD-nPF_bbbDGTjq00Ecmo,202
-appkit_assistant-0.7.3.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-appkit_assistant-0.7.3.dist-info/RECORD,,
+appkit_assistant-0.7.4.dist-info/METADATA,sha256=-UtfwMPp-C-2INeT7AgLVvu8I-LAPXgjGGjRLU_nnzY,8123
+appkit_assistant-0.7.4.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+appkit_assistant-0.7.4.dist-info/RECORD,,

appkit_assistant-0.7.3.dist-info/METADATA

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