MaxKB

MaxKB implements a document ingestion pipeline that processes uploaded files (PDF, Word, TXT, Markdown) into paragraph-level chunks, generates vector embeddings using configurable embedding models (BERT-based or API-backed), and stores them in PostgreSQL with pgvector extension for semantic search. The system handles batch vectorization asynchronously via Celery workers, tracks embedding status per document, and supports incremental re-indexing when documents are updated. Paragraph management includes problem-solution pairing for enhanced retrieval context.

MaxKB abstracts multiple LLM providers (OpenAI, Anthropic, Ollama, Qwen, DeepSeek, Llama3) behind a unified model configuration interface. The system stores provider credentials securely, supports model-specific parameters (temperature, max_tokens, system prompts), and routes inference requests through provider-specific adapters built on LangChain. Model configurations are workspace-scoped and can be switched at runtime without code changes. The architecture supports both cloud-hosted and self-hosted models (via Ollama).

MaxKB implements content filtering and prompt injection detection before sending user messages to LLMs. The system uses pattern matching and heuristics to detect common prompt injection techniques (e.g., 'ignore previous instructions', 'system prompt override'). Filtered messages are logged for analysis. The system also supports custom content filters per workspace. Responses from LLMs are optionally filtered for sensitive content (PII, profanity) before returning to users.

MaxKB logs all significant operations (create, update, delete, execute) with user attribution, timestamp, resource ID, and operation details. Audit logs are stored in PostgreSQL and queryable via API. The system supports filtering logs by user, resource type, operation type, and date range. Audit logs are immutable (append-only) and cannot be deleted by regular users. This enables compliance auditing and forensic analysis of system changes.

MaxKB implements internationalization (i18n) via Django's translation framework, supporting multiple languages (English, Chinese, etc.) in the UI. Language selection is per-user and persisted in user preferences. The system uses gettext for translation string extraction and management. Frontend components use i18n libraries (Vue i18n) to render translated strings. API responses include language-specific content (error messages, labels). This enables global deployment without separate language-specific instances.

MaxKB implements a visual workflow designer backed by a node-based execution engine that supports sequential and conditional execution paths. Workflow nodes include LLM inference, tool calling, knowledge base retrieval, code execution, and branching logic. The engine executes workflows via a state machine pattern, passing context between nodes and supporting loops and error handling. Workflows are stored as JSON definitions and executed asynchronously via Celery, with execution history and step-level logging for debugging. Tool nodes integrate with the code sandbox for safe custom code execution.

MaxKB provides a secure code execution environment for custom tools via a C-based sandbox (sandbox.so) that intercepts system calls and restricts file system access, network calls, and process spawning. Python code submitted as tool definitions is executed within this sandbox, allowing builders to extend agent capabilities with custom logic while preventing malicious code from accessing sensitive resources. The ToolExecutor class manages code compilation, sandboxing, and error handling. Execution results are captured and returned to the workflow engine.

MaxKB implements workspace-scoped multi-tenancy where each workspace is an isolated container for applications, knowledge bases, models, and users. Access control is enforced via role-based permissions (admin, editor, viewer) with fine-grained resource-level checks. User authentication uses JWT tokens, and workspace membership is tracked in a separate relation. The system supports workspace-level configuration (model defaults, embedding settings) and audit logging of all operations. Workspace data is logically isolated in the database but shares the same PostgreSQL instance.

MaxKB implements a streaming chat interface that delivers LLM responses token-by-token to clients via Server-Sent Events (SSE) or WebSocket, providing real-time feedback without waiting for full response generation. The chat system supports multiple platforms (web, mobile, embedded widgets) via a unified backend API. Chat messages are persisted with full history, and the system supports file uploads and speech-to-text transcription within chat sessions. Message processing includes prompt injection detection and content filtering before sending to LLM.

MaxKB integrates with the Model Context Protocol (MCP) standard, allowing agents to discover and invoke tools via a standardized interface. The system exposes MaxKB tools (knowledge base search, workflow execution) as MCP resources and supports external MCP servers for third-party integrations. Tool schemas are automatically generated from function signatures and validated before execution. This enables interoperability with other MCP-compatible systems and reduces vendor lock-in for tool definitions.

MaxKB uses Celery for asynchronous task processing, offloading long-running operations (document embedding, workflow execution, batch operations) from the request-response cycle. Tasks are queued in Redis or RabbitMQ and executed by worker processes, with status tracking and result storage. The system supports task retries, timeouts, and error callbacks. Embedding tasks are prioritized and can be monitored via a task status API. This architecture enables responsive UI even during heavy processing loads.

MaxKB implements hybrid search combining semantic similarity (via vector embeddings) and keyword matching to retrieve relevant paragraphs from the knowledge base. The search engine queries pgvector for semantic matches and PostgreSQL full-text search for keyword matches, then ranks results by relevance. Search results include source document metadata and paragraph context. The system supports filtering by document, knowledge base, or custom metadata. Reranking can be applied via LLM to improve result quality.

MaxKB allows builders to create applications (agents, chatbots) with configurable settings (model, knowledge base, system prompt, tools) and deploy them across multiple channels (web chat, API, embedded widget, Slack, WeChat). Each application has a unique configuration stored in the database and can be published to different channels with channel-specific settings. Applications can be versioned and rolled back. The system generates shareable links and API endpoints for each application.