initial commit

.dockerignore

@@ -0,0 +1,2 @@
+node_modules
+dist

.editorconfig

@@ -0,0 +1,10 @@
+root = true
+
+[*]
+end_of_line = lf
+insert_final_newline = true
+
+[*.{js,json,yml}]
+charset = utf-8
+indent_style = space
+indent_size = 2

.env.example

@@ -0,0 +1,5 @@
+# Copy this over:
+# cp .env.example .env
+# Then modify to suit your needs
+TAVILY_API_KEY=your_api_key_here
+LLM_BASE_URL=url_to_llm_here

.eslintrc.cjs

@@ -0,0 +1,60 @@
+module.exports = {
+  extends: [
+    "eslint:recommended",
+    "prettier",
+    "plugin:@typescript-eslint/recommended",
+  ],
+  parserOptions: {
+    ecmaVersion: 12,
+    parser: "@typescript-eslint/parser",
+    project: "./tsconfig.json",
+    sourceType: "module",
+  },
+  plugins: ["import", "@typescript-eslint", "no-instanceof"],
+  ignorePatterns: [
+    ".eslintrc.cjs",
+    "scripts",
+    "src/utils/lodash/*",
+    "node_modules",
+    "dist",
+    "dist-cjs",
+    "*.js",
+    "*.cjs",
+    "*.d.ts",
+  ],
+  rules: {
+    "no-instanceof/no-instanceof": 2,
+    "@typescript-eslint/explicit-module-boundary-types": 0,
+    "@typescript-eslint/no-empty-function": 0,
+    "@typescript-eslint/no-shadow": 0,
+    "@typescript-eslint/no-empty-interface": 0,
+    "@typescript-eslint/no-use-before-define": ["error", "nofunc"],
+    "@typescript-eslint/no-unused-vars": ["warn", { args: "none" }],
+    "@typescript-eslint/no-floating-promises": "error",
+    "@typescript-eslint/no-misused-promises": "error",
+    camelcase: 0,
+    "class-methods-use-this": 0,
+    "import/no-extraneous-dependencies": [
+      "error",
+      { devDependencies: ["**/*.test.ts"] },
+    ],
+    "import/no-unresolved": 0,
+    "import/prefer-default-export": 0,
+    "keyword-spacing": "error",
+    "max-classes-per-file": 0,
+    "max-len": 0,
+    "no-await-in-loop": 0,
+    "no-bitwise": 0,
+    "no-console": 0,
+    "no-restricted-syntax": 0,
+    "no-shadow": 0,
+    "no-continue": 0,
+    "no-underscore-dangle": 0,
+    "no-use-before-define": 0,
+    "no-useless-constructor": 0,
+    "no-return-await": 0,
+    "consistent-return": 0,
+    "no-else-return": 0,
+    "new-cap": ["error", { properties: false, capIsNew: false }],
+  },
+};

.github/workflows/unit-tests.yml

@@ -0,0 +1,52 @@
+# This workflow will run unit tests for the current project
+
+name: CI
+
+on:
+  push:
+  pull_request:
+  workflow_dispatch: # Allows triggering the workflow manually in GitHub UI
+
+# If another push to the same PR or branch happens while this workflow is still running,
+# cancel the earlier run in favor of the next run.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  unit-tests:
+    name: Unit Tests
+    strategy:
+      matrix:
+        os: [ubuntu-latest]
+        node-version: [18.x, 20.x, 22.x]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - name: Use Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v3
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: "yarn"
+      - name: Install dependencies
+        run: yarn install --immutable
+      - name: Build project
+        run: yarn build
+
+      - name: Lint project
+        run: yarn lint:all
+
+      - name: Check README spelling
+        uses: codespell-project/actions-codespell@v2
+        with:
+          ignore_words_file: .codespellignore
+          path: README.md
+
+      - name: Check code spelling
+        uses: codespell-project/actions-codespell@v2
+        with:
+          ignore_words_file: .codespellignore
+          path: src/
+
+      - name: Run tests
+        run: yarn test

.gitignore

@@ -0,0 +1,24 @@
+index.cjs
+index.js
+index.d.ts
+node_modules
+dist
+.yarn/*
+!.yarn/patches
+!.yarn/plugins
+!.yarn/releases
+!.yarn/sdks
+!.yarn/versions
+
+.turbo
+**/.turbo
+**/.eslintcache
+
+.env
+.ipynb_checkpoints
+
+
+# LangGraph API
+.langgraph_api
+
+.idea

.nvmrc

@@ -0,0 +1 @@
+22

.yarnrc.yml

@@ -0,0 +1 @@
+nodeLinker: node-modules

LICENSE

@@ -0,0 +1,24 @@
+This is free and unencumbered software released into the public domain.
+
+Anyone is free to copy, modify, publish, use, compile, sell, or
+distribute this software, either in source code form or as a compiled
+binary, for any purpose, commercial or non-commercial, and by any
+means.
+
+In jurisdictions that recognize copyright laws, the author or authors
+of this software dedicate any and all copyright interest in the
+software to the public domain. We make this dedication for the benefit
+of the public at large and to the detriment of our heirs and
+successors. We intend this dedication to be an overt act of
+relinquishment in perpetuity of all present and future rights to this
+software under copyright law.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
+
+For more information, please refer to <http://unlicense.org/>

README.md

@@ -0,0 +1,109 @@
+# Ollama Deep Researcher
+
+---
+
+##### Typescript Edition
+
+---
+
+> This repo is a Typescript edition of the [Ollama Deep Researcher](https://github.com/langchain-ai/ollama-deep-researcher) and the repo structure is inspired by the [langgraphjs-starter-template](https://github.com/langchain-ai/new-langgraphjs-project)
+
+Ollama Deep Researcher is a fully local web research assistant that uses any LLM hosted by [Ollama](https://ollama.com/search). Give it a topic and it will generate a web search query, gather web search results (via [Tavily](https://www.tavily.com/)), summarize the results of web search, reflect on the summary to examine knowledge gaps, generate a new search query to address the gaps, search, and improve the summary for a user-defined number of cycles. It will provide the user a final markdown summary with all sources used.
+
+![research-rabbit](https://github.com/user-attachments/assets/4308ee9c-abf3-4abb-9d1e-83e7c2c3f187)
+
+Short summary:
+<video src="https://github.com/user-attachments/assets/02084902-f067-4658-9683-ff312cab7944" controls></video>
+
+## 📺 Video Tutorials
+
+See it in action or build it yourself? Check out these helpful video tutorials:
+
+- [Overview of Ollama Deep Researcher with R1](https://www.youtube.com/watch?v=sGUjmyfof4Q) - Load and test [DeepSeek R1](https://api-docs.deepseek.com/news/news250120) [distilled models](https://ollama.com/library/deepseek-r1).
+- [Building Ollama Deep Researcher from Scratch](https://www.youtube.com/watch?v=XGuTzHoqlj8) - Overview of how this is built.
+
+## 🚀 Quickstart
+
+### Configuration
+
+In `./src/agent/configuration.ts` you can set the following configurations:
+
+- Set the name of your local LLM to use with Ollama (it will by default be `llama3.2`)
+- You can set the depth of the research iterations (it will by default be `3`)
+- You can set the base url of your llm (it will by default be `http://localhost:11434`)
+
+### Mac
+
+1. Download the Ollama app for Mac [here](https://ollama.com/download).
+
+2. Pull a local LLM from [Ollama](https://ollama.com/search). As an [example](https://ollama.com/library/deepseek-r1:8b):
+
+```bash
+ollama pull deepseek-r1:8b
+```
+
+3. Setup web search tool:
+
+- [Tavily API](https://tavily.com/)
+
+Set the corresponding environment variable via `.env` file you can simply copy from `.env.example`:
+
+```dotenv
+TAVILY_API_KEY=<your_tavily_api_key>
+```
+
+5. Clone the repository and launch the assistant with the LangGraph server:
+
+```bash
+# Clone the repository and start the LangGraph server
+git clone https://github.com/pacovk/ollama-deep-researcher-ts.git
+cd ollama-deep-researcher-ts
+yarn install
+```
+
+### Using the LangGraph Studio UI
+
+#### Docker Compose
+
+You can use the provided `docker-compose.yml` file to run LangGraph Studio with the Ollama Deep Researcher assistant.
+
+1. Start the LangGraph server with the Ollama Deep Researcher assistant:
+
+```bash
+docker compose up -d
+```
+
+Visit [LangGraph Studio Web UI](https://smith.langchain.com/studio/?baseUrl=http://127.0.0.1:2024) to interact with the assistant.
+
+Give the assistant a topic for research, and you can visualize its process!
+
+<img width="1621" alt="Screenshot 2025-01-24 at 10 08 22 PM" src="https://github.com/user-attachments/assets/4de6bd89-4f3b-424c-a9cb-70ebd3d45c5f" />
+
+ℹ️ There is also a Ollama Web UI available at [http://localhost:2024](http://localhost:2024) to interact with the assistant.
+
+## How it works
+
+Ollama Deep Researcher is inspired by [IterDRAG](https://arxiv.org/html/2410.04343v1#:~:text=To%20tackle%20this%20issue%2C%20we,used%20to%20generate%20intermediate%20answers.). This approach will decompose a query into sub-queries, retrieve documents for each one, answer the sub-query, and then build on the answer by retrieving docs for the second sub-query. Here, we do similar:
+
+- Given a user-provided topic, use a local LLM (via [Ollama](https://ollama.com/search)) to generate a web search query
+- Uses a search engine (configured for [Tavily](https://www.tavily.com/)) to find relevant sources
+- Uses LLM to summarize the findings from web search related to the user-provided research topic
+- Then, it uses the LLM to reflect on the summary, identifying knowledge gaps
+- It generates a new search query to address the knowledge gaps
+- The process repeats, with the summary being iteratively updated with new information from web search
+- It will repeat down the research rabbit hole
+- Runs for a configurable number of iterations (see `configuration` tab)
+
+## Outputs
+
+The output of the graph is a markdown file containing the research summary, with citations to the sources used.
+
+All sources gathered during research are saved to the graph state.
+
+You can visualize them in the graph state, which is visible in LangGraph Studio:
+
+![Screenshot 2024-12-05 at 4 08 59 PM](https://github.com/user-attachments/assets/e8ac1c0b-9acb-4a75-8c15-4e677e92f6cb)
+
+The final summary is saved to the graph state as well:
+
+![Screenshot 2024-12-05 at 4 10 11 PM](https://github.com/user-attachments/assets/f6d997d5-9de5-495f-8556-7d3891f6bc96)

docker-compose.yml

@@ -0,0 +1,27 @@
+services:
+  server:
+    build:
+      context: ./docker
+      dockerfile: Dockerfile
+    volumes:
+      - ${PWD}:/app
+    environment:
+      - LLM_BASE_URL=http://host.docker.internal:11434
+    ports:
+      - "2024:2024"
+
+  ollama-webui:
+    image: ghcr.io/open-webui/open-webui:main
+    container_name: ollama-webui
+    ports:
+      - 8080:8080
+    environment: # https://docs.openwebui.com/getting-started/env-configuration#default_models
+      - OLLAMA_BASE_URLS=http://host.docker.internal:11434 #comma separated ollama hosts
+      - ENV=dev
+      - WEBUI_AUTH=False
+      - WEBUI_NAME=valiantlynx AI
+      - WEBUI_URL=http://localhost:8080
+      - WEBUI_SECRET_KEY=t0p-s3cr3t
+    extra_hosts:
+      - host.docker.internal:host-gateway
+    restart: unless-stopped

docker/Dockerfile

@@ -0,0 +1,10 @@
+FROM node:alpine3.20
+
+EXPOSE 2024
+
+RUN npm install -g npm \
+    npm install -g @langchain/langgraph-cli
+
+WORKDIR /app
+
+ENTRYPOINT ["langgraphjs","dev", "--host", "0.0.0.0"]

jest.config.js

@@ -0,0 +1,18 @@
+export default {
+  preset: "ts-jest/presets/default-esm",
+  moduleNameMapper: {
+    "^(\\.{1,2}/.*)\\.js$": "$1",
+  },
+  transform: {
+    "^.+\\.tsx?$": [
+      "ts-jest",
+      {
+        useESM: true,
+      },
+    ],
+  },
+  extensionsToTreatAsEsm: [".ts"],
+  setupFiles: ["dotenv/config"],
+  passWithNoTests: true,
+  testTimeout: 20000,
+};

langgraph.json

@@ -0,0 +1,8 @@
+{
+  "node_version": "20",
+  "graphs": {
+    "agent": "./src/agent/graph.ts:graph"
+  },
+  "env": ".env",
+  "dependencies": ["."]
+}