DocSort CLI

DocSort CLI is an AI-powered command-line application that automates the classification, summarization, and interactive organization of PDF document collections.

Operating 100% locally and offline, DocSort extracts PDF text and metadata or falls back to Page 1 PNG rendering for scanned documents. It analyzes content using a local Multimodal Vision-Language AI model (qwen2.5vl:3b via Ollama) and presents an interactive terminal card UI for file decisions.

---

Key Features

• Dual Extraction Pipeline: Uses pdfjs-dist for standard text PDFs and automatically falls back to pdf-to-img Vision AI rendering for scanned documents.
• Scanner Watermark Filtering: Automatically filters out common scanner watermarks (such as CamScanner, Adobe Scan, Genius Scan) to ensure scanned PDFs are routed to Vision AI analysis.
• 100% Local & Private AI: Runs locally via Ollama using qwen2.5vl:3b with structured JSON mode (format: "json"). No cloud API keys or external data transmission required.
• Fast Preview Mode: Supports a -f / --fast flag to immediately inspect raw text snippets without waiting for AI model inference.
• Interactive Terminal UI: Renders formatted ASCII summary cards (cli-table3, chalk) with one-key decision prompts (inquirer).
• Safe Soft-Deletion Staging: Relocates files selected for deletion into a local .docsort-trash/ folder rather than permanently deleting them.
• VRAM & Token Efficiency: Optimized rendering scale (1.25x) and explicit context window limits (4096 tokens) tailored for mid-range GPUs (4 GB VRAM+).

---

Prerequisites

Before installing DocSort CLI, ensure you have the following installed on your system:

1. Node.js: Version 20.0.0 or higher (node -v)
2. Ollama: Local AI runner installed and accessible in your PATH (ollama --version)
3. Vision Model: Download the default multimodal vision model:

   ollama pull qwen2.5vl:3b

Make sure the local Ollama service is running before executing AI scans:

ollama serve

---

Installation & Setup

1. Clone Repository

git clone https://github.com/KunalSambyal/DocSort-CLI.git
cd DocSort-CLI

2. Install Dependencies

npm install

3. Build Project Binaries

Compile TypeScript sources to the dist/ distribution folder:

npm run build

4. Link CLI Globally

Link the package locally so docsort is available in your shell terminal:

npm link

Verify installation:

docsort --version

---

Usage Guide

Scan & Organize a Directory

To start an interactive AI analysis session on a target folder containing PDFs:

docsort scan /path/to/pdf/folder

Fast Raw Text Preview Mode

To quickly preview extracted raw text without invoking local AI inference:

docsort scan /path/to/pdf/folder --fast

Specify Custom Ollama Model

To run scanning with an alternative installed Ollama model:

docsort scan /path/to/pdf/folder --model qwen2.5vl:3b

---

Project Structure

DocSortCLI/
├── src/
│   ├── commands/               # CLI Commander action definitions
│   │   └── scan.command.ts     # Main scanning pipeline controller
│   ├── config/                 # Application constants & JSON schema
│   │   └── constants.ts
│   ├── services/               # Modular business logic services
│   │   ├── ai.service.ts       # Ollama API interaction & JSON parsing
│   │   ├── file.service.ts     # Move, rename, and soft-trash operations
│   │   ├── image.service.ts    # Page 1 PNG rendering fallback (pdf-to-img)
│   │   ├── pdf.service.ts      # PDF text & metadata extraction (pdfjs-dist)
│   │   └── pipeline.service.ts # Extraction & AI workflow orchestrator
│   ├── types/                  # Shared TypeScript interfaces
│   │   └── docsort.types.ts
│   ├── ui/                     # Terminal UI presentation logic
│   │   ├── card.ui.ts          # ASCII document card renderer
│   │   ├── menu.ui.ts          # Interactive key choice prompts
│   │   └── report.ui.ts        # End-of-session summary renderer
│   └── index.ts                # Application entry point
├── DocSort_Architecture_Guide.md
├── DocSort_Project_Plan.md
├── DocSort_SDD.md
├── package.json
└── tsconfig.json

---

Author

Kunal Sambyal