Oqura-ai/deepdoc: deep research over a local knowledge base
Deep research tool for local knowledge base.
At a glance
- What is it?
- deepdoc runs a multi-agent research workflow against documents you upload rather than the open web, then writes a markdown report. It is a small, MIT-licensed Python project with a Qdrant dependency and a thin configuration surface, and the README leaves several operational questions open.
- Who is it for?
- deepdoc fits a single analyst or a small team that already runs Docker and wants a report generated from a folder of documents, with OpenAI, Anthropic, Ollama or Gemini as the model backend. It does not fit anyone who needs a maintained API surface, a documented upgrade path or a way to run without an external LLM key, because the README describes none of those.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 135 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
What deepdoc does that a web research agent does not
Most research agents treat the open internet as the corpus. deepdoc inverts that. According to the README, it performs deep research on your local resources instead of the internet, accepting PDF, DOCX, JPG, TXT and similar files, extracting the text and splitting it into page-wise chunks. The intended user is someone with a private document set (contracts, internal reports, scanned pages) who wants a structured markdown write-up without sending the whole corpus through a manual reading pass. The README frames the payoff as uncovering insights from your own files without manually digging through them. That is a narrower and more honest claim than general-purpose search, and it is the reason the project exists. Note the boundary: the documents stay local, but the README's own .env.example requires MISTRAL_API_KEY, TAVILY_API_KEY and OPENAI_API_KEY, so the reasoning path still reaches external services unless you swap the provider in configuration.py.
The agent pipeline: chunks, structure, sections, reflection
The mechanism is a staged LangGraph workflow rather than a single retrieval call. The README lists the sequence: extract text, split into page-wise chunks, store those chunks in a vector database for semantic similarity search, generate a content structure from your instruction query, let you give feedback to refine that structure, then generate report sections and section topics. Each section is then handled by research agents that generate knowledge for the section, create research queries, run search agents over the chunked local data, use reflection agents to refine results, and produce final section content. Section-wise content is compiled and passed to a final report writer, and the output is a complete structured report in markdown. Two details matter for anyone judging the architecture. First, the human feedback step sits between structure generation and section writing, so the expensive part of the run happens after you approve an outline. Second, THREAD_CONFIG in configuration.py exposes max_queries, search_depth, num_reflections and n_points, which are the levers that control how much agent work each section performs. The README does not explain what each value does in practice, so tuning them is guesswork until you read the source.
Installing deepdoc and running a first report
The README requires uv for environment management and points to the official uv GitHub repository for platform-specific installation. Clone the repository and create the virtual environment first.
git clone https://github.com/Oqura-ai/deepdoc.git
cd deepdoc
uv venvActivate it with the command for your platform. On macOS or Linux the README gives source .venv/bin/activate; on Windows it gives .venv\Scripts\activate. Then copy the example environment file and fill in the keys.
cp .env.example .envOpen .env and set MISTRAL_API_KEY, TAVILY_API_KEY and OPENAI_API_KEY. Leave the defaults in place for the vector store: QDRANT_URL=http://localhost:6333, COLLECTION_NAME=knowledge_base, EMBEDDING_MODEL=BAAI/bge-small-en-v1.5 and QDRANT_DISABLE_THREADING=true. The README annotates that last one with "Don't change this". Install the dependencies, then bring up Qdrant.
uv pip install -r requirements.txt
docker-compose up --buildThe docker-compose.yaml defines a single qdrant service on image qdrant/qdrant:latest, mapping ports 6333 and 6334 and persisting storage to ./qdrant_data. Once it is up, start the application.
python main.pyThe README states the application guides you through the dataset creation process step by step and saves the final dataset into the output_files directory. If you want a different model or more agent work per section, edit configuration.py, which the README describes as the place to adjust LLM_CONFIG (provider, model, temperature) and THREAD_CONFIG.
Where deepdoc breaks down or is the wrong tool
The retrieval path is built on page-wise chunks and semantic similarity. That works for prose that survives text extraction and badly for documents that do not. The README lists JPG as an accepted input, but it describes extraction and chunking without describing an OCR stage, so image-only scans are a plausible failure point rather than a supported feature. Verify that before trusting a scanned corpus. The second constraint is the external dependency chain. The .env.example asks for three separate API keys, and requirements.txt pins langchain-openai, langchain-anthropic, langchain-ollama and langchain-google-genai alongside mistralai and tavily-python. A fully offline run is not described anywhere in the README, even though local models appear to be reachable through the Ollama integration. Third, the configuration surface is two dictionaries in one file. If you need per-collection settings, multiple concurrent knowledge bases or a stable configuration contract, this is not the tool. Finally, the README documents no test suite, no evaluation harness and no way to score whether a generated report is grounded in the source chunks. For a pipeline with reflection agents in the loop, that absence is the biggest gap, because there is no documented way to tell a good run from a plausible-sounding one.
How deepdoc differs from RAGFlow and from plain RAG
The comparison people reach for is RAGFlow, and the difference is in the shape of the output. A conventional RAG stack answers a question by retrieving passages and generating a response, one turn at a time, with the user driving the loop. deepdoc is a batch pipeline: it plans a structure, expands each section into research queries, searches the local chunks, reflects on the results and writes a long-form markdown report. The retrieval layer is comparable (Qdrant plus an embedding model, here BAAI/bge-small-en-v1.5 by default), but the orchestration layer is the product. That also means the cost profile is different. A RAG query costs one retrieval and one generation; a deepdoc run costs a structure generation, then per-section knowledge generation, query generation, search, reflection and writing, multiplied by max_queries and num_reflections. If your actual need is question answering over a document set, a plain RAG setup is cheaper and faster. deepdoc earns its overhead only when the deliverable is a written report with sections, not an answer.
Maintenance, dependencies and the MIT licence
The repository is not archived, and the last push was on 2026-05-04. There are no releases in the repository listing, so installation is from the main branch, and any upgrade means pulling new commits and re-resolving requirements.txt. That file mixes exact pins (python-dotenv==1.1.0, langchain-anthropic==0.3.10, tavily-python==0.5.4, rich==14.1.0, pyfiglet==1.0.3, langchain-google-genai==2.1.2, langchain-ollama==0.3.1) with ranges (langchain>=0.3.22,<0.4.0, langgraph>=0.3.24,<0.4.0) and unpinned packages (qdrant-client, python-docx, python-pptx, mistralai, pymupdf, fastembed, pdfplumber, reportlab). The unpinned entries are where breakage will come from, and because there is no lockfile in the repository listing, two installs on different days can resolve differently. The docker-compose.yaml pulls qdrant/qdrant:latest, which is another moving target. The MIT licence is permissive: it allows commercial use and modification, and it requires that the copyright notice and permission notice be included in copies or substantial portions. That is a summary of the licence text, not legal advice; read LICENSE for the operative terms. Because the project ships no releases, there is no version boundary to pin against, which matters if you plan to vendor it.
Editorial conclusion
deepdoc fits a single analyst or a small team that already runs Docker and wants a report generated from a folder of documents, with OpenAI, Anthropic, Ollama or Gemini as the model backend. It does not fit anyone who needs a maintained API surface, a documented upgrade path or a way to run without an external LLM key, because the README describes none of those. Before adopting it, run docker-compose up --build, confirm Qdrant answers on port 6333, and check that configuration.py exposes the knobs you actually need, since it is the only documented place to change model and search behaviour.
Frequently asked questions
Does deepdoc run entirely offline?
The README does not describe an offline mode. The .env.example requires MISTRAL_API_KEY, TAVILY_API_KEY and OPENAI_API_KEY, although configuration.py lets you change the LLM provider and requirements.txt includes langchain-ollama.
What file formats can I upload to deepdoc?
The README lists PDF, DOCX, JPG, TXT and similar local resources. It describes text extraction and page-wise chunking but does not document a separate OCR step for image-only files.
Do I need Docker to run deepdoc?
Yes for the vector store. The README instructs you to start the required services with docker-compose up --build, and docker-compose.yaml defines a qdrant service on ports 6333 and 6334.
Where does deepdoc save the generated report?
The README states the final dataset is saved in the output_files directory, and the repository listing shows an output_folder entry at the top level.
How do I change the model or the amount of research deepdoc does per section?
Edit configuration.py. It holds LLM_CONFIG with provider, model and temperature, and THREAD_CONFIG with max_queries, search_depth, num_reflections and n_points.
Is deepdoc the same as RAGFlow?
No. deepdoc is a staged research pipeline that plans an outline and writes a sectioned markdown report, while a RAG system typically answers individual questions by retrieving passages. Both can use a vector database such as Qdrant for retrieval.
Community notes