ai-marketplace-sdk 0.3.0

AI Marketplace Python SDK

AIMP SDK (Python)

This package provides the class-based SDK used by model authors.

Install

python -m pip install ai-marketplace-sdk

Install (local source)

cd sdk/python
uv pip install .

Development (editable)

cd sdk/python
uv pip install -e .

Fine-Tune From Scratch

The fine-tune flow has two sides:

• model authoring: define the schema and training runtime inside the model project
• consumer dataset creation: build one local bundle that matches the published schema

1. Define the training input contract

Model authors declare fine-tune inputs by subclassing FineTuneSchema and adding fields in tuning.py.

Available field types:

• ImageField
• AudioField
• VideoField
• FileField
• TuningTextField
• TuningJsonField

Example:

from aimp_sdk import FineTuneSchema, ImageField


def validate_png(value: object) -> None:
    if not str(value).lower().endswith(".png"):
        raise ValueError("Only PNG files are allowed")


class ModelFineTuneSchema(FineTuneSchema):
    query_image = ImageField(required=True, validators=[validate_png])
    candidate_image = ImageField(required=True, validators=[validate_png])

Use field-level validators=[...] and preprocessors=[...] when one field needs custom cleanup or validation. These hooks run during local bundle build, before upload.

2. Implement the tuning runtime

Model authors implement exactly one method: Component.tune(self, tuning) -> TuneResult.

The platform opens the uploaded bundle, splits train/validation data, injects trial parameters, and passes a single author-facing tuning object into your component.

from aimp_sdk import Component, TuneResult


class CoreModel(Component):
    tuning = ModelFineTuneSchema

    # In the current SDK, build(ctx) is the author hook used to load runtime state once.
    def build(self, ctx):
        self.runtime = load_runtime(ctx.artifacts_dir)
        return self.runtime

    def tune(self, tuning) -> TuneResult:
        learning_rate = tuning.params.learning_rate
        epochs = tuning.params.epochs
        for record in tuning.train_dataset:
            train_step(
                query_image=tuning.resolve_path(record.query_image),
                candidate_image=tuning.resolve_path(record.candidate_image),
                learning_rate=learning_rate,
            )

        _ = epochs
        validation_loss = evaluate(tuning.validation_dataset)
        return TuneResult(metrics={"validation_loss": validation_loss})

tuning exposes only training concerns:

• tuning.train_dataset
• tuning.validation_dataset
• tuning.params
• tuning.resolve_path(...)

In the current SDK, authors implement build(self, ctx) to load runtime state once. The separate load(...) method is framework-internal cache/lifecycle plumbing and is not the author-facing hook.

tuning.params comes from the model's published tuning.parameters contract. Defaults and search space metadata are contract-owned by the platform. Model code must not introduce hidden fallbacks such as getattr(tuning.params, "learning_rate", 1e-5).

Model code does not handle dataset files, S3 uploads, adapter URIs, or trial orchestration.

3. Build the consumer dataset bundle

Consumers do not write model-side tuning code. They use the published schema through the CLI:

1. ai fine-tune schema --model <model-slug>
2. ai fine-tune scaffold --model <model-slug>
3. edit prepare_bundle.py and add any local assets/
4. python prepare_bundle.py
5. ai fine-tune create --model <model-slug> --output-dir .

During bundle build the SDK:

• validates required fields and field types
• runs field preprocessors
• validates the processed values
• copies binary assets into the bundle
• writes data.parquet and manifest.json

That means field preprocessors and validators run before upload, not during remote execution.

4. Use the derived model directly

Successful LoRA fine-tunes produce a derived executable model with its own asset ID and slug. Clients should execute that derived model directly, as if it were a new model:

job = client.fine_tune_job(job_id="ft-123").wait_for_completion()

result = client.models.execute(
    model=job.tuned_model_slug,
    mode="generate",
    input={"prompt": "hello"},
)

Client code should not pass adapter_id to executions. Adapter resolution is platform-internal.