appkit-assistant 0.13.0__tar.gz

appkit_assistant-0.13.0/.gitignore

@@ -0,0 +1,114 @@
+__pycache__/
+__pypackages__/
+.cache
+.coverage
+.coverage.*
+.dmypy.json
+.DS_Store
+.eggs/
+.env
+.env.backup
+.env.docker
+.hypothesis/
+.idea/
+.installed.cfg
+.ipynb_checkpoints
+.mypy_cache/
+.nox/
+.pdm.toml
+.pybuilder/
+.pyre/
+.pytest_cache/
+.Python
+.python_packages
+.pytype/
+.ropeproject
+.scrapy
+.spyderproject
+.spyproject
+.states
+.tox/
+.venv
+.venv.mac
+.web
+.webassets-cache
+*.bak
+*.cover
+*.db
+*.egg
+*.egg-info/
+*.kv-env.*
+*.log
+*.manifest
+*.mo
+*.pot
+*.py,cover
+*.py[cod]
+*.sage.py
+*.so
+*.spec
+*.terraform.lock.hcl
+*.tfplan
+*.tfstate
+*.tfstate.*.backup
+*.tfstate.backup
+*.tfvars
+**/.terraform/*
+*$py.class
+/site
+/vectorstore/
+aila-storage/
+assets/external/
+build/
+celerybeat-schedule
+celerybeat.pid
+configuration/config.abaz009.yaml
+configuration/config.bubb001.yaml
+configuration/config.stie104.yaml
+configuration/config.voro047.yaml
+connector examples/sharepoint.json
+cover/
+coverage.xml
+cython_debug/
+db.sqlite3
+db.sqlite3-journal
+develop-eggs/
+dist/
+dmypy.json
+docs/_build/
+Documents/
+downloads/
+eggs/
+env.bak/
+env/
+ENV/
+htmlcov/
+instance/
+ipython_config.py
+knowledge/migrate.py
+lib/
+lib64/
+local_settings.py
+local.settings.json
+MANIFEST
+nosetests.xml
+out
+parts/
+pip-delete-this-directory.txt
+pip-log.txt
+Pipfile
+profile_default/
+sdist/
+share/python-wheels/
+sketchpad/
+sketchpad/
+stores/
+target/
+tests/mcp_test.py
+tmp.txt
+uploaded_files/
+uploads/
+var/
+venv.bak/
+venv/
+wheels/

appkit_assistant-0.13.0/PKG-INFO

@@ -0,0 +1,345 @@
+Metadata-Version: 2.4
+Name: appkit-assistant
+Version: 0.13.0
+Summary: Add your description here
+Project-URL: Homepage, https://github.com/jenreh/appkit
+Project-URL: Documentation, https://github.com/jenreh/appkit/tree/main/docs
+Project-URL: Repository, https://github.com/jenreh/appkit
+Project-URL: Issues, https://github.com/jenreh/appkit/issues
+Author: Jens Rehpöhler
+License: MIT
+Keywords: components,mantine,reflex,ui,web
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: User Interfaces
+Requires-Python: >=3.13
+Requires-Dist: appkit-commons
+Requires-Dist: appkit-mantine
+Requires-Dist: appkit-ui
+Requires-Dist: openai>=2.3.0
+Requires-Dist: reflex>=0.8.22
+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](https://raw.githubusercontent.com/jenreh/appkit/refs/heads/main/components/appkit-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