@jutge.org/toolkit 4.1.0 → 4.2.1

package/docs/getting-started-guide.md

@@ -0,0 +1,526 @@
+# Jutge Toolkit - Getting Started Guide
+
+Welcome to the New Jutge Toolkit! This guide will help you install and start using the toolkit to create, manage, and upload programming problems to Jutge.org. Information about problem formats will be provided in a separate document.
+
+## What is Jutge Toolkit?
+
+Jutge Toolkit is a command-line application that helps you create and manage programming problems for the Jutge.org platform. It provides tools to:
+
+- Create new problems from scratch or using templates
+- Generate problem elements using AI (JutgeAI)
+- Compile and test solutions in multiple programming languages
+- Generate PDF statements and other formats
+- Upload problems to Jutge.org
+
+## Installation
+
+Choose the installation instructions for your operating system:
+
+### Linux Installation
+
+1. **Install Bun (JavaScript runtime)**
+
+    Open a terminal and run:
+
+    ```bash
+    curl -fsSL https://bun.sh/install | bash
+    ```
+
+    After installation, close and reopen your terminal, or run:
+
+    ```bash
+    source ~/.bashrc
+    ```
+
+2. **Install Jutge Toolkit**
+
+    ```bash
+    bun install --global "@jutge.org/toolkit"
+    ```
+
+3. **Verify installation**
+
+    ```bash
+    jtk --version
+    ```
+
+    You should see the version number displayed.
+
+4. **Check dependencies**
+
+    ```bash
+    jtk doctor
+    ```
+
+    This command will show which tools are installed on your system. Don't worry if some are missing - you only need to install the ones for the programming languages and features you plan to use.
+
+5. **Install recommended dependencies (optional)**
+
+    Depending on your needs, you may want to install:
+    - **LaTeX** (for PDF statements):
+
+        ```bash
+        sudo apt-get install texlive-xetex texlive-fonts-recommended texlive-lang-european
+        ```
+
+    - **Pandoc** (for converting statements to different formats):
+
+        ```bash
+        sudo apt-get install pandoc
+        ```
+
+    - **ImageMagick** (for image processing):
+
+        ```bash
+        sudo apt-get install imagemagick
+        ```
+
+    - **Python 3** (if using Python in your problems):
+
+        ```bash
+        sudo apt-get install python3
+        ```
+
+    - **GCC/G++** (if using C/C++ in your problems):
+        ```bash
+        sudo apt-get install build-essential
+        ```
+
+### macOS Installation
+
+1. **Install Bun (JavaScript runtime)**
+
+    Open Terminal and run:
+
+    ```bash
+    curl -fsSL https://bun.sh/install | bash
+    ```
+
+    After installation, close and reopen your terminal.
+
+2. **Install Jutge Toolkit**
+
+    ```bash
+    bun install --global "@jutge.org/toolkit"
+    ```
+
+3. **Verify installation**
+
+    ```bash
+    jtk --version
+    ```
+
+    You should see the version number displayed.
+
+4. **Check dependencies**
+
+    ```bash
+    jtk doctor
+    ```
+
+    This command will show which tools are installed on your system.
+
+5. **Install recommended dependencies (optional)**
+
+    We recommend using Homebrew to install additional tools. If you don't have Homebrew, install it first:
+
+    ```bash
+    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+    ```
+
+    Then install the tools you need:
+    - **LaTeX** (for PDF statements):
+
+        ```bash
+        brew install --cask mactex
+        ```
+
+    - **Pandoc** (for converting statements):
+
+        ```bash
+        brew install pandoc
+        ```
+
+    - **ImageMagick** (for image processing):
+
+        ```bash
+        brew install imagemagick
+        ```
+
+    - **Python 3** (if using Python):
+
+        ```bash
+        brew install python3
+        ```
+
+    - **C/C++ Compiler** (if using C/C++):
+
+        macOS comes with Clang compiler. Install Xcode Command Line Tools:
+
+        ```bash
+        xcode-select --install
+        ```
+
+### Windows Installation
+
+1. **Open PowerShell**
+
+    Press Windows key, type "PowerShell", and open it. Remember to reopen PowerShell after installing each tool.
+
+2. **Install Bun (JavaScript runtime)**
+
+    Visit https://bun.sh/ and follow the installation instructions for Windows. It is easy!
+
+3. **Install Jutge Toolkit**
+
+    ```powershell
+    bun install --global "@jutge.org/toolkit"
+    ```
+
+    The first installation may take a while. If it fails with a `mkdir` error, try again - it's usually a transient error.
+
+4. **Verify installation**
+
+    ```powershell
+    jtk --version
+    ```
+
+    You should see the version number displayed.
+
+5. **Check dependencies**
+
+    ```powershell
+    jtk doctor
+    ```
+
+    This command will show which tools are installed on your system.
+
+6. **Install recommended dependencies (optional)**
+    - **LaTeX** (for PDF statements):
+
+        Install MiKTeX from https://miktex.org/download. During installation, select the option to install missing packages on-the-fly.
+
+    - **Pandoc** (for converting statements):
+
+        ```powershell
+        winget install --id JohnMacFarlane.Pandoc
+        ```
+
+    - **ImageMagick** (for image processing):
+
+        ```powershell
+        winget install --id ImageMagick.ImageMagick
+        ```
+
+    - **Python 3** (if using Python):
+
+        Install from https://www.python.org/downloads/windows/. Make sure to check "Add Python to PATH" during installation.
+
+    - **C/C++ Compiler** (if using C/C++):
+
+        We recommend w64devkit:
+        1. Download from https://github.com/skeeto/w64devkit/releases
+        2. Extract to a folder (e.g., `C:\w64devkit`)
+        3. Run `w64devkit.exe` to open a terminal with GCC available
+
+## Getting Started
+
+### Getting Help
+
+Before we dive into configuration, it's important to know how to get help:
+
+1. **View general help:**
+
+    ```bash
+    jtk --help
+    ```
+
+    This shows all available commands.
+
+2. **Get help for a specific command:**
+
+    ```bash
+    jtk make --help
+    jtk generate --help
+    jtk config --help
+    ```
+
+    Add `--help` to any command to see detailed information about its options and usage.
+
+3. **Get help using JutgeAI:**
+
+    You can ask questions about the toolkit in human language using the `ask` command and get answers generated by JutgeAI and formatted in arkdown:
+
+    ```bash
+    jtk ask "How to create a new problem?"
+    jtk ask "Com puc crear un problema nou?" --model "google/gemini-2.5-flash-lite"
+    ```
+
+    For this to work, you need to have set up an AI API key (see "Setting Up AI Features" below).
+
+4. **View information about the toolkit:**
+
+    ```bash
+    jtk about
+    ```
+
+### Configuration
+
+Before using the toolkit, you should configure it with your preferences:
+
+1. **View current configuration:**
+
+    ```bash
+    jtk config show
+    ```
+
+2. **Set a configuration value:**
+
+    ```bash
+    jtk config set defaultModel "google/gemini-2.5-flash"
+    ```
+
+3. **Edit configuration interactively:**
+
+    ```bash
+    jtk config edit
+    ```
+
+    This opens your default text editor with the configuration file.
+
+### Setting Up AI Features (Optional)
+
+If you want to use JutgeAI features to generate problems and content, you need to set up API keys:
+
+**For Google Gemini (Free for UPC users):**
+
+1. Visit https://aistudio.google.com/ and sign in
+2. Click "Get API key" in the sidebar
+3. Click "Create API key"
+4. Copy the generated key
+5. Set the environment variable:
+    - **Linux/macOS:** Add to `~/.bashrc` or `~/.zshrc`:
+        ```bash
+        export GEMINI_API_KEY="your-key-here"
+        ```
+    - **Windows PowerShell (permanent):**
+        ```powershell
+        [System.Environment]::SetEnvironmentVariable('GEMINI_API_KEY', 'your-key-here', 'User')
+        ```
+
+**For OpenAI (Paid):**
+
+1. Create an account at https://platform.openai.com/
+2. Navigate to API Keys section
+3. Create a new secret key
+4. Set the environment variable:
+    - **Linux/macOS:** Add to `~/.bashrc` or `~/.zshrc`:
+        ```bash
+        export OPENAI_API_KEY="your-key-here"
+        ```
+    - **Windows PowerShell (permanent):**
+        ```powershell
+        [System.Environment]::SetEnvironmentVariable('OPENAI_API_KEY', 'your-key-here', 'User')
+        ```
+
+### Your First Problem
+
+#### Option 1: Create from Template
+
+1. **Clone a template:**
+
+    ```bash
+    jtk clone
+    ```
+
+    This will show you available templates and create a new problem directory.
+
+2. **Or clone a specific template:**
+
+    ```bash
+    jtk clone standard/maximum-of-2-integers.pbm -d my-problem.pbm
+    ```
+
+#### Option 2: Create with AI
+
+1. **Create a problem using JutgeAI:**
+
+    ```bash
+    jtk generate problem -d factorial.pbm
+    ```
+
+    The toolkit will ask you for:
+    - Problem title
+    - Problem description
+    - Original language
+    - Programming language for the solution
+
+2. **Review the generated content** in the `factorial.pbm` directory.
+
+### Building Your Problem
+
+Once you have a problem directory, you can generate all necessary files:
+
+```bash
+cd factorial.pbm
+jtk make
+```
+
+This command will:
+
+- Compile solutions
+- Generate correct outputs for test cases
+- Create PDF statements
+- Generate HTML and text versions
+
+To make only specific elements:
+
+```bash
+jtk make pdf          # Only PDF statements
+jtk make exe          # Only compile executables
+jtk make cor          # Only generate correct outputs
+```
+
+### Testing Solutions
+
+To verify a solution against your golden solution:
+
+```bash
+jtk verify solution.py
+```
+
+This will run the solution against all test cases and compare outputs.
+
+### Generating Additional Content
+
+**Add statement translations:**
+
+```bash
+jtk generate translations en es ca
+```
+
+**Add solutions in other languages:**
+
+```bash
+jtk generate solutions python java cpp
+```
+
+**Generate test case generators:**
+
+```bash
+jtk generate generators --all
+```
+
+**Generate award image:**
+
+```bash
+jtk generate award.png "A golden trophy on a blue background"
+```
+
+**Generate award message:**
+
+```bash
+jtk generate award.html
+```
+
+### Cleaning Up
+
+Remove temporary and generated files:
+
+```bash
+jtk clean              # Dry run (shows what would be deleted)
+jtk clean --force      # Actually delete files
+jtk clean --all        # Also delete generated statements and correct files
+```
+
+### Uploading to Jutge.org
+
+When your problem is ready:
+
+```bash
+jtk upload
+```
+
+If this is a new problem, it will be created on Jutge.org and a `problem.yml` file will be generated with the problem ID. For subsequent uploads, the problem will be updated.
+
+## Common Commands Reference
+
+Here's a quick reference of the most commonly used commands:
+
+```bash
+jtk --help                          # Show help
+jtk --version                       # Show version
+jtk upgrade                         # Upgrade to latest version
+jtk about                           # Show information about the toolkit
+
+jtk config show                     # Show configuration
+jtk config set <key> <value>        # Set configuration value
+jtk config edit                     # Edit configuration interactively
+
+jtk clone [template]                # Clone template
+jtk generate problem                # Create problem with AI
+jtk make                            # Build all problem elements
+jtk verify <program>                # Test a solution
+jtk upload                          # Upload to Jutge.org
+jtk clean                           # Clean temporary files
+
+jtk doctor                          # Check system dependencies
+```
+
+## Getting Help
+
+- Use `--help` flag with any command to get detailed information:
+
+    ```bash
+    jtk make --help
+    jtk generate --help
+    ```
+
+- Check the documentation at https://github.com/jutge-org/jutge-toolkit
+
+- Report issues on GitHub
+
+## Tips for Success
+
+1. **Keep the toolkit updated:** Regularly run `jtk upgrade` to get the latest features and fixes.
+
+2. **Start simple:** Begin with a basic problem and gradually explore more features.
+
+3. **Review AI-generated content:** Always review and validate content generated by JutgeAI before using it in production.
+
+4. **Use version control:** Keep your problem directories in a Git repository to track changes.
+
+5. **Check dependencies:** Run `jtk doctor` periodically to ensure all required tools are installed.
+
+6. **Test thoroughly:** Always use `jtk verify` to test solutions before uploading.
+
+## Troubleshooting
+
+**Command not found after installation:**
+
+- Close and reopen your terminal
+- Check that Bun is properly installed: `bun --version`
+
+**Permission errors on Linux/macOS:**
+
+- You may need to add execution permissions to Bun's installation directory
+
+**AI features not working:**
+
+- Verify your API keys are set correctly
+- Check you have internet connectivity
+- Ensure the model name is correct in your configuration
+
+**LaTeX compilation fails:**
+
+- Make sure you have a complete LaTeX distribution installed
+- On Windows, ensure MiKTeX can install packages automatically
+
+**Problems with specific compilers:**
+
+- Run `jtk doctor` to see which compilers are available
+- Install only the compilers you need for your problems
+
+---
+
+You're now ready to start creating problems with Jutge Toolkit! If you have questions or need help, don't hesitate to consult the documentation or reach out to the community.

package/docs/jutge-ai.md

@@ -0,0 +1,82 @@
+# Jutge<sup>AI</sup> features
+
+The toolkit offers integration with Jutge<sup>AI</sup>, allowing users to leverage advanced AI models to help preparing problems.
+
+In particular, Jutge<sup>AI</sup> features can assist in:
+
+- Creating problems from scratch:
+    - You first need to provide a title and a brief description of the problem you want to create.
+
+        An example description could be: "_A problem where the user has to implement a function that calculates the factorial of a number using recursion and a main program that reads all integers from input and prints their factorial. Add a cute short story around it._"
+
+        Be specific in the description to get better results.
+
+    - Then, you need to choose the original language of the problem (use English for better results) and the programming language of the golden solution.
+
+    - After that, you can ask for more statement languages and more programming languages for the solutions.
+
+    - The AI will generate the problem statement, the golden solution, and a test suite including sample and private test cases.
+
+    - Moreover, you can also ask to generate test case generators, that is, programs that generate test cases for the problem. There are three types of test case generators:
+        - Random test case generators: programs that generate random test cases.
+        - Hard case generators: programs that generate test cases that cover edge cases.
+        - Efficient case generators: programs that generate large test cases to test the efficiency of the solutions.
+
+- Extending existing problems:
+    - You can use Jutge<sup>AI</sup> features to add new statement languages from the original language.
+
+    - You can also generate solutions in other programming languages from the golden solution.
+
+    - You can create new test case generators to extend the existing test suite.
+
+    - You can generate `award.png` and `award.html` files for the problem. (Note: `award.png` requires `dall-e-3` model access.)
+
+As in any other use of AI and LLMs, it is important to review and validate the generated content to ensure its correctness and quality. Treat the generated content as a first draft that needs to be refined and validated.
+
+In order to use the Jutge<sup>AI</sup> features of the toolkit, you need to have API keys for the models you wish to use. You should get the keys from the respective providers and set them as environment variables in your system. Because of the costs associated to the use of these models, the toolkit or Jutge.org cannot provide these keys directly.
+
+UPC users can get free access to Gemini models through their institutional Google accounts. These work well with Jutge<sup>AI</sup> features but have usage limits. If you need more capacity, consider using an OpenAI API key.
+
+## How to get Gemini API key
+
+1. Visit Google AI Studio:
+
+    Go to [aistudio.google.com](https://aistudio.google.com/) and sign in with your Google Account.
+
+2. Access the API Section:
+
+    Click on the **Get API key** button located in the left-hand sidebar menu.
+
+3. Generate the Key:
+    - Click the **Create API key** button.
+    - You will have two options: **Create API key in new project** (recommended for beginners) or **Create API key in existing project.**
+    - Select your preference, and the system will generate a unique key for you.
+
+4. Secure Your Key:
+
+    Copy the generated key immediately.
+
+5. Set `GEMINI_API_KEY` environment variable with the obtained key to use it in the toolkit. This will make models such as `google/gemini-2.5-flash` or `google/gemini-2.5-flash-lite` available for Jutge<sup>AI</sup> features.
+
+## How to get OpenAI API key
+
+1. Create an OpenAI Account:
+
+    Go to the OpenAI website and sign up (or log in if you already have an account).
+
+2. Access the API Dashboard:
+
+    After logging in, open the **API dashboard** from your account menu.
+
+3. Create an API Key:
+    - Navigate to **API Keys**.
+    - Click **Create new secret key**.
+    - Copy the key immediately (it will not be shown again).
+
+4. Secure Your Key: Copy the generated key immediately.
+
+5. Set `OPENAI_API_KEY` environment variable with the obtained key to use it in the toolkit.This will make models such as `openai/gpt-5-mini` or `openai/gpt-5-nano` available for Jutge<sup>AI</sup> features.
+
+## Other models
+
+We use `multi-llm-ts` package to interface with different models. If you have access to other models supported by this package, you can set the corresponding environment variables as described in the [multi-llm-ts documentation](https://github.com/nbonamy/multi-llm-ts) to use them with Jutge<sup>AI</sup> features.