Dr. Koala

An AI-powered web application for answering users' questions by searching the web.

Table of Contents

• Table of Contents
• Project Structure
• AI Agents Collaboration
• Preview
• Getting Started
  • Setup Environment Variables
    • Backend Environment Variables
    • Frontend Environment Variables
  • Quick Start with Docker Compose
  • Quick Start with Docker Compose for Production
  • Database Setup
  • Start the Server
    • Running Both Backend and Frontend
    • Running Backend Only
    • Running Frontend Only
    • With VSCode Debugger
  • Start the Frontend
    • Manual Setup
    • Using Make Command
  • Running Tests
    • With uv in Command Line
    • With Docker
  • API Documentation
• VSCode/Cursor Settings
• License

Project Structure

Dr. Koala is built with Next.js as the frontend and FastAPI as the backend. Both follow the principles of Clean Architecture. This project is using python-clean-arch as the template.

Based on the concept of clean architecture, the backend application contains the following major layers:

• Core layer (/core): The entities layer, which contains the core business rules and logic
• Service layer (/service): The use cases layer, which contains the application of business rules and logic
• Repository layer (/repository): The infrastructure layer, which contains the data access logic
• API layer (/api): The presentation layer, which contains the HTTP API endpoints

The frontend application contains the following major folders:

• Components folder (/components): The UI components folder, which contains the reusable UI components
• Modules folder (/modules): The module components folder, which contains the business logic for each page
• Hooks folder (/hooks): The hooks folder, which contains the custom hooks for the application, including the API integration logic
• Routes(pages) folder (/pages): The route components folder (in Next.js, it is the pages directory), which defines the routes for the application

AI Agents Collaboration

Dr. Koala uses AutoGen as the multi-agent framework. The prompt templates for the agents are defined in the app/core/constant/agent_configs.toml file.

There are 3 main agents in Dr. Koala:

• Primary Agent: For understanding the user's intentions, questions, and requirements by analyzing the user's input then planning the search, generation, and review tasks. Adjust the processing plan if needed.
• Search Agent: For searching the web with the Brave Search MCP tool.
• Generation Agent: For generating the final answer based on the searched results in the markdown format.

Preview

demo.mov

Getting Started

Setup Environment Variables

Backend Environment Variables

Create a new .env file by running the following command:

cp .env.example .env

Required environment variables:

• DB_HOST: PostgreSQL host (default: localhost)
• DB_PORT: PostgreSQL port (default: 5432)
• DB_NAME: PostgreSQL database name (default: dr_koala)
• DB_USER: PostgreSQL user (default: postgres)
• DB_PASSWORD: PostgreSQL password (default: postgres)
• XAI_API_KEY: Your xAI API key for Grok
• BRAVE_SEARCH_API_KEY: Your Brave Search API key for web searching

Frontend Environment Variables

Setup the frontend environment variables:

cd frontend
cp .env.example .env

Optional environment variables:

• NEXT_PUBLIC_API_URL: Backend API URL (default to http://localhost:7086, no need to change when running locally)

Quick Start with Docker Compose

You can quickly start the server with docker compose:

# Development
docker compose up -d

Quick Start with Docker Compose for Production

Setup the production environment variables:

cp .env.prod.example .env

Then run the following command to start the server in production mode:

docker compose -f docker-compose.prod.yml up --remove-orphans -d

Database Setup

In this example, we use PostgreSQL as the database. If you have it installed locally, you can set the database connection parameters in the .env file:

DB_HOST=localhost
DB_PORT=5432
DB_NAME=dr_koala
DB_USER=postgres
DB_PASSWORD=postgres

Or you can use docker compose file we provided to quickly setup one:

docker compose -f docker-compose.db.yml up -d

You can change the POSTGRES_DB, POSTGRES_USER, POSTGRES_PASSWORD in the .env file to change the database info of docker container.

Please remember to align the DB_NAME, DB_USER, DB_PASSWORD with the POSTGRES_DB, POSTGRES_USER, POSTGRES_PASSWORD in the .env file.

After the database is running, you can initialize the database by running the following commands:

make init-db

Start the Server

You can start both the backend and frontend together, or run them separately.

Running Both Backend and Frontend

To start both servers simultaneously:

make run

This will start:

• Backend API server at http://localhost:7086
• Frontend application at http://localhost:3076

Press Ctrl+C to stop both servers.

Running Backend Only

uv is used to manage the dependencies and virtual environment, make sure you have it installed before you start.

1. Install dependencies

   uv sync

2. Run the backend server

   make run-backend

The backend API will be available at http://localhost:7086.

Running Frontend Only

Make sure you have installed the frontend dependencies first (see Start the Frontend section).

make run-frontend

The frontend will be available at http://localhost:3076.

With VSCode Debugger

VSCode is recommended for development, before you start, make sure you have installed the Python and Python Debugger extensions.

1. First, you need to install the dependencies (see Running Backend Only)

2. Then, select the correct python interpreter in VSCode by press cmd + shift + p and search Python: Select Interpreter. The python interpreter should be the one you installed in the first step, usually you can find the uv-managed virtual environment in the list.

3. Then, you need to set up the debugger configuration for VSCode:

   cp .vscode/launch.example.json .vscode/launch.json

4. Choose the "FastAPI" configuration from the VSCode and run it.

Start the Frontend

The frontend application is built with Next.js and requires Node.js to run.

Manual Setup

1. Navigate to the frontend directory

   cd frontend

2. Setup frontend environment variables

   cp .env.example .env

   You can customize the API URL in .env:

   • NEXT_PUBLIC_API_URL: Backend API URL (default: http://localhost:7086)

3. Install dependencies

   pnpm i

4. Run the development server

   pnpm dev

The frontend application should be available at http://localhost:3076.

Using Make Command

After installing dependencies, you can also use the make command from the project root:

make run-frontend

Running Tests

With uv in Command Line

Make sure you have installed the dependencies with uv:

uv sync

Then, you can run the unit tests by the following command:

make run-unit-tests

With Docker

You can also run the unit tests with docker:

docker build -f Dockerfile.dev -t app-test --build-arg RUN_MODE=test . && docker run app-test

API Documentation

Once the server is running, visit the Swagger UI at http://localhost:7086/docs

VSCode/Cursor Settings

For VSCode/Cursor, run the following command to setup the editor config:

cp .vscode/settings.example.json .vscode/settings.json

License

MIT