> ## Documentation Index
> Fetch the complete documentation index at: https://docs.axioniclabs.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Mechanex Python SDK for inference and steering

> Install and configure the Mechanex Python SDK for remote or local inference, steering vector generation, SAE behavior monitoring, and policy management.

## Overview

Python SDK for the Axionic platform. Remote inference via the Axionic API, local model loading via TransformerLens, steering vectors, SAE behavior monitoring, runtime policies, model graph inspection, experimental attribution and RAAG wrappers, and a local OpenAI-compatible server.

Install from PyPI:

```bash theme={null}
pip install mechanex
```

<Warning>
  `transformer_lens` is required for local model loading but is not installed automatically by pip. Install it separately if you plan to run local models:

  ```bash theme={null}
  pip install transformer-lens
  ```
</Warning>

## Two Modes of Operation

<Tabs>
  <Tab title="Remote API">
    Generation, steering, and SAE operations run on Axionic-hosted GPU infrastructure. No local hardware requirements beyond running the SDK.

    * Requires an API key (`ax_` + 48 hex characters)
    * Credits are deducted per inference call
    * Supports all sampling methods including ADS
    * Model does not need to fit in local memory

    ```python theme={null}
    import mechanex as mx

    mx.set_key("ax_your_key_here")
    result = mx.generation.generate("Explain sparse autoencoders in one paragraph.")
    print(result)
    ```
  </Tab>

  <Tab title="Local Model">
    Load a model via TransformerLens and run generation, steering, and SAE operations entirely on local hardware. No per-call credit deduction for inference.

    * Requires `transformer_lens` and a GPU-capable machine for reasonable performance
    * An API key is still required for authentication on account-scoped operations
    * ADS sampling is remote-only and not available in local mode
    * Use `mx.set_execution_mode("local")` when API credentials are also configured

    ```python theme={null}
    import mechanex as mx

    mx.load("gpt2-small")  # loads via TransformerLens
    mx.set_execution_mode("local")
    result = mx.generation.generate("Explain sparse autoencoders in one paragraph.")
    print(result)
    ```
  </Tab>
</Tabs>

## Execution Mode

Control where operations run with `set_execution_mode()`:

| Mode               | Behavior                                                                                                               |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------- |
| `"auto"` (default) | Remote when API or JWT credentials are configured; local only when a model is loaded and no credentials are configured |
| `"remote"`         | Always use the Axionic API. Fails if not authenticated.                                                                |
| `"local"`          | Always use the locally loaded model. Fails if no model loaded.                                                         |

```python theme={null}
mx.set_execution_mode("local")   # force local-only
mx.set_execution_mode("remote")  # force API-only
mx.set_execution_mode("auto")    # default routing behavior
```

<Note>
  ADS and steering perceptrons are remote-only regardless of execution mode. Policy-backed local generation can still run saved policies, constraints, retries, and verifiers when a local model is loaded.
</Note>

<Cards>
  <Card title="Authentication" icon="key" href="/products/mechanex/authentication">
    API keys, JWT login, config file, key management.
  </Card>

  <Card title="Generation" icon="terminal" href="/products/mechanex/generation">
    generate(), sampling methods, steering at inference time.
  </Card>

  <Card title="Model Inspection" icon="network" href="/products/mechanex/model-inspection">
    Computation graph plus experimental attribution and RAAG wrappers.
  </Card>

  <Card title="Steering Vectors" icon="sliders" href="/products/mechanex/steering">
    generate\_vectors(), CAA vs Few-Shot, save/load.
  </Card>

  <Card title="SAE & Behaviors" icon="activity" href="/products/mechanex/sae">
    create\_behavior(), sae.generate(), behavior monitoring.
  </Card>

  <Card title="Policies" icon="settings" href="/products/mechanex/policies">
    Reusable configs combining steering, sampling, and constraints.
  </Card>
</Cards>