Registry / ai-ml / inference-schema

inference-schema

JSON →
library1.8pypypi✓ verified 84d ago

The `inference-schema` package provides a uniform schema definition for common machine learning applications, specifically designed to aid in web-based ML prediction services. It offers decorators (`@input_schema`, `@output_schema`) that automatically validate and serialize input/output data based on user-defined schemas, integrating well with web frameworks. The current version is 1.8, and it sees periodic updates, often tied to dependency version bumps or feature additions for ML deployments.

pip install inference-schema
INSTALL
IMPORT
SIG · INFERENCE-SCHEMA
I
inference-schema
ai-mlpythonv1.8
Install
2.2s avg
Import
41ms
Disk
20MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v1.8 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.920 runs
installs and imports cleanly · install 0.0s · import 0.044s · 22MB
glibc
py 3.103.920 runs
installs and imports cleanly · install 2.2s · import 0.039s · 23MB
20MB installed
● package 20MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

input_schema
from inference_schema.schema_decorators import input_schema
output_schema
from inference_schema.schema_decorators import output_schema
PandasParameterType
from inference_schema.parameter_types import PandasParameterType
NumpyParameterType
from inference_schema.parameter_types import NumpyParameterType

This quickstart demonstrates how to define input and output schemas for a Python function using `inference-schema` decorators. It uses `PandasParameterType` for structured DataFrame input and a simple dictionary for output. The decorators validate the incoming `input_data` against `sample_input_df` and ensure the function's return value conforms to `sample_output_dict`'s structure.

from inference_schema.schema_decorators import input_schema, output_schema from inference_schema.parameter_types import PandasParameterType import pandas as pd import json # Define sample input and output data structures # These samples are used to infer the schema for validation and serialization sample_input_df = pd.DataFrame({'feature1': [10.0, 20.0], 'feature2': [30.0, 40.0]}) sample_output_dict = {'prediction': [40.0, 60.0]} @input_schema(PandasParameterType(sample_input_df)) @output_schema(sample_output_dict) def predict(input_data: pd.DataFrame) -> dict: """ A dummy prediction function that takes a DataFrame and returns a dictionary. The decorators handle validation of `input_data` and serialization of the return value. """ # Example prediction logic: sum of features predictions = (input_data['feature1'] + input_data['feature2']).tolist() return {'prediction': predictions} # --- Example Usage --- # This is how you'd typically call it, with input that matches the schema input_for_prediction = pd.DataFrame({'feature1': [5.0, 15.0], 'feature2': [25.0, 35.0]}) result = predict(input_for_prediction) print(f"Predicted result: {result}") # If used in a web service, the input might come as JSON and be deserialized # and validated into a DataFrame before reaching `predict` function. # Example: raw_json_input = '{"feature1": [5.0, 15.0], "feature2": [25.0, 35.0]}' # (framework would parse, inference-schema would validate/convert)
Debug
Known issues
gotchaThe `sample_input` and `sample_output` provided to the decorators are critical. They define the *structure and data types* of the expected input and output, not just placeholder values. Mismatches between the actual data at runtime and these samples will cause schema validation errors.
fix
Always ensure your `sample_input` and `sample_output` accurately reflect the exact column names, keys, and data types (e.g., float, int, string) that your function expects and returns.
affects: All versions
breakingInference-schema pins its core dependency, `marshmallow`, to specific version ranges (e.g., `<3.18.0` for v1.8). If your project uses a different `marshmallow` version, it can lead to dependency conflicts or unexpected validation behavior.
fix
Align your project's `marshmallow` version with the range specified by `inference-schema`, or consider using a dedicated virtual environment to isolate dependencies.
affects: All versions
gotchaWhen using `PandasParameterType`, the decorated function is expected to receive a `pandas.DataFrame` object. If you directly call the function with a different type (e.g., a dictionary or list) without it being processed by the schema, it will likely fail.
fix
Ensure that the input to the decorated function is a `pandas.DataFrame` or that the web framework integration correctly deserializes the raw request body into a DataFrame before passing it to your function.
affects: All versions using `PandasParameterType`
Errors
Common errors & fixes
marshmallow.exceptions.ValidationError: {'field_name': ['Invalid type.']}
The input data type for a specific field did not match the type inferred from the `sample_input` schema.
fix
Verify that the data types in your actual input data (e.g., float vs. int, string vs. number) precisely match the types present in your `sample_input` DataFrame/dictionary.
AttributeError: 'dict' object has no attribute 'tolist'
The decorated function returned a dictionary, but the `output_schema` implied that a Pandas DataFrame was expected, or vice-versa, leading to an incompatible method call during serialization.
fix
Ensure the function's return value strictly conforms to the structure implied by the `sample_output` provided to `@output_schema`. If `output_schema` expects a list of numbers, convert your DataFrame column to a list using `.tolist()`.
TypeError: Object of type 'DataFrame' is not JSON serializable
This error typically occurs when a web framework tries to serialize the output of your decorated function (which might be a `pandas.DataFrame`) directly to JSON, but the `output_schema` hasn't fully transformed it into a JSON-compatible type.
fix
Ensure your `output_schema` (the `sample_output` dictionary/list) defines a structure that is inherently JSON-serializable (e.g., nested dictionaries and lists of primitive types). If your function returns a `DataFrame`, make sure the output schema forces its conversion to a list of dicts or similar.
Upgrade
Version history
1.8latest on PyPI · released May 17, 2024
Audit
Dependencies
marshmallowrequiredCore library for schema definition and validation.
numpyrequiredRequired for `NumpyParameterType` and often for internal data handling.
pandasrequiredRequired for `PandasParameterType` and commonly used for structured data input/output.
Agent activity
10 hits · last 30 days
node
10
Resources
inference-schema — pip install inference-schema · libregistry