@withpica/mcp-server/dist/tools/duplicates.d.ts

MCP Server for withPICA — enables AI assistants to interact with your withPICA music catalog

/**
 * Duplicate Detection & Merge Tools - MCP tools for finding and merging duplicates
 */
import { PicaClient } from "@withpica/mcp-sdk";
import { ToolDefinition, ToolExecutor } from "./index.js";
import { type DecisionBlock } from "@withpica/mcp-utils";
/** Most merges one batched pica_merge_duplicates call may carry — kept equal
 *  to MAX_MERGE_BATCH_ITEMS in lib/services/human-approval-merge-batch.ts (the
 *  approval gate's cap), pinned by lib/services/__tests__/human-approval-merge-batch.test.ts. */
export declare const MAX_MERGE_BATCH_ITEMS = 50;
/** Most ids one pica_duplicates_mark_different call may carry — kept equal to
 *  MAX_EXCLUSION_IDS in lib/services/duplicate-pair-exclusions.ts (which the
 *  route enforces), pinned by lib/services/__tests__/duplicate-pair-exclusions.test.ts. */
export declare const MAX_MARK_DIFFERENT_IDS = 25;
/**
 * Coerce entity_type to canonical plural + SDK-shaped singular.
 * Accepts both legacy ("work", "person") and canonical ("works", "people"),
 * plus the new ADR-264 WS1.3 types ("releases"/"recordings" + singular aliases).
 * Canonical plural matches `pica_find_duplicates` and `pica_*_query`.
 */
export declare function coerceMergeEntityType(value: string): {
    canonical: "works" | "people" | "releases" | "recordings";
    sdk: "work" | "person" | "recording" | "release";
};
/**
 * Entity types `pica_find_duplicates` accepts — a SUPERSET of the mergeable
 * ones. `audio_files` (ops issue dcea642b, 2026-09-10) detects the same file
 * uploaded twice; it is discovery-only, so it must never reach
 * `coerceMergeEntityType`.
 */
export declare function coerceFindEntityType(value: string): "works" | "people" | "releases" | "recordings" | "audio_files";
/** Human display name for a duplicate group — title/name over identifier key. */
export declare function duplicateGroupDisplayName(group: {
    key: string;
    items: Array<Record<string, unknown>>;
}): string;
/** Entity types whose pairs can be marked "they're different" by an agent. */
export declare const MARK_DIFFERENT_ENTITY_TYPES: readonly ["recordings", "releases"];
export type MarkDifferentEntityType = (typeof MARK_DIFFERENT_ENTITY_TYPES)[number];
/**
 * ADR-267 Rule 3 — the duplicate-resolution choice, ready to put to the user.
 * `entityType` is the find call's entity type: recording and release groups
 * can be marked "they're different" (pica_duplicates_mark_different), so
 * "keep them separate" says how to stop them coming back.
 */
export declare function buildDuplicateGroupDecision(group: {
    key: string;
    items: Array<Record<string, unknown>>;
    match_kind?: string;
    similarity?: number;
    remix?: unknown;
}, entityType?: string): DecisionBlock;
/**
 * Surface the merge recommendation already implied by the service's
 * `suggested_winner_id` as an explicit, reviewable read model: a named
 * `recommended_canonical` (id + one-line reason) plus a per-item `rationale`,
 * so an agent can present "keep X, fold Y/Z" for human sign-off without
 * reconstructing the heuristic. Additive presentation only — no data change.
 * (Founder feedback a03bfd1b — duplicate-cluster review object.)
 */
export declare function buildCanonicalRecommendation(group: {
    items: Array<Record<string, unknown>>;
    suggested_winner_id?: unknown;
    match_kind?: unknown;
}): {
    items: Array<Record<string, unknown>>;
    recommended_canonical: {
        id: string;
        reason: string;
    } | null;
};
export declare class DuplicatesTools {
    private pica;
    constructor(pica: PicaClient);
    getTools(): Array<{
        definition: ToolDefinition;
        executor: ToolExecutor;
    }>;
    private findDuplicates;
    private markDifferent;
    private mergeDuplicates;
    /**
     * The batch form for callers that execute directly (session / first-party
     * key — delegated agents never reach here: the HTTP gate freezes the list
     * into one approval). Runs each merge in turn through the single path; a
     * failure is recorded and the rest still run, and the result names every
     * pair's outcome so nothing reads as a blanket success.
     */
    private mergeBatch;
    private mergeOne;
}
//# sourceMappingURL=duplicates.d.ts.map