predikit 0.1.0__tar.gz

predikit-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,27 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build
+        run: |
+          pip install hatchling
+          python -m hatchling build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

predikit-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,27 @@
+name: Test
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Run tests
+        run: pytest --cov=src/predikit --cov-report=term-missing

predikit-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.coverage
+coverage.xml
+htmlcov/
+.pytest_cache/
+.venv/
+venv/
+*.egg

predikit-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tejas Tumakuru Ashok
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

predikit-0.1.0/PKG-INFO

@@ -0,0 +1,233 @@
+Metadata-Version: 2.4
+Name: predikit
+Version: 0.1.0
+Summary: Turn any trained sklearn/XGBoost model into an LLM-callable tool with auto-generated schemas and typed I/O.
+Project-URL: Homepage, https://github.com/Tejas-TA/predikit
+Project-URL: Repository, https://github.com/Tejas-TA/predikit
+Author-email: Tejas Tumakuru Ashok <tejas.tumakuruashok@travelandleisure.com>
+License: MIT
+License-File: LICENSE
+Keywords: agents,function-calling,llm,ml-tools,sklearn,xgboost
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+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: numpy>=1.24
+Requires-Dist: pydantic>=2.0
+Requires-Dist: scikit-learn>=1.2
+Provides-Extra: dev
+Requires-Dist: langchain-core>=0.1; extra == 'dev'
+Requires-Dist: pandas>=1.5; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: xgboost>=1.7; extra == 'dev'
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.1; extra == 'langchain'
+Provides-Extra: xgboost
+Requires-Dist: xgboost>=1.7; extra == 'xgboost'
+Description-Content-Type: text/markdown
+
+# predikit
+
+Turn any trained scikit-learn or XGBoost model into an LLM-callable tool — auto-generated JSON schemas, typed I/O, zero boilerplate.
+
+```python
+tool = ModelTool(model=clf, name="classify_iris", ...)
+tool.to_openai()              # OpenAI function schema, ready to pass to the API
+tool.invoke({"sqft": 2200})   # → {"price_usd": 370730}
+```
+
+## Install
+
+```bash
+pip install predikit
+
+# With XGBoost support
+pip install predikit[xgboost]
+
+# With LangChain support
+pip install predikit[langchain]
+```
+
+## 30-second example
+
+```python
+from pydantic import BaseModel, Field
+from sklearn.datasets import load_iris
+from sklearn.linear_model import LogisticRegression
+from predikit import ModelTool
+
+# Train
+X, y = load_iris(return_X_y=True)
+clf = LogisticRegression(max_iter=200).fit(X, y)
+
+# Define what the LLM will pass in
+class IrisInput(BaseModel):
+    sepal_length: float = Field(description="Sepal length in cm")
+    sepal_width:  float = Field(description="Sepal width in cm")
+    petal_length: float = Field(description="Petal length in cm")
+    petal_width:  float = Field(description="Petal width in cm")
+
+# Wrap the model
+tool = ModelTool(
+    model=clf,
+    name="classify_iris",
+    description="Classify an iris flower: 0=setosa, 1=versicolor, 2=virginica.",
+    input_schema=IrisInput,
+    output_name="species",
+    output_description="Predicted species index",
+)
+
+# Get an OpenAI-ready schema
+import json
+print(json.dumps(tool.to_openai(), indent=2))
+
+# Call it directly
+tool.invoke({
+    "sepal_length": 5.1, "sepal_width": 3.5,
+    "petal_length": 1.4, "petal_width": 0.2,
+})
+# → {"species": 0}
+```
+
+## Core API
+
+### `ModelTool`
+
+```python
+ModelTool(
+    model,               # fitted sklearn-compatible estimator
+    name: str,           # tool name the LLM sees
+    description: str,    # tool description the LLM sees
+    input_schema,        # Pydantic BaseModel describing inputs
+    output_name: str,    # key for the prediction in the returned dict
+    output_description: str,
+)
+```
+
+| Method | Returns | What it does |
+|--------|---------|--------------|
+| `.invoke(input_dict)` | `dict` | Validates → predicts → returns `{output_name: value}` |
+| `.to_openai()` | `dict` | OpenAI function-calling schema |
+| `.to_langchain()` | `StructuredTool` | LangChain tool |
+| `.to_callable()` | `Callable` | Plain Python function |
+
+### `ToolRegistry`
+
+Group multiple tools for bulk export:
+
+```python
+registry = ToolRegistry([price_tool, risk_tool])
+registry.to_openai()     # → list[dict], pass directly to OpenAI
+registry.to_langchain()  # → list[StructuredTool]
+registry.get("name")     # → ModelTool
+```
+
+## Field naming rule
+
+**Your Pydantic schema field names must exactly match the column names the model was trained on.**
+
+predikit maps inputs to features by name, not position. If you trained on a DataFrame with columns `["sqft", "bedrooms"]`, your schema fields must be `sqft` and `bedrooms` — not `sq_ft`, not `Sqft`.
+
+```python
+# ✓ Columns match: sqft, bedrooms, bathrooms
+class GoodInput(BaseModel):
+    sqft:      float
+    bedrooms:  float
+    bathrooms: float
+
+# ✗ Name mismatch — raises ValueError at runtime
+class BadInput(BaseModel):
+    square_footage: float  # model expects "sqft"
+    beds:           float  # model expects "bedrooms"
+    baths:          float  # model expects "bathrooms"
+```
+
+When there's a mismatch, predikit tells you exactly which names are wrong:
+
+```
+ValueError: Input schema is missing model features: ['sqft', 'bedrooms'].
+Schema has: ['square_footage', 'beds', 'bathrooms'], model expects: ['sqft', 'bedrooms', 'bathrooms']
+```
+
+> **Tip:** If you trained with a numpy array (no DataFrame), predikit has no feature names to check — it uses your schema's field definition order instead.
+
+## Cookbook
+
+### XGBoost regression
+
+```python
+from xgboost import XGBRegressor
+from predikit import ModelTool
+
+reg = XGBRegressor().fit(X_train, y_train)
+
+class HouseInput(BaseModel):
+    sqft:       float
+    bedrooms:   float
+    year_built: float
+
+tool = ModelTool(
+    model=reg,
+    name="price_estimate",
+    description="Predict home price in USD.",
+    input_schema=HouseInput,
+    output_name="price_usd",
+    output_description="Predicted sale price in USD",
+)
+```
+
+### Multiple tools in one registry
+
+```python
+registry = ToolRegistry([price_tool, risk_tool, demand_tool])
+
+# OpenAI
+response = client.chat.completions.create(
+    model="gpt-4o",
+    tools=registry.to_openai(),
+    ...
+)
+
+# LangChain
+agent = initialize_agent(tools=registry.to_langchain(), ...)
+```
+
+### Bool inputs from an LLM
+
+LLMs sometimes return `"yes"`, `"true"`, or `"1"` for boolean fields. predikit coerces these automatically before Pydantic validation:
+
+```python
+class Input(BaseModel):
+    has_pool: bool
+
+tool.invoke({"has_pool": "yes"})   # → coerced to True
+tool.invoke({"has_pool": "false"}) # → coerced to False
+tool.invoke({"has_pool": "maybe"}) # → raises ValueError with clear message
+```
+
+Supported strings: `true/false`, `yes/no`, `1/0`, `on/off`.
+
+### Orlando real estate demo
+
+See [`examples/03_orlando_real_estate.py`](examples/03_orlando_real_estate.py) for a full end-to-end walkthrough: synthetic dataset → XGBoost training → `ModelTool` → registry → OpenAI schema → prediction.
+
+## Roadmap
+
+Intentionally out of scope for v0.1 — planned for later releases:
+
+- Confidence-aware routing & fallback
+- Multi-model synthesis (agent calls several, reconciles results)
+- MLflow / Snowflake Model Registry integration
+- HuggingFace / PyTorch / TensorFlow support
+- Async invocation
+
+## License
+
+MIT © Tejas Tumakuru Ashok

predikit-0.1.0/README.md

@@ -0,0 +1,198 @@
+# predikit
+
+Turn any trained scikit-learn or XGBoost model into an LLM-callable tool — auto-generated JSON schemas, typed I/O, zero boilerplate.
+
+```python
+tool = ModelTool(model=clf, name="classify_iris", ...)
+tool.to_openai()              # OpenAI function schema, ready to pass to the API
+tool.invoke({"sqft": 2200})   # → {"price_usd": 370730}
+```
+
+## Install
+
+```bash
+pip install predikit
+
+# With XGBoost support
+pip install predikit[xgboost]
+
+# With LangChain support
+pip install predikit[langchain]
+```
+
+## 30-second example
+
+```python
+from pydantic import BaseModel, Field
+from sklearn.datasets import load_iris
+from sklearn.linear_model import LogisticRegression
+from predikit import ModelTool
+
+# Train
+X, y = load_iris(return_X_y=True)
+clf = LogisticRegression(max_iter=200).fit(X, y)
+
+# Define what the LLM will pass in
+class IrisInput(BaseModel):
+    sepal_length: float = Field(description="Sepal length in cm")
+    sepal_width:  float = Field(description="Sepal width in cm")
+    petal_length: float = Field(description="Petal length in cm")
+    petal_width:  float = Field(description="Petal width in cm")
+
+# Wrap the model
+tool = ModelTool(
+    model=clf,
+    name="classify_iris",
+    description="Classify an iris flower: 0=setosa, 1=versicolor, 2=virginica.",
+    input_schema=IrisInput,
+    output_name="species",
+    output_description="Predicted species index",
+)
+
+# Get an OpenAI-ready schema
+import json
+print(json.dumps(tool.to_openai(), indent=2))
+
+# Call it directly
+tool.invoke({
+    "sepal_length": 5.1, "sepal_width": 3.5,
+    "petal_length": 1.4, "petal_width": 0.2,
+})
+# → {"species": 0}
+```
+
+## Core API
+
+### `ModelTool`
+
+```python
+ModelTool(
+    model,               # fitted sklearn-compatible estimator
+    name: str,           # tool name the LLM sees
+    description: str,    # tool description the LLM sees
+    input_schema,        # Pydantic BaseModel describing inputs
+    output_name: str,    # key for the prediction in the returned dict
+    output_description: str,
+)
+```
+
+| Method | Returns | What it does |
+|--------|---------|--------------|
+| `.invoke(input_dict)` | `dict` | Validates → predicts → returns `{output_name: value}` |
+| `.to_openai()` | `dict` | OpenAI function-calling schema |
+| `.to_langchain()` | `StructuredTool` | LangChain tool |
+| `.to_callable()` | `Callable` | Plain Python function |
+
+### `ToolRegistry`
+
+Group multiple tools for bulk export:
+
+```python
+registry = ToolRegistry([price_tool, risk_tool])
+registry.to_openai()     # → list[dict], pass directly to OpenAI
+registry.to_langchain()  # → list[StructuredTool]
+registry.get("name")     # → ModelTool
+```
+
+## Field naming rule
+
+**Your Pydantic schema field names must exactly match the column names the model was trained on.**
+
+predikit maps inputs to features by name, not position. If you trained on a DataFrame with columns `["sqft", "bedrooms"]`, your schema fields must be `sqft` and `bedrooms` — not `sq_ft`, not `Sqft`.
+
+```python
+# ✓ Columns match: sqft, bedrooms, bathrooms
+class GoodInput(BaseModel):
+    sqft:      float
+    bedrooms:  float
+    bathrooms: float
+
+# ✗ Name mismatch — raises ValueError at runtime
+class BadInput(BaseModel):
+    square_footage: float  # model expects "sqft"
+    beds:           float  # model expects "bedrooms"
+    baths:          float  # model expects "bathrooms"
+```
+
+When there's a mismatch, predikit tells you exactly which names are wrong:
+
+```
+ValueError: Input schema is missing model features: ['sqft', 'bedrooms'].
+Schema has: ['square_footage', 'beds', 'bathrooms'], model expects: ['sqft', 'bedrooms', 'bathrooms']
+```
+
+> **Tip:** If you trained with a numpy array (no DataFrame), predikit has no feature names to check — it uses your schema's field definition order instead.
+
+## Cookbook
+
+### XGBoost regression
+
+```python
+from xgboost import XGBRegressor
+from predikit import ModelTool
+
+reg = XGBRegressor().fit(X_train, y_train)
+
+class HouseInput(BaseModel):
+    sqft:       float
+    bedrooms:   float
+    year_built: float
+
+tool = ModelTool(
+    model=reg,
+    name="price_estimate",
+    description="Predict home price in USD.",
+    input_schema=HouseInput,
+    output_name="price_usd",
+    output_description="Predicted sale price in USD",
+)
+```
+
+### Multiple tools in one registry
+
+```python
+registry = ToolRegistry([price_tool, risk_tool, demand_tool])
+
+# OpenAI
+response = client.chat.completions.create(
+    model="gpt-4o",
+    tools=registry.to_openai(),
+    ...
+)
+
+# LangChain
+agent = initialize_agent(tools=registry.to_langchain(), ...)
+```
+
+### Bool inputs from an LLM
+
+LLMs sometimes return `"yes"`, `"true"`, or `"1"` for boolean fields. predikit coerces these automatically before Pydantic validation:
+
+```python
+class Input(BaseModel):
+    has_pool: bool
+
+tool.invoke({"has_pool": "yes"})   # → coerced to True
+tool.invoke({"has_pool": "false"}) # → coerced to False
+tool.invoke({"has_pool": "maybe"}) # → raises ValueError with clear message
+```
+
+Supported strings: `true/false`, `yes/no`, `1/0`, `on/off`.
+
+### Orlando real estate demo
+
+See [`examples/03_orlando_real_estate.py`](examples/03_orlando_real_estate.py) for a full end-to-end walkthrough: synthetic dataset → XGBoost training → `ModelTool` → registry → OpenAI schema → prediction.
+
+## Roadmap
+
+Intentionally out of scope for v0.1 — planned for later releases:
+
+- Confidence-aware routing & fallback
+- Multi-model synthesis (agent calls several, reconciles results)
+- MLflow / Snowflake Model Registry integration
+- HuggingFace / PyTorch / TensorFlow support
+- Async invocation
+
+## License
+
+MIT © Tejas Tumakuru Ashok

predikit-0.1.0/examples/01_basic_sklearn.py

@@ -0,0 +1,45 @@
+"""Example 01 — Basic sklearn classifier wrapped as an OpenAI tool."""
+import json
+
+from pydantic import BaseModel, Field
+from sklearn.datasets import load_iris
+from sklearn.linear_model import LogisticRegression
+
+from predikit import ModelTool
+
+# 1. Train
+X, y = load_iris(return_X_y=True)
+clf = LogisticRegression(max_iter=200).fit(X, y)
+
+
+# 2. Define input schema
+class IrisInput(BaseModel):
+    sepal_length: float = Field(description="Sepal length in cm")
+    sepal_width: float = Field(description="Sepal width in cm")
+    petal_length: float = Field(description="Petal length in cm")
+    petal_width: float = Field(description="Petal width in cm")
+
+
+# 3. Wrap
+tool = ModelTool(
+    model=clf,
+    name="classify_iris",
+    description="Classify an iris flower as setosa (0), versicolor (1), or virginica (2).",
+    input_schema=IrisInput,
+    output_name="species",
+    output_description="Predicted species index: 0=setosa, 1=versicolor, 2=virginica",
+)
+
+# 4. OpenAI schema
+print("=== OpenAI Tool Schema ===")
+print(json.dumps(tool.to_openai(), indent=2))
+
+# 5. Direct invocation
+print("\n=== Direct Invocation ===")
+result = tool.invoke({"sepal_length": 5.1, "sepal_width": 3.5, "petal_length": 1.4, "petal_width": 0.2})
+print(f"Result: {result}")
+
+# 6. Plain callable
+fn = tool.to_callable()
+result2 = fn(sepal_length=6.3, sepal_width=3.3, petal_length=6.0, petal_width=2.5)
+print(f"Via callable: {result2}")

predikit-0.1.0/examples/02_xgboost_regression.py

@@ -0,0 +1,54 @@
+"""
+Example 02 — XGBoost regression model wrapped as a tool.
+Requires: pip install modelbridge[xgboost]
+"""
+import json
+
+from pydantic import BaseModel, Field
+from sklearn.datasets import make_regression
+from sklearn.model_selection import train_test_split
+
+try:
+    from xgboost import XGBRegressor
+except ImportError:
+    raise SystemExit("XGBoost not installed. Run: pip install modelbridge[xgboost]")
+
+from predikit import ModelTool
+
+# 1. Train
+X, y = make_regression(n_samples=500, n_features=4, noise=10, random_state=42)
+X_train, X_test, y_train, y_test = train_test_split(X, y, random_state=42)
+reg = XGBRegressor(n_estimators=100, random_state=42)
+reg.fit(X_train, y_train)
+
+
+# 2. Define input schema
+class RegressionInput(BaseModel):
+    feature_1: float = Field(description="Input feature 1")
+    feature_2: float = Field(description="Input feature 2")
+    feature_3: float = Field(description="Input feature 3")
+    feature_4: float = Field(description="Input feature 4")
+
+
+# 3. Wrap
+tool = ModelTool(
+    model=reg,
+    name="xgb_regressor",
+    description="Predict a continuous value from 4 numeric features using XGBoost.",
+    input_schema=RegressionInput,
+    output_name="predicted_value",
+    output_description="Predicted numeric output",
+)
+
+print("=== OpenAI Tool Schema ===")
+print(json.dumps(tool.to_openai(), indent=2))
+
+print("\n=== Invoke ===")
+result = tool.invoke({
+    "feature_1": float(X_test[0, 0]),
+    "feature_2": float(X_test[0, 1]),
+    "feature_3": float(X_test[0, 2]),
+    "feature_4": float(X_test[0, 3]),
+})
+print(f"Prediction: {result}")
+print(f"Actual:     {y_test[0]:.2f}")

predikit-0.1.0/examples/03_orlando_real_estate.py

@@ -0,0 +1,122 @@
+"""
+Example 03 — Orlando Real Estate Price Predictor  (portfolio demo)
+
+Trains an XGBoost model on synthetic Orlando-area housing data,
+wraps it as an LLM-callable tool, and shows the full end-to-end flow:
+schema generation → registry export → direct invocation → callable.
+
+Requires: pip install modelbridge[xgboost]
+"""
+import json
+
+import numpy as np
+import pandas as pd
+from pydantic import BaseModel, Field
+from sklearn.model_selection import train_test_split
+
+try:
+    from xgboost import XGBRegressor
+except ImportError:
+    raise SystemExit("XGBoost not installed. Run: pip install modelbridge[xgboost]")
+
+from predikit import ModelTool, ToolRegistry
+
+# ---------------------------------------------------------------------------
+# 1. Synthetic Orlando dataset
+# ---------------------------------------------------------------------------
+rng = np.random.default_rng(42)
+n = 1_000
+
+sqft           = rng.integers(800, 4_000, n).astype(float)
+bedrooms       = rng.integers(1, 6, n).astype(float)
+bathrooms      = rng.choice([1.0, 1.5, 2.0, 2.5, 3.0, 3.5, 4.0], n)
+year_built     = rng.integers(1960, 2024, n).astype(float)
+has_pool       = rng.integers(0, 2, n).astype(float)
+zip_code_group = rng.integers(0, 5, n).astype(float)  # 0=rural … 4=prime
+
+price = (
+    80 * sqft
+    + 15_000 * bedrooms
+    + 10_000 * bathrooms
+    + 500   * (year_built - 1960)
+    + 20_000 * has_pool
+    + 30_000 * zip_code_group
+    + rng.normal(0, 15_000, n)
+).clip(50_000, 1_500_000)
+
+df = pd.DataFrame({
+    "sqft":           sqft,
+    "bedrooms":       bedrooms,
+    "bathrooms":      bathrooms,
+    "year_built":     year_built,
+    "has_pool":       has_pool,
+    "zip_code_group": zip_code_group,
+})
+
+X_train, X_test, y_train, y_test = train_test_split(df, price, test_size=0.2, random_state=42)
+
+# ---------------------------------------------------------------------------
+# 2. Train model
+# ---------------------------------------------------------------------------
+model = XGBRegressor(n_estimators=200, learning_rate=0.05, random_state=42)
+model.fit(X_train, y_train)
+
+# ---------------------------------------------------------------------------
+# 3. Input schema — field names must match DataFrame columns exactly
+# ---------------------------------------------------------------------------
+class OrlandoHouseInput(BaseModel):
+    sqft:           float = Field(description="Total square footage of the home")
+    bedrooms:       float = Field(description="Number of bedrooms")
+    bathrooms:      float = Field(description="Number of bathrooms (0.5 increments)")
+    year_built:     float = Field(description="Year the home was built")
+    has_pool:       float = Field(description="1 if the home has a pool, else 0")
+    zip_code_group: float = Field(description="Area cluster 0–4 (0=rural, 4=prime location)")
+
+# ---------------------------------------------------------------------------
+# 4. Wrap as ModelTool and register
+# ---------------------------------------------------------------------------
+price_tool = ModelTool(
+    model=model,
+    name="orlando_home_price",
+    description=(
+        "Estimate the sale price of a residential property in the Orlando, FL metro area "
+        "based on its characteristics. Returns predicted price in USD."
+    ),
+    input_schema=OrlandoHouseInput,
+    output_name="estimated_price_usd",
+    output_description="Predicted home sale price in US dollars",
+)
+
+registry = ToolRegistry([price_tool])
+
+# ---------------------------------------------------------------------------
+# 5. Show OpenAI function schema
+# ---------------------------------------------------------------------------
+print("=== OpenAI Function Schema ===")
+print(json.dumps(registry.to_openai(), indent=2))
+
+# ---------------------------------------------------------------------------
+# 6. Run a prediction
+# ---------------------------------------------------------------------------
+sample = {
+    "sqft":           2_200.0,
+    "bedrooms":       3.0,
+    "bathrooms":      2.0,
+    "year_built":     2005.0,
+    "has_pool":       1.0,
+    "zip_code_group": 3.0,
+}
+
+print("\n=== Sample Prediction ===")
+print(f"Input:  {sample}")
+result = price_tool.invoke(sample)
+print(f"Output: {result}")
+print(f"\nEstimated price: ${result['estimated_price_usd']:,.0f}")
+
+# ---------------------------------------------------------------------------
+# 7. Same call via plain callable (simulates how an LLM agent would invoke it)
+# ---------------------------------------------------------------------------
+print("\n=== Via Plain Callable (LLM-style) ===")
+fn = price_tool.to_callable()
+result2 = fn(**sample)
+print(f"Result: {result2}")

predikit-0.1.0/pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "predikit"
+version = "0.1.0"
+description = "Turn any trained sklearn/XGBoost model into an LLM-callable tool with auto-generated schemas and typed I/O."
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.10"
+authors = [
+    {name = "Tejas Tumakuru Ashok", email = "tejas.tumakuruashok@travelandleisure.com"},
+]
+keywords = ["llm", "agents", "sklearn", "xgboost", "function-calling", "ml-tools"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+]
+dependencies = [
+    "pydantic>=2.0",
+    "scikit-learn>=1.2",
+    "numpy>=1.24",
+]
+
+[project.optional-dependencies]
+langchain = ["langchain-core>=0.1"]
+xgboost = ["xgboost>=1.7"]
+dev = [
+    "pytest>=7.0",
+    "pytest-cov>=4.0",
+    "xgboost>=1.7",
+    "langchain-core>=0.1",
+    "pandas>=1.5",
+]
+
+[project.urls]
+Homepage = "https://github.com/Tejas-TA/predikit"
+Repository = "https://github.com/Tejas-TA/predikit"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/predikit"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

predikit-0.1.0/src/predikit/__init__.py

@@ -0,0 +1,5 @@
+from .tool import ModelTool
+from .registry import ToolRegistry
+
+__all__ = ["ModelTool", "ToolRegistry"]
+__version__ = "0.1.0"

predikit-0.1.0/src/predikit/coerce.py

@@ -0,0 +1,50 @@
+from typing import Any
+from pydantic import BaseModel
+
+
+_BOOL_TRUE = {"true", "1", "yes", "on"}
+_BOOL_FALSE = {"false", "0", "no", "off"}
+
+
+def coerce_value(value: Any, target_type: type) -> Any:
+    """Coerce a single value to target_type with LLM-friendly string handling."""
+    if isinstance(value, target_type):
+        return value
+
+    if target_type is bool:
+        if isinstance(value, str):
+            low = value.lower()
+            if low in _BOOL_TRUE:
+                return True
+            if low in _BOOL_FALSE:
+                return False
+            raise ValueError(f"Cannot interpret {value!r} as bool. Expected one of: true/false, yes/no, 1/0, on/off")
+        return bool(value)
+
+    if target_type is int:
+        return int(float(value))
+
+    if target_type is float:
+        return float(value)
+
+    if target_type is str:
+        return str(value)
+
+    return value
+
+
+def coerce_inputs(validated: BaseModel, meta: dict) -> list:
+    """Return feature values in the order the model expects them."""
+    data = validated.model_dump()
+    feature_names = meta.get("feature_names")
+    if feature_names:
+        missing = [f for f in feature_names if f not in data]
+        if missing:
+            raise ValueError(
+                f"Input schema is missing model features: {missing}. "
+                f"Field names in your Pydantic schema must exactly match the column names "
+                f"used during model training. "
+                f"Schema has: {list(data.keys())}, model expects: {feature_names}"
+            )
+        return [data[f] for f in feature_names]
+    return list(data.values())

predikit-0.1.0/src/predikit/exporters/langchain.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ..tool import ModelTool
+
+
+def to_langchain_tool(tool: ModelTool):
+    """Convert a ModelTool to a LangChain StructuredTool."""
+    try:
+        from langchain_core.tools import StructuredTool
+    except ImportError:
+        raise ImportError(
+            "langchain-core is required. Install with: pip install predikit[langchain]"
+        )
+
+    def _run(**kwargs) -> dict:
+        return tool.invoke(kwargs)
+
+    return StructuredTool.from_function(
+        func=_run,
+        name=tool.name,
+        description=tool.description,
+        args_schema=tool.input_schema,
+    )

predikit-0.1.0/src/predikit/exporters/openai.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ..tool import ModelTool
+
+
+def to_openai_schema(tool: ModelTool) -> dict:
+    """Convert a ModelTool to an OpenAI function-calling schema dict."""
+    schema = tool.input_schema.model_json_schema()
+    schema.pop("title", None)
+
+    return {
+        "type": "function",
+        "function": {
+            "name": tool.name,
+            "description": tool.description,
+            "parameters": schema,
+        },
+    }

predikit-0.1.0/src/predikit/introspect.py

@@ -0,0 +1,22 @@
+from typing import Any
+
+
+def introspect(model: Any) -> dict:
+    """Extract metadata from a fitted sklearn-compatible estimator."""
+    meta: dict = {}
+
+    meta["feature_names"] = (
+        list(model.feature_names_in_) if hasattr(model, "feature_names_in_") else None
+    )
+    meta["n_features"] = (
+        int(model.n_features_in_) if hasattr(model, "n_features_in_") else None
+    )
+
+    if hasattr(model, "classes_"):
+        meta["task"] = "classification"
+        meta["classes"] = list(model.classes_)
+    else:
+        meta["task"] = "regression"
+        meta["classes"] = None
+
+    return meta

predikit-0.1.0/src/predikit/registry.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+from .tool import ModelTool
+
+
+class ToolRegistry:
+    """Bundles multiple ModelTools and provides bulk export methods."""
+
+    def __init__(self, tools: list[ModelTool]) -> None:
+        self._tools: dict[str, ModelTool] = {t.name: t for t in tools}
+
+    def get(self, name: str) -> ModelTool:
+        if name not in self._tools:
+            raise KeyError(f"No tool named '{name}'. Available: {list(self._tools)}")
+        return self._tools[name]
+
+    def to_openai(self) -> list[dict]:
+        return [t.to_openai() for t in self._tools.values()]
+
+    def to_langchain(self) -> list:
+        return [t.to_langchain() for t in self._tools.values()]

predikit-0.1.0/src/predikit/tool.py

@@ -0,0 +1,93 @@
+from __future__ import annotations
+from typing import Any, Callable
+
+import numpy as np
+from pydantic import BaseModel
+
+from .introspect import introspect
+from .coerce import coerce_inputs, coerce_value
+from .exporters.openai import to_openai_schema
+from .exporters.langchain import to_langchain_tool
+
+# Only apply pre-coercion for these scalar types; everything else goes straight to Pydantic.
+_SCALAR_TYPES = (bool, int, float, str)
+
+
+class ModelTool:
+    """Wraps a fitted sklearn-compatible model as an LLM-callable tool."""
+
+    def __init__(
+        self,
+        model: Any,
+        name: str,
+        description: str,
+        input_schema: type[BaseModel],
+        output_name: str,
+        output_description: str,
+    ) -> None:
+        self.model = model
+        self.name = name
+        self.description = description
+        self.input_schema = input_schema
+        self.output_name = output_name
+        self.output_description = output_description
+        self._meta = introspect(model)
+
+    def invoke(self, input_dict: dict) -> dict:
+        """Validate inputs, run prediction, return {output_name: value}."""
+        pre_coerced = self._pre_coerce(input_dict)
+        try:
+            validated = self.input_schema(**pre_coerced)
+        except Exception as exc:
+            raise ValueError(f"Input validation failed for '{self.name}': {exc}") from exc
+
+        features = coerce_inputs(validated, self._meta)
+        X = self._to_array(features)
+        prediction = self.model.predict(X)[0]
+
+        if hasattr(prediction, "item"):
+            prediction = prediction.item()
+
+        return {self.output_name: prediction}
+
+    def to_openai(self) -> dict:
+        """Return an OpenAI function-calling schema dict."""
+        return to_openai_schema(self)
+
+    def to_langchain(self):
+        """Return a LangChain StructuredTool."""
+        return to_langchain_tool(self)
+
+    def to_callable(self) -> Callable[..., dict]:
+        """Return a plain Python function that calls invoke()."""
+        def _fn(**kwargs) -> dict:
+            return self.invoke(kwargs)
+        _fn.__name__ = self.name
+        _fn.__doc__ = self.description
+        return _fn
+
+    def _pre_coerce(self, input_dict: dict) -> dict:
+        # Runs coerce_value before Pydantic so LLM strings like "yes"/"no" work for bool fields.
+        fields = self.input_schema.model_fields
+        result = {}
+        for k, v in input_dict.items():
+            field = fields.get(k)
+            annotation = getattr(field, "annotation", None) if field else None
+            if annotation in _SCALAR_TYPES:
+                try:
+                    result[k] = coerce_value(v, annotation)
+                except (ValueError, TypeError):
+                    result[k] = v  # let Pydantic surface the error with full context
+            else:
+                result[k] = v
+        return result
+
+    def _to_array(self, features: list) -> Any:
+        feature_names = self._meta.get("feature_names")
+        if feature_names:
+            try:
+                import pandas as pd
+                return pd.DataFrame([dict(zip(feature_names, features))])
+            except ImportError:
+                pass
+        return np.array([features])

predikit-0.1.0/tests/test_coerce.py

@@ -0,0 +1,57 @@
+import pytest
+from pydantic import BaseModel
+
+from predikit.coerce import coerce_inputs, coerce_value
+
+
+def test_coerce_bool_strings():
+    assert coerce_value("true", bool) is True
+    assert coerce_value("yes", bool) is True
+    assert coerce_value("false", bool) is False
+    assert coerce_value("0", bool) is False
+
+
+def test_coerce_bool_invalid():
+    with pytest.raises(ValueError):
+        coerce_value("maybe", bool)
+
+
+def test_coerce_int_from_string():
+    assert coerce_value("42", int) == 42
+    assert coerce_value("3.7", int) == 3
+
+
+def test_coerce_float_from_string():
+    assert coerce_value("3.14", float) == pytest.approx(3.14)
+
+
+def test_coerce_inputs_ordered_by_feature_names():
+    class Schema(BaseModel):
+        b: float
+        a: float
+
+    validated = Schema(b=2.0, a=1.0)
+    meta = {"feature_names": ["a", "b"]}
+    result = coerce_inputs(validated, meta)
+    assert result == [1.0, 2.0]
+
+
+def test_coerce_inputs_no_feature_names():
+    class Schema(BaseModel):
+        x: float
+        y: float
+
+    validated = Schema(x=3.0, y=4.0)
+    meta = {"feature_names": None}
+    result = coerce_inputs(validated, meta)
+    assert result == [3.0, 4.0]
+
+
+def test_coerce_inputs_missing_feature_raises():
+    class Schema(BaseModel):
+        x: float
+
+    validated = Schema(x=1.0)
+    meta = {"feature_names": ["x", "y"]}
+    with pytest.raises(ValueError, match="missing"):
+        coerce_inputs(validated, meta)

predikit-0.1.0/tests/test_exporters_openai.py

@@ -0,0 +1,42 @@
+from pydantic import BaseModel, Field
+from sklearn.datasets import load_iris
+from sklearn.linear_model import LogisticRegression
+
+from predikit import ModelTool
+
+
+class IrisInput(BaseModel):
+    sepal_length: float = Field(description="Sepal length in cm")
+    sepal_width: float = Field(description="Sepal width in cm")
+    petal_length: float = Field(description="Petal length in cm")
+    petal_width: float = Field(description="Petal width in cm")
+
+
+def _make_tool() -> ModelTool:
+    X, y = load_iris(return_X_y=True)
+    clf = LogisticRegression(max_iter=200).fit(X, y)
+    return ModelTool(
+        model=clf,
+        name="iris_classifier",
+        description="Classify iris species from petal/sepal measurements",
+        input_schema=IrisInput,
+        output_name="species",
+        output_description="Predicted species index",
+    )
+
+
+def test_openai_schema_top_level_structure():
+    schema = _make_tool().to_openai()
+    assert schema["type"] == "function"
+    assert schema["function"]["name"] == "iris_classifier"
+    assert "parameters" in schema["function"]
+
+
+def test_openai_schema_has_all_fields():
+    props = _make_tool().to_openai()["function"]["parameters"]["properties"]
+    assert set(props.keys()) == {"sepal_length", "sepal_width", "petal_length", "petal_width"}
+
+
+def test_openai_schema_no_title_at_top():
+    params = _make_tool().to_openai()["function"]["parameters"]
+    assert "title" not in params

predikit-0.1.0/tests/test_introspect.py

@@ -0,0 +1,31 @@
+from sklearn.datasets import load_iris
+from sklearn.linear_model import LinearRegression, LogisticRegression
+
+from predikit.introspect import introspect
+
+
+def test_classifier_metadata():
+    X, y = load_iris(return_X_y=True, as_frame=True)
+    clf = LogisticRegression(max_iter=200).fit(X, y)
+    meta = introspect(clf)
+    assert meta["task"] == "classification"
+    assert meta["classes"] == [0, 1, 2]
+    assert meta["feature_names"] == list(X.columns)
+    assert meta["n_features"] == 4
+
+
+def test_regressor_metadata():
+    X, y = load_iris(return_X_y=True, as_frame=True)
+    reg = LinearRegression().fit(X, y)
+    meta = introspect(reg)
+    assert meta["task"] == "regression"
+    assert meta["classes"] is None
+    assert meta["feature_names"] == list(X.columns)
+
+
+def test_no_feature_names():
+    X, y = load_iris(return_X_y=True)
+    reg = LinearRegression().fit(X, y)
+    meta = introspect(reg)
+    assert meta["feature_names"] is None
+    assert meta["n_features"] == 4

predikit-0.1.0/tests/test_registry.py

@@ -0,0 +1,45 @@
+import pytest
+from pydantic import BaseModel
+from sklearn.datasets import load_iris
+from sklearn.linear_model import LogisticRegression
+
+from predikit import ModelTool, ToolRegistry
+
+
+class IrisInput(BaseModel):
+    sepal_length: float
+    sepal_width: float
+    petal_length: float
+    petal_width: float
+
+
+@pytest.fixture
+def registry():
+    X, y = load_iris(return_X_y=True)
+    clf = LogisticRegression(max_iter=200).fit(X, y)
+    tool = ModelTool(
+        model=clf,
+        name="iris_classifier",
+        description="Classify iris species",
+        input_schema=IrisInput,
+        output_name="species",
+        output_description="Predicted species",
+    )
+    return ToolRegistry([tool])
+
+
+def test_get_tool(registry):
+    tool = registry.get("iris_classifier")
+    assert tool.name == "iris_classifier"
+
+
+def test_get_missing_raises(registry):
+    with pytest.raises(KeyError):
+        registry.get("nonexistent")
+
+
+def test_to_openai_returns_list(registry):
+    schemas = registry.to_openai()
+    assert isinstance(schemas, list)
+    assert len(schemas) == 1
+    assert schemas[0]["type"] == "function"

predikit-0.1.0/tests/test_tool.py

@@ -0,0 +1,84 @@
+import numpy as np
+import pytest
+from pydantic import BaseModel
+from sklearn.datasets import load_iris
+from sklearn.linear_model import LogisticRegression
+
+from predikit import ModelTool
+
+
+class IrisInput(BaseModel):
+    sepal_length: float
+    sepal_width: float
+    petal_length: float
+    petal_width: float
+
+
+@pytest.fixture
+def iris_tool():
+    X, y = load_iris(return_X_y=True)
+    clf = LogisticRegression(max_iter=200).fit(X, y)
+    return ModelTool(
+        model=clf,
+        name="iris_classifier",
+        description="Classify iris species from measurements",
+        input_schema=IrisInput,
+        output_name="species",
+        output_description="Predicted iris species (0=setosa, 1=versicolor, 2=virginica)",
+    )
+
+
+def test_invoke_returns_dict(iris_tool):
+    result = iris_tool.invoke(
+        {"sepal_length": 5.1, "sepal_width": 3.5, "petal_length": 1.4, "petal_width": 0.2}
+    )
+    assert "species" in result
+    assert result["species"] in [0, 1, 2]
+
+
+def test_invoke_string_inputs_coerced(iris_tool):
+    result = iris_tool.invoke(
+        {"sepal_length": "5.1", "sepal_width": "3.5", "petal_length": "1.4", "petal_width": "0.2"}
+    )
+    assert result["species"] in [0, 1, 2]
+
+
+def test_invoke_invalid_input_raises(iris_tool):
+    with pytest.raises(ValueError):
+        iris_tool.invoke({"sepal_length": "not_a_number"})
+
+
+def test_to_callable(iris_tool):
+    fn = iris_tool.to_callable()
+    assert callable(fn)
+    result = fn(sepal_length=5.1, sepal_width=3.5, petal_length=1.4, petal_width=0.2)
+    assert "species" in result
+
+
+def test_output_is_native_python_type(iris_tool):
+    result = iris_tool.invoke(
+        {"sepal_length": 5.1, "sepal_width": 3.5, "petal_length": 1.4, "petal_width": 0.2}
+    )
+    assert isinstance(result["species"], int)
+
+
+def test_invoke_bool_string_coerced_through_invoke():
+    class FlagInput(BaseModel):
+        value: float
+        active: bool
+
+    X = np.array([[1.0, 0], [2.0, 1], [3.0, 0], [4.0, 1]])
+    y = np.array([0, 1, 0, 1])
+    clf = LogisticRegression().fit(X, y)
+
+    tool = ModelTool(
+        model=clf,
+        name="flag_test",
+        description="test bool coercion",
+        input_schema=FlagInput,
+        output_name="result",
+        output_description="predicted class",
+    )
+    assert tool.invoke({"value": 3.0, "active": "yes"})["result"] in [0, 1]
+    assert tool.invoke({"value": 1.0, "active": "false"})["result"] in [0, 1]
+    assert tool.invoke({"value": 3.0, "active": "on"})["result"] in [0, 1]