MaxKB

MaxKB implements a document ingestion pipeline that parses uploaded files (PDF, Word, Markdown, etc.), chunks content into paragraphs, generates vector embeddings using PGVector-backed PostgreSQL, and indexes them for semantic retrieval. The system uses Celery for asynchronous batch embedding tasks, enabling non-blocking document processing at scale. Paragraph-level granularity allows fine-grained retrieval and citation tracking.

MaxKB abstracts multiple LLM providers (OpenAI, Anthropic, Ollama, DeepSeek, Qwen, Llama3) through a unified interface that handles provider-specific API contracts, token counting, and streaming response aggregation. The chat system implements server-sent events (SSE) for real-time token streaming to clients, with built-in fallback handling if a provider fails. Model configuration is stored per-workspace, enabling multi-tenant model isolation.

MaxKB implements a batch processing system for document embedding using Celery task queues. When documents are uploaded to a knowledge base, embedding tasks are queued asynchronously. The system tracks the status of each batch (pending, processing, completed, failed) and provides progress updates via WebSocket or polling. Failed embeddings can be retried with exponential backoff. Batch operations are idempotent; re-processing the same document doesn't create duplicates.

MaxKB provides a centralized model management interface where users configure LLM providers (OpenAI, Anthropic, Ollama, DeepSeek, Qwen, Llama3) with API keys and model parameters. Credentials are encrypted at rest and never logged. The system validates provider connectivity on configuration and provides fallback options if a provider fails. Model configurations are workspace-scoped, enabling different teams to use different providers.

MaxKB provides a visual workflow designer where users compose multi-step AI tasks using nodes (LLM, tool execution, conditional logic, data transformation). The workflow execution engine interprets the node graph, manages state between steps, handles branching based on conditions, and supports error recovery. Workflows can chain LLM calls with tool execution, knowledge base retrieval, and custom code execution in a DAG-like structure.

MaxKB allows users to define custom tools by uploading Python code that runs in an isolated sandbox environment. The sandbox uses a C library (sandbox.so) to intercept system calls, preventing malicious code from accessing the filesystem, network, or process management. Tool execution is async and integrated into workflows, allowing LLMs to call custom logic (e.g., database queries, API transformations) safely.

MaxKB implements workspace-level multi-tenancy where each workspace has isolated data (knowledge bases, applications, workflows, models). Access control is enforced through role-based permissions (admin, editor, viewer) with granular resource-level checks. User authentication supports LDAP, OAuth2, and local credentials. Workspace membership and permissions are stored in PostgreSQL with audit logging of all permission changes.

MaxKB implements vector-based semantic search using PGVector embeddings combined with optional keyword/BM25 matching for hybrid retrieval. When a user query arrives, it's embedded and compared against indexed paragraphs using cosine similarity. Results are ranked by relevance score and returned with source document metadata. The system supports filtering by document, knowledge base, or custom metadata tags.

MaxKB maintains persistent chat sessions with full message history, including user inputs, LLM responses, tool calls, and knowledge base citations. Sessions are stored per-application and can be accessed via web UI, mobile app, or API. The system supports session branching (creating alternative conversation paths) and message editing with automatic re-generation of downstream responses. Chat context is managed per-session to avoid token limit overflow.

MaxKB allows users to upload files (images, PDFs, audio) and audio files are automatically transcribed to text using speech-to-text models. Uploaded files are stored in a file service (local filesystem or S3-compatible storage) and can be referenced in chat messages. Images are processed for OCR if needed, and PDFs can be added directly to knowledge bases. File metadata (size, type, upload timestamp) is tracked for audit purposes.

MaxKB implements the Model Context Protocol (MCP) standard, allowing it to act as an MCP server that exposes tools to LLM clients. Tools are discovered dynamically via MCP, and their schemas are registered with the LLM for function calling. When an LLM decides to call a tool, MaxKB executes it (either as a sandboxed Python function or an external API call) and returns the result to the LLM. This enables seamless tool integration without hardcoding tool definitions.

MaxKB allows users to create applications (chatbots, agents) with customizable chat pipelines. Each application has a configuration that specifies the LLM model, system prompt, knowledge base to use, tools to enable, and workflow to execute. The chat pipeline orchestrates the flow: user input → knowledge base retrieval → LLM reasoning → tool execution → response generation. Applications can be deployed as web widgets, APIs, or standalone interfaces.