@djangocfg/ext-knowbase 1.0.0

package/src/components/Chat/types.ts

@@ -0,0 +1,81 @@
+/**
+ * Chat Types
+ * Type definitions for RAG-powered chat widget
+ */
+
+// Import types from local generated API
+import { ExtKnowbaseKnowbaseTypes, Enums as GeneratedEnums } from '../../api/generated/ext_knowbase';
+
+// ============================================================================
+// Extract types from generated API
+export const Enums = GeneratedEnums;
+export type ChatMessage = ExtKnowbaseKnowbaseTypes.ChatMessage;
+export type ChatSource = ExtKnowbaseKnowbaseTypes.ChatSource;
+
+// ─────────────────────────────────────────────────────────────────────────
+// Extended Message Type (for UI with sources)
+// ─────────────────────────────────────────────────────────────────────────
+
+export interface ChatMessageWithSources extends ChatMessage {
+  sources?: ChatSource[];
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// Widget Props
+// ─────────────────────────────────────────────────────────────────────────
+
+export interface ChatWidgetProps {
+  /** Whether to auto-open on mount */
+  autoOpen?: boolean;
+  /** Render even when closed (for animations) */
+  persistent?: boolean;
+  /** Additional CSS classes */
+  className?: string;
+  /** Callback when toggle state changes */
+  onToggle?: (isOpen: boolean) => void;
+  /** Callback when message is sent */
+  onMessage?: (message: ChatMessageWithSources) => void;
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// UI State
+// ─────────────────────────────────────────────────────────────────────────
+
+export interface ChatUIState {
+  isOpen: boolean;
+  isExpanded: boolean;
+  isMinimized: boolean;
+  showSources: boolean;
+  showTimestamps: boolean;
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// Component Props
+// ─────────────────────────────────────────────────────────────────────────
+
+export interface MessageListProps {
+  messages: ChatMessageWithSources[];
+  isLoading?: boolean;
+  showSources?: boolean;
+  showTimestamps?: boolean;
+  autoScroll?: boolean;
+  className?: string;
+}
+
+export interface MessageInputProps {
+  onSend: (message: string) => Promise<void>;
+  isLoading?: boolean;
+  disabled?: boolean;
+  placeholder?: string;
+  className?: string;
+}
+
+export interface SessionListProps {
+  isOpen: boolean;
+  onClose: () => void;
+  onSelectSession: (sessionId: string) => void;
+  className?: string;
+}
+
+
+

package/src/config.ts

@@ -0,0 +1,20 @@
+/**
+ * Knowledge Base extension configuration
+ */
+
+import type { ExtensionMetadata } from '@djangocfg/ext-base';
+
+export const extensionConfig: ExtensionMetadata = {
+  name: 'knowbase',
+  version: '1.0.0',
+  author: 'DjangoCFG',
+  displayName: 'Knowledge Base',
+  description: 'Knowledge base and documentation management system',
+  icon: '📚',
+  license: 'MIT',
+  githubUrl: 'https://github.com/markolofsen/django-cfg',
+  homepage: 'https://djangocfg.com',
+  keywords: ['knowledge-base', 'documentation', 'articles', 'help', 'faq'],
+  dependencies: [],
+  minVersion: '2.0.0',
+} as const;

package/src/contexts/knowbase/ChatContext.tsx

@@ -0,0 +1,173 @@
+/**
+ * Knowbase Chat Context
+ * Context for RAG-powered chat functionality
+ */
+
+'use client';
+
+import React, { createContext, useContext, type ReactNode } from 'react';
+
+import { apiKnowbase } from '../../api';
+import {
+  useKnowbaseAdminChatList,
+  useKnowbaseAdminChatRetrieve,
+  useCreateKnowbaseAdminChatCreate,
+  useUpdateKnowbaseAdminChatUpdate,
+  usePartialUpdateKnowbaseAdminChatPartialUpdate,
+  useDeleteKnowbaseAdminChatDestroy,
+  useKnowbaseAdminChatHistoryRetrieve,
+  useCreateKnowbaseAdminChatQueryCreate,
+} from '../../api/generated/ext_knowbase/_utils/hooks';
+import type {
+  PaginatedChatResponseList,
+  ChatResponse,
+  ChatResponseRequest,
+  PatchedChatResponseRequest,
+  ChatHistory,
+  ChatQueryRequest,
+} from './types';
+
+// ─────────────────────────────────────────────────────────────────────────
+// Context Type
+// ─────────────────────────────────────────────────────────────────────────
+
+export interface KnowbaseChatContextValue {
+  // Chat list
+  chats: PaginatedChatResponseList | undefined;
+  isLoadingChats: boolean;
+  chatsError: Error | undefined;
+  refreshChats: () => Promise<void>;
+
+  // Chat operations
+  getChat: (id: string) => Promise<ChatResponse | undefined>;
+  getChatHistory: (id: string) => Promise<ChatHistory | undefined>;
+  createChat: (data: ChatResponseRequest) => Promise<ChatResponse>;
+  updateChat: (id: string, data: ChatResponseRequest) => Promise<ChatResponse>;
+  partialUpdateChat: (id: string, data: PatchedChatResponseRequest) => Promise<ChatResponse>;
+  deleteChat: (id: string) => Promise<void>;
+
+  // RAG Query
+  sendQuery: (data: ChatQueryRequest) => Promise<ChatResponse>;
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// Context
+// ─────────────────────────────────────────────────────────────────────────
+
+const KnowbaseChatContext = createContext<KnowbaseChatContextValue | undefined>(undefined);
+
+// ─────────────────────────────────────────────────────────────────────────
+// Provider
+// ─────────────────────────────────────────────────────────────────────────
+
+export function KnowbaseChatProvider({ children }: { children: ReactNode }) {
+  // List chats
+  const {
+    data: chats,
+    error: chatsError,
+    isLoading: isLoadingChats,
+    mutate: mutateChats,
+  } = useKnowbaseAdminChatList({}, apiKnowbase);
+
+  const refreshChats = async () => {
+    await mutateChats();
+  };
+
+  // Mutations
+  const createChatMutation = useCreateKnowbaseAdminChatCreate();
+  const updateChatMutation = useUpdateKnowbaseAdminChatUpdate();
+  const partialUpdateChatMutation = usePartialUpdateKnowbaseAdminChatPartialUpdate();
+  const deleteChatMutation = useDeleteKnowbaseAdminChatDestroy();
+  const sendQueryMutation = useCreateKnowbaseAdminChatQueryCreate();
+
+  // Get single chat
+  const getChat = async (id: string): Promise<ChatResponse | undefined> => {
+    const { data } = useKnowbaseAdminChatRetrieve(id, apiKnowbase);
+    return data;
+  };
+
+  // Get chat history
+  const getChatHistory = async (id: string): Promise<ChatHistory | undefined> => {
+    const { data } = useKnowbaseAdminChatHistoryRetrieve(id, apiKnowbase);
+    return data;
+  };
+
+  // Create chat
+  const createChat = async (data: ChatResponseRequest): Promise<ChatResponse> => {
+    const result = await createChatMutation(data, apiKnowbase);
+    await refreshChats();
+    return result as ChatResponse;
+  };
+
+  // Update chat
+  const updateChat = async (id: string, data: ChatResponseRequest): Promise<ChatResponse> => {
+    const result = await updateChatMutation(id, data, apiKnowbase);
+    await refreshChats();
+    return result as ChatResponse;
+  };
+
+  // Partial update chat
+  const partialUpdateChat = async (
+    id: string,
+    data: PatchedChatResponseRequest
+  ): Promise<ChatResponse> => {
+    const result = await partialUpdateChatMutation(id, data, apiKnowbase);
+    await refreshChats();
+    return result as ChatResponse;
+  };
+
+  // Delete chat
+  const deleteChat = async (id: string): Promise<void> => {
+    await deleteChatMutation(id, apiKnowbase);
+    await refreshChats();
+  };
+
+  // Send RAG query
+  const sendQuery = async (data: ChatQueryRequest): Promise<ChatResponse> => {
+    const result = await sendQueryMutation(data, apiKnowbase);
+    await refreshChats();
+    return result as ChatResponse;
+  };
+
+  const value: KnowbaseChatContextValue = {
+    chats,
+    isLoadingChats,
+    chatsError,
+    refreshChats,
+    getChat,
+    getChatHistory,
+    createChat,
+    updateChat,
+    partialUpdateChat,
+    deleteChat,
+    sendQuery,
+  };
+
+  return <KnowbaseChatContext.Provider value={value}>{children}</KnowbaseChatContext.Provider>;
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// Hook
+// ─────────────────────────────────────────────────────────────────────────
+
+export function useKnowbaseChatContext(): KnowbaseChatContextValue {
+  const context = useContext(KnowbaseChatContext);
+  if (!context) {
+    throw new Error('useKnowbaseChatContext must be used within KnowbaseChatProvider');
+  }
+  return context;
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// Re-export types for external use
+// ─────────────────────────────────────────────────────────────────────────
+
+export type {
+  PaginatedChatResponseList,
+  ChatResponse,
+  ChatResponseRequest,
+  PatchedChatResponseRequest,
+  ChatHistory,
+  ChatQueryRequest,
+} from './types';
+

package/src/contexts/knowbase/DocumentsContext.tsx

@@ -0,0 +1,306 @@
+/**
+ * Knowbase Documents Context
+ * Context for managing documents and archives
+ */
+
+'use client';
+
+import React, { createContext, useContext, type ReactNode } from 'react';
+
+import { apiKnowbase } from '../../api';
+import {
+  useKnowbaseAdminDocumentsList,
+  useKnowbaseAdminDocumentsRetrieve,
+  useCreateKnowbaseAdminDocumentsCreate,
+  useUpdateKnowbaseAdminDocumentsUpdate,
+  usePartialUpdateKnowbaseAdminDocumentsPartialUpdate,
+  useDeleteKnowbaseAdminDocumentsDestroy,
+  useCreateKnowbaseAdminDocumentsReprocessCreate,
+  useKnowbaseAdminDocumentsStatusRetrieve,
+  useKnowbaseAdminDocumentsStatsRetrieve,
+  useKnowbaseSystemArchivesList,
+  useKnowbaseSystemArchivesRetrieve,
+  useCreateKnowbaseSystemArchivesCreate,
+  useUpdateKnowbaseSystemArchivesUpdate,
+  usePartialUpdateKnowbaseSystemArchivesPartialUpdate,
+  useDeleteKnowbaseSystemArchivesDestroy,
+  useKnowbaseSystemArchivesStatisticsRetrieve,
+} from '../../api/generated/ext_knowbase/_utils/hooks';
+import type {
+  PaginatedDocumentList,
+  Document,
+  DocumentCreateRequest,
+  DocumentRequest,
+  PatchedDocumentRequest,
+  DocumentProcessingStatus,
+  DocumentStats,
+  PaginatedDocumentArchiveListList,
+  DocumentArchive,
+  DocumentArchiveDetail,
+  PatchedDocumentArchiveRequest,
+  ArchiveProcessingResult,
+  ArchiveStatistics,
+} from './types';
+
+// ─────────────────────────────────────────────────────────────────────────
+// Context Type
+// ─────────────────────────────────────────────────────────────────────────
+
+export interface KnowbaseDocumentsContextValue {
+  // Documents list
+  documents: PaginatedDocumentList | undefined;
+  isLoadingDocuments: boolean;
+  documentsError: Error | undefined;
+  refreshDocuments: () => Promise<void>;
+
+  // Document operations
+  getDocument: (id: string) => Promise<Document | undefined>;
+  getDocumentStatus: (id: string) => Promise<DocumentProcessingStatus | undefined>;
+  getDocumentStats: () => Promise<DocumentStats | undefined>;
+  createDocument: (data: DocumentCreateRequest) => Promise<Document>;
+  updateDocument: (id: string, data: DocumentRequest) => Promise<Document>;
+  partialUpdateDocument: (id: string, data: PatchedDocumentRequest) => Promise<Document>;
+  deleteDocument: (id: string) => Promise<void>;
+  reprocessDocument: (id: string, data: DocumentRequest) => Promise<Document>;
+
+  // Archives list
+  archives: PaginatedDocumentArchiveListList | undefined;
+  isLoadingArchives: boolean;
+  archivesError: Error | undefined;
+  refreshArchives: () => Promise<void>;
+
+  // Archive operations
+  getArchive: (id: string) => Promise<DocumentArchiveDetail | undefined>;
+  getArchiveStatistics: () => Promise<ArchiveStatistics | undefined>;
+  createArchive: (data: FormData) => Promise<ArchiveProcessingResult>;
+  updateArchive: (
+    id: string,
+    title: string,
+    archive_file: File | Blob,
+    description?: string,
+    is_public?: boolean
+  ) => Promise<DocumentArchive>;
+  partialUpdateArchive: (id: string, data: PatchedDocumentArchiveRequest) => Promise<DocumentArchive>;
+  deleteArchive: (id: string) => Promise<void>;
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// Context
+// ─────────────────────────────────────────────────────────────────────────
+
+const KnowbaseDocumentsContext = createContext<KnowbaseDocumentsContextValue | undefined>(
+  undefined
+);
+
+// ─────────────────────────────────────────────────────────────────────────
+// Provider
+// ─────────────────────────────────────────────────────────────────────────
+
+export function KnowbaseDocumentsProvider({ children }: { children: ReactNode }) {
+  // Documents list (first page only for count)
+  const {
+    data: documents,
+    error: documentsError,
+    isLoading: isLoadingDocuments,
+    mutate: mutateDocuments,
+  } = useKnowbaseAdminDocumentsList({ page: 1, page_size: 1 }, apiKnowbase);
+
+  const refreshDocuments = async () => {
+    await mutateDocuments();
+  };
+
+  // Archives list (first page only for count)
+  const {
+    data: archives,
+    error: archivesError,
+    isLoading: isLoadingArchives,
+    mutate: mutateArchives,
+  } = useKnowbaseSystemArchivesList({ page: 1, page_size: 1 }, apiKnowbase);
+
+  const refreshArchives = async () => {
+    await mutateArchives();
+  };
+
+  // Document mutations
+  const createDocumentMutation = useCreateKnowbaseAdminDocumentsCreate();
+  const updateDocumentMutation = useUpdateKnowbaseAdminDocumentsUpdate();
+  const partialUpdateDocumentMutation = usePartialUpdateKnowbaseAdminDocumentsPartialUpdate();
+  const deleteDocumentMutation = useDeleteKnowbaseAdminDocumentsDestroy();
+  const reprocessDocumentMutation = useCreateKnowbaseAdminDocumentsReprocessCreate();
+
+  // Archive mutations
+  const createArchiveMutation = useCreateKnowbaseSystemArchivesCreate();
+  const updateArchiveMutation = useUpdateKnowbaseSystemArchivesUpdate();
+  const partialUpdateArchiveMutation = usePartialUpdateKnowbaseSystemArchivesPartialUpdate();
+  const deleteArchiveMutation = useDeleteKnowbaseSystemArchivesDestroy();
+
+  // Get single document
+  const getDocument = async (id: string): Promise<Document | undefined> => {
+    const { data } = useKnowbaseAdminDocumentsRetrieve(id, apiKnowbase);
+    return data;
+  };
+
+  // Get document status
+  const getDocumentStatus = async (id: string): Promise<DocumentProcessingStatus | undefined> => {
+    const { data } = useKnowbaseAdminDocumentsStatusRetrieve(id, apiKnowbase);
+    return data;
+  };
+
+  // Get document stats
+  const getDocumentStats = async (): Promise<DocumentStats | undefined> => {
+    const { data } = useKnowbaseAdminDocumentsStatsRetrieve(apiKnowbase);
+    return data;
+  };
+
+  // Create document
+  const createDocument = async (data: DocumentCreateRequest): Promise<Document> => {
+    const result = await createDocumentMutation(data, apiKnowbase);
+    await refreshDocuments();
+    return result as Document;
+  };
+
+  // Update document
+  const updateDocument = async (id: string, data: DocumentRequest): Promise<Document> => {
+    const result = await updateDocumentMutation(id, data, apiKnowbase);
+    await refreshDocuments();
+    return result as Document;
+  };
+
+  // Partial update document
+  const partialUpdateDocument = async (
+    id: string,
+    data: PatchedDocumentRequest
+  ): Promise<Document> => {
+    const result = await partialUpdateDocumentMutation(id, data, apiKnowbase);
+    await refreshDocuments();
+    return result as Document;
+  };
+
+  // Delete document
+  const deleteDocument = async (id: string): Promise<void> => {
+    await deleteDocumentMutation(id, apiKnowbase);
+    await refreshDocuments();
+  };
+
+  // Reprocess document
+  const reprocessDocument = async (id: string, data: DocumentRequest): Promise<Document> => {
+    const result = await reprocessDocumentMutation(id, data, apiKnowbase);
+    await refreshDocuments();
+    return result as Document;
+  };
+
+  // Get single archive
+  const getArchive = async (id: string): Promise<DocumentArchiveDetail | undefined> => {
+    const { data } = useKnowbaseSystemArchivesRetrieve(id, apiKnowbase);
+    return data as DocumentArchiveDetail | undefined;
+  };
+
+  // Get archive statistics
+  const getArchiveStatistics = async (): Promise<ArchiveStatistics | undefined> => {
+    const { data } = useKnowbaseSystemArchivesStatisticsRetrieve(apiKnowbase);
+    return data;
+  };
+
+  // Create archive
+  const createArchive = async (data: FormData): Promise<ArchiveProcessingResult> => {
+    const result = await createArchiveMutation(data, apiKnowbase);
+    await refreshArchives();
+    return result as unknown as ArchiveProcessingResult;
+  };
+
+  // Update archive
+  const updateArchive = async (
+    id: string,
+    title: string,
+    archive_file: File | Blob,
+    description?: string,
+    is_public?: boolean
+  ): Promise<DocumentArchive> => {
+    // Note: The hook expects DocumentArchiveRequest, but the client method has different signature
+    // This is a type mismatch in the generated code
+    const data = { title, archive_file, description, is_public } as any;
+    const result = await updateArchiveMutation(id, data, apiKnowbase);
+    await refreshArchives();
+    return result as unknown as DocumentArchive;
+  };
+
+  // Partial update archive
+  const partialUpdateArchive = async (
+    id: string,
+    data: PatchedDocumentArchiveRequest
+  ): Promise<DocumentArchive> => {
+    const result = await partialUpdateArchiveMutation(id, data, apiKnowbase);
+    await refreshArchives();
+    return result as unknown as DocumentArchive;
+  };
+
+  // Delete archive
+  const deleteArchive = async (id: string): Promise<void> => {
+    await deleteArchiveMutation(id, apiKnowbase);
+    await refreshArchives();
+  };
+
+  const value: KnowbaseDocumentsContextValue = {
+    documents,
+    isLoadingDocuments,
+    documentsError,
+    refreshDocuments,
+    getDocument,
+    getDocumentStatus,
+    getDocumentStats,
+    createDocument,
+    updateDocument,
+    partialUpdateDocument,
+    deleteDocument,
+    reprocessDocument,
+    archives: archives as PaginatedDocumentArchiveListList | undefined,
+    isLoadingArchives,
+    archivesError,
+    refreshArchives,
+    getArchive,
+    getArchiveStatistics,
+    createArchive,
+    updateArchive,
+    partialUpdateArchive,
+    deleteArchive,
+  };
+
+  return (
+    <KnowbaseDocumentsContext.Provider value={value}>
+      {children}
+    </KnowbaseDocumentsContext.Provider>
+  );
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// Hook
+// ─────────────────────────────────────────────────────────────────────────
+
+export function useKnowbaseDocumentsContext(): KnowbaseDocumentsContextValue {
+  const context = useContext(KnowbaseDocumentsContext);
+  if (!context) {
+    throw new Error('useKnowbaseDocumentsContext must be used within KnowbaseDocumentsProvider');
+  }
+  return context;
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// Re-export types for external use
+// ─────────────────────────────────────────────────────────────────────────
+
+export type {
+  PaginatedDocumentList,
+  Document,
+  DocumentCreateRequest,
+  DocumentRequest,
+  PatchedDocumentRequest,
+  DocumentProcessingStatus,
+  DocumentStats,
+  PaginatedDocumentArchiveListList,
+  DocumentArchive,
+  DocumentArchiveDetail,
+  PatchedDocumentArchiveRequest,
+  ArchiveProcessingResult,
+  ArchiveStatistics,
+} from './types';
+

package/src/contexts/knowbase/KnowbaseProvider.tsx

@@ -0,0 +1,47 @@
+/**
+ * Main Knowbase Provider
+ *
+ * Wraps all knowbase contexts with ExtensionProvider for proper registration
+ */
+
+'use client';
+
+import type { ReactNode } from 'react';
+import { ExtensionProvider } from '@djangocfg/ext-base/hooks';
+import { extensionConfig } from '../../config';
+import { KnowbaseChatProvider } from './ChatContext';
+import { KnowbaseDocumentsProvider } from './DocumentsContext';
+import { KnowbaseSessionsProvider } from './SessionsContext';
+
+interface KnowbaseProviderProps {
+  children: ReactNode;
+}
+
+/**
+ * Main provider for Knowledge Base extension
+ *
+ * Provides all knowbase contexts:
+ * - Chat context (RAG-powered chat)
+ * - Documents context (document management)
+ * - Sessions context (chat sessions)
+ *
+ * @example
+ * ```tsx
+ * <KnowbaseProvider>
+ *   <YourApp />
+ * </KnowbaseProvider>
+ * ```
+ */
+export function KnowbaseProvider({ children }: KnowbaseProviderProps) {
+  return (
+    <ExtensionProvider metadata={extensionConfig}>
+      <KnowbaseDocumentsProvider>
+        <KnowbaseSessionsProvider>
+          <KnowbaseChatProvider>
+            {children}
+          </KnowbaseChatProvider>
+        </KnowbaseSessionsProvider>
+      </KnowbaseDocumentsProvider>
+    </ExtensionProvider>
+  );
+}