# UniversalDocAgent (`unidoc_agent`)
UniversalDocAgent is a Python package designed to intelligently detect document types and automatically extract or summarize their contents using a set of specialized tools. It supports a wide range of file types such as PDFs, Word documents, emails, source code, Excel files, XML, OCR-recognizable images, and plain text.
You can optionally integrate with an LLM backend like **Ollama** to generate summaries and maintain conversation history across sessions.
---
## 🚧 Installation
```bash
pip install .
```
Run this from the root directory of your cloned project or package.
---
## 📂 Supported Document Types
| File Type | Handled By |
|--------------------|------------|
| `.pdf` | PDFTool |
| `.docx` | WordTool |
| `.txt` | TextTool |
| `.py`, `.js`, etc. | CodeTool |
| `.eml` | EmailTool |
| `.xlsx` | ExcelTool |
| `.jpg`, `.png`, etc.| OCRTool |
| `.xml` | XMLTool |
---
## 🚀 Usage Examples
### 1. Extracting Content
```python
from unidoc_agent.agent import read_document
file_path = "sample.pdf"
content = read_document(file_path)
print(content)
```
### 2. Summarizing Content
```python
summary = read_document("example.docx", summarize=True)
print(summary)
```
---
## 🧠 Advanced: Use Ollama LLM Backend
### Custom LLM model or session
```python
from unidoc_agent.agent import UniversalDocAgent
from unidoc_agent.agent import tools
agent = UniversalDocAgent(tools=tools, llm_backend="ollama")
summary = agent.summarize_content("report.txt")
print(summary)
```
---
## 💬 Conversation History with `OllamaClient`
The `OllamaClient` class is used internally to manage conversation context for summarization.
- **Caching**: Stores conversation history locally in `~/.unidoc_ollama_cache/{model}_{session_id}.json`
- **Session Management**: Custom session IDs let you manage multiple user contexts
### Clearing History
```python
from unidoc_agent.ollama_client import OllamaClient
client = OllamaClient(session_id="user123")
client.clear_history()
```
---
## 🔧 API Reference
### `read_document(file_path, summarize=False)`
- `file_path`: Path to the input document
- `summarize`: If `True`, returns a summary via LLM; else returns extracted content
### `UniversalDocAgent`
- `extract_content(file_path)`: Extracts raw content
- `summarize_content(file_path)`: Summarizes content using the selected tool + LLM
---
## 🔮 Tests
Make sure you have `pytest` or `unittest` installed:
```bash
pytest
```
Or:
```bash
python -m unittest discover tests/
```
---
## 📄 License
This project is licensed under the MIT License. See the [LICENSE](./LICENSE) file for details.
---
## 📊 Use Cases
- ✉️ **Email Parsing** – Automatically extract the body of `.eml` files and summarize them.
- 📄 **Document Summary** – Get concise summaries of long reports, manuals, or meeting notes.
- 📈 **Spreadsheet Reader** – Read `.xlsx` Excel files and extract tables or data grids.
- 🔧 **OCR Scanning** – Use OCRTool to read text from images (e.g., scanned receipts).
- 📁 **Source Code Insight** – Extract and analyze comments or logic from `.py` or `.js` files.
- 📖 **Multi-format Aggregation** – Use the same interface (`read_document`) for any supported format.
---
## 🚀 Contributing
Pull requests are welcome. Please open issues for bugs or feature requests.
---
## ✨ Acknowledgements
Thanks to OpenAI, Ollama, and the open-source contributors whose tools helped build this module.
Raw data
{
"_id": null,
"home_page": null,
"name": "unidoc-agent",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "document, pdf, docx, text, code, extract, ollama, chatbot",
"author": "Vedansh Bhatnagar",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/90/0b/99d4575b472577f551906880cc2788b1266a84049f60f825d33c734266d6/unidoc_agent-0.2.5.tar.gz",
"platform": null,
"description": "# UniversalDocAgent (`unidoc_agent`)\n\nUniversalDocAgent is a Python package designed to intelligently detect document types and automatically extract or summarize their contents using a set of specialized tools. It supports a wide range of file types such as PDFs, Word documents, emails, source code, Excel files, XML, OCR-recognizable images, and plain text.\n\nYou can optionally integrate with an LLM backend like **Ollama** to generate summaries and maintain conversation history across sessions.\n\n---\n\n## \ud83d\udea7 Installation\n\n```bash\npip install .\n```\n\nRun this from the root directory of your cloned project or package.\n\n---\n\n## \ud83d\udcc2 Supported Document Types\n\n| File Type | Handled By |\n|--------------------|------------|\n| `.pdf` | PDFTool |\n| `.docx` | WordTool |\n| `.txt` | TextTool |\n| `.py`, `.js`, etc. | CodeTool |\n| `.eml` | EmailTool |\n| `.xlsx` | ExcelTool |\n| `.jpg`, `.png`, etc.| OCRTool |\n| `.xml` | XMLTool |\n\n---\n\n## \ud83d\ude80 Usage Examples\n\n### 1. Extracting Content\n\n```python\nfrom unidoc_agent.agent import read_document\n\nfile_path = \"sample.pdf\"\ncontent = read_document(file_path)\nprint(content)\n```\n\n### 2. Summarizing Content\n\n```python\nsummary = read_document(\"example.docx\", summarize=True)\nprint(summary)\n```\n\n---\n\n## \ud83e\udde0 Advanced: Use Ollama LLM Backend\n\n### Custom LLM model or session\n\n```python\nfrom unidoc_agent.agent import UniversalDocAgent\nfrom unidoc_agent.agent import tools\n\nagent = UniversalDocAgent(tools=tools, llm_backend=\"ollama\")\nsummary = agent.summarize_content(\"report.txt\")\nprint(summary)\n```\n\n---\n\n## \ud83d\udcac Conversation History with `OllamaClient`\n\nThe `OllamaClient` class is used internally to manage conversation context for summarization.\n\n- **Caching**: Stores conversation history locally in `~/.unidoc_ollama_cache/{model}_{session_id}.json`\n- **Session Management**: Custom session IDs let you manage multiple user contexts\n\n### Clearing History\n\n```python\nfrom unidoc_agent.ollama_client import OllamaClient\n\nclient = OllamaClient(session_id=\"user123\")\nclient.clear_history()\n```\n\n---\n\n## \ud83d\udd27 API Reference\n\n### `read_document(file_path, summarize=False)`\n- `file_path`: Path to the input document\n- `summarize`: If `True`, returns a summary via LLM; else returns extracted content\n\n### `UniversalDocAgent`\n- `extract_content(file_path)`: Extracts raw content\n- `summarize_content(file_path)`: Summarizes content using the selected tool + LLM\n\n---\n\n## \ud83d\udd2e Tests\n\nMake sure you have `pytest` or `unittest` installed:\n\n```bash\npytest\n```\n\nOr:\n\n```bash\npython -m unittest discover tests/\n```\n\n---\n\n## \ud83d\udcc4 License\n\nThis project is licensed under the MIT License. See the [LICENSE](./LICENSE) file for details.\n\n---\n\n## \ud83d\udcca Use Cases\n\n- \u2709\ufe0f **Email Parsing** \u2013 Automatically extract the body of `.eml` files and summarize them.\n- \ud83d\udcc4 **Document Summary** \u2013 Get concise summaries of long reports, manuals, or meeting notes.\n- \ud83d\udcc8 **Spreadsheet Reader** \u2013 Read `.xlsx` Excel files and extract tables or data grids.\n- \ud83d\udd27 **OCR Scanning** \u2013 Use OCRTool to read text from images (e.g., scanned receipts).\n- \ud83d\udcc1 **Source Code Insight** \u2013 Extract and analyze comments or logic from `.py` or `.js` files.\n- \ud83d\udcd6 **Multi-format Aggregation** \u2013 Use the same interface (`read_document`) for any supported format.\n\n---\n\n## \ud83d\ude80 Contributing\n\nPull requests are welcome. Please open issues for bugs or feature requests.\n\n---\n\n## \u2728 Acknowledgements\n\nThanks to OpenAI, Ollama, and the open-source contributors whose tools helped build this module.\n\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Universal Document Agent for extracting and analyzing various documents with Ollama support.",
"version": "0.2.5",
"project_urls": null,
"split_keywords": [
"document",
" pdf",
" docx",
" text",
" code",
" extract",
" ollama",
" chatbot"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "8050c6d75ed02ae47c599e15d3a886d50479dcedc2a9033458a6418267cce0ab",
"md5": "9060c9a6f3253bb81cdc0768a88f3ab4",
"sha256": "28ab77d78a93967a790d14e422bcd33b52c112f5689d1678b1fe104807ea1eff"
},
"downloads": -1,
"filename": "unidoc_agent-0.2.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9060c9a6f3253bb81cdc0768a88f3ab4",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 10624,
"upload_time": "2025-07-14T03:39:32",
"upload_time_iso_8601": "2025-07-14T03:39:32.652970Z",
"url": "https://files.pythonhosted.org/packages/80/50/c6d75ed02ae47c599e15d3a886d50479dcedc2a9033458a6418267cce0ab/unidoc_agent-0.2.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "900b99d4575b472577f551906880cc2788b1266a84049f60f825d33c734266d6",
"md5": "6dd4690a6a12536aca04a13002f6f9aa",
"sha256": "64cfa621802a21cf32db21dddf0e5266ceb3af030480440ccbb59061209e1b83"
},
"downloads": -1,
"filename": "unidoc_agent-0.2.5.tar.gz",
"has_sig": false,
"md5_digest": "6dd4690a6a12536aca04a13002f6f9aa",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 9652,
"upload_time": "2025-07-14T03:39:33",
"upload_time_iso_8601": "2025-07-14T03:39:33.759967Z",
"url": "https://files.pythonhosted.org/packages/90/0b/99d4575b472577f551906880cc2788b1266a84049f60f825d33c734266d6/unidoc_agent-0.2.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-14 03:39:33",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "unidoc-agent"
}
JSON