Content
# 📘 Local-Portable-AI User Guide
This program is a **portable, self-contained AI assistant** that supports local internal business and administrative document (HWP, HWPX, PDF, XLSX, DOCX) analysis with AI-based automation. It runs immediately on your computer without requiring any separate program installation.
> [!IMPORTANT]
> **🛡️ 100% Complete Offline Security**
> The program operates without connecting to an external internet network or cloud AI server, using only the user's PC resources (CPU/RAM). None of the input document data is leaked externally.
> * **Recommended Specifications**: Depending on the model, RAM 4GB ~ 16GB or more is required (see below for details)
## 1. Installation and Operation Procedure
### 🛠️ Initial Setup
Place a compatible model folder in the **`Local-Portable-AI\models`** folder.
* **Example models supported as of v0.6v**:
* `gemma-4-E2B-it-qat-UD-Q4_K_XL` — Recommended RAM 4GB or more (fast, long conversation length, low performance, image support)
* `gemma-4-E4B-it-qat-UD-Q4_K_XL` — Recommended RAM 8GB or more (medium, long conversation length, medium performance, image support)
* `gemma-4-12B-it-qat-UD-Q4_K_XL` — Recommended RAM 16GB or more (slow, medium conversation length, high performance, image support)
* `gemma-4-26B-A4B-it-UD-IQ3_S` — Recommended RAM 16GB or more (medium, short conversation length, high performance, no image support)
### 🚀 Server Activation and Connection
1. Open the received **`Local-Portable-AI`** folder.
2. Double-click the **`run_server.bat`** file in the folder to execute it.
3. Follow the console instructions to input the model number to operate.
4. Once the AI engine initialization is complete, a web browser will automatically launch, displaying the chat window screen ([http://127.0.0.1:8080](http://127.0.0.1:8080)). (This may take 5 to 20 seconds, depending on your PC specifications.)
> [!WARNING]
> During program usage, do not close the black console window running in the background.
### ⏹️ Program Termination Method
Close the currently open web browser tab, and then close the black console window or press any key to safely and automatically terminate the backend process.
## 2. Document Analysis Method & File Storage Rules
To analyze a document, place it in a specified allowed path so that AI can safely read it.
### 📂 Allowed Directory (Security Sandbox)
For security reasons, AI can only read files located in the **project root folder and its subfolders**.
* **Recommended storage location**: `./workspace` folder within the project folder
* If you specify a file on the desktop or another drive, access will be blocked due to security policies. Please copy and move files to be analyzed into `./workspace`.
### ✍️ Chat Window Request Example
After placing the file to be analyzed in `./workspace`, request in the AI chat window as follows:
* *"Summarize the dummydata.xlsx file in ./workspace"*
* *"Extract this year's tax revenue table from ./workspace/local statistical report.hwpx in a table format"*
## 3. PDF Document Analysis Pipeline (as of v0.6v)
As of v0.6v, a **hybrid pipeline** automatically operates during PDF analysis, selecting the optimal path based on the type of PDF.
### 📄 Digital PDF (Text Layer Embedded)
This is a PDF generated by a typical word processor. It extracts the original text 100% accurately from the text layer. If an image analysis model (vision mode) is activated, it renders each page image to provide descriptions of visual elements such as illustrations, photos, and charts, along with the text.
```
📄 Text Layer Extraction (kordoc, 100% original preservation)
+
🖼️ Page Image Rendering → Vision Model Visual Analysis (image/illustration description)
↓
Final Combined Markdown (text + visual data specification)
```
### 🖼️ Scanned PDF (Image-based, No Text Layer)
This is a document scanned or converted from an image to PDF. Each page is rendered as a high-resolution image, and then OCR and vision analysis are performed in parallel.
```
🖼️ Full Page High-Resolution Rendering (pdfjs, automatic detection of actual number of pages)
↓
🔤 Tesseract OCR (Korean + English text extraction)
+
👁️ Vision Model Visual Analysis (image/chart description, in vision mode)
↓
Page-specific OCR Text + visual data specification
```
### ⏱️ Document Analysis Time Guide
| Document Type | Analysis Method | Expected Time |
|---|---|---|
| Text-based PDF | Text Layer Extraction (immediate) + Vision Analysis (per page) | a few seconds to a few minutes per page |
| Scanned PDF | Full-page OCR + Vision Analysis | a few minutes per page |
| HWPX / XLSX / DOCX | Direct kordoc parsing | within a few seconds |
| Single PNG / JPG image | Tesseract OCR + Vision Analysis | a few seconds to a few minutes |
> [!NOTE]
> **What is Vision Mode?** It is automatically set when selecting a model with `run_server.bat`. E2B, E4B, and 12B models have image recognition activated, while the 26B model does not. In vision mode, additional time is required for visual element analysis, but it understands documents with images or illustrations much more accurately.
### 🛡️ Hybrid Pipeline and Fallback System
Tesseract OCR and vision model analysis operate in a hybrid (parallel/sequential queue) structure. Even if the vision API does not respond due to a timeout (up to 20 minutes per page) or connection failure, the OCR extraction result is normally preserved and integrated into the final markdown.
```
[1️⃣ Tesseract OCR (text extraction)] [2️⃣ Vision Model (visual image analysis)]
\ /
\ / (excluded in case of failure/timeout)
▼ ▼
[Final Combined Document Markdown Generation]
```
## 4. Automatic Cache System
If the same document is requested for analysis again, it immediately returns the result stored in the `.mcp_cache/` folder. If a file is modified and saved, the cache is automatically invalidated by detecting changes in file size and modification time, and then re-analyzed with the latest content.
## 5. Project Structure and Modular Architecture
This project has been reorganized into a modular architecture under the `src/` folder, separating the main logic by role from a single script (`mcp-bridge.js`).
* **`mcp-bridge.js`**: Service entry point (non-blocking startup and router mounting)
* **`src/` submodules**:
* **`router.js`**: CORS restrictions and Completions API proxy, script injection routing
* **`sandbox.js`**: Security sandbox verification with symbolic link bypass protection
* **`pdf-parser.js`**: Digital/scanned PDF hybrid analysis based on Kordoc and PDFJS
* **`ocr-vision.js`**: Tesseract.js and local vision API parallel inference and automatic worker cleanup
* **`cache.js`**: MD5 caching engine with asynchronous non-blocking startup cleanup
* **`globals.js`**: Global debug logging and state management
* **`kordoc-loader.js`**: Kordoc library dynamic loader
* **`patcher.js`**: Inference response patch module for MCP specification compatibility
## 6. Technologies Used (Powered By)
> [!NOTE]
> The libraries listed below are all included within the program. There is no need for the user to install them separately.
[](https://www.npmjs.com/package/kordoc)
[](https://github.com/mozilla/pdf.js)
[](https://github.com/naptha/tesseract.js)
[](https://github.com/Automattic/node-canvas)
[](https://github.com/ggml-org/llama.cpp)
| Library | Role |
|---|---|
| **[kordoc](https://www.npmjs.com/package/kordoc)** | HWP·HWPX·PDF·XLSX·DOCX parsing and markdown conversion |
| **[Mozilla PDF.js](https://github.com/mozilla/pdf.js)** | High-resolution canvas rendering of PDF pages (for scanned PDF OCR) |
| **[Tesseract.js](https://github.com/naptha/tesseract.js)** | Korean/English OCR text extraction (scanned document processing) |
| **[node-canvas](https://github.com/Automattic/node-canvas)** | Canvas API implementation for PDF rendering in Node.js environment |
| **[llama.cpp](https://github.com/ggml-org/llama.cpp)** | Local LLM/vision model inference server (llama-server) |
## 7. Major Changes (v0.6v)
* **NFC/NFD Korean filename normalization**: Always automatically converts to NFC format so that Korean filenames with separated Cho/Song (NFD) created on macOS, etc., can be searched and read without errors within the Windows environment security sandbox.
* **Non-standard JSON tool call auto-correction**: Automatically detects and converts to standard MCP object structure and execution even if the model uses `tool_calls` or `tool` key instead of `tool_name`, or outputs JSON in a flat structure without `parameters`.
* **Schema-compliant parameter auto-normalization**: Automatically maps incorrectly requested variable names (e.g., `filePath` ↔ `path`, `content` ↔ `data`) to match each tool's schema, preventing WebUI schema validation errors.
* **Document comparison (`compare_documents`) result revamp**: Filters out meaningless output listings of unchanged text or tables (`[Table]`) and provides an intuitive before-and-after comparison of actually changed items (`~ [Changed] "Previous" -> "After"`).
* **Completion streaming buffer optimization**: Increases the temporary buffer size for incomplete tokens to prevent bugs where JSON tool call blocks are interrupted or miss the correction timing during Completions API streaming reception.
