Metadata-Version: 2.4
Name: predictlm-mcp
Version: 0.1.0
Summary: MCP server exposing PredictLM tabular foundation models as a tool for LLM agents (Claude Desktop, Cursor, Continue, etc.)
Project-URL: Homepage, https://zerooneresearch.ai/predictlm/
Project-URL: Repository, https://github.com/matej-01RAI/predictlm-mcp
Project-URL: Issues, https://github.com/matej-01RAI/predictlm-mcp/issues
Author-email: Matěj Svoboda <matej.svoboda@zerooneresearch.ai>
License: Apache-2.0
Keywords: claude-desktop,foundation-model,llm-tool,machine-learning,mcp,tabular
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Requires-Dist: mcp>=1.0
Requires-Dist: numpy>=1.24
Requires-Dist: pandas>=2.0
Requires-Dist: predictlm>=11.1
Requires-Dist: pydantic>=2.0
Provides-Extra: dev
Requires-Dist: mypy>=1.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.1; extra == 'dev'
Description-Content-Type: text/markdown

# predictlm-mcp

**MCP server exposing the [PredictLM](https://zerooneresearch.ai/predictlm/) tabular foundation model as a tool for LLM agents.**

Give Claude Desktop, Cursor, Continue.dev, Cody — any MCP client — a calibrated tabular-prediction tool. Drop a CSV in chat, ask "predict who'll churn", get answers back with uncertainty bars. No fine-tuning, no per-dataset training, no hallucinated numbers.

Status: alpha (`0.1.0`). API likely to evolve based on early-adopter feedback.

## Install

```bash
pip install predictlm-mcp
```

## Use with Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "predictlm": {
      "command": "predictlm-mcp",
      "args": ["--model", "predictlm-mini-13m", "--device", "cpu"]
    }
  }
}
```

Restart Claude Desktop. The `tabular_predict` and `tabular_describe` tools are now available to Claude.

## Use with Cursor / Continue.dev

Both clients support MCP servers via their MCP config files — point the command at `predictlm-mcp`.

## Tools

### `tabular_predict`
Predict labels for query rows given a context of labeled rows.

**Inputs:**
- `context_table` (CSV string OR array of objects) — labeled rows including the target column
- `target_column` (string) — name of the column to predict
- `query_table` (CSV string OR array of objects) — unlabeled rows to predict
- `task_type` (`auto` | `classification` | `regression`, default `auto`)
- `return_uncertainty` (bool, default `true`)

**Returns:**
```json
{
  "task_type": "classification",
  "predictions": ["churn", "stay", "churn", ...],
  "class_probabilities": [[0.82, 0.18], ...],
  "uncertainty": [0.18, 0.45, 0.12, ...],
  "context_n_rows": 200,
  "query_n_rows": 50,
  "model": {"name": "predictlm-mini-13m", "params": 13500000, "license": "Apache-2.0"}
}
```

### `tabular_describe`
Inspect the loaded model: name, params, license, supported tasks, recommended context size.

## Example agent transcript

```
User: I dropped customers.csv. Predict next-month churn for the 50 rows in
      new_customers.csv. Use the first 200 rows of customers.csv as context.

Claude:  (calls tabular_describe — confirms PredictLM-Mini, 13M params)
         (calls tabular_predict with context_table=customers.csv[:200],
          target_column="churn", query_table=new_customers.csv)

Claude:  Of 50 new customers, PredictLM predicts 12 are likely to churn next
         month with high confidence (≥0.8 probability), 21 are uncertain
         (0.4–0.8), and 17 are likely to stay. The 12 high-confidence churn
         predictions share a tenure < 4 months and >2 support tickets in the
         last 30 days — that's the dominant signal in the context data.
```

This is the difference between an LLM hallucinating predictions and an LLM
*delegating* prediction to a calibrated model and *reasoning about the result.*

## Why PredictLM specifically?

- **Apache-2.0** open weights — commercial-OK, on-device, HIPAA/SOC2 compliant by deployment
- **Calibrated uncertainty** — BarDistribution head returns predictive distributions, not just point predictions
- **13M / 26M parameters** — runs on a laptop (no GPU required)
- **In-context learning** — no per-dataset training; just label some context rows
- **Distilled from a 26M Base** — proven recipe, eval'd on 25 OpenML datasets

## License

Apache-2.0. Free for commercial use, including in agent products.

## Links

- Homepage: <https://zerooneresearch.ai/predictlm/>
- Model card (Mini): <https://huggingface.co/zerooneresearch/predictlm-mini-13m>
- Model card (Base): <https://huggingface.co/zerooneresearch/predictlm-base-26m>
- Issues: <https://github.com/matej-01RAI/predictlm-mcp/issues>
