{"id":31285704,"url":"https://github.com/aygp-dr/gemini-repl-006","last_synced_at":"2025-09-24T08:13:14.280Z","repository":{"id":305242171,"uuid":"1022353401","full_name":"aygp-dr/gemini-repl-006","owner":"aygp-dr","description":"Educational literate programming exercise: Use AI assistants to build a Clojure/Babashka REPL from org-mode specifications","archived":false,"fork":false,"pushed_at":"2025-07-19T00:02:27.000Z","size":49,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-19T03:53:21.522Z","etag":null,"topics":["ai-assistant","babashka","clojure","functional-programming","gemini-ai","literate-programming","org-mode","repl"],"latest_commit_sha":null,"homepage":null,"language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aygp-dr.png","metadata":{"files":{"readme":"README.org","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-18T22:48:35.000Z","updated_at":"2025-07-19T00:02:30.000Z","dependencies_parsed_at":"2025-07-19T04:08:44.444Z","dependency_job_id":null,"html_url":"https://github.com/aygp-dr/gemini-repl-006","commit_stats":null,"previous_names":["aygp-dr/gemini-repl-006"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/aygp-dr/gemini-repl-006","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aygp-dr%2Fgemini-repl-006","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aygp-dr%2Fgemini-repl-006/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aygp-dr%2Fgemini-repl-006/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aygp-dr%2Fgemini-repl-006/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aygp-dr","download_url":"https://codeload.github.com/aygp-dr/gemini-repl-006/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aygp-dr%2Fgemini-repl-006/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":276714452,"owners_count":25691398,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-24T02:00:09.776Z","response_time":97,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-assistant","babashka","clojure","functional-programming","gemini-ai","literate-programming","org-mode","repl"],"created_at":"2025-09-24T08:13:09.752Z","updated_at":"2025-09-24T08:13:14.262Z","avatar_url":"https://github.com/aygp-dr.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"#+TITLE: Gemini REPL 006: AI-Assisted Literate Programming Exercise\n#+AUTHOR: AYGP-DR\n#+DATE: 2025-07-18\n\n[[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]]\n\n* Overview\n\nThis repository contains a *literate programming exercise* designed for students learning to work with AI assistants (like Claude, ChatGPT, or Gemini) in software development workflows.\n\nThe 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.\n\n* Learning Objectives\n\nStudents who complete this exercise will learn:\n\n1. *Literate Programming*: How to work with org-mode documents that combine code and documentation\n2. *AI-Assisted Development*: How to guide AI assistants to generate working code from specifications\n3. *Functional Programming*: Clojure/Babashka idioms and patterns\n4. *System Architecture*: Building a non-trivial application with multiple components\n5. *Tool Integration*: Working with external APIs, file systems, and command-line interfaces\n\n* What's in This Repository\n\nThis repository contains three key org-mode documents that work together:\n\n1. [[file:README.org][README.org]] (this file) - Instructions for students and overview\n2. [[file:CLOJURE-GEMINI-REPL.org][CLOJURE-GEMINI-REPL.org]] - The complete literate programming specification\n3. [[file:REQUIREMENTS.org][REQUIREMENTS.org]] - Formal system requirements and acceptance criteria\n\n** Document Relationships\n\n*** [[file:CLOJURE-GEMINI-REPL.org][CLOJURE-GEMINI-REPL.org]] - The Implementation Guide\nThe main literate programming document contains:\n- Detailed system architecture\n- All source code (embedded in org-mode blocks)\n- Configuration files\n- Build scripts\n- Test suites\n- Documentation\n- AI assistant guidance\n- *Intentional inconsistencies* for educational purposes\n\n*** [[file:REQUIREMENTS.org][REQUIREMENTS.org]] - The Specification\nThe formal requirements document defines:\n- Core system requirements and constraints\n- API specifications and contracts\n- Security and performance requirements\n- Testing and quality standards\n- Release criteria for v0.1.0 and v1.0.0\n- Non-functional requirements (accessibility, i18n, extensibility)\n\n*** How They Work Together\n1. Students start with the *literate specification* (CLOJURE-GEMINI-REPL.org)\n2. They extract and implement the code with AI assistance\n3. They validate their implementation against *REQUIREMENTS.org*\n4. The requirements serve as acceptance tests for the exercise\n5. Any gaps between implementation and requirements are learning opportunities\n\n* Getting Started\n\n** Prerequisites\n\n- An AI assistant (Claude, ChatGPT, Gemini, etc.)\n- Basic familiarity with command-line tools\n- Emacs with org-mode (for tangling) OR an AI that can extract code blocks\n- Babashka installed (for running the generated code)\n  - FreeBSD users: Confirmed working on FreeBSD 14.3-RELEASE with ~sudo bash \u003c \u003c(curl -s https://raw.githubusercontent.com/babashka/babashka/master/install)~\n  - Docker users: See ~Dockerfile.student~ for a pre-configured environment\n  - Other systems: Follow [[https://babashka.org/#installation][official installation guide]]\n\n** Exercise Steps\n\n1. *Fork or Clone* this repository:\n   #+begin_src bash\n   git clone https://github.com/aygp-dr/gemini-repl-006.git\n   cd gemini-repl-006\n   #+end_src\n\n2. *Read* the [[file:CLOJURE-GEMINI-REPL.org][CLOJURE-GEMINI-REPL.org]] file to understand the system design\n\n3. *Use your AI assistant* to:\n   - Extract (tangle) all the code from the org file\n   - Set up the project structure\n   - Configure the environment\n   - Run tests\n   - Start the REPL\n\n4. *Document* your process:\n   - What prompts worked well?\n   - What challenges did you encounter?\n   - How did you guide the AI to success?\n\n** Example AI Prompts\n\nHere are some prompts to get you started:\n\n#+begin_example\n\"I have a literate programming document called [[file:CLOJURE-GEMINI-REPL.org][CLOJURE-GEMINI-REPL.org]] that contains \nembedded source code for a Clojure/Babashka project. Can you help me extract all the \ncode files and set up the project?\"\n#+end_example\n\n#+begin_example\n\"Please analyze the [[file:CLOJURE-GEMINI-REPL.org][CLOJURE-GEMINI-REPL.org]] file and create a Makefile target that \nwill tangle all the source code files to their correct locations.\"\n#+end_example\n\n#+begin_example\n\"The org file contains some documentation inconsistencies that were intentionally \nleft for educational purposes. Can you identify and fix them?\"\n#+end_example\n\n* Learning Path\n\n** Beginner Level\n1. Successfully extract all files from the org document\n2. Get the basic REPL running\n3. Execute simple commands\n\n** Intermediate Level\n1. Fix any inconsistencies in the extracted code\n2. Add a new slash command to the REPL\n3. Implement a new tool function\n4. Write additional tests\n\n** Advanced Level\n1. Refactor the code to improve architecture\n2. Add new features (e.g., conversation branching)\n3. Implement alternative backends (e.g., OpenAI, Anthropic)\n4. Create your own literate programming document for a different project\n\n* Evaluation Criteria\n\nYour implementation will be evaluated on:\n\n1. *Successful Extraction*: Did you extract all files correctly?\n2. *Working Implementation*: Does the REPL run without errors?\n3. *Problem Solving*: How did you handle issues and inconsistencies?\n4. *AI Collaboration*: How effectively did you work with your AI assistant?\n5. *Documentation*: Did you document your process and learnings?\n6. *Requirements Compliance*: Does your implementation meet the specifications in REQUIREMENTS.org?\n\n** Using REQUIREMENTS.org for Validation\n\nThe [[file:REQUIREMENTS.org][REQUIREMENTS.org]] document provides acceptance criteria that your implementation should meet:\n\n- Check the *Core System Requirements* section for API and context specifications\n- Validate CLI behavior against *CLI Interface Specifications*\n- Ensure all *Core Commands* in the Interactive REPL section work\n- Verify *Security Constraints* are enforced (especially workspace sandboxing)\n- Run tests to meet *Testing Requirements* coverage targets\n- Compare performance against *Performance Requirements* benchmarks\n\nThe requirements document includes specific test cases, error codes, and configuration schemas that your implementation should support.\n\n* Tips for Success\n\n- Start by understanding the overall architecture before diving into details\n- Use the AI to explain parts you don't understand\n- Test incrementally - don't try to get everything working at once\n- The org file has intentional inconsistencies - fixing them is part of the exercise\n- Compare your extracted files with the expected structure described in the org file\n\n* Submission\n\nIf this is part of a course:\n\n1. Create a new repository with your working implementation\n2. Include a ~LEARNING-JOURNAL.org~ documenting:\n   - Your process\n   - AI prompts that worked well\n   - Challenges and solutions\n   - Insights about AI-assisted development\n3. Submit a pull request with a link to your repository\n\n* Historical Context\n\nThis is version 006 in the gemini-repl series:\n- [[https://github.com/aygp-dr/gemini-repl][Original]]: ClojureScript implementation\n- [[https://github.com/aygp-dr/gemini-repl-001][001]]: Added formal methods (TLA+, Alloy)\n- [[https://github.com/aygp-dr/gemini-repl-003][003]]: Enhanced tooling and CI/CD\n- [[https://github.com/aygp-dr/gemini-repl-005][005]]: Python port with literate programming\n- [[https://github.com/aygp-dr/gemini-repl-006][006]]: Clojure/Babashka with literate programming (this exercise)\n\nEach version explores different aspects of REPL design and implementation.\n\n* Resources\n\n- [[https://orgmode.org/][Org-mode Documentation]]\n- [[https://babashka.org/][Babashka Documentation]]\n- [[https://www.anthropic.com/claude][Claude AI Assistant]]\n- [[https://github.com/aygp-dr/gemini-repl-005][Previous Version (Python) - gemini-repl-005]]\n\n* License\n\nThis educational material is provided under the MIT License. See the [[file:CLOJURE-GEMINI-REPL.org][CLOJURE-GEMINI-REPL.org]] file for details.\n\n* Support\n\nIf you're stuck:\n1. Re-read the relevant section of the org file\n2. Ask your AI assistant to explain the architecture\n3. Check if your issue is mentioned in the \"Common Issues\" section of the org file\n4. Remember: the goal is to learn AI-assisted development, not just to get the code working\n\nGood luck with your literate programming journey! 🚀\n\n* Appendix: Docker Setup (Optional)\n\nIf you prefer a containerized environment, here's a simple Dockerfile:\n\n#+begin_src dockerfile :tangle Dockerfile\nFROM ubuntu:22.04\n\n# Install basic dependencies\nRUN apt-get update \u0026\u0026 apt-get install -y \\\n    curl \\\n    git \\\n    \u0026\u0026 rm -rf /var/lib/apt/lists/*\n\n# Install mise (formerly rtx)\nRUN curl https://mise.run | sh\nENV PATH=\"/root/.local/share/mise/shims:/root/.local/bin:${PATH}\"\n\n# Install tools via mise\nRUN mise use --global java@temurin-17\nRUN mise use --global babashka@latest\n\n# Verify installations\nRUN java --version \u0026\u0026 bb --version\n\nWORKDIR /workspace\n\nCMD [\"/bin/bash\"]\n#+end_src\n\nTo use this:\n1. Tangle just this block: ~C-c C-v t~ on the code block in Emacs\n2. Or manually save the above to a file named ~Dockerfile~\n3. Build: ~docker build -t gemini-repl .~\n4. Run: ~docker run -it -v $(pwd):/workspace gemini-repl~\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faygp-dr%2Fgemini-repl-006","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faygp-dr%2Fgemini-repl-006","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faygp-dr%2Fgemini-repl-006/lists"}