AI Powered Contextual Reader

AI Powered Contextual Reader is a minimal document reader for language study. You can open a .docx, Markdown, plain text file, or a text-based .pdf, click a word in the text, and get an AI explanation that is grounded in the surrounding context instead of showing an isolated dictionary gloss.

This repository currently ships the first usable baseline:

• Open .docx, Markdown, plain text, and text-based PDF files in the browser
• Click a word to request an explanation from an OpenAI-compatible API
• See the explanation in a sticky panel while you continue reading
• Adjust the reader layout with a draggable divider
• Change API settings and Chinese spacing display from the topbar

Who This Is For

This app is useful if you read long-form documents and want fast contextual help without copying text into a separate chatbot window. It is especially suited to:

• bilingual reading
• test-prep and intensive reading
• vocabulary study inside academic or nonfiction texts
• comparing a word's local meaning with its broader sentence context

Current Status

This is an early but runnable release.

It is intentionally narrow in scope. The goal of this version is to make the core reading loop work well:

1. open a supported file
2. click a word
3. read the contextual AI explanation
4. keep moving through the document

If you are looking for OCR, Anki sync, EPUB support, or advanced annotation workflows, those are not included yet. See docs/roadmap.md.

Supported Documents

Supported now

• .docx
• .md
• .markdown
• .txt
• text-based .pdf

Not supported yet

• scanned PDF files that require OCR
• legacy .doc
• EPUB
• images
• handwriting

For PDFs, the text must be selectable. If the PDF behaves like a stack of images, this version will not extract usable text.

For Markdown files, the reader preserves a limited set of useful inline formatting, including:

• bold
• emphasis
• underline via inline HTML such as <u>...</u>
• highlight via inline HTML such as <mark>...</mark>
• inline code

How It Works

The app uses a split workspace:

• left side: document reader
• right side: contextual explanation panel

When you click a word, the app extracts nearby context from the current block of text and sends a request to the local server. The server then calls your OpenAI-compatible provider and returns a structured explanation.

The explanation panel is sticky on desktop layouts, so you do not need to scroll back to the top of the page to see the result.

Requirements

• Bun 1.3 or later
• an OpenAI-compatible API key

Quick Start

bun install
bun run dev

Then open:

http://localhost:3000

If port 3000 is already in use, set PORT before running the server.

Production-style Start

If you want the server to build the frontend and then serve the built app:

bun run start

API Configuration

You can configure the provider in two ways.

Option 1: Set it inside the app

Open the Settings panel in the topbar and fill in:

• OpenAI API Key
• Base URL
• Model

Settings are saved automatically into project config files.

You can also use the Test provider button in the settings panel to verify that your current API key, base URL, and model can complete a minimal request before you start clicking words in the reader.

This is the easiest option for local use.

Option 2: Set environment variables for the server

Copy .env.example to .env and fill in your values.

OPENAI_API_KEY=your_key_here
OPENAI_BASE_URL=https://api.openai.com/v1
OPENAI_MODEL=gpt-4o-mini
PORT=3000

Values entered in the Settings panel override the server defaults for requests made from the currently active config profile.

Reading Workflow

1. Start the app with bun run dev or bun run start.
2. Click Open a document in the topbar.
3. Choose a supported file from your computer.
4. Click a word in the document.
5. Read the explanation in the right panel.
6. Drag the center divider if you want more space for the document or the explanation panel.

Reader Settings

The topbar Settings panel currently includes:

• config profile switching
• config profile creation and deletion
• OpenAI API Key
• Base URL
• Model
• Enable Chinese segmented spacing
• Prompt system
• Prompt template
• Test provider

Chinese segmented spacing

This setting is off by default.

When disabled, Chinese text is displayed like a normal article. When enabled, the reader inserts visible spacing between adjacent Chinese word segments to make token boundaries easier to inspect during study.

This setting only changes display behavior. It does not disable word clicking.

Config profiles

Reader and provider settings are stored as real JSON files inside the project so they can be migrated or versioned with the repository.

Current config storage layout:

config/
  active.json
  profiles/
    default.json
    your-profile.json

The app auto-saves edits to the active profile after a short debounce. There is no manual save button.

Prompt templates currently support these placeholders:

• {{word}}
• {{documentName}}
• {{context}}
• {{system}}

Privacy and Data Flow

Document parsing happens locally in the app.

When you click a word, the app sends the following information to the local server:

• the selected word
• nearby text context
• basic document metadata needed for the explanation request

The local server then forwards the request to your configured OpenAI-compatible provider.

Do not use this version for confidential material unless you are comfortable with the selected context being sent to that provider.

Known Limitations

• text extraction from some PDFs can still be imperfect
• scanned PDFs are not supported
• the app currently focuses on single-word click explanations
• there is no saved vocabulary list yet
• there is no annotation system yet
• there is no account system or sync

Troubleshooting

The page opens but explanations fail

Check the following:

• your API key is valid
• your Base URL points to an OpenAI-compatible endpoint
• the chosen model exists on that provider
• the local server is running
• the Test provider button succeeds with the same settings

If you use a provider such as SiliconFlow, enter the provider URL exactly as the base API root, for example:

https://api.siliconflow.cn/v1

My PDF looks broken or words are oddly split

This usually means the PDF text layer is low quality. Try:

• selecting a different text-based PDF source
• using the original .docx when available
• confirming the PDF text is selectable outside this app

Chinese text looks too spaced out

Turn off Enable Chinese segmented spacing in Settings.

Roadmap

Planned work is tracked in docs/roadmap.md.

The short version:

• better PDF robustness
• richer explanation controls
• saved history and vocabulary workflows
• optional study integrations such as Anki

Development Verification

Useful local commands:

bun test
bun run typecheck
bun run build