HKPUG Opik Challenge Participant guide

First submission

Turn one plaintext prompt into the single encrypted file accepted by the challenge. The same helper and commands work on macOS, Linux, and Windows.

  1. 1Fork the repository
  2. 2Check your setup
  3. 3Pack and push
  4. 4Open a pull request

Fork the challenge repository

Create your own GitHub copy before working locally. Your encrypted submission is pushed to that fork and proposed back to pythonhk/main as a pull request.

Open the official repository

  1. GitHub repository header with the Fork button at the upper right

    Select Fork

    Open the official pythonhk repository and select Fork near the upper-right corner.

  2. GitHub Create a new fork form with Copy the main branch only selected

    Create your copy

    Choose your GitHub account, keep Copy the main branch only selected, and select Create fork.

  3. GitHub README lines showing the helper pack command and git commands used to push submission.zip

    Push the encrypted ZIP

    Clone your fork, run the helper locally, then commit and push only submission/submission.zip. Never commit your plaintext prompt or private key.

  4. GitHub comparison page showing base main and one changed file

    Create the pull request

    Select Compare & pull request. Confirm the base is pythonhk/main and GitHub reports 1 file changed, then select Create pull request.

    The archived verification shown here says View pull request; a new participant submission says Create pull request.

Clone your fork

git clone https://github.com/YOUR-GITHUB-USER/20260711-opik-14-days-challenge.git
cd 20260711-opik-14-days-challenge

Replace YOUR-GITHUB-USER with the account selected on the fork form.

Install the participant helper

Download the archive for your operating system and processor from the latest release, extract it, and put the executable in a folder on your PATH.

Download the latest helper release

macOS

Choose the darwin_arm64 archive for Apple silicon or darwin_amd64 for an Intel Mac. Extract hkpug-opik-helper.

Linux

Choose linux_amd64 for most PCs or linux_arm64 for an ARM machine. Extract hkpug-opik-helper.

Windows

Choose the matching Windows ZIP, extract hkpug-opik-helper.exe, and add its folder to your user PATH.

Confirm the installation from Terminal or PowerShell with hkpug-opik-helper version.

Check your team setup

Keep your team ID, private key, and certificate outside the repository. Run this check from the challenge repository before packaging a prompt.

Run the readiness check

hkpug-opik-helper doctor --team-id your-team-id --private-key path/to/private-key.pem --team-cert path/to/team-cert.pem

A ready message confirms that the team ID and credential files belong together. Fix any reported path or permission issue before continuing.

Pack one prompt

Write your prompt in submission/prompt.txt. The helper reads that local file and creates the encrypted submission archive.

Use the shared baseline for attempt 1

cp starter/prompt.example.txt submission/prompt.txt

Submit this two-line prompt unchanged for your first scored attempt. Its official real-model smoke score was 60.0/100: the answers were relevant and grounded, while the four deterministic response-contract criteria scored zero. Use the returned Opik traces to plan attempt 2.

Create the archive

hkpug-opik-helper pack --team-id your-team-id --private-key path/to/private-key.pem

The default output is submission/submission.zip. Re-running the command safely replaces your local archive.

Inspect it before upload

hkpug-opik-helper inspect --submission submission/submission.zip --team-cert path/to/team-cert.pem

Check that the displayed team ID and prompt digest are present. Preparing, packing, and inspecting locally does not use an attempt.

Open the pull request

The pull request must contain only the encrypted ZIP. Review the staged path before committing.

Stage and push

git status --short
git add submission/submission.zip
git commit -m "submission: add scored attempt"
git push
  1. Open a pull request into the repository's main branch.
  2. Confirm the changed-files view lists only submission/submission.zip.
  3. Wait for validation and scoring. A successful score counts toward your attempt limit.
  4. Use the pull-request comment to find your score and encrypted submission feedback download.

Submission feedback ready?

Keep the encrypted submission feedback artifact and your team credential files together on your machine for the next step.

Inspect submission feedback in Opik