@wutiankai/npc-dialogue 1.0.0-alpha.1

package/dist/index.d.ts

@@ -0,0 +1,323 @@
+type ProviderState = "uninitialized" | "initializing" | "ready" | "degraded" | "failed" | "disposed";
+interface ProviderStatus {
+    state: ProviderState;
+    providerId: string;
+    lastHealthCheck: number;
+    consecutiveFailures: number;
+    lastError?: string;
+    configRedacted: {
+        baseUrl: string;
+        model: string;
+    };
+}
+type TrustLevel = 0 | 1 | 2;
+interface GroundingData {
+    currentRoomName: string;
+    visibleExits: string[];
+    presentNpcNames: string[];
+    inventoryItemNames: string[];
+    discoveredClueNames: string[];
+    knownConsequences: string[];
+    turnsRemaining: number;
+}
+type RuntimeEvent = Record<string, unknown>;
+type VisibleState = Record<string, unknown>;
+interface NarrativeRequest {
+    id: string;
+    type: "narration" | "dialogue";
+    turnIndex: number;
+    events: RuntimeEvent[];
+    commandMessage: string;
+    visibleState: VisibleState;
+    dialogueContext?: {
+        npcId: string;
+        npcName: string;
+        npcRole: string;
+        topic: string;
+        topicResponse: string;
+        trustLevel: TrustLevel;
+        recentEvents: RuntimeEvent[];
+    };
+    grounding: GroundingData;
+    timestamp: number;
+    lang: "en" | "zh";
+}
+interface AuditRecord {
+    requestId: string;
+    turnIndex: number;
+    requestType: "narration" | "dialogue";
+    eventTypes: string[];
+    commandVerb: string;
+    responseSource: "ai" | "passthrough";
+    responseTextPreview: string;
+    validationPassed: boolean;
+    constraintViolations: string[];
+    providerState: ProviderState;
+    providerId: string;
+    promptStructure: {
+        systemPromptHash: string;
+        groundingFactCount: number;
+        eventCount: number;
+    };
+    latencyMs: number;
+    timestamp: number;
+}
+interface AuditFilter {
+    source?: "ai" | "passthrough";
+    minTurnIndex?: number;
+    maxTurnIndex?: number;
+    requestType?: "narration" | "dialogue";
+    validationPassed?: boolean;
+}
+interface AuditStats {
+    totalRequests: number;
+    aiSuccessCount: number;
+    passthroughCount: number;
+    aiFailureCount: number;
+    validationFailureCount: number;
+    constraintViolationCount: number;
+    averageLatencyMs: number;
+    byProvider: Record<string, {
+        calls: number;
+        failures: number;
+    }>;
+}
+interface ProviderRawResponse {
+    text: string;
+    model: string;
+    latencyMs: number;
+    promptTokenCount?: number;
+    completionTokenCount?: number;
+}
+
+interface NarrativeProvider {
+    readonly id: string;
+    initialize(): Promise<void>;
+    dispose(): Promise<void>;
+    getStatus(): ProviderStatus;
+    healthCheck(): Promise<boolean>;
+    call(request: NarrativeRequest, systemPrompt: string, userPrompt: string): Promise<ProviderRawResponse>;
+}
+declare class PassthroughProvider implements NarrativeProvider {
+    readonly id = "passthrough";
+    private status;
+    initialize(): Promise<void>;
+    dispose(): Promise<void>;
+    getStatus(): ProviderStatus;
+    healthCheck(): Promise<boolean>;
+    call(request: NarrativeRequest, _systemPrompt: string, _userPrompt: string): Promise<ProviderRawResponse>;
+}
+
+interface ProviderConfig {
+    apiKey?: string;
+    baseUrl: string;
+    model: string;
+    maxTokens: number;
+    temperature: number;
+}
+declare function loadConfigFromEnv(): ProviderConfig;
+
+declare class OpenAICompatibleProvider implements NarrativeProvider {
+    private config;
+    readonly id = "openai-compat";
+    private state;
+    private consecutiveFailures;
+    private lastHealthCheck;
+    private lastError?;
+    constructor(config: ProviderConfig);
+    initialize(): Promise<void>;
+    dispose(): Promise<void>;
+    getStatus(): ProviderStatus;
+    healthCheck(): Promise<boolean>;
+    call(_request: NarrativeRequest, systemPrompt: string, userPrompt: string): Promise<ProviderRawResponse>;
+    private recordFailure;
+}
+
+declare class AuditLog {
+    private entries;
+    private readonly maxEntries;
+    constructor(maxEntries?: number);
+    append(record: AuditRecord): void;
+    query(filter?: AuditFilter): AuditRecord[];
+    stats(): AuditStats;
+    clear(): void;
+    export(): AuditRecord[];
+    get length(): number;
+}
+
+/**
+ * NPC Script — the complete character bible for AI-driven dialogue.
+ * Defined per-NPC per-adventure.
+ */
+interface NpcScript {
+    npcId: string;
+    name: string;
+    role: string;
+    /** Optional world/genre framing for the system prompt.
+     *  E.g. "a murder mystery game set in a snowbound manor" */
+    worldSetting?: string;
+    persona: {
+        personality: string;
+        background: string;
+        speechPatterns: string;
+        emotionalBaseline?: string;
+        forbiddenTone?: string;
+    };
+    publicKnowledge: NpcKnowledgeEntry[];
+    privateKnowledge: NpcKnowledgeEntry[];
+    gatedSecrets: NpcSecret[];
+    ignorance: string[];
+    relationships: {
+        npcId: string;
+        attitude: string;
+        notes: string;
+    }[];
+}
+interface NpcKnowledgeEntry {
+    id: string;
+    topic: string;
+    content: string;
+}
+interface NpcSecret {
+    id: string;
+    topicGateId: string;
+    description: string;
+    revealConditions: string;
+    reactionWhenPressed: string;
+    triggerKeywords?: string[];
+    triggerPhrases?: string[];
+}
+interface ConversationExchange {
+    playerInput: string;
+    npcResponse: string;
+    /** Gate that was actually triggered (after policy review), or null. */
+    triggeredTopicGateId: string | null;
+    timestamp: number;
+    policyNotes?: string[];
+    possibleStateClaim?: "item_given" | "access_granted" | null;
+    runtimeConfirmed?: boolean;
+}
+/**
+ * What the AI returns — candidate signals, NOT executable decisions.
+ *
+ * AI proposes gate triggers/action hints, but the DialoguePolicy/runtime
+ * layers decide what to accept.
+ */
+interface DialogueAiResponse {
+    dialogue: string;
+    /** AI-proposed gate trigger — policy layer has final authority. */
+    candidateGateId: string | null;
+    /** What part of the player's input suggested this gate. */
+    gateEvidence: string;
+    /** AI confidence in the gate trigger. */
+    gateConfidence: "low" | "medium" | "high";
+    /** Optional action the AI thinks is happening (e.g., "item_given"). */
+    candidateActionHint: string | null;
+}
+interface DialogueContext {
+    currentRoom: string;
+    currentTurn: number;
+    turnsRemaining: number;
+    playerInventory: string[];
+    discoveredClues: string[];
+    currentTrust: number;
+    exhaustedTopicGateIds: string[];
+    recentExchanges: ConversationExchange[];
+    validTopicGateIds: string[];
+}
+interface DialogueRequest {
+    npcScript: NpcScript;
+    playerInput: string;
+    context: DialogueContext;
+}
+/**
+ * What the DialogueEngine returns to callers.
+ *
+ * Contains candidate signals from AI plus temporary backward-compatible
+ * fields so that callers can migrate incrementally.
+ */
+interface DialogueResult {
+    dialogue: string;
+    source: "ai" | "passthrough";
+    latencyMs: number;
+    candidateGateId: string | null;
+    gateEvidence: string;
+    gateConfidence: "low" | "medium" | "high";
+    /** AI-suggested action (e.g., "item_given"). Policy reviews this. */
+    candidateActionHint: string | null;
+    /** Raw AI output text before parsing. */
+    rawAiText: string;
+    /** Model identifier used for this call. */
+    model: string;
+    /** Prompt token count (if available from provider). */
+    promptTokens?: number;
+    /** Completion token count (if available from provider). */
+    completionTokens?: number;
+    /** Full system prompt sent to AI. */
+    systemPrompt: string;
+    /** Full user prompt sent to AI. */
+    userPrompt: string;
+    /** @deprecated Use candidateGateId. Maps from candidateGateId. */
+    triggeredTopicGateId: string | null;
+}
+
+interface DialogueEngineConfig {
+    lang: "en" | "zh";
+    maxConversationHistory: number;
+    failOpen: boolean;
+    /** Optional bilingual keyword map for cross-language gate matching.
+     *  Keys are English terms, values are arrays of Chinese equivalents. */
+    bilingualKeywordMap?: Record<string, string[]>;
+}
+declare class DialogueEngine {
+    private provider;
+    private auditLog;
+    private config;
+    private lang;
+    private initialized;
+    constructor(provider: NarrativeProvider, config?: Partial<DialogueEngineConfig>);
+    initialize(): Promise<void>;
+    dispose(): Promise<void>;
+    isAiAvailable(): boolean;
+    handleFreeFormDialogue(request: DialogueRequest): Promise<DialogueResult>;
+    private buildMinimalRequest;
+    private recordAudit;
+}
+
+interface DialoguePromptPair {
+    system: string;
+    user: string;
+}
+declare function buildNpcDialoguePrompt(npcScript: NpcScript, playerInput: string, context: DialogueContext, recentExchanges: ConversationExchange[], lang: "en" | "zh"): DialoguePromptPair;
+
+/**
+ * Parse AI response text as JSON. Handles:
+ * - markdown-wrapped JSON
+ * - truncated JSON (model hit max_tokens mid-response)
+ * - raw JSON without wrapper
+ * Accepts both old and new field name formats.
+ */
+declare function parseAiJson(rawText: string): DialogueAiResponse;
+
+declare function validateDialogueResponse(parsed: DialogueAiResponse): DialogueAiResponse;
+
+/**
+ * Expand explicit English keywords with Chinese equivalents for cross-language matching.
+ *
+ * @param englishKeywords - Keywords from secret definitions (typically English)
+ * @param bilingualMap - Optional map of English keyword → Chinese equivalents.
+ *   Provide a game-specific map for bilingual gate matching.
+ */
+declare function expandKeywordsBilingually(englishKeywords: string[], bilingualMap?: Record<string, string[]>): string[];
+/**
+ * Review a validated AI response for false gate triggers.
+ *
+ * Rules (greeting/short-input filtering is handled by dialogue-intent.ts):
+ * 1. If explicit trigger keywords/phrases exist, player input must match one
+ * 2. AI must provide gateEvidence or gateConfidence ≥ medium
+ */
+declare function reviewGateTrigger(validated: DialogueAiResponse, playerInput: string, npcScript: NpcScript, _context: DialogueContext, options?: {
+    bilingualKeywordMap?: Record<string, string[]>;
+}): DialogueAiResponse;
+
+export { AuditLog, type AuditRecord, type AuditStats, type ConversationExchange, type DialogueAiResponse, type DialogueContext, DialogueEngine, type DialogueEngineConfig, type DialoguePromptPair, type DialogueRequest, type DialogueResult, type GroundingData, type NarrativeProvider, type NarrativeRequest, type NpcKnowledgeEntry, type NpcScript, type NpcSecret, OpenAICompatibleProvider, PassthroughProvider, type ProviderConfig, type ProviderRawResponse, type ProviderState, type ProviderStatus, type TrustLevel, buildNpcDialoguePrompt, expandKeywordsBilingually, loadConfigFromEnv, parseAiJson, reviewGateTrigger, validateDialogueResponse };