Onboard a custom client algorithm¶

Adwize algorithms are client-specific implementations with client-specific objectives. They become reusable workflow inputs by publishing a standard semantic contract; agents and use cases must never branch on a model's Python name.

For the complete source-to-action YAML, see Onboard a client workflow.

1. Confirm the objective¶

Record:

• primary business KPI and unit;
• prediction entity (customer, campaign, account, product);
• target definition and horizon;
• decision the output is expected to support;
• required history, scoring cadence and freshness;
• model owner and operational contact.

Do not start implementation until the target can be calculated without future leakage and the connected sources satisfy the required grain and history.

2. Select an execution mode¶

Package mode is not arbitrary runtime code. The package must pass security/reproducibility review and be included in the worker release. External-table mode is preferred for client-owned models that have an independent deployment lifecycle.

3. Register semantic outputs¶

Every model spec declares what its output means:

name: client_purchase_propensity
version: 2.0.0
objective: purchase_within_horizon
entity: customer
execution:
  mode: external_table
semantic_outputs:
  - semantic: likelihood.purchase
    entity: customer
    value_field: score
    horizon_days: 30

All modes publish:

• stable entity ID;
• declared score/value fields;
• model reference and version;
• scoring timestamp and validity;
• data/model quality metadata;
• immutable source and run manifests.

4. Pin it in tenant YAML¶

- id: purchase_propensity
  type: algo
  ref: client_purchase_propensity@2.0.0
  runner: external_table
  depends_on: [graph]
  params:
    external_table_path: client-models/tenant_id={tenant_id}/date={as_of}/scores.parquet

The tenant workflow pins a version. It never contains credentials or unreviewed executable code.

5. Validate before activation¶

Validate offline:

• point-in-time feature/label correctness;
• output schema and entity uniqueness;
• coverage, nulls, bounds and freshness;
• temporal holdout performance and safe baselines;
• threshold or capacity policy;
• stability across important cohorts;
• compatibility with the client's KPI and intended use cases.

The use-case resolver enables a recommendation only when required semantics, quality gates, specialist and action capabilities are all available.

Current account example¶

The current workflow exposes:

propensity@1.1.0:
  semantic: likelihood.purchase
  horizon_days: 30

ltv@2.0.0:
  semantic: value.lifetime
  horizon_days: 30

Together these enable the high_value_high_propensity Media use case. If a governed Google Ads audience action is connected, the Media specialist may recommend delivering that audience. Neither model enables a budget recommendation: that requires a separate pacing or marginal-return signal.

Operating lifecycle¶

1. Publish a new immutable catalog/model version.
2. Validate it against production-shaped fixtures.
3. Update and validate the tenant YAML pin.
4. Run in shadow mode and compare manifests/quality.
5. Activate eligible use cases.
6. Monitor freshness, coverage, drift, failures and recommendation acceptance.
7. Retrain according to declared cadence.
8. Deprecate old versions only after tenant pins migrate.

Responsibility checklist¶

• Client: objective, KPI semantics, legal use, action approval policy.
• Data team: source mapping, identity, point-in-time correctness, freshness.
• Model team: implementation, evaluation, thresholds, version and monitoring.
• Platform team: runner isolation, schema validation, manifests, workflow compatibility and rollout.