@withpica/mcp-server 1.3.0

package/dist/tools/audio-files.js

@@ -0,0 +1,409 @@
+// Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
+import { formatAsText, formatList, formatSuccess, } from "@withpica/mcp-utils";
+import { withBillingGate } from "@withpica/mcp-utils";
+export class AudioFilesTools {
+    pica;
+    constructor(pica) {
+        this.pica = pica;
+    }
+    getTools() {
+        return [
+            {
+                definition: {
+                    name: "pica_audio_query",
+                    description: "Find audio files — filter by work, file type, or analysis status. " +
+                        "→ then: pica_audio_inspect (details for a specific file)",
+                    workflows: "infrastructure",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            work_id: {
+                                type: "string",
+                                description: "Filter by work ID to get all audio files for a specific work",
+                            },
+                            file_type: {
+                                type: "string",
+                                description: "Filter by file type",
+                                enum: ["master", "instrumental", "stem", "demo", "version"],
+                            },
+                            unprocessed: {
+                                type: "boolean",
+                                description: "Set true to get only files without audio analysis (no BPM/key detection yet)",
+                            },
+                            limit: {
+                                type: "number",
+                                description: "Maximum results to return (default: 50)",
+                            },
+                        },
+                    },
+                },
+                executor: this.queryAudioFiles.bind(this),
+            },
+            {
+                definition: {
+                    name: "pica_audio_inspect",
+                    description: "Get details for a specific audio file. Omit sections for everything. " +
+                        "→ then: pica_audio_analyze (run analysis), pica_audio_identify (fingerprint match)",
+                    workflows: ["audio-upload-required"],
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            id: {
+                                type: "string",
+                                description: "Audio file ID",
+                            },
+                            sections: {
+                                type: "array",
+                                items: {
+                                    type: "string",
+                                    enum: ["basic", "analysis", "status"],
+                                },
+                                description: "Which data sections to include. Omit for all sections.",
+                            },
+                        },
+                        required: ["id"],
+                    },
+                },
+                executor: this.inspectAudioFile.bind(this),
+            },
+            {
+                definition: {
+                    name: "pica_audio_analyze",
+                    description: "Trigger audio analysis on an audio file. Two analysis types available (1 credit each):\n" +
+                        "• Audio features (BPM, key, energy, valence, mood, duration)\n" +
+                        "• Lyrics transcription (speech-to-text + language detection)\n\n" +
+                        "Both are enabled by default. Analysis runs asynchronously — use pica_audio_inspect with status section to check progress. " +
+                        "Transcribed lyrics are saved to the transcriptions table and can be copied to the work's lyrics field. " +
+                        "→ then: pica_audio_inspect (check progress), pica_search_for_sync (find sync-ready works)",
+                    workflows: ["audio-upload-required"],
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            id: {
+                                type: "string",
+                                description: "Audio file ID to analyze",
+                            },
+                            force: {
+                                type: "boolean",
+                                description: "Force re-analysis even if the file was already analyzed",
+                            },
+                            enable_audio: {
+                                type: "boolean",
+                                description: "Enable audio feature extraction (BPM, key, energy). Default: true.",
+                            },
+                            enable_lyrics: {
+                                type: "boolean",
+                                description: "Enable lyrics transcription. Default: true.",
+                            },
+                        },
+                        required: ["id"],
+                    },
+                },
+                executor: withBillingGate(this.pica, "audio analysis", this.analyzeAudioFile.bind(this)),
+            },
+            {
+                definition: {
+                    name: "pica_audio_presigned_upload",
+                    description: "Generate a signed URL for uploading an audio file directly to storage. Returns an upload URL and upload ID. After uploading the file via HTTP PUT to the returned URL, call pica_audio_complete_upload to finalize. Supported formats: WAV, MP3, FLAC, AIFF, OGG, WebM. Max size: 800MB. " +
+                        "→ then: pica_audio_complete_upload (finalize upload), pica_audio_analyze (extract BPM, key, mood). " +
+                        "TIP: if you are in ChatGPT or another external client, users cannot upload audio " +
+                        "through the chat. Direct them to https://withpica.com/workspace where they can " +
+                        "drag and drop audio files (it auto-detects format and runs analysis). " +
+                        "If the user insists on using this tool, ask for the filename and file size — " +
+                        "you can detect the format from the file extension, no need to ask for content type.",
+                    workflows: ["audio-upload-required"],
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            filename: {
+                                type: "string",
+                                description: "Original filename with extension (e.g. 'my-song.wav')",
+                            },
+                            content_type: {
+                                type: "string",
+                                description: "MIME type — detect from the filename extension: " +
+                                    ".wav→audio/wav, .mp3→audio/mpeg, .flac→audio/flac, " +
+                                    ".aiff/.aif→audio/aiff, .ogg→audio/ogg, .webm→audio/webm. " +
+                                    "Do not ask the user for this — work it out from the filename.",
+                                enum: [
+                                    "audio/wav",
+                                    "audio/x-wav",
+                                    "audio/mpeg",
+                                    "audio/mp3",
+                                    "audio/flac",
+                                    "audio/x-flac",
+                                    "audio/aiff",
+                                    "audio/x-aiff",
+                                    "audio/ogg",
+                                    "audio/webm",
+                                ],
+                            },
+                            file_size: {
+                                type: "number",
+                                description: "File size in bytes",
+                            },
+                            work_id: {
+                                type: "string",
+                                description: "Optional work ID to link the audio file to. If provided, a recording will be auto-created for master files.",
+                            },
+                            title: {
+                                type: "string",
+                                description: "Optional title for the audio file. Defaults to filename without extension.",
+                            },
+                            file_type: {
+                                type: "string",
+                                description: "Type of audio file (default: 'master')",
+                                enum: ["master", "instrumental", "stem", "demo", "version"],
+                            },
+                        },
+                        required: ["filename", "content_type", "file_size"],
+                    },
+                },
+                executor: withBillingGate(this.pica, "audio upload", this.presignedUpload.bind(this)),
+            },
+            {
+                definition: {
+                    name: "pica_audio_complete_upload",
+                    description: "Finalize an audio file upload after the file has been PUT to the signed URL from pica_audio_presigned_upload. Creates the database record and optionally links to a work/recording. For master files linked to a work, a recording is auto-created if none exists. " +
+                        "After several mutations, surface a pica_dashboard_briefing to the user. " +
+                        "→ then: pica_audio_analyze (extract BPM, key, mood), pica_audio_identify (fingerprint match via ACRCloud)",
+                    workflows: ["audio-upload-required"],
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            upload_id: {
+                                type: "string",
+                                description: "The uploadId returned from pica_audio_presigned_upload",
+                            },
+                            key: {
+                                type: "string",
+                                description: "The storage key returned from pica_audio_presigned_upload",
+                            },
+                            bucket: {
+                                type: "string",
+                                description: "The bucket returned from pica_audio_presigned_upload",
+                            },
+                            filename: {
+                                type: "string",
+                                description: "Original filename",
+                            },
+                            content_type: {
+                                type: "string",
+                                description: "MIME type of the uploaded file",
+                            },
+                            file_size: {
+                                type: "number",
+                                description: "File size in bytes",
+                            },
+                            work_id: {
+                                type: "string",
+                                description: "Optional work ID to link the audio file to",
+                            },
+                            title: {
+                                type: "string",
+                                description: "Optional title for the audio file",
+                            },
+                            file_type: {
+                                type: "string",
+                                description: "Type of audio file (default: 'master')",
+                                enum: ["master", "instrumental", "stem", "demo", "version"],
+                            },
+                            stem_label: {
+                                type: "string",
+                                description: "Label for stem files (e.g. 'vocals', 'drums', 'bass')",
+                            },
+                            version_label: {
+                                type: "string",
+                                description: "Label for version files (e.g. 'radio edit', 'extended mix')",
+                            },
+                            recording_id: {
+                                type: "string",
+                                description: "Link to an existing recording ID instead of auto-creating one",
+                            },
+                            classification: {
+                                type: "string",
+                                description: "Audio classification (e.g. 'original', 'remix', 'cover', 'live')",
+                            },
+                        },
+                        required: [
+                            "upload_id",
+                            "key",
+                            "bucket",
+                            "filename",
+                            "content_type",
+                            "file_size",
+                        ],
+                    },
+                },
+                executor: withBillingGate(this.pica, "audio upload finalization", this.completeUpload.bind(this)),
+            },
+            {
+                definition: {
+                    name: "pica_audio_identify",
+                    description: "Identify a track using ACRCloud audio fingerprinting. Returns matched metadata (title, artist, album, ISRC, label) with confidence score. If matched, metadata is automatically propagated to the linked work.",
+                    workflows: "infrastructure",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            id: {
+                                type: "string",
+                                description: "Audio file ID to identify",
+                            },
+                            force: {
+                                type: "boolean",
+                                description: "Force re-identification even if already matched",
+                            },
+                        },
+                        required: ["id"],
+                    },
+                },
+                executor: withBillingGate(this.pica, "audio identification", this.identifyAudioFile.bind(this)),
+            },
+        ];
+    }
+    async queryAudioFiles(args) {
+        const files = await this.pica.audioFiles.list({
+            work_id: args.work_id,
+            file_type: args.file_type,
+            unprocessed: args.unprocessed,
+            limit: args.limit,
+        });
+        return formatList(files, { total: files.length });
+    }
+    async inspectAudioFile(args) {
+        const sections = args.sections;
+        const includeAll = !sections || sections.length === 0;
+        const includeBasic = includeAll || sections.includes("basic");
+        const includeAnalysis = includeAll || sections.includes("analysis");
+        const includeStatus = includeAll || sections.includes("status");
+        const result = {};
+        // Fetch basic + analysis data from get (they come together)
+        if (includeBasic || includeAnalysis) {
+            const file = await this.pica.audioFiles.get(args.id);
+            if (includeBasic) {
+                // ADR-201 Phase 2: surface every field the write side accepts.
+                // pica_audio_complete_upload writes recording_id, stem_label,
+                // version_label, classification (4 of the 5 audit-flagged fields)
+                // directly to audio_files columns. The fifth — content_type —
+                // is transformed into audio_format on write (e.g. "audio/mpeg"
+                // → "mpeg"); already surfaced.
+                result.basic = {
+                    id: file.id,
+                    work_id: file.work_id,
+                    recording_id: file.recording_id,
+                    title: file.title,
+                    filename: file.filename,
+                    file_type: file.file_type,
+                    stem_label: file.stem_label,
+                    version_label: file.version_label,
+                    classification: file.classification,
+                    file_size: file.file_size,
+                    audio_format: file.audio_format,
+                    published: file.published,
+                    created_at: file.created_at,
+                    updated_at: file.updated_at,
+                };
+            }
+            if (includeAnalysis) {
+                result.analysis = {
+                    duration_seconds: file.duration_seconds,
+                    detected_bpm: file.detected_bpm,
+                    detected_key: file.detected_key,
+                    detected_energy: file.detected_energy,
+                    detected_valence: file.detected_valence,
+                    detected_mood: file.detected_mood,
+                    metadata_extracted: file.metadata_extracted,
+                };
+            }
+        }
+        // Fetch status separately
+        if (includeStatus) {
+            const status = await this.pica.audioFiles.getStatus(args.id);
+            result.status = status;
+        }
+        return formatSuccess("Audio file details", result);
+    }
+    async analyzeAudioFile(args) {
+        const result = await this.pica.audioFiles.analyze(args.id, {
+            forceReAnalyze: args.force,
+            enableAudio: args.enable_audio,
+            enableLyrics: args.enable_lyrics,
+        });
+        return formatSuccess(result.message || "Analysis triggered", result.features);
+    }
+    async presignedUpload(args) {
+        const result = await this.pica.audioFiles.presignedUpload({
+            filename: args.filename,
+            contentType: args.content_type,
+            fileSize: args.file_size,
+            workId: args.work_id,
+            title: args.title,
+            fileType: args.file_type,
+        });
+        return formatSuccess(`Upload URL generated for "${args.filename}". PUT the file to the uploadUrl, then call pica_audio_complete_upload with the uploadId, key, bucket, and metadata to finalize.`, {
+            uploadUrl: result.uploadUrl,
+            uploadId: result.uploadId,
+            key: result.key,
+            bucket: result.bucket,
+            expiresAt: result.expiresAt,
+            metadata: result.metadata,
+        });
+    }
+    async completeUpload(args) {
+        const result = await this.pica.audioFiles.completeUpload({
+            uploadId: args.upload_id,
+            key: args.key,
+            bucket: args.bucket,
+            metadata: {
+                filename: args.filename,
+                contentType: args.content_type,
+                fileSize: args.file_size,
+                workId: args.work_id,
+                title: args.title,
+                fileType: args.file_type,
+                stemLabel: args.stem_label,
+                versionLabel: args.version_label,
+                recordingId: args.recording_id,
+                classification: args.classification,
+            },
+        });
+        const hints = [
+            {
+                gap: "audio_not_analysed",
+                suggestion: "Run pica_audio_analyze to extract BPM, key, energy, and mood",
+                severity: "important",
+            },
+            {
+                gap: "audio_not_identified",
+                suggestion: "Run pica_audio_identify to fingerprint and match against ACRCloud",
+                severity: "nice_to_have",
+            },
+        ];
+        if (!args.work_id) {
+            hints.unshift({
+                gap: "audio_not_linked",
+                suggestion: "Link this audio file to a work",
+                severity: "critical",
+            });
+        }
+        return formatSuccess(`Upload finalized. Audio file created with ID: ${result.audioFileId}.`, result, hints);
+    }
+    async identifyAudioFile(args) {
+        const result = await this.pica.audioFiles.identify(args.id, {
+            force: args.force,
+        });
+        if (result.alreadyIdentified) {
+            return formatSuccess("Already identified — no credits charged. Use force: true to re-identify.", result);
+        }
+        else if (result.status === "matched" && result.match) {
+            return formatSuccess(`Match found: "${result.match.title}" by ${result.match.artist} (confidence: ${Math.round((result.match.confidence || 0) * 100)}%). ISRC: ${result.match.isrc || "unknown"}. If the file is linked to a work, metadata has been propagated.`, result);
+        }
+        else if (result.status === "no_match") {
+            return formatSuccess("No match found in ACRCloud database. This may be an unreleased or very rare track.", result);
+        }
+        else {
+            return formatAsText(result);
+        }
+    }
+}
+//# sourceMappingURL=audio-files.js.map

package/dist/tools/audio-files.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audio-files.js","sourceRoot":"","sources":["../../src/tools/audio-files.ts"],"names":[],"mappings":"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"}

package/dist/tools/audit.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Audit Tools — ADR-154 F6
+ *
+ * Lets agents read their own recent MCP tool executions from mcp_audit_log.
+ * Scoped to the caller's organisation; only mutating + destructive calls
+ * are recorded (read tools are not logged by default).
+ */
+import { PicaClient } from "@withpica/mcp-sdk";
+import { ToolDefinition, ToolExecutor } from "./index.js";
+export declare class AuditTools {
+    private pica;
+    constructor(pica: PicaClient);
+    getTools(): Array<{
+        definition: ToolDefinition;
+        executor: ToolExecutor;
+    }>;
+    private listAudit;
+}
+//# sourceMappingURL=audit.d.ts.map

package/dist/tools/audit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit.d.ts","sourceRoot":"","sources":["../../src/tools/audit.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,cAAc,EAAE,YAAY,EAAc,MAAM,YAAY,CAAC;AAGtE,qBAAa,UAAU;IACrB,OAAO,CAAC,IAAI,CAAa;gBAEb,IAAI,EAAE,UAAU;IAI5B,QAAQ,IAAI,KAAK,CAAC;QAAE,UAAU,EAAE,cAAc,CAAC;QAAC,QAAQ,EAAE,YAAY,CAAA;KAAE,CAAC;YA4C3D,SAAS;CAaxB"}

package/dist/tools/audit.js

@@ -0,0 +1,58 @@
+// Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
+import { formatStructuredList } from "@withpica/mcp-utils";
+export class AuditTools {
+    pica;
+    constructor(pica) {
+        this.pica = pica;
+    }
+    getTools() {
+        return [
+            {
+                definition: {
+                    name: "pica_audit_list",
+                    description: "List recent MCP tool executions for this workspace. Use to recall what AI actions have been taken — what was created, updated, deleted, or attempted. Only mutating and destructive calls are recorded; read-only queries are not. Scoped to your catalog.",
+                    workflows: "infrastructure",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            limit: {
+                                type: "number",
+                                description: "Max number of entries to return (default 25, max 100).",
+                            },
+                            since: {
+                                type: "string",
+                                description: "ISO 8601 timestamp — only return entries created at or after this time (e.g. '2026-04-01T00:00:00Z').",
+                            },
+                            tool_name: {
+                                type: "string",
+                                description: "Filter to a single tool by exact name (e.g. 'pica_works_create').",
+                            },
+                            risk_level: {
+                                type: "string",
+                                enum: ["safe", "mutating", "destructive"],
+                                description: "Filter by risk classification.",
+                            },
+                            result_status: {
+                                type: "string",
+                                enum: ["success", "error", "confirmation_required"],
+                                description: "Filter by execution outcome.",
+                            },
+                        },
+                    },
+                },
+                executor: this.listAudit.bind(this),
+            },
+        ];
+    }
+    async listAudit(args) {
+        const entries = await this.pica.audit.list({
+            limit: typeof args.limit === "number" ? args.limit : undefined,
+            since: typeof args.since === "string" ? args.since : undefined,
+            tool_name: typeof args.tool_name === "string" ? args.tool_name : undefined,
+            risk_level: typeof args.risk_level === "string" ? args.risk_level : undefined,
+            result_status: typeof args.result_status === "string" ? args.result_status : undefined,
+        });
+        return formatStructuredList(entries, "audit_entry");
+    }
+}
+//# sourceMappingURL=audit.js.map

package/dist/tools/audit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit.js","sourceRoot":"","sources":["../../src/tools/audit.ts"],"names":[],"mappings":"AAAA,6DAA6D;AAY7D,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAE3D,MAAM,OAAO,UAAU;IACb,IAAI,CAAa;IAEzB,YAAY,IAAgB;QAC1B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;IAED,QAAQ;QACN,OAAO;YACL;gBACE,UAAU,EAAE;oBACV,IAAI,EAAE,iBAAiB;oBACvB,WAAW,EACT,4PAA4P;oBAC9P,SAAS,EAAE,gBAAgB;oBAC3B,WAAW,EAAE;wBACX,IAAI,EAAE,QAAQ;wBACd,UAAU,EAAE;4BACV,KAAK,EAAE;gCACL,IAAI,EAAE,QAAQ;gCACd,WAAW,EACT,wDAAwD;6BAC3D;4BACD,KAAK,EAAE;gCACL,IAAI,EAAE,QAAQ;gCACd,WAAW,EACT,uGAAuG;6BAC1G;4BACD,SAAS,EAAE;gCACT,IAAI,EAAE,QAAQ;gCACd,WAAW,EACT,mEAAmE;6BACtE;4BACD,UAAU,EAAE;gCACV,IAAI,EAAE,QAAQ;gCACd,IAAI,EAAE,CAAC,MAAM,EAAE,UAAU,EAAE,aAAa,CAAC;gCACzC,WAAW,EAAE,gCAAgC;6BAC9C;4BACD,aAAa,EAAE;gCACb,IAAI,EAAE,QAAQ;gCACd,IAAI,EAAE,CAAC,SAAS,EAAE,OAAO,EAAE,uBAAuB,CAAC;gCACnD,WAAW,EAAE,8BAA8B;6BAC5C;yBACF;qBACF;iBACF;gBACD,QAAQ,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC;aACpC;SACF,CAAC;IACJ,CAAC;IAEO,KAAK,CAAC,SAAS,CAAC,IAAyB;QAC/C,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC;YACzC,KAAK,EAAE,OAAO,IAAI,CAAC,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS;YAC9D,KAAK,EAAE,OAAO,IAAI,CAAC,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS;YAC9D,SAAS,EACP,OAAO,IAAI,CAAC,SAAS,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS;YACjE,UAAU,EACR,OAAO,IAAI,CAAC,UAAU,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,SAAS;YACnE,aAAa,EACX,OAAO,IAAI,CAAC,aAAa,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,SAAS;SAC1E,CAAC,CAAC;QACH,OAAO,oBAAoB,CAAC,OAAO,EAAE,aAAa,CAAC,CAAC;IACtD,CAAC;CACF"}

package/dist/tools/auth.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Auth Tools — pica_sign_in and pica_sign_out
+ * Available in lobby mode (no API key required).
+ */
+import { ToolDefinition, ToolExecutor } from "./index.js";
+import { ServerConfig } from "../config.js";
+type ReinitializeCallback = (apiKey: string) => void;
+type SignOutCallback = () => void;
+export declare class AuthTools {
+    private config;
+    private reinitialize;
+    private signOutCallback;
+    constructor(config: ServerConfig, reinitialize: ReinitializeCallback, signOutCallback?: SignOutCallback);
+    getTools(): Array<{
+        definition: ToolDefinition;
+        executor: ToolExecutor;
+    }>;
+    private signIn;
+    private signOut;
+}
+export {};
+//# sourceMappingURL=auth.d.ts.map

package/dist/tools/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/tools/auth.ts"],"names":[],"mappings":"AAEA;;;GAGG;AAEH,OAAO,EAAE,cAAc,EAAE,YAAY,EAAc,MAAM,YAAY,CAAC;AACtE,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAO5C,KAAK,oBAAoB,GAAG,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;AACrD,KAAK,eAAe,GAAG,MAAM,IAAI,CAAC;AAKlC,qBAAa,SAAS;IACpB,OAAO,CAAC,MAAM,CAAe;IAC7B,OAAO,CAAC,YAAY,CAAuB;IAC3C,OAAO,CAAC,eAAe,CAAkB;gBAGvC,MAAM,EAAE,YAAY,EACpB,YAAY,EAAE,oBAAoB,EAClC,eAAe,GAAE,eAA0B;IAO7C,QAAQ,IAAI,KAAK,CAAC;QAAE,UAAU,EAAE,cAAc,CAAC;QAAC,QAAQ,EAAE,YAAY,CAAA;KAAE,CAAC;YAqC3D,MAAM;YAyKN,OAAO;CAwBtB"}