init

Author: philschmid

.gitignore

@@ -0,0 +1,202 @@
+# Node / Frontend
+node_modules/
+frontend/dist/
+frontend/.vite/
+frontend/coverage/
+.DS_Store
+*.local
+
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+# OS generated files
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+
+# IDE files
+.idea/
+.vscode/
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?
+
+# Optional backend venv (if created in root)
+#.venv/ 
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+uv.lock
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+backend/.langgraph_api

Dockerfile

@@ -0,0 +1,46 @@
+# Stage 1: Build React Frontend
+FROM node:20-alpine AS frontend-builder
+
+# Set working directory for frontend
+WORKDIR /app/frontend
+
+# Copy frontend package files and install dependencies
+COPY frontend/package.json ./
+COPY frontend/package-lock.json ./
+# If you use yarn or pnpm, adjust accordingly (e.g., copy yarn.lock or pnpm-lock.yaml and use yarn install or pnpm install)
+RUN npm install
+
+# Copy the rest of the frontend source code
+COPY frontend/ ./
+
+# Build the frontend
+RUN npm run build
+
+# Stage 2: Python Backend
+FROM docker.io/langchain/langgraph-api:3.11
+
+# -- Copy built frontend from builder stage --
+# The app.py expects the frontend build to be at ../frontend/dist relative to its own location.
+# If app.py is at /deps/backend/src/agent/app.py, then ../frontend/dist resolves to /deps/frontend/dist.
+COPY --from=frontend-builder /app/frontend/dist /deps/frontend/dist
+# -- End of copying built frontend --
+
+# -- Adding local package . --
+ADD backend/ /deps/backend
+# -- End of local package . --
+    
+# -- Installing all local dependencies --
+RUN PYTHONDONTWRITEBYTECODE=1 pip install --no-cache-dir -c /api/constraints.txt -e /deps/backend
+# -- End of local dependencies install --
+ENV LANGGRAPH_HTTP='{"app": "/deps/backend/src/agent/app.py:app"}'
+ENV LANGSERVE_GRAPHS='{"agent": "/deps/backend/src/agent/graph.py:graph"}'
+
+# -- Ensure user deps didn't inadvertently overwrite langgraph-api
+RUN mkdir -p /api/langgraph_api /api/langgraph_runtime /api/langgraph_license &&     touch /api/langgraph_api/__init__.py /api/langgraph_runtime/__init__.py /api/langgraph_license/__init__.py
+RUN PYTHONDONTWRITEBYTECODE=1 pip install --no-cache-dir --no-deps -e /api
+# -- End of ensuring user deps didn't inadvertently overwrite langgraph-api --
+# -- Removing pip from the final image ~<:===~~~ --
+RUN pip uninstall -y pip setuptools wheel &&     rm -rf /usr/local/lib/python*/site-packages/pip* /usr/local/lib/python*/site-packages/setuptools* /usr/local/lib/python*/site-packages/wheel* &&     find /usr/local/bin -name "pip*" -delete
+# -- End of pip removal --
+
+WORKDIR /deps/backend

Makefile

@@ -0,0 +1,20 @@
+.PHONY: help dev-frontend dev-backend dev
+
+help:
+	@echo "Available commands:"
+	@echo "  make dev-frontend    - Starts the frontend development server (Vite)"
+	@echo "  make dev-backend     - Starts the backend development server (Uvicorn with reload)"
+	@echo "  make dev             - Starts both frontend and backend development servers"
+
+dev-frontend:
+	@echo "Starting frontend development server..."
+	@cd frontend && npm run dev
+
+dev-backend:
+	@echo "Starting backend development server..."
+	@cd backend && langgraph dev
+
+# Run frontend and backend concurrently
+dev:
+	@echo "Starting both frontend and backend development servers..."
+	@make dev-frontend & make dev-backend 

README.md

@@ -0,0 +1,106 @@
+# Gemini DeepSearch LangGraph Quickstart
+
+This project demonstrates a fullstack application using a React frontend and a LangGraph-powered backend agent. The agent is designed to perform comprehensive research on a user's query by dynamically generating search terms, querying the web using Google Search, reflecting on the results to identify knowledge gaps, and iteratively refining its search until it can provide a well-supported answer with citations. This application serves as an example of building research-augmented conversational AI using LangGraph and Google's Gemini models.
+
+## Features
+
+- 💬 Fullstack application with a React frontend and LangGraph backend.
+- 🧠 Powered by a LangGraph agent for advanced research and conversational AI.
+- 🔍 Dynamic search query generation using Google Gemini models.
+- 🌐 Integrated web research via Google Search API.
+- 🤔 Reflective reasoning to identify knowledge gaps and refine searches.
+- 📄 Generates answers with citations from gathered sources.
+- 🔄 Hot-reloading for both frontend and backend development during development.
+
+## Project Structure
+
+The project is divided into two main directories:
+
+-   `frontend/`: Contains the React application built with Vite.
+-   `backend/`: Contains the LangGraph/FastAPI application, including the research agent logic.
+
+## Getting Started: Development and Local Testing
+
+Follow these steps to get the application running locally for development and testing.
+
+**1. Prerequisites:**
+
+-   Node.js and npm (or yarn/pnpm)
+-   Python 3.8+
+-   **`GEMINI_API_KEY`**: The backend agent requires a Google Gemini API key.
+    1.  Navigate to the `backend/` directory.
+    2.  Create a file named `.env` by copying the `backend/.env.example` file.
+    3.  Open the `.env` file and add your Gemini API key: `GEMINI_API_KEY="YOUR_ACTUAL_API_KEY"`
+
+**2. Install Dependencies:**
+
+**Backend:**
+
+```bash
+cd backend
+pip install .
+```
+
+**Frontend:**
+
+```bash
+cd frontend
+npm install
+```
+
+**3. Run Development Servers:**
+
+**Backend & Frontend:**
+
+```bash
+make dev
+```
+This will run the backend and frontend development servers.    Open your browser and navigate to the frontend development server URL (e.g., `http://localhost:5173/app`).
+
+_Alternatively, you can run the backend and frontend development servers separately. For the backend, open a terminal in the `backend/` directory and run `langgraph dev`. The backend API will be available at `http://127.0.0.1:2024`. It will also open a browser window to the LangGraph UI. For the frontend, open a terminal in the `frontend/` directory and run `npm run dev`. The frontend will be available at `http://localhost:5173`._
+
+## How the Backend Agent Works (High-Level)
+
+The core of the backend is a LangGraph agent defined in `backend/src/agent/graph.py`. It follows these steps:
+
+![Agent Flow](./deepsearch.png)
+
+1.  **Generate Initial Queries:** Based on your input, it generates a set of initial search queries using a Gemini model.
+2.  **Web Research:** For each query, it uses the Gemini model with the Google Search API to find relevant web pages.
+3.  **Reflection & Knowledge Gap Analysis:** The agent analyzes the search results to determine if the information is sufficient or if there are knowledge gaps. It uses a Gemini model for this reflection process.
+4.  **Iterative Refinement:** If gaps are found or the information is insufficient, it generates follow-up queries and repeats the web research and reflection steps (up to a configured maximum number of loops).
+5.  **Finalize Answer:** Once the research is deemed sufficient, the agent synthesizes the gathered information into a coherent answer, including citations from the web sources, using a Gemini model.
+
+## Deployment
+
+In production, the backend server serves the optimized static frontend build. LangGraph requires a Redis instance and a Postgres database. Redis is used as a pub-sub broker to enable streaming real time output from background runs. Postgres is used to store assistants, threads, runs, persist thread state and long term memory, and to manage the state of the background task queue with 'exactly once' semantics. For more details on how to deploy the backend server, take a look at the [LangGraph Documentation](https://langchain-ai.github.io/langgraph/concepts/deployment_options/). Below is an example of how to build a Docker image that includes the optimized frontend build and the backend server and run it via `docker-compose`.
+
+_Note: For the docker-compose.yml example you need a LangSmith API key, you can get one from [LangSmith](https://smith.langchain.com/settings)._
+
+_Note: If you are not running the docker-compose.yml example or exposing the backend server to the public internet, you update the `apiUrl` in the `frontend/src/App.tsx` file your host. Currently the `apiUrl` is set to `http://localhost:8123` for docker-compose or `http://localhost:2024` for development._
+
+**1. Build the Docker Image:**
+
+   Run the following command from the **project root directory**:
+   ```bash
+   docker build -t deepsearch -f Dockerfile .
+   ```
+**2. Run the Production Server:**
+
+   ```bash
+   GEMINI_API_KEY=<your_gemini_api_key> LANGSMITH_API_KEY=<your_langsmith_api_key> docker-compose up
+   ```
+
+Open your browser and navigate to `http://localhost:8123/app/` to see the application. The API will be available at `http://localhost:8123`.
+
+## Technologies Used
+
+- [React](https://reactjs.org/) (with [Vite](https://vitejs.dev/)) - For the frontend user interface.
+- [Tailwind CSS](https://tailwindcss.com/) - For styling.
+- [Shadcn UI](https://ui.shadcn.com/) - For components.
+- [LangGraph](https://github.com/langchain-ai/langgraph) - For building the backend research agent.
+- [Google Gemini](https://ai.google.dev/models/gemini) - LLM for query generation, reflection, and answer synthesis.
+
+## License
+
+This project is licensed under the Apache License 2.0. See the [LICENSE](LICENSE) file for details. 

backend/.env.example

@@ -0,0 +1 @@
+# GEMINI_API_KEY=