Register a Trained Model for Inference

Turn a model you trained on ColabHive into a production prediction API.

After a training run completes, register it for inference to serve predictions over an endpoint. Choose account visibility for internal use, or public to share it in the catalog.

Two different "register" operations

This page is about trained models (training.register_for_inference), which support real visibility and pricing. Importing a ready-made model from HuggingFace is a separate flow (client.models.hf.register) — those imports are always public, base, and free. If that is what you want, see Import a Model from HuggingFace.

---

Quick Start

1. Train a model

from colabhive import ColabHive

client = ColabHive(api_key="hive_...", account_id="...")

dataset = client.datasets.upload("fraud_data", "./transactions.csv")
job = client.training.create(
    model="xgboost-classification",
    dataset_id=dataset.id,
)
job.wait()  # block until the run finishes

2. Register for inference (account-private)

endpoint = client.training.register_for_inference(
    run_id=job.id,
    name="my-fraud-detector",
    description="Internal fraud detection model",
    visibility="account",   # only your account can call it
)
print(endpoint.endpoint_id)

3. Make predictions

endpoints.infer is synchronous by default — the server waits and returns the result inline.

result = client.endpoints.infer(
    endpoint.endpoint_id,
    {"age": 35, "income": 50000, "transaction_amount": 1500},
)
print(result["result"])   # prediction is right here in sync mode

If the model is still cold and cannot finish within the sync window, the response comes back with status="queued" and a task_id instead — poll GET /api/builder/v1/tasks/{task_id} (or client.endpoints.get_task(task_id)) until it completes. See Inference Lifecycle.

---

Visibility modes

Account (private to your account)

Best for: internal models, proprietary algorithms, team usage.

• Available immediately after registration
• Only your account can call it
• Minimal setup (name + description); input/output schemas optional
• Free for your account

endpoint = client.training.register_for_inference(
    run_id=job.id,
    name="internal-recommender",
    description="Product recommendation model for our platform",
    visibility="account",
)

Public

Best for: sharing in the catalog and letting other accounts build on your work.

• Requires admin review before it goes live
• You can use it privately while it is pending
• Requires a complete specification (below)

Public registration requires:

• name + display_name
• A detailed description
• input_schema / output_schema (JSON Schema)
• example_input / example_output
• tags
• task_type
• price_per_request (in USD — see Pricing)

endpoint = client.training.register_for_inference(
    run_id=job.id,
    name="fraud-detection-xgboost-v1",
    display_name="Fraud Detection Model v1",
    description=(
        "XGBoost model trained on 100K e-commerce transactions. "
        "Best for transactions between $100 and $10,000."
    ),
    visibility="public",

    input_schema={
        "type": "object",
        "description": "Transaction features for fraud prediction",
        "properties": {
            "age": {"type": "number", "minimum": 18, "maximum": 100,
                    "description": "Customer age in years"},
            "income": {"type": "number", "minimum": 0,
                       "description": "Annual income in USD"},
            "transaction_amount": {"type": "number", "minimum": 0,
                                   "description": "Transaction amount in USD"},
        },
        "required": ["age", "income", "transaction_amount"],
    },
    output_schema={
        "type": "object",
        "properties": {
            "is_fraud": {"type": "boolean"},
            "confidence": {"type": "number", "minimum": 0, "maximum": 1},
        },
    },
    example_input={"age": 35, "income": 50000, "transaction_amount": 1500},
    example_output={"is_fraud": False, "confidence": 0.87},
    tags=["fraud", "xgboost", "classification", "fintech"],
    task_type="classification",
    price_per_request=0.001,   # USD per request
)

---

Review process (public models)

1. Submit with visibility="public" and the complete specification.
2. The endpoint goes into review; you can keep calling it privately in the meantime.
3. An admin checks quality, safety, and documentation.
4. Once approved, it appears in the catalog and other accounts can call it.

---

Best practices

Clear descriptions

# Good: specific, includes what it does and where it applies
description = "XGBoost model trained on 100K transactions. Best for e-commerce fraud on $100–$10K orders."

# Weak: vague, no detail
description = "A machine learning model"

Clear schemas

Always include a description per property, min/max ranges for numbers, enums for categorical values, and mark required fields.

input_schema = {
    "type": "object",
    "description": "Clear description of what this input represents",
    "properties": {
        "age": {"type": "number", "minimum": 18, "maximum": 100,
                "description": "Customer age in years"},
        "risk_level": {"type": "string", "enum": ["low", "medium", "high"],
                       "description": "Risk category"},
    },
    "required": ["age", "risk_level"],
}

Realistic examples and specific tags

example_input = {"age": 35, "income": 50000, "credit_score": 720, "transaction_amount": 1500}
tags = ["fraud", "xgboost", "classification", "fintech", "e-commerce"]

---

Pricing (public models)

Pricing is set with price_per_request, expressed in USD. Pick a value based on training cost, inference latency, and model complexity.

Model type	Latency	Suggested USD/request
Simple (XGBoost, LightGBM)	< 100 ms	0.0001 – 0.001
Medium (neural networks)	100–500 ms	0.001 – 0.01
Heavy (LLMs, vision)	> 500 ms	0.01 – 0.1

price_per_request = 0.001   # USD per request

---

Managing endpoints

# List your account's endpoints
for ep in client.endpoints.list(visibility="account"):
    print(ep.name)

# Endpoint detail
endpoint = client.endpoints.get(endpoint_id)
print(endpoint.input_schema, endpoint.output_schema)

# Delete (soft-delete; base models cannot be deleted)
client.endpoints.delete(endpoint_id)

---

Common questions

Can I update a registered model? Register a new version under a different name (e.g. fraud-v2). The original stays available. Trained/merged models also carry lineage — see Merge and Retrain.

Can I use a public model while it's pending review? Yes, privately. Other accounts can only call it after approval.

Can I change visibility later? Account → public requires review. Public → account is immediate.

---

Next steps

• Import a Model from HuggingFace — the other "register".
• Inference API Reference
• Merge and Retrain
• Troubleshooting