Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/aygp-dr/gemini-repl-006

Educational literate programming exercise: Use AI assistants to build a Clojure/Babashka REPL from org-mode specifications
https://github.com/aygp-dr/gemini-repl-006

ai-assistant babashka clojure functional-programming gemini-ai literate-programming org-mode repl

Last synced: 6 months ago
JSON representation

Educational literate programming exercise: Use AI assistants to build a Clojure/Babashka REPL from org-mode specifications

Awesome Lists containing this project

README 

          
#+TITLE: Gemini REPL 006: AI-Assisted Literate Programming Exercise

#+AUTHOR: AYGP-DR

#+DATE: 2025-07-18



[[https://www.freebsd.org/][file:https://img.shields.io/badge/FreeBSD-14.3--RELEASE-red.svg?logo=freebsd]] [[https://clojure.org/][file:https://img.shields.io/badge/Clojure-1.12.0-blue.svg?logo=clojure]] [[https://babashka.org/][file:https://img.shields.io/badge/Babashka-1.12.206-green.svg?logo=clojure]] [[https://orgmode.org/][file:https://img.shields.io/badge/Org--mode-9.0+-purple.svg?logo=gnu-emacs]] [[https://opensource.org/licenses/MIT][file:https://img.shields.io/badge/License-MIT-yellow.svg]] [[https://github.com/aygp-dr/gemini-repl-006][file:https://img.shields.io/badge/Type-Educational-orange.svg]]



* Overview



This repository contains a *literate programming exercise* designed for students learning to work with AI assistants (like Claude, ChatGPT, or Gemini) in software development workflows.



The repository does *NOT* contain a working REPL - instead, it provides a comprehensive specification in the form of a literate org-mode document that an AI assistant can use to generate a complete, working implementation.



* Learning Objectives



Students who complete this exercise will learn:



1. *Literate Programming*: How to work with org-mode documents that combine code and documentation

2. *AI-Assisted Development*: How to guide AI assistants to generate working code from specifications

3. *Functional Programming*: Clojure/Babashka idioms and patterns

4. *System Architecture*: Building a non-trivial application with multiple components

5. *Tool Integration*: Working with external APIs, file systems, and command-line interfaces



* What's in This Repository



This repository contains three key org-mode documents that work together:



1. [[file:README.org][README.org]] (this file) - Instructions for students and overview

2. [[file:CLOJURE-GEMINI-REPL.org][CLOJURE-GEMINI-REPL.org]] - The complete literate programming specification

3. [[file:REQUIREMENTS.org][REQUIREMENTS.org]] - Formal system requirements and acceptance criteria



** Document Relationships



*** [[file:CLOJURE-GEMINI-REPL.org][CLOJURE-GEMINI-REPL.org]] - The Implementation Guide

The main literate programming document contains:

- Detailed system architecture

- All source code (embedded in org-mode blocks)

- Configuration files

- Build scripts

- Test suites

- Documentation

- AI assistant guidance

- *Intentional inconsistencies* for educational purposes



*** [[file:REQUIREMENTS.org][REQUIREMENTS.org]] - The Specification

The formal requirements document defines:

- Core system requirements and constraints

- API specifications and contracts

- Security and performance requirements

- Testing and quality standards

- Release criteria for v0.1.0 and v1.0.0

- Non-functional requirements (accessibility, i18n, extensibility)



*** How They Work Together

1. Students start with the *literate specification* (CLOJURE-GEMINI-REPL.org)

2. They extract and implement the code with AI assistance

3. They validate their implementation against *REQUIREMENTS.org*

4. The requirements serve as acceptance tests for the exercise

5. Any gaps between implementation and requirements are learning opportunities



* Getting Started



** Prerequisites



- An AI assistant (Claude, ChatGPT, Gemini, etc.)

- Basic familiarity with command-line tools

- Emacs with org-mode (for tangling) OR an AI that can extract code blocks

- Babashka installed (for running the generated code)

  - FreeBSD users: Confirmed working on FreeBSD 14.3-RELEASE with ~sudo bash < <(curl -s https://raw.githubusercontent.com/babashka/babashka/master/install)~

  - Docker users: See ~Dockerfile.student~ for a pre-configured environment

  - Other systems: Follow [[https://babashka.org/#installation][official installation guide]]



** Exercise Steps



1. *Fork or Clone* this repository:

   #+begin_src bash

   git clone https://github.com/aygp-dr/gemini-repl-006.git

   cd gemini-repl-006

   #+end_src



2. *Read* the [[file:CLOJURE-GEMINI-REPL.org][CLOJURE-GEMINI-REPL.org]] file to understand the system design



3. *Use your AI assistant* to:

   - Extract (tangle) all the code from the org file

   - Set up the project structure

   - Configure the environment

   - Run tests

   - Start the REPL



4. *Document* your process:

   - What prompts worked well?

   - What challenges did you encounter?

   - How did you guide the AI to success?



** Example AI Prompts



Here are some prompts to get you started:



#+begin_example

"I have a literate programming document called [[file:CLOJURE-GEMINI-REPL.org][CLOJURE-GEMINI-REPL.org]] that contains 

embedded source code for a Clojure/Babashka project. Can you help me extract all the 

code files and set up the project?"

#+end_example



#+begin_example

"Please analyze the [[file:CLOJURE-GEMINI-REPL.org][CLOJURE-GEMINI-REPL.org]] file and create a Makefile target that 

will tangle all the source code files to their correct locations."

#+end_example



#+begin_example

"The org file contains some documentation inconsistencies that were intentionally 

left for educational purposes. Can you identify and fix them?"

#+end_example



* Learning Path



** Beginner Level

1. Successfully extract all files from the org document

2. Get the basic REPL running

3. Execute simple commands



** Intermediate Level

1. Fix any inconsistencies in the extracted code

2. Add a new slash command to the REPL

3. Implement a new tool function

4. Write additional tests



** Advanced Level

1. Refactor the code to improve architecture

2. Add new features (e.g., conversation branching)

3. Implement alternative backends (e.g., OpenAI, Anthropic)

4. Create your own literate programming document for a different project



* Evaluation Criteria



Your implementation will be evaluated on:



1. *Successful Extraction*: Did you extract all files correctly?

2. *Working Implementation*: Does the REPL run without errors?

3. *Problem Solving*: How did you handle issues and inconsistencies?

4. *AI Collaboration*: How effectively did you work with your AI assistant?

5. *Documentation*: Did you document your process and learnings?

6. *Requirements Compliance*: Does your implementation meet the specifications in REQUIREMENTS.org?



** Using REQUIREMENTS.org for Validation



The [[file:REQUIREMENTS.org][REQUIREMENTS.org]] document provides acceptance criteria that your implementation should meet:



- Check the *Core System Requirements* section for API and context specifications

- Validate CLI behavior against *CLI Interface Specifications*

- Ensure all *Core Commands* in the Interactive REPL section work

- Verify *Security Constraints* are enforced (especially workspace sandboxing)

- Run tests to meet *Testing Requirements* coverage targets

- Compare performance against *Performance Requirements* benchmarks



The requirements document includes specific test cases, error codes, and configuration schemas that your implementation should support.



* Tips for Success



- Start by understanding the overall architecture before diving into details

- Use the AI to explain parts you don't understand

- Test incrementally - don't try to get everything working at once

- The org file has intentional inconsistencies - fixing them is part of the exercise

- Compare your extracted files with the expected structure described in the org file



* Submission



If this is part of a course:



1. Create a new repository with your working implementation

2. Include a ~LEARNING-JOURNAL.org~ documenting:

   - Your process

   - AI prompts that worked well

   - Challenges and solutions

   - Insights about AI-assisted development

3. Submit a pull request with a link to your repository



* Historical Context



This is version 006 in the gemini-repl series:

- [[https://github.com/aygp-dr/gemini-repl][Original]]: ClojureScript implementation

- [[https://github.com/aygp-dr/gemini-repl-001][001]]: Added formal methods (TLA+, Alloy)

- [[https://github.com/aygp-dr/gemini-repl-003][003]]: Enhanced tooling and CI/CD

- [[https://github.com/aygp-dr/gemini-repl-005][005]]: Python port with literate programming

- [[https://github.com/aygp-dr/gemini-repl-006][006]]: Clojure/Babashka with literate programming (this exercise)



Each version explores different aspects of REPL design and implementation.



* Resources



- [[https://orgmode.org/][Org-mode Documentation]]

- [[https://babashka.org/][Babashka Documentation]]

- [[https://www.anthropic.com/claude][Claude AI Assistant]]

- [[https://github.com/aygp-dr/gemini-repl-005][Previous Version (Python) - gemini-repl-005]]



* License



This educational material is provided under the MIT License. See the [[file:CLOJURE-GEMINI-REPL.org][CLOJURE-GEMINI-REPL.org]] file for details.



* Support



If you're stuck:

1. Re-read the relevant section of the org file

2. Ask your AI assistant to explain the architecture

3. Check if your issue is mentioned in the "Common Issues" section of the org file

4. Remember: the goal is to learn AI-assisted development, not just to get the code working



Good luck with your literate programming journey! 🚀



* Appendix: Docker Setup (Optional)



If you prefer a containerized environment, here's a simple Dockerfile:



#+begin_src dockerfile :tangle Dockerfile

FROM ubuntu:22.04



# Install basic dependencies

RUN apt-get update && apt-get install -y \

    curl \

    git \

    && rm -rf /var/lib/apt/lists/*



# Install mise (formerly rtx)

RUN curl https://mise.run | sh

ENV PATH="/root/.local/share/mise/shims:/root/.local/bin:${PATH}"



# Install tools via mise

RUN mise use --global java@temurin-17

RUN mise use --global babashka@latest



# Verify installations

RUN java --version && bb --version



WORKDIR /workspace



CMD ["/bin/bash"]

#+end_src



To use this:

1. Tangle just this block: ~C-c C-v t~ on the code block in Emacs

2. Or manually save the above to a file named ~Dockerfile~

3. Build: ~docker build -t gemini-repl .~

4. Run: ~docker run -it -v $(pwd):/workspace gemini-repl~