diff --git a/.github/workflows/ci-auto-readme-generator.yml b/.github/workflows/ci-auto-readme-generator.yml
new file mode 100644
index 0000000..8afb738
--- /dev/null
+++ b/.github/workflows/ci-auto-readme-generator.yml
@@ -0,0 +1,24 @@
+name: CI - auto-readme-generator
+
+on:
+  push:
+    paths:
+      - "services/python-tools/tools/auto-readme-generator/**"
+  pull_request:
+    paths:
+      - "services/python-tools/tools/auto-readme-generator/**"
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Install deps
+        run: pip install -r services/python-tools/tools/auto-readme-generator/requirements.txt -r services/python-tools/tools/auto-readme-generator/requirements-dev.txt
+      - name: Run tests
+        run: |
+          cd services/python-tools/tools/auto-readme-generator
+          pytest tests/ -v
diff --git a/app/src/app/tools/[toolId]/page.tsx b/app/src/app/tools/[toolId]/page.tsx
index 154a99e..e914dcb 100644
--- a/app/src/app/tools/[toolId]/page.tsx
+++ b/app/src/app/tools/[toolId]/page.tsx
@@ -2,8 +2,9 @@
 
 import { Button, Label, Textarea } from "@ansospace/ui";
 import { ArrowUpRight, Crown, Lock, Play, X } from "lucide-react";
+import Image from "next/image";
 import { notFound, useParams } from "next/navigation";
-import { useCallback, useEffect, useState } from "react";
+import { useCallback, useEffect, useRef, useState } from "react";
 import { CodeEditor } from "@/components/code-editor";
 import { ResultViewer } from "@/components/result-viewer";
 import { ToolLayout } from "@/components/tool-layout";
@@ -135,6 +136,7 @@ function ToolPageContent({ toolId }: { toolId: string }) {
 								<p className="text-xs text-muted-foreground">
 									Upgrade your plan for more daily executions.{" "}
 									<button
+										type="button"
 										onClick={redirectToUpgrade}
 										className="text-primary hover:underline underline-offset-2"
 									>
@@ -191,6 +193,7 @@ function ToolPageContent({ toolId }: { toolId: string }) {
 								⚡ {toolUsage.remaining} use{toolUsage.remaining === 1 ? "" : "s"} remaining for
 								this tool today.{" "}
 								<button
+									type="button"
 									onClick={redirectToUpgrade}
 									className="underline underline-offset-2 hover:text-amber-400"
 								>
@@ -213,6 +216,7 @@ function ToolPageContent({ toolId }: { toolId: string }) {
 					<div className="relative mx-4 w-full max-w-md rounded-2xl border border-border/50 bg-card p-6 shadow-2xl animate-in zoom-in-95 duration-200">
 						{/* Close button */}
 						<button
+							type="button"
 							onClick={() => setShowUpgradeDialog(false)}
 							className="absolute right-4 top-4 rounded-full p-1 text-muted-foreground hover:bg-muted hover:text-foreground transition-colors"
 						>
@@ -293,6 +297,520 @@ function ToolPageContent({ toolId }: { toolId: string }) {
 // Generic input renderer - renders any InputFieldConfig
 // ---------------------------------------------------------------------------
 
+function PdfDropField({
+	config,
+	value,
+	onChange,
+}: {
+	config: InputFieldConfig;
+	value: string;
+	onChange: (value: string) => void;
+}) {
+	const dropRef = useRef<HTMLButtonElement>(null);
+	const fileInputRef = useRef<HTMLInputElement>(null);
+	const [dropState, setDropState] = useState<
+		| "idle"
+		| "hover"
+		| "loading"
+		| "loading-ocr"
+		| "loading-excel"
+		| "loading-word"
+		| "loading-image-ocr"
+		| "done"
+		| "error"
+	>("idle");
+	const [fileName, setFileName] = useState<string>("");
+	const [extractError, setExtractError] = useState<string>("");
+	const [source, setSource] = useState<"file" | "manual">("manual");
+
+	const maxMb = config.maxSizeMb ?? 20;
+	const maxBytes = maxMb * 1024 * 1024;
+
+	const extractText = useCallback(
+		async (file: File): Promise<string> => {
+			if (file.size > maxBytes) {
+				throw new Error(`File exceeds ${maxMb} MB limit.`);
+			}
+
+			const name = file.name.toLowerCase();
+			const win = window as unknown as Record<string, unknown>;
+
+			// ── HELPER: lazy-load a CDN script (idempotent) ──────────────────
+			async function loadScript(url: string, globalKey: string, label: string) {
+				if (!win[globalKey]) {
+					await new Promise<void>((resolve, reject) => {
+						const s = document.createElement("script");
+						s.src = url;
+						s.onload = () => resolve();
+						s.onerror = () =>
+							reject(new Error(`Failed to load ${label}. Check your internet connection.`));
+						document.head.appendChild(s);
+					});
+				}
+			}
+
+			// ── HELPER: OCR for an ImageBitmap or Blob with Tesseract.js ──────────────
+			async function runOcrOnBlob(blob: Blob): Promise<string> {
+				await loadScript(
+					"https://cdnjs.cloudflare.com/ajax/libs/tesseract.js/5.0.4/tesseract.min.js",
+					"Tesseract",
+					"Tesseract.js"
+				);
+				type TWorker = {
+					recognize: (img: Blob) => Promise<{ data: { text: string } }>;
+					terminate: () => Promise<void>;
+				};
+				type TTesseract = { createWorker: (lang: string) => Promise<TWorker> };
+				const Tesseract = win.Tesseract as TTesseract;
+				const worker = await Tesseract.createWorker("eng");
+				try {
+					const { data } = await worker.recognize(blob);
+					return data.text.trim();
+				} finally {
+					await worker.terminate();
+				}
+			}
+
+			// ════════════════════════════════════════════════════════════════════════
+			// PDF  (.pdf)
+			// ════════════════════════════════════════════════════════════════════════
+			if (name.endsWith(".pdf") || file.type === "application/pdf") {
+				// 1. Load pdf.js if missing
+				await loadScript(
+					"https://cdnjs.cloudflare.com/ajax/libs/pdf.js/3.11.174/pdf.min.js",
+					"pdfjsLib",
+					"pdf.js"
+				);
+				(
+					win.pdfjsLib as { GlobalWorkerOptions: { workerSrc: string } }
+				).GlobalWorkerOptions.workerSrc =
+					"https://cdnjs.cloudflare.com/ajax/libs/pdf.js/3.11.174/pdf.worker.min.js";
+
+				type PdfPage = {
+					getTextContent: () => Promise<{ items: { str: string; hasEOL?: boolean }[] }>;
+					getViewport: (o: { scale: number }) => { width: number; height: number };
+					render: (p: {
+						canvasContext: CanvasRenderingContext2D;
+						viewport: { width: number; height: number };
+					}) => { promise: Promise<void> };
+				};
+				const pdfjs = win.pdfjsLib as {
+					getDocument: (src: { data: ArrayBuffer }) => {
+						promise: Promise<{ numPages: number; getPage: (n: number) => Promise<PdfPage> }>;
+					};
+				};
+
+				const arrayBuffer = await file.arrayBuffer();
+				const pdf = await pdfjs.getDocument({ data: arrayBuffer }).promise;
+				const pages: string[] = [];
+
+				// 2. Native text extraction
+				for (let i = 1; i <= pdf.numPages; i++) {
+					const page = await pdf.getPage(i);
+					const content = await page.getTextContent();
+					const pageText = content.items
+						.map((item) => item.str + (item.hasEOL ? "\n" : ""))
+						.join("");
+					pages.push(pageText.trim());
+				}
+
+				const nativeText = pages.join("\n\n").trim();
+				if (nativeText.length > 30) return nativeText;
+
+				// 3. OCR fallback — scanned PDF (images, handwritten text, forms)
+				setDropState("loading-ocr");
+				const ocrPages: string[] = [];
+				const MAX_OCR_PAGES = 20;
+				const pagesToProcess = Math.min(pdf.numPages, MAX_OCR_PAGES);
+
+				for (let i = 1; i <= pagesToProcess; i++) {
+					const page = await pdf.getPage(i);
+					const viewport = page.getViewport({ scale: 2.5 });
+					const canvas = document.createElement("canvas");
+					canvas.width = Math.floor(viewport.width);
+					canvas.height = Math.floor(viewport.height);
+					const ctx = canvas.getContext("2d");
+					if (!ctx) throw new Error("Could not render PDF page for OCR.");
+					await page.render({ canvasContext: ctx, viewport }).promise;
+
+					const blob = await new Promise<Blob>((res, rej) =>
+						canvas.toBlob(
+							(b) => (b ? res(b) : rej(new Error("Could not render PDF page to image."))),
+							"image/png"
+						)
+					);
+					ocrPages.push(await runOcrOnBlob(blob));
+
+					// Release canvas memory after each page
+					canvas.width = 0;
+					canvas.height = 0;
+				}
+
+				if (pdf.numPages > MAX_OCR_PAGES) {
+					ocrPages.push(
+						`\n\n[Note: OCR was limited to the first ${MAX_OCR_PAGES} pages out of ${pdf.numPages} total.]`
+					);
+				}
+
+				const ocrText = ocrPages.join("\n\n").trim();
+				if (!ocrText)
+					throw new Error(
+						"OCR did not find readable text. The PDF may be blank or fully graphical."
+					);
+				return ocrText;
+			}
+
+			// ════════════════════════════════════════════════════════════════════════
+			// DIRECT IMAGES (.jpg, .jpeg, .png, .webp, .gif)
+			// Use case: photo of a document, whiteboard, scanned receipt
+			// ════════════════════════════════════════════════════════════════════════
+			if (
+				name.endsWith(".jpg") ||
+				name.endsWith(".jpeg") ||
+				name.endsWith(".png") ||
+				name.endsWith(".webp") ||
+				name.endsWith(".gif") ||
+				file.type.startsWith("image/")
+			) {
+				setDropState("loading-image-ocr");
+				const text = await runOcrOnBlob(file);
+				if (!text)
+					throw new Error(
+						"No readable text found in this image. Make sure the text is clear and not too small."
+					);
+				return text;
+			}
+
+			// ════════════════════════════════════════════════════════════════════════
+			// EXCEL (.xlsx, .xls)
+			// Convert to tabular text: headers + rows separated by tabs
+			// ════════════════════════════════════════════════════════════════════════
+			if (name.endsWith(".xlsx") || name.endsWith(".xls")) {
+				setDropState("loading-excel");
+				await loadScript(
+					"https://cdnjs.cloudflare.com/ajax/libs/xlsx/0.18.5/xlsx.full.min.js",
+					"XLSX",
+					"SheetJS"
+				);
+				type XLSXLib = {
+					read: (
+						data: ArrayBuffer,
+						opts: { type: string }
+					) => {
+						SheetNames: string[];
+						Sheets: Record<string, unknown>;
+					};
+					utils: {
+						sheet_to_csv: (sheet: unknown) => string;
+					};
+				};
+				const XLSX = win.XLSX as XLSXLib;
+				const arrayBuffer = await file.arrayBuffer();
+				const workbook = XLSX.read(arrayBuffer, { type: "array" });
+				const sections: string[] = [];
+
+				for (const sheetName of workbook.SheetNames) {
+					const csv = XLSX.utils.sheet_to_csv(workbook.Sheets[sheetName]);
+					const nonEmpty = csv
+						.split("\n")
+						.filter((l) => l.replace(/,/g, "").trim())
+						.join("\n");
+					if (nonEmpty.trim()) {
+						sections.push(`### Sheet: ${sheetName}\n${nonEmpty}`);
+					}
+				}
+
+				if (!sections.length) throw new Error("The Excel file appears to be empty.");
+				return sections.join("\n\n");
+			}
+
+			// ════════════════════════════════════════════════════════════════════════
+			// WORD (.docx)
+			// Extract text while preserving paragraph structure
+			// ════════════════════════════════════════════════════════════════════════
+			if (name.endsWith(".docx")) {
+				setDropState("loading-word");
+				await loadScript(
+					"https://cdnjs.cloudflare.com/ajax/libs/mammoth/1.6.0/mammoth.browser.min.js",
+					"mammoth",
+					"Mammoth.js"
+				);
+				type MammothLib = {
+					extractRawText: (opts: { arrayBuffer: ArrayBuffer }) => Promise<{ value: string }>;
+				};
+				const mammoth = win.mammoth as MammothLib;
+				const arrayBuffer = await file.arrayBuffer();
+				const result = await mammoth.extractRawText({ arrayBuffer });
+				const text = result.value.trim();
+				if (!text)
+					throw new Error("The Word document appears to be empty or contains only images.");
+				return text;
+			}
+
+			// ════════════════════════════════════════════════════════════════════════
+			// CSV (.csv) — browser-native, no library needed
+			// ════════════════════════════════════════════════════════════════════════
+			if (name.endsWith(".csv")) {
+				const text = await file.text();
+				if (!text.trim()) throw new Error("The CSV file is empty.");
+				// Count columns from the first row to give the model context
+				const lines = text.split("\n").filter((l) => l.trim());
+				const headerCols = lines[0]?.split(",").length ?? 0;
+				const preview = `CSV Document — ${lines.length - 1} rows × ${headerCols} columns\n\n${text}`;
+				return preview;
+			}
+
+			// ════════════════════════════════════════════════════════════════════════
+			// PLAIN TEXT (.txt, .md, and any other)
+			// ════════════════════════════════════════════════════════════════════════
+			const text = await file.text();
+			if (!text.trim()) throw new Error("The file appears to be empty.");
+			return text;
+		},
+		[maxMb, maxBytes]
+	);
+
+	const processFile = useCallback(
+		async (file: File) => {
+			setDropState("loading");
+			setFileName(file.name);
+			setExtractError("");
+			try {
+				const text = await extractText(file);
+				if (!text.trim()) throw new Error("No readable text found in this file.");
+				onChange(text);
+				setSource("file"); // Track that this value came from a file
+				setDropState("done");
+			} catch (err) {
+				setExtractError(err instanceof Error ? err.message : "Unknown error.");
+				setDropState("error");
+			}
+		},
+		[extractText, onChange]
+	);
+
+	const handleDragOver = useCallback((e: React.DragEvent) => {
+		e.preventDefault();
+		setDropState("hover");
+	}, []);
+
+	const handleDragLeave = useCallback(() => {
+		setDropState(source === "file" ? "done" : "idle");
+	}, [source]);
+
+	const handleDrop = useCallback(
+		(e: React.DragEvent) => {
+			e.preventDefault();
+			const file = e.dataTransfer.files?.[0];
+			if (file) processFile(file);
+		},
+		[processFile]
+	);
+
+	const handleFileInput = useCallback(
+		(e: React.ChangeEvent<HTMLInputElement>) => {
+			const file = e.target.files?.[0];
+			if (file) processFile(file);
+			e.target.value = "";
+		},
+		[processFile]
+	);
+
+	const handleClear = useCallback(() => {
+		onChange("");
+		setFileName("");
+		setDropState("idle");
+		setExtractError("");
+		setSource("manual"); // Reset to manual mode when cleared
+	}, [onChange]);
+
+	const isLoading =
+		dropState === "loading" ||
+		dropState === "loading-ocr" ||
+		dropState === "loading-excel" ||
+		dropState === "loading-word" ||
+		dropState === "loading-image-ocr";
+
+	const dropZoneBorder =
+		dropState === "hover"
+			? "border-primary bg-primary/5"
+			: dropState === "error"
+				? "border-destructive bg-destructive/5"
+				: dropState === "done"
+					? "border-primary/50 bg-primary/[0.03]"
+					: isLoading
+						? "border-primary/30 bg-muted/20"
+						: "border-input hover:border-primary/40 hover:bg-muted/30";
+
+	return (
+		<div className="space-y-2">
+			<Label>{config.label}</Label>
+
+			<input
+				ref={fileInputRef}
+				type="file"
+				accept={config.accept || ".pdf,.txt,.md,.csv,.xlsx,.xls,.docx,.jpg,.jpeg,.png,.webp,.gif"}
+				className="hidden"
+				onChange={handleFileInput}
+			/>
+			<button
+				type="button"
+				ref={dropRef}
+				onDragOver={handleDragOver}
+				onDragLeave={handleDragLeave}
+				onDrop={handleDrop}
+				onClick={() => fileInputRef.current?.click()}
+				className={`relative flex w-full cursor-pointer flex-col items-center justify-center gap-2 rounded-lg border-2 border-dashed px-4 py-6 text-center transition-colors ${dropZoneBorder}`}
+			>
+				{dropState === "loading" && (
+					<>
+						<div className="h-6 w-6 animate-spin rounded-full border-2 border-primary border-t-transparent" />
+						<p className="text-sm text-muted-foreground">Extracting text from {fileName}...</p>
+					</>
+				)}
+
+				{dropState === "loading-ocr" && (
+					<>
+						<div className="h-6 w-6 animate-spin rounded-full border-2 border-primary border-t-transparent" />
+						<p className="text-sm text-muted-foreground">
+							No text found - running OCR on {fileName}...
+						</p>
+						<p className="text-xs text-muted-foreground">This may take 10-30 seconds</p>
+					</>
+				)}
+
+				{dropState === "loading-excel" && (
+					<>
+						<div className="h-6 w-6 animate-spin rounded-full border-2 border-primary border-t-transparent" />
+						<p className="text-sm text-muted-foreground">Reading spreadsheet from {fileName}…</p>
+						<p className="text-xs text-muted-foreground">Converting sheets to text</p>
+					</>
+				)}
+
+				{dropState === "loading-word" && (
+					<>
+						<div className="h-6 w-6 animate-spin rounded-full border-2 border-primary border-t-transparent" />
+						<p className="text-sm text-muted-foreground">Extracting text from {fileName}…</p>
+						<p className="text-xs text-muted-foreground">Processing Word document</p>
+					</>
+				)}
+
+				{dropState === "loading-image-ocr" && (
+					<>
+						<div className="h-6 w-6 animate-spin rounded-full border-2 border-primary border-t-transparent" />
+						<p className="text-sm text-muted-foreground">Running OCR on {fileName}…</p>
+						<p className="text-xs text-muted-foreground">This may take 15–40 seconds</p>
+					</>
+				)}
+
+				{dropState === "done" && (
+					<>
+						<svg
+							xmlns="http://www.w3.org/2000/svg"
+							aria-hidden="true"
+							className="h-6 w-6 text-primary"
+							fill="none"
+							viewBox="0 0 24 24"
+							stroke="currentColor"
+							strokeWidth={2}
+						>
+							<path strokeLinecap="round" strokeLinejoin="round" d="M5 13l4 4L19 7" />
+						</svg>
+						<p className="text-sm font-medium text-primary">{fileName}</p>
+						<p className="text-xs text-muted-foreground">
+							{value.length.toLocaleString()} chars extracted · Click to replace
+						</p>
+					</>
+				)}
+
+				{dropState === "error" && (
+					<>
+						<svg
+							xmlns="http://www.w3.org/2000/svg"
+							aria-hidden="true"
+							className="h-6 w-6 text-destructive"
+							fill="none"
+							viewBox="0 0 24 24"
+							stroke="currentColor"
+							strokeWidth={2}
+						>
+							<path
+								strokeLinecap="round"
+								strokeLinejoin="round"
+								d="M12 9v4m0 4h.01M10.29 3.86L1.82 18a2 2 0 001.71 3h16.94a2 2 0 001.71-3L13.71 3.86a2 2 0 00-3.42 0z"
+							/>
+						</svg>
+						<p className="text-sm text-destructive">{extractError}</p>
+						<p className="text-xs text-muted-foreground">Click to try another file</p>
+					</>
+				)}
+
+				{(dropState === "idle" || dropState === "hover") && (
+					<>
+						<svg
+							xmlns="http://www.w3.org/2000/svg"
+							aria-hidden="true"
+							className={`h-8 w-8 transition-colors ${
+								dropState === "hover" ? "text-primary" : "text-muted-foreground"
+							}`}
+							fill="none"
+							viewBox="0 0 24 24"
+							stroke="currentColor"
+							strokeWidth={1.5}
+						>
+							<path
+								strokeLinecap="round"
+								strokeLinejoin="round"
+								d="M7 16a4 4 0 01-.88-7.903A5 5 0 1115.9 6L16 6a5 5 0 011 9.9M15 13l-3-3m0 0l-3 3m3-3v12"
+							/>
+						</svg>
+						<p className="text-sm font-medium">
+							{dropState === "hover"
+								? "Release to upload"
+								: "Drag your document here or click to browse"}
+						</p>
+						<p className="text-xs text-muted-foreground">
+							{config.helperText || "PDF · Word · Excel · CSV · Images · TXT — Max 25 MB"}
+						</p>
+					</>
+				)}
+			</button>
+
+			{value && !isLoading && (
+				<button
+					type="button"
+					onClick={(e) => {
+						e.stopPropagation();
+						handleClear();
+					}}
+					className="text-xs text-muted-foreground underline underline-offset-2 hover:text-foreground transition-colors"
+				>
+					Clear and start over
+				</button>
+			)}
+
+			{/* Only show the paste textarea when the user is typing, not when a file was loaded */}
+			{source === "manual" && (
+				<div className="space-y-1">
+					<p className="text-xs text-muted-foreground">Or paste / type text directly:</p>
+					<Textarea
+						value={value}
+						onChange={(e) => {
+							setSource("manual");
+							onChange(e.target.value);
+							if (e.target.value && dropState === "idle") setDropState("done");
+							if (!e.target.value) setDropState("idle");
+						}}
+						placeholder={config.placeholder}
+						rows={config.rows || 14}
+						className="resize-none font-mono text-xs"
+					/>
+				</div>
+			)}
+		</div>
+	);
+}
+
 function InputField({
 	config,
 	value,
@@ -385,7 +903,7 @@ function InputField({
 						/>
 						{value && (
 							<div className="relative h-10 w-10 shrink-0 overflow-hidden rounded-md border">
-								<img src={value} alt="Preview" className="h-full w-full object-cover" />
+								<Image src={value} alt="Preview" fill unoptimized className="object-cover" />
 							</div>
 						)}
 					</div>
@@ -479,7 +997,7 @@ function InputField({
 											)
 										);
 										const valid = Array.from(files).filter((f) => {
-											const ext = "." + f.name.split(".").pop()?.toLowerCase();
+											const ext = `.${f.name.split(".").pop()?.toLowerCase()}`;
 											const p = f.webkitRelativePath || f.name;
 											if (
 												p.includes("__pycache__") ||
@@ -530,6 +1048,9 @@ function InputField({
 				</div>
 			);
 
+		case "pdf-drop":
+			return <PdfDropField config={config} value={value} onChange={onChange} />;
+
 		default:
 			return null;
 	}
diff --git a/app/src/components/result-viewer.tsx b/app/src/components/result-viewer.tsx
index 8231460..7df87d5 100644
--- a/app/src/components/result-viewer.tsx
+++ b/app/src/components/result-viewer.tsx
@@ -60,6 +60,7 @@ function MermaidViewer({ chart }: { chart: string }) {
 		<div
 			ref={containerRef}
 			className="mermaid-wrapper my-6 flex items-center justify-center overflow-auto rounded-lg border border-border bg-zinc-950 dark:bg-zinc-900 p-6"
+			// biome-ignore lint/security/noDangerouslySetInnerHtml: Mermaid renders SVG markup.
 			dangerouslySetInnerHTML={{ __html: svg }}
 		/>
 	);
@@ -75,6 +76,23 @@ interface ResultViewerProps {
 	onOpenSettings?: () => void;
 }
 
+function stripThinkBlocks(text: string) {
+	// Remove well-formed <think> blocks first.
+	let out = text.replace(/<think\b[^>]*>[\s\S]*?<\/think>/gi, "");
+
+	// If an unclosed <think> remains, trim from the first real report heading.
+	if (/<think/i.test(out)) {
+		const headingIdx = out.search(/\n##\s/);
+		if (headingIdx !== -1) {
+			out = out.slice(headingIdx).trim();
+		} else {
+			out = out.replace(/<think[\s\S]*/i, "").trim();
+		}
+	}
+
+	return out;
+}
+
 const ERROR_CONFIG: Record<string, { icon: React.ReactNode; label: string; color: string }> = {
 	model_access_denied: {
 		icon: <Lock className="h-5 w-5" />,
@@ -216,6 +234,13 @@ export function ResultViewer({
 }: ResultViewerProps) {
 	const [copiedAll, setCopiedAll] = useState(false);
 	const [activeTab, setActiveTab] = useState<"preview" | "code">("preview");
+	const [logsExpanded, setLogsExpanded] = useState(false);
+
+	useEffect(() => {
+		if (result.includes("---REPORT_START---") && !isLoading) {
+			setLogsExpanded(false);
+		}
+	}, [isLoading, result]);
 
 	const handleCopyAll = useCallback(async () => {
 		await navigator.clipboard.writeText(result);
@@ -272,8 +297,8 @@ export function ResultViewer({
 		);
 	}
 
-	let parsedJson: { code?: string; [key: string]: any } | null = null;
-	let displayMarkdown = result;
+	let parsedJson: { code?: string; [key: string]: unknown } | null = null;
+	let displayMarkdown = "";
 	let pipelineLogs = "";
 	let isReportStarted = false;
 
@@ -281,12 +306,14 @@ export function ResultViewer({
 		if (result.includes("---REPORT_START---")) {
 			const parts = result.split("---REPORT_START---");
 			pipelineLogs = parts[0].trim();
-			displayMarkdown = parts[1] || "";
+			displayMarkdown = stripThinkBlocks(parts[1] || "");
 			isReportStarted = true;
 		} else if (streaming && isLoading) {
 			// If we haven't hit the report marker yet, everything is logs.
 			pipelineLogs = result.trim();
 			displayMarkdown = "";
+		} else {
+			displayMarkdown = stripThinkBlocks(result || "");
 		}
 	}
 
@@ -327,7 +354,11 @@ export function ResultViewer({
 			{pipelineLogs && (
 				<Card className="border-primary/20 bg-primary/[0.02] overflow-hidden">
 					<CardContent className="p-0">
-						<div className="flex items-center gap-3 border-b border-border/40 bg-muted/30 px-4 py-3">
+						<button
+							type="button"
+							onClick={() => setLogsExpanded((value) => !value)}
+							className="flex w-full items-center gap-3 border-b border-border/40 bg-muted/30 px-4 py-3 text-left"
+						>
 							<div className="relative">
 								{isLoading && !isReportStarted ? (
 									<Spinner className="h-4 w-4 text-primary" />
@@ -338,47 +369,55 @@ export function ResultViewer({
 									<Sparkles className="absolute -top-1 -right-1 h-2 w-2 animate-pulse text-primary" />
 								)}
 							</div>
-							<span className="text-sm font-medium text-muted-foreground">
+							<span className="flex-1 text-sm font-medium text-muted-foreground">
 								{isLoading && !isReportStarted ? "Agent Pipeline Running..." : "Pipeline Complete"}
 							</span>
-						</div>
-						<div className="max-h-[300px] overflow-y-auto bg-zinc-950 p-4 font-mono text-[13px] leading-relaxed text-zinc-300 dark:bg-zinc-950/50">
-							{pipelineLogs.split("\n").map((line, i) => {
-								if (!line.trim() || line === ".") return null;
-								let textColor = "text-zinc-400";
-								if (line.startsWith("[")) {
-									textColor = "text-primary font-semibold";
-								} else if (line.startsWith(">")) {
-									textColor = "text-zinc-300 ml-4 border-l-2 border-primary/30 pl-2";
-								} else if (
-									line.toLowerCase().includes("error") ||
-									line.toLowerCase().includes("failed")
-								) {
-									textColor = "text-red-400";
-								}
-								return (
-									<div key={i} className={`py-0.5 ${textColor}`}>
-										{line}
+							<span className="text-xs text-muted-foreground">
+								{isLoading && !isReportStarted ? "▼ visible" : logsExpanded ? "▲ hide" : "▼ show"}
+							</span>
+						</button>
+						{(isLoading && !isReportStarted) || logsExpanded ? (
+							<div className="max-h-[300px] overflow-y-auto bg-zinc-950 p-4 font-mono text-[13px] leading-relaxed text-zinc-300 dark:bg-zinc-950/50">
+								{pipelineLogs.split("\n").map((line) => {
+									if (!line.trim() || line === ".") return null;
+									let textColor = "text-zinc-400";
+									if (line.startsWith("[")) {
+										textColor = "text-primary font-semibold";
+									} else if (line.startsWith(">")) {
+										textColor = "text-zinc-300 ml-4 border-l-2 border-primary/30 pl-2";
+									} else if (
+										line.toLowerCase().includes("error") ||
+										line.toLowerCase().includes("failed")
+									) {
+										textColor = "text-red-400";
+									}
+									return (
+										<div
+											key={line ? `log-${line.slice(0, 20)}` : "empty-log"}
+											className={`py-0.5 ${textColor}`}
+										>
+											{line}
+										</div>
+									);
+								})}
+								{isLoading && !isReportStarted && (
+									<div className="mt-2 flex items-center gap-1.5 text-primary/70">
+										<span
+											className="h-1.5 w-1.5 animate-bounce rounded-full bg-primary/70"
+											style={{ animationDelay: "0ms" }}
+										/>
+										<span
+											className="h-1.5 w-1.5 animate-bounce rounded-full bg-primary/70"
+											style={{ animationDelay: "150ms" }}
+										/>
+										<span
+											className="h-1.5 w-1.5 animate-bounce rounded-full bg-primary/70"
+											style={{ animationDelay: "300ms" }}
+										/>
 									</div>
-								);
-							})}
-							{isLoading && !isReportStarted && (
-								<div className="mt-2 flex items-center gap-1.5 text-primary/70">
-									<span
-										className="h-1.5 w-1.5 animate-bounce rounded-full bg-primary/70"
-										style={{ animationDelay: "0ms" }}
-									/>
-									<span
-										className="h-1.5 w-1.5 animate-bounce rounded-full bg-primary/70"
-										style={{ animationDelay: "150ms" }}
-									/>
-									<span
-										className="h-1.5 w-1.5 animate-bounce rounded-full bg-primary/70"
-										style={{ animationDelay: "300ms" }}
-									/>
-								</div>
-							)}
-						</div>
+								)}
+							</div>
+						) : null}
 					</CardContent>
 				</Card>
 			)}
@@ -417,6 +456,7 @@ export function ResultViewer({
 					{hasHtmlCode && (
 						<div className="flex border-b border-border/50 px-4 pt-3 bg-muted/20">
 							<button
+								type="button"
 								onClick={() => setActiveTab("preview")}
 								className={`px-4 py-2 text-sm font-medium border-b-2 transition-colors ${
 									activeTab === "preview"
@@ -427,6 +467,7 @@ export function ResultViewer({
 								Preview
 							</button>
 							<button
+								type="button"
 								onClick={() => setActiveTab("code")}
 								className={`px-4 py-2 text-sm font-medium border-b-2 transition-colors ${
 									activeTab === "code"
diff --git a/app/src/components/tools/app-sidebar.tsx b/app/src/components/tools/app-sidebar.tsx
index 62cd39d..807d4eb 100644
--- a/app/src/components/tools/app-sidebar.tsx
+++ b/app/src/components/tools/app-sidebar.tsx
@@ -22,6 +22,7 @@ import {
 	Server,
 	Settings,
 } from "lucide-react";
+import Image from "next/image";
 import Link from "next/link";
 import { usePathname, useRouter } from "next/navigation";
 import { useEffect, useState } from "react";
@@ -72,6 +73,7 @@ function CollapsibleCategory({
 		<div className="group-data-[collapsible=icon]:hidden">
 			{/* Category header with icon */}
 			<button
+				type="button"
 				onClick={() => {
 					setIsOpen(!isOpen);
 					router.push(`/tools#${categoryKey}`);
@@ -155,7 +157,13 @@ export function AppSidebar() {
 					<SidebarMenuItem>
 						<SidebarMenuButton size="lg" render={<Link href="/tools" />} tooltip="Oxtools">
 							<span className="flex h-8 w-8 items-center justify-center rounded-lg overflow-hidden shrink-0">
-								<img src="/logo-icon-teal.png" alt="Oxlo" className="h-7 w-7 object-contain" />
+								<Image
+									src="/logo-icon-teal.png"
+									alt="Oxlo"
+									width={28}
+									height={28}
+									className="h-7 w-7 object-contain"
+								/>
 							</span>
 							<div className="grid flex-1 text-left text-sm leading-tight">
 								<span
@@ -286,6 +294,7 @@ function UsageCounter() {
 				{/* Upgrade link for free users */}
 				{planId === "free" && (
 					<button
+						type="button"
 						onClick={redirectToUpgrade}
 						className="w-full text-[10px] text-center text-primary hover:underline underline-offset-2"
 					>
diff --git a/app/src/components/usage-counter.tsx b/app/src/components/usage-counter.tsx
index 5177f84..6fe5be1 100644
--- a/app/src/components/usage-counter.tsx
+++ b/app/src/components/usage-counter.tsx
@@ -10,7 +10,7 @@ import { useAuth } from "@/providers/auth-provider";
  * Shows upgrade prompt when approaching or at limit.
  */
 export function UsageCounter() {
-	const { user, usage, isLoading, isAuthenticated, redirectToLogin, redirectToUpgrade } = useAuth();
+	const { usage, isLoading, isAuthenticated, redirectToLogin, redirectToUpgrade } = useAuth();
 
 	if (isLoading) {
 		return (
@@ -71,6 +71,7 @@ export function UsageCounter() {
 
 			{!isAuthenticated && !isExhausted && (
 				<button
+					type="button"
 					onClick={redirectToLogin}
 					className="w-full text-[10px] text-primary hover:underline underline-offset-2 text-center"
 				>
diff --git a/app/src/lib/tools/auto-readme-generator.ts b/app/src/lib/tools/auto-readme-generator.ts
new file mode 100644
index 0000000..ee91880
--- /dev/null
+++ b/app/src/lib/tools/auto-readme-generator.ts
@@ -0,0 +1,42 @@
+import type { ToolDefinition } from "@/types";
+
+export const autoReadmeGeneratorTool: ToolDefinition = {
+	id: "auto-readme-generator",
+	name: "Auto README Generator",
+	description: "Multi-agent pipeline that generates structured, validated READMEs.",
+	category: "documentation",
+	icon: "FileText",
+	status: "active",
+	outputFormat: "streaming-text",
+
+	// Tier 2: runs in the unified Python tool runner
+	tier: "tier2",
+
+	requiredFields: ["projectName", "projectDescription"],
+	defaultModel: "llama-3.3-70b",
+	buildSystemPrompt: () => "",
+	buildUserPrompt: ({ projectName, projectDescription, techStack }) =>
+		JSON.stringify({ projectName, projectDescription, techStack }),
+
+	inputs: [
+		{
+			key: "projectName",
+			label: "Project Name",
+			type: "text",
+			placeholder: "e.g. my-fastapi-app",
+		},
+		{
+			key: "projectDescription",
+			label: "Project Description",
+			type: "textarea",
+			placeholder: "What does your project do? Main features, target users.",
+			rows: 5,
+		},
+		{
+			key: "techStack",
+			label: "Tech Stack (optional)",
+			type: "text",
+			placeholder: "e.g. Python, FastAPI, PostgreSQL, Docker",
+		},
+	],
+};
diff --git a/app/src/lib/tools/pdf-summarizer.ts b/app/src/lib/tools/pdf-summarizer.ts
index 5039aeb..55326de 100644
--- a/app/src/lib/tools/pdf-summarizer.ts
+++ b/app/src/lib/tools/pdf-summarizer.ts
@@ -4,36 +4,30 @@ export const pdfSummarizer: ToolDefinition = {
 	id: "pdf-summarizer",
 	name: "PDF / Document Summarizer",
 	description:
-		"Paste document text and get a structured executive summary with key findings, action items, and highlights.",
+		"Upload any document — PDF, Word, Excel, CSV, or image — and get a structured executive summary with key findings, action items, and extracted data.",
 	category: "documentation",
 	icon: "FileSearch",
 	status: "active",
 
+	// Tier 2: runs in the unified Python tool runner
+	tier: "tier2",
+
 	requiredFields: ["documentText"],
 	defaultModel: "deepseek-r1-0528",
 
-	buildSystemPrompt: () =>
-		`You are an executive assistant and document analyst. Summarize the provided document text into a structured report:
-
-1. **Executive Summary** - 2-3 sentence overview
-2. **Key Findings** - Bulleted list of the most important points
-3. **Data & Numbers** - Extract all specific numbers, dates, amounts, percentages
-4. **Action Items** - Any tasks, deadlines, or next steps mentioned
-5. **Notable Quotes** - Direct quotes worth highlighting
-6. **Risk Factors** - Any concerns or warnings mentioned
-
-Be concise but comprehensive. Use markdown formatting.`,
-
-	buildUserPrompt: ({ documentText, focus }) =>
-		`${focus ? `**FOCUS AREA:** ${focus}\n\n` : ""}**DOCUMENT TEXT:**\n\`\`\`\n${documentText}\n\`\`\`\n\nSummarize this document.`,
+	buildSystemPrompt: () => "",
+	buildUserPrompt: () => "",
 
 	inputs: [
 		{
 			key: "documentText",
-			label: "Document Text",
-			type: "code",
-			placeholder: "Paste the text content of your document here...",
+			label: "Document",
+			type: "pdf-drop",
+			placeholder: "Drag a file here, or paste text directly...",
 			rows: 14,
+			accept: ".pdf,.txt,.md,.csv,.xlsx,.xls,.docx,.jpg,.jpeg,.png,.webp,.gif",
+			maxSizeMb: 25,
+			helperText: "PDF · Word · Excel · CSV · Images (JPG, PNG) · TXT · MD — Max 25 MB",
 		},
 		{
 			key: "focus",
diff --git a/app/src/lib/tools/registry.ts b/app/src/lib/tools/registry.ts
index 63fd80b..e4db3be 100644
--- a/app/src/lib/tools/registry.ts
+++ b/app/src/lib/tools/registry.ts
@@ -3,6 +3,7 @@ import type { CategoryInfo, ToolCategory, ToolDefinition } from "@/types";
 import { apiChangeAnalyzer } from "./api-change-analyzer";
 import { apiValidator } from "./api-validator";
 import { architectureDiagram } from "./architecture-diagram";
+import { autoReadmeGeneratorTool } from "./auto-readme-generator";
 import { bugReplayer } from "./bug-replayer";
 import { captionGenerator } from "./caption-generator";
 // --- Core tool definitions ---
@@ -114,6 +115,7 @@ export const tools: ToolDefinition[] = [
 	captionGenerator,
 	seoWriter,
 	deepResearch, // Tier 2: LangGraph multi-agent Python service
+	autoReadmeGeneratorTool,
 ];
 
 // ---------------------------------------------------------------------------
diff --git a/app/src/types/index.ts b/app/src/types/index.ts
index 3db21f9..2b60ffe 100644
--- a/app/src/types/index.ts
+++ b/app/src/types/index.ts
@@ -5,7 +5,7 @@ export type ToolStatus = "active" | "coming-soon";
 export interface InputFieldConfig {
 	key: string;
 	label: string;
-	type: "code" | "textarea" | "select" | "text" | "image" | "files";
+	type: "code" | "textarea" | "select" | "text" | "image" | "files" | "pdf-drop";
 	placeholder?: string;
 	rows?: number;
 	options?: { value: string; label: string }[];
@@ -32,6 +32,8 @@ export interface ToolDefinition {
 	icon: string;
 	/** Active or placeholder */
 	status: ToolStatus;
+	/** Output format hint for frontend rendering (e.g. "streaming-text") */
+	outputFormat?: string;
 
 	// --- Tier config ---
 	/**
diff --git a/services/python-tools/tools/auto-readme-generator/analyzer.py b/services/python-tools/tools/auto-readme-generator/analyzer.py
new file mode 100644
index 0000000..3aeb82d
--- /dev/null
+++ b/services/python-tools/tools/auto-readme-generator/analyzer.py
@@ -0,0 +1,110 @@
+import json
+import re
+from typing import Literal
+
+from pydantic import BaseModel, ValidationError
+
+from llm_client import call_oxlo_chat
+
+ANALYZER_MODEL = "deepseek-v3.2"
+
+DEFAULT_METADATA = {
+    "language": "unknown",
+    "package_manager": "unknown",
+    "framework": "unknown",
+    "entry_point": "unknown",
+    "project_type": "other",
+}
+
+
+class ProjectMetadata(BaseModel):
+    language: str = "unknown"
+    package_manager: str = "unknown"
+    framework: str = "unknown"
+    entry_point: str = "unknown"
+    project_type: Literal["library", "cli", "web-api", "web-app", "other"] = "other"
+
+
+def _sanitize(value: str, max_len: int = 500) -> str:
+    if not isinstance(value, str):
+        return ""
+    return value.strip()[:max_len]
+
+
+def _extract_json(text: str) -> str:
+    text = text.strip()
+    if text.startswith("```"):
+        text = re.sub(r"^```[a-zA-Z0-9_-]*", "", text)
+        text = re.sub(r"```$", "", text.strip())
+    return text
+
+
+def _parse_json(text: str) -> dict:
+    try:
+        parsed = json.loads(text)
+        if isinstance(parsed, dict):
+            return parsed
+        if isinstance(parsed, list):
+            for item in parsed:
+                if isinstance(item, dict):
+                    return item
+    except json.JSONDecodeError:
+        pass
+
+    for pattern in (r"\{.*\}", r"\[.*\]"):
+        match = re.search(pattern, text, re.DOTALL)
+        if not match:
+            continue
+        try:
+            parsed = json.loads(match.group(0))
+        except json.JSONDecodeError:
+            continue
+        if isinstance(parsed, dict):
+            return parsed
+        if isinstance(parsed, list):
+            for item in parsed:
+                if isinstance(item, dict):
+                    return item
+
+    return DEFAULT_METADATA.copy()
+
+
+async def analyze_project(name: str, description: str, tech_stack: str) -> dict:
+    safe_name = _sanitize(name)
+    safe_description = _sanitize(description, max_len=2000)
+    safe_tech_stack = _sanitize(tech_stack)
+
+    system_prompt = (
+        "You are a project analyzer. "
+        "Respond ONLY with a JSON object. No markdown, no explanation."
+    )
+    project_data = json.dumps(
+        {
+            "name": safe_name,
+            "description": safe_description,
+            "tech_stack": safe_tech_stack,
+        },
+        ensure_ascii=False,
+    )
+    user_prompt = (
+        f"Project data (JSON):\n{project_data}\n\n"
+        "Return JSON with keys: language, package_manager, framework, "
+        "entry_point, project_type (library|cli|web-api|web-app|other)."
+    )
+
+    try:
+        raw = await call_oxlo_chat(
+            ANALYZER_MODEL,
+            system_prompt,
+            user_prompt,
+            max_tokens=512,
+            temperature=0.2,
+        )
+
+        cleaned = _extract_json(raw)
+        parsed = _parse_json(cleaned)
+        return ProjectMetadata(**parsed).model_dump()
+    except ValidationError:
+        return DEFAULT_METADATA.copy()
+    except Exception:
+        return DEFAULT_METADATA.copy()
diff --git a/services/python-tools/tools/auto-readme-generator/llm_client.py b/services/python-tools/tools/auto-readme-generator/llm_client.py
new file mode 100644
index 0000000..a5efa1d
--- /dev/null
+++ b/services/python-tools/tools/auto-readme-generator/llm_client.py
@@ -0,0 +1,59 @@
+import os
+
+import httpx
+
+OXLO_BASE_URL = os.getenv("OXLO_BASE_URL", "https://api.oxlo.ai/v1")
+OXLO_API_KEY = os.getenv("OXLO_API_KEY", "")
+_CLIENT: httpx.AsyncClient | None = None
+
+
+class OxloError(RuntimeError):
+    pass
+
+
+def _get_client() -> httpx.AsyncClient:
+    global _CLIENT
+    if _CLIENT is None:
+        _CLIENT = httpx.AsyncClient()
+    return _CLIENT
+
+
+async def call_oxlo_chat(
+    model: str,
+    system_prompt: str,
+    user_prompt: str,
+    max_tokens: int = 2048,
+    temperature: float = 0.3,
+) -> str:
+    if not OXLO_API_KEY:
+        raise OxloError("OXLO_API_KEY not configured")
+
+    payload = {
+        "model": model,
+        "messages": [
+            {"role": "system", "content": system_prompt},
+            {"role": "user", "content": user_prompt},
+        ],
+        "temperature": temperature,
+        "max_tokens": max_tokens,
+    }
+
+    client = _get_client()
+    resp = await client.post(
+        f"{OXLO_BASE_URL}/chat/completions",
+        headers={"Authorization": f"Bearer {OXLO_API_KEY}"},
+        json=payload,
+        timeout=30,
+    )
+    resp.raise_for_status()
+    data = resp.json()
+    choices = data.get("choices")
+    if not choices or not isinstance(choices, list):
+        raise OxloError(f"Unexpected API response: no choices returned. Response: {data}")
+
+    message = choices[0].get("message", {}) if isinstance(choices[0], dict) else {}
+    content = message.get("content")
+    if content is None:
+        raise OxloError(f"Unexpected API response: content is None. Message: {message}")
+
+    return content.strip()
diff --git a/services/python-tools/tools/auto-readme-generator/planner.py b/services/python-tools/tools/auto-readme-generator/planner.py
new file mode 100644
index 0000000..81fb5ff
--- /dev/null
+++ b/services/python-tools/tools/auto-readme-generator/planner.py
@@ -0,0 +1,59 @@
+SECTION_PLANS = {
+    "web-api": [
+        "Title",
+        "Badges",
+        "Description",
+        "Features",
+        "Quick Start",
+        "Usage",
+        "API Reference",
+        "Config",
+        "Contributing",
+        "License",
+    ],
+    "cli": [
+        "Title",
+        "Badges",
+        "Description",
+        "Features",
+        "Installation",
+        "Usage",
+        "Config",
+        "Contributing",
+        "License",
+    ],
+    "library": [
+        "Title",
+        "Badges",
+        "Description",
+        "Installation",
+        "Usage",
+        "API Reference",
+        "Contributing",
+        "License",
+    ],
+    "web-app": [
+        "Title",
+        "Badges",
+        "Description",
+        "Features",
+        "Quick Start",
+        "Usage",
+        "Config",
+        "Contributing",
+        "License",
+    ],
+    "other": [
+        "Title",
+        "Description",
+        "Installation",
+        "Usage",
+        "Contributing",
+        "License",
+    ],
+}
+
+
+def plan_sections(metadata: dict) -> list:
+    project_type = (metadata or {}).get("project_type", "other")
+    return SECTION_PLANS.get(project_type, SECTION_PLANS["other"])
diff --git a/services/python-tools/tools/auto-readme-generator/refiner.py b/services/python-tools/tools/auto-readme-generator/refiner.py
new file mode 100644
index 0000000..33831a1
--- /dev/null
+++ b/services/python-tools/tools/auto-readme-generator/refiner.py
@@ -0,0 +1,56 @@
+from typing import Awaitable, Callable, Optional
+
+from llm_client import call_oxlo_chat
+from validator import validate_readme
+
+REFINER_MODEL = "llama-3.3-70b"
+
+
+def _sanitize(value: str, max_len: int = 12000) -> str:
+    if not isinstance(value, str):
+        return ""
+    return value.strip()[:max_len]
+
+
+async def refine_readme(
+    content: str,
+    issues: list,
+    metadata: dict,
+    section_plan: list,
+    call_model: Optional[Callable[[str, str, str, int, float], Awaitable[str]]] = None,
+) -> str:
+    if not issues:
+        return content
+
+    call_model = call_model or call_oxlo_chat
+
+    for attempt in range(2):
+        issue_summary = "\n".join(
+            f"- [{item['type']}] {item['detail']}" for item in issues
+        )
+        safe_issue_summary = _sanitize(issue_summary, max_len=2000)
+        safe_content = _sanitize(content, max_len=20000)
+        system_prompt = (
+            "You are a technical writer. Fix the README to resolve the listed issues. "
+            "Return the full corrected README only."
+        )
+        user_prompt = (
+            f"Issues to fix:\n{safe_issue_summary}\n\n"
+            f"README:\n{safe_content}\n\n"
+            "Ensure all required sections are present, badges use https://img.shields.io/, "
+            "and code fences include a language tag."
+        )
+
+        content = await call_model(
+            REFINER_MODEL,
+            system_prompt,
+            user_prompt,
+            4096,
+            0.2,
+        )
+
+        issues = validate_readme(content, section_plan, metadata)
+        if not issues:
+            break
+
+    return content
diff --git a/services/python-tools/tools/auto-readme-generator/requirements-dev.txt b/services/python-tools/tools/auto-readme-generator/requirements-dev.txt
new file mode 100644
index 0000000..918f578
--- /dev/null
+++ b/services/python-tools/tools/auto-readme-generator/requirements-dev.txt
@@ -0,0 +1,2 @@
+pytest==8.3.2
+pytest-asyncio==0.23.8
diff --git a/services/python-tools/tools/auto-readme-generator/requirements.txt b/services/python-tools/tools/auto-readme-generator/requirements.txt
new file mode 100644
index 0000000..46333da
--- /dev/null
+++ b/services/python-tools/tools/auto-readme-generator/requirements.txt
@@ -0,0 +1,2 @@
+httpx==0.27.0
+pydantic==2.7.1
diff --git a/services/python-tools/tools/auto-readme-generator/tests/conftest.py b/services/python-tools/tools/auto-readme-generator/tests/conftest.py
new file mode 100644
index 0000000..62fa24b
--- /dev/null
+++ b/services/python-tools/tools/auto-readme-generator/tests/conftest.py
@@ -0,0 +1,6 @@
+import pathlib
+import sys
+
+TOOL_DIR = pathlib.Path(__file__).resolve().parents[1]
+if str(TOOL_DIR) not in sys.path:
+    sys.path.insert(0, str(TOOL_DIR))
diff --git a/services/python-tools/tools/auto-readme-generator/tests/pytest.ini b/services/python-tools/tools/auto-readme-generator/tests/pytest.ini
new file mode 100644
index 0000000..2f4c80e
--- /dev/null
+++ b/services/python-tools/tools/auto-readme-generator/tests/pytest.ini
@@ -0,0 +1,2 @@
+[pytest]
+asyncio_mode = auto
diff --git a/services/python-tools/tools/auto-readme-generator/tests/test_pipeline.py b/services/python-tools/tools/auto-readme-generator/tests/test_pipeline.py
new file mode 100644
index 0000000..de9a0f0
--- /dev/null
+++ b/services/python-tools/tools/auto-readme-generator/tests/test_pipeline.py
@@ -0,0 +1,148 @@
+import pytest
+
+import analyzer
+import refiner
+import tool
+import writer
+from validator import validate_readme
+
+
+async def _collect_stream(data: dict) -> str:
+    stream = await tool.run(data)
+    chunks = []
+    async for chunk in stream:
+        chunks.append(chunk)
+    return "".join(chunks)
+
+
+def _readme_web_api() -> str:
+    return (
+        "# Title\n"
+        "## Badges\n"
+        "![build](https://img.shields.io/badge/build-passing-green)\n"
+        "## Description\n"
+        "API service for auth.\n"
+        "## Features\n"
+        "- Login\n"
+        "## Quick Start\n"
+        "```bash\n"
+        "pip install example\n"
+        "```\n"
+        "## Usage\n"
+        "```bash\n"
+        "python -m example\n"
+        "```\n"
+        "## API Reference\n"
+        "See docs.\n"
+        "## Config\n"
+        "ENV vars.\n"
+        "## Contributing\n"
+        "PRs welcome.\n"
+        "## License\n"
+        "MIT\n"
+    )
+
+
+def _readme_other() -> str:
+    return (
+        "# Title\n"
+        "## Description\n"
+        "Simple tool.\n"
+        "## Installation\n"
+        "```bash\n"
+        "pip install example\n"
+        "```\n"
+        "## Usage\n"
+        "```bash\n"
+        "example --help\n"
+        "```\n"
+        "## Contributing\n"
+        "PRs welcome.\n"
+        "## License\n"
+        "MIT\n"
+    )
+
+
+@pytest.mark.asyncio
+async def test_pipeline_happy_path(monkeypatch):
+    async def fake_call_oxlo_chat(model, system_prompt, user_prompt, max_tokens=2048, temperature=0.3):
+        if "project analyzer" in system_prompt.lower():
+            return (
+                "{"
+                "\"language\": \"python\","
+                "\"package_manager\": \"pip\","
+                "\"framework\": \"fastapi\","
+                "\"entry_point\": \"main.py\","
+                "\"project_type\": \"web-api\""
+                "}"
+            )
+        return _readme_web_api()
+
+    monkeypatch.setattr(analyzer, "call_oxlo_chat", fake_call_oxlo_chat)
+    monkeypatch.setattr(writer, "call_oxlo_chat", fake_call_oxlo_chat)
+    monkeypatch.setattr(refiner, "call_oxlo_chat", fake_call_oxlo_chat)
+
+    output = await _collect_stream(
+        {
+            "projectName": "fastapi-auth",
+            "projectDescription": "Auth API with FastAPI",
+            "techStack": "Python, FastAPI",
+        }
+    )
+
+    assert "---RESULT---" in output
+    assert "[ERROR]" not in output
+
+
+@pytest.mark.asyncio
+async def test_pipeline_handles_malformed_analyzer_response(monkeypatch):
+    async def fake_call_oxlo_chat(model, system_prompt, user_prompt, max_tokens=2048, temperature=0.3):
+        if "project analyzer" in system_prompt.lower():
+            return "not json"
+        return _readme_other()
+
+    monkeypatch.setattr(analyzer, "call_oxlo_chat", fake_call_oxlo_chat)
+    monkeypatch.setattr(writer, "call_oxlo_chat", fake_call_oxlo_chat)
+    monkeypatch.setattr(refiner, "call_oxlo_chat", fake_call_oxlo_chat)
+
+    captured = {}
+
+    async def fake_write_readme(metadata, section_plan):
+        captured["metadata"] = metadata
+        return _readme_other()
+
+    monkeypatch.setattr(tool, "write_readme", fake_write_readme)
+
+    output = await _collect_stream(
+        {
+            "projectName": "unknown",
+            "projectDescription": "Test",
+            "techStack": "",
+        }
+    )
+
+    assert "---RESULT---" in output
+    assert "## Installation" in output
+    assert captured["metadata"] == analyzer.DEFAULT_METADATA
+
+
+@pytest.mark.asyncio
+async def test_refiner_max_retries_returns_content():
+    async def always_bad(model, system_prompt, user_prompt, max_tokens=2048, temperature=0.3):
+        return "# Title\n```python\nprint('hi')\n"
+
+    content = "# Title\n```python\nprint('hi')\n"
+    metadata = {"package_manager": "npm"}
+    section_plan = ["Title"]
+    issues = validate_readme(content, section_plan, metadata)
+
+    result = await refiner.refine_readme(
+        content,
+        issues,
+        metadata,
+        section_plan,
+        call_model=always_bad,
+    )
+
+    assert result
+    assert validate_readme(result, section_plan, metadata)
diff --git a/services/python-tools/tools/auto-readme-generator/tests/test_planner.py b/services/python-tools/tools/auto-readme-generator/tests/test_planner.py
new file mode 100644
index 0000000..203e4c9
--- /dev/null
+++ b/services/python-tools/tools/auto-readme-generator/tests/test_planner.py
@@ -0,0 +1,16 @@
+from planner import plan_sections
+
+
+def test_web_api_has_api_reference():
+    plan = plan_sections({"project_type": "web-api"})
+    assert "API Reference" in plan
+
+
+def test_cli_has_installation():
+    plan = plan_sections({"project_type": "cli"})
+    assert "Installation" in plan
+
+
+def test_unknown_type_falls_back_to_other():
+    plan = plan_sections({"project_type": "xyz"})
+    assert "Usage" in plan
diff --git a/services/python-tools/tools/auto-readme-generator/tests/test_refiner.py b/services/python-tools/tools/auto-readme-generator/tests/test_refiner.py
new file mode 100644
index 0000000..a6a4a77
--- /dev/null
+++ b/services/python-tools/tools/auto-readme-generator/tests/test_refiner.py
@@ -0,0 +1,32 @@
+import pytest
+
+from refiner import refine_readme
+from validator import validate_readme
+
+
+async def _fake_call_model(model, system, user, max_tokens, temperature):
+    return (
+        "# Title\n"
+        "![build](https://img.shields.io/badge/build-passing-green)\n"
+        "# License\n"
+        "```python\nprint('hi')\n```\n"
+        "npm install\n"
+    )
+
+
+@pytest.mark.asyncio
+async def test_refiner_resolves_issues():
+    content = "# Title\n# License\n```\nraw code\n```\n"
+    metadata = {"package_manager": "npm"}
+    section_plan = ["Title", "License"]
+    issues = validate_readme(content, section_plan, metadata)
+
+    result = await refine_readme(
+        content,
+        issues,
+        metadata,
+        section_plan,
+        call_model=_fake_call_model,
+    )
+
+    assert validate_readme(result, section_plan, metadata) == []
diff --git a/services/python-tools/tools/auto-readme-generator/tests/test_validator.py b/services/python-tools/tools/auto-readme-generator/tests/test_validator.py
new file mode 100644
index 0000000..2907ac9
--- /dev/null
+++ b/services/python-tools/tools/auto-readme-generator/tests/test_validator.py
@@ -0,0 +1,35 @@
+from validator import validate_readme
+
+
+def test_detects_missing_section():
+    issues = validate_readme("# Title\n# Usage\n", ["Title", "Usage", "License"])
+    assert any(item["type"] == "missing_section" for item in issues)
+
+
+def test_detects_bad_badge():
+    content = "![b](http://shields.io/badge/foo-bar)\n# Title\n# License\n"
+    issues = validate_readme(content, ["Title", "License"])
+    assert any(item["type"] == "bad_badge" for item in issues)
+
+
+def test_detects_fence_without_language():
+    content = "# Title\n# License\n```\nsome code\n```\n"
+    issues = validate_readme(content, ["Title", "License"])
+    assert any(item["type"] == "no_lang_fence" for item in issues)
+
+
+def test_detects_missing_install_command_for_npm():
+    content = "# Title\n# Installation\n# Usage\n"
+    issues = validate_readme(content, ["Title", "Installation", "Usage"], {"package_manager": "npm"})
+    assert any(item["type"] == "install_command_mismatch" for item in issues)
+
+
+def test_passes_valid_readme():
+    content = (
+        "# Title\n"
+        "![build](https://img.shields.io/badge/build-passing-green)\n"
+        "# License\n"
+        "```python\nprint('hi')\n```\n"
+        "npm install\n"
+    )
+    assert validate_readme(content, ["Title", "License"], {"package_manager": "npm"}) == []
diff --git a/services/python-tools/tools/auto-readme-generator/tool.py b/services/python-tools/tools/auto-readme-generator/tool.py
new file mode 100644
index 0000000..0b59594
--- /dev/null
+++ b/services/python-tools/tools/auto-readme-generator/tool.py
@@ -0,0 +1,87 @@
+"""
+Auto README Generator — Tool Entry Point
+=========================================
+Multi-agent pipeline: analyze, plan, write, validate, refine.
+"""
+
+from analyzer import analyze_project
+from planner import plan_sections
+from writer import write_readme
+from validator import validate_readme
+from refiner import refine_readme
+
+
+MANIFEST = {
+    "id": "auto-readme-generator",
+    "name": "Auto README Generator",
+    "description": "Multi-agent pipeline that generates structured, validated READMEs.",
+    "author": "Franco Ayala",
+    "version": "1.0.0",
+}
+
+
+async def run(data: dict):
+    project_name = data.get("projectName", "Unnamed Project")
+    description = data.get("projectDescription", "")
+    tech_stack = data.get("techStack", "")
+
+    async def stream():
+        if not description.strip():
+            yield "[ERROR] Project description is required.\n"
+            return
+
+        yield "[1/5] Analyzing project metadata...\n"
+        try:
+            metadata = await analyze_project(project_name, description, tech_stack)
+        except Exception as exc:
+            yield f"[ERROR] Analyzer failed: {exc}\n"
+            return
+
+        yield "[2/5] Planning required sections...\n"
+        try:
+            section_plan = plan_sections(metadata)
+        except Exception as exc:
+            yield f"[ERROR] Planner failed: {exc}\n"
+            return
+
+        yield "[3/5] Writing README...\n"
+        try:
+            readme_content = await write_readme(metadata, section_plan)
+        except Exception as exc:
+            yield f"[ERROR] Writer failed: {exc}\n"
+            return
+
+        yield "[4/5] Validating sections and badges...\n"
+        try:
+            issues = validate_readme(readme_content, section_plan, metadata)
+        except Exception as exc:
+            yield f"[WARN] Validator failed, returning unvalidated result: {exc}\n"
+            issues = []
+
+        if issues:
+            yield f"[5/5] Found {len(issues)} issue(s), refining...\n"
+            try:
+                readme_content = await refine_readme(
+                    readme_content,
+                    issues,
+                    metadata,
+                    section_plan,
+                )
+            except Exception as exc:
+                yield f"[WARN] Refiner failed, returning best effort: {exc}\n"
+
+            try:
+                issues = validate_readme(readme_content, section_plan, metadata)
+            except Exception as exc:
+                yield f"[WARN] Post-refine validation failed: {exc}\n"
+                issues = []
+        else:
+            yield "[5/5] Validation passed.\n"
+
+        if issues:
+            yield f"[WARN] Validation still has {len(issues)} issue(s).\n"
+
+        yield "\n---RESULT---\n"
+        yield readme_content
+
+    return stream()
diff --git a/services/python-tools/tools/auto-readme-generator/validator.py b/services/python-tools/tools/auto-readme-generator/validator.py
new file mode 100644
index 0000000..4b3bd7c
--- /dev/null
+++ b/services/python-tools/tools/auto-readme-generator/validator.py
@@ -0,0 +1,111 @@
+import re
+from typing import Optional
+
+SHIELD_URL_PATTERN = re.compile(r"https?://[^\s\)\]]+")
+VALID_SHIELD_PREFIX = "https://img.shields.io/"
+FENCE_OPEN = re.compile(r"^`{3}(\w*)(?:\s.*)?$")
+
+INSTALL_COMMANDS = {
+    "npm": ["npm install", "npm ci"],
+    "yarn": ["yarn install", "yarn add"],
+    "pnpm": ["pnpm install", "pnpm add"],
+    "pip": ["pip install"],
+    "pipenv": ["pipenv install"],
+    "poetry": ["poetry install"],
+}
+
+
+def _has_section(content: str, section: str) -> bool:
+    pattern = re.compile(
+        rf"^#{{1,6}}\s+{re.escape(section)}\s*#*\s*$",
+        re.IGNORECASE | re.MULTILINE,
+    )
+    return bool(pattern.search(content))
+
+
+def _find_fence_issues(content: str) -> list:
+    issues = []
+    in_block = False
+
+    for line in content.splitlines():
+        match = FENCE_OPEN.match(line.strip())
+        if match is None:
+            continue
+
+        fence_lang = match.group(1)
+        if not in_block:
+            if not fence_lang:
+                issues.append({"type": "no_lang_fence", "detail": "code block missing language"})
+            in_block = True
+        else:
+            in_block = False
+
+    if in_block:
+        issues.append({"type": "unclosed_fence", "detail": "code block not closed"})
+
+    return issues
+
+
+def _extract_code_blocks(content: str) -> list:
+    blocks = []
+    in_block = False
+    current = []
+
+    for line in content.splitlines():
+        match = FENCE_OPEN.match(line.strip())
+        if match is not None:
+            if in_block:
+                blocks.append("\n".join(current))
+                current = []
+                in_block = False
+            else:
+                in_block = True
+            continue
+
+        if in_block:
+            current.append(line)
+
+    return blocks
+
+
+def _has_install_command(content: str, package_manager: str) -> bool:
+    options = INSTALL_COMMANDS.get(package_manager.lower(), [])
+    if not options:
+        return False
+
+    code_blocks = _extract_code_blocks(content)
+    for block in code_blocks:
+        if any(cmd in block for cmd in options):
+            return True
+
+    for cmd in options:
+        pattern = re.compile(rf"(?m)^[\t >`]*{re.escape(cmd)}\b")
+        if pattern.search(content):
+            return True
+
+    return False
+
+
+def validate_readme(content: str, section_plan: list, metadata: Optional[dict] = None) -> list:
+    issues = []
+
+    for section in section_plan:
+        if not _has_section(content, section):
+            issues.append({"type": "missing_section", "detail": section})
+
+    for url in SHIELD_URL_PATTERN.findall(content):
+        if "shields.io" in url and not url.startswith(VALID_SHIELD_PREFIX):
+            issues.append({"type": "bad_badge", "detail": url})
+
+    issues.extend(_find_fence_issues(content))
+
+    if metadata:
+        package_manager = metadata.get("package_manager", "").lower()
+        if package_manager and package_manager in INSTALL_COMMANDS:
+            if not _has_install_command(content, package_manager):
+                issues.append({
+                    "type": "install_command_mismatch",
+                    "detail": f"missing install command for {package_manager}",
+                })
+
+    return issues
diff --git a/services/python-tools/tools/auto-readme-generator/writer.py b/services/python-tools/tools/auto-readme-generator/writer.py
new file mode 100644
index 0000000..c636d46
--- /dev/null
+++ b/services/python-tools/tools/auto-readme-generator/writer.py
@@ -0,0 +1,87 @@
+import json
+
+from llm_client import call_oxlo_chat
+
+WRITER_MODEL = "llama-3.3-70b"
+
+ALLOWED_SECTIONS = {
+    "Title",
+    "Badges",
+    "Description",
+    "Features",
+    "Quick Start",
+    "Usage",
+    "API Reference",
+    "Config",
+    "Contributing",
+    "License",
+    "Installation",
+}
+
+DEFAULT_SECTIONS = ["Title", "Description", "Installation", "Usage", "License"]
+
+
+def _sanitize(value: str, max_len: int = 500) -> str:
+    if not isinstance(value, str):
+        return ""
+    return value.strip()[:max_len]
+
+
+def _sanitize_section_plan(section_plan: list) -> list:
+    if not isinstance(section_plan, list) or not section_plan:
+        return []
+    cleaned = []
+    seen = set()
+    for section in section_plan:
+        if not isinstance(section, str):
+            continue
+        section = section.strip()
+        if section in ALLOWED_SECTIONS and section not in seen:
+            cleaned.append(section)
+            seen.add(section)
+    return cleaned
+
+
+async def write_readme(metadata: dict, section_plan: list) -> str:
+    section_plan = _sanitize_section_plan(section_plan)
+    if not section_plan:
+        section_plan = DEFAULT_SECTIONS
+    package_manager = _sanitize((metadata or {}).get("package_manager", "unknown"))
+    language = _sanitize((metadata or {}).get("language", "unknown"))
+    framework = _sanitize((metadata or {}).get("framework", "unknown"))
+    entry_point = _sanitize((metadata or {}).get("entry_point", "unknown"))
+
+    metadata_block = json.dumps(
+        {
+            "package_manager": package_manager,
+            "language": language,
+            "framework": framework,
+            "entry_point": entry_point,
+        },
+        ensure_ascii=False,
+    )
+
+    system_prompt = (
+        "You are a technical writer. Generate a complete README.md in markdown.\n"
+        "Include ALL of these sections in order: "
+        + ", ".join(section_plan)
+        + ".\n"
+        f"<project_metadata>{metadata_block}</project_metadata>\n"
+        "Use the metadata above to pick correct install commands and examples. "
+        "All shields.io badge URLs must start with https://img.shields.io/. "
+        "All code blocks must have a language identifier (```python, ```bash, etc.). "
+        "Return only the README markdown."
+    )
+
+    user_prompt = (
+        "Write the README now. Use the metadata above to pick correct install "
+        "commands and examples. Ensure sections are present and properly titled."
+    )
+
+    return await call_oxlo_chat(
+        WRITER_MODEL,
+        system_prompt,
+        user_prompt,
+        max_tokens=4096,
+        temperature=0.3,
+    )
diff --git a/services/python-tools/tools/pdf-summarizer/extractor.py b/services/python-tools/tools/pdf-summarizer/extractor.py
new file mode 100644
index 0000000..e592d98
--- /dev/null
+++ b/services/python-tools/tools/pdf-summarizer/extractor.py
@@ -0,0 +1,72 @@
+import re
+from typing import List
+
+PATTERNS = {
+    "monetary": r"[\$€£¥]\s?\d[\d,]*(?:\.\d+)?(?:\s?[KMBkmb](?:illion)?)?",
+    "date": r"\b(?:\d{1,2}[/-]\d{1,2}[/-]\d{2,4}|\d{4}-\d{2}-\d{2}|(?:Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Sept|Oct|Nov|Dec)[a-z]*\s+\d{1,2},\s+\d{4})\b",
+    "percentage": r"\b\d+(?:\.\d+)?%\b",
+    "email": r"[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}",
+    "url": r"\bhttps?://[^\s)]+",
+    "large_number": r"\b\d{1,3}(?:,\d{3})+(?:\.\d+)?\b",
+}
+
+CONTEXT_WINDOW = 80
+
+
+def extract_entities(text: str) -> List[dict]:
+    results: List[dict] = []
+    seen = set()
+
+    for entity_type, pattern in PATTERNS.items():
+        for match in re.finditer(pattern, text, flags=re.IGNORECASE):
+            value = match.group(0).strip()
+            key = (entity_type, value, match.start())
+            if key in seen:
+                continue
+            seen.add(key)
+            context = _get_context(text, match.start(), match.end())
+            results.append(
+                {"type": entity_type, "value": value, "context": context}
+            )
+
+    try:
+        import spacy
+
+        try:
+            nlp = spacy.load("en_core_web_sm")
+        except Exception:
+            nlp = None
+
+        if nlp:
+            doc = nlp(text)
+            for ent in doc.ents:
+                if ent.label_ not in {
+                    "PERSON",
+                    "ORG",
+                    "GPE",
+                    "PRODUCT",
+                    "EVENT",
+                    "WORK_OF_ART",
+                }:
+                    continue
+                value = ent.text.strip()
+                key = ("proper_noun", value, ent.start_char)
+                if key in seen:
+                    continue
+                seen.add(key)
+                context = _get_context(text, ent.start_char, ent.end_char)
+                results.append(
+                    {"type": "proper_noun", "value": value, "context": context}
+                )
+    except Exception:
+        pass
+
+    return results
+
+
+def _get_context(text: str, start: int, end: int) -> str:
+    left = max(0, start - CONTEXT_WINDOW)
+    right = min(len(text), end + CONTEXT_WINDOW)
+    context = text[left:right]
+    context = re.sub(r"\s+", " ", context)
+    return context.strip()
diff --git a/services/python-tools/tools/pdf-summarizer/preprocessor.py b/services/python-tools/tools/pdf-summarizer/preprocessor.py
new file mode 100644
index 0000000..f397224
--- /dev/null
+++ b/services/python-tools/tools/pdf-summarizer/preprocessor.py
@@ -0,0 +1,167 @@
+import re
+from typing import Tuple
+
+CHUNK_MAX_CHARS = 12_000  # about 3,000 tokens
+
+
+def preprocess(text: str) -> Tuple[list, dict]:
+    normalized = text.replace("\r\n", "\n").replace("\r", "\n")
+    normalized = _strip_repeated_headers_footers(normalized)
+    cleaned = _clean(normalized)
+    structure = _detect_structure(cleaned)
+    chunks = _chunk(cleaned)
+    return chunks, structure
+
+
+def _clean(text: str) -> str:
+    text = text.replace("\f", "\n")
+    text = re.sub(r"[ \t]+", " ", text)
+    text = re.sub(r"\n{3,}", "\n\n", text)
+    return text.strip()
+
+
+def _strip_repeated_headers_footers(text: str) -> str:
+    pages = text.split("\f")
+    if len(pages) <= 1:
+        lines = [line for line in text.splitlines() if not _is_page_number_line(line)]
+        return "\n".join(lines)
+
+    header_counts: dict[str, int] = {}
+    footer_counts: dict[str, int] = {}
+    page_lines: list[list[str]] = []
+
+    for page in pages:
+        lines = [line for line in page.splitlines() if line.strip()]
+        header_lines = lines[:2]
+        footer_lines = lines[-2:] if len(lines) >= 2 else lines
+
+        for line in header_lines:
+            header_counts[line] = header_counts.get(line, 0) + 1
+        for line in footer_lines:
+            footer_counts[line] = footer_counts.get(line, 0) + 1
+
+        page_lines.append(page.splitlines())
+
+    header_repeats = {
+        line for line, count in header_counts.items() if count >= 2 and len(line) <= 80
+    }
+    footer_repeats = {
+        line for line, count in footer_counts.items() if count >= 2 and len(line) <= 80
+    }
+
+    cleaned_pages = []
+    for lines in page_lines:
+        cleaned_page_lines = []
+        for line in lines:
+            if _is_page_number_line(line):
+                continue
+            if line in header_repeats or line in footer_repeats:
+                continue
+            cleaned_page_lines.append(line)
+        cleaned_pages.append("\n".join(cleaned_page_lines))
+
+    return "\n\n".join(cleaned_pages)
+
+
+def _is_page_number_line(line: str) -> bool:
+    stripped = line.strip()
+    if not stripped:
+        return False
+    return bool(
+        re.match(r"^(page\s*)?\d+(\s*(/|of)\s*\d+)?$", stripped, re.IGNORECASE)
+    )
+
+
+def _detect_structure(text: str) -> dict:
+    lines = text.splitlines()
+    headings = []
+    numbered_sections = []
+    bullets = []
+    tables = []
+
+    for index, raw in enumerate(lines):
+        line = raw.strip()
+        if not line:
+            continue
+        if _is_heading(line):
+            headings.append({"line": line, "index": index})
+        if re.match(r"^\d+(\.\d+)*\s+.+", line):
+            numbered_sections.append({"line": line, "index": index})
+        if re.match(r"^(\*|-|\d+\)|\d+\.)\s+.+", line):
+            bullets.append({"line": line, "index": index})
+        if _looks_like_table_row(line):
+            tables.append({"line": line, "index": index})
+
+    return {
+        "headings": headings,
+        "numbered_sections": numbered_sections,
+        "bullets": bullets,
+        "tables": tables,
+        "counts": {
+            "headings": len(headings),
+            "numbered_sections": len(numbered_sections),
+            "bullets": len(bullets),
+            "tables": len(tables),
+        },
+    }
+
+
+def _is_heading(line: str) -> bool:
+    if line.endswith(":"):
+        return True
+    letters = re.sub(r"[^A-Za-z]", "", line)
+    if letters and line == line.upper() and len(line) <= 120:
+        return True
+    return False
+
+
+def _looks_like_table_row(line: str) -> bool:
+    if "|" in line:
+        return True
+    return bool(re.search(r"\S+\s{2,}\S+", line))
+
+
+def _chunk(text: str) -> list:
+    if len(text) <= CHUNK_MAX_CHARS:
+        return [text]
+
+    paragraphs = re.split(r"\n{2,}", text)
+    chunks: list[str] = []
+    current = ""
+
+    def flush() -> None:
+        nonlocal current
+        if current.strip():
+            chunks.append(current.strip())
+        current = ""
+
+    for para in paragraphs:
+        if not para.strip():
+            continue
+
+        if len(para) > CHUNK_MAX_CHARS:
+            sentences = re.split(r"(?<=[.!?])\s+", para)
+            for sentence in sentences:
+                if not sentence:
+                    continue
+                if len(sentence) > CHUNK_MAX_CHARS:
+                    for i in range(0, len(sentence), CHUNK_MAX_CHARS):
+                        piece = sentence[i : i + CHUNK_MAX_CHARS]
+                        if current and len(current) + len(piece) + 2 > CHUNK_MAX_CHARS:
+                            flush()
+                        if current:
+                            current += " " + piece
+                        else:
+                            current = piece
+                else:
+                    if current and len(current) + len(sentence) + 1 > CHUNK_MAX_CHARS:
+                        flush()
+                    current = sentence if not current else current + " " + sentence
+            continue
+
+        if current and len(current) + len(para) + 2 > CHUNK_MAX_CHARS:
+            flush()
+        current = para if not current else current + "\n\n" + para
+
+    flush()
+    return chunks
diff --git a/services/python-tools/tools/pdf-summarizer/requirements.txt b/services/python-tools/tools/pdf-summarizer/requirements.txt
new file mode 100644
index 0000000..9091857
--- /dev/null
+++ b/services/python-tools/tools/pdf-summarizer/requirements.txt
@@ -0,0 +1,2 @@
+openai>=1.30.0
+spacy>=3.7.0
\ No newline at end of file
diff --git a/services/python-tools/tools/pdf-summarizer/summarizer.py b/services/python-tools/tools/pdf-summarizer/summarizer.py
new file mode 100644
index 0000000..84cf6ff
--- /dev/null
+++ b/services/python-tools/tools/pdf-summarizer/summarizer.py
@@ -0,0 +1,43 @@
+import asyncio
+import os
+import re
+from typing import Optional
+
+from openai import AsyncOpenAI
+
+OXLO_BASE_URL = os.getenv("OXLO_BASE_URL", "https://api.oxlo.ai/v1")
+OXLO_API_KEY = os.getenv("OXLO_API_KEY", "")
+SUMMARIZER_MODEL = os.getenv("PDF_SUMMARIZER_MODEL", "deepseek-v3.2")
+
+client = AsyncOpenAI(api_key=OXLO_API_KEY, base_url=OXLO_BASE_URL)
+
+SYSTEM_PROMPT = (
+    "You are a precise document analyst. Summarize the provided section "
+    "with clear, factual points. Include key numbers, dates, amounts, percentages, "
+    "action items, and notable direct quotes mentioned in the text. "
+    "Focus on facts; do not add interpretation."
+)
+
+
+async def _summarize_one(chunk: str, index: int, focus: Optional[str] = None) -> str:
+    focus_line = f"\nFocus area: {focus}\n" if focus else ""
+    user_prompt = f"Section {index + 1}:\n{focus_line}{chunk}"
+
+    response = await client.chat.completions.create(
+        model=SUMMARIZER_MODEL,
+        messages=[
+            {"role": "system", "content": SYSTEM_PROMPT},
+            {"role": "user", "content": user_prompt},
+        ],
+        temperature=0.2,
+        max_tokens=600,
+    )
+
+    raw = response.choices[0].message.content or ""
+    cleaned = re.sub(r"<think>[\s\S]*?</think>", "", raw, flags=re.IGNORECASE).strip()
+    return cleaned
+
+
+async def summarize_chunks(chunks: list, focus: str = "") -> list:
+    tasks = [_summarize_one(chunk, index, focus) for index, chunk in enumerate(chunks)]
+    return await asyncio.gather(*tasks)
diff --git a/services/python-tools/tools/pdf-summarizer/synthesis.py b/services/python-tools/tools/pdf-summarizer/synthesis.py
new file mode 100644
index 0000000..0bfa351
--- /dev/null
+++ b/services/python-tools/tools/pdf-summarizer/synthesis.py
@@ -0,0 +1,161 @@
+import os
+import re
+
+from openai import AsyncOpenAI
+
+OXLO_BASE_URL = os.getenv("OXLO_BASE_URL", "https://api.oxlo.ai/v1")
+OXLO_API_KEY = os.getenv("OXLO_API_KEY", "")
+SYNTHESIS_MODEL = "deepseek-r1-0528"
+FALLBACK_MODEL = "kimi-k2.6"
+
+client = AsyncOpenAI(api_key=OXLO_API_KEY, base_url=OXLO_BASE_URL)
+
+REQUIRED_HEADERS = (
+    "## Executive Summary",
+    "## Key Findings",
+    "## Data & Numbers",
+    "## Action Items",
+    "## Notable Quotes",
+    "## Risk Factors",
+)
+
+SYSTEM_PROMPT = """\
+You are an executive assistant and expert document analyst. Summarize the provided document into a structured report.
+Given section summaries and extracted data points, output the following sections IN THIS EXACT ORDER using markdown headers:
+
+## Executive Summary
+(2-3 sentence overview)
+
+## Key Findings
+(bulleted list of the most important points)
+
+## Data & Numbers
+(extract all specific numbers, dates, amounts, percentages; use a markdown table when helpful)
+
+## Action Items
+(any tasks, deadlines, or next steps mentioned; if none are present, write "None identified.")
+
+## Notable Quotes
+(direct quotes worth highlighting; if none are present, write "None identified.")
+
+## Risk Factors
+(any concerns or warnings mentioned; if none are present, write "None identified.")
+
+Rules:
+- Never hallucinate figures. Use only data from the provided summaries and entities.
+- Preserve exact numbers, dates, and amounts.
+- Be concise but comprehensive. Use markdown formatting.
+- Start your response DIRECTLY with "## Executive Summary" - no preamble, no intro sentence.
+- Do NOT include any reasoning, chain-of-thought, or <think> blocks. Output only the final report.
+- Think briefly. Your <think> block must not exceed 300 words. Go directly to the report.
+"""
+
+
+def _build_entity_block(entities: list) -> str:
+    header = "| Type | Value | Context |"
+    divider = "| --- | --- | --- |"
+    if not entities:
+        return "\n".join([header, divider, "| None | None | None |"])
+
+    lines = [header, divider]
+    for entity in entities:
+        value = str(entity.get("value", "")).replace("|", "\\|")
+        context = str(entity.get("context", "")).replace("|", "\\|")
+        entity_type = str(entity.get("type", "")).replace("|", "\\|")
+        lines.append(f"| {entity_type} | {value} | {context} |")
+    return "\n".join(lines)
+
+
+def _format_structure(structure: dict) -> str:
+    if not structure:
+        return "None"
+
+    headings = [item.get("line", "") for item in structure.get("headings", [])][:12]
+    numbered = [
+        item.get("line", "") for item in structure.get("numbered_sections", [])
+    ][:12]
+    counts = structure.get("counts", {})
+
+    parts = []
+    if headings:
+        parts.append("Headings: " + "; ".join(headings))
+    if numbered:
+        parts.append("Numbered sections: " + "; ".join(numbered))
+
+    parts.append(f"Bullet lines: {counts.get('bullets', 0)}")
+    parts.append(f"Table-like lines: {counts.get('tables', 0)}")
+
+    return "\n".join(parts) if parts else "None"
+
+
+def _pick_model(summaries_text: str, entity_block: str) -> str:
+    combined_length = len(summaries_text) + len(entity_block)
+    if combined_length > 60_000:
+        return FALLBACK_MODEL
+    return SYNTHESIS_MODEL
+
+
+def _strip_think(raw: str) -> str:
+    """
+    Remove model reasoning blocks from the final response.
+    Handles both well-formed and malformed <think> content.
+    """
+    cleaned = re.sub(r"<think>[\s\S]*?</think>", "", raw, flags=re.IGNORECASE).strip()
+
+    if "<think>" in cleaned.lower():
+        match = re.search(r"(^|\n)(##\s)", cleaned)
+        if match:
+            cleaned = cleaned[match.start():].strip()
+        else:
+            cleaned = re.sub(r"<think>[\s\S]*", "", cleaned, flags=re.IGNORECASE).strip()
+
+    return cleaned
+
+
+def _section_score(text: str) -> int:
+    return sum(1 for header in REQUIRED_HEADERS if header in text)
+
+
+async def _create_completion(model: str, user_content: str) -> str:
+    response = await client.chat.completions.create(
+        model=model,
+        messages=[
+            {"role": "system", "content": SYSTEM_PROMPT},
+            {"role": "user", "content": user_content},
+        ],
+        temperature=0.2,
+        max_tokens=8192,
+    )
+
+    raw = response.choices[0].message.content or ""
+    return _strip_think(raw)
+
+
+async def synthesize(chunk_summaries: list, entities: list, structure: dict) -> str:
+    summaries_text = "\n\n".join(
+        f"### Section {index + 1}\n{summary}"
+        for index, summary in enumerate(chunk_summaries)
+    )
+    entity_block = _build_entity_block(entities)
+    structure_hint = _format_structure(structure)
+
+    user_content = (
+        "SECTION SUMMARIES:\n"
+        f"{summaries_text}\n\n"
+        "STRUCTURE HINTS:\n"
+        f"{structure_hint}\n\n"
+        "EXTRACTED ENTITIES (Type | Value | Context):\n"
+        f"{entity_block}\n"
+    )
+
+    model = _pick_model(summaries_text, entity_block)
+    report = await _create_completion(model, user_content)
+    if _section_score(report) < len(REQUIRED_HEADERS):
+        fallback_report = await _create_completion(FALLBACK_MODEL, user_content)
+        if _section_score(fallback_report) > _section_score(report) or (
+            _section_score(fallback_report) == _section_score(report)
+            and len(fallback_report) > len(report)
+        ):
+            report = fallback_report
+
+    return report
diff --git a/services/python-tools/tools/pdf-summarizer/tool.py b/services/python-tools/tools/pdf-summarizer/tool.py
new file mode 100644
index 0000000..500b36d
--- /dev/null
+++ b/services/python-tools/tools/pdf-summarizer/tool.py
@@ -0,0 +1,66 @@
+"""
+PDF Summarizer - Tool Entry Point
+"""
+
+import os
+
+from extractor import extract_entities
+from preprocessor import preprocess
+from summarizer import summarize_chunks
+from synthesis import synthesize
+
+
+MANIFEST = {
+    "id": "pdf-summarizer",
+    "name": "PDF / Document Summarizer",
+    "description": "Summarize long documents into a structured executive report",
+    "author": "Franci-343",
+    "version": "1.0.0",
+    "requires": ["openai"],
+}
+
+
+async def run(data: dict):
+    """
+    Execute the PDF summarization pipeline with streaming updates.
+    """
+    if not os.getenv("OXLO_API_KEY"):
+        return {"error": "OXLO_API_KEY not configured. Set it in .env"}
+
+    document_text = (
+        data.get("documentText")
+        or data.get("document_text")
+        or data.get("text")
+        or data.get("document")
+        or ""
+    )
+    if not str(document_text).strip():
+        return {"error": "Document text is required."}
+
+    focus = str(data.get("focus", "")).strip()
+
+    async def stream():
+        yield "[preprocess] Cleaning and chunking document...\n"
+        chunks, structure = preprocess(str(document_text))
+        if not chunks:
+            yield "[error] No usable content after preprocessing.\n"
+            return
+
+        yield f"[preprocess] Prepared {len(chunks)} chunks\n"
+
+        yield "[entities] Extracting entities...\n"
+        clean_text = "\n\n".join(chunks)
+        import asyncio
+        entities = await asyncio.to_thread(extract_entities, clean_text)
+        yield f"[entities] Extracted {len(entities)} entities\n"
+
+        yield "[summarize] Summarizing sections...\n"
+        chunk_summaries = await summarize_chunks(chunks, focus=focus)
+        yield f"[summarize] Completed {len(chunk_summaries)} sections\n"
+
+        yield "[synthesis] Building final report...\n"
+        final_output = await synthesize(chunk_summaries, entities, structure)
+        yield "\n---REPORT_START---\n"
+        yield final_output
+
+    return stream()