@yadsh/dsh-qa-surface 0.4.0 → 0.6.0

package/lib/documents/tools/shared.js

@@ -0,0 +1,88 @@
+/**
+ * What the four document tools share: the calling session's scope, the output
+ * shapes they render, and the warning formatter.
+ *
+ * A tool is a thin adapter. It reads the session's working directory (the
+ * artifact root and the allowed input roots both derive from it), hands intent
+ * to the runtime, and renders the structured result for the model. No tool
+ * knows a backend name beyond the one the result reports.
+ */
+import { DocumentError } from "../errors.js";
+export function toolWarnings(warnings) {
+    return warnings.map((warning) => ({
+        code: warning.code,
+        message: warning.message,
+        ...(warning.backend === undefined ? {} : { backend: warning.backend }),
+    }));
+}
+/** Shared output-schema fragment for the `warnings` array of every tool. */
+export const warningsSchema = {
+    type: "array",
+    items: {
+        type: "object",
+        additionalProperties: false,
+        properties: {
+            code: { type: "string", required: true },
+            message: { type: "string", required: true },
+            backend: { type: "string" },
+        },
+    },
+};
+/** Mutable projection of a produced file for the tool result. */
+export function toolFiles(files) {
+    return files.map((file) => ({
+        format: file.format,
+        path: file.path,
+        mediaType: file.mediaType,
+        size: file.size,
+        sha256: file.sha256,
+        status: file.status,
+        ...(file.error === undefined ? {} : { error: file.error }),
+    }));
+}
+/**
+ * Resolve the session scope, failing closed: a session without a working
+ * directory gets no document access rather than the host process's cwd.
+ */ export function requireDocumentScope(exec) {
+    const header = exec.agent?.session.header;
+    const cwd = header?.cwd;
+    if (typeof cwd !== "string" || cwd.trim() === "") {
+        throw new DocumentError("INVALID_INPUT", "this tool requires a calling session with a working directory");
+    }
+    const sessionId = header?.id === undefined ? undefined : String(header.id);
+    return {
+        workspaceRoot: cwd,
+        ...(sessionId === undefined ? {} : { sessionId }),
+        ...(exec.signal === undefined ? {} : { signal: exec.signal }),
+    };
+}
+export function fileParameter() {
+    return {
+        type: "string",
+        required: true,
+        description: "Path to the document. Relative paths start at the session working directory and must " +
+            "stay inside it or a configured document root.",
+    };
+}
+export function formatBytes(bytes) {
+    if (bytes < 1024)
+        return `${bytes} B`;
+    if (bytes < 1024 * 1024)
+        return `${(bytes / 1024).toFixed(1)} KiB`;
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MiB`;
+}
+export function renderWarning(warning) {
+    const backend = warning.backend === undefined ? "" : ` [${warning.backend}]`;
+    return `warning ${warning.code}${backend}: ${warning.message}`;
+}
+/** One line per produced file, plus failed formats explicitly named. */
+export function renderFiles(files) {
+    return files.map((file) => {
+        if (file.status === "failed") {
+            return `${file.format}: failed (${file.error ?? "unknown error"})`;
+        }
+        return `${file.format}: ${file.path} (${formatBytes(file.size)}, sha256 ${file.sha256.slice(0, 16)}…)`;
+    });
+}
+export const ARTIFACT_NOTE = "The artifact directory keeps the source, the assets and manifest.json beside the outputs.";
+//# sourceMappingURL=shared.js.map

package/lib/documents/tools/shared.js.map

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

package/lib/documents/tools/to-markdown.js

@@ -0,0 +1,125 @@
+/**
+ * `document_to_markdown` — DOCX/PDF to Markdown (§9, §34).
+ *
+ * The model gets the extracted text and a path to the full copy; the artifact
+ * bundle keeps the input, the extracted Markdown and any extracted images.
+ */
+import { defineTool } from "@deepseek-ai/dsh-tools";
+import { fileParameter, renderWarning, requireDocumentScope, toolWarnings, warningsSchema, } from "./shared.js";
+export const DOCUMENT_TO_MARKDOWN_TOOL = "document_to_markdown";
+const DESCRIPTION = [
+    "Extract a DOCX or PDF into Markdown.",
+    "Supports structured extraction, tables and images, and applies OCR when the document has no text layer.",
+    "Returns the Markdown plus the path of the extracted file inside its artifact bundle.",
+].join(" ");
+export function createDocumentToMarkdownTool(options) {
+    return defineTool({
+        name: DOCUMENT_TO_MARKDOWN_TOOL,
+        description: DESCRIPTION,
+        parameters: {
+            file: fileParameter(),
+            mode: {
+                type: "string",
+                enum: ["auto", "fast", "accurate"],
+                description: "Extraction route. `accurate` (default) uses the layout-aware extractor; `fast` prefers the light extractor when the deployment enables one.",
+            },
+            ocr: {
+                type: "string",
+                enum: ["auto", "off", "force"],
+                description: "OCR policy: `auto` lets the extractor decide per page, `off` never runs OCR, `force` always runs it.",
+            },
+            ocrLanguages: {
+                type: "array",
+                items: { type: "string" },
+                description: 'OCR languages, e.g. ["rus", "eng"].',
+            },
+            extractImages: {
+                type: "boolean",
+                description: "Write extracted images into the bundle's assets directory.",
+            },
+            extractTables: {
+                type: "boolean",
+                description: "Use the accurate table extraction mode.",
+            },
+            preservePageMarkers: {
+                type: "boolean",
+                description: "Keep page boundaries in the extracted Markdown where the extractor reports them.",
+            },
+            outputFilename: {
+                type: "string",
+                description: "Name of the extracted Markdown file inside the artifact bundle.",
+            },
+        },
+        output: {
+            schema: {
+                type: "object",
+                additionalProperties: false,
+                properties: {
+                    artifactId: { type: "string", required: true },
+                    markdown: { type: "string", required: true },
+                    markdownPath: { type: "string", required: true },
+                    assets: {
+                        type: "array",
+                        items: {
+                            type: "object",
+                            additionalProperties: false,
+                            properties: {
+                                path: { type: "string", required: true },
+                                mediaType: { type: "string", required: true },
+                            },
+                        },
+                    },
+                    pages: { type: "number" },
+                    backend: { type: "string", required: true },
+                    warnings: warningsSchema,
+                    manifestPath: { type: "string", required: true },
+                },
+            },
+            render: (_args, value) => {
+                const result = value;
+                return [
+                    {
+                        type: "text",
+                        text: [
+                            `artifact: ${result.artifactId} (extracted by ${result.backend})`,
+                            ...(result.pages === undefined ? [] : [`pages: ${result.pages}`]),
+                            `markdown: ${result.markdownPath}`,
+                            ...(result.assets === undefined
+                                ? []
+                                : [
+                                    `assets: ${result.assets.map((asset) => asset.path).join(", ")}`,
+                                ]),
+                            ...result.warnings.map(renderWarning),
+                            "---",
+                            result.markdown,
+                        ].join("\n"),
+                    },
+                ];
+            },
+        },
+        timeoutMs: options.runtime.config.docling.timeoutMs +
+            options.runtime.config.markitdown.timeoutMs +
+            30_000,
+        async execute(args, exec) {
+            const result = await options.runtime.toMarkdown(args, requireDocumentScope(exec));
+            return {
+                artifactId: result.artifactId,
+                markdown: result.markdown,
+                markdownPath: result.markdownPath,
+                ...(result.assets === undefined
+                    ? {}
+                    : {
+                        assets: result.assets.map((asset) => ({
+                            path: asset.path,
+                            mediaType: asset.mediaType,
+                        })),
+                    }),
+                ...(result.pages === undefined ? {} : { pages: result.pages }),
+                backend: result.backend,
+                warnings: toolWarnings(result.warnings),
+                manifestPath: result.manifestPath,
+            };
+        },
+    });
+}
+//# sourceMappingURL=to-markdown.js.map

package/lib/documents/tools/to-markdown.js.map

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

package/lib/documents/types.js

@@ -0,0 +1,12 @@
+/**
+ * Public types of the QA Surface document pipeline.
+ *
+ * The shapes here are the contract the agent sees (tool inputs and results),
+ * the contract the artifact store persists (manifest), and the contract the
+ * providers implement. They are deliberately free of any backend vocabulary:
+ * a tool result never names pandoc, LibreOffice or Docling, so a provider can
+ * be replaced without touching a prompt, a skill or a workflow
+ * (docs/specs/document-pipeline.md §4.1, §22).
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/lib/documents/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/documents/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG"}