voice-document-assistant

KO | EN

gitlite — search

#javascript #ai #llm #golang #go #android #linux #docker #macos #nodejs #cli #ios #mcp #open-source

voice-document-assistant

(★ 11)

A terminal-based assistant that lets you interact with local documents through voice

voice-document-assistant Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Voice Document Assistant

A terminal-based assistant that lets you interact with local documents through voice. Speak to it naturally and it will parse, read, and summarize PDFs, Office files, and images on your filesystem.

It uses the Gemini Live API for real-time audio and [LiteParse](https://github.com/run-llama/liteparse) for document parsing.

## Requirements

- Python 3.13+
- [LiteParse](https://github.com/run-llama/liteparse) for parsing (`npm install -g @llamaindex/liteparse` or `brew install run-llama/liteparse/llamaindex-liteparse`).
- A Google Gemini API key
- A working microphone and audio output device
- [uv](https://docs.astral.sh/uv/) for dependency management

PortAudio must be installed for PyAudio to work:

```bash
# macOS
brew install portaudio

# Debian/Ubuntu
sudo apt-get install portaudio19-dev
```

## Setup

```bash
git clone https://github.com/run-llama/voice-document-assistant
cd voice-document-assistant
uv pip install -e .
```

Set your API key, the Gemini Live Model and (optionally) the project associated with your API key:

```bash
export GOOGLE_API_KEY=your-api-key-here
export GEMINI_LIVE_MODEL="..."
export GOOGLE_PROJECT="..."
```

## Usage

Run the assistant from the directory containing your documents:

```bash
cd /path/to/your/documents
uv run run-agent
```

The assistant will listen through your microphone. Speak naturally to ask about files — for example:

- "What files do I have here?"
- "Summarize the PDF in my data folder."
- "Parse all the Word documents and tell me which ones mention budget."

Press `Ctrl+C` to end the session.

## Tools available to the agent

| Tool | Description |
|------|-------------|
| `list_current_folder_content` | Recursively lists files in the working directory |
| `parse_file` | Parses a single PDF, Office doc, or image into text or JSON |
| `parse_folder` | Batch-parses all supported files in a folder |
| `read_file` | Reads a text file (e.g. output from `parse_folder`) |

## Document parsing

Parsing is handled by [LiteParse](https://github.com/run-llama/liteparse), a local document parser that runs entirely on your machine (no GPU, no external models required). It extracts text with spatial positioning and can run OCR on scanned pages.

### Supported formats

- **PDF** — parsed directly
- **Office documents** — `.doc`, `.docx`, `.docm`, `.odt`, `.rtf`, `.ppt`, `.pptx`, `.pptm`, `.odp`, `.xls`, `.xlsx`, `.xlsm`, `.ods`, `.csv`, `.tsv` (converted via LibreOffice)
- **Images** — `.jpg`, `.jpeg`, `.png`, `.gif`, `.bmp`, `.tiff`, `.webp`, `.svg` (converted via ImageMagick)

LibreOffice and ImageMagick must be installed for non-PDF formats to work.

### Text vs. JSON output

When you ask the agent to parse a file, it returns plain text by default. You can ask it to return structured JSON instead, which includes per-page bounding boxes for each text element:

```json
[
  {
    "page": 1,
    "blocks": [
      {
        "text": "Invoice #1234",
        "x1": 72, "y1": 48, "x2": 300, "y2": 66
      }
    ]
  }
]
```

This is useful when you need to reason about the layout of a document (e.g. tables, columns, headers) rather than just its content.

### Batch parsing

The `parse_folder` tool converts all supported files in a directory and writes the results as `.txt` files to an output directory. This is efficient for large document sets because LiteParse reuses the same PDF engine across files. After batch parsing, use `read_file` to inspect individual results.

## License

MIT

voice-document-assistant

voice-document-assistant Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

voice-document-assistant

voice-document-assistant Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README