foreman-python-example

A minimal Python project that demonstrates running Foreman (LLMKube's agentic-coding harness) on a non-Go codebase.

Foreman's verification gate is language-configurable. Point an AgenticTask at a gateProfile and the same harness that fixes Go issues will format, lint, build, and test a Python project: same coder loop, same clean-room gate Job, same bite check.

What's here

Path	Purpose
src/temperature.py	The production code Foreman edits. Ships with celsius_to_fahrenheit.
tests/test_temperature.py	The test suite the gate runs.
pyproject.toml	ruff (format + lint) and pytest config.
requirements-dev.txt	Dev tool pins (ruff, pytest).
examples/agentictask-python.yaml	The AgenticTask that runs Foreman against this repo, with a Python gateProfile.

The seeded issue

The example task asks Foreman to add a fahrenheit_to_celsius() function with a test. That gives the bite check something real to verify: the new test must fail against the pre-change production code (no fahrenheit_to_celsius yet) and pass after the coder adds it.

How the gate is configured

Foreman defaults to a Go gate. To run on Python, the AgenticTask sets a gateProfile:

spec:
  gateProfile:
    language: python
    image: python:3.13
    sourceExtensions: [".py"]
    commands:
      format: "pip install -q ruff && ruff format --check ."
      lint:   "pip install -q ruff && ruff check ."
      build:  "python -m compileall src tests"
      test:   "pip install -q pytest && pytest -q"

Why pip install inside each command?

The stock python:3.13 image does not ship ruff or pytest. The gate Job runs each command in that image, so the tools have to be present. Two ways to get them:

1. Install-in-command (shown above) - prepend pip install -q <tool> && to each command. Zero infrastructure: works against any vanilla Python image. Costs a few seconds per gate run while pip resolves cached wheels.
2. A pre-baked image - publish an image that already has ruff + pytest (and your project's deps) and set gateProfile.image to it. Faster gate runs, but you own an image. Recommended once the project has real dependencies.

This example uses install-in-command so it runs out of the box with no image to build.

Running it

Prerequisites: an LLMKube cluster with Foreman (operator + a coder Agent), version 0.8.x or newer (the gateProfile field landed in #839).

# 1. Fork or clone this repo so the coder has a push target.
# 2. Edit examples/agentictask-python.yaml: set the repo, branch, and your Agent ref.
# 3. Apply it.
kubectl apply -f examples/agentictask-python.yaml

# 4. Watch the task move through coder -> gate -> review.
kubectl get agentictask foreman-python-example -w

When it finishes, Foreman will have opened a pull request adding fahrenheit_to_celsius() with a passing, biting test.

Learn more

• LLMKube - the Kubernetes operator and the Foreman harness this example runs on.
• Foreman docs - the coder/gate/review pipeline and the language-configurable gate (gateProfile) used here.

Local sanity check

You can run the same checks the gate runs, locally:

python -m venv .venv && source .venv/bin/activate
pip install -r requirements-dev.txt
ruff format --check .
ruff check .
python -m compileall src tests
pytest -q