## modelport

Turn any ML model into an MCP tool in 3 lines of code.

`modelport` wraps your trained model behind a standardized, self-describing capability that AI agents can discover, understand, and safely invoke via MCP (Model Context Protocol).

It provides:
- **Model-first API** — `Capability.from_model()` auto-infers schemas from trained models
- **Rich MCP tool descriptions** — LLMs see purpose, when-to-use guidance, input requirements, and limitations
- **Input/output validation** — every invocation is validated against JSON Schema before and after execution
- **Structured error handling** — standardized error codes, recoverable error hints, and retry guidance for MCP workflows
- **Runtime safety** — retry, timeout, and rate-limiting semantics built in
- **MCP server** — serve via stdio or StreamableHTTP for MCP clients

## Install

```bash
# Core only (no ML dependencies)
pip install modelport

# With scikit-learn support
pip install "modelport[sklearn]"

# With XGBoost support
pip install "modelport[xgboost]"

# With LightGBM support
pip install "modelport[lightgbm]"

# With everything
pip install "modelport[all]"
```

For local development:

```bash
uv sync
```

## Supported Backends

| Backend | Extra | Status |
| --- | --- | --- |
| scikit-learn estimators | `sklearn` | Fully supported |
| XGBoost sklearn API (`XGBClassifier`, `XGBRegressor`) | `xgboost` | Fully supported |
| LightGBM sklearn API (`LGBMClassifier`, `LGBMRegressor`) | `lightgbm` | Fully supported |
| Python callable (`dict -> dict`) | core | Fully supported |

## Quick Start

### 1. Describe your model

```python
from sklearn.datasets import load_iris
from sklearn.linear_model import LogisticRegression

from modelport import Capability

model = LogisticRegression(max_iter=200).fit(*load_iris(return_X_y=True))

capability = Capability.from_model(
    model,
    capability_id="iris-classifier",
    purpose="Predict iris species from flower measurements.",
    when_to_use=("You have sepal/petal measurements",),
    when_not_to_use=("You need regression or continuous outputs",),
)

result = capability.invoke({"sepal_length": 5.1, "sepal_width": 3.5, "petal_length": 1.4, "petal_width": 0.2})
print(result)
```

### 2. Serve as MCP

```python
from modelport.server.mcp_server import MCPCapabilityServer

server = MCPCapabilityServer(capability)
mcp = server.as_fastmcp(name="iris-classifier")
mcp.run(transport="stdio")
```

Connect to Claude Desktop, Cursor, or any MCP client — the tool appears with a rich description, correct input schema, and validation.

### 3. Example with VSCode.

Just add the following config to .vscode/mcp.json on the project's root folder: 

```json
{
  "servers": {
    "iris-classifier": {
      "command": "uv",
      "args": [
        "run",
        "python",
        "examples/04_multi_model_mcp/server.py",
        "--transport",
        "stdio"
      ]
    }
  }
}
```

## Error Handling

`modelport` provides structured error handling with:
- **Error codes**: VALIDATION_ERROR, BACKEND_ERROR, RATE_LIMITED, TIMEOUT, INTERNAL_ERROR
- **Recoverability hints**: Tells clients if errors are recoverable (transient) or fatal
- **Retry guidance**: `retry_after_seconds` for rate limits and timeouts
- **Unified format**: Consistent structured errors across modelport MCP flows

```python
from modelport import CapabilityError, ErrorCode

# Errors are automatically structured by modelport
# MCP clients receive:
{
    "error": {
        "code": "VALIDATION_ERROR",
        "message": "Invalid input provided",
        "recoverable": "recoverable",
        "details": {
            "validation_errors": [...]
        }
    }
}
```

## Performance Features

- **Parallel batch predictions**: True async/await parallelism (5-10x faster than sequential)

## Pydantic Model Support

Use Pydantic models to define input/output contracts:

```python
from pydantic import BaseModel

class IrisInput(BaseModel):
    sepal_length: float
    sepal_width: float
    petal_length: float
    petal_width: float

class IrisPrediction(BaseModel):
    species: str
    probability: float

capability = Capability.from_model(
    model,
    capability_id="iris-classifier",
    purpose="Predict iris species",
    input_model=IrisInput,
    output_model=IrisPrediction,
)
```

## Development Commands

```bash
uv run pytest tests/ -v
uv run ruff check src/modelport/ tests/
uv run mypy src/modelport/
```

## Examples

- `examples/01_basic_classifier`: sklearn `Capability.from_model(...)`
- `examples/02_mcp_server`: serving a model as MCP
- `examples/03_gradient_boosting`: XGBoost + LightGBM capabilities
- `examples/04_multi_model_mcp`: expose XGBoost + LightGBM as separate MCP tools in one server

## Documentation

- [API Documentation](docs/top-level.md)
- [Core Concepts](docs/core/README.md)
- [Runtime Backends](docs/runtime/README.md)
- [MCP Server](docs/server/README.md)
- [Validation](docs/validation/README.md)