September 20th by midnight.

You are tasked with building a simple a command-line tool that allows developers to use any OpenAI-compatible Chat Completion API endpoint in order to transform files in some helpful way.

Every student has played with Large Language Models (LLM) via ChatGPT or other apps, but very few have programmed using them. There are few topics in programming more exciting right now than learning how to program LLMs and we'll use our labs to explore this topic in detail.

LLMs allow us to transform text (and other media) from one format to another. A really simple example to understand might be translating English text to French. LLMs understand patterns like this really well and can solve lots of interesting language problems. And programmers have tons of interesting language problems!

Here are some suggestions of example tools you could build (feel free to build something totally different). They all work the same way: take an input file, transform it with an LLM and/or code, output the result. Your transformation should use an LLM via a Chat Completion, but may also layer on other transformations you do in code (e.g., you could pretty-print source code with something like Prettier before you output it):

1. Language translator: takes a source file in one programming language and outputs the file in a different language chosen by the user
2. Source code documenter: takes a source file and outputs the same source with code comments added
3. Code review: takes a source file or git diff, reviews the code, and outputs the code with review comments in Markdown format.
4. Merge conflict helper: takes a file with git merge conflict markers and outputs advice on how to fix it and/or a corrected version
5. Readme generator: takes a file and produces a README.md file to explain it
6. Test generator: takes a source file and outputs tests using some pre-defined testing framework
7. API documentation generator: takes a source file and generates API docs in some standard form
8. Source code localization: identifies strings that need to be translated in a file and outputs a localized version of the source ready for translation
9. Architecture Diagram generator: takes a source file and generates a diagram in Markdown with Mermaid.js or HTML with SVG, etc.
10. Unminifier: takes source code that has been minified (e.g., JS) and rewrites it in an unminified form

This first release is designed to expose you to the common workflows and tools involved in contributing to open source projects on GitHub. In order to give every student a similar learning experience, we will all be working on the same project.

This first release is also aimed at putting you in the role of "open source creator" and later "open source maintainer." You will use the code you write in this assignment in subsequent labs during the course to explore various aspects of open source work.

NOTE: in subsequent releases, you will have the freedom to work on real open source projects, but this first one is designed to give you a specific set of experiences.

In addition to the actual code you will write, the ultimate goal of this first release is to help you gain experience in many aspects of open source development, specifically:

• gaining experience in a programming language by building a real-world tool (you can use any programming language you want, even one that's new to you)
• learning about LLMs, chat completions, models, and prompts
• working with the basics of git, including branches, commits, etc.
• creating open source projects on GitHub
• writing about your own work via your Blog

At first, your CLI tool will have only a small number of features. Over the coming months we'll add more.

For this first release, you are asked to create a command-line tool (e.g., no GUI and not a web app). Your command-line tool will process input source files with an LLM to generate an output.

You will need to make your code work with the OpenAI Chat Completions API, and using a compatible provider. There are many you can choose from, some of which are free:

• Grok (free with llama models) - https://console.groq.com
• Official OpenAI (not free) - https://platform.openai.com/docs/overview
• OpenRouter (free and non-free models) - https://openrouter.ai/
• Ollama (free local LLMs) - https://ollama.com/blog/openai-compatibility

Each of these providers works in a similar way:

• create an Account
• generate an API Key
• find the correct Base URL to use for the API

After that, you can use any of the many open source libraries for different programming languages that work with OpenAI compatible APIs. If you don't find one you like, you can also use direct HTTP calls.

You can also try the API Base URL https://free-chatcraft-ai.deno.dev/api/v1 we use in ChatCraft for our free provider (use any string for the API Key, since no API key is necessary). It will route between various free models for you automatically if you use the auto model. See https://free-chatcraft-ai.deno.dev/api/v1/models for the list of all models it supports.

To begin, your tool must include all of the following:

1. pick a name for your tool. Try not to pick a name that is already used by other projects.

2. create a GitHub Repo for your project, see https://docs.github.com/en/enterprise/2.15/user/articles/create-a-repo

3. choose an OSI Approved Open Source License for your project and include a LICENSE file in your repo, see https://docs.github.com/en/github/creating-cloning-and-archiving-repositories/licensing-a-repository

4. create a README.md file, and keep it updated as you write your code, documenting how to use your tool, which features you include, etc. Your README file should tell users what your tool is for, how to use it, and give examples. GitHub README files are written in Markdown, which is a format you need to become comfortable using.

5. choose a programming language. You can use any language you want: pick one you know and love, or something new that you've never used before and want to learn. If you're studying a particular language in other courses, consider picking that one so you can get more practice with it. Or, if you want to add a new language to your resume, this is a good chance to practice. You might also choose to use a language you know, but in a new runtime (e.g., try using JavaScript with Bun instead of node.js). Students in previous semesters have used JavaScript, TypeScript, Python, C++, Go, Rust, Ruby, etc.

6. running your tool at the command-line with the --version or -v flag should print the tool's name and current version.

7. running your tool at the command-line with the --help or -h flag should print a standard help/usage message showing how to run the tool, which command line flags and arguments can be used, etc.

8. your tool should allow the user to specify one or more files as input:

# execute with a single file
tool-name ./file.js

# execute with multiple files
tool-name file1.js ../src/file2.js

9. by default, your tool should output to stdout

10. all debug info, errors, etc. should be written to stderr (i.e., so you don't mix logs with output).

11. at first, you can have your CLI tool simply echo the input file(s) back again to output. Once that's working, add LLM integration and make something really simple work (don't worry about making it perfect, just get something working for now).

In addition to the required features, you are asked to pick at least 2 of the following optional features to include in your submission:

1. allow the user to specify the model to use with the --model or -m flag

2. allow the user to specify an output filename using --output or -o:

# output to stdout
tool-name ./file.js

# output is written to file1-modified.js
tool-name file1.js -o file1-modified.js

3. allow the user to optionally specify their API key using --api-key or -a and the base URL using --base-url or -u:

4. allow the user to create an [.env file] in the current directory and have your tool automatically use it to set the API Key, Base URL, and any other config options you want.

5. pick a few of the optional parameters you can set for chat completions (e.g., temperature) and allow the user to set them via command-line args or .env file

6. support streaming responses when writing to stdout.

7. come up with your own idea. If you have an idea not listed above, talk to your professor and see if it's OK to implement that (it probably is).

For this assignment, everyone must create their own project, but that doesn't mean you can't talk to your colleagues. At every stage of your work, make sure you ask for help, share ideas, and get feedback from others in the class. You're also welcome to program together, use AI to help write your code (hopefully you can use your own tool to write itself at some point!), and collaborate with each other. Please use Slack to help with communication.

Try using community-based, open, collaborative development practices. This means talking with others about your work, and talking to them about theirs, asking for and giving help, and focusing on people as well as code. It also means doing this in public (e.g., on Slack) instead of in private. The goal is to support each other and for us to start building a community.

You will be graded on the following. Please make sure you have addressed everything that makes sense below:

• GitHub Repo exists
• GitHub Repo contains LICENSE file
• GitHub Repo contains a README.md file with clear and complete information on the steps to use the tool, examples, and all of its features
• GitHub README.md is free of typos, spelling mistakes, formatting or other errors
• README includes a short Movie, GIF, or link to recorded demo using vhs, asciinema, or screen recording showing a brief demo of how your tool works
• GitHub Repo contains project's Source Code
• GitHub Repo contains an examples/ directory with some sample/test files to use
• GitHub Repo does NOT contain any API Keys or other secrets (make sure you don't leak these when you add your code!)
• Source Code implements all Mandatory Requirements, and each one is Complete and Working
• Source Code implements 2 of the Optional Requirements, and both are Complete and Working
• Source Code is well written (consistent formatting, code comments, good naming, etc)
• Blog Post documents the project, how to use it, which features it includes, and shows examples of how to use it, including a link to your video demo recording
• Blog Post contains link to GitHub repo
• Add Info to Table Below

When you have completed all the requirements above, please add your details to the table below.