@orkg/scidquest 1.0.5 → 1.1.4

package/dist/lib/components/ResearchQuestionnaireApp.d.ts

@@ -0,0 +1,32 @@
+import React from 'react';
+import type { QuestionnaireTemplate } from '../types';
+import type { StructuredDocument } from '../../utils/structuredPdfExtractor';
+import { type ResearchQuestionnaireWorkspaceValue } from '../research-questionnaire-workspace';
+export interface ResearchQuestionnaireAppProps {
+    templateSpec: QuestionnaireTemplate;
+    pdfTextExtractor?: {
+        extractFullText: (url: string) => Promise<string>;
+    };
+    structuredPdfExtractor?: {
+        extractStructuredDocument: (text: string) => Promise<StructuredDocument>;
+    };
+    maxPdfSizeBytes?: number;
+    layout?: 'split' | 'single';
+    showPdfViewer?: boolean;
+    onAnswersChange?: (answers: Record<string, any>) => void;
+    initialAnswers?: Record<string, any>;
+    sx?: any;
+    /**
+     * When set, the left column (split layout) or main body (single layout) renders
+     * this node instead of the built-in TemplateQuestionnaire. Use for host apps that
+     * supply their own form while keeping ScidQuest PDF extraction and workspace state.
+     */
+    questionnaireSlot?: (ctx: ResearchQuestionnaireWorkspaceValue) => React.ReactNode;
+    /**
+     * Optional controlled answers. When both are set, the app does not keep a separate
+     * answers useState; the host owns the record (e.g. ORKG form values).
+     */
+    answers?: Record<string, any>;
+    setAnswers?: React.Dispatch<React.SetStateAction<Record<string, any>>>;
+}
+export declare const ResearchQuestionnaireApp: React.FC<ResearchQuestionnaireAppProps>;

package/dist/lib/components/ResearchQuestionnaireFieldAiWrapper.d.ts

@@ -0,0 +1,25 @@
+import React from 'react';
+import type { AIVerificationResult } from '../types';
+import type { ParentContext } from '../../types/context';
+export type ResearchFieldAiQuestionType = 'text' | 'select' | 'multi_select' | 'repeat_text' | 'group';
+export interface ResearchQuestionnaireFieldAiWrapperProps {
+    children: React.ReactNode;
+    questionId: string;
+    questionText: string;
+    questionType: ResearchFieldAiQuestionType;
+    questionOptions?: string[];
+    /** String form of the current field value (as sent to the LLM for verification). */
+    currentAnswer: string;
+    /** Called with the suggestion’s primary text when the user applies a suggestion. */
+    onApplySuggestion: (text: string) => void;
+    /** Force-hide AI chrome (e.g. custom blocks). */
+    disableAi?: boolean;
+    parentContext?: ParentContext;
+    onVerificationComplete?: (result: AIVerificationResult) => void;
+}
+/**
+ * Wraps a host-rendered field with ScidQuest AI (suggest / verify) and PDF evidence UI.
+ * Requires {@link useResearchQuestionnaireWorkspace} (provided automatically when using
+ * `ResearchQuestionnaireApp` with `questionnaireSlot`).
+ */
+export declare const ResearchQuestionnaireFieldAiWrapper: React.FC<ResearchQuestionnaireFieldAiWrapperProps>;

package/dist/lib/components/TemplateQuestionnaire.d.ts

@@ -0,0 +1,27 @@
+import React from 'react';
+import type { StructuredDocument } from '../../utils/structuredPdfExtractor';
+import type { QuestionnaireTemplate } from '../types';
+export interface TemplateQuestionnaireProps {
+    templateSpec: QuestionnaireTemplate | null;
+    answers: Record<string, any>;
+    setAnswers: (next: Record<string, any>) => void;
+    pdfContent?: string;
+    structuredDocument?: StructuredDocument | null;
+    onNavigateToPage?: (pageNumber: number) => void;
+    pdfExtractionError?: Error | null;
+    onRetryExtraction?: () => void;
+    onHighlightsChange?: (highlights: Record<number, {
+        left: number;
+        top: number;
+        width: number;
+        height: number;
+    }[]>) => void;
+    pdfUrl?: string | null;
+    pageWidth?: number | null;
+    aiConfig?: {
+        hidden?: boolean;
+    };
+    sx?: any;
+}
+declare const TemplateQuestionnaire: React.FC<TemplateQuestionnaireProps>;
+export { TemplateQuestionnaire };

package/dist/lib/context.d.ts

@@ -0,0 +1,14 @@
+import React, { ReactNode } from 'react';
+import { ScidQuestAdapter, LLMService } from './types';
+export interface ScidQuestContextType {
+    adapter: ScidQuestAdapter;
+}
+interface ScidQuestProviderProps {
+    llmService: LLMService;
+    children: ReactNode;
+}
+export declare const ScidQuestProvider: React.FC<ScidQuestProviderProps>;
+export declare const useScidQuestContext: () => ScidQuestContextType;
+/** Returns null outside `ScidQuestProvider` (for hooks that support optional embed + legacy paths). */
+export declare const useOptionalScidQuestContext: () => ScidQuestContextType | null;
+export {};

package/dist/lib/hooks/useSuggestionGenerator.d.ts

@@ -0,0 +1,26 @@
+import { type Suggestion, type FeedbackData } from '../../utils/suggestions';
+interface UseSuggestionGeneratorProps {
+    questionText: string;
+    questionType: string;
+    questionOptions?: string[];
+    pdfContent?: string;
+    contextHistory?: Array<{
+        id: string;
+        type: string;
+        content: string;
+        timestamp: number;
+        metadata?: any;
+    }>;
+    previousFeedback?: FeedbackData[];
+    excludedSuggestionIds?: Set<string>;
+}
+interface UseSuggestionGeneratorReturn {
+    suggestions: Suggestion[];
+    loading: boolean;
+    error: string | null;
+    rawError: unknown;
+    generateSuggestions: () => Promise<void>;
+    clearSuggestions: () => void;
+}
+export declare const useSuggestionGenerator: ({ questionText, questionType, questionOptions, pdfContent, contextHistory, previousFeedback, excludedSuggestionIds, }: UseSuggestionGeneratorProps) => UseSuggestionGeneratorReturn;
+export {};

package/dist/lib/index.d.ts

@@ -0,0 +1,25 @@
+export * from './types';
+export * from './context';
+export * from './hooks/useSuggestionGenerator';
+import 'react-pdf/dist/Page/AnnotationLayer.css';
+import 'react-pdf/dist/Page/TextLayer.css';
+export { createScidQuestAdapter } from './adapter';
+export { createLLMServiceFromAIService } from './utils/createLLMServiceFromAIService';
+export type { ResearchQuestionnaireWorkspaceValue, ResearchQuestionnaireSlotRenderProps, } from './research-questionnaire-workspace';
+export { ResearchQuestionnaireWorkspaceProvider, useResearchQuestionnaireWorkspace, } from './research-questionnaire-workspace';
+export { buildQuestionDefinitions, siblingQuestionIdsFor, } from './questionnaire-template-helpers';
+export { PDFUpload } from './components/PDFUpload';
+export { PdfViewer } from './components/PdfViewer';
+export { TemplateQuestionnaire } from './components/TemplateQuestionnaire';
+export { ResearchQuestionnaireApp } from './components/ResearchQuestionnaireApp';
+export { ResearchQuestionnaireFieldAiWrapper } from './components/ResearchQuestionnaireFieldAiWrapper';
+export type { ResearchFieldAiQuestionType, ResearchQuestionnaireFieldAiWrapperProps, } from './components/ResearchQuestionnaireFieldAiWrapper';
+export type { PDFUploadProps } from './components/PDFUpload';
+export type { PdfViewerProps } from './components/PdfViewer';
+export type { TemplateQuestionnaireProps } from './components/TemplateQuestionnaire';
+export type { ResearchQuestionnaireAppProps } from './components/ResearchQuestionnaireApp';
+import AIAssistantButton from '../components/TemplateQuestionaire/AIAssistantButton';
+import SuggestionBox from '../components/TemplateQuestionaire/SuggestionBox';
+export { AIAssistantButton, SuggestionBox };
+export { default as AIConfigurationDialog } from '../components/AI/AIConfigurationDialog';
+export { QuestionnaireAIProvider, QuestionnaireAIContext, } from '../context/QuestionnaireAIContext';

package/dist/lib/questionnaire-template-helpers.d.ts

@@ -0,0 +1,10 @@
+import type { Question, QuestionnaireTemplate } from './types';
+/**
+ * Flat map of question id → question definition (including nested subquestions / item_fields).
+ * Used by AI suggestion context gathering.
+ */
+export declare function buildQuestionDefinitions(template: QuestionnaireTemplate): Record<string, Question>;
+/**
+ * Sibling question ids in the same section (top-level) or same group (nested).
+ */
+export declare function siblingQuestionIdsFor(template: QuestionnaireTemplate, questionId: string): string[];

package/dist/lib/research-questionnaire-workspace.d.ts

@@ -0,0 +1,33 @@
+import React from 'react';
+import type { QuestionnaireTemplate } from './types';
+import type { StructuredDocument } from '../utils/structuredPdfExtractor';
+/**
+ * PDF + questionnaire workspace passed to {@link ResearchQuestionnaireApp}
+ * `questionnaireSlot` and exposed to descendants via context.
+ */
+export type ResearchQuestionnaireWorkspaceValue = {
+    templateSpec: QuestionnaireTemplate;
+    answers: Record<string, unknown>;
+    setAnswers: React.Dispatch<React.SetStateAction<Record<string, unknown>>>;
+    pdfContent: string | undefined;
+    structuredDocument: StructuredDocument | null;
+    pdfUrl: string | null;
+    pageWidth: number | null;
+    onNavigateToPage: (pageNumber: number) => void;
+    onHighlightsChange: (highlights: Record<number, {
+        left: number;
+        top: number;
+        width: number;
+        height: number;
+    }[]>) => void;
+    pdfExtractionError: Error | null;
+    onRetryExtraction: () => void;
+};
+/** Alias for embed API / docs. */
+export type ResearchQuestionnaireSlotRenderProps = ResearchQuestionnaireWorkspaceValue;
+export declare function ResearchQuestionnaireWorkspaceProvider({ value, children, }: {
+    value: ResearchQuestionnaireWorkspaceValue;
+    children: React.ReactNode;
+}): import("react/jsx-runtime").JSX.Element;
+/** `null` when not under {@link ResearchQuestionnaireWorkspaceProvider} (e.g. Form mode). */
+export declare function useResearchQuestionnaireWorkspace(): ResearchQuestionnaireWorkspaceValue | null;

package/dist/lib/types.d.ts

@@ -0,0 +1,121 @@
+import type { GenerateSuggestionsRequest, GenerateSuggestionsResponse, Suggestion } from '../utils/suggestions';
+import type { VerifyAnswerRequest, AIVerificationResult } from '../services/backendAIService';
+export type { GenerateSuggestionsRequest, GenerateSuggestionsResponse, Suggestion, VerifyAnswerRequest, AIVerificationResult, };
+/**
+ * Options for generating text with an LLM
+ */
+export interface LLMGenerateTextOptions {
+    temperature?: number;
+    maxTokens?: number;
+    systemContext?: string;
+}
+/**
+ * Response from LLM text generation
+ */
+export interface LLMGenerateTextResponse {
+    text: string;
+    reasoning?: string;
+    usage?: {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+    };
+}
+/**
+ * LLM Service Interface
+ *
+ * This interface defines the contract for LLM functions that the ScidQuest library
+ * requires. Users must provide an implementation of this interface when using the library.
+ *
+ * This approach ensures:
+ * - Security: The library never handles API keys directly
+ * - Flexibility: Users can use any LLM provider or implementation
+ * - Efficiency: Users control caching, rate limiting, and optimization
+ */
+export interface LLMService {
+    /**
+     * Generate text from a prompt using the LLM
+     *
+     * @param prompt - The user prompt/question
+     * @param options - Optional generation parameters
+     * @returns Promise resolving to the generated text and optional metadata
+     */
+    generateText(prompt: string, options?: LLMGenerateTextOptions): Promise<LLMGenerateTextResponse>;
+    /**
+     * Check if the LLM service is properly configured and ready to use
+     *
+     * @returns true if the service is configured and can be used
+     */
+    isConfigured(): boolean;
+}
+/**
+ * Internal adapter interface (used by library components)
+ * This wraps the LLMService to provide higher-level operations
+ */
+export interface ScidQuestAdapter {
+    generateSuggestions(request: GenerateSuggestionsRequest): Promise<GenerateSuggestionsResponse>;
+    verifyAnswer(request: VerifyAnswerRequest): Promise<AIVerificationResult>;
+    verifyAnswersBatch?(requests: VerifyAnswerRequest[]): Promise<AIVerificationResult[]>;
+    isConfigured(): boolean;
+}
+export interface ValidationRule {
+    format?: string;
+    formatError?: string;
+    minLength?: number;
+    minLengthError?: string;
+    maxLength?: number;
+    maxLengthError?: string;
+}
+export interface Mapping {
+    field: string;
+    node?: string;
+    property_id?: string;
+    cardinality?: string;
+    class_id?: string;
+    subtemplate_id?: string;
+    property_value_mapping?: Record<string, string>;
+}
+export interface Link {
+    field: string;
+    node: string;
+    property_id?: string;
+    cardinality?: string;
+    class_id?: string;
+    subtemplate_id?: string;
+}
+export interface Question {
+    id: string;
+    label?: string;
+    title?: string;
+    type: string;
+    required?: boolean;
+    choice_type?: 'single' | 'multiple' | 'no';
+    options?: string[];
+    evidence_fields?: string[];
+    evidence_per_item?: boolean;
+    desc?: string;
+    validation?: ValidationRule;
+    maps_to_fields?: Mapping[];
+    links_via_field?: Link;
+    property_id?: string;
+    cardinality?: string;
+    class_id?: string;
+    subtemplate_id?: string;
+    parent_property_id?: string;
+    parent_class_id?: string;
+    parent_subtemplate_id?: string;
+    item_fields?: Question[];
+    subquestions?: Question[];
+    disable_ai_assistant?: boolean;
+}
+export interface Section {
+    id: string;
+    title: string;
+    questions: Question[];
+}
+export interface QuestionnaireTemplate {
+    version: string;
+    template: string;
+    template_id: string;
+    sections: Section[];
+}

package/dist/lib/utils/createLLMServiceFromAIService.d.ts

@@ -0,0 +1,3 @@
+import type { LLMService } from '../types';
+import type { UnifiedAIService } from '../../services/backendAIService';
+export declare function createLLMServiceFromAIService(aiService: UnifiedAIService): LLMService;