Optimization

These Python examples are real runnable files. Edit the source file first; this page is rebuilt from the checked-in example and its metadata header.

Python AxGen Optimization

Runs a baseline OpenAI prediction and applies an optimizer artifact.

Provider: openai
Env: OPENAI_API_KEY, OPENAI_APIKEY
Level: beginner
Run: npm run example -- python src/examples/python/optimization/axgen-optimization.py
Source: src/examples/python/optimization/axgen-optimization.py

Python

import json
import os

from axllm import OpenAICompatibleClient, ax, OptimizerEngine


api_key = os.getenv("OPENAI_API_KEY") or os.getenv("OPENAI_APIKEY")
if not api_key:
    raise SystemExit("Set OPENAI_API_KEY or OPENAI_APIKEY to run this example.")

client = OpenAICompatibleClient(
    api_key=api_key,
    model=os.getenv("AX_OPENAI_MODEL", "gpt-5.4-mini"),
    model_config={"temperature": 0},
)
program = ax('emailText:string -> priority:class "high, normal, low", rationale:string', {"id": "priority", "instruction": "Classify the email priority."})
baseline = program.forward(client, {"emailText": "Production checkout is failing for enterprise customers."})


class ExampleOptimizer(OptimizerEngine):
    name = "example"
    version = "1"

    def optimize(self, request, evaluator=None):
        return {"componentMap": {"priority::instruction": "Classify operational risk. Use high for production-impacting urgency."}, "metadata": {"source": "axgen"}}


artifact = program.optimize_with(ExampleOptimizer(), [{"emailText": "URGENT: checkout is down", "priority": "high"}], {"apply": False})
program.apply_optimization(json.dumps(artifact))
after = program.forward(client, {"emailText": "Production checkout is failing for enterprise customers."})
print(json.dumps({"baseline": baseline, "after": after}, indent=2, sort_keys=True))

Python GEPA Optimization

Pairs a real OpenAI baseline with a local GEPA optimization pass.

Provider: openai
Env: OPENAI_API_KEY, OPENAI_APIKEY
Level: intermediate
Run: npm run example -- python src/examples/python/optimization/gepa-optimization.py
Source: src/examples/python/optimization/gepa-optimization.py

Python

import json
import os

from axllm import OpenAICompatibleClient, ax, AxGEPA, OptimizerEvaluator


api_key = os.getenv("OPENAI_API_KEY") or os.getenv("OPENAI_APIKEY")
if not api_key:
    raise SystemExit("Set OPENAI_API_KEY or OPENAI_APIKEY to run this example.")

client = OpenAICompatibleClient(
    api_key=api_key,
    model=os.getenv("AX_OPENAI_MODEL", "gpt-5.4-mini"),
    model_config={"temperature": 0},
)
program = ax('emailText:string -> priority:class "high, normal, low", rationale:string', {"id": "priority", "instruction": "Classify the email priority."})
baseline = program.forward(client, {"emailText": "Production checkout is failing for enterprise customers."})


class LocalEvaluator(OptimizerEvaluator):
    def evaluate(self, candidate_map, options=None):
        return {"rows": [{"prediction": {"answer": "Ax composes typed LLM programs."}, "scores": {"quality": 0.9}, "scalar": 0.9}], "avg": 0.9, "count": 1}


request = {"programKind": "axgen", "components": [{"id": "priority::instruction", "owner": "priority", "kind": "instruction", "current": "Classify priority clearly."}], "dataset": {"train": [{"emailText": "URGENT: checkout is down"}]}, "options": {"numTrials": 0, "maxMetricCalls": 4, "seed": 7}}
artifact = AxGEPA(seed=7).optimize(request, LocalEvaluator())
print(json.dumps({"baseline": baseline, "artifact": artifact}, indent=2, sort_keys=True))

Python Optimization Artifact Reuse

Saves and reapplies an optimizer artifact after a real OpenAI baseline.

Provider: openai
Env: OPENAI_API_KEY, OPENAI_APIKEY
Level: advanced
Run: npm run example -- python src/examples/python/optimization/artifact-optimization.py
Source: src/examples/python/optimization/artifact-optimization.py

Python

import json
import os

from axllm import OpenAICompatibleClient, ax, OptimizerEngine


api_key = os.getenv("OPENAI_API_KEY") or os.getenv("OPENAI_APIKEY")
if not api_key:
    raise SystemExit("Set OPENAI_API_KEY or OPENAI_APIKEY to run this example.")

client = OpenAICompatibleClient(
    api_key=api_key,
    model=os.getenv("AX_OPENAI_MODEL", "gpt-5.4-mini"),
    model_config={"temperature": 0},
)
program = ax('emailText:string -> priority:class "high, normal, low", rationale:string', {"id": "priority", "instruction": "Classify the email priority."})
baseline = program.forward(client, {"emailText": "Production checkout is failing for enterprise customers."})


class ExampleOptimizer(OptimizerEngine):
    name = "example"
    version = "1"

    def optimize(self, request, evaluator=None):
        return {"componentMap": {"priority::instruction": "Classify operational risk. Use high for production-impacting urgency."}, "metadata": {"source": "artifact"}}


artifact = program.optimize_with(ExampleOptimizer(), [{"emailText": "URGENT: checkout is down", "priority": "high"}], {"apply": False})
program.apply_optimization(json.dumps(artifact))
after = program.forward(client, {"emailText": "Production checkout is failing for enterprise customers."})
print(json.dumps({"baseline": baseline, "after": after}, indent=2, sort_keys=True))