Oak AI Lesson Assistant

Disclaimer
This project is intended primarily for internal use by Oak National Academy. While the repository is public, there is no expectation for external users to run the application. The installation instructions and other documentation are currently tailored for internal use and may not be comprehensive for external users.

Oak AI Lesson Assistant is a project focused on experimenting with AI models and their applications. This repository contains several components designed to facilitate AI research and development.

Table of contents

• Oak AI Lesson Assistant
  • Table of contents
  • Introduction
  • Installation
    • Prerequisites
    • Turborepo
  • Postgres setup
    • With Docker
    • With Homebrew
  • Doppler
  • Start the development server
  • Testing
    • Jest tests
    • End-to-end tests
      • Playwright tags
    • Testing in VSCode
  • Release process
  • PNPM / dependency problems
  • External contributions
    • Security
    • Contributing to the code
  • Open source acknowledgements
  • License

Introduction

Oak AI Lesson Assistant is a project designed to facilitate the development and testing of AI tools and models. The project is structured as a Turborepo monorepo, leveraging various open-source tools and libraries.

Installation

Prerequisites

With pnpm installed, run the following command from the project root:

pnpm install -r

Turborepo

This application is structured as a Turborepo monorepo. Install the "turbo" command globally:

pnpm install turbo --global

Postgres setup

Instructions are available for both Homebrew and Dockerized setups.

With Docker

Navigate to the packages/db directory:

cd packages/db

Build and run the Docker container to create a database named oai, with the username and password both as oai, bound to port 5432. It will also install pgvector and postgresql-contrib.

pnpm run docker-bootstrap

To run psql, ssh into the box using:

pnpm run docker-psql

To seed the database:

pnpm run db-push
pnpm run db-seed

From the repo root, then run:

pnpm run prompts

To reset and start fresh:

pnpm run docker-reset

To import a snapshot of production or staging databases into your local instance:

pnpm run docker-reset
pnpm run db-restore-from:prd

where :prd can be either :prd or :stg (the Doppler environments).

With Homebrew

Install and start PostgreSQL:

brew install postgresql
brew services start postgresql
createdb oai
psql

In PSQL:

sudo -u postgres psql
CREATE USER oai WITH ENCRYPTED PASSWORD 'oai';
GRANT ALL PRIVILEGES ON DATABASE oai TO oai;
ALTER USER oai WITH SUPERUSER;

Note: Running in superuser mode is not ideal; consider separate users for migrations and queries.

Exit PSQL using \quit.

Install PG Vector:

brew install pgvector
psql postgres
CREATE EXTENSION vector;

Quit PSQL.

Doppler

We use Doppler for secrets management. To run the application, you need to set up the Doppler CLI.

Navigate to the turborepo root:

brew install dopplerhq/cli/doppler
doppler login
doppler setup
pnpm doppler:pull:dev

This command copies the Doppler environment variables for the dev environment to a local .env file. When secrets change, run this command again.

Start the development server

Start the server with:

pnpm dev

Then visit http://localhost:2525.

Testing

Jest tests

The apps/nextjs and packages/aila projects have Jest tests. Run all tests using:

pnpm test

End-to-end tests

Ensure the dev server is running with pnpm dev. Use the Playwright UI to select and run individual tests interactively.

pnpm test-e2e-ui

To run tests headlessly in the CLI:

pnpm test-e2e

Playwright tags

Our Playwright tests are organised with tags:

• @authenticated: Tests with this tag use a pre-created test user, reused without cleanup between tests.
• @openai: Indicates that the test calls the OpenAI API without a mock. These are excluded from CI runs due to potential slowness, flakiness, or expense. We aim to use mocks for these tests in the future.

Testing in VSCode

Install the Jest and Playwright extensions recommended in the workspace config. Testing icons should appear in the gutter to the left of each test when viewing a test file. Clicking the icon will run the test. The testing tab in the VSCode nav bar provides an overview.

Release process

The current release process is fully documented in Notion, but broadly works as follows:

• Work is completed in branches that are merged to main using squash merge, with the commit message (set by the PR title) matching conventional commit convention.
• When ready to release, a 'release candidate' branch is created from main and a PR opened to merge that branch into production (where the live site is deployed from).
• The PR then contains all the commits to be released. This is manually tested.
• Once approved, the PR is merged into production and semantic release creates a tagged version commit, also updating the change log from the merged commits. The production branch is the merged back into main to ensure tags, change log, and hotfixes (raised to production directly from a working branch) are on the main branch.

PNPM / dependency problems

If you encounter issues with dependencies causing errors, try using PNPM's prune command:

pnpm prune
pnpm install -r

If issues persist, remove all node_modules folders in all packages and apps:

turbo clean
pnpm install -r

You may also want to clear your global npx cache:

rm -rf ~/.npm/_npx

External contributions

Security

Please see our security.txt file.

Contributing to the code

We don't currently accept external contributions to the codebase, but this is under review, and we hope to find an approach that works for us and the community.

Open source acknowledgements

As with all web projects, we depend on open-source libraries maintained by others. While it's not practical to acknowledge them all, we express our gratitude for the contributions and efforts of the OSS community.

License

Unless stated otherwise, the codebase is released under the MIT License. This covers both the codebase and any sample code in the documentation. Where any Oak National Academy trademarks or logos are included, these are not released under the MIT License and should be used in line with Oak National Academy brand guidelines.

Any documentation included is © Oak National Academy and available under the terms of the Open Government Licence v3.0, except where otherwise stated.