appkit-assistant

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

✨ 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
System Prompt Management - Versioned system prompts with admin editor interface
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:

git clone https://github.com/jenreh/appkit.git
cd appkit
uv sync

Standalone Installation

Install from PyPI:

pip install appkit-assistant

Or with uv:

uv add appkit-assistant

Dependencies

appkit-commons (shared utilities)
openai>=2.3.0 (OpenAI API client)

🏁 Quick Start

Basic Setup

Configure your API keys in your application's configuration:

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"
)

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))

Use the assistant component in your Reflex app:

import reflex as rx
from appkit_assistant.components import Assistant

def assistant_page():
    return rx.container(
        Assistant(),
        height="100vh"
    )

📖 Usage

Model Management

The ModelManager singleton handles all AI processors and models:

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:

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:

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:

from appkit_assistant.components import Assistant

def chat_page():
    return Assistant()

Individual Components

Use individual components for custom layouts:

import reflex as rx
from appkit_assistant.components import ThreadList, composer

def custom_assistant():
    return mn.stack(
        ThreadList(),
        composer(),
        spacing="4"
    )

MCP Server Management UI

Display and manage MCP servers:

from appkit_assistant.components import mcp_servers_table

def servers_page():
    return mcp_servers_table()

System Prompt Editor

Admin interface for managing versioned system prompts:

from appkit_assistant.components.system_prompt_editor import system_prompt_editor

def prompt_editor_page():
    return system_prompt_editor()

🔧 Configuration

AssistantConfig

Configure API keys and settings:

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

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
system_prompt_editor - Admin interface for system prompts

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:

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:

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 - UI components used in the assistant interface
appkit-user - User authentication and authorization
appkit-commons - Shared utilities and configuration

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

appkit_assistant-1.13.1.tar.gz (1.9 MB view details)

Uploaded Jul 8, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

appkit_assistant-1.13.1-py3-none-any.whl (213.1 kB view details)

Uploaded Jul 8, 2026 Python 3

File details

Details for the file appkit_assistant-1.13.1.tar.gz.

File metadata

Download URL: appkit_assistant-1.13.1.tar.gz
Upload date: Jul 8, 2026
Size: 1.9 MB
Tags: Source
Uploaded using Trusted Publishing? No
Uploaded via: uv/0.11.28 {"installer":{"name":"uv","version":"0.11.28","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

File hashes

Hashes for appkit_assistant-1.13.1.tar.gz
Algorithm	Hash digest
SHA256	`23d0b02e8161cf017a198271567cc313ec563c0ced45680d68418a7483adbebf`
MD5	`4c1b09989967af57f3998240a742f0e6`
BLAKE2b-256	`3c2f34dfbc594f49e8d70fbcf97222c43e7282afb9b5a1c26efabb119f28906d`

See more details on using hashes here.

File details

Details for the file appkit_assistant-1.13.1-py3-none-any.whl.

File metadata

Download URL: appkit_assistant-1.13.1-py3-none-any.whl
Upload date: Jul 8, 2026
Size: 213.1 kB
Tags: Python 3
Uploaded using Trusted Publishing? No
Uploaded via: uv/0.11.28 {"installer":{"name":"uv","version":"0.11.28","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

File hashes

Hashes for appkit_assistant-1.13.1-py3-none-any.whl
Algorithm	Hash digest
SHA256	`070e23c92b768d5ba2e6b2e87218d7c2c1d59d06e64edfd3396b8285eaaf6b87`
MD5	`c3c36e575f7326726d545834fa84a5d6`
BLAKE2b-256	`8a74c24d9e5783ca718de18337c7305ef2e357e507e9431fb5ea2ab696b52bfc`