mechanex 1.0.0

A Python client for the Axionic API.

Mechanex

Mechanex is a runtime control layer for small models.

The core promise is: improve model behavior at inference time through policies, without retraining.

Product Direction

Mechanex is built around a policy-first workflow:

1. Choose a model (local, self-hosted, or hosted).
2. Choose a task profile.
3. Choose an objective.
4. Apply runtime controls (sampling, steering, constraints, verifiers, optimization).
5. Compare and evaluate policies.
6. Deploy and iterate.

Core Concepts

Policy

A policy is the reusable runtime object. It defines:

• Sampling method and search settings.
• Steering settings.
• Output constraints.
• Verifier stack.
• Optimization and fallback behavior.

Execution Modes

Mechanex supports hybrid execution:

• auto: remote when authenticated, local when not authenticated.
• remote: force hosted inference (account + credits required).
• local: force local model execution.

Hosted Remote Model Catalog

When using hosted execution (mx.set_execution_mode("remote")), you can select a model with:

import mechanex as mx
mx.set_model("qwen3-0.6b")

Supported hosted models:

Family	Models
Gemma 2	gemma-2-27b, gemma-2-2b, gemma-2-9b, gemma-2-9b-it, gemma-2b, gemma-2b-it
Gemma 3	gemma-3-12b-it, gemma-3-12b-pt, gemma-3-1b-it, gemma-3-1b-pt, gemma-3-270m, gemma-3-270m-it, gemma-3-27b-it, gemma-3-27b-pt, gemma-3-4b-it, gemma-3-4b-pt
Llama	llama-3.1-8b, llama-3.1-8b-instruct, llama-3.3-70b-instruct, meta-llama-3-8b-instruct
Qwen	qwen2.5-7b-instruct, qwen3-0.6b, qwen3-1.7b, qwen3-14b, qwen3-4b, qwen3-8b
Other	deepseek-r1-distill-llama-8b, gpt-oss-20b, gpt2-small, mistral-7b, pythia-70m-deduped

Installation

pip install mechanex

Quickstart

Remote Runtime Policy

import mechanex as mx

mx.set_key("your-api-key", persist=True)
mx.set_execution_mode("remote")

schema = {
    "type": "object",
    "required": ["answer", "confidence"],
    "properties": {
        "answer": {"type": "string"},
        "confidence": {"type": "number"}
    }
}

out = mx.generation.generate(
    prompt="Return JSON: answer + confidence for 'Paris is in France'.",
    sampling_method="guided-generation",
    json_schema=schema,
    max_tokens=120,
)
print(out)

Local Runtime Policy

import mechanex as mx

mx.load("gpt2-small")
mx.set_execution_mode("local")

policy = mx.policy.strict_json_extraction(
    schema={
        "type": "object",
        "required": ["summary"],
        "properties": {"summary": {"type": "string"}},
    },
    name="strict_json_small_v1",
)

res = mx.policy.run(
    prompt="Summarize speculative decoding in one sentence.",
    policy=policy,
    include_trace=True,
)
print(res["output"])

Runtime Controls

Sampling Methods

Supported methods:

• greedy
• top-k
• top-p
• min-p
• typical
• ads (Adaptive Determinantal Sampling)
• constrained-beam-search
• speculative-decoding
• ssd
• guided-generation
• ensemble-sampling

Steering Modes

Supported vector-generation modes:

• caa
• few-shot

Constraints and Verifiers

Mechanex policies support:

• JSON mode + JSON schema constraints.
• Regex and grammar constraints.
• Required fields and forbidden terms.
• Verifier pipelines including syntax/schema checks.

Local vs Remote Capability Notes

• ADS is remote-only.
• Steering perceptrons are remote-only.
• Other runtime policy methods are available for local usage with capability-aware fallback behavior where needed.

Policy API

Save, Run, Compare, Evaluate

import mechanex as mx

policy = mx.policy.fast_tool_router()
pid = mx.policy.save(policy)

single = mx.policy.run(
    prompt="Route this request to the correct tool and return JSON.",
    policy_id=pid,
    include_trace=True,
)

cmp = mx.policy.compare(
    prompt="Extract order_id and status from text.",
    policies=[mx.policy.fast_tool_router(), mx.policy.strict_json_extraction({
        "type": "object",
        "required": ["order_id", "status"],
        "properties": {"order_id": {"type": "string"}, "status": {"type": "string"}},
    })],
)

ev = mx.policy.evaluate(
    prompts=[
        "Extract {name, role} from: Alice is CTO.",
        "Extract {name, role} from: Bob is PM.",
    ],
    policy_id=pid,
)

OpenAI-Compatible Serving

Mechanex can run a local OpenAI-compatible server:

import mechanex as mx
mx.load("gpt2-small")
mx.set_execution_mode("local")
mx.serve(port=8001)

Then use any OpenAI-compatible client against http://localhost:8001/v1. policy / policy_id, steering fields, and behavior fields can be passed in request bodies.

SDK Configuration

• Default backend URL is hosted Axionic backend.
• Override backend URL with:
  • constructor: Mechanex(base_url="...")
  • env var: MECHANEX_BASE_URL

CLI

Account and key lifecycle:

• mechanex signup
• mechanex login
• mechanex whoami
• mechanex create-api-key
• mechanex list-api-keys
• mechanex balance
• mechanex topup
• mechanex logout

Examples

See examples/README.md for runnable workflows, including:

• local-first runtime control
• remote runtime control
• sampling strategy sweep
• strict JSON policies
• policy compare/evaluate
• local steering vectors
• OpenAI-compatible serving

Engineering Docs

• Contributing
• Engineering Standards
• Testing Guide
• CI/CD
• Operations Runbook
• Release Process