AI MIDI Composition Assistant

Final Project: CSC 481 – Knowledge‑Based Systems, Cal Poly, Spring 2025

Instructor: Dr. Rodrigo Canaan

Team: Nathan Lim, Jeremiah Liao, Colin Ngo, and Jerry Tang.

This repository contains the complete source code, evaluation scripts, and demos for our final course project. The system combines a knowledge base of music‑theory and composition rules with an AI LLM-based composer using OpenAI GPT‑o4‑mini to extend a seed MIDI excerpt while respecting harmonic and stylistic constraints.

To read our full paper discussing our system design and its outputs, please see the PDF in the /docs directory.

---

Using The System

# 1. Clone and enter the repo
$ git clone https://github.com/nathanlim1/ai-composition-assistant.git
$ cd ai-composition-assistant

# (2.) Optionally, create a virtual environment.

# 3. Install dependencies
$ pip install -r requirements.txt

# 4. Provide your OpenAI credentials into a .env file.
$ echo "OPENAI_API_KEY=sk‑..." > .env

# 5. Compose an 8‑measure continuation in the same style as the excerpt
$ python main.py --input test_input/bach_minuet_in_g_116.mid \
                 --measures 8 \
                 --output output/extended_piece.mid

# The completed MIDI is written to output/extended_piece.mid

REQUIRED!!: A .env file containing an OPENAI_API_KEY must exist in the project root. The key is automatically loaded by python‑dotenv at runtime. Generate a key using an OpenAI account. This API Key is used to make calls to the OpenAI API to use their LLMs.

---

Our system is runnable via main.py.

Run python main.py --help for the complete option list.

All options have default arguments. Simply running python main.py will use the default input of "test_input/bach_minuet_in_g_116.mid" with 8.0 extended measures, a prompt of "Extend the excerpt in a similar style", recursion limit of 50, max review iterations of 3, and place the output into "our_generated_output/extended_piece.mid".

All default parameters except the input and output filenames were kept the same for all of our internal testing of the system, including all results in our presentation and paper.

---

Reproducing Results from the Paper

We purposefully use OpenAI LLMs with a temperature set to 1, meaning that there is stochastic nature to the LLMs output. That is, given the same input the LLMs will not produce the same output. This means every run of our system will produce different results. We have placed outputs that our system has generated in /our_generated_output in both MIDI and mp3 format (in case using an OpenAI API key or running is otherwise not possible), but feel free to run main.py to reproduce composition results (however, they will be different from what has been created).

---

Repository Structure

ai-composition-assistant/
   │
   ├── docs/                        # Documentation and academic papers
   │   ├── 481FINALPAPER.pdf        # Final project paper
   │   ├── report.tex               # LaTeX report source
   │   └── bibliography.bib         # Bibliography for the paper
   │
   ├── src/                         # Source code
   │   ├── compositionAgent.py      # Core logic for the composition agent and graph
   │   ├── KB.py                    # Knowledge base with music theory rules
   │   ├── MidiHandler.py           # MIDI file handling utilities
   │   └── test_midi_handler.py     # Tests for MIDI handling
   │
   ├── external_generated_output/   # Output from external tools or models
   ├── our_generated_output/        # Output from our system
   ├── test_input/                  # Test MIDI files for input
   │
   ├── main.py                      # Main entry point for running the assistant
   ├── README.md                    # Project documentation
   ├── requirements.txt             # Python dependencies
   └── .gitignore                   # Git ignore rules

---

External Libraries Used

• music21
  For parsing, analyzing, and manipulating MIDI files and music theory data.

• typing_extensions
  Provides backports of new type hinting features for older Python versions.

• python-dotenv and dotenv
  For loading environment variables from .env files.

• langgraph
  For building and running the graph-based workflow that powers the composition agent.

• langchain-openai
  For integrating with OpenAI models as part of the composition and review process.

• langchain-core
  Provides core abstractions and message types for the LangChain ecosystem.

• pydantic
  For data validation and settings management using Python type annotations.

These dependencies are also listed in /requirements.txt

Thank you!