Ax Signatures For Python

Use when writing Python code with axllm for string signatures, field descriptors, JSON schema output, validation, and typed tool argument shapes.

Install

Install only this skill for Python:

npx skills add https://ax-llm.github.io/ax/python/ --skill 'ax-python-signature'

Published skill file: ax-python-signature/SKILL.md.

Source

• Source: packages/python/skills/ax-python-signature/SKILL.md
• Version: 25.3.2

Skill Instructions

This skill helps an agent write Python code with the generated Ax package axllm. Use the generated package API, examples, and manifests; do not import TypeScript-only APIs unless you are editing the TypeScript package.

When To Use

• Declare input and output contracts with native generated-package APIs.
• Generate JSON-schema-compatible shapes for outputs, tools, prompts, and validation.
• Keep Standard Schema and TypeScript-only helper libraries out of generated-language code.

Package Facts

• Language: Python.
• Package: axllm.
• Package API docs: API.md and axir-api.json.
• Capability manifest: axir-capabilities.json.
• Runnable examples: examples/.
• Real network support: yes.
• Scripted no-key transport support: yes.
• Runtime profiles: javascript-quickjs, python-pyodide.

Core Pattern

from axllm import s

sig = s("question:string -> answer:string")
schema = sig.to_json_schema("outputs")

More Patterns

Simple string contract

Use the string form when field names and types are enough.

from axllm import ax

program = ax("questionText:string -> answerText:string")

Bounded class output

A class field constrains the model to a known label set.

router = ax(
    'messageText:string -> routeClass:class "support, sales, engineering"'
)

Fluent constraints

Python exposes the native fluent builder for validation constraints and objects.

from axllm import f

signature = (
    f()
    .input("contactEmail", f.string("Contact email").email())
    .output("partySize", f.number("Guests").min(1).max(12))
    .output("bookingCode", f.string().regex(r"^[A-Z]{3}-\d{4}$"))
    .build()
)

JSON schema

Render the output contract for tools, validators, or external consumers.

schema = signature.to_json_schema("outputs")

Reuse the signature

Pass one built signature into AxGen and call it like any other program.

program = ax(signature)
output = program.forward(client, inputs)

Start from the complete programs under examples/, then browse the larger gallery at https://axllm.dev/python/subsystems/s/.

Decision evidence

Add (evidence) to boolean/class/score signature outputs to retain probabilities, values, provenance, and native class/score confidence through AxGen. Boolean threshold 0.7 is local to that field; scalar fields still use provider trueThreshold. A plain score returns a continuous zero-based rubric index.

Native selected classes and continuous scores are preserved, even when they differ from argmax or a weighted mean. Generative providers elicit probabilities, derive values locally, omit confidence, and use provenance.source=elicited. Ax attaches actual provider/model provenance. The result shape does not make confidence or calibration comparable across models.

By default a decision refusal raises a terminal AxDecisionRefusalError without correction retries. Use (evidence, refusal return) for an answered/refused union. Generated-language error envelopes retain the decision error type. Arrays, optional fields and nested evidence work with generative models; native providers require flat required scalar fields. Streaming emits only complete evidence. Label-only examples never manufacture distributions.

For reranking, evaluate query/document pairs with the same score rubric, retain candidate IDs outside the model, and sort by relevance.value. Runnable decision-evidence examples are under src/examples/python/generation/.

Typesafe / Jev

The typesafe provider supports required boolean, class, and ordered rubric score outputs. Use score “Low, Medium, High” to declare a rubric. Numeric bounds never define a Score rubric; ordinary numbers, freeform strings, optional outputs, arrays, nesting, media, tools, and sampling controls are rejected before transport.

Set provider trueThreshold (or true_threshold) to a finite value in [0,1], default 0.5. Boolean conversion uses noul >= threshold; this policy is local and never sent. Choice returns the selected label without a confidence cutoff.

Use boolean(true “Core task blocked”, false “Routine request”) and class label descriptions for criteria. Fluent describe_values / describeValues / DescribeValues keeps the same field value type. C++ uses valueDescriptions on its existing field descriptors. Other providers receive readable prompt and schema descriptions.

The separate native client exposes system_one / systemOne / SystemOne and list_models / listModels / ListModels. Native probabilities remain unchanged. Score returns a fractional zero-based rubric position: convert scales explicitly in application code. Entries may be text, structured JSON objects/arrays, or null. Choice allows 1–255 labels; Score requires 2–10 rubric levels. The service context limit covers state, questions, and criteria; Ax never truncates or pretends to count native tokens exactly.

Choice and Score probabilities must be finite values in [0,1], match the criteria keys, and sum to one within an inclusive 0.01 tolerance. Totals of 0.99 and 1.01 are accepted with an allowance for floating-point summation error. Ax preserves the returned probabilities without renormalizing them.

The default model is jev-latest. Use API keys or renewable credential callbacks, the shared HTTP transport, retry settings, timeout, and cancellation. Native model discovery is separate from configured Ax model aliases. Typed native answers retain question names; only TypeScript can infer literal question keys and Choice-label unions at compile time. Other languages use their native typed maps/records/enums.

Typesafe-only balancers propagate the output-schema requirement. Mixed pools retain ordinary prompts and select Typesafe only when the actual request already has a supported schema. Unsupported requests remain excluded during fallback and degradation. Typesafe has no token streaming; the provider returns one completed result through its stream interface.

Runnable signature, native criteria/scoring, and two-program hybrid examples are under src/examples/python/generation/. See https://axllm.dev/python/examples/generation/.

OpenAI Decisions

The openai-decisions provider uses /v1/decisions with gpt-6-luna by default. Required boolean fields become predicates; required class fields become choices; score fields become labelled native rubrics. Use normal AxGen signatures with (evidence) to retain probabilities, provider-selected values, native confidence, and trusted provenance; use (evidence, refusal return) for an answered/refused union. See the Typesafe/Jev skill for decision evidence and reranking across both providers. trueThreshold (or true_threshold) defaults to 0.5, is finite in [0,1], and uses an inclusive comparison. Field value descriptions become criteria instructions or choice descriptions. Raw answers remain in providerMetadata.openaiDecisions.answers; usage uses existing program APIs.

Use openai_decisions for explicit provider request shapes and native JSON input. Its create operation (Go: Create) accepts input and an ordered questions array. Each question has string instructions and an optional unique string name; unnamed answers retain name: null. Predicate returns probability. Choice requires 2-255 string or boolean choices and returns choice, confidence, and probabilities. Score requires 2-10 explicitly labelled levels and returns a fractional zero-based score, confidence, and probabilities. Handle type: refusal before accessing answer values. Preserve full model, answer order, and usage.

Core validates response names, kinds, rubric membership, finite bounds, and distributions summing to one within an inclusive 0.01 tolerance. Probabilities are never normalized. Native input is text or user messages containing input_text and inline input_image data URLs (up to 128 images). Hosted image URLs, audio, non-user roles, and tool items are rejected. Signature prompt/history becomes role-labelled text evidence in one user message. Numeric bounds never define a score rubric; optional, numeric, nested, array, freeform, tool, and sampling requests are rejected before transport.

Use api_key/apiKey or renewable credential providers with shared timeout, retry, and cancellation. Fresh credential headers override static/custom headers case-insensitively on every attempt. Inherited and per-call cancellation both apply. The endpoint returns a completed result without token streaming. Public signature and native examples are under src/examples/python/generation/.

Relevant API Surface

• Signatures: s, f, AxSignature
• Tools: fn, Tool

Guardrails

• Start from package examples for exact native syntax before inventing a new call shape.
• Use provider-api examples only when the user explicitly has provider credentials available.
• Use no-key examples for deterministic local checks and provider request mapping.
• Treat AxIR as the source of generated package truth: if package docs disagree with source code, update the compiler and regenerate packages.
• Do not copy repo-maintainer skills from tools/*/skills/ into user packages.