Metadata-Version: 2.4
Name: ai-marketplace-sdk
Version: 0.2.0
Summary: AI Marketplace Python SDK
Project-URL: Homepage, https://github.com/zakariaalmoktar/AI-Marketplace-Platform
Project-URL: Repository, https://github.com/zakariaalmoktar/AI-Marketplace-Platform
Project-URL: Issues, https://github.com/zakariaalmoktar/AI-Marketplace-Platform/issues
Author: AI Marketplace Platform
License: Proprietary
Keywords: agents,ai,marketplace,runtime,sdk
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Requires-Dist: ai-marketplace-framework==0.2.0
Requires-Dist: datasets
Requires-Dist: pandas
Description-Content-Type: text/markdown

# AIMP SDK (Python)

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

## Install

```bash
python -m pip install ai-marketplace-sdk
```

## Install (local source)

```bash
cd sdk/python
uv pip install .
```

## Development (editable)

```bash
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:

```python
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.

```python
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:

```python
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.
